Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Command data and lifecycle
Producing and consuming data
TerminalUI owns terminal output and prompts. Each stream reports whether it is attached to a terminal through isTTY. The three stream capabilities are independent.
| Concern | Current behavior |
|---|---|
| Machine data | ui.output(text) writes a newline to redirected stdout. Visible TTY stdout stays silent unless { force: true } is set. |
| Human decoration | ui.log, note, intro, outro, and spinners use stderr and disappear when stderr is not a TTY. |
| Persistent diagnostics | ui.error(text) writes to stderr even when redirected. It also carries protocol metadata such as RUN_LOG_FILE. |
| Prompts | canPrompt requires both stdin and stderr to be TTYs. Piping stdout alone does not disable prompts. |
A command serializes its machine result before calling output. A command without a separate human renderer uses force: true when its data must remain visible on a terminal. Output consumers must follow that command's contract. proxy can return text or JSON, while listeners emit a stream rather than one JSON document.
resolveExplicitTextInput resolves an input flag: a literal string, @file, or - / @- to read stdin to end of input. With no flag it returns undefined and never reads stdin, so a command such as proxy or listen cannot wait on a pipe it was handed. composio execute alone also reads JSON piped without -d (resolveInput in tools.execute.arguments.ts) and fails when the pipe sends nothing within PIPED_STDIN_SILENCE_TIMEOUT. The command validates supplied data with its own parser and schema before using it.
Stdin.readAll buffers size-limited input until end of input (EOF). It is not a reader for an unlimited event stream. A producer that never closes stdin keeps the command waiting. TestLive({ stdin: { isTTY: false, data: '...' } }) supplies finite test input without consuming the test runner's stdin.
Commands that do more than request and print
| Command | Behavior that changes the implementation approach |
|---|---|
listen |
A realtime subscription can run indefinitely without --timeout or --max-events. It writes payload files and an events.jsonl index, and emits status and event lines. --stream also emits inline payload values. |
dev triggers listen |
A long-lived listener can append to an output file or forward events to a URL. Each sink can fail independently. |
run |
A child process inherits stdin, stdout, and stderr. Arbitrary script output is not a CLI JSON result. The command announces a log path on stderr and preserves the child's exit outcome. |
proxy |
A successful proxy operation can contain an upstream HTTP error response. The command's exit code alone does not establish an upstream success status. |
The listen handler uses scoped event fibers and acquireUseRelease for temporary-trigger cleanup. It does not collect the full event stream into memory. Its in-memory event-id set still grows with the subscription, so an agent session needs a bounded duration or event count.
Sink failure handling counts failures and continues by default. The stop summary remains visible on redirected stderr. --fail-fast stops on the first sink failure and exits 1. A clean listener exit therefore does not prove every event was saved or forwarded. On a count or timeout stop, accepted event work gets a bounded drain. A signal stop interrupts active event fibers before release, so it does not guarantee that every accepted write completed.
Ctrl+C, Ctrl+D and cleanup
The runner owns SIGINT, SIGTERM, and SIGHUP. Handlers cooperate through ShutdownSignal. Resource cleanup belongs in scoped Effects and finalizers.
| Situation | Result |
|---|---|
| Ctrl+C interrupts a normal command | An interruption-only outcome after SIGINT exits 130. SIGTERM and SIGHUP use 143 and 129. |
| A subscribed listener receives Ctrl+C or SIGTERM | It cooperates and normally exits 0 after release. Before subscription confirmation, interruption still uses 130 or 143. |
run receives a stop signal |
It forwards the signal to its child process group and mirrors how the child ends. A child that handles the signal can exit 0. |
| A second signal arrives, or shutdown exceeds 10 seconds | The runner forces termination. Finalizers are not guaranteed to complete. |
| A finite stdin read receives EOF | Stdin.readAll() returns the buffered input. In a Unix terminal in cooked mode, Ctrl+D on an empty input line produces EOF. It is not a process-wide stop signal. |
| Clack reports prompt cancellation | confirm returns false. select returns the first option. Ctrl+D has no CLI-wide cancellation contract in raw prompts and is not a substitute for Ctrl+C. |
When prompting is unavailable, confirm returns its configured default, which is true if omitted. select returns the first option. A handler must not treat either fallback as a person's explicit approval. Destructive commands need an explicit noninteractive policy, as in connections remove --yes.
Recovery for agents
A parsed, authenticated invocation can still fail after a remote action took effect. Idempotent request options enable retries only for calls known to be safe to repeat. An agent checks remote state before repeating a create, delete, execution, or proxy action after a timeout or interruption.
A recovery flow keeps stdout and stderr separate, inspects the exit outcome, and applies the command's output contract. A nonzero exit can still accompany useful execution JSON. A zero listener exit can accompany sink-failure diagnostics. For run, the child script defines the meaning of its output and exit status.
After a listener is force-killed, temporary-trigger cleanup and accepted writes may be incomplete. Existing payload files and the stop diagnostics are evidence, not proof of complete delivery. Prompt defaults, EOF, and a clean shutdown do not authorize an agent to infer that a requested side effect succeeded.