@devries-cameron20 / composio-1 / commits / b0a02c969
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(examples): make validation provider agnostic (#3790)

This PR: - makes example typecheck, lint, and Workers dry-runs discover packages by script presence instead of a Mastra-only filter - runs the nightly staging suite as a provider matrix, starting with Mastra and failing when a matrix package is missing - keeps direct and Tool Router agents explicit while sharing the Tool Router agent between Node.js and Cloudflare Workers - keeps root ESLint rules in Turbo's lint cache key and documents both Worker secrets ## Testing - `pnpm run typecheck` - `pnpm run typecheck:examples` - `./node_modules/.bin/eslint ts/packages --ext .ts,.tsx` (0 errors; 72 existing warnings) - `pnpm run lint:examples` - `pnpm exec turbo cf:dry-run --filter='./ts/examples/*'` - confirmed Turbo includes `eslint.config.mjs` in the Mastra lint task inputs - confirmed a missing provider package fails instead of silently passing the nightly smoke step ## Post-Deploy Monitoring & Validation - after merge, dispatch `ts.examples-nightly.yml` on `next` and confirm the `mastra examples against staging` matrix leg runs smoke, direct-tools, and Tool Router successfully - healthy signal: smoke reports wrapped tools and both agent steps return non-empty output - failure signal: workflow logs contain `SMOKE FAIL`, `Agent returned empty output`, `No projects matched`, or a secret preflight error; revert this PR if the foundation gate begins false-passing or blocking unrelated example work - validation window and owner: the first post-merge dispatch plus the next scheduled 06:00 UTC nightly, owned by the TypeScript examples maintainers --- [![Compound Engineering](https://img.shields.io/badge/Compound-Engineering-6C5CE7)](https://github.com/EveryInc/compound-engineering-plugin) ![Codex](https://img.shields.io/badge/GPT--5-000000)

Alberto Schiabel committed Jul 10, 2026 at 11:42 UTC b0a02c96933404b12da36e5416348d5c73a1c04d
12 files changed +191 -123
.github/workflows/ts.examples-nightly.yml
+11 -7
@@ -23,8 +23,12 @@ env:
23
24 jobs:
25 examples-staging:
26 - name: Examples against staging
26 + name: ${{ matrix.provider }} examples against staging
27 runs-on: ubuntu-latest
28 + strategy:
29 + fail-fast: false
30 + matrix:
31 + provider: [mastra]
32
33 steps:
34 - name: Checkout Code
@@ -52,14 +56,14 @@ jobs:
56
57 # Deterministic regression net — needs only COMPOSIO_API_KEY, no LLM.
58 # Self-skips when the secret is absent (e.g. fork-triggered dispatch).
55 - - name: Mastra smoke (wrapping + tool-router)
56 - run: pnpm --filter mastra-example run smoke
59 + - name: ${{ matrix.provider }} smoke (wrapping + tool-router)
60 + run: pnpm --filter ${{ matrix.provider }}-example --fail-if-no-match run smoke
61
62 # Full agent run — only when an LLM key is configured.
59 - - name: Mastra direct-tools example
63 + - name: ${{ matrix.provider }} direct-tools example
64 if: ${{ env.OPENAI_API_KEY != '' }}
61 - run: bun ts/examples/mastra/src/index.ts
65 + run: bun ts/examples/${{ matrix.provider }}/src/index.ts
66
63 - - name: Mastra tool-router example
67 + - name: ${{ matrix.provider }} tool-router example
68 if: ${{ env.OPENAI_API_KEY != '' }}
65 - run: bun ts/examples/mastra/src/tool-router.ts
69 + run: bun ts/examples/${{ matrix.provider }}/src/tool-router.ts
.github/workflows/ts.examples.yml
+3 -1
@@ -8,6 +8,7 @@ on:
8 - 'ts/packages/core/**'
9 - 'ts/packages/providers/**'
10 - 'eslint.config.mjs'
11 + - 'package.json'
12 - '.github/actions/setup-node-pnpm-bun/action.yml'
13 - '.github/workflows/ts.examples.yml'
14 - 'mise.toml'
@@ -20,6 +21,7 @@ on:
21 - 'ts/packages/core/**'
22 - 'ts/packages/providers/**'
23 - 'eslint.config.mjs'
24 + - 'package.json'
25 - '.github/actions/setup-node-pnpm-bun/action.yml'
26 - '.github/workflows/ts.examples.yml'
27 - 'mise.toml'
@@ -64,4 +66,4 @@ jobs:
66
67 # Prove the Cloudflare Workers entry bundles without secrets or deploying.
68 - name: Cloudflare Workers dry-run build
67 - run: pnpm --filter mastra-example run cf:dry-run
69 + run: pnpm exec turbo cf:dry-run --filter='./ts/examples/*'
package.json
+2 -2
@@ -37,8 +37,8 @@
37 "test:ui": "vitest --ui",
38 "typecheck": "turbo typecheck --filter=./ts/packages/**",
39 "typecheck:tsc": "turbo typecheck:tsc --filter=./ts/packages/**",
40 - "typecheck:examples": "turbo typecheck --filter=mastra-example",
41 - "lint:examples": "eslint ts/examples/mastra --ext .ts,.tsx",
40 + "typecheck:examples": "turbo typecheck --filter='./ts/examples/*'",
41 + "lint:examples": "turbo lint --filter='./ts/examples/*'",
42 "lint": "eslint ts/packages --ext .ts,.tsx",
43 "lint:packages": "eslint ts/packages --ext .ts,.tsx",
44 "lint:fix": "eslint . --ext .ts,.tsx --fix",
ts/examples/mastra/README.md
+17 -11
@@ -19,35 +19,41 @@ cp .env.example .env # then fill in COMPOSIO_API_KEY and OPENAI_API_KEY
19
20 ## Examples
21
22 -| File | What it shows | Run |
23 -| --- | --- | --- |
24 -| `src/index.ts` | Direct tools: fetch one Composio tool as a Mastra tool | `bun ts/examples/mastra/src/index.ts` |
25 -| `src/tool-router.ts` | **Tool Router** (v1-canonical): `composio.sessions.create(...)` → `session.tools()` | `bun ts/examples/mastra/src/tool-router.ts` |
26 -| `src/cloudflare.ts` | The same wrapping path on the **Cloudflare Workers** runtime | `bun run cf:dev` (then `GET localhost:8787/`) |
22 +| File | What it shows | Run |
23 +| -------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------- |
24 +| `src/index.ts` | Direct tools: fetch one Composio tool as a Mastra tool | `bun ts/examples/mastra/src/index.ts` |
25 +| `src/tool-router.ts` | **Tool Router** (v1-canonical): `composio.sessions.create(...)` → `session.tools()` | `bun ts/examples/mastra/src/tool-router.ts` |
26 +| `src/cloudflare.ts` | The same Tool Router agent path on the **Cloudflare Workers** runtime | `bun run cf:dev` (then `GET localhost:8787/`) |
27
28 From this folder you can also use `pnpm start` (index), `pnpm tool-router`, and
29 `pnpm cf:dev`.
30
31 ## Using Anthropic instead of OpenAI
32
33 -Swap the model import and set `ANTHROPIC_API_KEY`:
33 +The model setup lives in `src/hackernews-agent/direct.ts` and
34 +`src/hackernews-agent/tool-router.ts`. Replace the OpenAI provider in the agent
35 +you want to run and add `ANTHROPIC_API_KEY` to its environment type:
36
37 ```ts
36 -// import { openai } from '@ai-sdk/openai';
37 -import { anthropic } from '@ai-sdk/anthropic';
38 +import { createAnthropic } from '@ai-sdk/anthropic';
39 // ...
40 +const anthropic = createAnthropic({
41 + apiKey: requireKey(env, 'ANTHROPIC_API_KEY'),
42 +});
43 model: anthropic('claude-haiku-4-5'),
44 ```
45
42 -(You'll also need to add `@ai-sdk/anthropic` to the dependencies.)
46 +Add `@ai-sdk/anthropic` to the dependencies and configure the Anthropic key in
47 +the Node environment or Worker bindings, depending on the runtime.
48
49 ## Runtime notes
50
51 - **Node/Bun:** `src/index.ts` and `src/tool-router.ts` read keys from
52 `process.env` via `dotenv`.
53 - **Cloudflare Workers:** `src/cloudflare.ts` reads keys from the Worker `env`
49 - binding (no `process.env`). Provide the key with
50 - `wrangler secret put COMPOSIO_API_KEY`. CI validates the Worker build with
54 + binding (no `process.env`). Provide both keys with
55 + `wrangler secret put COMPOSIO_API_KEY` and
56 + `wrangler secret put OPENAI_API_KEY`. CI validates the Worker build with
57 `wrangler deploy --dry-run`.
58
59 ## Support
ts/examples/mastra/package.json
+1
@@ -14,6 +14,7 @@
14 "cf:dev": "wrangler dev",
15 "cf:dry-run": "wrangler deploy --dry-run --outdir dist-worker",
16 "typecheck": "tsc --noEmit -p ./tsconfig.json && tsc --noEmit -p ./tsconfig.worker.json",
17 + "lint": "eslint src --ext .ts,.tsx",
18 "test": "echo \"Error: no test specified\" && exit 1"
19 },
20 "keywords": [
ts/examples/mastra/src/cloudflare.ts
+10 -20
@@ -1,9 +1,8 @@
1 /**
2 * Mastra × Composio — Cloudflare Workers
3 *
4 - * Proves the Mastra provider's tool-wrapping path runs on the Workers runtime,
5 - * not just Node. Reads config from the Worker `env` binding (no `process.env`),
6 - * fetches HackerNews tools wrapped for Mastra, and returns their slugs.
4 + * Proves the same Tool Router agent path runs on the Workers runtime, not just
5 + * Node. Reads config from the Worker `env` binding (no `process.env`).
6 *
7 * This entry is what the per-PR CI validates with `wrangler deploy --dry-run`.
8 *
@@ -11,28 +10,19 @@
10 * cd ts/examples/mastra && bun run cf:dev # then GET http://localhost:8787/
11 * Deploy config: wrangler.jsonc
12 */
14 -import { Composio } from '@composio/core';
15 -import { MastraProvider } from '@composio/mastra';
13 +import {
14 + runToolRouterHackerNewsAgent,
15 + type ToolRouterHackerNewsAgentEnvironment,
16 +} from './hackernews-agent/tool-router';
17
17 -export interface Env {
18 - COMPOSIO_API_KEY: string;
19 -}
18 +export type Env = Required<ToolRouterHackerNewsAgentEnvironment>;
19
20 export default {
21 async fetch(_request: Request, env: Env): Promise<Response> {
23 - const composio = new Composio({
24 - apiKey: env.COMPOSIO_API_KEY,
25 - provider: new MastraProvider(),
26 - });
27 -
28 - const tools = await composio.tools.get('default', {
29 - toolkits: ['hackernews'],
30 - });
22 + const text = await runToolRouterHackerNewsAgent(env);
23
32 - return Response.json({
33 - runtime: 'cloudflare-workers',
34 - provider: 'mastra',
35 - tools: Object.keys(tools),
24 + return new Response(text, {
25 + headers: { 'content-type': 'text/plain; charset=utf-8' },
26 });
27 },
28 };
ts/examples/mastra/src/hackernews-agent/direct.ts new
+66
@@ -0,0 +1,66 @@
1 +import { createOpenAI } from '@ai-sdk/openai';
2 +import { Composio } from '@composio/core';
3 +import { MastraProvider } from '@composio/mastra';
4 +import { Agent } from '@mastra/core/agent';
5 +import { stepCountIs } from 'ai';
6 +
7 +interface DirectHackerNewsAgentEnvironment {
8 + COMPOSIO_API_KEY?: string;
9 + OPENAI_API_KEY?: string;
10 +}
11 +
12 +function requireKey(
13 + env: DirectHackerNewsAgentEnvironment,
14 + name: keyof DirectHackerNewsAgentEnvironment
15 +): string {
16 + const value = env[name];
17 + if (!value) {
18 + throw new Error(`${name} is required to run the HackerNews agent.`);
19 + }
20 +
21 + return value;
22 +}
23 +
24 +export async function runDirectHackerNewsAgent(
25 + env: DirectHackerNewsAgentEnvironment
26 +): Promise<string> {
27 + const composioApiKey = requireKey(env, 'COMPOSIO_API_KEY');
28 + const openaiApiKey = requireKey(env, 'OPENAI_API_KEY');
29 + const composio = new Composio({
30 + apiKey: composioApiKey,
31 + provider: new MastraProvider(),
32 + });
33 + const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER_BY_USERNAME', {
34 + beforeExecute: ({ toolSlug, params }) => {
35 + console.log(`🔧 executing ${toolSlug} with ${JSON.stringify(params.arguments)}`);
36 + return params;
37 + },
38 + afterExecute: ({ toolSlug, result }) => {
39 + console.log(`✅ ${toolSlug} finished`);
40 + return result;
41 + },
42 + });
43 + const openai = createOpenAI({
44 + apiKey: openaiApiKey,
45 + });
46 + const agent = new Agent({
47 + id: 'hackernews-agent',
48 + name: 'HackerNews Agent',
49 + instructions: 'You are a helpful assistant that looks up HackerNews users.',
50 + model: openai('gpt-5-mini'),
51 + tools,
52 + });
53 +
54 + const { text } = await agent.generate(
55 + [{ role: 'user', content: 'Tell me about the HackerNews user `pg`.' }],
56 + {
57 + stopWhen: stepCountIs(10),
58 + }
59 + );
60 +
61 + if (!text || text.trim().length === 0) {
62 + throw new Error('Agent returned empty output — expected a non-empty response.');
63 + }
64 +
65 + return text;
66 +}
ts/examples/mastra/src/hackernews-agent/tool-router.ts new
+66
@@ -0,0 +1,66 @@
1 +import { createOpenAI } from '@ai-sdk/openai';
2 +import { Composio } from '@composio/core';
3 +import { MastraProvider } from '@composio/mastra';
4 +import { Agent } from '@mastra/core/agent';
5 +import { stepCountIs } from 'ai';
6 +
7 +export interface ToolRouterHackerNewsAgentEnvironment {
8 + COMPOSIO_API_KEY?: string;
9 + OPENAI_API_KEY?: string;
10 +}
11 +
12 +function requireKey(
13 + env: ToolRouterHackerNewsAgentEnvironment,
14 + name: keyof ToolRouterHackerNewsAgentEnvironment
15 +): string {
16 + const value = env[name];
17 + if (!value) {
18 + throw new Error(`${name} is required to run the HackerNews agent.`);
19 + }
20 +
21 + return value;
22 +}
23 +
24 +export async function runToolRouterHackerNewsAgent(
25 + env: ToolRouterHackerNewsAgentEnvironment
26 +): Promise<string> {
27 + const composioApiKey = requireKey(env, 'COMPOSIO_API_KEY');
28 + const openaiApiKey = requireKey(env, 'OPENAI_API_KEY');
29 + const composio = new Composio({
30 + apiKey: composioApiKey,
31 + provider: new MastraProvider(),
32 + });
33 + const session = await composio.sessions.create('example-user', {
34 + toolkits: ['hackernews'],
35 + });
36 + const tools = await session.tools();
37 + const openai = createOpenAI({
38 + apiKey: openaiApiKey,
39 + });
40 + const agent = new Agent({
41 + id: 'hackernews-router-agent',
42 + name: 'HackerNews Router Agent',
43 + instructions:
44 + 'You are a helpful assistant. Use the available Composio tools to search for and read HackerNews data before answering.',
45 + model: openai('gpt-5-mini'),
46 + tools,
47 + });
48 +
49 + const { text } = await agent.generate(
50 + [
51 + {
52 + role: 'user',
53 + content: 'What are the current top 3 HackerNews stories? Give me their titles.',
54 + },
55 + ],
56 + {
57 + stopWhen: stepCountIs(10),
58 + }
59 + );
60 +
61 + if (!text || text.trim().length === 0) {
62 + throw new Error('Agent returned empty output — expected a non-empty response.');
63 + }
64 +
65 + return text;
66 +}
ts/examples/mastra/src/index.ts
+2 -40
@@ -12,49 +12,11 @@
12 * Run:
13 * bun ts/examples/mastra/src/index.ts
14 */
15 -import { openai } from '@ai-sdk/openai';
16 -import { Composio } from '@composio/core';
17 -import { MastraProvider } from '@composio/mastra';
18 -import { Agent } from '@mastra/core/agent';
19 -import { stepCountIs } from 'ai';
15 import 'dotenv/config';
16
22 -const composio = new Composio({
23 - apiKey: process.env.COMPOSIO_API_KEY,
24 - provider: new MastraProvider(),
25 -});
17 +import { runDirectHackerNewsAgent } from './hackernews-agent/direct';
18
27 -// Fetch a single tool from the unauthenticated HackerNews toolkit.
28 -// The modifiers below are optional — they show the schema/execution hooks.
29 -const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER_BY_USERNAME', {
30 - beforeExecute: ({ toolSlug, params }) => {
31 - console.log(`🔧 executing ${toolSlug} with ${JSON.stringify(params.arguments)}`);
32 - return params;
33 - },
34 - afterExecute: ({ toolSlug, result }) => {
35 - console.log(`✅ ${toolSlug} finished`);
36 - return result;
37 - },
38 -});
39 -
40 -const agent = new Agent({
41 - id: 'hackernews-agent',
42 - name: 'HackerNews Agent',
43 - instructions: 'You are a helpful assistant that looks up HackerNews users.',
44 - model: openai('gpt-5-mini'),
45 - tools,
46 -});
47 -
48 -// Allow the agent a few steps to call the tool and then summarize the result.
49 -const { text } = await agent.generate(
50 - [{ role: 'user', content: 'Tell me about the HackerNews user `pg`.' }],
51 - { stopWhen: stepCountIs(10) }
52 -);
53 -
54 -// This example doubles as a test: a healthy run returns non-empty text.
55 -if (!text || text.trim().length === 0) {
56 - throw new Error('Agent returned empty output — expected a non-empty response.');
57 -}
19 +const text = await runDirectHackerNewsAgent(process.env);
20
21 console.log('\n🤖 Agent response:\n');
22 console.log(text);
ts/examples/mastra/src/tool-router.ts
+2 -39
@@ -15,48 +15,11 @@
15 * Run:
16 * bun ts/examples/mastra/src/tool-router.ts
17 */
18 -import { openai } from '@ai-sdk/openai';
19 -import { Composio } from '@composio/core';
20 -import { MastraProvider } from '@composio/mastra';
21 -import { Agent } from '@mastra/core/agent';
22 -import { stepCountIs } from 'ai';
18 import 'dotenv/config';
19
25 -const composio = new Composio({
26 - apiKey: process.env.COMPOSIO_API_KEY,
27 - provider: new MastraProvider(),
28 -});
20 +import { runToolRouterHackerNewsAgent } from './hackernews-agent/tool-router';
21
30 -// Canonical session creation. `composio.sessions.create(...)` is the v1 surface;
31 -// the bare `composio.create(...)` alias is deprecated.
32 -const session = await composio.sessions.create('example-user', {
33 - toolkits: ['hackernews'],
34 -});
35 -
36 -const tools = await session.tools();
37 -
38 -const agent = new Agent({
39 - id: 'hackernews-router-agent',
40 - name: 'HackerNews Router Agent',
41 - instructions:
42 - 'You are a helpful assistant. Use the available Composio tools to search for and read HackerNews data before answering.',
43 - model: openai('gpt-5-mini'),
44 - tools,
45 -});
46 -
47 -// Tool Router is a multi-step flow: the agent calls the router's search +
48 -// multi-execute meta-tools, then summarizes. Without a step budget the run
49 -// stops after the first tool call and returns empty text, so allow several
50 -// steps (matches the Mastra tool-router e2e reference).
51 -const { text } = await agent.generate(
52 - [{ role: 'user', content: 'What are the current top 3 HackerNews stories? Give me their titles.' }],
53 - { stopWhen: stepCountIs(10) }
54 -);
55 -
56 -// This example doubles as a test: a healthy run returns non-empty text.
57 -if (!text || text.trim().length === 0) {
58 - throw new Error('Agent returned empty output — expected a non-empty response.');
59 -}
22 +const text = await runToolRouterHackerNewsAgent(process.env);
23
24 console.log('\n🤖 Agent response:\n');
25 console.log(text);
ts/examples/mastra/wrangler.jsonc
+5 -3
@@ -9,10 +9,12 @@
9 "compatibility_date": "2025-06-20",
10 "compatibility_flags": ["nodejs_compat"],
11 "observability": {
12 - "enabled": true
13 - }
12 + "enabled": true,
13 + },
14 /**
15 - * COMPOSIO_API_KEY is provided as a Worker secret, not committed here:
15 + * COMPOSIO_API_KEY and OPENAI_API_KEY are provided as Worker secrets, not
16 + * committed here:
17 * wrangler secret put COMPOSIO_API_KEY
18 + * wrangler secret put OPENAI_API_KEY
19 */
20 }
turbo.jsonc
+6
@@ -74,6 +74,12 @@
74 "dependsOn": ["^build"],
75 "cache": false
76 },
77 + "lint": {
78 + "inputs": ["$TURBO_DEFAULT$", "../../../eslint.config.mjs"]
79 + },
80 + "cf:dry-run": {
81 + "dependsOn": ["^build"]
82 + },
83 "//#clean": {
84 "cache": false
85 },