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

test(ts/e2e): add a fake Composio backend for CLI e2e tests (#5351)

This PR: - part of [PRDE-2212](https://linear.app/composio/issue/PRDE-2212/cli-e2e-tests-fake-backend-operation-suites-and-agent-journeys-with) - builds on top of https://github.com/ComposioHQ/composio/pull/5350; split from https://github.com/ComposioHQ/composio/pull/5312 - adds a fake Composio backend, Dashboard, agents service, GitHub release server, and PostHog endpoint with a request `journal`, seeded `world`, and per-route `faults` - decodes fake responses with `@composio/client` schemas while documenting the authorization and backend behavior that remain assumptions - adds `startJourneyContainer()` and `startCliRig()` for commands that share a container and empty home, including optional read-only mounts - runs the standalone contract suite before the API-key check in CI, with API keys blanked so forks and Dependabot can run it ## Context Frozen install, CLI dependency builds, utility and fake-backend typechecks, and 31 keyless contract tests passed; the inherited upgrade suite also passed. Prettier passed for authored files; the generated lockfile has the same formatting mismatch as the base and retains pnpm's output. The new lockfile importer is the only dependency change. Complete CLI workflow validation after the base merges and this PR is retargeted to `next`.

Alberto Schiabel committed Nov 16, 2026 at 12:35 UTC e8107cb4c51580fdf3ed087dd8e2acc8860987f3
21 files changed +3453 -33
.github/workflows/ts.test-e2e.yml
+44 -28
@@ -189,32 +189,6 @@ jobs:
189 - name: Build
190 run: pnpm run build:packages
191
192 - - name: Check API keys
193 - id: api-keys
194 - env:
195 - IS_FORK_PR: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork }}
196 - run: |
197 - missing=()
198 - for name in COMPOSIO_API_KEY OPENAI_API_KEY COMPOSIO_USER_API_KEY; do
199 - if [ -z "${!name}" ]; then
200 - missing+=("$name")
201 - fi
202 - done
203 -
204 - if [ "${#missing[@]}" -gt 0 ]; then
205 - echo "available=false" >> "$GITHUB_OUTPUT"
206 - if [ "$GITHUB_ACTOR" = "dependabot[bot]" ] || [ "$IS_FORK_PR" = "true" ]; then
207 - echo "::notice::Skipping secret-backed E2E tests; missing ${missing[*]}."
208 - exit 0
209 - fi
210 -
211 - printf '::error::%s is not set\n' "${missing[@]}"
212 - exit 1
213 - fi
214 -
215 - echo "available=true" >> "$GITHUB_OUTPUT"
216 - echo "✅ API keys are configured"
217 -
192 - name: Verify CLI image reuse policy
193 run: pnpm --filter @e2e-tests/utils test
194
@@ -245,9 +219,51 @@ jobs:
219 composio.cli_version=${{ steps.cli-version.outputs.value }}
220 org.opencontainers.image.revision=${{ github.sha }}
221
248 - - name: Run CLI E2E Tests
222 + # These suites run the CLI against a fake Composio deployment, so they need no key and run on every PR, fork and
223 + # Dependabot PRs included. The keys are blanked to keep it that way.
224 + - name: Run CLI E2E Tests (no API keys)
225 + env:
226 + COMPOSIO_USER_API_KEY: ''
227 + COMPOSIO_API_KEY: ''
228 + COMPOSIO_BASE_URL: ''
229 + OPENAI_API_KEY: ''
230 + run: >-
231 + pnpm exec turbo test:e2e:cli
232 + --filter=@e2e-tests/cli-fake-backend
233 +
234 + # After the keyless step, so a missing key cannot keep those suites from running.
235 + - name: Check API keys
236 + id: api-keys
237 + env:
238 + IS_FORK_PR: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork }}
239 + run: |
240 + missing=()
241 + for name in COMPOSIO_API_KEY OPENAI_API_KEY COMPOSIO_USER_API_KEY; do
242 + if [ -z "${!name}" ]; then
243 + missing+=("$name")
244 + fi
245 + done
246 +
247 + if [ "${#missing[@]}" -gt 0 ]; then
248 + echo "available=false" >> "$GITHUB_OUTPUT"
249 + if [ "$GITHUB_ACTOR" = "dependabot[bot]" ] || [ "$IS_FORK_PR" = "true" ]; then
250 + echo "::notice::Skipping secret-backed E2E tests; missing ${missing[*]}."
251 + exit 0
252 + fi
253 +
254 + printf '::error::%s is not set\n' "${missing[@]}"
255 + exit 1
256 + fi
257 +
258 + echo "available=true" >> "$GITHUB_OUTPUT"
259 + echo "✅ API keys are configured"
260 +
261 + - name: Run CLI E2E Tests (staging)
262 if: steps.api-keys.outputs.available == 'true'
250 - run: pnpm run test:e2e:cli
263 + run: >-
264 + pnpm exec turbo test:e2e:cli
265 + --filter='@e2e-tests/cli-*'
266 + --filter='!@e2e-tests/cli-fake-backend'
267
268 # Cloudflare Workerd E2E tests
269 test-e2e-cloudflare:
pnpm-lock.yaml
+21
@@ -246,6 +246,27 @@ importers:
246 specifier: workspace:*
247 version: link:../../_utils
248
249 + ts/e2e-tests/cli/fake-backend:
250 + devDependencies:
251 + '@composio/client':
252 + specifier: 'catalog:'
253 + version: 2.1.32(effect@4.1.3)
254 + '@e2e-tests/utils':
255 + specifier: workspace:*
256 + version: link:../../_utils
257 + '@types/bun':
258 + specifier: 'catalog:'
259 + version: 1.4.4
260 + effect:
261 + specifier: 'catalog:'
262 + version: 4.1.3
263 + typescript:
264 + specifier: 'catalog:'
265 + version: 7.0.2
266 + zod:
267 + specifier: 'catalog:'
268 + version: 4.6.7
269 +
270 ts/e2e-tests/cli/install:
271 devDependencies:
272 '@e2e-tests/utils':
ts/e2e-tests/.gitignore
+1
@@ -1,2 +1,3 @@
1 # Debug logs from Docker e2e test runs
2 DEBUG.log
3 +DEBUG.*.log
ts/e2e-tests/_utils/README.md
+22
@@ -126,6 +126,28 @@ expect(result.files['out.txt']).toBe('0.1.24');
126
127 The files are copied out of the container after execution and returned as a map in the result.
128
129 +### `startJourneyContainer`
130 +
131 +One CLI container that stays up while a test runs several commands in it, so a login or a cache file written by one command is there for the next. Unlike `runCmd`, it mounts no host `~/.composio` and passes through no API key.
132 +
133 +```typescript
134 +import { startJourneyContainer } from '@e2e-tests/utils';
135 +
136 +const journey = await startJourneyContainer({ env: { COMPOSIO_BASE_URL: mockUrl } });
137 +const first = await journey.exec('composio login --user-api-key uk_test');
138 +const second = await journey.exec('composio whoami', { timeoutSeconds: 30 });
139 +await journey.writeFile('/work/app/.composio/project.json', '{}');
140 +await journey.stop();
141 +```
142 +
143 +| Member | Description |
144 +| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
145 +| `exec(command, options?)` | Runs a POSIX `sh` command line. Options: `env`, `stdin`, `cwd` (defaults to the home), `timeoutSeconds` (default 60; exit code 124 on expiry), `user` (`uid:gid`, to run without root) |
146 +| `writeFile(path, content)` / `readFile(path)` | Write or read a file inside the container |
147 +| `steps()` / `writeDebugLog(path)` | The commands run so far with their results |
148 +| `home` | The home directory (default `/home/journey`), created empty when the journey starts |
149 +| `stop()` | Removes the container |
150 +
151 ### `E2ETestResultWithSetup`
152
153 Extended result when `runFixture` is called with a `setup` option:
ts/e2e-tests/_utils/src/index.ts
+7
@@ -21,3 +21,10 @@ export {
21 type ExecResult,
22 type InstallImage,
23 } from './image-lifecycle';
24 +export {
25 + startJourneyContainer,
26 + type JourneyContainer,
27 + type JourneyExecOptions,
28 + type JourneyOptions,
29 + type JourneyStep,
30 +} from './journey';
ts/e2e-tests/_utils/src/journey.ts new
+208
@@ -0,0 +1,208 @@
1 +/**
2 + * Journey containers: one CLI container that stays up while a test runs
3 + * several commands in it, so state written by one command (a login, a linked
4 + * account, a cache file) is there for the next.
5 + *
6 + * `runCmd` gives every command a fresh container, which suits single commands.
7 + * A journey also differs in what it lets in: nothing from the host. No host
8 + * `~/.composio` mount and no API key passthrough, so a journey can only reach
9 + * what its test points it at.
10 + */
11 +
12 +import { $ } from 'bun';
13 +import { writeFile } from 'node:fs/promises';
14 +import { getRepoRoot, resolveCliVersionMetaList } from './config';
15 +import { ensureCliImage } from './image-lifecycle';
16 +import type { E2ETestResult } from './types';
17 +
18 +export interface JourneyOptions {
19 + /** Environment of every command in the journey. */
20 + env?: Record<string, string>;
21 + /**
22 + * Home directory inside the container. It does not exist until the journey
23 + * starts, so the CLI meets it the way a first run does.
24 + */
25 + home?: string;
26 + /** Short name used in the container name, to tell journeys apart in `docker ps`. */
27 + label?: string;
28 + /** Host files or directories mounted read-only, such as a tool the journey runs. */
29 + readOnlyMounts?: ReadonlyArray<{ readonly source: string; readonly target: string }>;
30 +}
31 +
32 +export interface JourneyExecOptions {
33 + /** Extra environment for this command only. */
34 + env?: Record<string, string>;
35 + /** Text piped to the command's stdin. Without it stdin is `/dev/null`. */
36 + stdin?: string;
37 + /** Working directory; defaults to the journey's home. */
38 + cwd?: string;
39 + /** Kills the command after this long and reports exit code 124. Defaults to 60 seconds. */
40 + timeoutSeconds?: number;
41 + /** Runs the command as this `uid:gid` instead of root, so file permissions apply to it. */
42 + user?: string;
43 +}
44 +
45 +export interface JourneyStep {
46 + readonly command: string;
47 + readonly result: E2ETestResult;
48 + readonly durationMs: number;
49 +}
50 +
51 +export interface JourneyContainer {
52 + readonly name: string;
53 + readonly home: string;
54 + /** Runs a POSIX `sh` command line in the container. */
55 + exec(command: string, options?: JourneyExecOptions): Promise<E2ETestResult>;
56 + /** Writes a file inside the container, creating its directory. */
57 + writeFile(path: string, content: string): Promise<void>;
58 + /** Reads a file from the container; rejects when it does not exist. */
59 + readFile(path: string): Promise<string>;
60 + /** Every command run so far, in order. */
61 + steps(): ReadonlyArray<JourneyStep>;
62 + /** Writes the steps to a log file on the host, for reading after a failure. */
63 + writeDebugLog(path: string): Promise<void>;
64 + /** Removes the container. */
65 + stop(): Promise<void>;
66 +}
67 +
68 +const DEFAULT_HOME = '/home/journey';
69 +const DEFAULT_TIMEOUT_SECONDS = 60;
70 +
71 +const shellQuote = (value: string): string => `'${value.replace(/'/g, `'\\''`)}'`;
72 +
73 +const envArgs = (env: Record<string, string> = {}): string[] =>
74 + Object.entries(env).flatMap(([name, value]) => ['-e', `${name}=${value}`]);
75 +
76 +const formatStep = (step: JourneyStep, index: number): string =>
77 + [
78 + `--- Step ${index + 1} ---`,
79 + `Command: ${step.command}`,
80 + `Duration: ${(step.durationMs / 1000).toFixed(2)}s`,
81 + `Exit Code: ${step.result.exitCode}`,
82 + '',
83 + '[stdout]',
84 + step.result.stdout.trim() || '(empty)',
85 + '',
86 + '[stderr]',
87 + step.result.stderr.trim() || '(empty)',
88 + '',
89 + ].join('\n');
90 +
91 +let imageTagPromise: Promise<string> | undefined;
92 +
93 +/** The CLI image of the current checkout, ensured once per test process. */
94 +const currentCliImage = (): Promise<string> => {
95 + imageTagPromise ??= (() => {
96 + const [cliVersion] = resolveCliVersionMetaList(['current']);
97 + return ensureCliImage(cliVersion.value, { repoRoot: getRepoRoot() });
98 + })();
99 + return imageTagPromise;
100 +};
101 +
102 +/**
103 + * Starts a container from the CLI image of the current checkout and keeps it
104 + * running until `stop()`.
105 + */
106 +export async function startJourneyContainer(
107 + options: JourneyOptions = {}
108 +): Promise<JourneyContainer> {
109 + const imageTag = await currentCliImage();
110 + const home = options.home ?? DEFAULT_HOME;
111 + const name = `e2e-journey-${options.label ?? 'cli'}-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
112 + const steps: JourneyStep[] = [];
113 + const mountArgs = (options.readOnlyMounts ?? []).flatMap(mount => [
114 + '--mount',
115 + `type=bind,source=${mount.source},target=${mount.target},readonly`,
116 + ]);
117 +
118 + const started =
119 + await $`docker run -d --rm --name ${name} --label composio.e2e=true --label composio.runtime=cli --add-host host.docker.internal:host-gateway -e HOME=${home} ${envArgs(options.env)} ${mountArgs} --workdir / ${imageTag} sleep infinity`
120 + .nothrow()
121 + .quiet();
122 + if (started.exitCode !== 0) {
123 + throw new Error(`Failed to start journey container: ${started.stderr.toString().trim()}`);
124 + }
125 +
126 + const run = async (
127 + command: string,
128 + execOptions: JourneyExecOptions = {}
129 + ): Promise<E2ETestResult> => {
130 + const timeout = execOptions.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
131 + // `timeout` lives in the container so the limit also stops the processes
132 + // the command started; a host-side kill would only end `docker exec`.
133 + const bounded = `timeout --kill-after=5 ${timeout} sh -c ${shellQuote(command)}`;
134 + const process = Bun.spawn(
135 + [
136 + 'docker',
137 + 'exec',
138 + '-i',
139 + ...envArgs(execOptions.env),
140 + ...(execOptions.user ? ['--user', execOptions.user] : []),
141 + '--workdir',
142 + execOptions.cwd ?? home,
143 + name,
144 + 'sh',
145 + '-c',
146 + bounded,
147 + ],
148 + {
149 + stdin: new TextEncoder().encode(execOptions.stdin ?? ''),
150 + stdout: 'pipe',
151 + stderr: 'pipe',
152 + }
153 + );
154 + const [stdout, stderr, exitCode] = await Promise.all([
155 + new Response(process.stdout).text(),
156 + new Response(process.stderr).text(),
157 + process.exited,
158 + ]);
159 + return { exitCode, stdout, stderr };
160 + };
161 +
162 + const prepared = await run(`mkdir -p ${shellQuote(home)}`, { cwd: '/' });
163 + if (prepared.exitCode !== 0) {
164 + await $`docker rm -f ${name}`.nothrow().quiet();
165 + throw new Error(`Failed to create journey home ${home}: ${prepared.stderr.trim()}`);
166 + }
167 +
168 + return {
169 + name,
170 + home,
171 + exec: async (command, execOptions) => {
172 + const startedAt = Date.now();
173 + const result = await run(command, execOptions);
174 + steps.push({ command, result, durationMs: Date.now() - startedAt });
175 + return result;
176 + },
177 + writeFile: async (path, content) => {
178 + const directory = path.slice(0, Math.max(1, path.lastIndexOf('/')));
179 + const written = await run(`mkdir -p ${shellQuote(directory)} && cat > ${shellQuote(path)}`, {
180 + stdin: content,
181 + cwd: '/',
182 + });
183 + if (written.exitCode !== 0) {
184 + throw new Error(`Failed to write ${path} in ${name}: ${written.stderr.trim()}`);
185 + }
186 + },
187 + readFile: async path => {
188 + const read = await run(`cat ${shellQuote(path)}`, { cwd: '/' });
189 + if (read.exitCode !== 0) {
190 + throw new Error(`Failed to read ${path} in ${name}: ${read.stderr.trim()}`);
191 + }
192 + return read.stdout;
193 + },
194 + steps: () => [...steps],
195 + writeDebugLog: async path => {
196 + await writeFile(
197 + path,
198 + [`Journey container: ${name}`, `Image: ${imageTag}`, '', ...steps.map(formatStep)].join(
199 + '\n'
200 + ),
201 + 'utf-8'
202 + );
203 + },
204 + stop: async () => {
205 + await $`docker rm -f ${name}`.nothrow().quiet();
206 + },
207 + };
208 +}
ts/e2e-tests/cli/README.md
+23 -5
@@ -10,11 +10,29 @@ Tests use `runCmd` to execute shell commands in the container and assert on exit
10
11 ## Test Suites
12
13 -| Suite | Description | Env Vars |
14 -| --------------------- | ------------------------------------------------------ | ----------------------- |
15 -| [upgrade](./upgrade/) | `composio upgrade` replaces a running Linux executable | None |
16 -| [version](./version/) | `composio version` output and exit code | None |
17 -| [whoami](./whoami/) | `composio whoami` prints the API key | `COMPOSIO_USER_API_KEY` |
13 +| Suite | Description | Env Vars |
14 +| ------------------------------- | ------------------------------------------------------------------------------------ | ----------------------- |
15 +| [upgrade](./upgrade/) | `composio upgrade` replaces a running Linux executable | None |
16 +| [fake-backend](./fake-backend/) | Test support: the fake Composio deployment CLI tests talk to, and its contract check | None |
17 +| [version](./version/) | `composio version` output and exit code | None |
18 +| [whoami](./whoami/) | `composio whoami` prints the API key | `COMPOSIO_USER_API_KEY` |
19 +
20 +## Journeys
21 +
22 +`runCmd` starts a fresh container for every command. A test that needs several commands to share state (log in, link, then execute) holds one container instead:
23 +
24 +```typescript
25 +import { startJourneyContainer } from '@e2e-tests/utils';
26 +
27 +const journey = await startJourneyContainer({ env: { COMPOSIO_BASE_URL: fake.docker.http } });
28 +await journey.exec('composio login --user-api-key …');
29 +const result = await journey.exec('composio whoami');
30 +await journey.stop();
31 +```
32 +
33 +A journey container mounts nothing from the host and passes through no API key. Tests can use it through `startCliRig` from `@e2e-tests/cli-fake-backend/rig`, which also starts the fake backend and points every host the CLI knows at it. Other outbound traffic is not blocked.
34 +
35 +`fake-backend` needs no secret. CI runs it in their own step with the API keys blanked, on every pull request, fork and Dependabot ones included; the suites that talk to staging run in a second step that is skipped when the keys are missing.
36
37 ## Isolation Tool
38
ts/e2e-tests/cli/fake-backend/README.md new
+62
@@ -0,0 +1,62 @@
1 +# Fake Composio backend
2 +
3 +Test support for CLI end-to-end suites. One process answers for every host the `composio` binary talks to, so a test never reaches a real Composio, GitHub, or PostHog endpoint.
4 +
5 +| Host the CLI calls | Pointed here by | Listener |
6 +| ------------------ | -------------------------------------------------------- | -------- |
7 +| Backend API | `COMPOSIO_BASE_URL` | HTTP |
8 +| Dashboard | `COMPOSIO_WEB_URL` | HTTPS |
9 +| Agents service | `COMPOSIO_AGENTS_BASE_URL` | HTTP |
10 +| GitHub releases | `COMPOSIO_GITHUB_API_BASE_URL` and `COMPOSIO_GITHUB_URL` | HTTP |
11 +| PostHog | `COMPOSIO_POSTHOG_INGEST_URL` | HTTP |
12 +
13 +`fake.cliEnv()` returns that environment. The Dashboard listener speaks TLS because the CLI sends a user API key to the Dashboard only over `https:` (or to loopback); the certificate is generated with the host's `openssl` at start and trusted in the container through `NODE_EXTRA_CA_CERTS`.
14 +
15 +## What it gives a test
16 +
17 +```ts
18 +import { startCliRig } from '@e2e-tests/cli-fake-backend/rig';
19 +
20 +const rig = await startCliRig();
21 +await rig.login();
22 +const result = await rig.run('composio search "send a slack message"');
23 +
24 +result.exitCode; // what the CLI did
25 +result.requests; // what the fake received while it ran
26 +rig.fake.world; // seeded state, and stand-ins for a person (linkLoginSession, connect)
27 +rig.fake.faults.inject({
28 + route: 'toolRouter.session.search',
29 + fault: { kind: 'status', status: 500 },
30 +});
31 +```
32 +
33 +- **Journal** (`src/journal.ts`). Every request, in order, with what the test usually wants to assert already resolved: the service it was for, the route that answered, the key class (`user` for `uk_`, `project` for `ak_`, `agent` for `cak_`), whether this deployment issued the key, the org, the project by its seeded label (`consumer`, `developer`, `developer-other`), how the project was learned (`scope-headers`, `project-key`, `key-default`, `route`), the project the request itself named (`requestedProject`, which a tool-router session can override), the user the request acted as, whether it changed anything (`tool-executed`, `connection-started`), and for an execution the tool and arguments it ran with, whichever of the three execute routes ran it.
34 +- **World** (`src/world.ts`). One org member, one user API key, a consumer project, two developer projects, four toolkits, five tools. Ids and timestamps are fixed, so two runs print the same bytes. A second fake started with `{ userApiKey }` is a deployment that never issued the first one's key.
35 +- **Faults** (`src/faults.ts`). Per route or per `METHOD /path` pattern, for a number of requests: a status with the standard error envelope, a delay, a reset before the response, a reset in the middle of the body, a body that is not JSON, JSON of another shape, an HTML page, an empty body.
36 +
37 +Run it by hand to poke at the CLI:
38 +
39 +```bash
40 +bun ts/e2e-tests/cli/fake-backend/src/main.ts /tmp/fake-ca.pem
41 +```
42 +
43 +## Fidelity
44 +
45 +**Verified.** Each route named after a `@composio/client` operation answers with a body that the client's own response schema for that operation decodes. `contract.test.ts` calls every such route and decodes the answer with `schemaLoaders` from `@composio/client/effect/schemas`; it also fails when a typed route has no sample. Run it with `pnpm --filter @e2e-tests/cli-fake-backend test:e2e:cli` (no Docker needed).
46 +
47 +**Assumed, not verified.** Read these before trusting a result that depends on them.
48 +
49 +- The client schemas are permissive (unknown fields pass, most fields are optional). A decoded response has the required fields with the right types; it is not shown to be what the real backend sends for that request.
50 +- Routes the client does not type are written from the CLI source that calls them: the Dashboard procedures `/api/cli/trpc/execute` and `executeMeta` (envelope from `dashboard-tool-execution.ts`), `POST /api/v3/org/project/{id}/api_keys/create`, `GET /api/v3/tools/{slug}/get_latest_version`, `POST /api/v3/cli/analytics`, the agents service, the GitHub release API, PostHog capture.
51 +- Error responses use the envelope the CLI's error extraction reads (`{ error: { message, code, slug, status, request_id, suggested_fix } }`). The slugs and codes are the ones the CLI special-cases (`ToolRouterV2_NoActiveConnection`, `ActionExecute_ConnectedAccountNotFound`, 4302); every other slug is invented.
52 +- Authorization rules are a model: a user key with `x-org-id` and `x-project-id` acts on that project; a project key acts on its project; **a user key with no scope acts on the org's default developer project**, the one `auth/session/info` reports. The last rule is a guess at what the real backend does with such a request. The journal marks those requests `key-default` so a test can see when the CLI relied on it.
53 +- `auth/session/info` for a user key reports the default developer project, never the consumer project.
54 +- Search is keyword matching over five tools. Tool executions return canned data. Nothing here says a real toolkit would accept the arguments.
55 +- **Tool arguments are not validated.** A tool runs with whatever arrives, a missing required argument included. The CLI validates against the tool's schema first, but sends the call anyway when it cannot load that schema (`validateToolInputBeforeExecute`), relying on the server. The real answer to an invalid input was never captured, so the fake does not invent one; a test that depends on the arguments asserts them from the journal.
56 +- A tool-router session acts on the project it was created for, whatever project the request names. Whether the real backend rejects a request whose scope differs from its session's is unknown; the journal keeps both (`project`, `requestedProject`) so a test can require them to agree.
57 +- A link request starts a connection as `INITIATED`; it turns `ACTIVE` after `world.linkCompletesAfterPolls` status reads, or never, or when its redirect URL is loaded: there is no OAuth page behind that URL, and a `GET` of it stands for the person approving. The world remembers which approvals came from the person and whether any answer has since reported them (`unreportedApprovals`), which is how a journey's person knows the agent cannot have seen one yet.
58 +- Retry-After, rate-limit headers, pagination past one page, request size limits, and timeouts on the server side are not modelled.
59 +
60 +## Not here
61 +
62 +Triggers, realtime (Pusher), logs, file uploads, `proxy`, MCP, and toolkit versions beyond one fixed version per toolkit have no routes. A command that needs one gets a 404 with slug `Fake_UnhandledRoute`, which the journal records with `route: null`.
ts/e2e-tests/cli/fake-backend/contract.test.ts new
+340
@@ -0,0 +1,340 @@
1 +/**
2 + * Keeps the fake backend honest against `@composio/client`.
3 + *
4 + * Every route named after a client operation is called once per sample below,
5 + * and its answer is decoded with the response schema the client itself ships
6 + * for that operation. A fake response the real client would reject fails here,
7 + * before any CLI suite builds on it.
8 + */
9 +
10 +import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
11 +import { schemaLoaders } from '@composio/client/effect/schemas';
12 +import * as Schema from 'effect/Schema';
13 +import {
14 + CONSUMER_PROJECT,
15 + CONSUMER_USER_ID,
16 + DEVELOPER_PROJECT,
17 + GLOBAL_TEST_USER_ID,
18 + ORG,
19 + ROUTES,
20 + startFakeComposio,
21 + USER_API_KEY,
22 + type FakeComposio,
23 + type World,
24 +} from './src/index';
25 +
26 +type OperationName = keyof typeof schemaLoaders;
27 +
28 +const isOperationName = (name: string): name is OperationName => name in schemaLoaders;
29 +
30 +/** Decodes like the client does when a call asks for validation; throws on the first mismatch. */
31 +const decodeWith = (schema: Schema.Codec<unknown, unknown, never, never>, json: unknown): unknown =>
32 + Schema.decodeUnknownSync(schema)(json);
33 +
34 +interface Sample {
35 + /** The operation whose route the request must reach. */
36 + readonly operation: OperationName;
37 + /** What makes this sample different from another one of the same operation. */
38 + readonly variant: string;
39 + readonly method: 'GET' | 'POST';
40 + /** May read ids from state the `prepare` step created. */
41 + readonly path: (world: World) => string;
42 + readonly body?: unknown;
43 + readonly project?: 'consumer' | 'developer';
44 + readonly expectStatus?: number;
45 + /** Seeds what the request needs and is undone by the next sample's fresh world. */
46 + readonly prepare?: (world: World) => void;
47 +}
48 +
49 +const SLACK_ARGUMENTS = { channel: 'general', text: 'hello' };
50 +
51 +const withConsumerSession = (world: World) => {
52 + world.createToolRouterSession(CONSUMER_PROJECT.label, CONSUMER_USER_ID);
53 +};
54 +
55 +const withConnectedConsumerSession = (world: World) => {
56 + withConsumerSession(world);
57 + world.connect(CONSUMER_PROJECT.label, CONSUMER_USER_ID, 'slack');
58 +};
59 +
60 +const SESSION = '/api/v3.1/tool_router/session/trs_e2e0001';
61 +
62 +const SAMPLES: ReadonlyArray<Sample> = [
63 + {
64 + operation: 'auth.session.retrieveInfo',
65 + variant: 'user key',
66 + method: 'GET',
67 + path: () => '/api/v3.1/auth/session/info',
68 + },
69 + { operation: 'org.list', variant: 'two orgs', method: 'GET', path: () => '/api/v3.1/org/list' },
70 + {
71 + operation: 'org.project.list',
72 + variant: 'developer projects',
73 + method: 'GET',
74 + path: () => '/api/v3.1/org/project/list',
75 + },
76 + {
77 + operation: '_internal.org.consumer.project.resolve',
78 + variant: 'consumer project',
79 + method: 'POST',
80 + path: () => '/api/v3.1/org/consumer/project/resolve',
81 + },
82 + {
83 + operation: '_internal.org.consumer.listConnectedToolkits',
84 + variant: 'one connected toolkit',
85 + method: 'GET',
86 + path: () => `/api/v3.1/org/consumer/connected_toolkits?user_id=${CONSUMER_USER_ID}`,
87 + prepare: world => void world.connect(CONSUMER_PROJECT.label, CONSUMER_USER_ID, 'slack'),
88 + },
89 + {
90 + operation: '_internal.org.consumer.retrieveConfig',
91 + variant: 'defaults',
92 + method: 'GET',
93 + path: () => '/api/v3.1/org/consumer/config',
94 + },
95 + {
96 + operation: '_internal.consumer.permissions.resolve',
97 + variant: 'allow all',
98 + method: 'POST',
99 + path: () => '/api/v3.1/consumer/permissions/resolve',
100 + body: {},
101 + },
102 + {
103 + operation: '_internal.cli.createSession',
104 + variant: 'pending',
105 + method: 'POST',
106 + path: () => '/api/v3.1/cli/create-session',
107 + body: { scope: 'user' },
108 + },
109 + {
110 + operation: '_internal.cli.getSession',
111 + variant: 'pending',
112 + method: 'GET',
113 + path: world => `/api/v3.1/cli/get-session?id=${world.loginSessions[0]?.id}`,
114 + prepare: world => void world.createLoginSession(),
115 + },
116 + {
117 + operation: '_internal.cli.getSession',
118 + variant: 'linked',
119 + method: 'GET',
120 + path: world => `/api/v3.1/cli/get-session?id=${world.loginSessions[0]?.id}`,
121 + prepare: world => {
122 + world.createLoginSession();
123 + world.linkLoginSession();
124 + },
125 + },
126 + {
127 + operation: 'toolkits.list',
128 + variant: 'all toolkits',
129 + method: 'GET',
130 + path: () => '/api/v3.1/toolkits',
131 + },
132 + {
133 + operation: 'toolkits.retrieve',
134 + variant: 'oauth toolkit',
135 + method: 'GET',
136 + path: () => '/api/v3.1/toolkits/slack',
137 + },
138 + {
139 + operation: 'toolkits.retrieve',
140 + variant: 'no-auth toolkit',
141 + method: 'GET',
142 + path: () => '/api/v3.1/toolkits/hackernews',
143 + },
144 + { operation: 'tools.list', variant: 'all tools', method: 'GET', path: () => '/api/v3.1/tools' },
145 + {
146 + operation: 'tools.retrieve',
147 + variant: 'one tool',
148 + method: 'GET',
149 + path: () => '/api/v3.1/tools/SLACK_SEND_MESSAGE',
150 + },
151 + {
152 + operation: 'toolRouter.session.create',
153 + variant: 'consumer user',
154 + method: 'POST',
155 + path: () => '/api/v3.1/tool_router/session',
156 + body: { user_id: CONSUMER_USER_ID },
157 + project: 'consumer',
158 + expectStatus: 201,
159 + },
160 + {
161 + operation: 'toolRouter.session.search',
162 + variant: 'not connected',
163 + method: 'POST',
164 + path: () => `${SESSION}/search`,
165 + body: { queries: [{ use_case: 'send a slack message' }] },
166 + project: 'consumer',
167 + prepare: withConsumerSession,
168 + },
169 + {
170 + operation: 'toolRouter.session.search',
171 + variant: 'connected',
172 + method: 'POST',
173 + path: () => `${SESSION}/search`,
174 + body: { queries: [{ use_case: 'send a slack message' }] },
175 + project: 'consumer',
176 + prepare: withConnectedConsumerSession,
177 + },
178 + {
179 + operation: 'toolRouter.session.execute',
180 + variant: 'completed',
181 + method: 'POST',
182 + path: () => `${SESSION}/execute`,
183 + body: { tool_slug: 'SLACK_SEND_MESSAGE', arguments: SLACK_ARGUMENTS },
184 + project: 'consumer',
185 + prepare: withConnectedConsumerSession,
186 + },
187 + {
188 + operation: 'toolRouter.session.executeMeta',
189 + variant: 'completed',
190 + method: 'POST',
191 + path: () => `${SESSION}/execute_meta`,
192 + body: { slug: 'COMPOSIO_SEARCH_TOOLS', arguments: {} },
193 + project: 'consumer',
194 + prepare: withConsumerSession,
195 + },
196 + {
197 + operation: 'toolRouter.session.link',
198 + variant: 'new connection',
199 + method: 'POST',
200 + path: () => `${SESSION}/link`,
201 + body: { toolkit: 'slack' },
202 + project: 'consumer',
203 + expectStatus: 201,
204 + prepare: withConsumerSession,
205 + },
206 + {
207 + operation: 'toolRouter.session.toolkits',
208 + variant: 'one connected',
209 + method: 'GET',
210 + path: () => `${SESSION}/toolkits`,
211 + project: 'consumer',
212 + prepare: withConnectedConsumerSession,
213 + },
214 + {
215 + operation: 'authConfigs.list',
216 + variant: 'managed configs',
217 + method: 'GET',
218 + path: () => '/api/v3.1/auth_configs',
219 + project: 'developer',
220 + },
221 + {
222 + operation: 'authConfigs.retrieve',
223 + variant: 'managed config',
224 + method: 'GET',
225 + path: world => `/api/v3.1/auth_configs/${world.authConfigs[0]?.id}`,
226 + project: 'developer',
227 + },
228 + {
229 + operation: 'connectedAccounts.list',
230 + variant: 'active and pending',
231 + method: 'GET',
232 + path: () => '/api/v3.1/connected_accounts',
233 + project: 'developer',
234 + prepare: world => {
235 + world.connect(DEVELOPER_PROJECT.label, GLOBAL_TEST_USER_ID, 'slack');
236 + world.linkCompletesAfterPolls = null;
237 + world.beginConnection({
238 + projectLabel: DEVELOPER_PROJECT.label,
239 + userId: GLOBAL_TEST_USER_ID,
240 + toolkit: 'github',
241 + });
242 + },
243 + },
244 + {
245 + operation: 'connectedAccounts.retrieve',
246 + variant: 'active',
247 + method: 'GET',
248 + path: world => `/api/v3.1/connected_accounts/${world.connections[0]?.id}`,
249 + project: 'developer',
250 + prepare: world => void world.connect(DEVELOPER_PROJECT.label, GLOBAL_TEST_USER_ID, 'slack'),
251 + },
252 + {
253 + operation: 'link.create',
254 + variant: 'new connection',
255 + method: 'POST',
256 + path: () => '/api/v3.1/connected_accounts/link',
257 + body: { auth_config_id: 'ac_e2e0001', user_id: GLOBAL_TEST_USER_ID },
258 + project: 'developer',
259 + expectStatus: 201,
260 + },
261 + {
262 + operation: 'tools.execute',
263 + variant: 'successful',
264 + method: 'POST',
265 + path: () => '/api/v3.1/tools/execute/SLACK_SEND_MESSAGE',
266 + body: { user_id: GLOBAL_TEST_USER_ID, arguments: SLACK_ARGUMENTS },
267 + project: 'developer',
268 + prepare: world => void world.connect(DEVELOPER_PROJECT.label, GLOBAL_TEST_USER_ID, 'slack'),
269 + },
270 +];
271 +
272 +const PROJECT_IDS = {
273 + consumer: CONSUMER_PROJECT.nanoId,
274 + developer: DEVELOPER_PROJECT.nanoId,
275 +} as const;
276 +
277 +describe('fake backend contract', () => {
278 + let fake: FakeComposio;
279 +
280 + const call = async (sample: Sample): Promise<Response> => {
281 + // A fresh world per sample: ids in sample paths assume nothing ran before.
282 + await fake?.close();
283 + fake = await startFakeComposio();
284 + sample.prepare?.(fake.world);
285 + return fetch(`${fake.host.http}${sample.path(fake.world)}`, {
286 + method: sample.method,
287 + headers: {
288 + 'content-type': 'application/json',
289 + 'x-user-api-key': USER_API_KEY,
290 + 'x-org-id': ORG.id,
291 + ...(sample.project ? { 'x-project-id': PROJECT_IDS[sample.project] } : {}),
292 + },
293 + body: sample.body === undefined ? undefined : JSON.stringify(sample.body),
294 + });
295 + };
296 +
297 + beforeAll(async () => {
298 + fake = await startFakeComposio();
299 + });
300 +
301 + afterAll(async () => {
302 + await fake.close();
303 + });
304 +
305 + for (const sample of SAMPLES) {
306 + it(`${sample.operation} (${sample.variant}) decodes with the client's schema`, async () => {
307 + const response = await call(sample);
308 + const json: unknown = await response.json();
309 + expect({ status: response.status, json }).toMatchObject({
310 + status: sample.expectStatus ?? 200,
311 + });
312 + expect(fake.journal.entries().at(-1)?.route).toBe(sample.operation);
313 +
314 + const schema = await schemaLoaders[sample.operation]();
315 + // Throws with the path of the first field the client would reject.
316 + decodeWith(schema, json);
317 + });
318 + }
319 +
320 + it('has a sample for every route that claims a client operation', () => {
321 + const sampled = new Set<string>(SAMPLES.map(sample => sample.operation));
322 + const unsampled = ROUTES.filter(route => route.typed && !sampled.has(route.name)).map(
323 + route => route.name
324 + );
325 + expect(unsampled).toEqual([]);
326 + });
327 +
328 + it('names only real client operations on typed routes', () => {
329 + const unknown = ROUTES.filter(route => route.typed && !isOperationName(route.name)).map(
330 + route => route.name
331 + );
332 + expect(unknown).toEqual([]);
333 + });
334 +
335 + it('rejects a response that drifts from the client schema', async () => {
336 + // Guards the guard: a decoder that accepts anything would make this file vacuous.
337 + const schema = await schemaLoaders['toolRouter.session.link']();
338 + expect(() => decodeWith(schema, { link_token: 'lt_1' })).toThrow();
339 + });
340 +});
ts/e2e-tests/cli/fake-backend/package.json new
+33
@@ -0,0 +1,33 @@
1 +{
2 + "name": "@e2e-tests/cli-fake-backend",
3 + "version": "0.0.0",
4 + "private": true,
5 + "type": "module",
6 + "exports": {
7 + ".": {
8 + "import": {
9 + "types": "./src/index.ts",
10 + "default": "./src/index.ts"
11 + }
12 + },
13 + "./rig": {
14 + "import": {
15 + "types": "./src/rig.ts",
16 + "default": "./src/rig.ts"
17 + }
18 + }
19 + },
20 + "scripts": {
21 + "typecheck": "tsc --noEmit",
22 + "test:e2e": "bun test contract.test.ts",
23 + "test:e2e:cli": "bun test contract.test.ts"
24 + },
25 + "devDependencies": {
26 + "@composio/client": "catalog:",
27 + "@e2e-tests/utils": "workspace:*",
28 + "@types/bun": "catalog:",
29 + "effect": "catalog:",
30 + "typescript": "catalog:",
31 + "zod": "catalog:"
32 + }
33 +}
ts/e2e-tests/cli/fake-backend/src/faults.ts new
+104
@@ -0,0 +1,104 @@
1 +/**
2 + * Fault injection: a fault replaces or distorts the answer of one route.
3 + *
4 + * A fault is addressed to a route name (`toolRouter.session.execute`) or to a
5 + * `METHOD /path` pattern, and applies to the next `times` matching requests.
6 + */
7 +
8 +export type Fault =
9 + /** Answer with this status and the standard error envelope (or `body`). */
10 + | {
11 + readonly kind: 'status';
12 + readonly status: number;
13 + readonly slug?: string;
14 + readonly message?: string;
15 + readonly code?: number;
16 + readonly headers?: Readonly<Record<string, string>>;
17 + readonly body?: unknown;
18 + }
19 + /** Hold the answer back for `ms` before sending it unchanged. */
20 + | { readonly kind: 'delay'; readonly ms: number }
21 + /** Send the headers and the first bytes of the body, then drop the connection. */
22 + | { readonly kind: 'reset-mid-body' }
23 + /** Accept the request and drop the connection without answering. */
24 + | { readonly kind: 'reset' }
25 + /** 200 with a body that is not JSON. */
26 + | { readonly kind: 'malformed-json' }
27 + /** 200 with valid JSON whose shape the CLI does not expect. */
28 + | { readonly kind: 'schema-drift'; readonly transform: (body: unknown) => unknown }
29 + /** An HTML page, as a proxy or captive portal would answer. */
30 + | { readonly kind: 'html'; readonly status?: number }
31 + /** 200 with an empty body. */
32 + | { readonly kind: 'empty-body' };
33 +
34 +export interface FaultTarget {
35 + /** A route name, or a pattern tested against `METHOD /path`. */
36 + readonly route: string | RegExp;
37 + readonly fault: Fault;
38 + /** How many matching requests the fault applies to. Defaults to every one. */
39 + readonly times?: number;
40 +}
41 +
42 +interface ArmedFault {
43 + readonly target: FaultTarget;
44 + remaining: number;
45 +}
46 +
47 +export class FaultController {
48 + private armed: ArmedFault[] = [];
49 +
50 + /** Arms a fault and returns a function that disarms it. */
51 + inject(target: FaultTarget): () => void {
52 + const entry: ArmedFault = { target, remaining: target.times ?? Number.POSITIVE_INFINITY };
53 + this.armed.push(entry);
54 + return () => {
55 + this.armed = this.armed.filter(candidate => candidate !== entry);
56 + };
57 + }
58 +
59 + clear(): void {
60 + this.armed = [];
61 + }
62 +
63 + /** The fault for this request, consuming one of its uses. */
64 + take(route: string | null, method: string, path: string): Fault | undefined {
65 + const line = `${method} ${path}`;
66 + const match = this.armed.find(({ target, remaining }) => {
67 + if (remaining <= 0) return false;
68 + return typeof target.route === 'string' ? target.route === route : target.route.test(line);
69 + });
70 + if (!match) return undefined;
71 + match.remaining -= 1;
72 + return match.target.fault;
73 + }
74 +}
75 +
76 +export const describeFault = (fault: Fault): string =>
77 + fault.kind === 'status' ? `status:${fault.status}` : fault.kind;
78 +
79 +/** Fixed, so an error path prints the same request id on every run. */
80 +export const FAULT_REQUEST_ID = 'req_e2e_fault_0001';
81 +
82 +export const errorEnvelope = (params: {
83 + status: number;
84 + message: string;
85 + slug: string;
86 + code?: number;
87 + suggestedFix?: string;
88 +}) => ({
89 + error: {
90 + message: params.message,
91 + code: params.code ?? params.status,
92 + slug: params.slug,
93 + status: params.status,
94 + request_id: FAULT_REQUEST_ID,
95 + suggested_fix: params.suggestedFix ?? '',
96 + },
97 +});
98 +
99 +export const HTML_ERROR_PAGE =
100 + '<!DOCTYPE html><html><head><title>502 Bad Gateway</title></head>' +
101 + '<body><h1>502 Bad Gateway</h1><p>The upstream server is unreachable.</p></body></html>\n';
102 +
103 +/** A body no JSON parser accepts: a response cut off inside a string. */
104 +export const MALFORMED_JSON_BODY = '{"items": [{"slug": "trunc';
ts/e2e-tests/cli/fake-backend/src/index.ts new
+6
@@ -0,0 +1,6 @@
1 +export { startFakeComposio, type FakeComposio, type FakeUrls } from './server';
2 +export { summarize, type JournalEntry, type KeyClass, type ServiceRole } from './journal';
3 +export { errorEnvelope, FAULT_REQUEST_ID, type Fault, type FaultTarget } from './faults';
4 +export { ROUTES, AGENT_IDENTITY } from './routes';
5 +export type { Route, RouteContext, RouteResult } from './route';
6 +export * from './world';
ts/e2e-tests/cli/fake-backend/src/journal.ts new
+158
@@ -0,0 +1,158 @@
1 +/**
2 + * The request journal: what the fake backend received, in arrival order, with
3 + * the identity each request carried resolved against the seeded world.
4 + */
5 +
6 +import type { World } from './world';
7 +
8 +/** Which first-party service a request was meant for, told apart by its path. */
9 +export type ServiceRole =
10 + 'backend' | 'dashboard' | 'agents' | 'github-api' | 'github-download' | 'posthog' | 'unknown';
11 +
12 +/**
13 + * The kind of credential a request carried.
14 + *
15 + * - `user`: a user API key (`uk_`), from `x-user-api-key` or the Dashboard's bearer token.
16 + * - `project`: a project API key (`ak_`), from `x-api-key`.
17 + * - `agent`: a Composio agent key (`cak_`), sent to the agents service.
18 + * - `none`: no credential header at all.
19 + * - `unrecognized`: a credential whose prefix names none of the above.
20 + */
21 +export type KeyClass = 'user' | 'project' | 'agent' | 'none' | 'unrecognized';
22 +
23 +export interface JournalEntry {
24 + readonly seq: number;
25 + readonly role: ServiceRole;
26 + readonly method: string;
27 + readonly path: string;
28 + readonly query: Readonly<Record<string, string>>;
29 + /** The route that answered, e.g. `toolRouter.session.execute`; `null` when none matched. */
30 + readonly route: string | null;
31 + readonly keyClass: KeyClass;
32 + /** Whether the seeded world issued the credential. */
33 + readonly keyKnown: boolean;
34 + readonly orgId: string | null;
35 + /** The project the request acted on, as the seeded label (`consumer`, `developer`, …). */
36 + readonly project: string | null;
37 + /**
38 + * The project the request itself named, through its project key or its scope
39 + * headers; `null` when it named none. `project` can differ: a tool-router
40 + * session acts on the project it was created for, whatever the request says.
41 + */
42 + readonly requestedProject: string | null;
43 + /**
44 + * How the fake learned the project:
45 + * - `scope-headers`: `x-org-id` and `x-project-id` on a user-key request.
46 + * - `project-key`: the project API key that authenticated the request.
47 + * - `key-default`: a user key with no scope, falling back to the org's default project.
48 + * - `route`: the endpoint itself implies it (a consumer endpoint, a tool-router session).
49 + */
50 + readonly projectFrom: 'scope-headers' | 'project-key' | 'key-default' | 'route' | null;
51 + /** The user the request acted as, when the request names or implies one. */
52 + readonly userId: string | null;
53 + readonly body: unknown;
54 + readonly status: number;
55 + /** What the request changed in the world: a tool that ran, a connection that was started. */
56 + readonly effect: 'tool-executed' | 'connection-started' | null;
57 + /**
58 + * The tool that ran, for a `tool-executed` entry, whichever route ran it.
59 + * The three execute routes carry the slug and the arguments differently.
60 + */
61 + readonly tool: {
62 + readonly slug: string;
63 + readonly arguments: Readonly<Record<string, unknown>>;
64 + } | null;
65 + /** The injected fault that shaped the answer, if any. */
66 + readonly fault: string | null;
67 +}
68 +
69 +export interface RequestIdentity {
70 + readonly keyClass: KeyClass;
71 + readonly key: string | null;
72 + readonly keyKnown: boolean;
73 + readonly orgId: string | null;
74 + /** Label of the project named by `x-project-id` or owning the project key. */
75 + readonly project: string | null;
76 +}
77 +
78 +const classifyKey = (key: string): KeyClass => {
79 + if (key.startsWith('uk_') || key.startsWith('uak_')) return 'user';
80 + if (key.startsWith('ak_')) return 'project';
81 + if (key.startsWith('cak_')) return 'agent';
82 + return 'unrecognized';
83 +};
84 +
85 +const bearerToken = (headers: Headers): string | null => {
86 + const value = headers.get('authorization');
87 + if (!value) return null;
88 + const match = /^Bearer\s+(.+)$/i.exec(value);
89 + return match?.[1] ?? null;
90 +};
91 +
92 +/** Reads the credential and scope headers the CLI sends and resolves them against the world. */
93 +export const identify = (headers: Headers, world: World): RequestIdentity => {
94 + const key = headers.get('x-user-api-key') ?? headers.get('x-api-key') ?? bearerToken(headers);
95 + const orgId = headers.get('x-org-id');
96 + const scopedProject = world.findProject(headers.get('x-project-id') ?? undefined);
97 +
98 + if (key === null) {
99 + return { keyClass: 'none', key, keyKnown: false, orgId, project: scopedProject?.label ?? null };
100 + }
101 +
102 + const keyClass = classifyKey(key);
103 + if (keyClass === 'project') {
104 + const project = world.projectForApiKey(key);
105 + return {
106 + keyClass,
107 + key,
108 + keyKnown: project !== undefined,
109 + orgId: orgId ?? project?.orgId ?? null,
110 + project: project?.label ?? null,
111 + };
112 + }
113 +
114 + return {
115 + keyClass,
116 + key,
117 + keyKnown: keyClass === 'user' && key === world.userApiKey,
118 + orgId,
119 + project: scopedProject?.label ?? null,
120 + };
121 +};
122 +
123 +export class Journal {
124 + private readonly log: JournalEntry[] = [];
125 +
126 + record(entry: Omit<JournalEntry, 'seq'>): JournalEntry {
127 + const recorded = { ...entry, seq: this.log.length + 1 };
128 + this.log.push(recorded);
129 + return recorded;
130 + }
131 +
132 + /** Every entry so far. */
133 + entries(): ReadonlyArray<JournalEntry> {
134 + return [...this.log];
135 + }
136 +
137 + /** A cursor for `since`, so a test can look at one command's requests only. */
138 + mark(): number {
139 + return this.log.length;
140 + }
141 +
142 + since(mark: number): ReadonlyArray<JournalEntry> {
143 + return this.log.slice(mark);
144 + }
145 +
146 + /** Entries answered by the named route. */
147 + route(route: string): ReadonlyArray<JournalEntry> {
148 + return this.log.filter(entry => entry.route === route);
149 + }
150 +
151 + clear(): void {
152 + this.log.length = 0;
153 + }
154 +}
155 +
156 +/** `METHOD /path` per entry: a compact form for assertions and failure output. */
157 +export const summarize = (entries: ReadonlyArray<JournalEntry>): string[] =>
158 + entries.map(entry => `${entry.method} ${entry.path}`);
ts/e2e-tests/cli/fake-backend/src/main.ts new
+43
@@ -0,0 +1,43 @@
1 +/**
2 + * Runs the fake backend on its own, for poking at the CLI by hand:
3 + *
4 + * bun ts/e2e-tests/cli/fake-backend/src/main.ts
5 + *
6 + * Prints the environment to give the binary and logs each request it receives.
7 + * Pass a path to also write the Dashboard certificate there, for
8 + * `NODE_EXTRA_CA_CERTS`.
9 + */
10 +
11 +import { writeFileSync } from 'node:fs';
12 +import { startFakeComposio } from './server';
13 +
14 +const fake = await startFakeComposio();
15 +const certificatePath = process.argv[2];
16 +if (certificatePath) writeFileSync(certificatePath, fake.caCert);
17 +console.log(
18 + Object.entries(fake.cliEnv())
19 + .map(([name, value]) => `${name}=${value}`)
20 + .join('\n')
21 +);
22 +
23 +let seen = 0;
24 +setInterval(() => {
25 + for (const entry of fake.journal.since(seen)) {
26 + console.log(
27 + JSON.stringify({
28 + role: entry.role,
29 + request: `${entry.method} ${entry.path}`,
30 + query: entry.query,
31 + route: entry.route,
32 + key: entry.keyClass,
33 + org: entry.orgId,
34 + project: entry.project,
35 + via: entry.projectFrom,
36 + user: entry.userId,
37 + status: entry.status,
38 + body: entry.body,
39 + })
40 + );
41 + }
42 + seen = fake.journal.mark();
43 +}, 100);
ts/e2e-tests/cli/fake-backend/src/rig.ts new
+97
@@ -0,0 +1,97 @@
1 +/**
2 + * A CLI rig: one fake Composio deployment and one journey container whose
3 + * `composio` binary is pointed at it for every host it knows. Other outbound
4 + * traffic from the container is not blocked.
5 + */
6 +
7 +import { startJourneyContainer, type E2ETestResult, type JourneyContainer } from '@e2e-tests/utils';
8 +import type { JourneyExecOptions, JourneyOptions } from '@e2e-tests/utils';
9 +import type { JournalEntry } from './journal';
10 +import { startFakeComposio, type FakeComposio } from './server';
11 +import { USER_API_KEY } from './world';
12 +
13 +/** Where the fake Dashboard's certificate lives inside the container. */
14 +export const CA_CERT_PATH = '/etc/composio-e2e/fake-ca.pem';
15 +
16 +export interface RigOptions {
17 + /** Short name for the container, shown in `docker ps`. */
18 + label?: string;
19 + /**
20 + * `false` leaves `COMPOSIO_WEB_URL` unset, which keeps consumer executions on
21 + * the backend instead of the Dashboard. Defaults to `true`, the production path.
22 + */
23 + dashboard?: boolean;
24 + /** Extra environment for every command, applied over the rig's own. */
25 + env?: Record<string, string>;
26 + /** Host files mounted read-only into the container. */
27 + readOnlyMounts?: JourneyOptions['readOnlyMounts'];
28 +}
29 +
30 +export interface CommandResult extends E2ETestResult {
31 + /** What the fake received while the command ran, in arrival order. */
32 + readonly requests: ReadonlyArray<JournalEntry>;
33 +}
34 +
35 +export interface CliRig {
36 + readonly fake: FakeComposio;
37 + readonly journey: JourneyContainer;
38 + /** Runs a command line in the container and collects the requests it caused. */
39 + run(command: string, options?: JourneyExecOptions): Promise<CommandResult>;
40 + /** Stores the seeded user API key the way `composio login --user-api-key` does. */
41 + login(): Promise<CommandResult>;
42 + stop(): Promise<void>;
43 +}
44 +
45 +/**
46 + * The environment that keeps the binary hermetic: every host it knows is the
47 + * fake, telemetry is off, and the fake Dashboard's certificate is trusted.
48 + */
49 +export const hermeticEnv = (
50 + fake: FakeComposio,
51 + options: Pick<RigOptions, 'dashboard'> = {}
52 +): Record<string, string> => ({
53 + ...fake.cliEnv({ dashboard: options.dashboard }),
54 + COMPOSIO_CLI_TELEMETRY_DISABLED: '1',
55 + NODE_EXTRA_CA_CERTS: CA_CERT_PATH,
56 +});
57 +
58 +export const startCliRig = async (options: RigOptions = {}): Promise<CliRig> => {
59 + const fake = await startFakeComposio();
60 + let journey: JourneyContainer;
61 + try {
62 + journey = await startJourneyContainer({
63 + label: options.label,
64 + env: { ...hermeticEnv(fake, options), ...options.env },
65 + readOnlyMounts: options.readOnlyMounts,
66 + });
67 + await journey.writeFile(CA_CERT_PATH, fake.caCert);
68 + } catch (error) {
69 + await fake.close();
70 + throw error;
71 + }
72 +
73 + const run: CliRig['run'] = async (command, execOptions) => {
74 + const mark = fake.journal.mark();
75 + const result = await journey.exec(command, execOptions);
76 + return { ...result, requests: fake.journal.since(mark) };
77 + };
78 +
79 + return {
80 + fake,
81 + journey,
82 + run,
83 + login: async () => {
84 + const result = await run(`composio login --user-api-key ${USER_API_KEY} --no-skill-install`);
85 + if (result.exitCode !== 0) {
86 + throw new Error(
87 + `Rig login failed (exit ${result.exitCode})\nstdout: ${result.stdout}\nstderr: ${result.stderr}`
88 + );
89 + }
90 + return result;
91 + },
92 + stop: async () => {
93 + await journey.stop();
94 + await fake.close();
95 + },
96 + };
97 +};
ts/e2e-tests/cli/fake-backend/src/route.ts new
+120
@@ -0,0 +1,120 @@
1 +/**
2 + * The route model of the fake backend: how a request finds its handler, and
3 + * what a handler may say about the request it served.
4 + */
5 +
6 +import { errorEnvelope } from './faults';
7 +import type { RequestIdentity, ServiceRole } from './journal';
8 +import type { SeededProject, World } from './world';
9 +
10 +/** The base URLs the binary under test reaches the fake at, for links in response bodies. */
11 +export interface PublicUrls {
12 + readonly backend: string;
13 + readonly dashboard: string;
14 +}
15 +
16 +export interface RouteContext {
17 + readonly world: World;
18 + readonly identity: RequestIdentity;
19 + readonly params: Readonly<Record<string, string>>;
20 + readonly query: URLSearchParams;
21 + /** The parsed JSON body, or `undefined` when there is none. Parse it with zod before use. */
22 + readonly body: unknown;
23 + readonly headers: Headers;
24 + readonly urls: PublicUrls;
25 + /** The project the request is scoped to; set for `auth: 'project'` routes. */
26 + readonly project: SeededProject | undefined;
27 +}
28 +
29 +export type RouteEffect = 'tool-executed' | 'connection-started';
30 +
31 +export interface ExecutedTool {
32 + readonly slug: string;
33 + readonly arguments: Readonly<Record<string, unknown>>;
34 +}
35 +
36 +export interface RouteResult {
37 + readonly status?: number;
38 + readonly json?: unknown;
39 + readonly text?: string;
40 + readonly bytes?: Uint8Array;
41 + readonly headers?: Readonly<Record<string, string>>;
42 + /**
43 + * What the request changed, when it changed something. A Dashboard execution
44 + * answers 200 whether or not the tool ran, so a status alone cannot tell.
45 + */
46 + readonly effect?: RouteEffect;
47 + /** The tool a `tool-executed` request ran, with the arguments it ran with. */
48 + readonly tool?: ExecutedTool;
49 + /** Overrides the journal's project and user for this request (a session implies both). */
50 + readonly acted?: { readonly project?: string | null; readonly userId?: string | null };
51 +}
52 +
53 +/**
54 + * Who may call a route.
55 + *
56 + * - `none`: no credential needed.
57 + * - `user`: the seeded user API key.
58 + * - `key`: any credential the world issued; catalog reads need no project.
59 + * - `project`: a project API key, or the user API key with `x-org-id` and `x-project-id`.
60 + */
61 +export type RouteAuth = 'none' | 'user' | 'key' | 'project';
62 +
63 +export interface Route {
64 + /**
65 + * The client operation the route implements (`toolRouter.session.execute`),
66 + * or a name of its own for endpoints `@composio/client` does not type.
67 + */
68 + readonly name: string;
69 + readonly role: ServiceRole;
70 + readonly method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
71 + /** Path template; `:name` captures one segment. `/api/:v/` accepts `v3` and `v3.1`. */
72 + readonly path: string;
73 + /**
74 + * Whether `name` is a key of the client's response schema table, which the
75 + * contract test decodes this route's success response with.
76 + */
77 + readonly typed: boolean;
78 + readonly auth: RouteAuth;
79 + readonly handle: (context: RouteContext) => RouteResult;
80 +}
81 +
82 +const API_VERSIONS = new Set(['v3', 'v3.1']);
83 +
84 +/** The captures of `path` against `template`, or `undefined` when it does not match. */
85 +export const matchPath = (template: string, path: string): Record<string, string> | undefined => {
86 + const wanted = template.split('/');
87 + const actual = path.split('/');
88 + if (wanted.length !== actual.length) return undefined;
89 + const params: Record<string, string> = {};
90 + for (const [index, segment] of wanted.entries()) {
91 + const value = actual[index] ?? '';
92 + if (segment.startsWith(':')) {
93 + if (value === '') return undefined;
94 + if (segment === ':v' && !API_VERSIONS.has(value)) return undefined;
95 + params[segment.slice(1)] = decodeURIComponent(value);
96 + } else if (segment !== value) {
97 + return undefined;
98 + }
99 + }
100 + return params;
101 +};
102 +
103 +export const notFound = (message: string, slug = 'Resource_NotFound'): RouteResult => ({
104 + status: 404,
105 + json: errorEnvelope({ status: 404, message, slug }),
106 +});
107 +
108 +export const badRequest = (message: string, slug = 'Request_Invalid'): RouteResult => ({
109 + status: 400,
110 + json: errorEnvelope({ status: 400, message, slug }),
111 +});
112 +
113 +/** One page holding every item: the seeded lists never need a second one. */
114 +export const singlePage = <T>(items: ReadonlyArray<T>) => ({
115 + items,
116 + next_cursor: null,
117 + total_pages: 1,
118 + current_page: 1,
119 + total_items: items.length,
120 +});
ts/e2e-tests/cli/fake-backend/src/routes.ts new
+1205
@@ -0,0 +1,1205 @@
1 +/**
2 + * Every route the fake backend answers.
3 + *
4 + * A route named after a `@composio/client` operation (`typed: true`) answers
5 + * with the shape that operation's response schema describes; the contract test
6 + * decodes each one with the client's own schema.
7 + */
8 +
9 +import { z } from 'zod';
10 +import { errorEnvelope } from './faults';
11 +import { badRequest, notFound, singlePage, type Route, type RouteContext } from './route';
12 +import {
13 + CONSUMER_PROJECT,
14 + CONSUMER_USER_ID,
15 + MEMBER,
16 + SEEDED_AT,
17 + SEEDED_EXPIRY,
18 + type AuthConfig,
19 + type Connection,
20 + type Release,
21 + type SeededProject,
22 + type SeededTool,
23 + type SeededToolkit,
24 + type World,
25 +} from './world';
26 +
27 +const LOGO = 'https://logos.composio.test/toolkit.svg';
28 +
29 +// --- request bodies -----------------------------------------------------------
30 +
31 +const SessionCreateBody = z.looseObject({ user_id: z.string() });
32 +const SearchBody = z.looseObject({
33 + queries: z.array(z.looseObject({ use_case: z.string() })).optional(),
34 +});
35 +const ExecuteBody = z.looseObject({
36 + tool_slug: z.string(),
37 + arguments: z.record(z.string(), z.unknown()).optional(),
38 + account: z.string().optional(),
39 +});
40 +const ExecuteMetaBody = z.looseObject({
41 + slug: z.string(),
42 + arguments: z.record(z.string(), z.unknown()).optional(),
43 +});
44 +const SessionLinkBody = z.looseObject({ toolkit: z.string(), alias: z.string().optional() });
45 +const LinkCreateBody = z.looseObject({
46 + auth_config_id: z.string(),
47 + user_id: z.string(),
48 + alias: z.string().optional(),
49 +});
50 +const DirectExecuteBody = z.looseObject({
51 + user_id: z.string().optional(),
52 + arguments: z.record(z.string(), z.unknown()).optional(),
53 + connected_account_id: z.string().optional(),
54 +});
55 +const ApiKeyCreateBody = z.looseObject({ name: z.string() });
56 +const TrpcBody = z.object({ json: z.record(z.string(), z.unknown()) });
57 +
58 +// --- response builders --------------------------------------------------------
59 +
60 +const projectDetails = (project: SeededProject, world: World) => ({
61 + auto_id: project.autoId,
62 + id: project.uuid,
63 + org_id: project.orgId,
64 + name: project.name,
65 + email: `${project.name}@projects.composio.test`,
66 + nano_id: project.nanoId,
67 + created_at: SEEDED_AT,
68 + updated_at: SEEDED_AT,
69 + webhook_url: null,
70 + event_webhook_url: null,
71 + webhook_secret: null,
72 + triggers_enabled: true,
73 + last_subscribed_at: null,
74 + deleted: false,
75 + is_new_webhook: true,
76 + webhook_version: 'V3',
77 + org: { id: world.org.id, name: world.org.name, plan: world.org.plan },
78 +});
79 +
80 +const toolkitListItem = (toolkit: SeededToolkit, world: World) => ({
81 + slug: toolkit.slug,
82 + name: toolkit.name,
83 + type: 'native',
84 + app: toolkit.slug,
85 + toolkit_type: 'api',
86 + is_local_toolkit: false,
87 + auth_schemes: toolkit.noAuth ? [] : ['OAUTH2'],
88 + composio_managed_auth_schemes: toolkit.noAuth ? [] : ['OAUTH2'],
89 + no_auth: toolkit.noAuth,
90 + deprecated: { toolkitId: `tk_${toolkit.slug}` },
91 + meta: {
92 + created_at: SEEDED_AT,
93 + updated_at: SEEDED_AT,
94 + description: toolkit.description,
95 + logo: LOGO,
96 + categories: [],
97 + triggers_count: 0,
98 + tools_count: world.tools.filter(tool => tool.toolkit === toolkit.slug).length,
99 + version: toolkit.version,
100 + available_versions: [toolkit.version],
101 + },
102 +});
103 +
104 +const toolkitDetails = (toolkit: SeededToolkit, world: World) => ({
105 + slug: toolkit.slug,
106 + name: toolkit.name,
107 + type: 'native',
108 + enabled: true,
109 + no_auth: toolkit.noAuth,
110 + composio_managed_auth_schemes: toolkit.noAuth ? [] : ['OAUTH2'],
111 + composio_managed_auth: toolkit.noAuth
112 + ? []
113 + : [
114 + {
115 + managed_app_id: `ma_${toolkit.slug}`,
116 + is_default: true,
117 + mode: 'OAUTH2',
118 + scopes: { available: [] },
119 + },
120 + ],
121 + is_local_toolkit: false,
122 + auth_config_details: toolkit.noAuth
123 + ? []
124 + : [
125 + {
126 + mode: 'OAUTH2',
127 + name: 'OAuth 2.0',
128 + required_scopes: [],
129 + fields: {
130 + auth_config_creation: { required: [], optional: [] },
131 + connected_account_initiation: { required: [], optional: [] },
132 + },
133 + },
134 + ],
135 + meta: {
136 + created_at: SEEDED_AT,
137 + updated_at: SEEDED_AT,
138 + description: toolkit.description,
139 + logo: LOGO,
140 + categories: [],
141 + triggers_count: 0,
142 + tools_count: world.tools.filter(tool => tool.toolkit === toolkit.slug).length,
143 + version: toolkit.version,
144 + available_versions: [toolkit.version],
145 + },
146 + deprecated: { toolkitId: `tk_${toolkit.slug}`, rawProxyInfoByAuthSchemes: [] },
147 +});
148 +
149 +const toolDetails = (tool: SeededTool, world: World) => {
150 + const toolkit = world.findToolkit(tool.toolkit);
151 + const version = toolkit?.version ?? 'latest';
152 + return {
153 + slug: tool.slug,
154 + name: tool.name,
155 + description: tool.description,
156 + toolkit: { slug: tool.toolkit, name: toolkit?.name ?? tool.toolkit, logo: LOGO },
157 + input_parameters: tool.inputParameters,
158 + no_auth: toolkit?.noAuth ?? false,
159 + available_versions: [version],
160 + version,
161 + output_parameters: { type: 'object', properties: {} },
162 + scopes: [],
163 + scope_requirements: null,
164 + tags: [],
165 + is_deprecated: false,
166 + deprecated: {
167 + displayName: tool.name,
168 + version,
169 + available_versions: [version],
170 + is_deprecated: false,
171 + toolkit: { logo: LOGO },
172 + },
173 + };
174 +};
175 +
176 +const connectedAccount = (connection: Connection, urls: RouteContext['urls']) => {
177 + if (connection.status === 'ACTIVE') connection.reportedActive = true;
178 + return {
179 + toolkit: { slug: connection.toolkit },
180 + auth_config: {
181 + id: connection.authConfigId,
182 + auth_scheme: 'OAUTH2',
183 + is_composio_managed: true,
184 + is_disabled: false,
185 + },
186 + id: connection.id,
187 + word_id: connection.wordId,
188 + alias: connection.alias,
189 + user_id: connection.userId,
190 + status: connection.status,
191 + created_at: SEEDED_AT,
192 + updated_at: SEEDED_AT,
193 + state:
194 + connection.status === 'ACTIVE'
195 + ? {
196 + authScheme: 'OAUTH2',
197 + val: { status: 'ACTIVE', access_token: 'REDACTED', token_type: 'Bearer' },
198 + }
199 + : {
200 + authScheme: 'OAUTH2',
201 + val: { status: 'INITIATED', redirectUrl: redirectUrl(urls, connection) },
202 + },
203 + data: {},
204 + params: {},
205 + status_reason: null,
206 + is_disabled: false,
207 + test_request_endpoint: '',
208 + deprecated: { labels: [], uuid: `00000000-0000-4000-8000-${connection.id.padStart(12, '0')}` },
209 + };
210 +};
211 +
212 +const authConfigItem = (authConfig: AuthConfig, world: World) => ({
213 + id: authConfig.id,
214 + uuid: authConfig.uuid,
215 + type: 'default',
216 + toolkit: { slug: authConfig.toolkit, logo: LOGO },
217 + name: authConfig.name,
218 + auth_scheme: 'OAUTH2',
219 + is_composio_managed: true,
220 + status: 'ENABLED',
221 + created_by: MEMBER.id,
222 + created_at: SEEDED_AT,
223 + last_updated_at: SEEDED_AT,
224 + no_of_connections: world.connections.filter(c => c.authConfigId === authConfig.id).length,
225 + tool_access_config: {
226 + tools_for_connected_account_creation: [],
227 + tools_available_for_execution: [],
228 + },
229 +});
230 +
231 +const redirectUrl = (urls: RouteContext['urls'], connection: Connection) =>
232 + `${urls.backend}/api/v3/s/${connection.id}`;
233 +
234 +const noActiveConnection = (toolkit: string) => ({
235 + status: 400,
236 + json: errorEnvelope({
237 + status: 400,
238 + code: 4302,
239 + slug: 'ToolRouterV2_NoActiveConnection',
240 + message: `No active connection found for toolkit ${toolkit}`,
241 + suggestedFix: `Connect ${toolkit} before executing this tool`,
242 + }),
243 +});
244 +
245 +const unknownTool = (slug: string) => notFound(`Tool ${slug} not found`, 'Tool_ToolNotFound');
246 +
247 +/** The session named in the path, with the project and user it was created for. */
248 +const sessionOf = (context: RouteContext) =>
249 + context.world.toolRouterSessions.find(session => session.id === context.params.sessionId);
250 +
251 +const unknownSession = (context: RouteContext) =>
252 + notFound(
253 + `Tool router session ${context.params.sessionId} not found`,
254 + 'ToolRouterV2_SessionNotFound'
255 + );
256 +
257 +/**
258 + * Runs a tool for a user on a project: the connection check and the tool's
259 + * canned answer. Shared by the session, Dashboard, and direct execute routes.
260 + */
261 +const runTool = (
262 + world: World,
263 + params: { projectLabel: string; userId: string; slug: string; args: Record<string, unknown> }
264 +):
265 + | { kind: 'unknown-tool' }
266 + | { kind: 'not-connected'; toolkit: string }
267 + | { kind: 'ran'; data: Record<string, unknown>; logId: string } => {
268 + const tool = world.findTool(params.slug);
269 + if (!tool) return { kind: 'unknown-tool' };
270 + const toolkit = world.findToolkit(tool.toolkit);
271 + if (
272 + !toolkit?.noAuth &&
273 + !world.reportActiveConnection(params.projectLabel, params.userId, tool.toolkit)
274 + ) {
275 + return { kind: 'not-connected', toolkit: tool.toolkit };
276 + }
277 + return { kind: 'ran', data: tool.respond(params.args), logId: world.nextLogId() };
278 +};
279 +
280 +const searchResponse = (
281 + context: RouteContext,
282 + session: { id: string; projectLabel: string; userId: string },
283 + useCases: ReadonlyArray<string>
284 +) => {
285 + const { world } = context;
286 + const matches = useCases.map(useCase => {
287 + const words = useCase
288 + .toLowerCase()
289 + .split(/[^a-z0-9]+/)
290 + .filter(word => word.length > 2);
291 + const tools = world.tools.filter(tool => {
292 + const haystack =
293 + `${tool.slug} ${tool.name} ${tool.description} ${tool.toolkit}`.toLowerCase();
294 + return words.some(word => haystack.includes(word));
295 + });
296 + // Toolkit names outrank incidental word overlap ("send" matches Slack and Gmail).
297 + const named = tools.filter(tool => words.includes(tool.toolkit));
298 + return { useCase, tools: named.length > 0 ? named : tools };
299 + });
300 + const toolkits = [...new Set(matches.flatMap(match => match.tools.map(tool => tool.toolkit)))];
301 + const allTools = [...new Set(matches.flatMap(match => match.tools))];
302 +
303 + return {
304 + success: true,
305 + error: null,
306 + results: matches.map((match, index) => ({
307 + index: index + 1,
308 + use_case: match.useCase,
309 + execution_guidance: 'Execute the primary tool with the documented arguments.',
310 + primary_tool_slugs: match.tools.slice(0, 1).map(tool => tool.slug),
311 + related_tool_slugs: match.tools.slice(1).map(tool => tool.slug),
312 + toolkits: [...new Set(match.tools.map(tool => tool.toolkit))],
313 + })),
314 + toolkit_connection_statuses: toolkits.map(slug => {
315 + const toolkit = world.findToolkit(slug);
316 + const connection = world.reportActiveConnection(session.projectLabel, session.userId, slug);
317 + const connected = toolkit?.noAuth === true || connection !== undefined;
318 + return {
319 + toolkit: slug,
320 + description: toolkit?.description ?? '',
321 + has_active_connection: connected,
322 + status_message: connected
323 + ? `${slug} is connected`
324 + : `No active connection for ${slug}. Initiate a connection before executing its tools.`,
325 + };
326 + }),
327 + tool_schemas: Object.fromEntries(
328 + allTools.map(tool => [
329 + tool.slug,
330 + {
331 + tool_slug: tool.slug,
332 + toolkit: tool.toolkit,
333 + description: tool.description,
334 + input_schema: tool.inputParameters,
335 + hasFullSchema: true,
336 + },
337 + ])
338 + ),
339 + time_info: {
340 + current_time_utc: SEEDED_AT,
341 + current_time_utc_epoch_seconds: Date.parse(SEEDED_AT) / 1000,
342 + message: 'Fixed time of the fake backend.',
343 + },
344 + session: { id: session.id, generate_id: false, instructions: 'Reuse this session id.' },
345 + next_steps_guidance: ['Execute the primary tool slug for each use case.'],
346 + };
347 +};
348 +
349 +// --- routes -------------------------------------------------------------------
350 +
351 +const backend = (route: Omit<Route, 'role'>): Route => ({ ...route, role: 'backend' });
352 +
353 +const ACCOUNT_ROUTES: ReadonlyArray<Route> = [
354 + backend({
355 + name: 'auth.session.retrieveInfo',
356 + method: 'GET',
357 + path: '/api/:v/auth/session/info',
358 + typed: true,
359 + auth: 'user',
360 + handle: ({ world, project }) => ({
361 + json: {
362 + // A user key belongs to no project, so the org's default developer
363 + // project is reported, never the consumer project: a command that
364 + // reuses this id instead of resolving the consumer project shows up in
365 + // the journal as acting on the wrong project.
366 + project: projectDetails(project ?? world.defaultProject, world),
367 + api_key: null,
368 + org_member: {
369 + id: world.member.id,
370 + email: world.member.email,
371 + name: world.member.name,
372 + role: world.member.role,
373 + metadata: {},
374 + },
375 + },
376 + }),
377 + }),
378 + backend({
379 + name: 'org.list',
380 + method: 'GET',
381 + path: '/api/:v/org/list',
382 + typed: true,
383 + auth: 'user',
384 + handle: ({ world }) => ({
385 + json: {
386 + organizations: world.organizations.map(org => ({
387 + id: org.id,
388 + name: org.name,
389 + created_at: SEEDED_AT,
390 + updated_at: SEEDED_AT,
391 + })),
392 + next_cursor: null,
393 + total_pages: 1,
394 + current_page: 1,
395 + total_items: world.organizations.length,
396 + },
397 + }),
398 + }),
399 + backend({
400 + name: 'org.project.list',
401 + method: 'GET',
402 + path: '/api/:v/org/project/list',
403 + typed: true,
404 + auth: 'user',
405 + handle: ({ world, identity }) => {
406 + const projects = world.projects.filter(
407 + project =>
408 + project.kind === 'developer' && project.orgId === (identity.orgId ?? world.org.id)
409 + );
410 + return {
411 + json: {
412 + data: projects.map(project => ({
413 + id: project.nanoId,
414 + org_id: project.orgId,
415 + name: project.name,
416 + email: `${project.name}@projects.composio.test`,
417 + created_at: SEEDED_AT,
418 + updated_at: SEEDED_AT,
419 + webhook_url: null,
420 + event_webhook_url: null,
421 + webhook_secret: null,
422 + triggers_enabled: true,
423 + last_subscribed_at: null,
424 + is_new_webhook: true,
425 + webhook_version: 'V3',
426 + deleted: false,
427 + })),
428 + next_cursor: null,
429 + total_pages: 1,
430 + current_page: 1,
431 + total_items: projects.length,
432 + },
433 + };
434 + },
435 + }),
436 + backend({
437 + name: 'org.project.apiKeys.create',
438 + method: 'POST',
439 + path: '/api/:v/org/project/:projectId/api_keys/create',
440 + typed: false,
441 + auth: 'user',
442 + handle: ({ world, params, body }) => {
443 + const project = world.findProject(params.projectId);
444 + if (!project) return notFound(`Project ${params.projectId} not found`, 'Project_NotFound');
445 + const { name } = ApiKeyCreateBody.parse(body);
446 + const key = world.mintProjectKey(project.label, name);
447 + return {
448 + json: { id: `key_${world.mintedProjectKeys.length}`, name, key, created_at: SEEDED_AT },
449 + acted: { project: project.label },
450 + };
451 + },
452 + }),
453 + backend({
454 + name: '_internal.org.consumer.project.resolve',
455 + method: 'POST',
456 + path: '/api/:v/org/consumer/project/resolve',
457 + typed: true,
458 + auth: 'user',
459 + handle: ({ identity }) => ({
460 + json: {
461 + project_id: CONSUMER_PROJECT.uuid,
462 + project_nano_id: CONSUMER_PROJECT.nanoId,
463 + project_name: CONSUMER_PROJECT.name,
464 + org_id: identity.orgId ?? CONSUMER_PROJECT.orgId,
465 + project_type: 'CONSUMER',
466 + config: {
467 + consumer_experience_enabled: true,
468 + enhanced_controls: false,
469 + enable_instant: false,
470 + },
471 + consumer_user_id: CONSUMER_USER_ID,
472 + user_id: MEMBER.id,
473 + },
474 + acted: { project: CONSUMER_PROJECT.label, userId: CONSUMER_USER_ID },
475 + }),
476 + }),
477 + backend({
478 + name: '_internal.org.consumer.listConnectedToolkits',
479 + method: 'GET',
480 + path: '/api/:v/org/consumer/connected_toolkits',
481 + typed: true,
482 + auth: 'user',
483 + handle: ({ world, query }) => {
484 + const userId = query.get('user_id') ?? CONSUMER_USER_ID;
485 + const toolkits = world.connections
486 + .filter(
487 + connection =>
488 + connection.projectLabel === CONSUMER_PROJECT.label &&
489 + connection.userId === userId &&
490 + connection.status === 'ACTIVE'
491 + )
492 + .map(connection => connection.toolkit);
493 + return {
494 + json: { toolkits: [...new Set(toolkits)] },
495 + acted: { project: CONSUMER_PROJECT.label, userId },
496 + };
497 + },
498 + }),
499 + backend({
500 + name: '_internal.org.consumer.retrieveConfig',
501 + method: 'GET',
502 + path: '/api/:v/org/consumer/config',
503 + typed: true,
504 + auth: 'user',
505 + handle: ({ world, identity }) => ({
506 + json: {
507 + org_id: identity.orgId ?? world.org.id,
508 + consumer_experience_enabled: true,
509 + enhanced_controls: false,
510 + },
511 + }),
512 + }),
513 + backend({
514 + name: '_internal.consumer.permissions.resolve',
515 + method: 'POST',
516 + path: '/api/:v/consumer/permissions/resolve',
517 + typed: true,
518 + auth: 'user',
519 + handle: () => ({
520 + json: { experimental: { permissions: { default: 'allow_all', overrides: {} } } },
521 + }),
522 + }),
523 +];
524 +
525 +const LOGIN_ROUTES: ReadonlyArray<Route> = [
526 + backend({
527 + name: '_internal.cli.createSession',
528 + method: 'POST',
529 + path: '/api/:v/cli/create-session',
530 + typed: true,
531 + auth: 'none',
532 + handle: ({ world }) => {
533 + const session = world.createLoginSession();
534 + return {
535 + json: {
536 + id: session.id,
537 + code: session.code,
538 + expiresAt: SEEDED_EXPIRY,
539 + status: session.status,
540 + scope: 'user',
541 + },
542 + };
543 + },
544 + }),
545 + backend({
546 + name: '_internal.cli.getSession',
547 + method: 'GET',
548 + path: '/api/:v/cli/get-session',
549 + typed: true,
550 + auth: 'none',
551 + handle: ({ world, query }) => {
552 + const reference = query.get('id') ?? query.get('code') ?? '';
553 + const session = world.loginSessions.find(s => s.id === reference || s.code === reference);
554 + if (!session) return notFound(`CLI session ${reference} not found`, 'Cli_SessionNotFound');
555 + const linked = session.status === 'linked';
556 + if (linked) session.reportedLinked = true;
557 + return {
558 + json: {
559 + id: session.id,
560 + code: session.code,
561 + status: session.status,
562 + expiresAt: SEEDED_EXPIRY,
563 + account: linked
564 + ? { id: world.member.id, email: world.member.email, name: world.member.name }
565 + : null,
566 + api_key: linked ? world.userApiKey : null,
567 + scope: 'user',
568 + },
569 + };
570 + },
571 + }),
572 + backend({
573 + // The page a link's `redirect_url` points at. Whoever opens it is the
574 + // account's owner at the consent screen, and opening it is their approval.
575 + name: 'connectedAccounts.authorizationPage',
576 + method: 'GET',
577 + path: '/api/:v/s/:id',
578 + typed: false,
579 + auth: 'none',
580 + handle: ({ world, params }) =>
581 + world.authorizeConnection(params.id ?? '')
582 + ? { text: 'Authorized. You can close this tab.' }
583 + : notFound(`No pending authorization ${params.id}`, 'ConnectedAccount_NotFound'),
584 + }),
585 + backend({
586 + name: 'cli.analytics',
587 + method: 'POST',
588 + path: '/api/:v/cli/analytics',
589 + typed: false,
590 + auth: 'none',
591 + handle: () => ({ status: 204 }),
592 + }),
593 +];
594 +
595 +const CATALOG_ROUTES: ReadonlyArray<Route> = [
596 + backend({
597 + name: 'toolkits.list',
598 + method: 'GET',
599 + path: '/api/:v/toolkits',
600 + typed: true,
601 + auth: 'key',
602 + handle: ({ world, query }) => {
603 + const search = query.get('search')?.toLowerCase();
604 + const items = world.toolkits
605 + .filter(toolkit => !search || toolkit.slug.startsWith(search))
606 + .map(toolkit => toolkitListItem(toolkit, world));
607 + return { json: singlePage(items) };
608 + },
609 + }),
610 + backend({
611 + name: 'toolkits.retrieve',
612 + method: 'GET',
613 + path: '/api/:v/toolkits/:slug',
614 + typed: true,
615 + auth: 'key',
616 + handle: ({ world, params }) => {
617 + const toolkit = world.findToolkit(params.slug ?? '');
618 + return toolkit
619 + ? { json: toolkitDetails(toolkit, world) }
620 + : notFound(`Toolkit ${params.slug} not found`, 'Toolkit_NotFound');
621 + },
622 + }),
623 + backend({
624 + name: 'tools.list',
625 + method: 'GET',
626 + path: '/api/:v/tools',
627 + typed: true,
628 + auth: 'key',
629 + handle: ({ world, query }) => {
630 + const toolkit = query.get('toolkit_slug')?.toLowerCase();
631 + const slugs = query.get('tool_slugs')?.toUpperCase().split(',');
632 + const items = world.tools
633 + .filter(tool => !toolkit || tool.toolkit === toolkit)
634 + .filter(tool => !slugs || slugs.includes(tool.slug))
635 + .map(tool => toolDetails(tool, world));
636 + return { json: singlePage(items) };
637 + },
638 + }),
639 + backend({
640 + name: 'tools.getLatestVersion',
641 + method: 'GET',
642 + path: '/api/:v/tools/:slug/get_latest_version',
643 + typed: false,
644 + auth: 'key',
645 + handle: ({ world, params }) => {
646 + const tool = world.findTool(params.slug ?? '');
647 + if (!tool) return unknownTool(params.slug ?? '');
648 + return {
649 + json: {
650 + slug: tool.slug,
651 + toolkit: tool.toolkit,
652 + version: world.findToolkit(tool.toolkit)?.version ?? 'latest',
653 + },
654 + };
655 + },
656 + }),
657 + backend({
658 + name: 'tools.retrieve',
659 + method: 'GET',
660 + path: '/api/:v/tools/:slug',
661 + typed: true,
662 + auth: 'key',
663 + handle: ({ world, params }) => {
664 + const tool = world.findTool(params.slug ?? '');
665 + return tool ? { json: toolDetails(tool, world) } : unknownTool(params.slug ?? '');
666 + },
667 + }),
668 +];
669 +
670 +const SESSION_ROUTES: ReadonlyArray<Route> = [
671 + backend({
672 + name: 'toolRouter.session.create',
673 + method: 'POST',
674 + path: '/api/:v/tool_router/session',
675 + typed: true,
676 + auth: 'project',
677 + handle: ({ world, body, project, urls }) => {
678 + const { user_id: userId } = SessionCreateBody.parse(body);
679 + const session = world.createToolRouterSession(project!.label, userId);
680 + return {
681 + status: 201,
682 + json: {
683 + session_id: session.id,
684 + mcp: { type: 'http', url: `${urls.backend}/tool_router/${session.id}/mcp` },
685 + tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'COMPOSIO_MULTI_EXECUTE_TOOL'],
686 + config: {
687 + user_id: userId,
688 + instant: false,
689 + preload: { tools: [] },
690 + search: { enable: true },
691 + execute: { enable_multi_execute: true },
692 + },
693 + config_version: 1,
694 + },
695 + acted: { project: project!.label, userId },
696 + };
697 + },
698 + }),
699 + backend({
700 + name: 'toolRouter.session.search',
701 + method: 'POST',
702 + path: '/api/:v/tool_router/session/:sessionId/search',
703 + typed: true,
704 + auth: 'project',
705 + handle: context => {
706 + const session = sessionOf(context);
707 + if (!session) return unknownSession(context);
708 + const { queries } = SearchBody.parse(context.body);
709 + return {
710 + json: searchResponse(
711 + context,
712 + session,
713 + (queries ?? []).map(query => query.use_case)
714 + ),
715 + acted: { project: session.projectLabel, userId: session.userId },
716 + };
717 + },
718 + }),
719 + backend({
720 + name: 'toolRouter.session.execute',
721 + method: 'POST',
722 + path: '/api/:v/tool_router/session/:sessionId/execute',
723 + typed: true,
724 + auth: 'project',
725 + handle: context => {
726 + const session = sessionOf(context);
727 + if (!session) return unknownSession(context);
728 + const request = ExecuteBody.parse(context.body);
729 + const acted = { project: session.projectLabel, userId: session.userId };
730 + const outcome = runTool(context.world, {
731 + projectLabel: session.projectLabel,
732 + userId: session.userId,
733 + slug: request.tool_slug,
734 + args: request.arguments ?? {},
735 + });
736 + if (outcome.kind === 'unknown-tool') return { ...unknownTool(request.tool_slug), acted };
737 + if (outcome.kind === 'not-connected')
738 + return { ...noActiveConnection(outcome.toolkit), acted };
739 + return {
740 + json: { result_type: 'completed', data: outcome.data, error: null, log_id: outcome.logId },
741 + acted,
742 + effect: 'tool-executed',
743 + tool: { slug: request.tool_slug, arguments: request.arguments ?? {} },
744 + };
745 + },
746 + }),
747 + backend({
748 + name: 'toolRouter.session.executeMeta',
749 + method: 'POST',
750 + path: '/api/:v/tool_router/session/:sessionId/execute_meta',
751 + typed: true,
752 + auth: 'project',
753 + handle: context => {
754 + const session = sessionOf(context);
755 + if (!session) return unknownSession(context);
756 + const request = ExecuteMetaBody.parse(context.body);
757 + return {
758 + json: {
759 + result_type: 'completed',
760 + data: { slug: request.slug, echoed_arguments: request.arguments ?? {} },
761 + error: null,
762 + log_id: context.world.nextLogId(),
763 + },
764 + acted: { project: session.projectLabel, userId: session.userId },
765 + };
766 + },
767 + }),
768 + backend({
769 + name: 'toolRouter.session.link',
770 + method: 'POST',
771 + path: '/api/:v/tool_router/session/:sessionId/link',
772 + typed: true,
773 + auth: 'project',
774 + handle: context => {
775 + const session = sessionOf(context);
776 + if (!session) return unknownSession(context);
777 + const request = SessionLinkBody.parse(context.body);
778 + const toolkit = context.world.findToolkit(request.toolkit);
779 + if (!toolkit) return notFound(`Toolkit ${request.toolkit} not found`, 'Toolkit_NotFound');
780 + const connection = context.world.beginConnection({
781 + projectLabel: session.projectLabel,
782 + userId: session.userId,
783 + toolkit: toolkit.slug,
784 + alias: request.alias,
785 + });
786 + return {
787 + status: 201,
788 + json: {
789 + link_token: `lt_${connection.id}`,
790 + redirect_url: redirectUrl(context.urls, connection),
791 + connected_account_id: connection.id,
792 + },
793 + acted: { project: session.projectLabel, userId: session.userId },
794 + effect: 'connection-started',
795 + };
796 + },
797 + }),
798 + backend({
799 + name: 'toolRouter.session.toolkits',
800 + method: 'GET',
801 + path: '/api/:v/tool_router/session/:sessionId/toolkits',
802 + typed: true,
803 + auth: 'project',
804 + handle: context => {
805 + const session = sessionOf(context);
806 + if (!session) return unknownSession(context);
807 + const { world } = context;
808 + const wanted = context.query.get('toolkits')?.toLowerCase().split(',');
809 + const items = world.toolkits
810 + .filter(toolkit => !wanted || wanted.includes(toolkit.slug))
811 + .map(toolkit => {
812 + const connection = world.reportActiveConnection(
813 + session.projectLabel,
814 + session.userId,
815 + toolkit.slug
816 + );
817 + return {
818 + name: toolkit.name,
819 + slug: toolkit.slug,
820 + enabled: true,
821 + is_no_auth: toolkit.noAuth,
822 + composio_managed_auth_schemes: toolkit.noAuth ? [] : ['OAUTH2'],
823 + meta: { logo: LOGO, description: toolkit.description },
824 + connected_account: connection
825 + ? {
826 + id: connection.id,
827 + user_id: connection.userId,
828 + status: connection.status,
829 + created_at: SEEDED_AT,
830 + auth_config: {
831 + id: connection.authConfigId,
832 + auth_scheme: 'OAUTH2',
833 + is_composio_managed: true,
834 + },
835 + }
836 + : null,
837 + };
838 + });
839 + return {
840 + json: singlePage(items),
841 + acted: { project: session.projectLabel, userId: session.userId },
842 + };
843 + },
844 + }),
845 +];
846 +
847 +const DEVELOPER_ROUTES: ReadonlyArray<Route> = [
848 + backend({
849 + name: 'authConfigs.list',
850 + method: 'GET',
851 + path: '/api/:v/auth_configs',
852 + typed: true,
853 + auth: 'project',
854 + handle: ({ world, project, query }) => {
855 + const toolkit = query.get('toolkit_slug')?.toLowerCase();
856 + const items = world.authConfigs
857 + .filter(authConfig => authConfig.projectLabel === project!.label)
858 + .filter(authConfig => !toolkit || authConfig.toolkit === toolkit)
859 + .map(authConfig => authConfigItem(authConfig, world));
860 + return { json: singlePage(items) };
861 + },
862 + }),
863 + backend({
864 + name: 'authConfigs.retrieve',
865 + method: 'GET',
866 + path: '/api/:v/auth_configs/:id',
867 + typed: true,
868 + auth: 'project',
869 + handle: ({ world, project, params }) => {
870 + const authConfig = world.authConfigs.find(
871 + candidate => candidate.id === params.id && candidate.projectLabel === project!.label
872 + );
873 + return authConfig
874 + ? { json: authConfigItem(authConfig, world) }
875 + : notFound(`Auth config ${params.id} not found`, 'AuthConfig_NotFound');
876 + },
877 + }),
878 + backend({
879 + name: 'connectedAccounts.list',
880 + method: 'GET',
881 + path: '/api/:v/connected_accounts',
882 + typed: true,
883 + auth: 'project',
884 + handle: ({ world, project, query, urls }) => {
885 + const userIds = query.getAll('user_ids').flatMap(value => value.split(','));
886 + const toolkits = query.getAll('toolkit_slugs').flatMap(value => value.split(','));
887 + const statuses = query.getAll('statuses').flatMap(value => value.split(','));
888 + const items = world.connections
889 + .filter(connection => connection.projectLabel === project!.label)
890 + .filter(connection => userIds.length === 0 || userIds.includes(connection.userId))
891 + .filter(connection => toolkits.length === 0 || toolkits.includes(connection.toolkit))
892 + .filter(connection => statuses.length === 0 || statuses.includes(connection.status))
893 + .map(connection => connectedAccount(connection, urls));
894 + return {
895 + json: singlePage(items),
896 + acted: { userId: userIds.length === 1 ? (userIds[0] ?? null) : null },
897 + };
898 + },
899 + }),
900 + backend({
901 + name: 'connectedAccounts.retrieve',
902 + method: 'GET',
903 + path: '/api/:v/connected_accounts/:id',
904 + typed: true,
905 + auth: 'project',
906 + handle: ({ world, project, params, urls }) => {
907 + const connection = world.connections.find(
908 + candidate => candidate.id === params.id && candidate.projectLabel === project!.label
909 + );
910 + if (connection) world.pollConnection(connection);
911 + return connection
912 + ? { json: connectedAccount(connection, urls), acted: { userId: connection.userId } }
913 + : notFound(`Connected account ${params.id} not found`, 'ConnectedAccount_NotFound');
914 + },
915 + }),
916 + backend({
917 + name: 'link.create',
918 + method: 'POST',
919 + path: '/api/:v/connected_accounts/link',
920 + typed: true,
921 + auth: 'project',
922 + handle: ({ world, project, body, urls }) => {
923 + const request = LinkCreateBody.parse(body);
924 + const authConfig = world.authConfigs.find(
925 + candidate =>
926 + candidate.id === request.auth_config_id && candidate.projectLabel === project!.label
927 + );
928 + if (!authConfig) {
929 + return notFound(`Auth config ${request.auth_config_id} not found`, 'AuthConfig_NotFound');
930 + }
931 + const connection = world.beginConnection({
932 + projectLabel: project!.label,
933 + userId: request.user_id,
934 + toolkit: authConfig.toolkit,
935 + alias: request.alias,
936 + });
937 + return {
938 + status: 201,
939 + json: {
940 + link_token: `lt_${connection.id}`,
941 + redirect_url: redirectUrl(urls, connection),
942 + expires_at: SEEDED_EXPIRY,
943 + connected_account_id: connection.id,
944 + },
945 + acted: { userId: request.user_id },
946 + effect: 'connection-started',
947 + };
948 + },
949 + }),
950 + backend({
951 + name: 'tools.execute',
952 + method: 'POST',
953 + path: '/api/:v/tools/execute/:slug',
954 + typed: true,
955 + auth: 'project',
956 + handle: ({ world, project, params, body }) => {
957 + const request = DirectExecuteBody.parse(body);
958 + const slug = params.slug ?? '';
959 + const userId =
960 + request.user_id ??
961 + world.connections.find(connection => connection.id === request.connected_account_id)
962 + ?.userId ??
963 + '';
964 + const acted = { userId: userId === '' ? null : userId };
965 + const outcome = runTool(world, {
966 + projectLabel: project!.label,
967 + userId,
968 + slug,
969 + args: request.arguments ?? {},
970 + });
971 + if (outcome.kind === 'unknown-tool') return { ...unknownTool(slug), acted };
972 + if (outcome.kind === 'not-connected') {
973 + return {
974 + status: 400,
975 + json: errorEnvelope({
976 + status: 400,
977 + code: 4302,
978 + slug: 'ActionExecute_ConnectedAccountNotFound',
979 + message: `No connected account found for user ${userId} and toolkit ${outcome.toolkit}`,
980 + }),
981 + acted,
982 + };
983 + }
984 + return {
985 + json: { data: outcome.data, error: null, successful: true, log_id: outcome.logId },
986 + acted,
987 + effect: 'tool-executed',
988 + tool: { slug, arguments: request.arguments ?? {} },
989 + };
990 + },
991 + }),
992 +];
993 +
994 +/**
995 + * The Dashboard procedures behind consumer `composio execute`. The Dashboard
996 + * resolves the consumer project and the consumer user from the login, runs the
997 + * tool on the backend, and relays the backend's answer inside a tRPC envelope.
998 + */
999 +const trpcReply = (outcome: unknown) => ({ result: { data: { json: outcome } } });
1000 +
1001 +const DASHBOARD_ROUTES: ReadonlyArray<Route> = [
1002 + {
1003 + name: 'dashboard.execute',
1004 + role: 'dashboard',
1005 + method: 'POST',
1006 + path: '/api/cli/trpc/execute',
1007 + typed: false,
1008 + auth: 'none',
1009 + handle: ({ world, identity, body }) => {
1010 + const acted = { project: CONSUMER_PROJECT.label, userId: CONSUMER_USER_ID };
1011 + if (identity.keyClass !== 'user' || !identity.keyKnown) {
1012 + return {
1013 + status: 401,
1014 + json: {
1015 + error: {
1016 + json: {
1017 + message: 'Invalid or expired credentials',
1018 + code: -32001,
1019 + data: { code: 'UNAUTHORIZED', httpStatus: 401 },
1020 + },
1021 + },
1022 + },
1023 + acted,
1024 + };
1025 + }
1026 + const request = ExecuteBody.parse(TrpcBody.parse(body).json);
1027 + const outcome = runTool(world, {
1028 + projectLabel: CONSUMER_PROJECT.label,
1029 + userId: CONSUMER_USER_ID,
1030 + slug: request.tool_slug,
1031 + args: request.arguments ?? {},
1032 + });
1033 + if (outcome.kind === 'unknown-tool') {
1034 + const failure = unknownTool(request.tool_slug);
1035 + return {
1036 + json: trpcReply({
1037 + ok: false,
1038 + status: 404,
1039 + error: z.object({ error: z.unknown() }).parse(failure.json).error,
1040 + }),
1041 + acted,
1042 + };
1043 + }
1044 + if (outcome.kind === 'not-connected') {
1045 + const failure = noActiveConnection(outcome.toolkit);
1046 + return {
1047 + json: trpcReply({ ok: false, status: failure.status, error: failure.json.error }),
1048 + acted,
1049 + };
1050 + }
1051 + return {
1052 + json: trpcReply({
1053 + ok: true,
1054 + response: {
1055 + result_type: 'completed',
1056 + data: outcome.data,
1057 + error: null,
1058 + log_id: outcome.logId,
1059 + },
1060 + }),
1061 + acted,
1062 + effect: 'tool-executed',
1063 + tool: { slug: request.tool_slug, arguments: request.arguments ?? {} },
1064 + };
1065 + },
1066 + },
1067 + {
1068 + name: 'dashboard.executeMeta',
1069 + role: 'dashboard',
1070 + method: 'POST',
1071 + path: '/api/cli/trpc/executeMeta',
1072 + typed: false,
1073 + auth: 'none',
1074 + handle: ({ world, body }) => {
1075 + const request = ExecuteMetaBody.parse(TrpcBody.parse(body).json);
1076 + return {
1077 + json: trpcReply({
1078 + ok: true,
1079 + response: {
1080 + result_type: 'completed',
1081 + data: { slug: request.slug, echoed_arguments: request.arguments ?? {} },
1082 + error: null,
1083 + log_id: world.nextLogId(),
1084 + },
1085 + }),
1086 + acted: { project: CONSUMER_PROJECT.label, userId: CONSUMER_USER_ID },
1087 + };
1088 + },
1089 + },
1090 +];
1091 +
1092 +const AGENT_IDENTITY = {
1093 + status: 'READY',
1094 + slug: 'e2e-agent',
1095 + email: 'e2e-agent@agent.composio.test',
1096 + composio_agent_key: 'cak_e2e_agent_key_0001',
1097 + composio: {
1098 + member_id: 'mem_e2e_agent',
1099 + org_id: 'ok_e2eagent0001',
1100 + project_id: 'pr_e2eagent00001',
1101 + user_api_key: 'uak_e2e_agent_user_key',
1102 + },
1103 +} as const;
1104 +
1105 +const AGENT_ROUTES: ReadonlyArray<Route> = [
1106 + {
1107 + name: 'agents.signup',
1108 + role: 'agents',
1109 + method: 'POST',
1110 + path: '/api/signup',
1111 + typed: false,
1112 + auth: 'none',
1113 + handle: () => ({ json: AGENT_IDENTITY }),
1114 + },
1115 + {
1116 + name: 'agents.whoami',
1117 + role: 'agents',
1118 + method: 'GET',
1119 + path: '/api/whoami',
1120 + typed: false,
1121 + auth: 'none',
1122 + handle: ({ identity }) =>
1123 + identity.key === AGENT_IDENTITY.composio_agent_key
1124 + ? { json: AGENT_IDENTITY }
1125 + : { status: 401, json: { message: 'unauthorized' } },
1126 + },
1127 +];
1128 +
1129 +const releaseJson = (release: Release, baseUrl: string) => ({
1130 + tag_name: release.tag,
1131 + draft: false,
1132 + prerelease: release.prerelease,
1133 + assets: release.assets.map(asset => ({
1134 + name: asset.name,
1135 + browser_download_url: `${baseUrl}/ComposioHQ/composio/releases/download/${encodeURIComponent(release.tag)}/${asset.name}`,
1136 + })),
1137 +});
1138 +
1139 +const RELEASE_ROUTES: ReadonlyArray<Route> = [
1140 + {
1141 + name: 'github.releases.list',
1142 + role: 'github-api',
1143 + method: 'GET',
1144 + path: '/repos/:owner/:repo/releases',
1145 + typed: false,
1146 + auth: 'none',
1147 + handle: ({ world, urls }) => ({
1148 + json: world.releases.map(release => releaseJson(release, urls.backend)),
1149 + }),
1150 + },
1151 + {
1152 + name: 'github.releases.byTag',
1153 + role: 'github-api',
1154 + method: 'GET',
1155 + path: '/repos/:owner/:repo/releases/tags/:tag',
1156 + typed: false,
1157 + auth: 'none',
1158 + handle: ({ world, params, urls }) => {
1159 + const release = world.releases.find(candidate => candidate.tag === params.tag);
1160 + return release
1161 + ? { json: releaseJson(release, urls.backend) }
1162 + : { status: 404, json: { message: 'Not Found', status: '404' } };
1163 + },
1164 + },
1165 + {
1166 + name: 'github.releases.download',
1167 + role: 'github-download',
1168 + method: 'GET',
1169 + path: '/:owner/:repo/releases/download/:tag/:asset',
1170 + typed: false,
1171 + auth: 'none',
1172 + handle: ({ world, params }) => {
1173 + const asset = world.releases
1174 + .find(candidate => candidate.tag === params.tag)
1175 + ?.assets.find(candidate => candidate.name === params.asset);
1176 + return asset ? { bytes: asset.read() } : { status: 404, text: 'Not Found\n' };
1177 + },
1178 + },
1179 +];
1180 +
1181 +const TELEMETRY_ROUTES: ReadonlyArray<Route> = [
1182 + {
1183 + name: 'posthog.capture',
1184 + role: 'posthog',
1185 + method: 'POST',
1186 + path: '/posthog/i/v0/e/',
1187 + typed: false,
1188 + auth: 'none',
1189 + handle: () => ({ json: { status: 1 } }),
1190 + },
1191 +];
1192 +
1193 +export const ROUTES: ReadonlyArray<Route> = [
1194 + ...ACCOUNT_ROUTES,
1195 + ...LOGIN_ROUTES,
1196 + ...CATALOG_ROUTES,
1197 + ...SESSION_ROUTES,
1198 + ...DEVELOPER_ROUTES,
1199 + ...DASHBOARD_ROUTES,
1200 + ...AGENT_ROUTES,
1201 + ...RELEASE_ROUTES,
1202 + ...TELEMETRY_ROUTES,
1203 +];
1204 +
1205 +export { AGENT_IDENTITY };
ts/e2e-tests/cli/fake-backend/src/server.ts new
+386
@@ -0,0 +1,386 @@
1 +/**
2 + * The fake Composio deployment: one process that answers for every host the
3 + * `composio` binary talks to (backend, Dashboard, agents service, GitHub
4 + * releases, PostHog), keeps a journal of what it received, and can be told to
5 + * misbehave per route.
6 + */
7 +
8 +import { createServer as createHttpServer } from 'node:http';
9 +import type { IncomingMessage, Server, ServerResponse } from 'node:http';
10 +import { createServer as createHttpsServer } from 'node:https';
11 +import type { AddressInfo } from 'node:net';
12 +import {
13 + describeFault,
14 + errorEnvelope,
15 + FaultController,
16 + HTML_ERROR_PAGE,
17 + MALFORMED_JSON_BODY,
18 + type Fault,
19 +} from './faults';
20 +import { identify, Journal, type RequestIdentity, type ServiceRole } from './journal';
21 +import { matchPath, type Route, type RouteContext, type RouteResult } from './route';
22 +import { ROUTES } from './routes';
23 +import { tlsMaterial } from './tls';
24 +import { World, type SeededProject } from './world';
25 +
26 +/** The base URLs of the fake, as seen from one vantage point. */
27 +export interface FakeUrls {
28 + /** `COMPOSIO_BASE_URL`, `COMPOSIO_AGENTS_BASE_URL`, `COMPOSIO_GITHUB_API_BASE_URL`, `COMPOSIO_GITHUB_URL`. */
29 + readonly http: string;
30 + /** `COMPOSIO_WEB_URL`. */
31 + readonly https: string;
32 + readonly posthog: string;
33 +}
34 +
35 +export interface FakeComposio {
36 + readonly world: World;
37 + readonly journal: Journal;
38 + readonly faults: FaultController;
39 + /** URLs a process on the host uses. */
40 + readonly host: FakeUrls;
41 + /** URLs a process inside a container uses. */
42 + readonly docker: FakeUrls;
43 + /** PEM certificate the Dashboard listener presents; trust it with `NODE_EXTRA_CA_CERTS`. */
44 + readonly caCert: string;
45 + /**
46 + * The environment that points every host the binary talks to at this fake.
47 + * `dashboard: false` leaves `COMPOSIO_WEB_URL` unset, which keeps consumer
48 + * executions on the backend transport.
49 + */
50 + readonly cliEnv: (options?: { dashboard?: boolean }) => Record<string, string>;
51 + readonly close: () => Promise<void>;
52 +}
53 +
54 +const roleOf = (path: string, viaTls: boolean): ServiceRole => {
55 + if (path.startsWith('/api/cli/trpc/')) return 'dashboard';
56 + if (path.startsWith('/api/v3/') || path.startsWith('/api/v3.1/')) return 'backend';
57 + if (path.startsWith('/api/')) return 'agents';
58 + if (path.startsWith('/repos/')) return 'github-api';
59 + if (path.includes('/releases/download/')) return 'github-download';
60 + if (path.startsWith('/posthog')) return 'posthog';
61 + return viaTls ? 'dashboard' : 'unknown';
62 +};
63 +
64 +const readBody = (request: IncomingMessage): Promise<string> =>
65 + new Promise((resolve, reject) => {
66 + const chunks: Uint8Array[] = [];
67 + request.on('data', (chunk: Uint8Array) => chunks.push(chunk));
68 + request.on('end', () => resolve(new TextDecoder().decode(Buffer.concat(chunks))));
69 + request.on('error', reject);
70 + });
71 +
72 +const parseJson = (text: string): unknown => {
73 + if (text.trim() === '') return undefined;
74 + try {
75 + return JSON.parse(text) as unknown;
76 + } catch {
77 + // Kept as text so the journal still shows what arrived.
78 + return text;
79 + }
80 +};
81 +
82 +const toHeaders = (request: IncomingMessage): Headers => {
83 + const headers = new Headers();
84 + for (const [name, value] of Object.entries(request.headers)) {
85 + if (value === undefined) continue;
86 + headers.set(name, Array.isArray(value) ? value.join(', ') : value);
87 + }
88 + return headers;
89 +};
90 +
91 +interface Planned {
92 + readonly status: number;
93 + readonly headers: Record<string, string>;
94 + readonly body: Uint8Array;
95 +}
96 +
97 +const plan = (result: RouteResult): Planned => {
98 + const status = result.status ?? 200;
99 + if (result.bytes !== undefined) {
100 + return {
101 + status,
102 + headers: { 'content-type': 'application/octet-stream', ...result.headers },
103 + body: result.bytes,
104 + };
105 + }
106 + if (result.text !== undefined) {
107 + return {
108 + status,
109 + headers: { 'content-type': 'text/plain; charset=utf-8', ...result.headers },
110 + body: new TextEncoder().encode(result.text),
111 + };
112 + }
113 + return {
114 + status,
115 + headers: { 'content-type': 'application/json', ...result.headers },
116 + body: new TextEncoder().encode(result.json === undefined ? '' : JSON.stringify(result.json)),
117 + };
118 +};
119 +
120 +const jsonPlan = (status: number, json: unknown, headers: Record<string, string> = {}): Planned =>
121 + plan({ status, json, headers });
122 +
123 +/** The answer a fault dictates. `null` drops the connection without a response. */
124 +const distort = async (
125 + fault: Fault,
126 + honest: Planned
127 +): Promise<{ planned: Planned; cutAfter?: number } | null> => {
128 + switch (fault.kind) {
129 + case 'status':
130 + return {
131 + planned: jsonPlan(
132 + fault.status,
133 + fault.body ??
134 + errorEnvelope({
135 + status: fault.status,
136 + message: fault.message ?? `Injected HTTP ${fault.status}`,
137 + slug: fault.slug ?? `Injected_${fault.status}`,
138 + code: fault.code,
139 + }),
140 + { ...fault.headers }
141 + ),
142 + };
143 + case 'delay':
144 + await Bun.sleep(fault.ms);
145 + return { planned: honest };
146 + case 'reset':
147 + return null;
148 + case 'reset-mid-body':
149 + return { planned: honest, cutAfter: Math.max(1, Math.floor(honest.body.length / 2)) };
150 + case 'malformed-json':
151 + return { planned: plan({ status: 200, text: MALFORMED_JSON_BODY, headers: honest.headers }) };
152 + case 'schema-drift': {
153 + const drifted = fault.transform(JSON.parse(new TextDecoder().decode(honest.body)));
154 + return { planned: jsonPlan(honest.status, drifted) };
155 + }
156 + case 'html':
157 + return {
158 + planned: plan({
159 + status: fault.status ?? 502,
160 + text: HTML_ERROR_PAGE,
161 + headers: { 'content-type': 'text/html; charset=utf-8' },
162 + }),
163 + };
164 + case 'empty-body':
165 + return { planned: plan({ status: 200, json: undefined }) };
166 + }
167 +};
168 +
169 +const send = (response: ServerResponse, planned: Planned, cutAfter?: number): void => {
170 + response.writeHead(planned.status, {
171 + ...planned.headers,
172 + 'content-length': String(planned.body.length),
173 + });
174 + if (cutAfter === undefined) {
175 + response.end(planned.body);
176 + return;
177 + }
178 + // The declared length is never delivered: the client sees the body end early.
179 + response.write(planned.body.subarray(0, cutAfter));
180 + setTimeout(() => response.socket?.destroy(), 50);
181 +};
182 +
183 +const labelled = (world: World, identity: RequestIdentity): SeededProject | undefined =>
184 + identity.project ? world.projectByLabel(identity.project) : undefined;
185 +
186 +const authorize = (
187 + route: Route,
188 + identity: RequestIdentity,
189 + world: World
190 +): { project: SeededProject | undefined } | { denied: Planned } => {
191 + if (route.auth === 'none') return { project: labelled(world, identity) };
192 +
193 + const unauthorized = (message: string): { denied: Planned } => ({
194 + denied: jsonPlan(401, errorEnvelope({ status: 401, message, slug: 'Auth_InvalidApiKey' })),
195 + });
196 + if (identity.keyClass === 'none') return unauthorized('No API key provided');
197 + if (!identity.keyKnown) return unauthorized('Invalid API key');
198 +
199 + if (route.auth === 'key') return { project: labelled(world, identity) };
200 +
201 + if (route.auth === 'user') {
202 + return identity.keyClass === 'user'
203 + ? { project: labelled(world, identity) }
204 + : unauthorized('This endpoint requires a user API key');
205 + }
206 +
207 + // A user key sent without `x-org-id` and `x-project-id` acts on the org's
208 + // default project, the one `auth/session/info` reports for that key.
209 + return { project: labelled(world, identity) ?? world.defaultProject };
210 +};
211 +
212 +const listen = (server: Server): Promise<number> =>
213 + new Promise((resolve, reject) => {
214 + server.once('error', reject);
215 + server.listen({ host: '0.0.0.0', port: 0 }, () => {
216 + server.off('error', reject);
217 + resolve((server.address() as AddressInfo).port);
218 + });
219 + });
220 +
221 +const closeServer = (server: Server): Promise<void> =>
222 + new Promise(resolve => {
223 + server.closeAllConnections();
224 + server.close(() => resolve());
225 + });
226 +
227 +/** Starts the fake on two free ports (HTTP, and HTTPS for the Dashboard). */
228 +export const startFakeComposio = async (
229 + options: {
230 + routes?: ReadonlyArray<Route>;
231 + /** The one user API key this deployment issued; defaults to the seeded key. */
232 + userApiKey?: string;
233 + } = {}
234 +): Promise<FakeComposio> => {
235 + const world = new World({ userApiKey: options.userApiKey });
236 + const journal = new Journal();
237 + const faults = new FaultController();
238 + // Suite-specific routes come first so they can shadow a seeded one.
239 + const routes = [...(options.routes ?? []), ...ROUTES];
240 + const tls = tlsMaterial();
241 + let urls: { host: FakeUrls; docker: FakeUrls } | undefined;
242 +
243 + const handler = (viaTls: boolean) => (request: IncomingMessage, response: ServerResponse) => {
244 + void (async () => {
245 + const url = new URL(request.url ?? '/', 'http://fake.invalid');
246 + const method = request.method ?? 'GET';
247 + const headers = toHeaders(request);
248 + const body = parseJson(await readBody(request));
249 + const identity = identify(headers, world);
250 + const role = roleOf(url.pathname, viaTls);
251 +
252 + let params: Record<string, string> = {};
253 + const route = routes.find(candidate => {
254 + if (candidate.method !== method) return false;
255 + const captured = matchPath(candidate.path, url.pathname);
256 + if (captured) params = captured;
257 + return captured !== undefined;
258 + });
259 +
260 + let acted: RouteResult['acted'];
261 + let effect: RouteResult['effect'];
262 + let tool: RouteResult['tool'];
263 + let scoped: SeededProject | undefined;
264 + const honest = (): Planned => {
265 + if (!route) {
266 + return jsonPlan(
267 + 404,
268 + errorEnvelope({
269 + status: 404,
270 + message: `The fake backend has no route for ${method} ${url.pathname}`,
271 + slug: 'Fake_UnhandledRoute',
272 + })
273 + );
274 + }
275 + const access = authorize(route, identity, world);
276 + if ('denied' in access) return access.denied;
277 + if (route.auth === 'project') scoped = access.project;
278 + const context: RouteContext = {
279 + world,
280 + identity,
281 + params,
282 + query: url.searchParams,
283 + body,
284 + headers,
285 + urls: { backend: urls!.docker.http, dashboard: urls!.docker.https },
286 + project: access.project,
287 + };
288 + const result = route.handle(context);
289 + acted = result.acted;
290 + effect = result.effect;
291 + tool = result.tool;
292 + return plan(result);
293 + };
294 +
295 + const fault = faults.take(route?.name ?? null, method, url.pathname);
296 + // A fault that replaces the answer must not also let the route act.
297 + const replaces =
298 + fault !== undefined &&
299 + fault.kind !== 'delay' &&
300 + fault.kind !== 'schema-drift' &&
301 + fault.kind !== 'reset-mid-body';
302 + const honestPlan = replaces ? jsonPlan(200, {}) : honest();
303 + const outcome = fault ? await distort(fault, honestPlan) : { planned: honestPlan };
304 +
305 + journal.record({
306 + role,
307 + method,
308 + path: url.pathname,
309 + query: Object.fromEntries(url.searchParams),
310 + route: route?.name ?? null,
311 + keyClass: identity.keyClass,
312 + keyKnown: identity.keyKnown,
313 + orgId: identity.orgId,
314 + project: acted?.project !== undefined ? acted.project : (scoped?.label ?? identity.project),
315 + requestedProject: identity.project,
316 + projectFrom:
317 + acted?.project !== undefined && acted.project !== identity.project
318 + ? 'route'
319 + : identity.project !== null
320 + ? identity.keyClass === 'project'
321 + ? 'project-key'
322 + : 'scope-headers'
323 + : scoped
324 + ? 'key-default'
325 + : null,
326 + userId: acted?.userId ?? null,
327 + body,
328 + status: outcome?.planned.status ?? 0,
329 + effect: effect ?? null,
330 + tool: tool ?? null,
331 + fault: fault ? describeFault(fault) : null,
332 + });
333 +
334 + if (outcome === null) {
335 + request.socket.destroy();
336 + return;
337 + }
338 + send(response, outcome.planned, outcome.cutAfter);
339 + })().catch(error => {
340 + // A handler bug must fail the test that triggered it, not hang the client.
341 + send(
342 + response,
343 + jsonPlan(
344 + 500,
345 + errorEnvelope({
346 + status: 500,
347 + message: `Fake backend handler threw: ${error instanceof Error ? error.message : String(error)}`,
348 + slug: 'Fake_HandlerThrew',
349 + })
350 + )
351 + );
352 + });
353 + };
354 +
355 + const httpServer = createHttpServer(handler(false));
356 + const httpsServer = createHttpsServer({ key: tls.key, cert: tls.cert }, handler(true));
357 + const [httpPort, httpsPort] = await Promise.all([listen(httpServer), listen(httpsServer)]);
358 +
359 + const urlsFor = (hostname: string): FakeUrls => ({
360 + http: `http://${hostname}:${httpPort}`,
361 + https: `https://${hostname}:${httpsPort}`,
362 + posthog: `http://${hostname}:${httpPort}/posthog/i/v0/e/`,
363 + });
364 + urls = { host: urlsFor('localhost'), docker: urlsFor('host.docker.internal') };
365 + const docker = urls.docker;
366 +
367 + return {
368 + world,
369 + journal,
370 + faults,
371 + host: urls.host,
372 + docker,
373 + caCert: tls.cert,
374 + cliEnv: ({ dashboard = true } = {}) => ({
375 + COMPOSIO_BASE_URL: docker.http,
376 + ...(dashboard ? { COMPOSIO_WEB_URL: docker.https } : {}),
377 + COMPOSIO_AGENTS_BASE_URL: docker.http,
378 + COMPOSIO_GITHUB_API_BASE_URL: docker.http,
379 + COMPOSIO_GITHUB_URL: docker.http,
380 + COMPOSIO_POSTHOG_INGEST_URL: docker.posthog,
381 + }),
382 + close: async () => {
383 + await Promise.all([closeServer(httpServer), closeServer(httpsServer)]);
384 + },
385 + };
386 +};
ts/e2e-tests/cli/fake-backend/src/tls.ts new
+60
@@ -0,0 +1,60 @@
1 +/**
2 + * A throwaway certificate for the fake Dashboard.
3 + *
4 + * The CLI sends a user API key to the Dashboard only over `https:` (or to
5 + * loopback), so a fake the container reaches by host name has to speak TLS.
6 + */
7 +
8 +import { execFileSync } from 'node:child_process';
9 +import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
10 +import { tmpdir } from 'node:os';
11 +import { join } from 'node:path';
12 +
13 +export interface TlsMaterial {
14 + readonly key: string;
15 + readonly cert: string;
16 +}
17 +
18 +/** Host names the binary under test may reach the fake by. */
19 +export const FAKE_HOSTNAMES = ['host.docker.internal', 'localhost'] as const;
20 +
21 +let cached: TlsMaterial | undefined;
22 +
23 +/** Self-signed, generated once per test process with the host's `openssl`. */
24 +export const tlsMaterial = (): TlsMaterial => {
25 + if (cached) return cached;
26 + const directory = mkdtempSync(join(tmpdir(), 'composio-e2e-tls-'));
27 + const keyPath = join(directory, 'key.pem');
28 + const certPath = join(directory, 'cert.pem');
29 + try {
30 + execFileSync(
31 + 'openssl',
32 + [
33 + 'req',
34 + '-x509',
35 + '-newkey',
36 + 'rsa:2048',
37 + '-nodes',
38 + '-days',
39 + '2',
40 + '-keyout',
41 + keyPath,
42 + '-out',
43 + certPath,
44 + '-subj',
45 + `/CN=${FAKE_HOSTNAMES[0]}`,
46 + '-addext',
47 + `subjectAltName=${FAKE_HOSTNAMES.map(name => `DNS:${name}`).join(',')},IP:127.0.0.1`,
48 + ],
49 + { stdio: 'pipe' }
50 + );
51 + cached = { key: readFileSync(keyPath, 'utf8'), cert: readFileSync(certPath, 'utf8') };
52 + return cached;
53 + } catch (cause) {
54 + throw new Error('The fake Dashboard needs `openssl` on PATH to create its test certificate.', {
55 + cause,
56 + });
57 + } finally {
58 + rmSync(directory, { recursive: true, force: true });
59 + }
60 +};
ts/e2e-tests/cli/fake-backend/src/world.ts new
+500
@@ -0,0 +1,500 @@
1 +/**
2 + * The seeded state of the fake Composio deployment.
3 + *
4 + * Everything a response can echo back (ids, timestamps, emails) is fixed here,
5 + * so two runs of the same journey print the same bytes.
6 + */
7 +
8 +/** The one instant every seeded `created_at`/`updated_at` reports. */
9 +export const SEEDED_AT = '2026-01-01T00:00:00.000Z';
10 +
11 +/** Far enough ahead that a seeded login session never expires during a run. */
12 +export const SEEDED_EXPIRY = '2099-01-01T00:00:00.000Z';
13 +
14 +export interface SeededOrg {
15 + readonly id: string;
16 + readonly name: string;
17 + readonly plan: string;
18 +}
19 +
20 +export interface SeededMember {
21 + readonly id: string;
22 + readonly email: string;
23 + readonly name: string;
24 + readonly role: string;
25 +}
26 +
27 +export type ProjectKind = 'consumer' | 'developer';
28 +
29 +export interface SeededProject {
30 + /** What the journal calls this project, so assertions never repeat an id. */
31 + readonly label: string;
32 + readonly kind: ProjectKind;
33 + readonly autoId: number;
34 + readonly uuid: string;
35 + readonly nanoId: string;
36 + readonly name: string;
37 + readonly orgId: string;
38 + /** Project API key (`ak_`), minted for the developer project by `dev init`. */
39 + readonly apiKey: string;
40 +}
41 +
42 +export interface SeededToolkit {
43 + readonly slug: string;
44 + readonly name: string;
45 + readonly description: string;
46 + readonly noAuth: boolean;
47 + readonly version: string;
48 +}
49 +
50 +export interface SeededTool {
51 + readonly slug: string;
52 + readonly name: string;
53 + readonly toolkit: string;
54 + readonly description: string;
55 + readonly inputParameters: Record<string, unknown>;
56 + /** Whether running it changes nothing: a lookup, as opposed to a send or a create. */
57 + readonly readOnly: boolean;
58 + /** What a successful execution answers with, given the arguments it received. */
59 + readonly respond: (args: Record<string, unknown>) => Record<string, unknown>;
60 +}
61 +
62 +export interface Connection {
63 + readonly id: string;
64 + readonly projectLabel: string;
65 + readonly userId: string;
66 + readonly toolkit: string;
67 + readonly authConfigId: string;
68 + status: 'INITIATED' | 'ACTIVE';
69 + readonly wordId: string;
70 + readonly alias: string | null;
71 + /** Status reads left before the account turns `ACTIVE`; `null` when it never will. */
72 + pollsUntilActive: number | null;
73 + /** Whether the person approved it, as opposed to a seeded or self-completing connection. */
74 + approvedByPerson: boolean;
75 + /** Whether an answer has told a caller that the account is `ACTIVE`. */
76 + reportedActive: boolean;
77 +}
78 +
79 +export interface ReleaseAsset {
80 + readonly name: string;
81 + readonly read: () => Uint8Array;
82 +}
83 +
84 +/** A GitHub release of the CLI, as `composio upgrade` and the update check see it. */
85 +export interface Release {
86 + readonly tag: string;
87 + readonly prerelease: boolean;
88 + readonly assets: ReadonlyArray<ReleaseAsset>;
89 +}
90 +
91 +export interface AuthConfig {
92 + readonly id: string;
93 + readonly uuid: string;
94 + readonly projectLabel: string;
95 + readonly toolkit: string;
96 + readonly name: string;
97 +}
98 +
99 +export interface CliLoginSession {
100 + readonly id: string;
101 + readonly code: string;
102 + status: 'pending' | 'linked';
103 + /** Whether an answer has told a caller that the session is linked. */
104 + reportedLinked: boolean;
105 +}
106 +
107 +export interface ToolRouterSession {
108 + readonly id: string;
109 + readonly projectLabel: string;
110 + readonly userId: string;
111 +}
112 +
113 +export const ORG: SeededOrg = { id: 'ok_e2eacme00001', name: 'Acme E2E', plan: 'BUSINESS' };
114 +
115 +/** A second organization the same person belongs to, for `--org` and `orgs` rows. */
116 +export const OTHER_ORG: SeededOrg = { id: 'ok_e2eglobex001', name: 'Globex E2E', plan: 'HOBBY' };
117 +
118 +export const MEMBER: SeededMember = {
119 + id: '00000000-0000-4000-8000-00000000a001',
120 + email: 'dev@acme-e2e.test',
121 + name: 'Dev Eloper',
122 + role: 'admin',
123 +};
124 +
125 +/** The user API key (`uk_`) a completed login stores. */
126 +export const USER_API_KEY = 'uk_e2e_acme_user_key_0001';
127 +
128 +/** A well-formed user key this deployment never issued. */
129 +export const FOREIGN_USER_API_KEY = 'uk_e2e_issued_elsewhere_9999';
130 +
131 +export const CONSUMER_PROJECT: SeededProject = {
132 + label: 'consumer',
133 + kind: 'consumer',
134 + autoId: 1001,
135 + uuid: '00000000-0000-4000-8000-00000000c001',
136 + nanoId: 'pr_e2econsumer01',
137 + name: 'acme-e2e-consumer',
138 + orgId: ORG.id,
139 + apiKey: 'ak_e2e_consumer_project_key',
140 +};
141 +
142 +export const DEVELOPER_PROJECT: SeededProject = {
143 + label: 'developer',
144 + kind: 'developer',
145 + autoId: 2001,
146 + uuid: '00000000-0000-4000-8000-00000000d001',
147 + nanoId: 'pr_e2edeveloper1',
148 + name: 'acme-e2e-dev',
149 + orgId: ORG.id,
150 + apiKey: 'ak_e2e_developer_project_key',
151 +};
152 +
153 +/** A second developer project, the target of `--project-name`. */
154 +export const OTHER_DEVELOPER_PROJECT: SeededProject = {
155 + label: 'developer-other',
156 + kind: 'developer',
157 + autoId: 2002,
158 + uuid: '00000000-0000-4000-8000-00000000d002',
159 + nanoId: 'pr_e2edeveloper2',
160 + name: 'acme-e2e-staging',
161 + orgId: ORG.id,
162 + apiKey: 'ak_e2e_developer_other_key',
163 +};
164 +
165 +/** The consumer user: the logged-in person inside their consumer project. */
166 +export const CONSUMER_USER_ID = 'consumer-user-e2e-acme-0001';
167 +
168 +/** The global test user a login stores for the dev tree. */
169 +export const GLOBAL_TEST_USER_ID = `pg-test-${MEMBER.id}`;
170 +
171 +export const TOOLKITS: ReadonlyArray<SeededToolkit> = [
172 + {
173 + slug: 'slack',
174 + name: 'Slack',
175 + description: 'Send messages and manage channels in Slack.',
176 + noAuth: false,
177 + version: '20260101_00',
178 + },
179 + {
180 + slug: 'github',
181 + name: 'GitHub',
182 + description: 'Work with repositories, issues, and pull requests.',
183 + noAuth: false,
184 + version: '20260101_00',
185 + },
186 + {
187 + slug: 'gmail',
188 + name: 'Gmail',
189 + description: 'Read and send email with Gmail.',
190 + noAuth: false,
191 + version: '20260101_00',
192 + },
193 + {
194 + slug: 'hackernews',
195 + name: 'Hacker News',
196 + description: 'Read stories and user profiles from Hacker News.',
197 + noAuth: true,
198 + version: '20260101_00',
199 + },
200 +];
201 +
202 +const objectSchema = (
203 + properties: Record<string, { type: string; description: string }>,
204 + required: ReadonlyArray<string>
205 +) => ({ type: 'object', properties, required: [...required] });
206 +
207 +export const TOOLS: ReadonlyArray<SeededTool> = [
208 + {
209 + slug: 'SLACK_SEND_MESSAGE',
210 + name: 'Send message',
211 + toolkit: 'slack',
212 + description: 'Posts a message to a Slack channel.',
213 + inputParameters: objectSchema(
214 + {
215 + channel: { type: 'string', description: 'Channel name or id to post to.' },
216 + text: { type: 'string', description: 'Message text.' },
217 + },
218 + ['channel', 'text']
219 + ),
220 + readOnly: false,
221 + respond: args => ({
222 + ok: true,
223 + channel: args.channel ?? null,
224 + ts: '1767225600.000100',
225 + message: { text: args.text ?? null },
226 + }),
227 + },
228 + {
229 + slug: 'GITHUB_CREATE_AN_ISSUE',
230 + name: 'Create an issue',
231 + toolkit: 'github',
232 + description: 'Creates an issue in a GitHub repository.',
233 + inputParameters: objectSchema(
234 + {
235 + owner: { type: 'string', description: 'Repository owner.' },
236 + repo: { type: 'string', description: 'Repository name.' },
237 + title: { type: 'string', description: 'Issue title.' },
238 + body: { type: 'string', description: 'Issue body.' },
239 + },
240 + ['owner', 'repo', 'title']
241 + ),
242 + readOnly: false,
243 + respond: args => ({
244 + number: 101,
245 + title: args.title ?? null,
246 + html_url: `https://github.com/${String(args.owner)}/${String(args.repo)}/issues/101`,
247 + }),
248 + },
249 + {
250 + slug: 'GITHUB_GET_THE_AUTHENTICATED_USER',
251 + name: 'Get the authenticated user',
252 + toolkit: 'github',
253 + description: 'Returns the profile of the connected GitHub account.',
254 + inputParameters: objectSchema({}, []),
255 + readOnly: true,
256 + respond: () => ({ login: 'acme-e2e-dev', id: 4242 }),
257 + },
258 + {
259 + slug: 'GMAIL_SEND_EMAIL',
260 + name: 'Send email',
261 + toolkit: 'gmail',
262 + description: 'Sends an email from the connected Gmail account.',
263 + inputParameters: objectSchema(
264 + {
265 + recipient_email: { type: 'string', description: 'Recipient address.' },
266 + subject: { type: 'string', description: 'Subject line.' },
267 + body: { type: 'string', description: 'Message body.' },
268 + },
269 + ['recipient_email']
270 + ),
271 + readOnly: false,
272 + respond: () => ({ id: 'msg_e2e_0001', labelIds: ['SENT'] }),
273 + },
274 + {
275 + slug: 'HACKERNEWS_GET_USER',
276 + name: 'Get user',
277 + toolkit: 'hackernews',
278 + description: 'Returns a Hacker News user profile.',
279 + inputParameters: objectSchema(
280 + { username: { type: 'string', description: 'Hacker News username.' } },
281 + ['username']
282 + ),
283 + readOnly: true,
284 + respond: args => ({ id: args.username ?? null, karma: 157316 }),
285 + },
286 +];
287 +
288 +/** Mutable state; one instance per fake backend. */
289 +export class World {
290 + readonly org = ORG;
291 + readonly organizations: ReadonlyArray<SeededOrg> = [ORG, OTHER_ORG];
292 + readonly member = MEMBER;
293 + readonly userApiKey: string;
294 + readonly projects: ReadonlyArray<SeededProject> = [
295 + CONSUMER_PROJECT,
296 + DEVELOPER_PROJECT,
297 + OTHER_DEVELOPER_PROJECT,
298 + ];
299 + /** The project an unscoped user-key request acts on, as `auth/session/info` reports it. */
300 + readonly defaultProject = DEVELOPER_PROJECT;
301 + readonly toolkits = TOOLKITS;
302 + readonly tools = TOOLS;
303 +
304 + readonly connections: Connection[] = [];
305 + readonly authConfigs: AuthConfig[] = [];
306 + readonly loginSessions: CliLoginSession[] = [];
307 + readonly toolRouterSessions: ToolRouterSession[] = [];
308 + /** Project API keys minted by `POST …/api_keys/create`, newest last. */
309 + readonly mintedProjectKeys: Array<{ key: string; projectLabel: string; name: string }> = [];
310 + /** Published CLI releases. Empty by default: no update is ever on offer. */
311 + readonly releases: Release[] = [];
312 + /**
313 + * How a link request ends, standing in for the person at the OAuth screen:
314 + * the number of status reads before the account is `ACTIVE`, or `null` when
315 + * nobody ever finishes authorizing.
316 + */
317 + linkCompletesAfterPolls: number | null = 1;
318 + private toolExecutions = 0;
319 +
320 + constructor(options: { userApiKey?: string } = {}) {
321 + this.userApiKey = options.userApiKey ?? USER_API_KEY;
322 + // Each developer project starts with one Composio-managed auth config per
323 + // toolkit that needs auth, as a fresh project gets on first use.
324 + for (const project of this.projects.filter(p => p.kind === 'developer')) {
325 + for (const toolkit of this.toolkits.filter(t => !t.noAuth)) {
326 + this.authConfigForToolkit(project.label, toolkit.slug);
327 + }
328 + }
329 + }
330 +
331 + projectByLabel(label: string): SeededProject {
332 + const project = this.projects.find(p => p.label === label);
333 + if (!project) throw new Error(`No seeded project labelled ${label}`);
334 + return project;
335 + }
336 +
337 + /** A project by nano id, uuid, or name: the ids a request can carry. */
338 + findProject(reference: string | undefined): SeededProject | undefined {
339 + if (!reference) return undefined;
340 + return this.projects.find(
341 + p => p.nanoId === reference || p.uuid === reference || p.name === reference
342 + );
343 + }
344 +
345 + projectForApiKey(key: string): SeededProject | undefined {
346 + const minted = this.mintedProjectKeys.find(k => k.key === key);
347 + if (minted) return this.projectByLabel(minted.projectLabel);
348 + return this.projects.find(p => p.apiKey === key);
349 + }
350 +
351 + findToolkit(slug: string): SeededToolkit | undefined {
352 + return this.toolkits.find(t => t.slug === slug.toLowerCase());
353 + }
354 +
355 + findTool(slug: string): SeededTool | undefined {
356 + return this.tools.find(t => t.slug === slug.toUpperCase());
357 + }
358 +
359 + authConfigForToolkit(projectLabel: string, toolkit: string): AuthConfig {
360 + const existing = this.authConfigs.find(
361 + a => a.projectLabel === projectLabel && a.toolkit === toolkit
362 + );
363 + if (existing) return existing;
364 + const ordinal = String(this.authConfigs.length + 1).padStart(4, '0');
365 + const created: AuthConfig = {
366 + id: `ac_e2e${ordinal}`,
367 + uuid: `00000000-0000-4000-8000-0000000a${ordinal}`,
368 + projectLabel,
369 + toolkit,
370 + name: `${toolkit}-${projectLabel}`,
371 + };
372 + this.authConfigs.push(created);
373 + return created;
374 + }
375 +
376 + activeConnection(projectLabel: string, userId: string, toolkit: string): Connection | undefined {
377 + return this.connections.find(
378 + c =>
379 + c.projectLabel === projectLabel &&
380 + c.userId === userId &&
381 + c.toolkit === toolkit &&
382 + c.status === 'ACTIVE'
383 + );
384 + }
385 +
386 + /** `activeConnection` for answering a request: the caller now knows the account is active. */
387 + reportActiveConnection(
388 + projectLabel: string,
389 + userId: string,
390 + toolkit: string
391 + ): Connection | undefined {
392 + const connection = this.activeConnection(projectLabel, userId, toolkit);
393 + if (connection) connection.reportedActive = true;
394 + return connection;
395 + }
396 +
397 + /** Starts a connection the way a link request does: `INITIATED`, with a redirect to follow. */
398 + beginConnection(params: {
399 + projectLabel: string;
400 + userId: string;
401 + toolkit: string;
402 + alias?: string | null;
403 + }): Connection {
404 + const ordinal = String(this.connections.length + 1).padStart(4, '0');
405 + const connection: Connection = {
406 + id: `ca_e2e${ordinal}`,
407 + projectLabel: params.projectLabel,
408 + userId: params.userId,
409 + toolkit: params.toolkit,
410 + authConfigId: this.authConfigForToolkit(params.projectLabel, params.toolkit).id,
411 + status: 'INITIATED',
412 + wordId: `${params.toolkit}_e2e_${ordinal}`,
413 + alias: params.alias ?? null,
414 + pollsUntilActive: this.linkCompletesAfterPolls,
415 + approvedByPerson: false,
416 + reportedActive: false,
417 + };
418 + this.connections.push(connection);
419 + return connection;
420 + }
421 +
422 + /** One status read of a pending connection, which may be the one that finds it authorized. */
423 + pollConnection(connection: Connection): void {
424 + if (connection.status === 'ACTIVE' || connection.pollsUntilActive === null) return;
425 + connection.pollsUntilActive -= 1;
426 + if (connection.pollsUntilActive <= 0) connection.status = 'ACTIVE';
427 + }
428 +
429 + /** Seeds an already-active connection, for journeys that start connected. */
430 + connect(projectLabel: string, userId: string, toolkit: string): Connection {
431 + const connection = this.beginConnection({ projectLabel, userId, toolkit });
432 + connection.status = 'ACTIVE';
433 + return connection;
434 + }
435 +
436 + /** Stands in for the person approving one authorization; `false` when there is none pending under that id. */
437 + authorizeConnection(id: string): boolean {
438 + const connection = this.connections.find(c => c.id === id && c.status === 'INITIATED');
439 + if (!connection) return false;
440 + connection.status = 'ACTIVE';
441 + connection.approvedByPerson = true;
442 + return true;
443 + }
444 +
445 + /**
446 + * Ids of the login sessions and connections the person approved that no
447 + * answer has reported yet: the CLI, and so the agent, cannot know of them.
448 + */
449 + unreportedApprovals(): ReadonlyArray<string> {
450 + return [
451 + ...this.loginSessions
452 + .filter(session => session.status === 'linked' && !session.reportedLinked)
453 + .map(session => session.id),
454 + ...this.connections
455 + .filter(connection => connection.approvedByPerson && !connection.reportedActive)
456 + .map(connection => connection.id),
457 + ];
458 + }
459 +
460 + createLoginSession(): CliLoginSession {
461 + const ordinal = String(this.loginSessions.length + 1).padStart(4, '0');
462 + const session: CliLoginSession = {
463 + id: `00000000-0000-4000-8000-00000005${ordinal}`,
464 + code: `E2E${ordinal.slice(1)}`,
465 + status: 'pending',
466 + reportedLinked: false,
467 + };
468 + this.loginSessions.push(session);
469 + return session;
470 + }
471 +
472 + /** Stands in for the person approving the login in the browser. */
473 + linkLoginSession(idOrCode?: string): CliLoginSession {
474 + const session = idOrCode
475 + ? this.loginSessions.find(s => s.id === idOrCode || s.code === idOrCode)
476 + : this.loginSessions.at(-1);
477 + if (!session) throw new Error('No CLI login session to link');
478 + session.status = 'linked';
479 + return session;
480 + }
481 +
482 + createToolRouterSession(projectLabel: string, userId: string): ToolRouterSession {
483 + const ordinal = String(this.toolRouterSessions.length + 1).padStart(4, '0');
484 + const session: ToolRouterSession = { id: `trs_e2e${ordinal}`, projectLabel, userId };
485 + this.toolRouterSessions.push(session);
486 + return session;
487 + }
488 +
489 + mintProjectKey(projectLabel: string, name: string): string {
490 + const ordinal = String(this.mintedProjectKeys.length + 1).padStart(4, '0');
491 + const key = `ak_e2e_minted_${projectLabel.replace(/[^a-z]/g, '')}_${ordinal}`;
492 + this.mintedProjectKeys.push({ key, projectLabel, name });
493 + return key;
494 + }
495 +
496 + nextLogId(): string {
497 + this.toolExecutions += 1;
498 + return `log_e2e${String(this.toolExecutions).padStart(4, '0')}`;
499 + }
500 +}
ts/e2e-tests/cli/fake-backend/tsconfig.json new
+13
@@ -0,0 +1,13 @@
1 +{
2 + "$schema": "https://json.schemastore.org/tsconfig",
3 + "compilerOptions": {
4 + "target": "es2022",
5 + "module": "esnext",
6 + "moduleResolution": "bundler",
7 + "strict": true,
8 + "skipLibCheck": true,
9 + "noEmit": true,
10 + "types": ["bun"]
11 + },
12 + "include": ["*.ts", "src/**/*.ts"]
13 +}