From a8e26b4fd99a429169e10e5e65f2ad7be915dee0 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 4 Feb 2026 13:46:46 +0100 Subject: [PATCH] feat: Stabilize Session Config Options updates the schema to 0.10.8 Also adds unstable support for session usage --- schema/schema.json | 157 +++++++++++++++++++++++---- scripts/generate.js | 2 +- src/acp.ts | 20 +--- src/schema/index.ts | 3 + src/schema/types.gen.ts | 193 ++++++++++++++++++---------------- src/schema/zod.gen.ts | 228 ++++++++++++++++++++++------------------ 6 files changed, 378 insertions(+), 225 deletions(-) diff --git a/schema/schema.json b/schema/schema.json index c7e8534..f6bed4a 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -718,7 +718,7 @@ "$ref": "#/$defs/SetSessionConfigOptionRequest" } ], - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSets the current value for a session configuration option.", + "description": "Sets the current value for a session configuration option.", "title": "SetSessionConfigOptionRequest" }, { @@ -867,7 +867,7 @@ "x-docs-ignore": true }, "ConfigOptionUpdate": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSession configuration options have been updated.", + "description": "Session configuration options have been updated.", "properties": { "_meta": { "additionalProperties": true, @@ -1013,6 +1013,22 @@ "required": ["content"], "type": "object" }, + "Cost": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCost information for a session.", + "properties": { + "amount": { + "description": "Total cumulative cost for session.", + "format": "double", + "type": "number" + }, + "currency": { + "description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\").", + "type": "string" + } + }, + "required": ["amount", "currency"], + "type": "object" + }, "CreateTerminalRequest": { "description": "Request to create a new terminal and execute a command.", "properties": { @@ -1352,7 +1368,7 @@ "type": ["object", "null"] }, "configOptions": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.", + "description": "Initial session configuration options if supported by the Agent.", "items": { "$ref": "#/$defs/SessionConfigOption" }, @@ -1706,7 +1722,7 @@ "type": ["object", "null"] }, "configOptions": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.", + "description": "Initial session configuration options if supported by the Agent.", "items": { "$ref": "#/$defs/SessionConfigOption" }, @@ -1960,7 +1976,7 @@ "type": ["object", "null"] }, "configOptions": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.", + "description": "Initial session configuration options if supported by the Agent.", "items": { "$ref": "#/$defs/SessionConfigOption" }, @@ -2224,6 +2240,17 @@ } ], "description": "Indicates why the agent stopped processing the turn." + }, + "usage": { + "anyOf": [ + { + "$ref": "#/$defs/Usage" + }, + { + "type": "null" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for this turn (optional)." } }, "required": ["stopReason"], @@ -2527,7 +2554,7 @@ "type": ["object", "null"] }, "configOptions": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial session configuration options if supported by the Agent.", + "description": "Initial session configuration options if supported by the Agent.", "items": { "$ref": "#/$defs/SessionConfigOption" }, @@ -2630,15 +2657,15 @@ "type": "object" }, "SessionConfigGroupId": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session configuration option value group.", + "description": "Unique identifier for a session configuration option value group.", "type": "string" }, "SessionConfigId": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session configuration option.", + "description": "Unique identifier for a session configuration option.", "type": "string" }, "SessionConfigOption": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session configuration option selector and its current state.", + "description": "A session configuration option selector and its current state.", "discriminator": { "propertyName": "type" }, @@ -2720,10 +2747,10 @@ "type": "string" } ], - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSemantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec." + "description": "Semantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec." }, "SessionConfigSelect": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA single-value selector (dropdown) session configuration option payload.", + "description": "A single-value selector (dropdown) session configuration option payload.", "properties": { "currentValue": { "allOf": [ @@ -2746,7 +2773,7 @@ "type": "object" }, "SessionConfigSelectGroup": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA group of possible values for a session configuration option.", + "description": "A group of possible values for a session configuration option.", "properties": { "_meta": { "additionalProperties": true, @@ -2777,7 +2804,7 @@ "type": "object" }, "SessionConfigSelectOption": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA possible value for a session configuration option.", + "description": "A possible value for a session configuration option.", "properties": { "_meta": { "additionalProperties": true, @@ -2823,10 +2850,10 @@ "type": "array" } ], - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nPossible values for a session configuration option." + "description": "Possible values for a session configuration option." }, "SessionConfigValueId": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a session configuration option value.", + "description": "Unique identifier for a session configuration option value.", "type": "string" }, "SessionForkCapabilities": { @@ -3166,7 +3193,7 @@ "$ref": "#/$defs/ConfigOptionUpdate" } ], - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSession configuration options have been updated.", + "description": "Session configuration options have been updated.", "properties": { "sessionUpdate": { "const": "config_option_update", @@ -3191,11 +3218,27 @@ }, "required": ["sessionUpdate"], "type": "object" + }, + { + "allOf": [ + { + "$ref": "#/$defs/UsageUpdate" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for the session.", + "properties": { + "sessionUpdate": { + "const": "usage_update", + "type": "string" + } + }, + "required": ["sessionUpdate"], + "type": "object" } ] }, "SetSessionConfigOptionRequest": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for setting a session configuration option.", + "description": "Request parameters for setting a session configuration option.", "properties": { "_meta": { "additionalProperties": true, @@ -3233,7 +3276,7 @@ "x-side": "agent" }, "SetSessionConfigOptionResponse": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `session/set_config_option` method.", + "description": "Response to `session/set_config_option` method.", "properties": { "_meta": { "additionalProperties": true, @@ -3813,6 +3856,84 @@ "required": ["hint"], "type": "object" }, + "Usage": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage information for a prompt turn.", + "properties": { + "cachedReadTokens": { + "description": "Total cache read tokens.", + "format": "uint64", + "minimum": 0, + "type": ["integer", "null"] + }, + "cachedWriteTokens": { + "description": "Total cache write tokens.", + "format": "uint64", + "minimum": 0, + "type": ["integer", "null"] + }, + "inputTokens": { + "description": "Total input tokens across all turns.", + "format": "uint64", + "minimum": 0, + "type": "integer" + }, + "outputTokens": { + "description": "Total output tokens across all turns.", + "format": "uint64", + "minimum": 0, + "type": "integer" + }, + "thoughtTokens": { + "description": "Total thought/reasoning tokens", + "format": "uint64", + "minimum": 0, + "type": ["integer", "null"] + }, + "totalTokens": { + "description": "Sum of all token types across session.", + "format": "uint64", + "minimum": 0, + "type": "integer" + } + }, + "required": ["totalTokens", "inputTokens", "outputTokens"], + "type": "object" + }, + "UsageUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for a session.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + }, + "cost": { + "anyOf": [ + { + "$ref": "#/$defs/Cost" + }, + { + "type": "null" + } + ], + "description": "Cumulative session cost (optional)." + }, + "size": { + "description": "Total context window size in tokens.", + "format": "uint64", + "minimum": 0, + "type": "integer" + }, + "used": { + "description": "Tokens currently in context.", + "format": "uint64", + "minimum": 0, + "type": "integer" + } + }, + "required": ["used", "size"], + "type": "object" + }, "WaitForTerminalExitRequest": { "description": "Request to wait for a terminal command to exit.", "properties": { diff --git a/scripts/generate.js b/scripts/generate.js index 0989bbb..2667027 100644 --- a/scripts/generate.js +++ b/scripts/generate.js @@ -5,7 +5,7 @@ import * as fs from "fs/promises"; import { dirname } from "path"; import * as prettier from "prettier"; -const CURRENT_SCHEMA_RELEASE = "v0.10.7"; +const CURRENT_SCHEMA_RELEASE = "v0.10.8"; await main(); diff --git a/src/acp.ts b/src/acp.ts index b534879..171ff52 100644 --- a/src/acp.ts +++ b/src/acp.ts @@ -112,12 +112,12 @@ export class AgentSideConnection { return result ?? {}; } case schema.AGENT_METHODS.session_set_config_option: { - if (!agent.unstable_setSessionConfigOption) { + if (!agent.setSessionConfigOption) { throw RequestError.methodNotFound(method); } const validatedParams = validate.zSetSessionConfigOptionRequest.parse(params); - return agent.unstable_setSessionConfigOption(validatedParams); + return agent.setSessionConfigOption(validatedParams); } default: if (agent.extMethod) { @@ -727,18 +727,12 @@ export class ClientSideConnection implements Agent { } /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Set a configuration option for a given session. * * The response contains the full set of configuration options and their current values, * as changing one option may affect the available values or state of other options. - * - * @experimental */ - async unstable_setSessionConfigOption( + async setSessionConfigOption( params: schema.SetSessionConfigOptionRequest, ): Promise { return await this.#connection.sendRequest( @@ -1552,18 +1546,12 @@ export interface Agent { params: schema.SetSessionModelRequest, ): Promise; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Set a configuration option for a given session. * * The response contains the full set of configuration options and their current values, * as changing one option may affect the available values or state of other options. - * - * @experimental */ - unstable_setSessionConfigOption?( + setSessionConfigOption?( params: schema.SetSessionConfigOptionRequest, ): Promise; /** diff --git a/src/schema/index.ts b/src/schema/index.ts index 9575677..958bc84 100644 --- a/src/schema/index.ts +++ b/src/schema/index.ts @@ -24,6 +24,7 @@ export type { Content, ContentBlock, ContentChunk, + Cost, CreateTerminalRequest, CreateTerminalResponse, CurrentModeUpdate, @@ -126,6 +127,8 @@ export type { ToolCallUpdate, ToolKind, UnstructuredCommandInput, + Usage, + UsageUpdate, WaitForTerminalExitRequest, WaitForTerminalExitResponse, WriteTextFileRequest, diff --git a/src/schema/types.gen.ts b/src/schema/types.gen.ts index c7e63b8..0bc9422 100644 --- a/src/schema/types.gen.ts +++ b/src/schema/types.gen.ts @@ -401,13 +401,7 @@ export type ClientResponse = }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Session configuration options have been updated. - * - * @experimental */ export type ConfigOptionUpdate = { /** @@ -499,6 +493,26 @@ export type ContentChunk = { content: ContentBlock; }; +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Cost information for a session. + * + * @experimental + */ +export type Cost = { + /** + * Total cumulative cost for session. + */ + amount: number; + /** + * ISO 4217 currency code (e.g., "USD", "EUR"). + */ + currency: string; +}; + /** * Request to create a new terminal and execute a command. */ @@ -826,13 +840,7 @@ export type ForkSessionResponse = { [key: string]: unknown; } | null; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Initial session configuration options if supported by the Agent. - * - * @experimental */ configOptions?: Array | null; /** @@ -1161,13 +1169,7 @@ export type LoadSessionResponse = { [key: string]: unknown; } | null; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Initial session configuration options if supported by the Agent. - * - * @experimental */ configOptions?: Array | null; /** @@ -1405,13 +1407,7 @@ export type NewSessionResponse = { [key: string]: unknown; } | null; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Initial session configuration options if supported by the Agent. - * - * @experimental */ configOptions?: Array | null; /** @@ -1663,6 +1659,16 @@ export type PromptResponse = { * Indicates why the agent stopped processing the turn. */ stopReason: StopReason; + /** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Token usage for this turn (optional). + * + * @experimental + */ + usage?: Usage | null; }; /** @@ -1923,13 +1929,7 @@ export type ResumeSessionResponse = { [key: string]: unknown; } | null; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Initial session configuration options if supported by the Agent. - * - * @experimental */ configOptions?: Array | null; /** @@ -2030,24 +2030,12 @@ export type SessionCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for a session configuration option value group. - * - * @experimental */ export type SessionConfigGroupId = string; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for a session configuration option. - * - * @experimental */ export type SessionConfigId = string; @@ -2083,10 +2071,6 @@ export type SessionConfigOption = SessionConfigSelect & { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Semantic category for a session configuration option. * * This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs @@ -2096,8 +2080,6 @@ export type SessionConfigOption = SessionConfigSelect & { * * Category names beginning with `_` are free for custom use, like other ACP extension methods. * Category names that do not begin with `_` are reserved for the ACP spec. - * - * @experimental */ export type SessionConfigOptionCategory = | "mode" @@ -2106,13 +2088,7 @@ export type SessionConfigOptionCategory = | string; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * A single-value selector (dropdown) session configuration option payload. - * - * @experimental */ export type SessionConfigSelect = { /** @@ -2126,13 +2102,7 @@ export type SessionConfigSelect = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * A group of possible values for a session configuration option. - * - * @experimental */ export type SessionConfigSelectGroup = { /** @@ -2160,13 +2130,7 @@ export type SessionConfigSelectGroup = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * A possible value for a session configuration option. - * - * @experimental */ export type SessionConfigSelectOption = { /** @@ -2194,26 +2158,14 @@ export type SessionConfigSelectOption = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Possible values for a session configuration option. - * - * @experimental */ export type SessionConfigSelectOptions = | Array | Array; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for a session configuration option value. - * - * @experimental */ export type SessionConfigValueId = string; @@ -2505,16 +2457,13 @@ export type SessionUpdate = }) | (SessionInfoUpdate & { sessionUpdate: "session_info_update"; + }) + | (UsageUpdate & { + sessionUpdate: "usage_update"; }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request parameters for setting a session configuration option. - * - * @experimental */ export type SetSessionConfigOptionRequest = { /** @@ -2542,13 +2491,7 @@ export type SetSessionConfigOptionRequest = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response to `session/set_config_option` method. - * - * @experimental */ export type SetSessionConfigOptionResponse = { /** @@ -3008,6 +2951,76 @@ export type UnstructuredCommandInput = { hint: string; }; +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Token usage information for a prompt turn. + * + * @experimental + */ +export type Usage = { + /** + * Total cache read tokens. + */ + cachedReadTokens?: bigint | null; + /** + * Total cache write tokens. + */ + cachedWriteTokens?: bigint | null; + /** + * Total input tokens across all turns. + */ + inputTokens: bigint; + /** + * Total output tokens across all turns. + */ + outputTokens: bigint; + /** + * Total thought/reasoning tokens + */ + thoughtTokens?: bigint | null; + /** + * Sum of all token types across session. + */ + totalTokens: bigint; +}; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Context window and cost update for a session. + * + * @experimental + */ +export type UsageUpdate = { + /** + * The _meta property is reserved by ACP to allow clients and agents to attach additional + * metadata to their interactions. Implementations MUST NOT make assumptions about values at + * these keys. + * + * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + */ + _meta?: { + [key: string]: unknown; + } | null; + /** + * Cumulative session cost (optional). + */ + cost?: Cost | null; + /** + * Total context window size in tokens. + */ + size: bigint; + /** + * Tokens currently in context. + */ + used: bigint; +}; + /** * Request to wait for a terminal command to exit. */ diff --git a/src/schema/zod.gen.ts b/src/schema/zod.gen.ts index 0a2df9f..935c520 100644 --- a/src/schema/zod.gen.ts +++ b/src/schema/zod.gen.ts @@ -39,6 +39,20 @@ export const zBlobResourceContents = z.object({ uri: z.string(), }); +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Cost information for a session. + * + * @experimental + */ +export const zCost = z.object({ + amount: z.number(), + currency: z.string(), +}); + /** * Response containing the ID of the created terminal. */ @@ -585,32 +599,16 @@ export const zRequestPermissionResponse = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for a session configuration option value group. - * - * @experimental */ export const zSessionConfigGroupId = z.string(); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for a session configuration option. - * - * @experimental */ export const zSessionConfigId = z.string(); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Semantic category for a session configuration option. * * This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs @@ -620,8 +618,6 @@ export const zSessionConfigId = z.string(); * * Category names beginning with `_` are free for custom use, like other ACP extension methods. * Category names that do not begin with `_` are reserved for the ACP spec. - * - * @experimental */ export const zSessionConfigOptionCategory = z.union([ z.literal("mode"), @@ -631,24 +627,12 @@ export const zSessionConfigOptionCategory = z.union([ ]); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for a session configuration option value. - * - * @experimental */ export const zSessionConfigValueId = z.string(); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * A possible value for a session configuration option. - * - * @experimental */ export const zSessionConfigSelectOption = z.object({ _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), @@ -658,13 +642,7 @@ export const zSessionConfigSelectOption = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * A group of possible values for a session configuration option. - * - * @experimental */ export const zSessionConfigSelectGroup = z.object({ _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), @@ -674,13 +652,7 @@ export const zSessionConfigSelectGroup = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Possible values for a session configuration option. - * - * @experimental */ export const zSessionConfigSelectOptions = z.union([ z.array(zSessionConfigSelectOption), @@ -688,13 +660,7 @@ export const zSessionConfigSelectOptions = z.union([ ]); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * A single-value selector (dropdown) session configuration option payload. - * - * @experimental */ export const zSessionConfigSelect = z.object({ currentValue: zSessionConfigValueId, @@ -718,13 +684,7 @@ export const zSessionConfigOption = zSessionConfigSelect ); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Session configuration options have been updated. - * - * @experimental */ export const zConfigOptionUpdate = z.object({ _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), @@ -1136,13 +1096,7 @@ export const zInitializeResponse = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request parameters for setting a session configuration option. - * - * @experimental */ export const zSetSessionConfigOptionRequest = z.object({ _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), @@ -1152,13 +1106,7 @@ export const zSetSessionConfigOptionRequest = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response to `session/set_config_option` method. - * - * @experimental */ export const zSetSessionConfigOptionResponse = z.object({ _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), @@ -1222,40 +1170,6 @@ export const zStopReason = z.union([ z.literal("cancelled"), ]); -/** - * Response from processing a user prompt. - * - * See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion) - */ -export const zPromptResponse = z.object({ - _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), - stopReason: zStopReason, -}); - -export const zAgentResponse = z.union([ - z.object({ - id: zRequestId, - result: z.union([ - zInitializeResponse, - zAuthenticateResponse, - zNewSessionResponse, - zLoadSessionResponse, - zListSessionsResponse, - zForkSessionResponse, - zResumeSessionResponse, - zSetSessionModeResponse, - zSetSessionConfigOptionResponse, - zPromptResponse, - zSetSessionModelResponse, - zExtResponse, - ]), - }), - z.object({ - error: zError, - id: zRequestId, - }), -]); - /** * Embed a terminal created with `terminal/create` by its id. * @@ -1610,6 +1524,115 @@ export const zAvailableCommandsUpdate = z.object({ availableCommands: z.array(zAvailableCommand), }); +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Token usage information for a prompt turn. + * + * @experimental + */ +export const zUsage = z.object({ + cachedReadTokens: z + .union([ + z.coerce.bigint().gte(BigInt(0)).max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), + z.null(), + ]) + .optional(), + cachedWriteTokens: z + .union([ + z.coerce.bigint().gte(BigInt(0)).max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), + z.null(), + ]) + .optional(), + inputTokens: z.coerce + .bigint() + .gte(BigInt(0)) + .max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), + outputTokens: z.coerce + .bigint() + .gte(BigInt(0)) + .max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), + thoughtTokens: z + .union([ + z.coerce.bigint().gte(BigInt(0)).max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), + z.null(), + ]) + .optional(), + totalTokens: z.coerce + .bigint() + .gte(BigInt(0)) + .max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), +}); + +/** + * Response from processing a user prompt. + * + * See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion) + */ +export const zPromptResponse = z.object({ + _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), + stopReason: zStopReason, + usage: z.union([zUsage, z.null()]).optional(), +}); + +export const zAgentResponse = z.union([ + z.object({ + id: zRequestId, + result: z.union([ + zInitializeResponse, + zAuthenticateResponse, + zNewSessionResponse, + zLoadSessionResponse, + zListSessionsResponse, + zForkSessionResponse, + zResumeSessionResponse, + zSetSessionModeResponse, + zSetSessionConfigOptionResponse, + zPromptResponse, + zSetSessionModelResponse, + zExtResponse, + ]), + }), + z.object({ + error: zError, + id: zRequestId, + }), +]); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Context window and cost update for a session. + * + * @experimental + */ +export const zUsageUpdate = z.object({ + _meta: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(), + cost: z.union([zCost, z.null()]).optional(), + size: z.coerce.bigint().gte(BigInt(0)).max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), + used: z.coerce.bigint().gte(BigInt(0)).max(BigInt("18446744073709551615"), { + message: "Invalid value: Expected uint64 to be <= 18446744073709551615", + }), +}); + /** * Different types of updates that can be sent during session processing. * @@ -1668,6 +1691,11 @@ export const zSessionUpdate = z.union([ sessionUpdate: z.literal("session_info_update"), }), ), + zUsageUpdate.and( + z.object({ + sessionUpdate: z.literal("usage_update"), + }), + ), ]); /**