@devries-cameron20 / composio Mirror · read-only
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

next
ts 417 lines 15.1 KB
Raw
1 import * as fs from 'node:fs';
2 import * as path from 'node:path';
3 import { CLI_EXPERIMENTAL_FEATURES } from '../../src/experimental-features';
4 import { composioDevReference } from './references/composio-dev';
5 import { powerUserExamplesReference } from './references/power-user-examples';
6 import { troubleshootingReference } from './references/troubleshooting';
7 import {
8 isEnabledForBuild,
9 renderReferenceDocument,
10 resolveSkillBuildContext,
11 validateReferenceDocument,
12 type SkillBuildContext,
13 type SkillFeatureFlag,
14 type SkillReleaseChannel,
15 } from './reference-schema';
16
17 // Re-exported for scripts/build-skills.ts, which maps the --channel CLI
18 // flag onto the build pipeline's channel type.
19 export type { SkillReleaseChannel };
20
21 type SkillFlag = {
22 description: string;
23 name: string;
24 features?: SkillFeatureFlag[];
25 };
26
27 type SkillExample = {
28 code: string;
29 description?: string;
30 features?: SkillFeatureFlag[];
31 };
32
33 type SkillCommand = {
34 id: string;
35 title: string;
36 summary?: string;
37 features?: SkillFeatureFlag[];
38 intro?: string[];
39 flags?: SkillFlag[];
40 examples?: SkillExample[];
41 notes?: string[];
42 extraBody?: Array<{
43 features?: SkillFeatureFlag[];
44 markdown: string;
45 }>;
46 };
47
48 const sourceAssetsDir = path.resolve(import.meta.dirname, './assets');
49
50 const frontmatter = {
51 name: 'composio-cli',
52 description:
53 'Help users operate the published Composio CLI to find the right tool, connect accounts, inspect schemas, execute tools, subscribe to trigger events with `composio listen`, script workflows with `composio run`, and call authenticated app APIs with `composio proxy`. Use when the user asks how to do something with `composio`, wants to run a known tool slug, needs to discover a slug with `composio search`, fix a missing connection with `composio link`, inspect tool inputs with `--get-schema` or `--dry-run`, troubleshoot top-level CLI flows, or explicitly needs `composio dev` guidance.',
54 };
55
56 const commands: SkillCommand[] = [
57 {
58 id: 'execute',
59 title: '`execute` - Run A Tool',
60 summary: 'Use `execute` when the tool slug is already known.',
61 flags: [
62 {
63 name: '`--get-schema`',
64 description: 'Inspect required arguments without executing the tool.',
65 },
66 {
67 name: '`--dry-run`',
68 description: 'Preview the request shape without performing the action.',
69 },
70 {
71 name: '`--file`',
72 description:
73 'Inject a local file path into a tool that exposes exactly one uploadable file argument.',
74 },
75 {
76 name: '`--parallel`',
77 description: 'Execute multiple independent tool calls in the same invocation.',
78 },
79 {
80 name: '`--account`',
81 description:
82 'Select which connected account to use by alias, word_id, or account id when multiple accounts exist for the same toolkit.',
83 },
84 ],
85 examples: [
86 {
87 code: "composio execute GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'",
88 },
89 {
90 description: 'Inspect required inputs without executing',
91 code: 'composio execute GITHUB_CREATE_AN_ISSUE --get-schema',
92 },
93 {
94 description: 'Preview safely',
95 code: 'composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d \'{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }\'',
96 },
97 {
98 description: 'Pass data from a file or stdin',
99 code: 'composio execute GITHUB_CREATE_AN_ISSUE -d @issue.json\ncat issue.json | composio execute GITHUB_CREATE_AN_ISSUE -d -',
100 },
101 {
102 description: 'Upload a local file',
103 code: 'composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \\\n --file ./image.png \\\n -d \'{ channels: "C123" }\'',
104 },
105 {
106 description: 'Run independent tool calls in parallel',
107 code: 'composio execute --parallel \\\n GMAIL_SEND_EMAIL -d \'{ recipient_email: "a@b.com", subject: "Hi" }\' \\\n GITHUB_CREATE_AN_ISSUE -d \'{ owner: "acme", repo: "app", title: "Bug" }\'',
108 },
109 ],
110 notes: [
111 '`--file` only works when the tool exposes a single uploadable file input. Otherwise use explicit `-d` JSON.',
112 ],
113 },
114 {
115 id: 'search',
116 title: '`search` - Find The Slug',
117 summary: 'Use `search` only when the tool slug is not already known.',
118 examples: [
119 {
120 code: 'composio search "create a github issue"\ncomposio search "send an email" --toolkits gmail\ncomposio search "send an email" "create a github issue"\ncomposio search "my emails" "my github issues" --toolkits gmail,github',
121 },
122 ],
123 notes: [
124 'Batch related discovery work into one `search` invocation, then move back to `execute` once the correct slugs are known.',
125 ],
126 },
127 {
128 id: 'link',
129 title: '`link` - Connect An Account',
130 summary:
131 'Use `link` when `execute` reports that a toolkit is not connected, or when the user explicitly wants to authorize an account.',
132 examples: [
133 {
134 code: 'composio link gmail\ncomposio link googlecalendar --no-browser --no-wait',
135 },
136 ],
137 flags: [
138 {
139 name: '`--no-wait`',
140 description:
141 'Print the authorization URL as JSON (`redirect_url`) and return at once instead of waiting for the authorization.',
142 },
143 {
144 name: '`--alias`',
145 description:
146 'Assign an alias to the connected account. Required when creating an additional account for the same toolkit.',
147 },
148 ],
149 notes: [
150 "When the user has to open the page themselves, run `link` with `--no-wait`, show them the `redirect_url`, and wait for them to say they approved. Without `--no-wait` the command blocks until the authorization completes, so the URL reaches the user only if they can see the command's output.",
151 'Retry the original `execute` command after linking succeeds.',
152 ],
153 },
154 {
155 id: 'listen',
156 title: '`listen` - Subscribe To Trigger Events',
157 features: [CLI_EXPERIMENTAL_FEATURES.LISTEN],
158 summary:
159 'Use `listen` for temporary trigger subscriptions in consumer projects, especially when background agents should consume new event payloads from artifact files.',
160 examples: [
161 {
162 code: "composio listen GMAIL_NEW_GMAIL_MESSAGE\ncomposio listen SLACK_CHANNEL_MESSAGE_RECEIVED -p '{ trigger_config: { channel_id: \"C123\" } }'\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE --stream\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE --stream '.data.threadId'\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 5m\ncomposio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --max-events 5",
163 },
164 ],
165 flags: [
166 {
167 name: '`-p/--params`',
168 description:
169 'Provide only trigger config fields; connected account resolution is automatic.',
170 },
171 {
172 name: '`--stream`',
173 description: 'Print events inline, optionally narrowed to a JSON path.',
174 },
175 {
176 name: '`--timeout` and `--max-events`',
177 description: 'Stop long-running listeners cleanly.',
178 },
179 {
180 name: '`--fail-fast`',
181 description:
182 'Stop at the first event that fails to save and exit 1, so a bounded run that lost events is not a success.',
183 },
184 {
185 name: '`--account`',
186 description: 'Select which connected account to use by alias, word_id, or account id.',
187 },
188 ],
189 notes: [
190 '`composio artifacts cwd` shows the current artifact root when saved payloads need inspection.',
191 ],
192 },
193 {
194 id: 'proxy',
195 title: '`proxy` - Raw API Access',
196 summary:
197 'Use `proxy` when a toolkit supports a raw API operation that is easier than finding a dedicated tool slug.',
198 examples: [
199 {
200 code: 'composio proxy https://api.github.com/user --toolkit github --account work --method GET </dev/null',
201 },
202 ],
203 flags: [
204 {
205 name: '`--account`',
206 description: 'Select which connected account to use by alias, word_id, or account id.',
207 },
208 ],
209 },
210 {
211 id: 'run',
212 title: '`run` - Scripting and Programmatic Workflows',
213 summary:
214 'For programmatic calls, loops, output plumbing, or anything beyond a single tool call, prefer `composio run`.',
215 intro: [
216 '`composio run` executes an inline ESM JavaScript/TypeScript snippet with authenticated `execute()`, `search()`, and `proxy()` pre-injected. No SDK setup required.',
217 ],
218 examples: [
219 {
220 description: 'Chain multiple tools',
221 code: 'composio run \'\n const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");\n const emails = await execute("GMAIL_FETCH_EMAILS", { max_results: 1 });\n console.log({ login: me.data.login, fetchedEmails: !!emails.data });\n\'',
222 },
223 {
224 description: 'Fan out with Promise.all',
225 code: 'composio run \'\n const [me, emails] = await Promise.all([\n execute("GITHUB_GET_THE_AUTHENTICATED_USER"),\n execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),\n ]);\n console.log({ login: me.data.login, emailCount: emails.data.messages?.length });\n\'',
226 },
227 ],
228 notes: [
229 'Use top-level `execute --parallel` instead when the user only needs a few independent tool calls and does not need script logic.',
230 ],
231 },
232 {
233 id: 'auth',
234 title: 'Auth',
235 examples: [
236 {
237 code: 'composio whoami # check current session\ncomposio login # authenticate if whoami fails',
238 },
239 ],
240 },
241 ];
242
243 const defaultWorkflow = (build: SkillBuildContext) => {
244 const lines = [
245 '1. Start with `composio execute <slug>` whenever the slug is known.',
246 '2. If several independent tool calls must happen at once, use `composio execute -p/--parallel` with repeated `<slug> -d <json>` groups.',
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(
255 '7. If the CLI build enables the experimental `listen` feature, use it for temporary consumer-project trigger subscriptions.'
256 );
257 }
258
259 return lines;
260 };
261
262 const referenceDocuments = [
263 composioDevReference,
264 powerUserExamplesReference,
265 troubleshootingReference,
266 ] as const;
267
268 const renderExample = (example: SkillExample) => {
269 const lines = [];
270
271 if (example.description) {
272 lines.push(example.description + ':');
273 }
274
275 lines.push('```bash', example.code, '```');
276 return lines.join('\n');
277 };
278
279 const renderCommand = (build: SkillBuildContext, command: SkillCommand) => {
280 const lines: string[] = [`## ${command.title}`];
281
282 if (command.summary) {
283 lines.push('', command.summary);
284 }
285
286 for (const intro of command.intro ?? []) {
287 lines.push('', intro);
288 }
289
290 const examples = (command.examples ?? []).filter(example => isEnabledForBuild(build, example));
291 if (examples.length > 0) {
292 for (const example of examples) {
293 lines.push('', renderExample(example));
294 }
295 }
296
297 const flags = (command.flags ?? []).filter(flag => isEnabledForBuild(build, flag));
298 if (flags.length > 0) {
299 lines.push('', 'Key flags:');
300 for (const flag of flags) {
301 lines.push(`- ${flag.name}: ${flag.description}`);
302 }
303 }
304
305 for (const note of command.notes ?? []) {
306 lines.push('', `- ${note}`);
307 }
308
309 for (const extra of (command.extraBody ?? []).filter(block => isEnabledForBuild(build, block))) {
310 lines.push('', extra.markdown);
311 }
312
313 return lines.join('\n');
314 };
315
316 export const renderComposioCliSkill = (
317 channel: SkillReleaseChannel,
318 featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>>
319 ) => {
320 const build = resolveSkillBuildContext(channel, featureOverrides);
321 const lines: string[] = [
322 '---',
323 `name: ${frontmatter.name}`,
324 `description: ${frontmatter.description}`,
325 '---',
326 '',
327 '<!-- AUTO-GENERATED: edit skills-src/composio-cli/index.ts and rebuild -->',
328 `<!-- release-channel: ${channel} -->`,
329 '',
330 '# Composio CLI',
331 '',
332 '## Default Workflow',
333 '',
334 ...defaultWorkflow(build),
335 ];
336
337 const enabledCommands = commands.filter(command => isEnabledForBuild(build, command));
338 for (const command of enabledCommands) {
339 lines.push('', renderCommand(build, command));
340 }
341
342 lines.push(
343 '',
344 '## Escalate Only When Needed',
345 '',
346 'If the user is stuck on top-level commands or needs fallback inspection commands, load [references/troubleshooting.md](references/troubleshooting.md).',
347 '',
348 'If the user explicitly asks about developer projects, auth configs, connected accounts, triggers, logs, orgs, or projects, load [references/composio-dev.md](references/composio-dev.md). `composio dev` is not the default end-user path. In a developer project, run tools with `composio dev playground-execute`, not `composio execute`.'
349 );
350
351 return lines.join('\n') + '\n';
352 };
353
354 export const renderReferenceFiles = (
355 channel: SkillReleaseChannel,
356 featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>>
357 ) => {
358 const build = resolveSkillBuildContext(channel, featureOverrides);
359 return Object.fromEntries(
360 referenceDocuments.map(document => [
361 `${document.slug}.md`,
362 renderReferenceDocument(document, build),
363 ])
364 );
365 };
366
367 export const validateSkillSources = () => referenceDocuments.flatMap(validateReferenceDocument);
368
369 const copyDir = (sourceDir: string, targetDir: string) => {
370 fs.mkdirSync(targetDir, { recursive: true });
371 for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
372 const sourcePath = path.join(sourceDir, entry.name);
373 const targetPath = path.join(targetDir, entry.name);
374
375 if (entry.isDirectory()) {
376 copyDir(sourcePath, targetPath);
377 continue;
378 }
379
380 fs.copyFileSync(sourcePath, targetPath);
381 }
382 };
383
384 export const buildComposioCliSkill = ({
385 channel,
386 outputRoot,
387 featureOverrides,
388 }: {
389 channel: SkillReleaseChannel;
390 outputRoot: string;
391 featureOverrides?: Partial<Record<SkillFeatureFlag, boolean>>;
392 }) => {
393 const skillOutputDir = path.join(outputRoot, 'composio-cli');
394 fs.rmSync(skillOutputDir, { recursive: true, force: true });
395 fs.mkdirSync(skillOutputDir, { recursive: true });
396
397 fs.writeFileSync(
398 path.join(skillOutputDir, 'SKILL.md'),
399 renderComposioCliSkill(channel, featureOverrides),
400 'utf8'
401 );
402
403 const agentsSourceDir = path.join(sourceAssetsDir, 'agents');
404 if (fs.existsSync(agentsSourceDir)) {
405 copyDir(agentsSourceDir, path.join(skillOutputDir, 'agents'));
406 }
407
408 const referencesOutputDir = path.join(skillOutputDir, 'references');
409 fs.mkdirSync(referencesOutputDir, { recursive: true });
410 for (const [fileName, markdown] of Object.entries(
411 renderReferenceFiles(channel, featureOverrides)
412 )) {
413 fs.writeFileSync(path.join(referencesOutputDir, fileName), markdown, 'utf8');
414 }
415
416 return skillOutputDir;
417 };