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
Net −56 lines of comment prose. Earlier commits added multi-paragraph blocks explaining each forward-compat guard, sentinel choice, and schema-bypass cast — most of that is rederivable from the surrounding code. Keep one-line WHY notes where the intent is non-obvious; drop the prose elsewhere.
jkomyno committed
May 7, 2026 at 10:59 UTC
5bdaafd506085487bdfbb30980a99daddb78bb6a
10 files changed
+25
-81
python/composio/core/models/connected_accounts.py
+2
-5
@@ -28,11 +28,8 @@ logger = logging.getLogger(__name__)
28
# 2026-05-08 / 2026-07-03 retirement when the auth config is Composio-managed.
29
_LEGACY_RETIRING_OAUTH_SCHEMES = frozenset({"OAUTH1", "OAUTH2", "DCR_OAUTH"})
30
31
-# Mirrors the TS contract (`ConnectionRequest.ts` `terminalErrorStates`):
32
-# FAILED / EXPIRED / REVOKED are credentials-gone states and should raise
33
-# immediately rather than poll until timeout. INACTIVE is intentionally
34
-# excluded — it means "user disabled, can be reactivated", and a connection
35
-# can briefly transit through it before settling on ACTIVE.
31
+# Mirrors TS `ConnectionRequest.ts:terminalErrorStates`. INACTIVE is excluded
32
+# on purpose — it can recover to ACTIVE.
33
_TERMINAL_CONNECTION_STATES: t.FrozenSet[str] = frozenset(
34
{"FAILED", "EXPIRED", "REVOKED"}
35
)
python/tests/test_connected_accounts.py
+1
-10
@@ -179,9 +179,6 @@ class TestConnectionRequest:
179
def test_wait_for_connection_fails_fast_on_terminal_status(
180
self, monkeypatch, terminal_status
181
):
182
- # Mirrors the TS contract (`ConnectionRequest.ts` `terminalErrorStates`):
183
- # FAILED / EXPIRED / REVOKED are credentials-gone states and should
184
- # raise immediately rather than poll until timeout.
182
mock_client = Mock()
183
terminal = Mock()
184
terminal.status = terminal_status
@@ -194,10 +191,7 @@ class TestConnectionRequest:
191
client=mock_client,
192
)
193
197
- # Defensively patch `time.time` (matches sibling tests at lines 137,
198
- # 170): a stuck CI runner could otherwise reach the deadline before
199
- # the first retrieve call lands, masking the SDKError assertion as a
200
- # ComposioSDKTimeoutError.
194
+ # Patch `time.time` defensively — matches sibling tests.
195
current_time = {"value": 0.0}
196
197
def fake_time():
@@ -217,9 +211,6 @@ class TestConnectionRequest:
211
assert mock_client.connected_accounts.retrieve.call_count == 1
212
213
def test_wait_for_connection_does_not_treat_inactive_as_terminal(self, monkeypatch):
220
- # INACTIVE means "user disabled, can be reactivated" — a connection can
221
- # briefly transit through it before settling on ACTIVE. Failing fast
222
- # there would regress callers that previously recovered.
214
mock_client = Mock()
215
inactive = Mock()
216
inactive.status = "INACTIVE"
ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.list.cmd.ts
+3
-12
@@ -88,13 +88,9 @@ export const connectedAccountsCmd$List = Command.make(
88
})
89
)
90
);
91
- // The Composio server enum for connection statuses evolves on Apollo's
92
- // cadence (REVOKED was added in PR #9550; S2S_OAUTH2 revocation is queued
93
- // next). A closed `Schema.Literal(...)` in `ConnectedAccountItem` would
94
- // reject any future status and brick `composio dev connected-accounts list`
95
- // for every user — even those filtering on `--status ACTIVE`. Catch the
96
- // ParseError, warn, and degrade to the raw response so the table still
97
- // renders.
91
+ // Forward-compat: a future Apollo status would otherwise brick the
92
+ // command via the closed `Schema.Literal(...)`. Degrade to raw on
93
+ // ParseError; formatters only read non-credential-bearing fields.
94
const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult).pipe(
95
Effect.catchTag('ParseError', error =>
96
Effect.gen(function* () {
@@ -104,11 +100,6 @@ export const connectedAccountsCmd$List = Command.make(
100
`the latest schema. Continuing with raw response.\n\n` +
101
`Decode error: ${error.message}`
102
);
107
- // Cast lies about the schema brand, but the downstream formatters
108
- // (`formatConnectedAccountsTable`, `formatConnectedAccountsJson`)
109
- // only read whitelisted fields — credential-bearing `state` /
110
- // `data` are never indexed, so the unvalidated raw payload is
111
- // safe to render as-is.
103
return rawResult as ConnectedAccountListResponse;
104
})
105
)
ts/packages/cli/src/commands/connections/commands/connections.list.cmd.ts
+1
-6
@@ -73,9 +73,7 @@ export const connectionsCmd$List = Command.make('list', { toolkit }, ({ toolkit
73
limit: 1000,
74
})
75
);
76
- // Same forward-compat guard as `connected-accounts.list.cmd.ts`: the
77
- // closed `Schema.Literal(...)` for `status` would brick this command
78
- // for the entire user base when Apollo adds a new enum value.
76
+ // Same forward-compat guard as `connected-accounts.list.cmd.ts`.
77
const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult).pipe(
78
Effect.catchTag('ParseError', error =>
79
Effect.gen(function* () {
@@ -85,9 +83,6 @@ export const connectionsCmd$List = Command.make('list', { toolkit }, ({ toolkit
83
`the latest schema. Continuing with raw response.\n\n` +
84
`Decode error: ${error.message}`
85
);
88
- // Cast lies about the schema brand, but `formatConnectionsJson`
89
- // only reads `status`, `alias`, `word_id`, `toolkit.slug` — the
90
- // unvalidated raw payload is safe to render as-is.
86
return rawResult as ConnectedAccountListResponse;
87
})
88
)
ts/packages/cli/src/commands/connections/commands/connections.remove.cmd.ts
+1
-7
@@ -109,9 +109,7 @@ export const connectionsCmd$Remove = Command.make('remove', { account }, ({ acco
109
})
110
)
111
);
112
- // Same forward-compat guard as `connected-accounts.list.cmd.ts`: the
113
- // closed `Schema.Literal(...)` for `status` would brick this command
114
- // for the entire user base when Apollo adds a new enum value.
112
+ // Same forward-compat guard as `connected-accounts.list.cmd.ts`.
113
const result = yield* Schema.decodeUnknown(ConnectedAccountListResponse)(rawResult).pipe(
114
Effect.catchTag('ParseError', error =>
115
Effect.gen(function* () {
@@ -121,10 +119,6 @@ export const connectionsCmd$Remove = Command.make('remove', { account }, ({ acco
119
`the latest schema. Continuing with raw response.\n\n` +
120
`Decode error: ${error.message}`
121
);
124
- // Cast lies about the schema brand, but `resolveAccount` and
125
- // `formatAccountSummary` only read `id`, `alias`, `word_id`,
126
- // `toolkit.slug`, `status` — credential-bearing `state` / `data`
127
- // are never indexed, so the unvalidated raw payload is safe.
122
return rawResult as ConnectedAccountListResponse;
123
})
124
)
ts/packages/cli/src/services/connected-account-selection.ts
+4
-8
@@ -1,13 +1,9 @@
1
import type { ConnectedAccountItem } from 'src/models/connected-accounts';
2
3
-/**
4
- * `ConnectedAccountItem` widened to allow an `'UNKNOWN'` status sentinel
5
- * used by the CLI when the server returns a status the schema does not
6
- * recognize (e.g. a newly-added Apollo enum value). Selection helpers only
7
- * pick `'ACTIVE'` accounts, so any other label — including `'UNKNOWN'` —
8
- * is filtered out, but storing the honest sentinel avoids falsely tagging
9
- * the row as `'INACTIVE'` (which means "user-disabled" specifically).
10
- */
3
+// `ConnectedAccountItem` widened with an `'UNKNOWN'` sentinel for statuses
4
+// the closed schema doesn't yet know about. Selection only picks `'ACTIVE'`,
5
+// so unknown rows still drop out — but without falsely labeling them
6
+// `'INACTIVE'` (= user-disabled).
7
export type SelectableConnectedAccount = Omit<ConnectedAccountItem, 'status'> & {
8
readonly status: ConnectedAccountItem['status'] | 'UNKNOWN';
9
};
ts/packages/cli/src/services/tool-router-session-connections.ts
+4
-9
@@ -59,9 +59,7 @@ const normalizeConnectedAccountStatus = (
59
case 'REVOKED':
60
return status;
61
default:
62
- // Apollo can introduce new statuses at any time. Use a sentinel
63
- // (`'UNKNOWN'`) instead of coercing to `'INACTIVE'`, which would
64
- // falsely tag the account as user-disabled in selection logic.
62
+ // Sentinel — `'INACTIVE'` would falsely tag the account as user-disabled.
63
return 'UNKNOWN';
64
}
65
};
@@ -128,8 +126,8 @@ export const resolveToolRouterSessionConnections = (
126
const connectedToolkits = new Set<string>();
127
const explicitAccountsByToolkit = new Map<string, RawConnectedAccount>();
128
131
- // Second pass over the raw items — needs untouched `auth_config` and
132
- // `is_disabled` metadata that the normalized projection drops.
129
+ // Second pass over raw items — needs `auth_config` / `is_disabled`
130
+ // dropped by the normalized projection.
131
for (const item of items) {
132
const toolkit = item.toolkit?.slug?.toLowerCase().trim();
133
if (!toolkit || item.is_disabled) continue;
@@ -174,10 +172,7 @@ export const resolveToolRouterSessionConnections = (
172
}),
173
Effect.tap(({ unknownStatuses }) =>
174
unknownStatuses.size > 0
177
- ? // Service-layer code: peers use `Effect.logDebug` for diagnostic
178
- // signal. The user-facing `ui.log.warn` channel runs from command
179
- // layers (e.g. `connected-accounts.list.cmd.ts`).
180
- Effect.logDebug(
175
+ ? Effect.logDebug(
176
`[ToolRouterSession] received unrecognized connected_account.status ` +
177
`value(s): ${[...unknownStatuses].join(', ')}. Treating as 'UNKNOWN' ` +
178
`(not selectable). Run "composio upgrade" to pick up the latest schema.`
ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.list.cmd.test.ts
+2
-8
@@ -232,18 +232,12 @@ describe('CLI: composio dev connected-accounts list', () => {
232
}
233
);
234
235
- // Forward-compat: simulate the server returning a status the CLI does not
236
- // know about (e.g. a freshly-added Apollo enum value). The decode now uses
237
- // `catchTag('ParseError')` to warn and degrade rather than crashing the
238
- // entire command — even users filtering on `--status ACTIVE` would
239
- // otherwise be blocked.
235
+ // Forward-compat: server returns a status the CLI doesn't know about.
236
const unknownStatusAccounts = [
237
{
238
...testConnectedAccounts[0],
239
id: 'con_future_status',
244
- // Cast to bypass the closed `ConnectedAccountItem['status']` literal —
245
- // the whole point of this test is what happens when the server hands
246
- // us a value the schema rejects.
240
+ // Cast bypasses the closed status literal — that's the point.
241
status: 'FUTURE_NOT_YET_KNOWN' as ConnectedAccountItem['status'],
242
},
243
];
ts/packages/core/src/types/connectedAccountAuthStates.types.ts
+6
-9
@@ -145,10 +145,8 @@ export const Oauth2InactiveConnectionDataSchema = Oauth2InitiatingConnectionData
145
.describe('for slack user scopes'),
146
}).catchall(z.unknown());
147
148
-// Mirrors `Oauth2RevokedConnectionDataSchema` on the Apollo side
149
-// (`apps/apollo/src/lib/connected_accounts/schemes/connectionDataScheme.ts`).
150
-// See the invariant comment above `S2SOauth2ConnectionDataSchema` below for
151
-// the OAuth2-only / S2S_OAUTH2-next scope.
148
+// Mirrors Apollo's `Oauth2RevokedConnectionDataSchema`. Scope: see
149
+// `S2SOauth2ConnectionDataSchema` below.
150
export const Oauth2RevokedConnectionDataSchema = Oauth2InitiatingConnectionDataSchema.extend({
151
status: z.literal(ConnectionStatuses.REVOKED),
152
revoked_at: z.string().optional(),
@@ -179,11 +177,10 @@ export type Oauth2ConnectionData = z.infer<typeof Oauth2ConnectionDataSchema>;
177
export type CustomOauth2ConnectionData = z.infer<typeof CustomOauth2ConnectionDataSchema>;
178
179
// S2S_OAUTH2
182
-// Invariant: REVOKED is OAuth2-only as of Apollo PR #9550 (2026-05). S2S_OAUTH2
183
-// revocation is on Apollo's near-term roadmap; the REVOKED arm below is added
184
-// preemptively so that when the server starts emitting it, the per-scheme
185
-// schema accepts it instead of `transformConnectedAccountResponse` silently
186
-// dropping the entire `state` payload (refresh tokens, etc.).
180
+// Invariant (Apollo PR #9550, 2026-05): REVOKED is OAUTH2-only today;
181
+// S2S_OAUTH2 is queued. The REVOKED arm below is preemptive — without it
182
+// `transformConnectedAccountResponse` would silently drop `state` once the
183
+// server starts emitting it.
184
const S2SOauth2BaseSchema = BaseSchemeRaw.extend({
185
status: z.literal(ConnectionStatuses.INITIALIZING),
186
}).catchall(z.unknown());
ts/packages/core/test/connectedAccounts/connectedAccountAuthStates.test.ts
+1
-7
@@ -51,10 +51,6 @@ describe('connectedAccountAuthStates — REVOKED arms', () => {
51
});
52
53
it('accepts REVOKED for S2S_OAUTH2 (preempts the queued Apollo rollout)', () => {
54
- // Today the server only emits REVOKED for OAUTH2, but S2S_OAUTH2 is on
55
- // Apollo's near-term roadmap. Without the matching arm, the entire
56
- // `state` would silently fail discriminated-union parsing in the
57
- // top-level transformer.
54
const parsed = ConnectionDataSchema.parse({
55
authScheme: AuthSchemeTypes.S2S_OAUTH2,
56
val: {
@@ -129,10 +125,8 @@ describe('connectedAccountAuthStates — REVOKED arms', () => {
125
});
126
127
describe('ConnectionStatuses enum closure', () => {
128
+ // Forces deliberate updates when Apollo adds a status.
129
it('enumerates exactly the values this PR contracts for', () => {
133
- // Closure test — if Apollo adds a new status, the SDK should mirror it
134
- // here on purpose, not by accident. Compare the enum object's value set
135
- // to the set this PR ships.
130
expect(new Set(Object.values(ConnectionStatuses))).toEqual(
131
new Set(['INITIALIZING', 'INITIATED', 'ACTIVE', 'FAILED', 'EXPIRED', 'INACTIVE', 'REVOKED'])
132
);