Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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}`); |