Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: trim verbose comments across the REVOKED-rollout commits

jkomyno5bdaafd50608
diff --git a/python/composio/core/models/connected_accounts.py b/python/composio/core/models/connected_accounts.py
index 4f95b2f87..ad93fc1e3 100644
--- a/python/composio/core/models/connected_accounts.py
+++ b/python/composio/core/models/connected_accounts.py
@@ -28,11 +28,8 @@ logger = logging.getLogger(__name__)
# 2026-05-08 / 2026-07-03 retirement when the auth config is Composio-managed.
_LEGACY_RETIRING_OAUTH_SCHEMES = frozenset({"OAUTH1", "OAUTH2", "DCR_OAUTH"})
-# Mirrors the TS contract (`ConnectionRequest.ts` `terminalErrorStates`):
-# FAILED / EXPIRED / REVOKED are credentials-gone states and should raise
-# immediately rather than poll until timeout. INACTIVE is intentionally
-# excluded — it means "user disabled, can be reactivated", and a connection
-# can briefly transit through it before settling on ACTIVE.
+# Mirrors TS `ConnectionRequest.ts:terminalErrorStates`. INACTIVE is excluded
+# on purpose — it can recover to ACTIVE.
_TERMINAL_CONNECTION_STATES: t.FrozenSet[str] = frozenset(
{"FAILED", "EXPIRED", "REVOKED"}
)
diff --git a/python/tests/test_connected_accounts.py b/python/tests/test_connected_accounts.py
index cbaf62f3a..b18aace21 100644
--- a/python/tests/test_connected_accounts.py
+++ b/python/tests/test_connected_accounts.py
@@ -179,9 +179,6 @@ class TestConnectionRequest:
def test_wait_for_connection_fails_fast_on_terminal_status(
self, monkeypatch, terminal_status
):
- # Mirrors the TS contract (`ConnectionRequest.ts` `terminalErrorStates`):
- # FAILED / EXPIRED / REVOKED are credentials-gone states and should
- # raise immediately rather than poll until timeout.
mock_client = Mock()
terminal = Mock()
terminal.status = terminal_status
@@ -194,10 +191,7 @@ class TestConnectionRequest:
client=mock_client,
)
- # Defensively patch `time.time` (matches sibling tests at lines 137,
- # 170): a stuck CI runner could otherwise reach the deadline before
- # the first retrieve call lands, masking the SDKError assertion as a
- # ComposioSDKTimeoutError.
+ # Patch `time.time` defensively — matches sibling tests.
current_time = {"value": 0.0}
def fake_time():
@@ -217,9 +211,6 @@ class TestConnectionRequest:
assert mock_client.connected_accounts.retrieve.call_count == 1
def test_wait_for_connection_does_not_treat_inactive_as_terminal(self, monkeypatch):
- # INACTIVE means "user disabled, can be reactivated" — a connection can
- # briefly transit through it before settling on ACTIVE. Failing fast
- # there would regress callers that previously recovered.
mock_client = Mock()
inactive = Mock()
inactive.status = "INACTIVE"
diff --git a/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts b/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts
index 8756ca80a..c489918bb 100644
--- a/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts
+++ b/ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts
@@ -88,13 +88,9 @@ export const connectedAccountsCmd$List = Command.make(
})
)
);
- // The Composio server enum for connection statuses evolves on Apollo's
- // cadence (REVOKED was added in PR #9550; S2S_OAUTH2 revocation is queued
- // next). A closed `Schema.Literal(...)` in `ConnectedAccountItem` would
- // reject any future status and brick `composio dev connected-accounts list`
- // for every user — even those filtering on `--status ACTIVE`. Catch the
- // ParseError, warn, and degrade to the raw response so the table still
- // renders.
+ // Forward-compat: a future Apollo status would otherwise brick the
+ // command via the closed `Schema.Literal(...)`. Degrade to raw on
+ // ParseError; formatters only read non-credential-bearing fields.
const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult).pipe(
Effect.catchTag('ParseError', error =>
Effect.gen(function* () {
@@ -104,11 +100,6 @@ export const connectedAccountsCmd$List = Command.make(
`the latest schema. Continuing with raw response.\n\n` +
`Decode error: ${error.message}`
);
- // Cast lies about the schema brand, but the downstream formatters
- // (`formatConnectedAccountsTable`, `formatConnectedAccountsJson`)
- // only read whitelisted fields — credential-bearing `state` /
- // `data` are never indexed, so the unvalidated raw payload is
- // safe to render as-is.
return rawResult as ConnectedAccountListResponse;
})
)
diff --git a/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts b/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts
index 09e1e7fcc..112a1da23 100644
--- a/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts
+++ b/ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts
@@ -73,9 +73,7 @@ export const connectionsCmd$List = Command.make('list', { toolkit }, ({ toolkit
limit: 1000,
})
);
- // Same forward-compat guard as `connected-accounts.list.cmd.ts`: the
- // closed `Schema.Literal(...)` for `status` would brick this command
- // for the entire user base when Apollo adds a new enum value.
+ // Same forward-compat guard as `connected-accounts.list.cmd.ts`.
const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult).pipe(
Effect.catchTag('ParseError', error =>
Effect.gen(function* () {
@@ -85,9 +83,6 @@ export const connectionsCmd$List = Command.make('list', { toolkit }, ({ toolkit
`the latest schema. Continuing with raw response.\n\n` +
`Decode error: ${error.message}`
);
- // Cast lies about the schema brand, but `formatConnectionsJson`
- // only reads `status`, `alias`, `word_id`, `toolkit.slug` — the
- // unvalidated raw payload is safe to render as-is.
return rawResult as ConnectedAccountListResponse;
})
)
diff --git a/ts/packages/cli/src/commands/connections/commands/connections.remove.cmd.ts b/ts/packages/cli/src/commands/connections/commands/connections.remove.cmd.ts
index e86d4d842..e5683667d 100644
--- a/ts/packages/cli/src/commands/connections/commands/connections.remove.cmd.ts
+++ b/ts/packages/cli/src/commands/connections/commands/connections.remove.cmd.ts
@@ -109,9 +109,7 @@ export const connectionsCmd$Remove = Command.make('remove', { account }, ({ acco
})
)
);
- // Same forward-compat guard as `connected-accounts.list.cmd.ts`: the
- // closed `Schema.Literal(...)` for `status` would brick this command
- // for the entire user base when Apollo adds a new enum value.
+ // Same forward-compat guard as `connected-accounts.list.cmd.ts`.
const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult).pipe(
Effect.catchTag('ParseError', error =>
Effect.gen(function* () {
@@ -121,10 +119,6 @@ export const connectionsCmd$Remove = Command.make('remove', { account }, ({ acco
`the latest schema. Continuing with raw response.\n\n` +
`Decode error: ${error.message}`
);
- // Cast lies about the schema brand, but `resolveAccount` and
- // `formatAccountSummary` only read `id`, `alias`, `word_id`,
- // `toolkit.slug`, `status` — credential-bearing `state` / `data`
- // are never indexed, so the unvalidated raw payload is safe.
return rawResult as ConnectedAccountListResponse;
})
)
diff --git a/ts/packages/cli/src/services/connected-account-selection.ts b/ts/packages/cli/src/services/connected-account-selection.ts
index 824d8f004..38d0dd12a 100644
--- a/ts/packages/cli/src/services/connected-account-selection.ts
+++ b/ts/packages/cli/src/services/connected-account-selection.ts
@@ -1,13 +1,9 @@
import type { ConnectedAccountItem } from 'src/models/connected-accounts';
-/**
- * `ConnectedAccountItem` widened to allow an `'UNKNOWN'` status sentinel
- * used by the CLI when the server returns a status the schema does not
- * recognize (e.g. a newly-added Apollo enum value). Selection helpers only
- * pick `'ACTIVE'` accounts, so any other label — including `'UNKNOWN'` —
- * is filtered out, but storing the honest sentinel avoids falsely tagging
- * the row as `'INACTIVE'` (which means "user-disabled" specifically).
- */
+// `ConnectedAccountItem` widened with an `'UNKNOWN'` sentinel for statuses
+// the closed schema doesn't yet know about. Selection only picks `'ACTIVE'`,
+// so unknown rows still drop out — but without falsely labeling them
+// `'INACTIVE'` (= user-disabled).
export type SelectableConnectedAccount = Omit<ConnectedAccountItem, 'status'> & {
readonly status: ConnectedAccountItem['status'] | 'UNKNOWN';
};
diff --git a/ts/packages/cli/src/services/tool-router-session-connections.ts b/ts/packages/cli/src/services/tool-router-session-connections.ts
index 691d9f853..15768ec49 100644
--- a/ts/packages/cli/src/services/tool-router-session-connections.ts
+++ b/ts/packages/cli/src/services/tool-router-session-connections.ts
@@ -59,9 +59,7 @@ const normalizeConnectedAccountStatus = (
case 'REVOKED':
return status;
default:
- // Apollo can introduce new statuses at any time. Use a sentinel
- // (`'UNKNOWN'`) instead of coercing to `'INACTIVE'`, which would
- // falsely tag the account as user-disabled in selection logic.
+ // Sentinel — `'INACTIVE'` would falsely tag the account as user-disabled.
return 'UNKNOWN';
}
};
@@ -128,8 +126,8 @@ export const resolveToolRouterSessionConnections = (
const connectedToolkits = new Set<string>();
const explicitAccountsByToolkit = new Map<string, RawConnectedAccount>();
- // Second pass over the raw items — needs untouched `auth_config` and
- // `is_disabled` metadata that the normalized projection drops.
+ // Second pass over raw items — needs `auth_config` / `is_disabled`
+ // dropped by the normalized projection.
for (const item of items) {
const toolkit = item.toolkit?.slug?.toLowerCase().trim();
if (!toolkit || item.is_disabled) continue;
@@ -174,10 +172,7 @@ export const resolveToolRouterSessionConnections = (
}),
Effect.tap(({ unknownStatuses }) =>
unknownStatuses.size > 0
- ? // Service-layer code: peers use `Effect.logDebug` for diagnostic
- // signal. The user-facing `ui.log.warn` channel runs from command
- // layers (e.g. `connected-accounts.list.cmd.ts`).
- Effect.logDebug(
+ ? Effect.logDebug(
`[ToolRouterSession] received unrecognized connected_account.status ` +
`value(s): ${[...unknownStatuses].join(', ')}. Treating as 'UNKNOWN' ` +
`(not selectable). Run "composio upgrade" to pick up the latest schema.`
diff --git a/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts b/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts
index d69e5e063..cd82c60b7 100644
--- a/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts
@@ -232,18 +232,12 @@ describe('CLI: composio dev connected-accounts list', () => {
}
);
- // Forward-compat: simulate the server returning a status the CLI does not
- // know about (e.g. a freshly-added Apollo enum value). The decode now uses
- // `catchTag('ParseError')` to warn and degrade rather than crashing the
- // entire command — even users filtering on `--status ACTIVE` would
- // otherwise be blocked.
+ // Forward-compat: server returns a status the CLI doesn't know about.
const unknownStatusAccounts = [
{
...testConnectedAccounts[0],
id: 'con_future_status',
- // Cast to bypass the closed `ConnectedAccountItem['status']` literal —
- // the whole point of this test is what happens when the server hands
- // us a value the schema rejects.
+ // Cast bypasses the closed status literal — that's the point.
status: 'FUTURE_NOT_YET_KNOWN' as ConnectedAccountItem['status'],
},
];
diff --git a/ts/packages/core/src/types/connectedAccountAuthStates.types.ts b/ts/packages/core/src/types/connectedAccountAuthStates.types.ts
index e3ffc01d6..32131b1cb 100644
--- a/ts/packages/core/src/types/connectedAccountAuthStates.types.ts
+++ b/ts/packages/core/src/types/connectedAccountAuthStates.types.ts
@@ -145,10 +145,8 @@ export const Oauth2InactiveConnectionDataSchema = Oauth2InitiatingConnectionData
.describe('for slack user scopes'),
}).catchall(z.unknown());
-// Mirrors `Oauth2RevokedConnectionDataSchema` on the Apollo side
-// (`apps/apollo/src/lib/connected_accounts/schemes/connectionDataScheme.ts`).
-// See the invariant comment above `S2SOauth2ConnectionDataSchema` below for
-// the OAuth2-only / S2S_OAUTH2-next scope.
+// Mirrors Apollo's `Oauth2RevokedConnectionDataSchema`. Scope: see
+// `S2SOauth2ConnectionDataSchema` below.
export const Oauth2RevokedConnectionDataSchema = Oauth2InitiatingConnectionDataSchema.extend({
status: z.literal(ConnectionStatuses.REVOKED),
revoked_at: z.string().optional(),
@@ -179,11 +177,10 @@ export type Oauth2ConnectionData = z.infer<typeof Oauth2ConnectionDataSchema>;
export type CustomOauth2ConnectionData = z.infer<typeof CustomOauth2ConnectionDataSchema>;
// S2S_OAUTH2
-// Invariant: REVOKED is OAuth2-only as of Apollo PR #9550 (2026-05). S2S_OAUTH2
-// revocation is on Apollo's near-term roadmap; the REVOKED arm below is added
-// preemptively so that when the server starts emitting it, the per-scheme
-// schema accepts it instead of `transformConnectedAccountResponse` silently
-// dropping the entire `state` payload (refresh tokens, etc.).
+// Invariant (Apollo PR #9550, 2026-05): REVOKED is OAUTH2-only today;
+// S2S_OAUTH2 is queued. The REVOKED arm below is preemptive — without it
+// `transformConnectedAccountResponse` would silently drop `state` once the
+// server starts emitting it.
const S2SOauth2BaseSchema = BaseSchemeRaw.extend({
status: z.literal(ConnectionStatuses.INITIALIZING),
}).catchall(z.unknown());
diff --git a/ts/packages/core/test/connectedAccounts/connectedAccountAuthStates.test.ts b/ts/packages/core/test/connectedAccounts/connectedAccountAuthStates.test.ts
index 2ae7575cd..4b1e43632 100644
--- a/ts/packages/core/test/connectedAccounts/connectedAccountAuthStates.test.ts
+++ b/ts/packages/core/test/connectedAccounts/connectedAccountAuthStates.test.ts
@@ -51,10 +51,6 @@ describe('connectedAccountAuthStates — REVOKED arms', () => {
});
it('accepts REVOKED for S2S_OAUTH2 (preempts the queued Apollo rollout)', () => {
- // Today the server only emits REVOKED for OAUTH2, but S2S_OAUTH2 is on
- // Apollo's near-term roadmap. Without the matching arm, the entire
- // `state` would silently fail discriminated-union parsing in the
- // top-level transformer.
const parsed = ConnectionDataSchema.parse({
authScheme: AuthSchemeTypes.S2S_OAUTH2,
val: {
@@ -129,10 +125,8 @@ describe('connectedAccountAuthStates — REVOKED arms', () => {
});
describe('ConnectionStatuses enum closure', () => {
+ // Forces deliberate updates when Apollo adds a status.
it('enumerates exactly the values this PR contracts for', () => {
- // Closure test — if Apollo adds a new status, the SDK should mirror it
- // here on purpose, not by accident. Compare the enum object's value set
- // to the set this PR ships.
expect(new Set(Object.values(ConnectionStatuses))).toEqual(
new Set(['INITIALIZING', 'INITIATED', 'ACTIVE', 'FAILED', 'EXPIRED', 'INACTIVE', 'REVOKED'])
);