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

Harden `composio run` subagent output and parallel discovery (#3051)

## Summary - Hardened `composio run` subagent execution so structured output is validated more reliably and logfile paths are propagated back to callers. - Added an MCP-based structured output helper and bundled it with the CLI run companion modules. - Improved permission handling and read-access root propagation for subagent sessions. - Updated CLI skill docs to cover top-level parallel execution and multi-query search usage. - Added/updated tests around `run` command behavior and ACP subagent flows. ## Testing - `Not run` (not requested in this context). - Existing/updated test coverage was added for `ts/packages/cli/test/src/commands/run.cmd.test.ts`. - Existing/updated test coverage was added for `ts/packages/cli/test/src/services/run-subagent-acp.test.ts`.

Rahul Tarak committed Mar 27, 2026 at 06:04 UTC 2a0d9552299c8acd9570298a6f95c52efcbfef3e
3 files changed +51 -6
ts/packages/cli/skills/composio-cli/SKILL.md
+18 -5
@@ -8,9 +8,10 @@ description: Help users operate the published Composio CLI to find the right too
8 ## Default Workflow
9
10 1. Start with `composio execute <slug>` whenever the slug is known.
11 -2. If `execute` says the toolkit is not connected, run `composio link <toolkit>` and retry.
12 -3. If the arguments are unclear, run `composio execute <slug> --get-schema` or `--dry-run` before guessing.
13 -4. Reach for `composio search "<task>"` only when the slug is unknown.
11 +2. If several independent tool calls must happen at once, use `composio execute -p/--parallel` with repeated `<slug> -d <json>` groups.
12 +3. If `execute` says the toolkit is not connected, run `composio link <toolkit>` and retry.
13 +4. If the arguments are unclear, run `composio execute <slug> --get-schema` or `--dry-run` before guessing.
14 +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.
15
16 ## `execute` — Run A Tool
17
@@ -37,14 +38,24 @@ composio execute GITHUB_CREATE_AN_ISSUE -d @issue.json
38 cat issue.json | composio execute GITHUB_CREATE_AN_ISSUE -d -
39 ```
40
41 +Run independent tool calls in parallel:
42 +
43 +```bash
44 +composio execute --parallel \
45 + GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \
46 + GITHUB_CREATE_AN_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'
47 +```
48 +
49 ## `search` — Find The Slug
50
51 ```bash
52 composio search "create a github issue"
53 composio search "send an email" --toolkits gmail
54 +composio search "send an email" "create a github issue"
55 +composio search "my emails" "my github issues" --toolkits gmail,github
56 ```
57
47 -Read the returned slugs, choose the best match, and move back to `execute`.
58 +Use multiple quoted queries when the user is exploring more than one task or a small cross-app workflow. Read the returned slugs, choose the best match, and move back to `execute`.
59
60 ## `link` — Connect An Account
61
@@ -81,6 +92,8 @@ composio run '
92 '
93 ```
94
95 +Use top-level `execute --parallel` when the user just needs a few independent tool calls and does not need script logic, loops, or output plumbing.
96 +
97 Fan out with `Promise.all`:
98
99 ```bash
@@ -106,7 +119,7 @@ composio run --logs-off '
119 '
120 ```
121
109 -For more patterns — `proxy()` inside scripts, `search()` inside scripts, mixed `execute()` + `proxy()`, and `--dry-run`/`--debug` flags — load [references/power-user-examples.md](references/power-user-examples.md).
122 +For more patterns — multi-query top-level `search`, `proxy()` inside scripts, mixed `execute()` + `proxy()`, and `--dry-run`/`--debug` flags — load [references/power-user-examples.md](references/power-user-examples.md).
123
124 ## Auth
125
ts/packages/cli/skills/composio-cli/references/power-user-examples.md
+14
@@ -20,6 +20,14 @@ composio run '
20 '
21 ```
22
23 +If the user does not need script logic and just wants a few independent calls, prefer top-level parallel execute instead:
24 +
25 +```bash
26 +composio execute --parallel \
27 + GMAIL_FETCH_EMAILS -d '{ max_results: 2 }' \
28 + GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'
29 +```
30 +
31 ## Use `Promise.all` To Fan Out
32
33 Fetch from multiple services at once:
@@ -58,6 +66,12 @@ composio run '
66 '
67 ```
68
69 +Batch related discovery work with multiple queries when it keeps the workflow simpler:
70 +
71 +```bash
72 +composio search "send an email" "create a github issue" --toolkits gmail,github
73 +```
74 +
75 ## Use `subAgent()` With `z` And `result.prompt()`
76
77 Turn a tool result into structured output:
ts/packages/cli/skills/composio-cli/references/troubleshooting.md
+19 -1
@@ -66,9 +66,10 @@ Fix:
66 ```bash
67 composio search "create a github issue"
68 composio search "send an email" --toolkits gmail
69 +composio search "send an email" "create a github issue"
70 ```
71
71 -Use `composio tools list <toolkit>` only when the user already knows the toolkit and needs to browse the available slugs manually.
72 +Use multiple queries in one `search` call when the user is exploring several related tasks at once. Use `composio tools list <toolkit>` only when the user already knows the toolkit and needs to browse the available slugs manually.
73
74 ## Confusion About Required Inputs
75
@@ -86,6 +87,23 @@ composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{
87
88 Use `composio tools info <slug>` only when the user wants a compact summary of a known slug and the `execute --get-schema` output is still not enough.
89
90 +## Several Independent Tool Calls
91 +
92 +Symptoms:
93 +
94 +- the user wants to run multiple unrelated tools in one step
95 +- the user is about to write a script only to execute a few independent calls
96 +
97 +Fix:
98 +
99 +```bash
100 +composio execute --parallel \
101 + GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \
102 + GITHUB_CREATE_AN_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'
103 +```
104 +
105 +Escalate to `composio run` only when the user needs control flow, loops, `Promise.all`, `search()` inside a script, `proxy()`, or `subAgent()`.
106 +
107 ## `tools info` And `tools list` Are Fallbacks
108
109 Treat these commands as secondary inspection tools: