diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 68d7941b4..6add87e28 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -14,6 +14,7 @@ on: options: - latest - prerelease + - unstable version: description: "Version override (optional, e.g., 1.0.0). If empty, auto-increments." type: string @@ -66,8 +67,8 @@ jobs: fi else if [[ "$VERSION" != *-* ]]; then - echo "❌ Error: Version '$VERSION' has no prerelease suffix but dist-tag is 'prerelease'" >> $GITHUB_STEP_SUMMARY - echo "Use a version with suffix (e.g., '1.0.0-preview.0') for prerelease" + echo "❌ Error: Version '$VERSION' has no prerelease suffix but dist-tag is '${{ github.event.inputs.dist-tag }}'" >> $GITHUB_STEP_SUMMARY + echo "Use a version with suffix (e.g., '1.0.0-preview.0') for prerelease/unstable" exit 1 fi fi @@ -107,11 +108,12 @@ jobs: name: nodejs-package path: nodejs/*.tgz - name: Publish to npm - if: github.ref == 'refs/heads/main' + if: github.ref == 'refs/heads/main' || github.event.inputs.dist-tag == 'unstable' run: npm publish --tag ${{ github.event.inputs.dist-tag }} --access public --registry https://registry.npmjs.org publish-dotnet: name: Publish .NET SDK + if: github.event.inputs.dist-tag != 'unstable' needs: version runs-on: ubuntu-latest defaults: @@ -147,6 +149,7 @@ jobs: publish-python: name: Publish Python SDK + if: github.event.inputs.dist-tag != 'unstable' needs: version runs-on: ubuntu-latest defaults: @@ -183,7 +186,7 @@ jobs: github-release: name: Create GitHub Release needs: [version, publish-nodejs, publish-dotnet, publish-python] - if: github.ref == 'refs/heads/main' + if: github.ref == 'refs/heads/main' && github.event.inputs.dist-tag != 'unstable' runs-on: ubuntu-latest steps: - uses: actions/checkout@v6.0.2 diff --git a/nodejs/package-lock.json b/nodejs/package-lock.json index fc3d4e3b4..9f04ae02f 100644 --- a/nodejs/package-lock.json +++ b/nodejs/package-lock.json @@ -9,7 +9,7 @@ "version": "0.1.8", "license": "MIT", "dependencies": { - "@github/copilot": "^0.0.421", + "@github/copilot": "^0.0.422", "vscode-jsonrpc": "^8.2.1", "zod": "^4.3.6" }, @@ -662,26 +662,26 @@ } }, "node_modules/@github/copilot": { - "version": "0.0.421", - "resolved": "https://registry.npmjs.org/@github/copilot/-/copilot-0.0.421.tgz", - "integrity": "sha512-nDUt9f5al7IgBOTc7AwLpqvaX61VsRDYDQ9D5iR0QQzHo4pgDcyOXIjXUQUKsJwObXHfh6qR+Jm1vnlbw5cacg==", + "version": "0.0.422", + "resolved": "https://registry.npmjs.org/@github/copilot/-/copilot-0.0.422.tgz", + "integrity": "sha512-i00dQgb7mER39ZUPX1R/HJ/QFqV2DHKsVZZOFp+g+GxJrJ836M3GePNmLs1yPteSelZqVPsSCx1hhwZ7qpD6RA==", "license": "SEE LICENSE IN LICENSE.md", "bin": { "copilot": "npm-loader.js" }, "optionalDependencies": { - "@github/copilot-darwin-arm64": "0.0.421", - "@github/copilot-darwin-x64": "0.0.421", - "@github/copilot-linux-arm64": "0.0.421", - "@github/copilot-linux-x64": "0.0.421", - "@github/copilot-win32-arm64": "0.0.421", - "@github/copilot-win32-x64": "0.0.421" + "@github/copilot-darwin-arm64": "0.0.422", + "@github/copilot-darwin-x64": "0.0.422", + "@github/copilot-linux-arm64": "0.0.422", + "@github/copilot-linux-x64": "0.0.422", + "@github/copilot-win32-arm64": "0.0.422", + "@github/copilot-win32-x64": "0.0.422" } }, "node_modules/@github/copilot-darwin-arm64": { - "version": "0.0.421", - "resolved": "https://registry.npmjs.org/@github/copilot-darwin-arm64/-/copilot-darwin-arm64-0.0.421.tgz", - "integrity": "sha512-S4plFsxH7W8X1gEkGNcfyKykIji4mNv8BP/GpPs2Ad84qWoJpZzfZsjrjF0BQ8mvFObWp6Ft2SZOnJzFZW1Ftw==", + "version": "0.0.422", + "resolved": "https://registry.npmjs.org/@github/copilot-darwin-arm64/-/copilot-darwin-arm64-0.0.422.tgz", + "integrity": "sha512-3GrU8zt/JkCQaJEgI0uyRegRsv0j/DUhFFeN546gW1Fgaqd5GuuTQlofXrENCVA0h14KCePWYukWZ62EXSSU3A==", "cpu": [ "arm64" ], @@ -695,9 +695,9 @@ } }, "node_modules/@github/copilot-darwin-x64": { - "version": "0.0.421", - "resolved": "https://registry.npmjs.org/@github/copilot-darwin-x64/-/copilot-darwin-x64-0.0.421.tgz", - "integrity": "sha512-h+Dbfq8ByAielLYIeJbjkN/9Abs6AKHFi+XuuzEy4YA9jOA42uKMFsWYwaoYH8ZLK9Y+4wagYI9UewVPnyIWPA==", + "version": "0.0.422", + "resolved": "https://registry.npmjs.org/@github/copilot-darwin-x64/-/copilot-darwin-x64-0.0.422.tgz", + "integrity": "sha512-8Zcq2SCQcp5nKXbCvqJErb5OEaUiRNyggjQDG4iaTGEAdJz2b2wwH8vzoHqsW/iOAAUTCBZaQnSaK+Wup5yr6A==", "cpu": [ "x64" ], @@ -711,9 +711,9 @@ } }, "node_modules/@github/copilot-linux-arm64": { - "version": "0.0.421", - "resolved": "https://registry.npmjs.org/@github/copilot-linux-arm64/-/copilot-linux-arm64-0.0.421.tgz", - "integrity": "sha512-cxlqDRR/wKfbdzd456N2h7sZOZY069wU2ycSYSmo7cC75U5DyhMGYAZwyAhvQ7UKmS5gJC/wgSgye0njuK22Xg==", + "version": "0.0.422", + "resolved": "https://registry.npmjs.org/@github/copilot-linux-arm64/-/copilot-linux-arm64-0.0.422.tgz", + "integrity": "sha512-PK+S1VHgKCEEM8QSsl1b3gERHt1UgyPeQbcVzdcwOW0Y9FbHbGBoAYfdzjhn8G0tDsHyg1ldVHz2DLzC4GdLsg==", "cpu": [ "arm64" ], @@ -727,9 +727,9 @@ } }, "node_modules/@github/copilot-linux-x64": { - "version": "0.0.421", - "resolved": "https://registry.npmjs.org/@github/copilot-linux-x64/-/copilot-linux-x64-0.0.421.tgz", - "integrity": "sha512-7np5b6EEemJ3U3jnl92buJ88nlpqOAIrLaJxx3pJGrP9SVFMBD/6EAlfIQ5m5QTfs+/vIuTKWBrq1wpFVZZUcQ==", + "version": "0.0.422", + "resolved": "https://registry.npmjs.org/@github/copilot-linux-x64/-/copilot-linux-x64-0.0.422.tgz", + "integrity": "sha512-88aF2Tg490NLTviiCknxWg1YC4yWpJuSj4PQ9nVhLupPkj+n8gCVltSPHD47OgFxJx8sKRBZOD20bdbLNvUltw==", "cpu": [ "x64" ], @@ -743,9 +743,9 @@ } }, "node_modules/@github/copilot-win32-arm64": { - "version": "0.0.421", - "resolved": "https://registry.npmjs.org/@github/copilot-win32-arm64/-/copilot-win32-arm64-0.0.421.tgz", - "integrity": "sha512-T6qCqOnijD5pmC0ytVsahX3bpDnXtLTgo9xFGo/BGaPEvX02ePkzcRZkfkOclkzc8QlkVji6KqZYB+qMZTliwg==", + "version": "0.0.422", + "resolved": "https://registry.npmjs.org/@github/copilot-win32-arm64/-/copilot-win32-arm64-0.0.422.tgz", + "integrity": "sha512-PXTASaBA+uRYXzaDW0KCvGQQHNV6i6MJdcBfCPiJ8rPwqRaox/asy9C004IoulFQyw9sZpLV2m1Po9zLDVeW4g==", "cpu": [ "arm64" ], @@ -759,9 +759,9 @@ } }, "node_modules/@github/copilot-win32-x64": { - "version": "0.0.421", - "resolved": "https://registry.npmjs.org/@github/copilot-win32-x64/-/copilot-win32-x64-0.0.421.tgz", - "integrity": "sha512-KDfy3wsRQFIcOQDdd5Mblvh+DWRq+UGbTQ34wyW36ws1BsdWkV++gk9bTkeJRsPbQ51wsJ0V/jRKEZv4uK5dTA==", + "version": "0.0.422", + "resolved": "https://registry.npmjs.org/@github/copilot-win32-x64/-/copilot-win32-x64-0.0.422.tgz", + "integrity": "sha512-SPSwnmAZu0i+7Rb0dUIP6sczfAk8pzAteCLKPLDmtn2H/pH/jfplvmEwQdd2XlNMitlPTRaFOGbI8UYYlayuOw==", "cpu": [ "x64" ], diff --git a/nodejs/package.json b/nodejs/package.json index ef89556ac..4deb46cb4 100644 --- a/nodejs/package.json +++ b/nodejs/package.json @@ -12,6 +12,10 @@ ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" + }, + "./extension": { + "import": "./dist/extension.js", + "types": "./dist/extension.d.ts" } }, "type": "module", @@ -40,7 +44,7 @@ "author": "GitHub", "license": "MIT", "dependencies": { - "@github/copilot": "^0.0.421", + "@github/copilot": "^0.0.422", "vscode-jsonrpc": "^8.2.1", "zod": "^4.3.6" }, diff --git a/nodejs/scripts/get-version.js b/nodejs/scripts/get-version.js index d58ff79d9..784dd0b51 100644 --- a/nodejs/scripts/get-version.js +++ b/nodejs/scripts/get-version.js @@ -5,7 +5,7 @@ * * Usage: * - * node scripts/get-version.js [current|current-prerelease|latest|prerelease] + * node scripts/get-version.js [current|current-prerelease|latest|prerelease|unstable] * * Outputs the version to stdout. */ @@ -32,7 +32,7 @@ async function getLatestVersion(tag) { async function main() { const command = process.argv[2]; - const validCommands = ["current", "current-prerelease", "latest", "prerelease"]; + const validCommands = ["current", "current-prerelease", "latest", "prerelease", "unstable"]; if (!validCommands.includes(command)) { console.error( `Invalid argument, must be one of: ${validCommands.join(", ")}, got: "${command}"` @@ -75,8 +75,16 @@ async function main() { return; } + if (command === "unstable") { + const unstable = await getLatestVersion("unstable"); + if (unstable && semver.gt(unstable, higherVersion)) { + higherVersion = unstable; + } + } + const increment = command === "latest" ? "patch" : "prerelease"; - const prereleaseIdentifier = command === "prerelease" ? "preview" : undefined; + const prereleaseIdentifier = + command === "prerelease" ? "preview" : command === "unstable" ? "unstable" : undefined; const nextVersion = semver.inc(higherVersion, increment, prereleaseIdentifier); if (!nextVersion) { console.error(`Failed to increment version "${higherVersion}" with "${increment}"`); diff --git a/nodejs/src/client.ts b/nodejs/src/client.ts index fe8655b55..cd936c07b 100644 --- a/nodejs/src/client.ts +++ b/nodejs/src/client.ts @@ -42,11 +42,6 @@ import type { SessionListFilter, SessionMetadata, Tool, - ToolCallRequestPayload, - ToolCallResponsePayload, - ToolHandler, - ToolResult, - ToolResultObject, TypedSessionLifecycleHandler, } from "./types.js"; @@ -196,6 +191,12 @@ export class CopilotClient { throw new Error("cliUrl is mutually exclusive with useStdio and cliPath"); } + if (options.isChildProcess && (options.cliUrl || options.useStdio === false)) { + throw new Error( + "isChildProcess must be used in conjunction with useStdio and not with cliUrl" + ); + } + // Validate auth options with external server if (options.cliUrl && (options.githubToken || options.useLoggedInUser !== undefined)) { throw new Error( @@ -211,12 +212,17 @@ export class CopilotClient { this.isExternalServer = true; } + if (options.isChildProcess) { + this.isExternalServer = true; + } + this.options = { cliPath: options.cliPath || getBundledCliPath(), cliArgs: options.cliArgs ?? [], cwd: options.cwd ?? process.cwd(), port: options.port || 0, useStdio: options.cliUrl ? false : (options.useStdio ?? true), // Default to stdio unless cliUrl is provided + isChildProcess: options.isChildProcess ?? false, cliUrl: options.cliUrl, logLevel: options.logLevel || "debug", autoStart: options.autoStart ?? true, @@ -1204,17 +1210,19 @@ export class CopilotClient { * Connect to the CLI server (via socket or stdio) */ private async connectToServer(): Promise { - if (this.options.useStdio) { - return this.connectViaStdio(); + if (this.options.isChildProcess) { + return this.connectToParentProcessViaStdio(); + } else if (this.options.useStdio) { + return this.connectToChildProcessViaStdio(); } else { return this.connectViaTcp(); } } /** - * Connect via stdio pipes + * Connect to child via stdio pipes */ - private async connectViaStdio(): Promise { + private async connectToChildProcessViaStdio(): Promise { if (!this.cliProcess) { throw new Error("CLI process not started"); } @@ -1236,6 +1244,24 @@ export class CopilotClient { this.connection.listen(); } + /** + * Connect to parent via stdio pipes + */ + private async connectToParentProcessViaStdio(): Promise { + if (this.cliProcess) { + throw new Error("CLI child process was unexpectedly started in parent process mode"); + } + + // Create JSON-RPC connection over stdin/stdout + this.connection = createMessageConnection( + new StreamMessageReader(process.stdin), + new StreamMessageWriter(process.stdout) + ); + + this.attachConnectionHandlers(); + this.connection.listen(); + } + /** * Connect to the CLI server via TCP socket */ @@ -1278,19 +1304,11 @@ export class CopilotClient { this.handleSessionLifecycleNotification(notification); }); - this.connection.onRequest( - "tool.call", - async (params: ToolCallRequestPayload): Promise => - await this.handleToolCallRequest(params) - ); - - this.connection.onRequest( - "permission.request", - async (params: { - sessionId: string; - permissionRequest: unknown; - }): Promise<{ result: unknown }> => await this.handlePermissionRequest(params) - ); + // External tool calls and permission requests are now handled via broadcast events: + // the server sends external_tool.requested / permission.requested as session event + // notifications, and CopilotSession._dispatchEvent handles them internally by + // executing the handler and responding via session.tools.handlePendingToolCall / + // session.permissions.handlePendingPermissionRequest RPC. this.connection.onRequest( "userInput.request", @@ -1376,86 +1394,6 @@ export class CopilotClient { } } - private async handleToolCallRequest( - params: ToolCallRequestPayload - ): Promise { - if ( - !params || - typeof params.sessionId !== "string" || - typeof params.toolCallId !== "string" || - typeof params.toolName !== "string" - ) { - throw new Error("Invalid tool call payload"); - } - - const session = this.sessions.get(params.sessionId); - if (!session) { - throw new Error(`Unknown session ${params.sessionId}`); - } - - const handler = session.getToolHandler(params.toolName); - if (!handler) { - return { result: this.buildUnsupportedToolResult(params.toolName) }; - } - - return await this.executeToolCall(handler, params); - } - - private async executeToolCall( - handler: ToolHandler, - request: ToolCallRequestPayload - ): Promise { - try { - const invocation = { - sessionId: request.sessionId, - toolCallId: request.toolCallId, - toolName: request.toolName, - arguments: request.arguments, - }; - const result = await handler(request.arguments, invocation); - - return { result: this.normalizeToolResult(result) }; - } catch (error) { - const message = error instanceof Error ? error.message : String(error); - return { - result: { - // Don't expose detailed error information to the LLM for security reasons - textResultForLlm: - "Invoking this tool produced an error. Detailed information is not available.", - resultType: "failure", - error: message, - toolTelemetry: {}, - }, - }; - } - } - - private async handlePermissionRequest(params: { - sessionId: string; - permissionRequest: unknown; - }): Promise<{ result: unknown }> { - if (!params || typeof params.sessionId !== "string" || !params.permissionRequest) { - throw new Error("Invalid permission request payload"); - } - - const session = this.sessions.get(params.sessionId); - if (!session) { - throw new Error(`Session not found: ${params.sessionId}`); - } - - try { - const result = await session._handlePermissionRequest(params.permissionRequest); - return { result }; - } catch (_error) { - // If permission handler fails, deny the permission - return { - result: { - kind: "denied-no-approval-rule-and-could-not-request-from-user", - }, - }; - } - } - private async handleUserInputRequest(params: { sessionId: string; question: string; @@ -1505,49 +1443,6 @@ export class CopilotClient { return { output }; } - private normalizeToolResult(result: unknown): ToolResultObject { - if (result === undefined || result === null) { - return { - textResultForLlm: "Tool returned no result", - resultType: "failure", - error: "tool returned no result", - toolTelemetry: {}, - }; - } - - // ToolResultObject passes through directly (duck-type check) - if (this.isToolResultObject(result)) { - return result; - } - - // Everything else gets wrapped as a successful ToolResultObject - const textResult = typeof result === "string" ? result : JSON.stringify(result); - return { - textResultForLlm: textResult, - resultType: "success", - toolTelemetry: {}, - }; - } - - private isToolResultObject(value: unknown): value is ToolResultObject { - return ( - typeof value === "object" && - value !== null && - "textResultForLlm" in value && - typeof (value as ToolResultObject).textResultForLlm === "string" && - "resultType" in value - ); - } - - private buildUnsupportedToolResult(toolName: string): ToolResult { - return { - textResultForLlm: `Tool '${toolName}' is not supported by this client instance.`, - resultType: "failure", - error: `tool '${toolName}' not supported`, - toolTelemetry: {}, - }; - } - /** * Attempt to reconnect to the server */ diff --git a/nodejs/src/extension.ts b/nodejs/src/extension.ts new file mode 100644 index 000000000..b84fb2b6f --- /dev/null +++ b/nodejs/src/extension.ts @@ -0,0 +1,7 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All rights reserved. + *--------------------------------------------------------------------------------------------*/ + +import { CopilotClient } from "./client.js"; + +export const extension = new CopilotClient({ isChildProcess: true }); diff --git a/nodejs/src/generated/rpc.ts b/nodejs/src/generated/rpc.ts index af6d27783..527cee621 100644 --- a/nodejs/src/generated/rpc.ts +++ b/nodejs/src/generated/rpc.ts @@ -209,13 +209,17 @@ export interface SessionModeSetParams { export interface SessionPlanReadResult { /** - * Whether plan.md exists in the workspace + * Whether the plan file exists in the workspace */ exists: boolean; /** - * The content of plan.md, or null if it does not exist + * The content of the plan file, or null if it does not exist */ content: string | null; + /** + * Absolute file path of the plan file, or null if workspace is not enabled + */ + path: string | null; } export interface SessionPlanReadParams { @@ -233,7 +237,7 @@ export interface SessionPlanUpdateParams { */ sessionId: string; /** - * The new content for plan.md + * The new content for the plan file */ content: string; } @@ -430,6 +434,40 @@ export interface SessionCompactionCompactParams { sessionId: string; } +export interface SessionToolsHandlePendingToolCallResult { + success: boolean; +} + +export interface SessionToolsHandlePendingToolCallParams { + /** + * Target session identifier + */ + sessionId: string; + requestId: string; + result?: string; + error?: string; +} + +export interface SessionPermissionsHandlePendingPermissionRequestResult { + success: boolean; +} + +export interface SessionPermissionsHandlePendingPermissionRequestParams { + /** + * Target session identifier + */ + sessionId: string; + requestId: string; + result: { + kind: + | "approved" + | "denied-by-rules" + | "denied-no-approval-rule-and-could-not-request-from-user" + | "denied-interactively-by-user"; + rules?: unknown[]; + }; +} + /** Create typed server-scoped RPC methods (no session required). */ export function createServerRpc(connection: MessageConnection) { return { @@ -499,5 +537,13 @@ export function createSessionRpc(connection: MessageConnection, sessionId: strin compact: async (): Promise => connection.sendRequest("session.compaction.compact", { sessionId }), }, + tools: { + handlePendingToolCall: async (params: Omit): Promise => + connection.sendRequest("session.tools.handlePendingToolCall", { sessionId, ...params }), + }, + permissions: { + handlePendingPermissionRequest: async (params: Omit): Promise => + connection.sendRequest("session.permissions.handlePendingPermissionRequest", { sessionId, ...params }), + }, }; } diff --git a/nodejs/src/generated/session-events.ts b/nodejs/src/generated/session-events.ts index 4b0e4c0b6..cf87e1025 100644 --- a/nodejs/src/generated/session-events.ts +++ b/nodejs/src/generated/session-events.ts @@ -5,747 +5,2147 @@ export type SessionEvent = | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.start"; data: { + /** + * Unique identifier for the session + */ sessionId: string; + /** + * Schema version number for the session event format + */ version: number; + /** + * Identifier of the software producing the events (e.g., "copilot-agent") + */ producer: string; + /** + * Version string of the Copilot application + */ copilotVersion: string; + /** + * ISO 8601 timestamp when the session was created + */ startTime: string; + /** + * Model selected at session creation time, if any + */ selectedModel?: string; + /** + * Working directory and git context at session start + */ context?: { + /** + * Current working directory path + */ cwd: string; + /** + * Root directory of the git repository, resolved via git rev-parse + */ gitRoot?: string; + /** + * Repository identifier in "owner/name" format, derived from the git remote URL + */ repository?: string; + /** + * Current git branch name + */ branch?: string; }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.resume"; data: { + /** + * ISO 8601 timestamp when the session was resumed + */ resumeTime: string; + /** + * Total number of persisted events in the session at the time of resume + */ eventCount: number; + /** + * Updated working directory and git context at resume time + */ context?: { + /** + * Current working directory path + */ cwd: string; + /** + * Root directory of the git repository, resolved via git rev-parse + */ gitRoot?: string; + /** + * Repository identifier in "owner/name" format, derived from the git remote URL + */ repository?: string; + /** + * Current git branch name + */ branch?: string; }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.error"; data: { + /** + * Category of error (e.g., "authentication", "authorization", "quota", "rate_limit", "query") + */ errorType: string; + /** + * Human-readable error message + */ message: string; + /** + * Error stack trace, when available + */ stack?: string; + /** + * HTTP status code from the upstream request, if applicable + */ statusCode?: number; + /** + * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs + */ providerCallId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "session.idle"; - data: {}; + /** + * Payload indicating the agent is idle; includes any background tasks still in flight + */ + data: { + /** + * Background tasks still running when the agent became idle + */ + backgroundTasks?: { + /** + * Currently running background agents + */ + agents: { + /** + * Unique identifier of the background agent + */ + agentId: string; + /** + * Type of the background agent + */ + agentType: string; + /** + * Human-readable description of the agent task + */ + description?: string; + }[]; + /** + * Currently running background shell commands + */ + shells: { + /** + * Unique identifier of the background shell + */ + shellId: string; + /** + * Human-readable description of the shell command + */ + description?: string; + }[]; + }; + }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "session.title_changed"; data: { + /** + * The new display title for the session + */ title: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.info"; data: { + /** + * Category of informational message (e.g., "notification", "timing", "context_window", "mcp", "snapshot", "configuration", "authentication", "model") + */ infoType: string; + /** + * Human-readable informational message for display in the timeline + */ message: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.warning"; data: { + /** + * Category of warning (e.g., "subscription", "policy", "mcp") + */ warningType: string; + /** + * Human-readable warning message for display in the timeline + */ message: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.model_change"; data: { + /** + * Model that was previously selected, if any + */ previousModel?: string; + /** + * Newly selected model identifier + */ newModel: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.mode_changed"; data: { + /** + * Agent mode before the change (e.g., "interactive", "plan", "autopilot") + */ previousMode: string; + /** + * Agent mode after the change (e.g., "interactive", "plan", "autopilot") + */ newMode: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.plan_changed"; data: { + /** + * The type of operation performed on the plan file + */ operation: "create" | "update" | "delete"; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.workspace_file_changed"; data: { /** - * Relative path within the workspace files directory + * Relative path within the session workspace files directory */ path: string; + /** + * Whether the file was newly created or updated + */ operation: "create" | "update"; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.handoff"; data: { + /** + * ISO 8601 timestamp when the handoff occurred + */ handoffTime: string; + /** + * Origin type of the session being handed off + */ sourceType: "remote" | "local"; + /** + * Repository context for the handed-off session + */ repository?: { + /** + * Repository owner (user or organization) + */ owner: string; + /** + * Repository name + */ name: string; + /** + * Git branch name, if applicable + */ branch?: string; }; + /** + * Additional context information for the handoff + */ context?: string; + /** + * Summary of the work done in the source session + */ summary?: string; + /** + * Session ID of the remote session being handed off + */ remoteSessionId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.truncation"; data: { + /** + * Maximum token count for the model's context window + */ tokenLimit: number; + /** + * Total tokens in conversation messages before truncation + */ preTruncationTokensInMessages: number; + /** + * Number of conversation messages before truncation + */ preTruncationMessagesLength: number; + /** + * Total tokens in conversation messages after truncation + */ postTruncationTokensInMessages: number; + /** + * Number of conversation messages after truncation + */ postTruncationMessagesLength: number; + /** + * Number of tokens removed by truncation + */ tokensRemovedDuringTruncation: number; + /** + * Number of messages removed by truncation + */ messagesRemovedDuringTruncation: number; + /** + * Identifier of the component that performed truncation (e.g., "BasicTruncator") + */ performedBy: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "session.snapshot_rewind"; data: { + /** + * Event ID that was rewound to; all events after this one were removed + */ upToEventId: string; + /** + * Number of events that were removed by the rewind + */ eventsRemoved: number; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; - ephemeral: true; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ + ephemeral?: boolean; type: "session.shutdown"; data: { + /** + * Whether the session ended normally ("routine") or due to a crash/fatal error ("error") + */ shutdownType: "routine" | "error"; + /** + * Error description when shutdownType is "error" + */ errorReason?: string; + /** + * Total number of premium API requests used during the session + */ totalPremiumRequests: number; + /** + * Cumulative time spent in API calls during the session, in milliseconds + */ totalApiDurationMs: number; + /** + * Unix timestamp (milliseconds) when the session started + */ sessionStartTime: number; + /** + * Aggregate code change metrics for the session + */ codeChanges: { + /** + * Total number of lines added during the session + */ linesAdded: number; + /** + * Total number of lines removed during the session + */ linesRemoved: number; + /** + * List of file paths that were modified during the session + */ filesModified: string[]; }; + /** + * Per-model usage breakdown, keyed by model identifier + */ modelMetrics: { [k: string]: { + /** + * Request count and cost metrics + */ requests: { + /** + * Total number of API requests made to this model + */ count: number; + /** + * Cumulative cost multiplier for requests to this model + */ cost: number; }; + /** + * Token usage breakdown + */ usage: { + /** + * Total input tokens consumed across all requests to this model + */ inputTokens: number; + /** + * Total output tokens produced across all requests to this model + */ outputTokens: number; + /** + * Total tokens read from prompt cache across all requests + */ cacheReadTokens: number; + /** + * Total tokens written to prompt cache across all requests + */ cacheWriteTokens: number; }; }; }; + /** + * Model that was selected at the time of shutdown + */ currentModel?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.context_changed"; data: { + /** + * Current working directory path + */ cwd: string; + /** + * Root directory of the git repository, resolved via git rev-parse + */ gitRoot?: string; + /** + * Repository identifier in "owner/name" format, derived from the git remote URL + */ repository?: string; + /** + * Current git branch name + */ branch?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "session.usage_info"; data: { + /** + * Maximum token count for the model's context window + */ tokenLimit: number; + /** + * Current number of tokens in the context window + */ currentTokens: number; + /** + * Current number of messages in the conversation + */ messagesLength: number; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.compaction_start"; + /** + * Empty payload; the event signals that LLM-powered conversation compaction has begun + */ data: {}; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.compaction_complete"; data: { + /** + * Whether compaction completed successfully + */ success: boolean; + /** + * Error message if compaction failed + */ error?: string; + /** + * Total tokens in conversation before compaction + */ preCompactionTokens?: number; + /** + * Total tokens in conversation after compaction + */ postCompactionTokens?: number; + /** + * Number of messages before compaction + */ preCompactionMessagesLength?: number; + /** + * Number of messages removed during compaction + */ messagesRemoved?: number; + /** + * Number of tokens removed during compaction + */ tokensRemoved?: number; + /** + * LLM-generated summary of the compacted conversation history + */ summaryContent?: string; + /** + * Checkpoint snapshot number created for recovery + */ checkpointNumber?: number; + /** + * File path where the checkpoint was stored + */ checkpointPath?: string; + /** + * Token usage breakdown for the compaction LLM call + */ compactionTokensUsed?: { + /** + * Input tokens consumed by the compaction LLM call + */ input: number; + /** + * Output tokens produced by the compaction LLM call + */ output: number; + /** + * Cached input tokens reused in the compaction LLM call + */ cachedInput: number; }; + /** + * GitHub request tracing ID (x-github-request-id header) for the compaction LLM call + */ requestId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "session.task_complete"; data: { + /** + * Optional summary of the completed task, provided by the agent + */ summary?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "user.message"; data: { + /** + * The user's message text as displayed in the timeline + */ content: string; + /** + * Transformed version of the message sent to the model, with XML wrapping, timestamps, and other augmentations for prompt caching + */ transformedContent?: string; + /** + * Files, selections, or GitHub references attached to the message + */ attachments?: ( | { type: "file"; + /** + * Absolute file or directory path + */ path: string; + /** + * User-facing display name for the attachment + */ displayName: string; + /** + * Optional line range to scope the attachment to a specific section of the file + */ lineRange?: { + /** + * Start line number (1-based) + */ start: number; + /** + * End line number (1-based, inclusive) + */ end: number; }; } | { type: "directory"; + /** + * Absolute file or directory path + */ path: string; + /** + * User-facing display name for the attachment + */ displayName: string; + /** + * Optional line range to scope the attachment to a specific section of the file + */ lineRange?: { + /** + * Start line number (1-based) + */ start: number; + /** + * End line number (1-based, inclusive) + */ end: number; }; } | { + /** + * Attachment type discriminator + */ type: "selection"; + /** + * Absolute path to the file containing the selection + */ filePath: string; + /** + * User-facing display name for the selection + */ displayName: string; + /** + * The selected text content + */ text: string; + /** + * Position range of the selection within the file + */ selection: { start: { + /** + * Start line number (0-based) + */ line: number; + /** + * Start character offset within the line (0-based) + */ character: number; }; end: { + /** + * End line number (0-based) + */ line: number; + /** + * End character offset within the line (0-based) + */ character: number; }; }; } | { + /** + * Attachment type discriminator + */ type: "github_reference"; + /** + * Issue, pull request, or discussion number + */ number: number; + /** + * Title of the referenced item + */ title: string; + /** + * Type of GitHub reference + */ referenceType: "issue" | "pr" | "discussion"; + /** + * Current state of the referenced item (e.g., open, closed, merged) + */ state: string; + /** + * URL to the referenced item on GitHub + */ url: string; } )[]; + /** + * Origin of this message, used for timeline filtering (e.g., "skill-pdf" for skill-injected messages that should be hidden from the user) + */ source?: string; + /** + * The agent mode that was active when this message was sent + */ agentMode?: "interactive" | "plan" | "autopilot" | "shell"; + /** + * CAPI interaction ID for correlating this user message with its turn + */ interactionId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "pending_messages.modified"; + /** + * Empty payload; the event signals that the pending message queue has changed + */ data: {}; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "assistant.turn_start"; data: { + /** + * Identifier for this turn within the agentic loop, typically a stringified turn number + */ turnId: string; + /** + * CAPI interaction ID for correlating this turn with upstream telemetry + */ interactionId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "assistant.intent"; data: { + /** + * Short description of what the agent is currently doing or planning to do + */ intent: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "assistant.reasoning"; data: { + /** + * Unique identifier for this reasoning block + */ reasoningId: string; + /** + * The complete extended thinking text from the model + */ content: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "assistant.reasoning_delta"; data: { + /** + * Reasoning block ID this delta belongs to, matching the corresponding assistant.reasoning event + */ reasoningId: string; + /** + * Incremental text chunk to append to the reasoning content + */ deltaContent: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "assistant.streaming_delta"; data: { + /** + * Cumulative total bytes received from the streaming response so far + */ totalResponseSizeBytes: number; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "assistant.message"; data: { + /** + * Unique identifier for this assistant message + */ messageId: string; + /** + * The assistant's text response content + */ content: string; + /** + * Tool invocations requested by the assistant in this message + */ toolRequests?: { + /** + * Unique identifier for this tool call + */ toolCallId: string; + /** + * Name of the tool being invoked + */ name: string; - arguments?: unknown; + /** + * Arguments to pass to the tool, format depends on the tool + */ + arguments?: { + [k: string]: unknown; + }; + /** + * Tool call type: "function" for standard tool calls, "custom" for grammar-based tool calls. Defaults to "function" when absent. + */ type?: "function" | "custom"; }[]; + /** + * Opaque/encrypted extended thinking data from Anthropic models. Session-bound and stripped on resume. + */ reasoningOpaque?: string; + /** + * Readable reasoning text from the model's extended thinking + */ reasoningText?: string; + /** + * Encrypted reasoning content from OpenAI models. Session-bound and stripped on resume. + */ encryptedContent?: string; + /** + * Generation phase for phased-output models (e.g., thinking vs. response phases) + */ phase?: string; + /** + * Actual output token count from the API response (completion_tokens), used for accurate token accounting + */ + outputTokens?: number; + /** + * CAPI interaction ID for correlating this message with upstream telemetry + */ interactionId?: string; + /** + * Tool call ID of the parent tool invocation when this event originates from a sub-agent + */ parentToolCallId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "assistant.message_delta"; data: { + /** + * Message ID this delta belongs to, matching the corresponding assistant.message event + */ messageId: string; + /** + * Incremental text chunk to append to the message content + */ deltaContent: string; + /** + * Tool call ID of the parent tool invocation when this event originates from a sub-agent + */ parentToolCallId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "assistant.turn_end"; data: { + /** + * Identifier of the turn that has ended, matching the corresponding assistant.turn_start event + */ turnId: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "assistant.usage"; data: { + /** + * Model identifier used for this API call + */ model: string; + /** + * Number of input tokens consumed + */ inputTokens?: number; + /** + * Number of output tokens produced + */ outputTokens?: number; + /** + * Number of tokens read from prompt cache + */ cacheReadTokens?: number; + /** + * Number of tokens written to prompt cache + */ cacheWriteTokens?: number; + /** + * Model multiplier cost for billing purposes + */ cost?: number; + /** + * Duration of the API call in milliseconds + */ duration?: number; + /** + * What initiated this API call (e.g., "sub-agent"); absent for user-initiated calls + */ initiator?: string; + /** + * Completion ID from the model provider (e.g., chatcmpl-abc123) + */ apiCallId?: string; + /** + * GitHub request tracing ID (x-github-request-id header) for server-side log correlation + */ providerCallId?: string; + /** + * Parent tool call ID when this usage originates from a sub-agent + */ parentToolCallId?: string; + /** + * Per-quota resource usage snapshots, keyed by quota identifier + */ quotaSnapshots?: { [k: string]: { + /** + * Whether the user has an unlimited usage entitlement + */ isUnlimitedEntitlement: boolean; + /** + * Total requests allowed by the entitlement + */ entitlementRequests: number; + /** + * Number of requests already consumed + */ usedRequests: number; + /** + * Whether usage is still permitted after quota exhaustion + */ usageAllowedWithExhaustedQuota: boolean; + /** + * Number of requests over the entitlement limit + */ overage: number; + /** + * Whether overage is allowed when quota is exhausted + */ overageAllowedWithExhaustedQuota: boolean; + /** + * Percentage of quota remaining (0.0 to 1.0) + */ remainingPercentage: number; + /** + * Date when the quota resets + */ resetDate?: string; }; }; + /** + * Per-request cost and usage data from the CAPI copilot_usage response field + */ copilotUsage?: { + /** + * Itemized token usage breakdown + */ tokenDetails: { + /** + * Number of tokens in this billing batch + */ batchSize: number; + /** + * Cost per batch of tokens + */ costPerBatch: number; + /** + * Total token count for this entry + */ tokenCount: number; + /** + * Token category (e.g., "input", "output") + */ tokenType: string; }[]; + /** + * Total cost in nano-AIU (AI Units) for this request + */ totalNanoAiu: number; }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "abort"; data: { + /** + * Reason the current turn was aborted (e.g., "user initiated") + */ reason: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "tool.user_requested"; data: { + /** + * Unique identifier for this tool call + */ toolCallId: string; + /** + * Name of the tool the user wants to invoke + */ toolName: string; - arguments?: unknown; + /** + * Arguments for the tool invocation + */ + arguments?: { + [k: string]: unknown; + }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "tool.execution_start"; data: { + /** + * Unique identifier for this tool call + */ toolCallId: string; + /** + * Name of the tool being executed + */ toolName: string; - arguments?: unknown; + /** + * Arguments passed to the tool + */ + arguments?: { + [k: string]: unknown; + }; + /** + * Name of the MCP server hosting this tool, when the tool is an MCP tool + */ mcpServerName?: string; + /** + * Original tool name on the MCP server, when the tool is an MCP tool + */ mcpToolName?: string; + /** + * Tool call ID of the parent tool invocation when this event originates from a sub-agent + */ parentToolCallId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "tool.execution_partial_result"; data: { + /** + * Tool call ID this partial result belongs to + */ toolCallId: string; + /** + * Incremental output chunk from the running tool + */ partialOutput: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "tool.execution_progress"; data: { + /** + * Tool call ID this progress notification belongs to + */ toolCallId: string; + /** + * Human-readable progress status message (e.g., from an MCP server) + */ progressMessage: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "tool.execution_complete"; data: { + /** + * Unique identifier for the completed tool call + */ toolCallId: string; + /** + * Whether the tool execution completed successfully + */ success: boolean; + /** + * Model identifier that generated this tool call + */ model?: string; + /** + * CAPI interaction ID for correlating this tool execution with upstream telemetry + */ interactionId?: string; + /** + * Whether this tool call was explicitly requested by the user rather than the assistant + */ isUserRequested?: boolean; + /** + * Tool execution result on success + */ result?: { + /** + * Concise tool result text sent to the LLM for chat completion, potentially truncated for token efficiency + */ content: string; + /** + * Full detailed tool result for UI/timeline display, preserving complete content such as diffs. Falls back to content when absent. + */ detailedContent?: string; + /** + * Structured content blocks (text, images, audio, resources) returned by the tool in their native format + */ contents?: ( | { + /** + * Content block type discriminator + */ type: "text"; + /** + * The text content + */ text: string; } | { + /** + * Content block type discriminator + */ type: "terminal"; + /** + * Terminal/shell output text + */ text: string; + /** + * Process exit code, if the command has completed + */ exitCode?: number; + /** + * Working directory where the command was executed + */ cwd?: string; } | { + /** + * Content block type discriminator + */ type: "image"; + /** + * Base64-encoded image data + */ data: string; + /** + * MIME type of the image (e.g., image/png, image/jpeg) + */ mimeType: string; } | { + /** + * Content block type discriminator + */ type: "audio"; + /** + * Base64-encoded audio data + */ data: string; + /** + * MIME type of the audio (e.g., audio/wav, audio/mpeg) + */ mimeType: string; } | { + /** + * Icons associated with this resource + */ icons?: { + /** + * URL or path to the icon image + */ src: string; + /** + * MIME type of the icon image + */ mimeType?: string; + /** + * Available icon sizes (e.g., ['16x16', '32x32']) + */ sizes?: string[]; + /** + * Theme variant this icon is intended for + */ theme?: "light" | "dark"; }[]; + /** + * Resource name identifier + */ name: string; + /** + * Human-readable display title for the resource + */ title?: string; + /** + * URI identifying the resource + */ uri: string; + /** + * Human-readable description of the resource + */ description?: string; + /** + * MIME type of the resource content + */ mimeType?: string; + /** + * Size of the resource in bytes + */ size?: number; + /** + * Content block type discriminator + */ type: "resource_link"; } | { + /** + * Content block type discriminator + */ type: "resource"; + /** + * The embedded resource contents, either text or base64-encoded binary + */ resource: | { + /** + * URI identifying the resource + */ uri: string; + /** + * MIME type of the text content + */ mimeType?: string; + /** + * Text content of the resource + */ text: string; } | { + /** + * URI identifying the resource + */ uri: string; + /** + * MIME type of the blob content + */ mimeType?: string; + /** + * Base64-encoded binary content of the resource + */ blob: string; }; } )[]; }; + /** + * Error details when the tool execution failed + */ error?: { + /** + * Human-readable error message + */ message: string; + /** + * Machine-readable error code + */ code?: string; }; + /** + * Tool-specific telemetry data (e.g., CodeQL check counts, grep match counts) + */ toolTelemetry?: { [k: string]: unknown; }; + /** + * Tool call ID of the parent tool invocation when this event originates from a sub-agent + */ parentToolCallId?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "skill.invoked"; data: { + /** + * Name of the invoked skill + */ name: string; + /** + * File path to the SKILL.md definition + */ path: string; + /** + * Full content of the skill file, injected into the conversation for the model + */ content: string; + /** + * Tool names that should be auto-approved when this skill is active + */ allowedTools?: string[]; + /** + * Name of the plugin this skill originated from, when applicable + */ pluginName?: string; + /** + * Version of the plugin this skill originated from, when applicable + */ pluginVersion?: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "subagent.started"; data: { + /** + * Tool call ID of the parent tool invocation that spawned this sub-agent + */ toolCallId: string; + /** + * Internal name of the sub-agent + */ agentName: string; + /** + * Human-readable display name of the sub-agent + */ agentDisplayName: string; + /** + * Description of what the sub-agent does + */ agentDescription: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "subagent.completed"; data: { + /** + * Tool call ID of the parent tool invocation that spawned this sub-agent + */ toolCallId: string; + /** + * Internal name of the sub-agent + */ agentName: string; + /** + * Human-readable display name of the sub-agent + */ agentDisplayName: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "subagent.failed"; data: { + /** + * Tool call ID of the parent tool invocation that spawned this sub-agent + */ toolCallId: string; + /** + * Internal name of the sub-agent + */ agentName: string; + /** + * Human-readable display name of the sub-agent + */ agentDisplayName: string; + /** + * Error message describing why the sub-agent failed + */ error: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "subagent.selected"; data: { + /** + * Internal name of the selected custom agent + */ agentName: string; + /** + * Human-readable display name of the selected custom agent + */ agentDisplayName: string; + /** + * List of tool names available to this agent, or null for all tools + */ tools: string[] | null; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "subagent.deselected"; + /** + * Empty payload; the event signals that the custom agent was deselected, returning to the default agent + */ data: {}; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "hook.start"; data: { + /** + * Unique identifier for this hook invocation + */ hookInvocationId: string; + /** + * Type of hook being invoked (e.g., "preToolUse", "postToolUse", "sessionStart") + */ hookType: string; - input?: unknown; + /** + * Input data passed to the hook + */ + input?: { + [k: string]: unknown; + }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "hook.end"; data: { + /** + * Identifier matching the corresponding hook.start event + */ hookInvocationId: string; + /** + * Type of hook that was invoked (e.g., "preToolUse", "postToolUse", "sessionStart") + */ hookType: string; - output?: unknown; + /** + * Output data produced by the hook + */ + output?: { + [k: string]: unknown; + }; + /** + * Whether the hook completed successfully + */ success: boolean; + /** + * Error details when the hook failed + */ error?: { + /** + * Human-readable error message + */ message: string; + /** + * Error stack trace, when available + */ stack?: string; }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; + /** + * When true, the event is transient and not persisted to the session event log on disk + */ ephemeral?: boolean; type: "system.message"; data: { + /** + * The system or developer prompt text + */ content: string; + /** + * Message role: "system" for system prompts, "developer" for developer-injected instructions + */ role: "system" | "developer"; + /** + * Optional name identifier for the message source + */ name?: string; + /** + * Metadata about the prompt template and its construction + */ metadata?: { + /** + * Version identifier of the prompt template used + */ promptVersion?: string; + /** + * Template variables used when constructing the prompt + */ variables?: { [k: string]: unknown; }; @@ -753,136 +2153,555 @@ export type SessionEvent = }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "permission.requested"; data: { + /** + * Unique identifier for this permission request; used to respond via session.respondToPermission() + */ requestId: string; + /** + * Details of the permission being requested + */ permissionRequest: | { + /** + * Permission kind discriminator + */ kind: "shell"; + /** + * Tool call ID that triggered this permission request + */ toolCallId?: string; + /** + * The complete shell command text to be executed + */ fullCommandText: string; + /** + * Human-readable description of what the command intends to do + */ intention: string; + /** + * Parsed command identifiers found in the command text + */ commands: { + /** + * Command identifier (e.g., executable name) + */ identifier: string; + /** + * Whether this command is read-only (no side effects) + */ readOnly: boolean; }[]; + /** + * File paths that may be read or written by the command + */ possiblePaths: string[]; + /** + * URLs that may be accessed by the command + */ possibleUrls: { + /** + * URL that may be accessed by the command + */ url: string; }[]; + /** + * Whether the command includes a file write redirection (e.g., > or >>) + */ hasWriteFileRedirection: boolean; + /** + * Whether the UI can offer session-wide approval for this command pattern + */ canOfferSessionApproval: boolean; + /** + * Optional warning message about risks of running this command + */ warning?: string; } | { + /** + * Permission kind discriminator + */ kind: "write"; + /** + * Tool call ID that triggered this permission request + */ toolCallId?: string; + /** + * Human-readable description of the intended file change + */ intention: string; + /** + * Path of the file being written to + */ fileName: string; + /** + * Unified diff showing the proposed changes + */ diff: string; + /** + * Complete new file contents for newly created files + */ newFileContents?: string; } | { + /** + * Permission kind discriminator + */ kind: "read"; + /** + * Tool call ID that triggered this permission request + */ toolCallId?: string; + /** + * Human-readable description of why the file is being read + */ intention: string; + /** + * Path of the file or directory being read + */ path: string; } | { + /** + * Permission kind discriminator + */ kind: "mcp"; + /** + * Tool call ID that triggered this permission request + */ toolCallId?: string; + /** + * Name of the MCP server providing the tool + */ serverName: string; + /** + * Internal name of the MCP tool + */ toolName: string; + /** + * Human-readable title of the MCP tool + */ toolTitle: string; - args?: unknown; + /** + * Arguments to pass to the MCP tool + */ + args?: { + [k: string]: unknown; + }; + /** + * Whether this MCP tool is read-only (no side effects) + */ readOnly: boolean; } | { + /** + * Permission kind discriminator + */ kind: "url"; + /** + * Tool call ID that triggered this permission request + */ toolCallId?: string; + /** + * Human-readable description of why the URL is being accessed + */ intention: string; + /** + * URL to be fetched + */ url: string; } | { + /** + * Permission kind discriminator + */ kind: "memory"; + /** + * Tool call ID that triggered this permission request + */ toolCallId?: string; + /** + * Topic or subject of the memory being stored + */ subject: string; + /** + * The fact or convention being stored + */ fact: string; + /** + * Source references for the stored fact + */ citations: string; } | { + /** + * Permission kind discriminator + */ kind: "custom-tool"; + /** + * Tool call ID that triggered this permission request + */ toolCallId?: string; + /** + * Name of the custom tool + */ toolName: string; + /** + * Description of what the custom tool does + */ toolDescription: string; - args?: unknown; + /** + * Arguments to pass to the custom tool + */ + args?: { + [k: string]: unknown; + }; }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "permission.completed"; data: { + /** + * Request ID of the resolved permission request; clients should dismiss any UI for this request + */ requestId: string; + /** + * The result of the permission request + */ + result: { + /** + * The outcome of the permission request + */ + kind: + | "approved" + | "denied-by-rules" + | "denied-no-approval-rule-and-could-not-request-from-user" + | "denied-interactively-by-user" + | "denied-by-content-exclusion-policy"; + }; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "user_input.requested"; data: { + /** + * Unique identifier for this input request; used to respond via session.respondToUserInput() + */ requestId: string; + /** + * The question or prompt to present to the user + */ question: string; + /** + * Predefined choices for the user to select from, if applicable + */ choices?: string[]; + /** + * Whether the user can provide a free-form text response in addition to predefined choices + */ allowFreeform?: boolean; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "user_input.completed"; data: { + /** + * Request ID of the resolved user input request; clients should dismiss any UI for this request + */ requestId: string; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "elicitation.requested"; data: { + /** + * Unique identifier for this elicitation request; used to respond via session.respondToElicitation() + */ requestId: string; + /** + * Message describing what information is needed from the user + */ message: string; + /** + * Elicitation mode; currently only "form" is supported. Defaults to "form" when absent. + */ mode?: "form"; + /** + * JSON Schema describing the form fields to present to the user + */ requestedSchema: { type: "object"; + /** + * Form field definitions, keyed by field name + */ properties: { [k: string]: unknown; }; + /** + * List of required field names + */ required?: string[]; }; [k: string]: unknown; }; } | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ id: string; + /** + * ISO 8601 timestamp when the event was created + */ timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ parentId: string | null; ephemeral: true; type: "elicitation.completed"; data: { + /** + * Request ID of the resolved elicitation request; clients should dismiss any UI for this request + */ + requestId: string; + }; + } + | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ + id: string; + /** + * ISO 8601 timestamp when the event was created + */ + timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ + parentId: string | null; + ephemeral: true; + type: "external_tool.requested"; + data: { + /** + * Unique identifier for this request; used to respond via session.respondToExternalTool() + */ + requestId: string; + /** + * Session ID that this external tool request belongs to + */ + sessionId: string; + /** + * Tool call ID assigned to this external tool invocation + */ + toolCallId: string; + /** + * Name of the external tool to invoke + */ + toolName: string; + /** + * Arguments to pass to the external tool + */ + arguments?: { + [k: string]: unknown; + }; + }; + } + | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ + id: string; + /** + * ISO 8601 timestamp when the event was created + */ + timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ + parentId: string | null; + ephemeral: true; + type: "external_tool.completed"; + data: { + /** + * Request ID of the resolved external tool request; clients should dismiss any UI for this request + */ + requestId: string; + }; + } + | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ + id: string; + /** + * ISO 8601 timestamp when the event was created + */ + timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ + parentId: string | null; + ephemeral: true; + type: "command.queued"; + data: { + /** + * Unique identifier for this request; used to respond via session.respondToQueuedCommand() + */ + requestId: string; + /** + * The slash command text to be executed (e.g., /help, /clear) + */ + command: string; + }; + } + | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ + id: string; + /** + * ISO 8601 timestamp when the event was created + */ + timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ + parentId: string | null; + ephemeral: true; + type: "command.completed"; + data: { + /** + * Request ID of the resolved command request; clients should dismiss any UI for this request + */ + requestId: string; + }; + } + | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ + id: string; + /** + * ISO 8601 timestamp when the event was created + */ + timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ + parentId: string | null; + ephemeral: true; + type: "exit_plan_mode.requested"; + data: { + /** + * Unique identifier for this request; used to respond via session.respondToExitPlanMode() + */ + requestId: string; + /** + * Summary of the plan that was created + */ + summary: string; + /** + * Full content of the plan file + */ + planContent: string; + /** + * Available actions the user can take (e.g., approve, edit, reject) + */ + actions: string[]; + /** + * The recommended action for the user to take + */ + recommendedAction: string; + }; + } + | { + /** + * Unique event identifier (UUID v4), generated when the event is emitted + */ + id: string; + /** + * ISO 8601 timestamp when the event was created + */ + timestamp: string; + /** + * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event. + */ + parentId: string | null; + ephemeral: true; + type: "exit_plan_mode.completed"; + data: { + /** + * Request ID of the resolved exit plan mode request; clients should dismiss any UI for this request + */ requestId: string; }; }; diff --git a/nodejs/src/sdkProtocolVersion.ts b/nodejs/src/sdkProtocolVersion.ts index 9485bc00d..0e5314374 100644 --- a/nodejs/src/sdkProtocolVersion.ts +++ b/nodejs/src/sdkProtocolVersion.ts @@ -8,7 +8,7 @@ * The SDK protocol version. * This must match the version expected by the copilot-agent-runtime server. */ -export const SDK_PROTOCOL_VERSION = 2; +export const SDK_PROTOCOL_VERSION = 3; /** * Gets the SDK protocol version. diff --git a/nodejs/src/session.ts b/nodejs/src/session.ts index f7b0ee585..bf643fae1 100644 --- a/nodejs/src/session.ts +++ b/nodejs/src/session.ts @@ -13,7 +13,6 @@ import type { MessageOptions, PermissionHandler, PermissionRequest, - PermissionRequestResult, SessionEvent, SessionEventHandler, SessionEventPayload, @@ -284,11 +283,15 @@ export class CopilotSession { /** * Dispatches an event to all registered handlers. + * Also handles broadcast request events internally (external tool calls, permissions). * * @param event - The session event to dispatch * @internal This method is for internal use by the SDK. */ _dispatchEvent(event: SessionEvent): void { + // Handle broadcast request events internally (fire-and-forget) + this._handleBroadcastEvent(event); + // Dispatch to typed handlers for this specific event type const typedHandlers = this.typedEventHandlers.get(event.type); if (typedHandlers) { @@ -311,6 +314,95 @@ export class CopilotSession { } } + /** + * Handles broadcast request events by executing local handlers and responding via RPC. + * Handlers are dispatched as fire-and-forget — rejections propagate as unhandled promise + * rejections, consistent with standard EventEmitter / event handler semantics. + * @internal + */ + private _handleBroadcastEvent(event: SessionEvent): void { + if (event.type === "external_tool.requested") { + const { requestId, toolName } = event.data as { + requestId: string; + toolName: string; + arguments: unknown; + toolCallId: string; + sessionId: string; + }; + const args = (event.data as { arguments: unknown }).arguments; + const toolCallId = (event.data as { toolCallId: string }).toolCallId; + const handler = this.toolHandlers.get(toolName); + if (handler) { + void this._executeToolAndRespond(requestId, toolName, toolCallId, args, handler); + } + } else if (event.type === "permission.requested") { + const { requestId, permissionRequest } = event.data as { + requestId: string; + permissionRequest: PermissionRequest; + }; + if (this.permissionHandler) { + void this._executePermissionAndRespond(requestId, permissionRequest); + } + } + } + + /** + * Executes a tool handler and sends the result back via RPC. + * @internal + */ + private async _executeToolAndRespond( + requestId: string, + toolName: string, + toolCallId: string, + args: unknown, + handler: ToolHandler + ): Promise { + try { + const rawResult = await handler(args, { + sessionId: this.sessionId, + toolCallId, + toolName, + arguments: args, + }); + let result: string; + if (rawResult == null) { + result = ""; + } else if (typeof rawResult === "string") { + result = rawResult; + } else { + result = JSON.stringify(rawResult); + } + await this.rpc.tools.handlePendingToolCall({ requestId, result }); + } catch (error) { + const message = + error instanceof Error ? error.message : String(error); + await this.rpc.tools.handlePendingToolCall({ requestId, error: message }); + } + } + + /** + * Executes a permission handler and sends the result back via RPC. + * @internal + */ + private async _executePermissionAndRespond( + requestId: string, + permissionRequest: PermissionRequest + ): Promise { + try { + const result = await this.permissionHandler!(permissionRequest, { + sessionId: this.sessionId, + }); + await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result }); + } catch (_error) { + await this.rpc.permissions.handlePendingPermissionRequest({ + requestId, + result: { + kind: "denied-no-approval-rule-and-could-not-request-from-user", + }, + }); + } + } + /** * Registers custom tool handlers for this session. * @@ -381,30 +473,6 @@ export class CopilotSession { this.hooks = hooks; } - /** - * Handles a permission request from the Copilot CLI. - * - * @param request - The permission request data from the CLI - * @returns A promise that resolves with the permission decision - * @internal This method is for internal use by the SDK. - */ - async _handlePermissionRequest(request: unknown): Promise { - if (!this.permissionHandler) { - // No handler registered, deny permission - return { kind: "denied-no-approval-rule-and-could-not-request-from-user" }; - } - - try { - const result = await this.permissionHandler(request as PermissionRequest, { - sessionId: this.sessionId, - }); - return result; - } catch (_error) { - // Handler failed, deny permission - return { kind: "denied-no-approval-rule-and-could-not-request-from-user" }; - } - } - /** * Handles a user input request from the Copilot CLI. * diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts index 482216a98..fe9fce312 100644 --- a/nodejs/src/types.ts +++ b/nodejs/src/types.ts @@ -44,6 +44,13 @@ export interface CopilotClientOptions { */ useStdio?: boolean; + /** + * When true, indicates the SDK is running as a child process of the Copilot CLI server, and should + * use its own stdio for communicating with the existing parent process. Can only be used in combination + * with useStdio: true. + */ + isChildProcess?: boolean; + /** * URL of an existing Copilot CLI server to connect to over TCP * When provided, the client will not spawn a CLI process diff --git a/nodejs/test/e2e/harness/sdkTestContext.ts b/nodejs/test/e2e/harness/sdkTestContext.ts index a5cf2ec57..96cccfe35 100644 --- a/nodejs/test/e2e/harness/sdkTestContext.ts +++ b/nodejs/test/e2e/harness/sdkTestContext.ts @@ -21,7 +21,8 @@ const SNAPSHOTS_DIR = resolve(__dirname, "../../../../test/snapshots"); export async function createSdkTestContext({ logLevel, -}: { logLevel?: "error" | "none" | "warning" | "info" | "debug" | "all"; cliPath?: string } = {}) { + useStdio, +}: { logLevel?: "error" | "none" | "warning" | "info" | "debug" | "all"; cliPath?: string; useStdio?: boolean } = {}) { const homeDir = realpathSync(fs.mkdtempSync(join(os.tmpdir(), "copilot-test-config-"))); const workDir = realpathSync(fs.mkdtempSync(join(os.tmpdir(), "copilot-test-work-"))); @@ -45,6 +46,7 @@ export async function createSdkTestContext({ cliPath: process.env.COPILOT_CLI_PATH, // Use fake token in CI to allow cached responses without real auth githubToken: isCI ? "fake-token-for-e2e-tests" : undefined, + useStdio: useStdio, }); const harness = { homeDir, workDir, openAiEndpoint, copilotClient, env }; diff --git a/nodejs/test/e2e/multi-client.test.ts b/nodejs/test/e2e/multi-client.test.ts new file mode 100644 index 000000000..dc2e48c33 --- /dev/null +++ b/nodejs/test/e2e/multi-client.test.ts @@ -0,0 +1,289 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All rights reserved. + *--------------------------------------------------------------------------------------------*/ + +import { describe, expect, it, afterAll } from "vitest"; +import { z } from "zod"; +import { CopilotClient, defineTool, approveAll } from "../../src/index.js"; +import type { SessionEvent } from "../../src/index.js"; +import { createSdkTestContext } from "./harness/sdkTestContext"; + +describe("Multi-client broadcast", async () => { + // Use TCP mode so a second client can connect to the same CLI process + const ctx = await createSdkTestContext({ useStdio: false }); + const client1 = ctx.copilotClient; + + // Trigger connection so we can read the port + const initSession = await client1.createSession({ onPermissionRequest: approveAll }); + await initSession.destroy(); + + const actualPort = (client1 as unknown as { actualPort: number }).actualPort; + let client2 = new CopilotClient({ cliUrl: `localhost:${actualPort}` }); + + afterAll(async () => { + await client2.stop(); + }); + + it("both clients see tool request and completion events", async () => { + const tool = defineTool("magic_number", { + description: "Returns a magic number", + parameters: z.object({ + seed: z.string().describe("A seed value"), + }), + handler: ({ seed }) => `MAGIC_${seed}_42`, + }); + + // Client 1 creates a session with a custom tool + const session1 = await client1.createSession({ + onPermissionRequest: approveAll, + tools: [tool], + }); + + // Client 2 resumes with NO tools — should not overwrite client 1's tools + const session2 = await client2.resumeSession(session1.sessionId, { + onPermissionRequest: approveAll, + }); + + // Track events seen by each client + const client1Events: SessionEvent[] = []; + const client2Events: SessionEvent[] = []; + + session1.on((event) => client1Events.push(event)); + session2.on((event) => client2Events.push(event)); + + // Send a prompt that triggers the custom tool + const response = await session1.sendAndWait({ + prompt: "Use the magic_number tool with seed 'hello' and tell me the result", + }); + + // The response should contain the tool's output + expect(response?.data.content).toContain("MAGIC_hello_42"); + + // Both clients should have seen the external_tool.requested event + const client1ToolRequested = client1Events.filter( + (e) => e.type === "external_tool.requested" + ); + const client2ToolRequested = client2Events.filter( + (e) => e.type === "external_tool.requested" + ); + expect(client1ToolRequested.length).toBeGreaterThan(0); + expect(client2ToolRequested.length).toBeGreaterThan(0); + + // Both clients should have seen the external_tool.completed event + const client1ToolCompleted = client1Events.filter( + (e) => e.type === "external_tool.completed" + ); + const client2ToolCompleted = client2Events.filter( + (e) => e.type === "external_tool.completed" + ); + expect(client1ToolCompleted.length).toBeGreaterThan(0); + expect(client2ToolCompleted.length).toBeGreaterThan(0); + + await session2.destroy(); + }); + + it("one client approves permission and both see the result", async () => { + const client1PermissionRequests: unknown[] = []; + + // Client 1 creates a session and manually approves permission requests + const session1 = await client1.createSession({ + onPermissionRequest: (request) => { + client1PermissionRequests.push(request); + return { kind: "approved" as const }; + }, + }); + + // Client 2 resumes the same session — its handler never resolves, + // so only client 1's approval takes effect (no race) + const session2 = await client2.resumeSession(session1.sessionId, { + onPermissionRequest: () => new Promise(() => {}), + }); + + // Track events seen by each client + const client1Events: SessionEvent[] = []; + const client2Events: SessionEvent[] = []; + + session1.on((event) => client1Events.push(event)); + session2.on((event) => client2Events.push(event)); + + // Send a prompt that triggers a write operation (requires permission) + const response = await session1.sendAndWait({ + prompt: "Create a file called hello.txt containing the text 'hello world'", + }); + + expect(response?.data.content).toBeTruthy(); + + // Client 1 should have handled the permission request + expect(client1PermissionRequests.length).toBeGreaterThan(0); + + // Both clients should have seen permission.requested events + const client1PermRequested = client1Events.filter( + (e) => e.type === "permission.requested" + ); + const client2PermRequested = client2Events.filter( + (e) => e.type === "permission.requested" + ); + expect(client1PermRequested.length).toBeGreaterThan(0); + expect(client2PermRequested.length).toBeGreaterThan(0); + + // Both clients should have seen permission.completed events with approved result + const client1PermCompleted = client1Events.filter( + (e): e is SessionEvent & { type: "permission.completed" } => e.type === "permission.completed" + ); + const client2PermCompleted = client2Events.filter( + (e): e is SessionEvent & { type: "permission.completed" } => e.type === "permission.completed" + ); + expect(client1PermCompleted.length).toBeGreaterThan(0); + expect(client2PermCompleted.length).toBeGreaterThan(0); + for (const event of [...client1PermCompleted, ...client2PermCompleted]) { + expect(event.data.result.kind).toBe("approved"); + } + + await session2.destroy(); + }); + + it("one client rejects permission and both see the result", async () => { + // Client 1 creates a session and denies all permission requests + const session1 = await client1.createSession({ + onPermissionRequest: () => ({ kind: "denied-interactively-by-user" as const }), + }); + + // Client 2 resumes — its handler never resolves so only client 1's denial takes effect + const session2 = await client2.resumeSession(session1.sessionId, { + onPermissionRequest: () => new Promise(() => {}), + }); + + const client1Events: SessionEvent[] = []; + const client2Events: SessionEvent[] = []; + + session1.on((event) => client1Events.push(event)); + session2.on((event) => client2Events.push(event)); + + // Ask the agent to write a file (requires permission) + const { writeFile } = await import("fs/promises"); + const { join } = await import("path"); + const testFile = join(ctx.workDir, "protected.txt"); + await writeFile(testFile, "protected content"); + + await session1.sendAndWait({ + prompt: "Edit protected.txt and replace 'protected' with 'hacked'.", + }); + + // Verify the file was NOT modified (permission was denied) + const { readFile } = await import("fs/promises"); + const content = await readFile(testFile, "utf-8"); + expect(content).toBe("protected content"); + + // Both clients should have seen permission.requested and permission.completed + expect(client1Events.filter((e) => e.type === "permission.requested").length).toBeGreaterThan(0); + expect(client2Events.filter((e) => e.type === "permission.requested").length).toBeGreaterThan(0); + + // Both clients should see the denial in the completed event + const client1PermCompleted = client1Events.filter( + (e): e is SessionEvent & { type: "permission.completed" } => e.type === "permission.completed" + ); + const client2PermCompleted = client2Events.filter( + (e): e is SessionEvent & { type: "permission.completed" } => e.type === "permission.completed" + ); + expect(client1PermCompleted.length).toBeGreaterThan(0); + expect(client2PermCompleted.length).toBeGreaterThan(0); + for (const event of [...client1PermCompleted, ...client2PermCompleted]) { + expect(event.data.result.kind).toBe("denied-interactively-by-user"); + } + + await session2.destroy(); + }); + + it("two clients register different tools and agent uses both", { timeout: 90_000 }, async () => { + const toolA = defineTool("city_lookup", { + description: "Returns a city name for a given country code", + parameters: z.object({ + countryCode: z.string().describe("A two-letter country code"), + }), + handler: ({ countryCode }) => `CITY_FOR_${countryCode}`, + }); + + const toolB = defineTool("currency_lookup", { + description: "Returns a currency for a given country code", + parameters: z.object({ + countryCode: z.string().describe("A two-letter country code"), + }), + handler: ({ countryCode }) => `CURRENCY_FOR_${countryCode}`, + }); + + // Client 1 creates a session with tool A + const session1 = await client1.createSession({ + onPermissionRequest: approveAll, + tools: [toolA], + }); + + // Client 2 resumes with tool B (different tool, union should have both) + const session2 = await client2.resumeSession(session1.sessionId, { + onPermissionRequest: approveAll, + tools: [toolB], + }); + + // Send a prompt that requires both tools + const response = await session1.sendAndWait({ + prompt: + "Use the city_lookup tool with countryCode 'US' and the currency_lookup tool with countryCode 'US'. Tell me both results.", + }); + + expect(response?.data.content).toContain("CITY_FOR_US"); + expect(response?.data.content).toContain("CURRENCY_FOR_US"); + + await session2.destroy(); + }); + + it("disconnecting client removes its tools", { timeout: 90_000 }, async () => { + const toolA = defineTool("stable_tool", { + description: "A tool that persists across disconnects", + parameters: z.object({ input: z.string() }), + handler: ({ input }) => `STABLE_${input}`, + }); + + const toolB = defineTool("ephemeral_tool", { + description: "A tool that will disappear when its client disconnects", + parameters: z.object({ input: z.string() }), + handler: ({ input }) => `EPHEMERAL_${input}`, + }); + + // Client 1 creates a session with stable_tool + const session1 = await client1.createSession({ + onPermissionRequest: approveAll, + tools: [toolA], + }); + + // Client 2 resumes with ephemeral_tool + await client2.resumeSession(session1.sessionId, { + onPermissionRequest: approveAll, + tools: [toolB], + }); + + // Verify both tools work before disconnect + const bothResponse = await session1.sendAndWait({ + prompt: + "Use the stable_tool with input 'test1' and the ephemeral_tool with input 'test2'. Tell me both results.", + }); + expect(bothResponse?.data.content).toContain("STABLE_test1"); + expect(bothResponse?.data.content).toContain("EPHEMERAL_test2"); + + // Disconnect client 2 without destroying the shared session + await client2.forceStop(); + + // Give the server time to process the connection close and remove tools + await new Promise((resolve) => setTimeout(resolve, 500)); + + // Recreate client2 for cleanup in afterAll (but don't rejoin the session) + client2 = new CopilotClient({ cliUrl: `localhost:${actualPort}` }); + + // Now only stable_tool should be available + const afterResponse = await session1.sendAndWait({ + prompt: + "Use the stable_tool with input 'still_here'. Also try using ephemeral_tool if it is available.", + }); + expect(afterResponse?.data.content).toContain("STABLE_still_here"); + // ephemeral_tool should NOT have produced a result + expect(afterResponse?.data.content).not.toContain("EPHEMERAL_"); + }); +}); diff --git a/nodejs/test/e2e/tools.test.ts b/nodejs/test/e2e/tools.test.ts index 724f36b90..3f5c3e09f 100644 --- a/nodejs/test/e2e/tools.test.ts +++ b/nodejs/test/e2e/tools.test.ts @@ -37,7 +37,6 @@ describe("Custom tools", async () => { handler: ({ input }) => input.toUpperCase(), }), ], - onPermissionRequest: approveAll, }); const assistantMessage = await session.sendAndWait({ @@ -57,7 +56,6 @@ describe("Custom tools", async () => { }, }), ], - onPermissionRequest: approveAll, }); const answer = await session.sendAndWait({ @@ -114,7 +112,6 @@ describe("Custom tools", async () => { }, }), ], - onPermissionRequest: approveAll, }); const assistantMessage = await session.sendAndWait({ diff --git a/test/snapshots/multi_client/both_clients_see_tool_request_and_completion_events.yaml b/test/snapshots/multi_client/both_clients_see_tool_request_and_completion_events.yaml new file mode 100644 index 000000000..b4b14d0ea --- /dev/null +++ b/test/snapshots/multi_client/both_clients_see_tool_request_and_completion_events.yaml @@ -0,0 +1,50 @@ +models: + - claude-sonnet-4.5 +conversations: + - messages: + - role: system + content: ${system} + - role: user + content: Use the magic_number tool with seed 'hello' and tell me the result + - role: assistant + content: I'll use the magic_number tool with seed 'hello' for you. + - role: assistant + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Getting magic number"}' + - role: assistant + tool_calls: + - id: toolcall_1 + type: function + function: + name: magic_number + arguments: '{"seed":"hello"}' + - messages: + - role: system + content: ${system} + - role: user + content: Use the magic_number tool with seed 'hello' and tell me the result + - role: assistant + content: I'll use the magic_number tool with seed 'hello' for you. + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Getting magic number"}' + - id: toolcall_1 + type: function + function: + name: magic_number + arguments: '{"seed":"hello"}' + - role: tool + tool_call_id: toolcall_0 + content: Intent logged + - role: tool + tool_call_id: toolcall_1 + content: MAGIC_hello_42 + - role: assistant + content: The magic number for seed 'hello' is **MAGIC_hello_42**. diff --git a/test/snapshots/multi_client/disconnecting_client_removes_its_tools.yaml b/test/snapshots/multi_client/disconnecting_client_removes_its_tools.yaml new file mode 100644 index 000000000..f763e7987 --- /dev/null +++ b/test/snapshots/multi_client/disconnecting_client_removes_its_tools.yaml @@ -0,0 +1,175 @@ +models: + - claude-sonnet-4.5 +conversations: + - messages: + - role: system + content: ${system} + - role: user + content: Use the stable_tool with input 'test1' and the ephemeral_tool with input 'test2'. Tell me both results. + - role: assistant + content: I'll call both tools for you and report the results. + - role: assistant + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Testing stable and ephemeral tools"}' + - role: assistant + tool_calls: + - id: toolcall_1 + type: function + function: + name: stable_tool + arguments: '{"input":"test1"}' + - role: assistant + tool_calls: + - id: toolcall_2 + type: function + function: + name: ephemeral_tool + arguments: '{"input":"test2"}' + - messages: + - role: system + content: ${system} + - role: user + content: Use the stable_tool with input 'test1' and the ephemeral_tool with input 'test2'. Tell me both results. + - role: assistant + content: I'll call both tools for you and report the results. + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Testing stable and ephemeral tools"}' + - id: toolcall_1 + type: function + function: + name: stable_tool + arguments: '{"input":"test1"}' + - id: toolcall_2 + type: function + function: + name: ephemeral_tool + arguments: '{"input":"test2"}' + - role: tool + tool_call_id: toolcall_0 + content: Intent logged + - role: tool + tool_call_id: toolcall_1 + content: STABLE_test1 + - role: tool + tool_call_id: toolcall_2 + content: EPHEMERAL_test2 + - role: assistant + content: |- + Both tools executed successfully: + - **stable_tool** returned: `STABLE_test1` + - **ephemeral_tool** returned: `EPHEMERAL_test2` + - role: user + content: >- + + + Tools no longer available: ephemeral_tool + + + Important: Do not attempt to call tools that are no longer available unless you've been notified that they're + available again. + + + + + Use the stable_tool with input 'still_here'. Also try using ephemeral_tool if it is available. + - role: assistant + content: I'll call the stable_tool and check on the ephemeral_tool availability. + - role: assistant + tool_calls: + - id: toolcall_3 + type: function + function: + name: report_intent + arguments: '{"intent":"Testing tool availability"}' + - role: assistant + tool_calls: + - id: toolcall_4 + type: function + function: + name: stable_tool + arguments: '{"input":"still_here"}' + - messages: + - role: system + content: ${system} + - role: user + content: Use the stable_tool with input 'test1' and the ephemeral_tool with input 'test2'. Tell me both results. + - role: assistant + content: I'll call both tools for you and report the results. + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Testing stable and ephemeral tools"}' + - id: toolcall_1 + type: function + function: + name: stable_tool + arguments: '{"input":"test1"}' + - id: toolcall_2 + type: function + function: + name: ephemeral_tool + arguments: '{"input":"test2"}' + - role: tool + tool_call_id: toolcall_0 + content: Intent logged + - role: tool + tool_call_id: toolcall_1 + content: STABLE_test1 + - role: tool + tool_call_id: toolcall_2 + content: EPHEMERAL_test2 + - role: assistant + content: |- + Both tools executed successfully: + - **stable_tool** returned: `STABLE_test1` + - **ephemeral_tool** returned: `EPHEMERAL_test2` + - role: user + content: >- + + + Tools no longer available: ephemeral_tool + + + Important: Do not attempt to call tools that are no longer available unless you've been notified that they're + available again. + + + + + Use the stable_tool with input 'still_here'. Also try using ephemeral_tool if it is available. + - role: assistant + content: I'll call the stable_tool and check on the ephemeral_tool availability. + tool_calls: + - id: toolcall_3 + type: function + function: + name: report_intent + arguments: '{"intent":"Testing tool availability"}' + - id: toolcall_4 + type: function + function: + name: stable_tool + arguments: '{"input":"still_here"}' + - role: tool + tool_call_id: toolcall_3 + content: Intent logged + - role: tool + tool_call_id: toolcall_4 + content: STABLE_still_here + - role: assistant + content: >- + **stable_tool** returned: `STABLE_still_here` + + + The **ephemeral_tool** is no longer available (it was removed as indicated in the tools_changed_notice), so I + couldn't call it. diff --git a/test/snapshots/multi_client/one_client_approves_permission_and_both_see_the_result.yaml b/test/snapshots/multi_client/one_client_approves_permission_and_both_see_the_result.yaml new file mode 100644 index 000000000..b86427936 --- /dev/null +++ b/test/snapshots/multi_client/one_client_approves_permission_and_both_see_the_result.yaml @@ -0,0 +1,50 @@ +models: + - claude-sonnet-4.5 +conversations: + - messages: + - role: system + content: ${system} + - role: user + content: Create a file called hello.txt containing the text 'hello world' + - role: assistant + content: I'll create the hello.txt file with the text 'hello world'. + - role: assistant + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Creating hello.txt file"}' + - role: assistant + tool_calls: + - id: toolcall_1 + type: function + function: + name: create + arguments: '{"file_text":"hello world","path":"${workdir}/hello.txt"}' + - messages: + - role: system + content: ${system} + - role: user + content: Create a file called hello.txt containing the text 'hello world' + - role: assistant + content: I'll create the hello.txt file with the text 'hello world'. + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Creating hello.txt file"}' + - id: toolcall_1 + type: function + function: + name: create + arguments: '{"file_text":"hello world","path":"${workdir}/hello.txt"}' + - role: tool + tool_call_id: toolcall_0 + content: Intent logged + - role: tool + tool_call_id: toolcall_1 + content: Created file ${workdir}/hello.txt with 11 characters + - role: assistant + content: Done! I've created the file `hello.txt` containing the text 'hello world'. diff --git a/test/snapshots/multi_client/one_client_rejects_permission_and_both_see_the_result.yaml b/test/snapshots/multi_client/one_client_rejects_permission_and_both_see_the_result.yaml new file mode 100644 index 000000000..ba9db87d0 --- /dev/null +++ b/test/snapshots/multi_client/one_client_rejects_permission_and_both_see_the_result.yaml @@ -0,0 +1,25 @@ +models: + - claude-sonnet-4.5 +conversations: + - messages: + - role: system + content: ${system} + - role: user + content: Edit protected.txt and replace 'protected' with 'hacked'. + - role: assistant + content: I'll help you edit protected.txt to replace 'protected' with 'hacked'. Let me first view the file and then make + the change. + - role: assistant + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Editing protected.txt file"}' + - role: assistant + tool_calls: + - id: toolcall_1 + type: function + function: + name: view + arguments: '{"path":"${workdir}/protected.txt"}' diff --git a/test/snapshots/multi_client/two_clients_register_different_tools_and_agent_uses_both.yaml b/test/snapshots/multi_client/two_clients_register_different_tools_and_agent_uses_both.yaml new file mode 100644 index 000000000..db3a827aa --- /dev/null +++ b/test/snapshots/multi_client/two_clients_register_different_tools_and_agent_uses_both.yaml @@ -0,0 +1,70 @@ +models: + - claude-sonnet-4.5 +conversations: + - messages: + - role: system + content: ${system} + - role: user + content: Use the city_lookup tool with countryCode 'US' and the currency_lookup tool with countryCode 'US'. Tell me both + results. + - role: assistant + content: I'll call both tools for you with the country code 'US'. + - role: assistant + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Looking up city and currency"}' + - role: assistant + tool_calls: + - id: toolcall_1 + type: function + function: + name: city_lookup + arguments: '{"countryCode":"US"}' + - role: assistant + tool_calls: + - id: toolcall_2 + type: function + function: + name: currency_lookup + arguments: '{"countryCode":"US"}' + - messages: + - role: system + content: ${system} + - role: user + content: Use the city_lookup tool with countryCode 'US' and the currency_lookup tool with countryCode 'US'. Tell me both + results. + - role: assistant + content: I'll call both tools for you with the country code 'US'. + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: '{"intent":"Looking up city and currency"}' + - id: toolcall_1 + type: function + function: + name: city_lookup + arguments: '{"countryCode":"US"}' + - id: toolcall_2 + type: function + function: + name: currency_lookup + arguments: '{"countryCode":"US"}' + - role: tool + tool_call_id: toolcall_0 + content: Intent logged + - role: tool + tool_call_id: toolcall_1 + content: CITY_FOR_US + - role: tool + tool_call_id: toolcall_2 + content: CURRENCY_FOR_US + - role: assistant + content: |- + Here are the results: + - **City for US**: CITY_FOR_US + - **Currency for US**: CURRENCY_FOR_US diff --git a/test/snapshots/tools/handles_tool_calling_errors.yaml b/test/snapshots/tools/handles_tool_calling_errors.yaml index d6f5fba29..33226722d 100644 --- a/test/snapshots/tools/handles_tool_calling_errors.yaml +++ b/test/snapshots/tools/handles_tool_calling_errors.yaml @@ -15,6 +15,6 @@ conversations: arguments: "{}" - role: tool tool_call_id: toolcall_0 - content: Invoking this tool produced an error. Detailed information is not available. + content: "Failed to execute `get_user_location` tool with arguments: {} due to error: Error: Tool execution failed" - role: assistant - content: unknown + content: Your location is unknown. diff --git a/test/snapshots/tools/invokes_built_in_tools.yaml b/test/snapshots/tools/invokes_built_in_tools.yaml index a0b83d959..068cc4acc 100644 --- a/test/snapshots/tools/invokes_built_in_tools.yaml +++ b/test/snapshots/tools/invokes_built_in_tools.yaml @@ -17,8 +17,4 @@ conversations: tool_call_id: toolcall_0 content: "1. # ELIZA, the only chatbot you'll ever need" - role: assistant - content: |- - The first line of README.md is: - ``` - # ELIZA, the only chatbot you'll ever need - ``` + content: "The first line of README.md is: `# ELIZA, the only chatbot you'll ever need`" diff --git a/test/snapshots/tools/invokes_custom_tool.yaml b/test/snapshots/tools/invokes_custom_tool.yaml index fcb6fa726..6f212e4a7 100644 --- a/test/snapshots/tools/invokes_custom_tool.yaml +++ b/test/snapshots/tools/invokes_custom_tool.yaml @@ -17,4 +17,7 @@ conversations: tool_call_id: toolcall_0 content: HELLO - role: assistant - content: "The encrypted string is: **HELLO**" + content: |- + The encrypted string is: **HELLO** + + (This is a simple cipher that converts the string to uppercase.) diff --git a/test/snapshots/tools/invokes_custom_tool_with_permission_handler.yaml b/test/snapshots/tools/invokes_custom_tool_with_permission_handler.yaml index 5b046d4c3..fcb6fa726 100644 --- a/test/snapshots/tools/invokes_custom_tool_with_permission_handler.yaml +++ b/test/snapshots/tools/invokes_custom_tool_with_permission_handler.yaml @@ -17,4 +17,4 @@ conversations: tool_call_id: toolcall_0 content: HELLO - role: assistant - content: "The encrypted result is: **HELLO**" + content: "The encrypted string is: **HELLO**" diff --git a/test/snapshots/tools/overrides_built_in_tool_with_custom_tool.yaml b/test/snapshots/tools/overrides_built_in_tool_with_custom_tool.yaml index 6865beeb5..ec8dc20ef 100644 --- a/test/snapshots/tools/overrides_built_in_tool_with_custom_tool.yaml +++ b/test/snapshots/tools/overrides_built_in_tool_with_custom_tool.yaml @@ -7,14 +7,45 @@ conversations: - role: user content: Use grep to search for the word 'hello' - role: assistant + content: I'll search for the word 'hello' in the current directory. + - role: assistant + tool_calls: + - id: toolcall_0 + type: function + function: + name: report_intent + arguments: "{\"intent\":\"Searching for 'hello'\"}" + - role: assistant + tool_calls: + - id: toolcall_1 + type: function + function: + name: grep + arguments: '{"query":"hello"}' + - messages: + - role: system + content: ${system} + - role: user + content: Use grep to search for the word 'hello' + - role: assistant + content: I'll search for the word 'hello' in the current directory. tool_calls: - id: toolcall_0 + type: function + function: + name: report_intent + arguments: "{\"intent\":\"Searching for 'hello'\"}" + - id: toolcall_1 type: function function: name: grep arguments: '{"query":"hello"}' - role: tool tool_call_id: toolcall_0 + content: Intent logged + - role: tool + tool_call_id: toolcall_1 content: "CUSTOM_GREP_RESULT: hello" - role: assistant - content: "The grep result is: **CUSTOM_GREP_RESULT: hello**" + content: 'The grep search found a result for "hello" in the current directory. The output shows `CUSTOM_GREP_RESULT: + hello`, indicating the custom grep implementation found a match.'