@devries-cameron20 / composio Mirror · read-only / commits / 935383a2e
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, 04:45 UTC

fix(cli): validate the search response (#5360)

This PR: - part of [PRDE-2212](https://linear.app/composio/issue/PRDE-2212/cli-e2e-tests-fake-backend-operation-suites-and-agent-journeys-with) - builds on top of https://github.com/ComposioHQ/composio/pull/5359; split from https://github.com/ComposioHQ/composio/pull/5333 - checks the fields search consumes while preserving result fields and the backend’s key order on stdout - reports malformed successful responses by operation with an upgrade hint, keeping schema issues that might quote response data off stderr - replaces the two raw-TypeError pins and expected failures with two passing unexpected-response operation cases - passes the full CLI suite, CLI and workspace typechecks, Effect diagnostics, Oxlint, Prettier, and keyless Docker operations, whoami, and agent-signin suites The CLI test workflow runs for PRs targeting `next`, not this stack base; full CI completes after retargeting. The existing Docker scenarios cover these corrections; no recording changes are needed.

Alberto Schiabel committed Nov 16, 2026 at 13:11 UTC 935383a2e41aab15c5cf04b160b7e15657d1d3ae
14 files changed +248 -69
ts/e2e-tests/cli/operations/README.md
+10 -10
@@ -61,16 +61,16 @@ The catalogue starts from one question: what can go wrong for a CLI that an agen
61
62 ### Network (`network-faults.test.ts`)
63
64 -| Fault | Injected at | Must hold | Status |
65 -| ------------------------------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
66 -| Connection refused | `COMPOSIO_BASE_URL` to a closed port | exit 1; stdout empty; `ECONNREFUSED` on stderr | ok |
67 -| HTTP 500, 429, HTML 502 page, reset before response, on every attempt | `search` | exit 1; stdout empty; cause on stderr; three attempts | ok |
68 -| Reset in the middle of the body | `search` | exit 1; stdout empty; one attempt | ok |
69 -| Body that is not JSON | `search` | exit 1; stdout empty; says the response shape is unexpected and names `composio upgrade` | ok |
70 -| One 500, one 429 with Retry-After, one reset, then healthy | `search` | exit 0; stderr empty; normal result; two attempts | ok |
71 -| Slow response (4 s) | `search` | exit 0; one attempt | ok |
72 -| Valid JSON of another shape; empty 200 body | `search` | exit 1 with an unexpected-response message | expected failure: crashes with a `TypeError` naming a minified variable |
73 -| HTTP 500, 429, HTML page, non-JSON body, reset before response, reset mid-body | tool execution, Dashboard transport and backend transport | exit 1; **exactly one execution request**; stdout is JSON with `successful: false` and an error; no `data` | ok |
64 +| Fault | Injected at | Must hold | Status |
65 +| ------------------------------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------ |
66 +| Connection refused | `COMPOSIO_BASE_URL` to a closed port | exit 1; stdout empty; `ECONNREFUSED` on stderr | ok |
67 +| HTTP 500, 429, HTML 502 page, reset before response, on every attempt | `search` | exit 1; stdout empty; cause on stderr; three attempts | ok |
68 +| Reset in the middle of the body | `search` | exit 1; stdout empty; one attempt | ok |
69 +| Body that is not JSON | `search` | exit 1; stdout empty; says the response shape is unexpected and names `composio upgrade` | ok |
70 +| One 500, one 429 with Retry-After, one reset, then healthy | `search` | exit 0; stderr empty; normal result; two attempts | ok |
71 +| Slow response (4 s) | `search` | exit 0; one attempt | ok |
72 +| Valid JSON of another shape; empty 200 body | `search` | exit 1 with an unexpected-response message | ok |
73 +| HTTP 500, 429, HTML page, non-JSON body, reset before response, reset mid-body | tool execution, Dashboard transport and backend transport | exit 1; **exactly one execution request**; stdout is JSON with `successful: false` and an error; no `data` | ok |
74
75 Observed and left as is: on the backend transport an HTML error page is copied whole into the `error` field of the result.
76
ts/e2e-tests/cli/operations/network-faults.test.ts
+3 -12
@@ -167,23 +167,14 @@ describe('network faults on a read (`search`)', () => {
167 { name: 'an empty 200 body', fault: { kind: 'empty-body' } },
168 ] satisfies ReadonlyArray<{ name: string; fault: Fault }>) {
169 it(
170 - `today: ${name}: exit 1 with a raw TypeError`,
170 + `${name}: reported as an unexpected response`,
171 async () => {
172 rig.fake.faults.inject({ route: SEARCH, fault });
173 const result = await rig.run(SEARCH_SLACK);
174 expect(result.exitCode).toBe(1);
175 expect(result.stdout).toBe('');
176 - expect(clean(result.stderr)).toContain('TypeError');
177 - },
178 - TEST_TIMEOUT_MS
179 - );
180 -
181 - // CLI defect: a 200 whose JSON lacks the fields `search` reads crashes with a raw TypeError naming a minified variable.
182 - it.failing(
183 - `${name}: reported as an unexpected response`,
184 - async () => {
185 - rig.fake.faults.inject({ route: SEARCH, fault });
186 - const result = await rig.run(SEARCH_SLACK);
176 + expect(clean(result.stderr)).not.toContain('TypeError');
177 + expect(clean(result.stderr)).toContain('composio upgrade');
178 expect(clean(result.stderr)).toContain(
179 'is not in the shape this version of the CLI expects'
180 );
ts/packages/cli/AGENTS.md
+1 -1
@@ -208,7 +208,7 @@ Each nested `Arr.flatMap` adds one independent axis; the innermost `Arr.map` bui
208
209 - Never branch on an Effect value's internal tag field directly. Use the owning module's public refinement or matcher (`Option`, `Result`, `Exit`, `Cause`, `CliError`), `Match.valueTags` for exhaustive unions, or `Predicate.isTagged` for a single narrowing guard.
210 - Do not wrap a plain `Error` in `Effect.fail` for expected failures. Give the failure a meaningful `Data.TaggedError` type with structured fields and a preserved cause, then recover with `catchTag` / `catchTags`. Reserve `Effect.die` and `Effect.dieMessage` for impossible invariants.
211 -- Treat `unknown`, JSON, and persisted state as trust boundaries. Decode them with `effect/Schema` or narrow them with `Predicate`; an `as` assertion is not validation, and hand-rolled structural guards (`'x' in obj` / `typeof` chains) are not a substitute for a schema. Each typed API response is validated at most once. The CLI's own schema validates a response the CLI transforms, filters for stdout, or writes to a cache file: the catalog models (`src/models/toolkits.ts`, `tools.ts`, `trigger-types.ts`), the auth-config and connected-account allowlists that keep credential-bearing fields off stdout (including the list responses and the `auth-configs create` response in `src/models/auth-configs.ts` and `connected-accounts.ts`), the `ToolkitSlug` path-safety check, the `Session` `DateTime` transform, and `TriggerInstanceItems`. Those calls decode with the CLI schema, failing with `services/HttpDecodingError`. The client validates a response against its own generated schema only when the call passes the `validated` request option (`src/services/composio-request.ts`); a mismatch fails with the client's `DecodeError`, which the CLI reports with the operation, the request id, and an upgrade hint. Pass `validated` only on a read the CLI consumes whole through the client's types, where no field may drift: `cli.realtime.credentials` (every field feeds the realtime connection), `org.list` (organization ids and names for login), and `org.consumer.listConnectedToolkits` (a list of slugs). Every other typed call leaves it off: calls that are not reads, because failing after the server acted would invite a retry that repeats the side effect; reads the CLI validates with its own schema; and reads that must tolerate drift because the CLI consumes a few fields of a response whose client schema fixes enums or requires fields the CLI never reads (`logs.createToolExecution`, `logs.retrieveToolExecution`, `logs.triggers.*`, `tools.list`, `tools.retrieve`, `org.project.list`, `toolRouter.session.search`, `toolRouter.session.toolkits`, `connectedAccounts.list`, which tolerates unknown statuses, and `triggerInstances.listActive`, whose page counts the CLI defaults). Adding a validated read means saying in its doc comment why the CLI cannot tolerate drift there. Responses fetched with the raw `client.get`/`client.post` are untyped and always need a CLI schema (`LatestToolVersionResponse` in `src/models/tools.ts`, and the consumer config and permission payloads in `tool-permissions.ts`). `effect/Schema` is the CLI's schema tool — do not introduce zod here (zod is the convention in the SDK packages and docs).
211 +- Treat `unknown`, JSON, and persisted state as trust boundaries. Decode them with `effect/Schema` or narrow them with `Predicate`; an `as` assertion is not validation, and hand-rolled structural guards (`'x' in obj` / `typeof` chains) are not a substitute for a schema. Each typed API response is validated at most once. The CLI's own schema validates a response the CLI transforms, filters for stdout, or writes to a cache file: the catalog models (`src/models/toolkits.ts`, `tools.ts`, `trigger-types.ts`), the auth-config and connected-account allowlists that keep credential-bearing fields off stdout (including the list responses and the `auth-configs create` response in `src/models/auth-configs.ts` and `connected-accounts.ts`), the `ToolkitSlug` path-safety check, the `Session` `DateTime` transform, `TriggerInstanceItems`, and the tool search response (`ToolSearchResponse` in `src/models/tool-search.ts`, the fields `composio search` reads, keeping each result's other fields for stdout). Those calls decode with the CLI schema, failing with `services/HttpDecodingError`; `decode(schema, { operation })` names the client operation, and such a failure is then reported like the client's `DecodeError` below, never with the schema issues, which may quote the response. The client validates a response against its own generated schema only when the call passes the `validated` request option (`src/services/composio-request.ts`); a mismatch fails with the client's `DecodeError`, which the CLI reports with the operation, the request id, and an upgrade hint. Pass `validated` only on a read the CLI consumes whole through the client's types, where no field may drift: `cli.realtime.credentials` (every field feeds the realtime connection), `org.list` (organization ids and names for login), and `org.consumer.listConnectedToolkits` (a list of slugs). Every other typed call leaves it off: calls that are not reads, because failing after the server acted would invite a retry that repeats the side effect; reads the CLI validates with its own schema; and reads that must tolerate drift because the CLI consumes a few fields of a response whose client schema fixes enums or requires fields the CLI never reads (`logs.createToolExecution`, `logs.retrieveToolExecution`, `logs.triggers.*`, `tools.list`, `tools.retrieve`, `org.project.list`, `toolRouter.session.toolkits`, `connectedAccounts.list`, which tolerates unknown statuses, and `triggerInstances.listActive`, whose page counts the CLI defaults). Adding a validated read means saying in its doc comment why the CLI cannot tolerate drift there. Responses fetched with the raw `client.get`/`client.post` are untyped and always need a CLI schema (`LatestToolVersionResponse` in `src/models/tools.ts`, and the consumer config and permission payloads in `tool-permissions.ts`). `effect/Schema` is the CLI's schema tool — do not introduce zod here (zod is the convention in the SDK packages and docs).
212 - Do not inspect private `effect/cli` internals (parser state, `HelpDoc` string shapes, `CliError` suggestion machinery). `Command.runWith` renders help and parse/validation errors itself — see the entry-point section above — so command-tree introspection must stay on the public `Command.Any` surface (`name`, `alias`, `subcommands`). `CliError.InvalidValue` takes structured `{ option, value, expected, kind }` fields, not a free-form message — handler-level validation raises `CommandInputError` from `src/commands/errors.ts` (built with `commandInputError('<command>')`, carrying `command`, `message`, and the `option` at fault), not a hand-built `CliError`. It, `NotLoggedInError`, `ProjectResolutionError`, `ConnectedAccountResolutionError` (an `--account` selector that matches no connected account, or the account lookup behind it failing), and the other expected failures (a missing user id, login, or SDK install; an unknown org, toolkit, or version) declare `get [ExpectedFailure]() { return true; }` from `src/effects/expected-failure.ts` where the class is defined; `isUsageFailure` in `errors.ts` checks that marker, and the invocation prints the message and exits 1, with no defect banner. A new expected error opts in the same way, with no central list to update; a defect stays unmarked. A failure the command prints itself fails already reported: `reportFailure` (`src/effects/report-failure.ts`) prints a message and hint, then fails with `ReportedFailure`; a command that prints more after the message calls `printFailure`, prints the rest, then fails with `ReportedFailure`. A command-specific error the command already printed (`ReportedToolExecutionError` and `ReportedProxyCommandError`, whose result is on stdout as `{ "successful": false }`, `ShellSetupAbortError`, `SetupCommandError`) declares `get [Runtime.errorReported]() { return false; }` and `get [Runtime.errorExitCode]() { return 1; }` where the class is defined. Either way the runtime prints nothing more and exits 1, and telemetry records the command as failed.
213 - Prefer `Effect.mapError`, `Effect.matchEffect`, and typed recovery over `Effect.catch` blocks (the v4 name for what was `Effect.catchAll`) that flatten distinct failures into one message-only error.
214
ts/packages/cli/CHANGELOG.md
+6
@@ -4,6 +4,12 @@
4
5 ### Patch Changes
6
7 +- `composio search` now fails with "The API response for
8 + 'toolRouter.session.search' is not in the shape this version of the CLI
9 + expects" and `composio upgrade` as the way out when the API answers 200 with
10 + JSON it cannot read or with an empty body. It crashed with a raw `TypeError`
11 + naming a minified variable, which told an agent nothing it could act on.
12 +
13 - `composio whoami` now exits 1 when it cannot read the account (the backend
14 rejects the stored key, cannot be reached, or fails), with nothing on stdout
15 and the reason on stderr; a rejected key also names `composio login`. It
ts/packages/cli/src/commands/tools/search/tools.search.format.ts
+6 -15
@@ -1,21 +1,12 @@
1 -import type { SessionSearchResponse } from '@composio/client/resources/tool-router';
1 import { Effect } from 'effect';
2 +import type { SearchResult, SearchToolSchemas } from 'src/models/tool-search';
3 import type { Tool } from 'src/models/tools';
4 import type { TerminalUI } from 'src/services/terminal-ui';
5 import type { CommandTree } from 'src/commands/surface';
6 import { commandHintExample, commandHintStep } from 'src/services/command-hints';
7 import { formatToolsTable } from '../format';
8
9 -export type SearchToolSchema = NonNullable<SessionSearchResponse['tool_schemas'][string]>;
10 -export type SearchResultRecord = SessionSearchResponse['results'][number];
11 -export type SearchResponseRecord = Pick<
12 - SessionSearchResponse,
13 - 'results' | 'toolkit_connection_statuses' | 'tool_schemas' | 'next_steps_guidance' | 'error'
14 ->;
15 -
16 -export const stripSearchResultMetadata = <
17 - T extends { reference_workbench_snippets?: unknown; plan_id?: unknown },
18 ->(
9 +export const stripSearchResultMetadata = <T extends Readonly<Record<string, unknown>>>(
10 result: T
11 ) => {
12 const {
@@ -33,10 +24,10 @@ export const toHomeRelativePath = (cacheDir: string, absolutePath: string) =>
24
25 export const collectToolsForResult = (params: {
26 result: {
36 - primary_tool_slugs: string[];
37 - related_tool_slugs: string[];
27 + primary_tool_slugs: ReadonlyArray<string>;
28 + related_tool_slugs: ReadonlyArray<string>;
29 };
39 - toolSchemas: Record<string, SearchToolSchema>;
30 + toolSchemas: SearchToolSchemas;
31 toolkitSet?: Set<string>;
32 limit: number;
33 }): Tool[] => {
@@ -112,7 +103,7 @@ export const buildSearchNextSteps = (params: {
103 export const emitHumanSearchOutput = (params: {
104 ui: TerminalUI;
105 queries: ReadonlyArray<string>;
115 - resultsWithTools: Array<{ result: SearchResultRecord; tools: Tool[] }>;
106 + resultsWithTools: Array<{ result: SearchResult; tools: Tool[] }>;
107 nextStepsGuidance: ReadonlyArray<string>;
108 firstSlug?: string;
109 firstDataArg: string;
ts/packages/cli/src/commands/tools/search/tools.search.handler.ts
+15 -17
@@ -8,7 +8,8 @@ import { clampLimit } from 'src/ui/clamp-limit';
8 import { resolveToolRouterSession } from 'src/effects/create-tool-router-session';
9 import { buildMinimalPayloadFromSchema } from 'src/ui/build-minimal-payload';
10 import { ComposioClientSingleton } from 'src/services/composio-clients';
11 -import { idempotent } from 'src/services/composio-request';
11 +import { decode, idempotent } from 'src/services/composio-request';
12 +import { SearchToolSchemas, ToolSearchResponse } from 'src/models/tool-search';
13 import { isRemoteCustomToolSlug } from 'src/utils/remote-custom-toolkit';
14 import { toolInputRequiredError } from 'src/utils/tool-input-required';
15 import {
@@ -28,8 +29,6 @@ import {
29 stripSearchResultMetadata,
30 toHomeRelativePath,
31 TOOL_SCHEMA_PATH_FORMAT,
31 - type SearchResponseRecord,
32 - type SearchToolSchema,
32 } from './tools.search.format';
33
34 export type ToolsSearchParams = {
@@ -43,7 +42,7 @@ export type ToolsSearchParams = {
42 const invalidSearchInput = commandInputError('search');
43
44 const buildSearchJsonPayload = (params: {
46 - searchResponse: SearchResponseRecord;
45 + searchResponse: ToolSearchResponse;
46 cacheScope: { orgId?: string; consumerUserId?: string };
47 projectScope: { orgId: string; projectId: string };
48 nextSteps: Array<{ action: string; command: string }>;
@@ -151,11 +150,14 @@ export const runToolsSearch = (params: ToolsSearchParams) =>
150 const searchPayload = {
151 queries: queries.map(query => ({ use_case: query })),
152 };
154 - // The command reads a few of the search response's fields; the rest, enums
153 + // Decoded with the CLI's schema for the fields it reads; the rest, enums
154 // among them, may change without this version of the CLI noticing.
155 const searchResponse = yield* client.toolRouter.session
156 .search(sessionId, searchPayload, idempotent)
158 - .pipe(failedWith(ToolsSearchRequestError, 'Failed to search tools.'));
157 + .pipe(
158 + Effect.flatMap(decode(ToolSearchResponse, { operation: 'toolRouter.session.search' })),
159 + failedWith(ToolsSearchRequestError, 'Failed to search tools.')
160 + );
161 const customToolSlugsMissingSchemas = Object.entries(searchResponse.tool_schemas)
162 .filter(([slug, schema]) => isRemoteCustomToolSlug(slug) && !schema.input_schema)
163 .map(([slug]) => slug);
@@ -191,17 +193,13 @@ export const runToolsSearch = (params: ToolsSearchParams) =>
193 return yield* schemasFailed(new Error(schemaResponse.error));
194 }
195
194 - const resolvedSchemas = schemaResponse.data.tool_schemas;
195 - if (!resolvedSchemas || typeof resolvedSchemas !== 'object') {
196 - return yield* schemasFailed(new Error('Tool Router returned no tool schemas.'));
197 - }
196 + const resolvedSchemas = yield* decode(SearchToolSchemas, {
197 + operation: 'toolRouter.session.executeMeta',
198 + })(schemaResponse.data.tool_schemas).pipe(Effect.mapError(schemasFailed));
199
200 return {
201 ...searchResponse,
201 - tool_schemas: {
202 - ...searchResponse.tool_schemas,
203 - ...(resolvedSchemas as Record<string, SearchToolSchema>),
204 - },
202 + tool_schemas: { ...searchResponse.tool_schemas, ...resolvedSchemas },
203 };
204 });
205 return {
@@ -296,7 +294,7 @@ export const runToolsSearch = (params: ToolsSearchParams) =>
294 limit: clampedLimit,
295 resultCount: totalToolCount,
296 toolRouterSessionId: searchResult.historyScope?.toolRouterSessionId,
299 - nextSteps: searchResponse.next_steps_guidance,
297 + nextSteps: searchResponse.next_steps_guidance ?? [],
298 },
299 }).pipe(Effect.catch(() => Effect.void));
300
@@ -305,11 +303,11 @@ export const runToolsSearch = (params: ToolsSearchParams) =>
303 ui,
304 queries,
305 resultsWithTools,
308 - nextStepsGuidance: searchResponse.next_steps_guidance,
306 + nextStepsGuidance: searchResponse.next_steps_guidance ?? [],
307 firstSlug,
308 firstDataArg,
309 tree,
312 - error: searchResponse.error,
310 + error: searchResponse.error ?? null,
311 });
312 } else if (emitJson) {
313 const outputJson = JSON.stringify(outputForJq, null, 2);
ts/packages/cli/src/effect-errors/logic/errors/extract-error-details.ts
+15 -2
@@ -1,10 +1,13 @@
1 +import type { DecodeError } from '@composio/client/effect';
2 import { hasProperty, isFunction } from 'effect/Predicate';
3 import {
4 describeDecodeError,
5 isClientApiError,
6 isClientConnectionError,
7 isClientDecodeError,
8 + isOperationDecodingError,
9 type ClientApiError,
10 + type OperationDecodingError,
11 } from 'src/utils/api-error-extraction';
12
13 interface ErrorDetails {
@@ -13,13 +16,17 @@ interface ErrorDetails {
16 message: unknown;
17 }
18
19 +const decodeErrorDetail = (error: DecodeError | OperationDecodingError): string => {
20 + const { message, hint } = describeDecodeError(error);
21 + return `${message}\n${hint}`;
22 +};
23 +
24 // A client error has no cause chain: its own message is the status line and
25 // response body, and a connection error's description is the transport's text.
26 // A response that failed decoding is reported by operation and request id.
27 const clientApiErrorDetail = (error: ClientApiError): string => {
28 if (isClientDecodeError(error)) {
21 - const { message, hint } = describeDecodeError(error);
22 - return `${message}\n${hint}`;
29 + return decodeErrorDetail(error);
30 }
31 if (isClientConnectionError(error)) {
32 return error.description ?? error.message;
@@ -42,6 +49,8 @@ const causeDetail = (cause: unknown): string | undefined => {
49 }
50
51 if (isClientApiError(current)) return clientApiErrorDetail(current);
52 + // Its cause is the schema issues, which may quote the response.
53 + if (isOperationDecodingError(current)) return decodeErrorDetail(current);
54
55 if (typeof current === 'string' && current.length > 0) {
56 detail = current;
@@ -86,6 +95,10 @@ export const extractErrorDetails = (error: unknown): ErrorDetails => {
95 };
96 }
97
98 + if (isOperationDecodingError(error)) {
99 + return { isPlainString: false, type: error.name, message: decodeErrorDetail(error) };
100 + }
101 +
102 const isTaggedErrorWithCause =
103 error instanceof Error && hasProperty(error, 'cause') && hasProperty(error, '_tag');
104 if (isTaggedErrorWithCause) {
ts/packages/cli/src/models/tool-search.ts new
+54
@@ -0,0 +1,54 @@
1 +import { Schema } from 'effect';
2 +
3 +/**
4 + * The CLI's contract for a Tool Router search response (`toolRouter.session.search`): the fields
5 + * `composio search` reads, and nothing it does not. The client's schema for the endpoint also
6 + * fixes enums and requires fields the command never reads, which may change without this
7 + * version of the CLI noticing.
8 + */
9 +
10 +const JsonObject = Schema.Record(Schema.String, Schema.Unknown);
11 +
12 +/** A tool's schema in a search response, as `composio search` lists and caches it. */
13 +export const SearchToolSchema = Schema.Struct({
14 + toolkit: Schema.String,
15 + tool_slug: Schema.String,
16 + description: Schema.optional(Schema.NullOr(Schema.String)),
17 + input_schema: Schema.optional(Schema.NullOr(JsonObject)),
18 + output_schema: Schema.optional(Schema.NullOr(JsonObject)),
19 +}).annotate({ identifier: 'SearchToolSchema' });
20 +export type SearchToolSchema = Schema.Schema.Type<typeof SearchToolSchema>;
21 +
22 +export const SearchToolSchemas = Schema.Record(Schema.String, SearchToolSchema);
23 +export type SearchToolSchemas = Schema.Schema.Type<typeof SearchToolSchemas>;
24 +
25 +const SearchResultFields = Schema.StructWithRest(
26 + Schema.Struct({
27 + use_case: Schema.String,
28 + primary_tool_slugs: Schema.Array(Schema.String),
29 + related_tool_slugs: Schema.Array(Schema.String),
30 + recommended_plan_steps: Schema.optional(Schema.NullOr(Schema.Array(Schema.String))),
31 + }),
32 + [JsonObject]
33 +);
34 +export type SearchResult = Schema.Schema.Type<typeof SearchResultFields>;
35 +
36 +/**
37 + * One query's result. `composio search` prints the result on stdout, so it is checked and then
38 + * kept as the API sent it, its other fields and its key order included: decoding a struct
39 + * rebuilds the object with the declared fields first.
40 + */
41 +export const SearchResult = Schema.declare(Schema.is(SearchResultFields)).annotate({
42 + identifier: 'SearchResult',
43 +});
44 +
45 +export const ToolSearchResponse = Schema.Struct({
46 + results: Schema.Array(SearchResult),
47 + tool_schemas: SearchToolSchemas,
48 + toolkit_connection_statuses: Schema.Array(
49 + Schema.Struct({ toolkit: Schema.String, has_active_connection: Schema.Boolean })
50 + ),
51 + error: Schema.optional(Schema.NullOr(Schema.String)),
52 + next_steps_guidance: Schema.optional(Schema.NullOr(Schema.Array(Schema.String))),
53 +}).annotate({ identifier: 'ToolSearchResponse' });
54 +export type ToolSearchResponse = Schema.Schema.Type<typeof ToolSearchResponse>;
ts/packages/cli/src/services/composio-errors.ts
+7
@@ -19,6 +19,13 @@ export class ComposioClientConfigurationError extends Data.TaggedError(
19 */
20 export class HttpDecodingError extends Data.TaggedError('services/HttpDecodingError')<{
21 readonly cause?: unknown;
22 + /**
23 + * The request whose response failed, as the client names its operation
24 + * (`toolRouter.session.search`). With it, the failure is reported like the
25 + * client's own `DecodeError`: by operation, with an upgrade hint, never with
26 + * the schema issues, which may quote the response.
27 + */
28 + readonly operation?: string;
29 }> {}
30
31 /**
ts/packages/cli/src/services/composio-request.ts
+7 -3
@@ -34,11 +34,15 @@ export const idempotent = { maxRetries: DEFAULT_MAX_RETRIES } satisfies RequestO
34 export const validated = { decode: true } satisfies RequestOptions;
35
36 /**
37 - * Decodes a payload against a CLI-owned contract.
37 + * Decodes a payload against a CLI-owned contract. Pass the client's name for
38 + * the request's `operation` to have a mismatch reported by that name.
39 */
40 export const decode =
40 - <S extends Schema.Top>(schema: S) =>
41 + <S extends Schema.Top>(schema: S, options?: { readonly operation?: string }) =>
42 (input: unknown): Effect.Effect<S['Type'], HttpDecodingError, S['DecodingServices']> =>
43 Schema.decodeUnknownEffect(schema)(input).pipe(
43 - Effect.catchTag('SchemaError', cause => new HttpDecodingError({ cause }))
44 + Effect.catchTag(
45 + 'SchemaError',
46 + cause => new HttpDecodingError({ cause, operation: options?.operation })
47 + )
48 );
ts/packages/cli/src/utils/api-error-extraction.ts
+28 -9
@@ -19,7 +19,11 @@ import {
19 type DecodeError,
20 } from '@composio/client/effect';
21 import { Predicate } from 'effect';
22 -import { CLIENT_API_ERROR_TAGS, type ClientApiError } from 'src/services/composio-errors';
22 +import {
23 + CLIENT_API_ERROR_TAGS,
24 + HttpDecodingError,
25 + type ClientApiError,
26 +} from 'src/services/composio-errors';
27
28 export type { ClientApiError };
29
@@ -37,16 +41,30 @@ export const isClientConnectionError = (value: unknown): value is APIConnectionE
41 export const isClientDecodeError = (value: unknown): value is DecodeError =>
42 isComposioError(value) && Predicate.isTagged(value, '@composio/client/DecodeError');
43
44 +/** A response that failed the CLI's own schema, for a request named by its client operation. */
45 +export type OperationDecodingError = HttpDecodingError & { readonly operation: string };
46 +
47 +export const isOperationDecodingError = (value: unknown): value is OperationDecodingError =>
48 + value instanceof HttpDecodingError && value.operation !== undefined;
49 +
50 /**
41 - * What the CLI prints when a response failed client decoding. It names the
42 - * request and never quotes the response.
51 + * What the CLI prints when a response failed client decoding, or the CLI's
52 + * own schema for a named operation. It names the request and never quotes the
53 + * response.
54 */
55 export const describeDecodeError = (
45 - error: DecodeError
56 + error: DecodeError | OperationDecodingError
57 ): { readonly message: string; readonly hint: string } => {
58 const subject =
48 - error.operation !== undefined ? `'${error.operation}'` : `${error.method} ${error.url}`;
49 - const requestId = error.requestId !== undefined ? ` (request id: ${error.requestId})` : '';
59 + error.operation !== undefined
60 + ? `'${error.operation}'`
61 + : isClientDecodeError(error)
62 + ? `${error.method} ${error.url}`
63 + : 'a request';
64 + const requestId =
65 + isClientDecodeError(error) && error.requestId !== undefined
66 + ? ` (request id: ${error.requestId})`
67 + : '';
68 return {
69 message: `The API response for ${subject} is not in the shape this version of the CLI expects${requestId}.`,
70 hint: 'Upgrade the CLI, then retry:\n> composio upgrade',
@@ -121,9 +139,10 @@ export const extractMessage = (value: unknown, seen?: Set<unknown>): string | un
139 return value.details?.message ?? extractMessage(value.body, visited) ?? value.message;
140 }
141
124 - // A response that failed client decoding is reported by operation and
125 - // request id, with the remedy, never by the client's raw message.
126 - if (isClientDecodeError(value)) {
142 + // A response that failed client decoding (or the CLI's schema for a named
143 + // operation) is reported by operation and request id, with the remedy,
144 + // never by the raw message.
145 + if (isClientDecodeError(value) || isOperationDecodingError(value)) {
146 const { message, hint } = describeDecodeError(value);
147 return `${message}\n${hint}`;
148 }
ts/packages/cli/test/src/commands/tools/search/tools.search.client.cmd.test.ts
+46
@@ -139,6 +139,15 @@ describe('CLI: composio search over the API client', () => {
139 };
140 // Once as the log line and once as the piped output.
141 expect(lines).toEqual([JSON.stringify(payload, null, 2), JSON.stringify(payload, null, 2)]);
142 + // A result keeps the API's key order on stdout.
143 + expect(Object.keys(JSON.parse(String(lines.at(-1))).results[0])).toEqual([
144 + 'index',
145 + 'use_case',
146 + 'difficulty',
147 + 'primary_tool_slugs',
148 + 'related_tool_slugs',
149 + 'toolkits',
150 + ]);
151 expect(stub.requests.filter(request => request.path === SEARCH_PATH)).toEqual([
152 {
153 method: 'POST',
@@ -179,6 +188,43 @@ describe('CLI: composio search over the API client', () => {
188 );
189 });
190
191 + layer(testLayer)('[Given] a 200 search response the command cannot read', it => {
192 + it.effect.each([
193 + { name: 'JSON of another shape', respond: () => Response.json({ unexpected: true }) },
194 + {
195 + name: 'a result without its tool slugs',
196 + respond: () =>
197 + Response.json({
198 + ...searchResponse,
199 + results: [{ index: 1, use_case: 'send an email', toolkits: ['gmail'] }],
200 + }),
201 + },
202 + {
203 + name: 'an empty body',
204 + respond: () =>
205 + new Response(null, {
206 + status: 200,
207 + headers: { 'content-type': 'application/json', 'content-length': '0' },
208 + }),
209 + },
210 + ])('[Then] $name fails as a response this CLI does not understand', ({ respond }) =>
211 + Effect.gen(function* () {
212 + const stub = searchingOver(respond);
213 + const terminal = redirectedTerminalUI();
214 + const exit = yield* Effect.exit(
215 + cli(['search', 'send an email']).pipe(Effect.provide([stub.layer, terminal.layer]))
216 + );
217 +
218 + expect(exitCodeOf(exit)).toBe(1);
219 + expect(terminal.stdout()).toBe('');
220 + expect(terminal.stderr()).toContain(
221 + "Failed to search tools.\nCaused by: The API response for 'toolRouter.session.search' is not in the shape this version of the CLI expects.\nUpgrade the CLI, then retry:\n> composio upgrade"
222 + );
223 + expect(terminal.stderr()).not.toContain('TypeError');
224 + })
225 + );
226 + });
227 +
228 layer(testLayer)('[Given] the API rejects the search', it => {
229 it.effect('[Then] the command fails with the status and response body as the cause', () =>
230 Effect.gen(function* () {
ts/packages/cli/test/src/effect-errors/extract-error-details.test.ts
+38
@@ -7,6 +7,7 @@ import {
7 import { describe, expect, it } from 'vitest';
8 import { Data } from 'effect';
9 import { extractErrorDetails } from 'src/effect-errors/logic/errors/extract-error-details';
10 +import { HttpDecodingError } from 'src/services/composio-errors';
11
12 class RequestError extends Data.TaggedError('RequestError')<{
13 readonly message: string;
@@ -200,4 +201,41 @@ describe('extractErrorDetails for an uncaught API failure', () => {
201 );
202 });
203 });
204 +
205 + describe("raised for a response that failed the CLI's schema", () => {
206 + // The schema issues may quote the response, so they are never shown.
207 + const shapeError = new HttpDecodingError({
208 + cause: new Error('Expected array, got {"secret":"value"}'),
209 + operation: 'toolRouter.session.search',
210 + });
211 + const described =
212 + "The API response for 'toolRouter.session.search' is not in the shape this version of the CLI expects.\nUpgrade the CLI, then retry:\n> composio upgrade";
213 +
214 + it('names the operation and suggests an upgrade', () => {
215 + expect(extractErrorDetails(shapeError)).toStrictEqual({
216 + isPlainString: false,
217 + type: 'services/HttpDecodingError',
218 + message: described,
219 + });
220 + });
221 +
222 + it('does so as the cause of a command error', () => {
223 + const error = new RequestError({ message: 'Failed to search tools.', cause: shapeError });
224 +
225 + expect(extractErrorDetails(error).message).toBe(
226 + `Failed to search tools.\nCaused by: ${described}`
227 + );
228 + });
229 +
230 + it('keeps the schema issues of a failure that names no operation', () => {
231 + const error = new RequestError({
232 + message: 'Failed to fetch toolkits.',
233 + cause: new HttpDecodingError({ cause: new Error('Expected array') }),
234 + });
235 +
236 + expect(extractErrorDetails(error).message).toBe(
237 + 'Failed to fetch toolkits.\nCaused by: Expected array'
238 + );
239 + });
240 + });
241 });
ts/packages/cli/test/src/utils/api-error-extraction.test.ts
+12
@@ -5,6 +5,7 @@ import {
5 RateLimitError,
6 } from '@composio/client/effect';
7 import { describe, expect, it } from 'vitest';
8 +import { HttpDecodingError } from 'src/services/composio-errors';
9 import {
10 extractApiErrorDetails,
11 extractMessage,
@@ -144,6 +145,17 @@ describe('extractMessage', () => {
145 );
146 });
147
148 + it("reports a response that failed the CLI's schema for a named operation, with the remedy", () => {
149 + const shapeError = new HttpDecodingError({
150 + cause: new Error('Expected object, got undefined'),
151 + operation: 'toolRouter.session.search',
152 + });
153 +
154 + expect(extractMessage({ cause: shapeError })).toBe(
155 + "The API response for 'toolRouter.session.search' is not in the shape this version of the CLI expects.\nUpgrade the CLI, then retry:\n> composio upgrade"
156 + );
157 + });
158 +
159 it('reads the transport text of a connection error', () => {
160 const error = connectionError('fetch failed: connect ECONNREFUSED 127.0.0.1:1');
161