@devries-cameron20 / composio-1 / commits / c59c2db88
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.

feat(cli): exit 75 when a failed request is safe to send again (#5387)

This PR: - builds on top of https://github.com/ComposioHQ/composio/pull/5364 - exits 75 (`EX_TEMPFAIL`) instead of 1 when a failed request is safe to send again as it is: a 429, or a timeout, connection failure, 408 or 5xx of an idempotent method; stderr says to run the same command again - `composio execute` adds `"retry": "safe"` or `"retry": "check-first"` to its `{ "successful": false }` result; `check-first` means the tool may have run before the request failed (timeout, reset, 5xx, unreadable response), so repeating it could act twice. Off a terminal stderr stays empty, as before - one classifier, `retryAdviceFor` (`src/effects/retry-advice.ts`), feeds `handleClientApiError`, the invocation's failure report, and `execute` on both the Dashboard and backend transports - the `composio-cli` skill tells agents what exit 75 and `retry` mean: one line in the default workflow, and a troubleshooting section on when to run a command again and when to check first - `operations/network-faults.test.ts` pins it: a 429 on `search` exits 75; each execution fault is still sent once and reports its `retry` ## Context Claude Code's exit-2 handling applies to hooks, not to tool commands, and exit 2 conventionally means a usage error. A distinct code for "temporary, safe to retry" lets any caller (agents, scripts, CI) retry without parsing text. The CLI decides retry safety because only it knows whether a request has a side effect. Known gap: the client's errors carry the HTTP method but not whether the call was sent with `idempotent`, so a POST read such as `search` still exits 1 on a 5xx or timeout even though the client retried it. https://github.com/ComposioHQ/composio-client/issues/244 asks the client to carry that flag (and `retry-after`) on its errors. The CLI test workflow only runs on PRs targeting `next`, so full CI completes after the stack below merges and this PR is retargeted.

Alberto Schiabel committed Nov 16, 2026 at 13:24 UTC c59c2db88a5c67d8034280f1b5639c9f5cf783cc
22 files changed +603 -52
.agents/skills/cli-command/references/design.md
+1 -1
@@ -26,7 +26,7 @@
26 - Runtime config is read from environment variables via `effect/Config`. Every variable the CLI reads is declared, under its full name, in one of the catalogs in `src/config` (`APP_CONFIG` for user-facing `COMPOSIO_*` settings, `DEBUG_CONFIG`, `TELEMETRY_CONFIG`, `HOST_CONFIG`, `GITHUB_CONFIG`); add new variables there, never inline. Tests inject `ConfigProvider.fromEnvRecord({...})`.
27 - Persistent user/auth state lives in `~/.composio/config.json` and `~/.composio/user_data.json`. The API key can be stored in the OS keyring. `ComposioUserContext` applies environment overrides to stored values.
28 - Project-scoped data uses a project-local `.composio/` directory.
29 -- Exit `0` on success and `1` on failure. A command a signal cancels exits 128 + the signal's number: `130` (Ctrl-C), `143` (SIGTERM), `129` (SIGHUP). A listener stopped with Ctrl-C or SIGTERM once subscribed exits `0`; `composio run` ends the way its script did (its code, or the same signal). Never assign `process.exitCode`: an error declares `[Runtime.errorExitCode]` / `[Runtime.errorReported]` (effect `Runtime`), and `Runtime.defaultTeardown`, run by the CLI's runner (`src/run-main.ts`), picks the code. Never install signal handlers in a command; cooperate through `ShutdownSignal` instead (see `ts/packages/cli/AGENTS.md`). There is no distinct "invalid usage" exit code — do not invent one.
29 +- Exit `0` on success and `1` on failure, or `75` (`EX_TEMPFAIL`) when the failure is a request that is safe to send again as it is: one the API refused with a 429, or one with an idempotent method that timed out, lost its connection, or got a 408 or 5xx (`retryAdviceFor` in `src/effects/retry-advice.ts`). A request that failed in flight and may have taken effect exits `1`; where the command knows it has a side effect (`composio execute`), it says to check before running it again. A command a signal cancels exits 128 + the signal's number: `130` (Ctrl-C), `143` (SIGTERM), `129` (SIGHUP). A listener stopped with Ctrl-C or SIGTERM once subscribed exits `0`; `composio run` ends the way its script did (its code, or the same signal). Never assign `process.exitCode`: an error declares `[Runtime.errorExitCode]` / `[Runtime.errorReported]` (effect `Runtime`), and `Runtime.defaultTeardown`, run by the CLI's runner (`src/run-main.ts`), picks the code. Never install signal handlers in a command; cooperate through `ShutdownSignal` instead (see `ts/packages/cli/AGENTS.md`). There is no distinct "invalid usage" exit code — do not invent one.
30
31 ## References
32
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 | 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 |
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 (75 for the 429, with how to retry); 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 (75 for the 429); **exactly one execution request**; stdout is JSON with `successful: false`, an error and `retry` (`safe` for the 429, else `check-first`); 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
+58 -14
@@ -5,6 +5,11 @@
5 * heals or fails with exit 1, empty stdout, and the cause on stderr. A tool
6 * execution is sent exactly once whatever happens, because a second attempt
7 * could act twice.
8 + *
9 + * A failure that is safe to send again as it is (a 429, which the API refused
10 + * before acting) exits 75 instead of 1, so a caller can retry on the code alone.
11 + * A failed execution says in its result whether it is safe to run again or may
12 + * have run (`retry`).
13 */
14
15 import { afterAll, afterEach, beforeAll, describe, expect, it } from 'bun:test';
@@ -24,6 +29,10 @@ import {
29
30 const SEARCH = 'toolRouter.session.search';
31
32 +/** The exit code of a failure that is safe to send again as it is (`EX_TEMPFAIL`). */
33 +const TEMPORARY_FAILURE = 75;
34 +const RETRY_HINT = 'run the same command again';
35 +
36 describe('network faults on a read (`search`)', () => {
37 let rig: CliRig;
38
@@ -62,6 +71,7 @@ describe('network faults on a read (`search`)', () => {
71 fault: Fault;
72 stderr: ReadonlyArray<string>;
73 attempts: number;
74 + exitCode?: number;
75 }> = [
76 {
77 name: 'HTTP 500 on every attempt',
@@ -72,8 +82,9 @@ describe('network faults on a read (`search`)', () => {
82 {
83 name: 'HTTP 429 on every attempt',
84 fault: { kind: 'status', status: 429, headers: { 'retry-after': '1' } },
75 - stderr: ['Injected HTTP 429'],
85 + stderr: ['Injected HTTP 429', RETRY_HINT],
86 attempts: 3,
87 + exitCode: TEMPORARY_FAILURE,
88 },
89 {
90 name: 'an HTML error page from a proxy',
@@ -101,14 +112,14 @@ describe('network faults on a read (`search`)', () => {
112 },
113 ];
114
104 - for (const { name, fault, stderr, attempts } of persistent) {
115 + for (const { name, fault, stderr, attempts, exitCode = 1 } of persistent) {
116 it(
106 - `${name}: exit 1, empty stdout, cause on stderr`,
117 + `${name}: exit ${exitCode}, empty stdout, cause on stderr`,
118 async () => {
119 rig.fake.faults.inject({ route: SEARCH, fault });
120 const result = await rig.run(SEARCH_SLACK);
121
111 - expect(result.exitCode).toBe(1);
122 + expect(result.exitCode).toBe(exitCode);
123 expect(result.stdout).toBe('');
124 for (const text of stderr) expect(clean(result.stderr)).toContain(text);
125 expect(searchRequests(result)).toHaveLength(attempts);
@@ -184,13 +195,45 @@ describe('network faults on a read (`search`)', () => {
195 }
196 });
197
187 -const EXECUTION_FAULTS: ReadonlyArray<{ name: string; fault: Fault }> = [
188 - { name: 'HTTP 500', fault: { kind: 'status', status: 500 } },
189 - { name: 'HTTP 429', fault: { kind: 'status', status: 429, headers: { 'retry-after': '1' } } },
190 - { name: 'an HTML error page', fault: { kind: 'html', status: 502 } },
191 - { name: 'a body that is not JSON', fault: { kind: 'malformed-json' } },
192 - { name: 'connection reset before any response', fault: { kind: 'reset' } },
193 - { name: 'connection reset in the middle of the body', fault: { kind: 'reset-mid-body' } },
198 +// A 429 refused the execution, so it is safe to send again; after any other fault the tool may
199 +// have run, so the result says to check first.
200 +const EXECUTION_FAULTS: ReadonlyArray<{
201 + name: string;
202 + fault: Fault;
203 + exitCode: number;
204 + retry: 'safe' | 'check-first';
205 +}> = [
206 + { name: 'HTTP 500', fault: { kind: 'status', status: 500 }, exitCode: 1, retry: 'check-first' },
207 + {
208 + name: 'HTTP 429',
209 + fault: { kind: 'status', status: 429, headers: { 'retry-after': '1' } },
210 + exitCode: TEMPORARY_FAILURE,
211 + retry: 'safe',
212 + },
213 + {
214 + name: 'an HTML error page',
215 + fault: { kind: 'html', status: 502 },
216 + exitCode: 1,
217 + retry: 'check-first',
218 + },
219 + {
220 + name: 'a body that is not JSON',
221 + fault: { kind: 'malformed-json' },
222 + exitCode: 1,
223 + retry: 'check-first',
224 + },
225 + {
226 + name: 'connection reset before any response',
227 + fault: { kind: 'reset' },
228 + exitCode: 1,
229 + retry: 'check-first',
230 + },
231 + {
232 + name: 'connection reset in the middle of the body',
233 + fault: { kind: 'reset-mid-body' },
234 + exitCode: 1,
235 + retry: 'check-first',
236 + },
237 ];
238
239 for (const transport of [
@@ -227,19 +270,20 @@ for (const transport of [
270 TEST_TIMEOUT_MS
271 );
272
230 - for (const { name, fault } of EXECUTION_FAULTS) {
273 + for (const { name, fault, exitCode, retry } of EXECUTION_FAULTS) {
274 it(
232 - `${name}: sent exactly once, reported as a failed result on stdout`,
275 + `${name}: sent exactly once, reported as a failed result on stdout with retry "${retry}"`,
276 async () => {
277 rig.fake.faults.inject({ route: transport.route, fault });
278 const result = await rig.run(EXECUTE_SLACK);
279
237 - expect(result.exitCode).toBe(1);
280 + expect(result.exitCode).toBe(exitCode);
281 expect(result.requests.filter(entry => entry.route === transport.route)).toHaveLength(1);
282 const outcome = stdoutJson(result, ExecutionResult);
283 expect(outcome.successful).toBe(false);
284 expect(outcome.error ?? '').not.toBe('');
285 expect(outcome.data).toBeUndefined();
286 + expect(outcome.retry).toBe(retry);
287 },
288 TEST_TIMEOUT_MS
289 );
ts/e2e-tests/cli/operations/support.ts
+1
@@ -54,6 +54,7 @@ export const ExecutionResult = z.looseObject({
54 error: z.string().nullable().optional(),
55 slug: z.string().optional(),
56 data: z.record(z.string(), z.unknown()).optional(),
57 + retry: z.enum(['safe', 'check-first']).optional(),
58 });
59
60 export const SearchResult = z.looseObject({
ts/packages/cli/AGENTS.md
+1 -1
@@ -25,7 +25,7 @@ The CLI is built on the **Effect.ts ecosystem** and runs on **Bun**. Service-ori
25 - `UpgradeBinaryLive` — Self-update from GitHub releases
26 - `BunFileSystem.layer`, `BunPath.layer`, `BunServices.layer`, `FetchHttpClient.layer` — Bun runtime integration (`@effect/platform-bun`'s `BunContext` no longer exists in v4; `BunServices.layer` is the aggregate replacement)
27
28 -Explicit help and version actions complete successfully. `Command.runWith` renders parse/validation errors and contextual help itself before re-failing with `CliError.ShowHelp`, which carries `[Runtime.errorReported] = false` (suppresses the runner's automatic error log) and `[Runtime.errorExitCode]` (1 alongside parse errors). `runInvocation` prints every failure not yet on screen (an expected failure's message, a 401 with the login hint from `unauthorizedHint` in `src/effects/rejected-user-api-key.ts`, or the defect report), never one already on screen (`[Runtime.errorReported] = false`, `ShowHelp` included), and fails with the command's own `Cause`, so tests can match its typed error. `forRunner` hands that to the runner with what it printed marked reported (`ReportedFailure`), keeping the markers of failures already on screen, and the runner exits through `Runtime.defaultTeardown`: 0 on success, otherwise the squashed failure's `[Runtime.errorExitCode]`, or 1 without one. This preserves failing exit codes without duplicate error output. Never assign `process.exitCode`; an error that needs a code other than 1 declares it (`ChildProcessExited` in `src/effects/child-process-exited.ts`, which `composio run` fails with when its script exits non-zero). See the module docstring at the top of `cli-main.ts` for the argv-prefix contract with `src/commands/index.ts`. In tests, `cliExit(args)` returns `{ exit, exitCode }` and `exitCodeOf(exit)` the code, both mapped the way `runCli` maps them (`runnerExit`, then the runner's `exitActionFor`).
28 +Explicit help and version actions complete successfully. `Command.runWith` renders parse/validation errors and contextual help itself before re-failing with `CliError.ShowHelp`, which carries `[Runtime.errorReported] = false` (suppresses the runner's automatic error log) and `[Runtime.errorExitCode]` (1 alongside parse errors). `runInvocation` prints every failure not yet on screen (an expected failure's message, a 401 with the login hint from `unauthorizedHint` in `src/effects/rejected-user-api-key.ts`, or the defect report), never one already on screen (`[Runtime.errorReported] = false`, `ShowHelp` included), and fails with the command's own `Cause`, so tests can match its typed error. `forRunner` hands that to the runner with what it printed marked reported (`ReportedFailure`), keeping the markers of failures already on screen, and the runner exits through `Runtime.defaultTeardown`: 0 on success, otherwise the squashed failure's `[Runtime.errorExitCode]`, or 1 without one. A request failure that is safe to send again as it is (`retryAdviceFor` in `src/effects/retry-advice.ts`: a 429, or a timeout, connection failure, 408 or 5xx of an idempotent method) is printed with `retryHint('safe')` and exits 75 (`TEMPORARY_FAILURE_EXIT_CODE`, `EX_TEMPFAIL`), whether `handleClientApiError`, `runInvocation` or `composio execute` reports it; `ReportedFailure` and `ReportedToolExecutionError` carry it as `retryable`. `composio execute` adds `"retry": "safe"` or `"retry": "check-first"` (the execution may have run before it failed) to its `{ "successful": false }` result. This preserves failing exit codes without duplicate error output. Never assign `process.exitCode`; an error that needs a code other than 1 declares it (`ChildProcessExited` in `src/effects/child-process-exited.ts`, which `composio run` fails with when its script exits non-zero). See the module docstring at the top of `cli-main.ts` for the argv-prefix contract with `src/commands/index.ts`. In tests, `cliExit(args)` returns `{ exit, exitCode }` and `exitCodeOf(exit)` the code, both mapped the way `runCli` maps them (`runnerExit`, then the runner's `exitActionFor`).
29
30 Signals belong to the runner, the one place that installs SIGINT, SIGTERM and SIGHUP handlers; never add `process.on` for them elsewhere. It hands the first signal to the invocation's `ShutdownSignal` service (`src/services/shutdown-signal.ts`). A command that registered with `cooperate` for that signal stops by itself and ends normally: `listen` and `dev triggers listen` register `LISTENER_STOP` (SIGINT, SIGTERM) once Pusher confirms the subscription, through `TriggersRealtime`'s `onSubscribed`, and exit 0; `run` registers every signal, forwards it to its script's process group, and mirrors how the script ended (its code, or `ChildProcessSignaled`, whose signal the runner re-raises; when the CLI's own SIGTERM/SIGKILL escalation ended the script, the first signal instead). Every other command is interrupted, and an exit made of interruptions alone after a signal is 128 + its number: 130 (SIGINT), 143 (SIGTERM), 129 (SIGHUP). A second signal, or a stop longer than `SHUTDOWN_DEADLINE` (10 seconds), forces the exit: 128 + n, or for `run`, kill the script's group and re-raise.
31
ts/packages/cli/CHANGELOG.md
+2
@@ -4,6 +4,8 @@
4
5 ### Patch Changes
6
7 +- A failed request that is safe to send again now exits 75 (`EX_TEMPFAIL`) instead of 1 and says so on stderr: one the API refused with a 429, or a read that timed out, lost its connection, or got a 408 or 5xx. Scripts and agents can retry on 75 without guessing. A failed `composio execute` adds `"retry": "safe"`, or `"retry": "check-first"` when the tool may have run before the request failed, to its `{ "successful": false }` result, and the `composio-cli` skill tells agents what both mean. Every other failed request still exits 1.
8 +
9 - `composio dev toolkits list` and `info` now read a user's connection status in the resolved developer project. When no directory project applies, `--user-id` or the global test user can use the default developer project. A failed project lookup leaves the catalog available and warns when `--connected` cannot be applied.
10
11 - A directory developer project must belong to the stored login's org, checked before any request. With no stored org, the CLI checks every page of the active key's org list. Resource commands refuse a project outside that boundary and name why they use the default developer project instead.
ts/packages/cli/skills-src/composio-cli/index.ts
+2 -1
@@ -247,11 +247,12 @@ const defaultWorkflow = (build: SkillBuildContext) => {
247 '3. If `execute` says the toolkit is not connected, run `composio link <toolkit>` and retry.',
248 '4. If the arguments are unclear, run `composio execute <slug> --get-schema` or `--dry-run` before guessing.',
249 '5. Reach for `composio search "<task>"` only when the slug is unknown. `search` accepts one or more queries, so batch related discovery work into a single command when useful.',
250 + '6. If a command exits 75, the failure was temporary and running it again cannot act twice: wait a moment and run the same command again. If a failed `execute` result has `"retry": "check-first"`, the tool may already have run: check before running it again.',
251 ];
252
253 if (build.experimentalFeatures[CLI_EXPERIMENTAL_FEATURES.LISTEN]) {
254 lines.push(
254 - '6. If the CLI build enables the experimental `listen` feature, use it for temporary consumer-project trigger subscriptions.'
255 + '7. If the CLI build enables the experimental `listen` feature, use it for temporary consumer-project trigger subscriptions.'
256 );
257 }
258
ts/packages/cli/skills-src/composio-cli/references/troubleshooting.ts
+13
@@ -30,6 +30,19 @@ export const troubleshootingReference: ReferenceDocument = {
30 },
31 ],
32 },
33 + {
34 + title: 'A Command Failed And Might Work If Run Again',
35 + body: [
36 + 'Symptoms:',
37 + '- a command exits 75 instead of 1',
38 + '- a failed `execute` result on stdout has a `retry` field',
39 + 'Fix:',
40 + '- Exit 75 means the failure was temporary (rate limited, a timeout or a server error on a request that changes nothing) and running the same command again cannot act twice. Wait a few seconds and run it again; stop after two or three attempts and report the error.',
41 + '- `"retry": "safe"` on a failed `execute` result means the same, and the command exits 75.',
42 + '- `"retry": "check-first"` means the request failed in flight and the tool may already have run. Running it again could act twice (send the email twice, create two issues). First check whether it took effect, for example by reading the sent folder or listing the issues with another `execute`, and run it again only if it did not.',
43 + '- Any other failure exits 1: running the same command again fails the same way, so fix the cause the error names.',
44 + ],
45 + },
46 {
47 title: 'Invalid JSON Input',
48 body: [
ts/packages/cli/src/commands/tools/execute/tools.execute.errors.ts
+6 -2
@@ -1,6 +1,7 @@
1 import { Data, Runtime } from 'effect';
2 import { commandInputError } from 'src/commands/errors';
3 import { ExpectedFailure } from 'src/effects/expected-failure';
4 +import { TEMPORARY_FAILURE_EXIT_CODE } from 'src/effects/retry-advice';
5
6 // Also raised by the hand-rolled `--parallel` mini-parser (`parseParallelExecuteArgs` in `tools.execute.parallel.ts`).
7 export const invalidArguments = commandInputError('execute');
@@ -25,18 +26,21 @@ export class ToolExecutionError extends Data.TaggedError('ToolExecutionError')<{
26
27 /**
28 * A failed execution whose result is already on stdout as `{ "successful": false, ... }`.
28 - * The runtime prints nothing more for it (`[Runtime.errorReported]` is false) and exits 1.
29 + * The runtime prints nothing more for it (`[Runtime.errorReported]` is false) and exits 1, or
30 + * `TEMPORARY_FAILURE_EXIT_CODE` (75) when it is `retryable`: running the same command again
31 + * cannot make a change twice (see `src/effects/retry-advice.ts`).
32 */
33 export class ReportedToolExecutionError extends Data.TaggedError('ReportedToolExecutionError')<{
34 readonly reason: 'connection_check' | 'execution_failed' | 'parallel_failed';
35 readonly message: string;
36 readonly toolSlug?: string;
37 + readonly retryable?: boolean;
38 }> {
39 get [Runtime.errorReported]() {
40 return false;
41 }
42
43 get [Runtime.errorExitCode]() {
40 - return 1;
44 + return this.retryable === true ? TEMPORARY_FAILURE_EXIT_CODE : 1;
45 }
46 }
ts/packages/cli/src/commands/tools/execute/tools.execute.failure.ts
+18
@@ -8,6 +8,7 @@ import {
8 isMaybeToolNotFoundError,
9 } from 'src/analytics/events';
10 import * as constants from 'src/constants';
11 +import { retryHint, type RetryAdvice } from 'src/effects/retry-advice';
12 import { toolkitFromToolSlug } from 'src/effects/toolkit-from-tool-slug';
13 import type { ToolkitProjectScope } from 'src/services/composio-clients';
14 import {
@@ -293,3 +294,20 @@ export const handleExecutionError = (
294
295 return { error: mapped.message, slug: slugValue };
296 });
297 +
298 +/**
299 + * Tells the reader on a terminal whether the failed execution can be run again. Off a terminal it
300 + * prints nothing, like the rest of the failure: the JSON result on stdout carries it as `retry`.
301 + * In the developer tree, a request that may have taken effect also names where recent executions
302 + * are listed.
303 + */
304 +export const printExecuteRetryAdvice = (
305 + ui: TerminalUI,
306 + advice: RetryAdvice,
307 + surface: 'root' | 'dev'
308 +) =>
309 + ui.log.step(
310 + advice === 'check-first' && surface === 'dev'
311 + ? `${retryHint(advice)}\nRecent tool executions:\n> composio dev logs tools`
312 + : retryHint(advice)
313 + );
ts/packages/cli/src/commands/tools/execute/tools.execute.handler.ts
+18 -2
@@ -1,5 +1,6 @@
1 import { Effect, Option } from 'effect';
2 import { CommandSurface } from 'src/commands/surface';
3 +import { retryAdviceFor } from 'src/effects/retry-advice';
4 import { toolkitFromToolSlug } from 'src/effects/toolkit-from-tool-slug';
5 import { appendCliSessionHistory } from 'src/services/cli-session-artifacts';
6 import {
@@ -25,7 +26,11 @@ import {
26 } from './tools.execute.context';
27 import { perfDebugLog } from './tools.execute.debug';
28 import { invalidArguments, ReportedToolExecutionError } from './tools.execute.errors';
28 -import { emitExecuteFailureTelemetry, handleExecutionError } from './tools.execute.failure';
29 +import {
30 + emitExecuteFailureTelemetry,
31 + handleExecutionError,
32 + printExecuteRetryAdvice,
33 +} from './tools.execute.failure';
34 import {
35 ciRedactReplacer,
36 connectionTips,
@@ -255,9 +260,19 @@ const runExecuteWithSpinner = (params: {
260 stage: 'execution',
261 projectScope: toolkitProjectScope(params.resolvedProject),
262 });
263 + // Whether the request can be sent again as it is: `"retry": "safe"` (exit 75) or
264 + // `"retry": "check-first"` when it may have run before it failed.
265 + const retry = Option.getOrUndefined(retryAdviceFor(error));
266 + if (retry !== undefined) {
267 + yield* printExecuteRetryAdvice(params.ui, retry, params.surface);
268 + }
269 yield* writeExecuteStdout(
270 params.ui,
260 - JSON.stringify({ successful: false, ...summary }, ciRedactReplacer, 2)
271 + JSON.stringify(
272 + { successful: false, ...summary, ...(retry === undefined ? {} : { retry }) },
273 + ciRedactReplacer,
274 + 2
275 + )
276 );
277 yield* appendCliSessionHistory({
278 ...executeSessionHistoryScope(params.resolvedProject),
@@ -273,6 +288,7 @@ const runExecuteWithSpinner = (params: {
288 reason: 'execution_failed',
289 toolSlug: params.slug,
290 message: summary.error,
291 + ...(retry === 'safe' ? { retryable: true } : {}),
292 });
293 }),
294 onSuccess: result =>
ts/packages/cli/src/effects/handle-http-error.ts
+12 -2
@@ -5,6 +5,7 @@ import type { TerminalUI } from 'src/services/terminal-ui';
5 import { reportFailure, type ReportedFailure } from 'src/effects/report-failure';
6 import { describeDecodeError, isClientDecodeError } from 'src/utils/api-error-extraction';
7 import { isUnauthorized, unauthorizedHint } from 'src/effects/rejected-user-api-key';
8 +import { isSafeToRetry, retryHint } from 'src/effects/retry-advice';
9
10 export interface Suggestion {
11 readonly label: string;
@@ -24,10 +25,17 @@ interface ErrorReport {
25 readonly suggestedFix?: string;
26 // Set when the failure has its own remedy, which replaces the caller's hint.
27 readonly hint?: string;
28 + // Set when running the same command again is safe and may pass.
29 + readonly retryable?: boolean;
30 }
31
32 const reportOf = (e: ClientApiError): Effect.Effect<ErrorReport> => {
33 if (isClientDecodeError(e)) return Effect.succeed(describeDecodeError(e));
34 + // A temporary failure's remedy is to run the command again, whatever the caller's hint says.
35 + if (isSafeToRetry(e)) {
36 + const message = isAPIError(e) ? e.details?.message : undefined;
37 + return Effect.succeed({ message, hint: retryHint('safe'), retryable: true });
38 + }
39 if (isAPIError(e)) {
40 const statusReport = { message: e.details?.message, suggestedFix: e.details?.suggested_fix };
41 return isUnauthorized(e)
@@ -50,7 +58,9 @@ const reportOf = (e: ClientApiError): Effect.Effect<ErrorReport> => {
58 * The final rendering is `reportFailure`'s (`src/effects/report-failure.ts`):
59 * the message and hint reach stderr as plain lines when it is not a TTY, and
60 * the handler fails with a `ReportedFailure`, so the process exits 1 and
53 - * callers such as scripts and agents can detect the failure. The handler never
61 + * callers such as scripts and agents can detect the failure. A failure that is
62 + * safe to run again as it is (see `src/effects/retry-advice.ts`) says so in
63 + * place of the hint and exits 75. The handler never
64 * succeeds, so the recovered effect keeps the request's own success type and
65 * the caller reads the result straight through.
66 *
@@ -108,5 +118,5 @@ export const handleClientApiError =
118 }
119 }
120
111 - return yield* reportFailure(ui, message, withHint(hint));
121 + return yield* reportFailure(ui, message, withHint(hint), { retryable: report.retryable });
122 });
ts/packages/cli/src/effects/report-failure.ts
+16 -5
@@ -1,21 +1,25 @@
1 import { Data, Effect, Runtime } from 'effect';
2 +import { TEMPORARY_FAILURE_EXIT_CODE } from 'src/effects/retry-advice';
3 import type { TerminalUI } from 'src/services/terminal-ui';
4
5 /**
6 * A failure already shown to the user. It only makes the command fail: the runner does not
6 - * log it (`[Runtime.errorReported]` is false) and `Runtime.defaultTeardown` exits 1.
7 + * log it (`[Runtime.errorReported]` is false) and `Runtime.defaultTeardown` exits 1, or
8 + * `TEMPORARY_FAILURE_EXIT_CODE` (75) when it is `retryable`: running the same command again is
9 + * safe and may pass (see `src/effects/retry-advice.ts`).
10 *
11 * The markers are getters, like `ExpectedFailure`, so they stay off the instance's own properties.
12 */
13 export class ReportedFailure extends Data.TaggedError('effects/ReportedFailure')<{
14 readonly message: string;
15 + readonly retryable?: boolean;
16 }> {
17 get [Runtime.errorReported]() {
18 return false;
19 }
20
21 get [Runtime.errorExitCode]() {
18 - return 1;
22 + return this.retryable === true ? TEMPORARY_FAILURE_EXIT_CODE : 1;
23 }
24 }
25
@@ -39,15 +43,22 @@ export const printFailure = (ui: TerminalUI, message: string, hint?: string) =>
43
44 /**
45 * Reports a failure the command handles itself: prints it like `printFailure`, then fails with a
42 - * `ReportedFailure`, so the process exits 1 without printing more.
46 + * `ReportedFailure`, so the process exits 1 (75 when `retryable`) without printing more.
47 *
48 * A usage mistake fails with a `CommandInputError` instead; see `src/commands/errors.ts`.
49 */
50 export const reportFailure = (
51 ui: TerminalUI,
52 message: string,
49 - hint?: string
53 + hint?: string,
54 + options?: { readonly retryable?: boolean }
55 ): Effect.Effect<never, ReportedFailure> =>
56 printFailure(ui, message, hint).pipe(
52 - Effect.andThen(Effect.fail(new ReportedFailure({ message })))
57 + Effect.andThen(
58 + Effect.fail(
59 + new ReportedFailure(
60 + options?.retryable === true ? { message, retryable: true } : { message }
61 + )
62 + )
63 + )
64 );
ts/packages/cli/src/effects/retry-advice.ts new
+121
@@ -0,0 +1,121 @@
1 +import { isComposioError } from '@composio/client/effect';
2 +import { Option, Predicate } from 'effect';
3 +import type { ClientApiError } from 'src/services/composio-errors';
4 +import { DashboardToolExecutionError } from 'src/services/dashboard-tool-execution';
5 +
6 +/**
7 + * The exit code of a failure that is safe to retry as it is: `EX_TEMPFAIL` from `sysexits.h`
8 + * ("a temporary failure; the user is invited to retry"). Every other failure exits 1.
9 + */
10 +export const TEMPORARY_FAILURE_EXIT_CODE = 75;
11 +
12 +/**
13 + * What a caller can do after a request failed:
14 + *
15 + * - `safe`: run the same command again. The request did not take effect (the API refused it with
16 + * a 429), or it failed in a way that may pass on a later attempt and repeating it cannot repeat
17 + * a side effect (its method is idempotent).
18 + * - `check-first`: the request failed in flight and may have taken effect. Running the command
19 + * again could repeat its side effect, so check whether it did first.
20 + */
21 +export type RetryAdvice = 'safe' | 'check-first';
22 +
23 +/** The methods RFC 9110 defines as idempotent: repeating one has the effect of sending it once. */
24 +const IDEMPOTENT_METHODS: ReadonlySet<string> = new Set([
25 + 'GET',
26 + 'HEAD',
27 + 'OPTIONS',
28 + 'TRACE',
29 + 'PUT',
30 + 'DELETE',
31 +]);
32 +
33 +/** The transport failures the client refuses to retry: a redirect it will not follow. */
34 +const PERMANENT_CONNECTION_REASONS: ReadonlySet<string> = new Set([
35 + 'OpaqueRedirect',
36 + 'TooManyRedirects',
37 +]);
38 +
39 +const isClientApiError = (error: unknown): error is ClientApiError =>
40 + isComposioError(error) && error._tag !== '@composio/client/ConfigurationError';
41 +
42 +/**
43 + * The failed request behind `error`: `error` itself, or the `cause` a command's error keeps (see
44 + * `requestError`), a few levels deep.
45 + */
46 +const clientErrorOf = (error: unknown, depth = 0): Option.Option<ClientApiError> =>
47 + isClientApiError(error)
48 + ? Option.some(error)
49 + : depth < 3 && Predicate.hasProperty(error, 'cause')
50 + ? clientErrorOf(error.cause, depth + 1)
51 + : Option.none();
52 +
53 +/**
54 + * Whether the request ended in a way a later attempt may not: the same conditions the client
55 + * retries a call marked `idempotent` on (see `src/services/composio-request.ts`), less a 409.
56 + */
57 +const isTransient = (error: ClientApiError): boolean => {
58 + switch (error._tag) {
59 + case '@composio/client/APIConnectionTimeoutError':
60 + return true;
61 + case '@composio/client/APIConnectionError':
62 + return !PERMANENT_CONNECTION_REASONS.has(error.reason);
63 + case '@composio/client/RateLimitError':
64 + case '@composio/client/InternalServerError':
65 + return true;
66 + case '@composio/client/APIError':
67 + return error.status === 408;
68 + default:
69 + return false;
70 + }
71 +};
72 +
73 +/**
74 + * The advice for an execution the Dashboard transport sent (always once, as a `POST`): one that
75 + * got no answer, or an answer it could not read, may have run the tool; a 429 did not.
76 + */
77 +const dashboardAdvice = (error: DashboardToolExecutionError): Option.Option<RetryAdvice> => {
78 + if (error.status === 429) return Option.some('safe');
79 + switch (error.reason) {
80 + case 'request':
81 + case 'timeout':
82 + case 'response':
83 + return Option.some('check-first');
84 + case 'dashboard':
85 + return error.status !== undefined && error.status >= 500
86 + ? Option.some('check-first')
87 + : Option.none();
88 + default:
89 + return Option.none();
90 + }
91 +};
92 +
93 +/**
94 + * The retry advice for a failed request, when there is one: none for a failure that would fail
95 + * the same way again (a 4xx other than 408 and 429, a read whose response failed decoding,
96 + * anything that is not a failed request).
97 + */
98 +export const retryAdviceFor = (error: unknown): Option.Option<RetryAdvice> => {
99 + if (error instanceof DashboardToolExecutionError) return dashboardAdvice(error);
100 + return Option.flatMap(clientErrorOf(error), clientError => {
101 + const idempotent = IDEMPOTENT_METHODS.has(clientError.method.toUpperCase());
102 + // A response that arrived but could not be read: the request ran, so repeating a read fails
103 + // the same way, and repeating anything else may act twice.
104 + if (clientError._tag === '@composio/client/DecodeError') {
105 + return idempotent ? Option.none() : Option.some('check-first');
106 + }
107 + if (!isTransient(clientError)) return Option.none();
108 + if (clientError._tag === '@composio/client/RateLimitError') return Option.some('safe');
109 + return Option.some(idempotent ? 'safe' : 'check-first');
110 + });
111 +};
112 +
113 +/** Whether `error` is a failed request the caller can run again as it is. */
114 +export const isSafeToRetry = (error: unknown): boolean =>
115 + Option.contains(retryAdviceFor(error), 'safe');
116 +
117 +/** The line that tells the reader what to do about a failure with `advice`. */
118 +export const retryHint = (advice: RetryAdvice): string =>
119 + advice === 'safe'
120 + ? 'This failure is temporary, and repeating the request cannot make a change twice: run the same command again in a moment.'
121 + : 'The request may have taken effect before it failed. Check whether it did before you run the command again, or it may happen twice.';
ts/packages/cli/src/invocation/invocation.ts
+17 -2
@@ -23,6 +23,7 @@ import * as constants from 'src/constants';
23 import { isExpectedFailure } from 'src/effects/expected-failure';
24 import { isUnauthorized, unauthorizedHint } from 'src/effects/rejected-user-api-key';
25 import { ReportedFailure } from 'src/effects/report-failure';
26 +import { isSafeToRetry, retryHint } from 'src/effects/retry-advice';
27 import { toolkitFromToolSlug } from 'src/effects/toolkit-from-tool-slug';
28 import { getVersion } from 'src/effects/version';
29 import {
@@ -201,10 +202,16 @@ const report = (cause: Cause.Cause<unknown>) =>
202 Option.match({ onNone: () => Effect.void, onSome: ui.error })
203 )
204 : Effect.void;
205 + // A failed request that is safe to run again as it is says so after its message; the runner
206 + // exits 75 for it (see `runnerCause`).
207 + const printRetryHint = Option.exists(error, isSafeToRetry)
208 + ? ui.error(retryHint('safe'))
209 + : Effect.void;
210 const expected = Option.filter(error, isExpectedFailure);
211 if (Option.isSome(expected)) {
212 yield* ui.error(expected.value.message);
213 yield* printUnauthorizedHint(expected.value);
214 + yield* printRetryHint;
215 return;
216 }
217 // Any other 401 gets the backend's message in place of a defect report.
@@ -231,6 +238,7 @@ const report = (cause: Cause.Cause<unknown>) =>
238 }).trim();
239 if (message.length > 0) {
240 yield* ui.error(message);
241 + yield* printRetryHint;
242 }
243 });
244
@@ -263,14 +271,21 @@ export const runInvocation = (
271
272 /**
273 * The cause the runner receives for a failed invocation. A failure `runInvocation` put on screen
266 - * becomes a `ReportedFailure`: the runner logs nothing and exits 1. A failure that was on screen
274 + * becomes a `ReportedFailure`: the runner logs nothing and exits 1, or 75 for a failed request
275 + * that is safe to run again as it is. A failure that was on screen
276 * before (`ShowHelp`, a command's own report, `ChildProcessExited`) keeps its markers and its
277 * exit code, and an interruption stays one, so a signal still decides the exit.
278 */
279 export const runnerCause = (cause: Cause.Cause<unknown>): Cause.Cause<unknown> =>
280 cause.reasons.every(hasNothingToPrint)
281 ? cause
273 - : Cause.fail(new ReportedFailure({ message: Cause.pretty(cause) }));
282 + : Cause.fail(
283 + new ReportedFailure(
284 + Option.exists(Cause.findErrorOption(cause), isSafeToRetry)
285 + ? { message: Cause.pretty(cause), retryable: true }
286 + : { message: Cause.pretty(cause) }
287 + )
288 + );
289
290 /** `exit` as the runner receives it; see {@link runnerCause}. */
291 export const runnerExit = <A>(exit: Exit.Exit<A, unknown>): Exit.Exit<A, unknown> =>
ts/packages/cli/test/src/cli-main.test.ts
+6 -1
@@ -285,7 +285,12 @@ describe('reported tool execution failures', () => {
285 {
286 name: 'a Dashboard outage',
287 args: ['execute', 'HACKERNEWS_GET_ITEM', '-d', '{"id":1}'],
288 - stdout: { successful: false, error: expect.stringContaining('(HTTP 503)') },
288 + // The tool may have run before the Dashboard failed, so the result says to check first.
289 + stdout: {
290 + successful: false,
291 + error: expect.stringContaining('(HTTP 503)'),
292 + retry: 'check-first',
293 + },
294 },
295 {
296 name: 'a meta tool that reports a failure',
ts/packages/cli/test/src/commands/init.cmd.test.ts
+5 -3
@@ -1,6 +1,7 @@
1 import { describe, expect, layer } from '@effect/vitest';
2 import { Effect } from 'effect';
3 import { cli, TestLive, MockConsole } from 'test/__utils__';
4 +import { retryHint } from 'src/effects/retry-advice';
5 import { exitCodeOf } from 'test/__utils__/exit-code';
6 import { makeOrgProject } from 'test/__utils__/models/account';
7 import { redirectedTerminalUI } from 'test/__utils__/services/redirected-terminal-ui';
@@ -70,7 +71,7 @@ describe('CLI: composio dev init', () => {
71 const lines = yield* MockConsole.getLines({ stripAnsi: true });
72
73 expect(result._tag).toBe('Failure');
73 - expect(lines.slice(0, -1)).toEqual([
74 + expect(lines.slice(0, -2)).toEqual([
75 '-- composio dev init --',
76 'Could not fetch projects from the server.',
77 projectGuidance,
@@ -80,8 +81,9 @@ describe('CLI: composio dev init', () => {
81 '-- --',
82 ]);
83 // The command fails with the client's error after its guidance, which the invocation
83 - // reports as a defect.
84 - expect(lines.at(-1)).toContain('@composio/client/APIConnectionError');
84 + // reports as a defect, then says the request is safe to send again.
85 + expect(lines.at(-2)).toContain('@composio/client/APIConnectionError');
86 + expect(lines.at(-1)).toBe(retryHint('safe'));
87 })
88 );
89 });
ts/packages/cli/test/src/commands/tools/execute/tools.execute.transport.test.ts
+57 -1
@@ -3,10 +3,17 @@ import * as os from 'node:os';
3 import * as path from 'node:path';
4 import { describe, expect, it } from '@effect/vitest';
5 import { afterEach, beforeEach, vi } from 'vitest';
6 -import { APIConnectionError, APIError, type ComposioError } from '@composio/client/effect';
6 +import {
7 + APIConnectionError,
8 + APIConnectionTimeoutError,
9 + APIError,
10 + RateLimitError,
11 + type ComposioError,
12 +} from '@composio/client/effect';
13 import type { SessionExecuteResponse } from '@composio/client/resources/tool-router';
14 import { ConfigProvider, Effect, Exit, Fiber, Option, Schema } from 'effect';
15 import { TestClock } from 'effect/testing';
16 +import { TEMPORARY_FAILURE_EXIT_CODE } from 'src/effects/retry-advice';
17 import * as composioAccount from 'src/services/composio-account';
18 import * as consumerShortTermCache from 'src/services/consumer-short-term-cache';
19 import * as toolPermissions from 'src/services/tool-permissions';
@@ -19,6 +26,7 @@ import {
26 TestLive,
27 type DashboardTestRequest,
28 } from 'test/__utils__';
29 +import { exitCodeOf } from 'test/__utils__/exit-code';
30 import type { TestLiveInput } from 'test/__utils__/services/test-layer';
31
32 vi.mock('node:dns/promises', () => ({
@@ -536,6 +544,54 @@ describe('CLI: composio execute transport', () => {
544 })
545 );
546
547 + it.effect('says to check first when an execution timed out, since the tool may have run', () =>
548 + Effect.gen(function* () {
549 + const world = makeWorld({
550 + env: backendOnlyEnv,
551 + backendExecute: () =>
552 + Effect.fail(
553 + new APIConnectionTimeoutError({
554 + message: 'Request timed out.',
555 + method: 'POST',
556 + url: 'https://mock.invalid/api/v3.1/tool_router/session/{session_id}/execute',
557 + })
558 + ),
559 + });
560 +
561 + const { exit, lines } = yield* world.run(EXECUTE_GMAIL);
562 +
563 + expect(lastJson(lines)).toMatchObject({ successful: false, retry: 'check-first' });
564 + expect(exitCodeOf(exit)).toBe(1);
565 + // Sent once: the client never repeats an execution.
566 + expect(world.toolRouterCalls.filter(call => call.method === 'execute')).toHaveLength(1);
567 + })
568 + );
569 +
570 + it.effect('says a rate-limited execution is safe to run again and exits 75', () =>
571 + Effect.gen(function* () {
572 + const world = makeWorld({
573 + env: backendOnlyEnv,
574 + backendExecute: () =>
575 + Effect.fail(
576 + new RateLimitError({
577 + message: '429 Too many requests',
578 + method: 'POST',
579 + url: 'https://mock.invalid/api/v3.1/tool_router/session/{session_id}/execute',
580 + status: 429,
581 + requestId: 'req_rate',
582 + details: undefined,
583 + body: undefined,
584 + })
585 + ),
586 + });
587 +
588 + const { exit, lines } = yield* world.run(EXECUTE_GMAIL);
589 +
590 + expect(lastJson(lines)).toMatchObject({ successful: false, retry: 'safe' });
591 + expect(exitCodeOf(exit)).toBe(TEMPORARY_FAILURE_EXIT_CODE);
592 + })
593 + );
594 +
595 it.effect('reports a relayed wallet failure exactly as the backend transport does', () =>
596 Effect.gen(function* () {
597 const viaDashboard = makeWorld({
ts/packages/cli/test/src/commands/whoami.cmd.test.ts
+4 -2
@@ -3,6 +3,7 @@ import { assert, describe, expect, layer } from '@effect/vitest';
3 import { isUsageFailure } from 'src/commands/errors';
4 import { ConfigProvider, Effect } from 'effect';
5 import { cli, TestLive, MockConsole } from 'test/__utils__';
6 +import { retryHint, TEMPORARY_FAILURE_EXIT_CODE } from 'src/effects/retry-advice';
7 import { exitCodeOf } from 'test/__utils__/exit-code';
8 import { makeSessionInfo } from 'test/__utils__/models/account';
9 import { redirectedTerminalUI } from 'test/__utils__/services/redirected-terminal-ui';
@@ -132,14 +133,15 @@ describe('CLI: composio whoami', () => {
133 },
134 })
135 )('when the backend fails to answer', it => {
135 - it.effect('[Then] exits 1 with nothing on stdout and the failure on stderr', () =>
136 + it.effect('[Then] exits 75 with nothing on stdout and says it is safe to run again', () =>
137 Effect.gen(function* () {
138 const terminal = redirectedTerminalUI();
139 const exit = yield* Effect.exit(cli(['whoami']).pipe(Effect.provide(terminal.layer)));
140
140 - expect(exitCodeOf(exit)).toBe(1);
141 + expect(exitCodeOf(exit)).toBe(TEMPORARY_FAILURE_EXIT_CODE);
142 expect(terminal.stdout()).toBe('');
143 expect(terminal.stderr()).toContain('Internal Server Error');
144 + expect(terminal.stderr()).toContain(retryHint('safe'));
145 })
146 );
147 });
ts/packages/cli/test/src/effects/handle-http-error.test.ts
+60 -5
@@ -5,12 +5,15 @@ import {
5 BadRequestError as ClientBadRequestError,
6 ConfigurationError as ClientConfigurationError,
7 DecodeError as ClientDecodeError,
8 + InternalServerError as ClientInternalServerError,
9 + RateLimitError as ClientRateLimitError,
10 type ComposioError,
11 } from '@composio/client/effect';
12 import { describe, expect, it } from '@effect/vitest';
13 import { ConfigProvider, Effect } from 'effect';
14 import { handleClientApiError } from 'src/effects/handle-http-error';
15 import { ReportedFailure } from 'src/effects/report-failure';
16 +import { retryHint, TEMPORARY_FAILURE_EXIT_CODE } from 'src/effects/retry-advice';
17 import { CLIENT_API_ERROR_TAGS } from 'src/services/composio-errors';
18 import { TerminalUI } from 'src/services/terminal-ui';
19 import { exitCodeOf } from 'test/__utils__/exit-code';
@@ -88,13 +91,13 @@ describe('handleClientApiError', () => {
91 it.effect.each([
92 new ClientAPIConnectionError({
93 message: 'Connection error.',
91 - method: 'GET',
94 + method: 'POST',
95 url,
96 reason: 'TransportError',
97 description: 'fetch failed',
98 }),
96 - new ClientAPIConnectionTimeoutError({ message: 'Request timed out.', method: 'GET', url }),
97 - ])('prints the fallback message for $_tag', error =>
99 + new ClientAPIConnectionTimeoutError({ message: 'Request timed out.', method: 'POST', url }),
100 + ])('prints the fallback message for $_tag of a request that may have taken effect', error =>
101 Effect.gen(function* () {
102 const { ui, lines } = recordingUI();
103
@@ -108,6 +111,58 @@ describe('handleClientApiError', () => {
111 })
112 );
113
114 + it.effect.each([
115 + new ClientAPIConnectionError({
116 + message: 'Connection error.',
117 + method: 'GET',
118 + url,
119 + reason: 'TransportError',
120 + description: 'fetch failed',
121 + }),
122 + new ClientAPIConnectionTimeoutError({ message: 'Request timed out.', method: 'GET', url }),
123 + new ClientInternalServerError({
124 + message: '503 Service Unavailable',
125 + method: 'GET',
126 + url,
127 + status: 503,
128 + requestId: undefined,
129 + details: undefined,
130 + body: undefined,
131 + }),
132 + ])('says a $_tag of a GET is safe to run again and exits 75', error =>
133 + Effect.gen(function* () {
134 + const { ui, lines } = recordingUI();
135 +
136 + const exit = yield* Effect.exit(handleClientApiError(ui, options)(error));
137 +
138 + expect(lines).toStrictEqual([
139 + 'stderr: Failed to fetch auth config "ac_missing".',
140 + `stderr: ${retryHint('safe')}`,
141 + ]);
142 + expect(exitCodeOf(exit)).toBe(TEMPORARY_FAILURE_EXIT_CODE);
143 + })
144 + );
145 +
146 + it.effect('says a rate-limited POST is safe to run again, since it did not run', () =>
147 + Effect.gen(function* () {
148 + const { ui, lines } = recordingUI();
149 + const rateLimited = new ClientRateLimitError({
150 + message: '429 Too many requests',
151 + method: 'POST',
152 + url,
153 + status: 429,
154 + requestId: undefined,
155 + details: { message: 'Too many requests', code: 429, slug: 'RateLimited', status: 429 },
156 + body: undefined,
157 + });
158 +
159 + const exit = yield* Effect.exit(handleClientApiError(ui, options)(rateLimited));
160 +
161 + expect(lines).toStrictEqual(['stderr: Too many requests', `stderr: ${retryHint('safe')}`]);
162 + expect(exitCodeOf(exit)).toBe(TEMPORARY_FAILURE_EXIT_CODE);
163 + })
164 + );
165 +
166 it.effect('names the operation and request id of a decode failure and suggests an upgrade', () =>
167 Effect.gen(function* () {
168 const { ui, lines } = recordingUI();
@@ -181,12 +236,12 @@ describe('Effect.catchTag(CLIENT_API_ERROR_TAGS, handleClientApiError(...))', ()
236 clientDecodeError,
237 new ClientAPIConnectionError({
238 message: 'Connection error.',
184 - method: 'GET',
239 + method: 'POST',
240 url,
241 reason: 'TransportError',
242 description: 'fetch failed',
243 }),
189 - new ClientAPIConnectionTimeoutError({ message: 'Request timed out.', method: 'GET', url }),
244 + new ClientAPIConnectionTimeoutError({ message: 'Request timed out.', method: 'POST', url }),
245 ])('reports $_tag and fails already reported', error =>
246 Effect.gen(function* () {
247 const { ui, lines } = recordingUI();
ts/packages/cli/test/src/effects/retry-advice.test.ts new
+137
@@ -0,0 +1,137 @@
1 +import {
2 + APIConnectionError,
3 + APIConnectionTimeoutError,
4 + APIError,
5 + BadRequestError,
6 + ConflictError,
7 + DecodeError,
8 + InternalServerError,
9 + RateLimitError,
10 + type APIErrorFields,
11 +} from '@composio/client/effect';
12 +import { describe, expect, it } from '@effect/vitest';
13 +import { Option } from 'effect';
14 +import { requestError } from 'src/effects/request-error';
15 +import { retryAdviceFor } from 'src/effects/retry-advice';
16 +import { DashboardToolExecutionError } from 'src/services/dashboard-tool-execution';
17 +
18 +const url = 'https://backend.composio.dev/api/v3.1/tools/{tool_slug}';
19 +
20 +const status = (method: string, code: number): APIErrorFields => ({
21 + message: `${code}`,
22 + method,
23 + url,
24 + status: code,
25 + requestId: undefined,
26 + details: undefined,
27 + body: undefined,
28 +});
29 +
30 +const connectionError = (method: string, reason = 'TransportError') =>
31 + new APIConnectionError({
32 + message: 'Connection error.',
33 + method,
34 + url,
35 + reason,
36 + description: undefined,
37 + });
38 +
39 +const timeout = (method: string) =>
40 + new APIConnectionTimeoutError({ message: 'Request timed out.', method, url });
41 +
42 +class WrappingError extends requestError('test/WrappingError') {}
43 +
44 +describe('retryAdviceFor', () => {
45 + it.each([
46 + { name: 'a GET that timed out', error: timeout('GET'), advice: 'safe' },
47 + { name: 'a GET whose connection failed', error: connectionError('GET'), advice: 'safe' },
48 + {
49 + name: 'a GET answered 503',
50 + error: new InternalServerError(status('GET', 503)),
51 + advice: 'safe',
52 + },
53 + {
54 + name: 'a DELETE answered 502',
55 + error: new InternalServerError(status('DELETE', 502)),
56 + advice: 'safe',
57 + },
58 + { name: 'a GET answered 408', error: new APIError(status('GET', 408)), advice: 'safe' },
59 + { name: 'a POST answered 429', error: new RateLimitError(status('POST', 429)), advice: 'safe' },
60 + { name: 'a POST that timed out', error: timeout('POST'), advice: 'check-first' },
61 + {
62 + name: 'a POST whose connection failed',
63 + error: connectionError('POST'),
64 + advice: 'check-first',
65 + },
66 + {
67 + name: 'a PATCH answered 500',
68 + error: new InternalServerError(status('PATCH', 500)),
69 + advice: 'check-first',
70 + },
71 + ])('[Given] $name [Then] the advice is $advice', ({ error, advice }) => {
72 + expect(retryAdviceFor(error)).toStrictEqual(Option.some(advice));
73 + });
74 +
75 + it.each([
76 + { name: 'a 400', error: new BadRequestError(status('GET', 400)) },
77 + { name: 'a 409', error: new ConflictError(status('GET', 409)) },
78 + {
79 + name: 'a read whose response failed decoding',
80 + error: new DecodeError({
81 + message: 'The response body is not valid JSON.',
82 + method: 'GET',
83 + url,
84 + status: 200,
85 + requestId: undefined,
86 + operation: 'tools.retrieve',
87 + issues: [],
88 + }),
89 + },
90 + { name: 'a redirect the client refused', error: connectionError('GET', 'TooManyRedirects') },
91 + { name: 'an error that is not a request', error: new Error('boom') },
92 + ])('[Given] $name [Then] there is no advice', ({ error }) => {
93 + expect(retryAdviceFor(error)).toStrictEqual(Option.none());
94 + });
95 +
96 + it('[Given] an execution whose response failed decoding [Then] it may have run', () => {
97 + const error = new DecodeError({
98 + message: 'The response body is not valid JSON.',
99 + method: 'POST',
100 + url,
101 + status: 200,
102 + requestId: undefined,
103 + operation: 'toolRouter.session.execute',
104 + issues: [],
105 + });
106 +
107 + expect(retryAdviceFor(error)).toStrictEqual(Option.some('check-first'));
108 + });
109 +
110 + it('[Given] a command error that keeps the request failure as its cause [Then] it reads the cause', () => {
111 + const wrapped = new WrappingError({ message: 'Failed to fetch.', cause: timeout('GET') });
112 +
113 + expect(retryAdviceFor(wrapped)).toStrictEqual(Option.some('safe'));
114 + });
115 +
116 + it.each([
117 + { reason: 'request', status: undefined, advice: Option.some('check-first') },
118 + { reason: 'timeout', status: undefined, advice: Option.some('check-first') },
119 + { reason: 'response', status: 503, advice: Option.some('check-first') },
120 + { reason: 'response', status: 429, advice: Option.some('safe') },
121 + { reason: 'dashboard', status: 429, advice: Option.some('safe') },
122 + { reason: 'dashboard', status: 500, advice: Option.some('check-first') },
123 + { reason: 'dashboard', status: 400, advice: Option.none() },
124 + { reason: 'unauthorized', status: 401, advice: Option.none() },
125 + ] as const)(
126 + '[Given] a Dashboard execution that failed with $reason ($status) [Then] the advice is $advice',
127 + ({ reason, status: httpStatus, advice }) => {
128 + const error = new DashboardToolExecutionError({
129 + reason,
130 + message: 'failed',
131 + ...(httpStatus === undefined ? {} : { status: httpStatus }),
132 + });
133 +
134 + expect(retryAdviceFor(error)).toStrictEqual(advice);
135 + }
136 + );
137 +});
ts/packages/cli/test/src/invocation/report-invocation-failure.test.ts
+38
@@ -2,7 +2,10 @@ import { describe, expect, it } from '@effect/vitest';
2 import { Cause, Console, Effect, Exit, Layer } from 'effect';
3 import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
4 import * as BunPath from '@effect/platform-bun/BunPath';
5 +import { APIConnectionTimeoutError } from '@composio/client/effect';
6 import { ReportedFailure } from 'src/effects/report-failure';
7 +import { requestError } from 'src/effects/request-error';
8 +import { retryHint, TEMPORARY_FAILURE_EXIT_CODE } from 'src/effects/retry-advice';
9 import { reportInvocationFailure } from 'src/invocation/invocation';
10 import { MockConsole } from 'test/__utils__';
11 import { exitCodeOf } from 'test/__utils__/exit-code';
@@ -61,4 +64,39 @@ describe('reportInvocationFailure', () => {
64 expect(stderr[0]).toContain('boom');
65 })
66 );
67 +
68 + it.effect('[Given] a request failure safe to send again [Then] it says so and exits 75', () =>
69 + Effect.gen(function* () {
70 + class FetchError extends requestError('test/FetchError') {}
71 + const failure = new FetchError({
72 + message: 'Failed to fetch toolkits.',
73 + cause: new APIConnectionTimeoutError({
74 + message: 'Request timed out.',
75 + method: 'GET',
76 + url: 'https://backend.composio.dev/api/v3.1/toolkits',
77 + }),
78 + });
79 +
80 + const { exit, stderr } = yield* report(Cause.fail(failure));
81 +
82 + expect(failureOf(exit)).toBe(failure);
83 + expect(exitCodeOf(exit)).toBe(TEMPORARY_FAILURE_EXIT_CODE);
84 + expect(stderr.at(-1)).toBe(retryHint('safe'));
85 + })
86 + );
87 +
88 + it.effect('[Given] a POST that timed out [Then] it exits 1 with no retry advice', () =>
89 + Effect.gen(function* () {
90 + const failure = new APIConnectionTimeoutError({
91 + message: 'Request timed out.',
92 + method: 'POST',
93 + url: 'https://backend.composio.dev/api/v3.1/auth_configs',
94 + });
95 +
96 + const { exit, stderr } = yield* report(Cause.fail(failure));
97 +
98 + expect(exitCodeOf(exit)).toBe(1);
99 + expect(stderr.join('\n')).not.toContain(retryHint('safe'));
100 + })
101 + );
102 });