@devries-cameron20 / composio Mirror · read-only / commits / 5bdaafd50
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 22:15 UTC

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 );