Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion MIGRATION_STABLE_UNSTABLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,9 @@ of APIs that require `/unstable` include:
- `systemPrompt` on `session/fork`. On `session/new`, `session/load` (v1), and
`session/resume` it is stable.
- Turn `usage` on v1 prompt responses and usage on v2 idle state updates.
- Subagent capabilities and session updates.
- `session/options`, and `configOptions` on `session/new`, `session/load`
(v1), and `session/resume`.
- Subagent capabilities and session updates, and `session` tool call content.
- Additional plan representations and `plan_removed` updates. V1's existing
stable `plan` update and v2's stable item-based `plan_update` remain available
from their stable-feature entrypoints. V1's ID-based `plan_update`, and v2's
Expand Down
1 change: 1 addition & 0 deletions schema/v1/meta.unstable.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
"session_archive": "session/archive",
"session_unarchive": "session/unarchive",
"session_status": "session/status",
"session_options": "session/options",
"session_set_title": "session/set_title",
"session_resume": "session/resume",
"session_close": "session/close",
Expand Down
239 changes: 237 additions & 2 deletions schema/v1/schema.unstable.json

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions schema/v2/meta.unstable.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"session_archive": "session/archive",
"session_unarchive": "session/unarchive",
"session_status": "session/status",
"session_options": "session/options",
"session_set_title": "session/set_title",
"session_resume": "session/resume",
"session_close": "session/close",
Expand Down
2 changes: 1 addition & 1 deletion schema/v2/schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -7699,7 +7699,7 @@
"type": "object",
"properties": {
"sessionId": {
"description": "The ID of the session to cancel operations for.",
"description": "The ID of the session whose foreground work to cancel.",
"allOf": [
{
"$ref": "#/$defs/SessionId"
Expand Down
287 changes: 284 additions & 3 deletions schema/v2/schema.unstable.json

Large diffs are not rendered by default.

11 changes: 8 additions & 3 deletions scripts/generate.js
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ import * as prettier from "prettier";
import ts from "typescript";
import { generateBindings } from "./generate-bindings.js";

const CURRENT_V1_SCHEMA_RELEASE = "schema-v1.30.0";
const CURRENT_V2_SCHEMA_RELEASE = "schema-v2.0.0-alpha.14";
const CURRENT_V1_SCHEMA_RELEASE = "schema-v1.31.0";
const CURRENT_V2_SCHEMA_RELEASE = "schema-v2.0.0-alpha.15";
const CHECK_GENERATED = process.argv.includes("--check");

// ── Extensible-union pipeline ────────────────────────────────────────────────
Expand Down Expand Up @@ -87,6 +87,11 @@ const V2_EXTENSIBLE_UNIONS = [
"ToolCallContent",
];

const V2_UNSTABLE_EXTENSIBLE_UNIONS = [
...V2_EXTENSIBLE_UNIONS,
"InitialSessionConfigOption",
];

const SCHEMA_CONFIGS = [
{
name: "v1",
Expand Down Expand Up @@ -139,7 +144,7 @@ const SCHEMA_CONFIGS = [
stagingDir: "./src/v2/.schema-unstable-staging",
previousDir: "./src/v2/.schema-unstable-previous",
schemaDeserializeImport: "../../../core/schema-deserialize.js",
expectedExtensibleUnions: V2_EXTENSIBLE_UNIONS,
expectedExtensibleUnions: V2_UNSTABLE_EXTENSIBLE_UNIONS,
brandUnknownVariants: true,
openApiVersion: "2.0.0",
releaseTag: CURRENT_V2_SCHEMA_RELEASE,
Expand Down
1 change: 1 addition & 0 deletions src/typedoc.v2.unstable.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"v2/unstable/schema/types.gen.ts:DiffChange",
"v2/unstable/schema/types.gen.ts:ElicitationPropertySchema",
"v2/unstable/schema/types.gen.ts:IdleStateUpdate",
"v2/unstable/schema/types.gen.ts:InitialSessionConfigOption",
"v2/unstable/schema/types.gen.ts:McpServer",
"v2/unstable/schema/types.gen.ts:MultiSelectItems",
"v2/unstable/schema/types.gen.ts:PlanUpdateContent",
Expand Down
136 changes: 136 additions & 0 deletions src/v1/acp.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4658,6 +4658,7 @@ describe("Connection", () => {
[AGENT_METHODS.session_archive, { sessionId: "s1" }],
[AGENT_METHODS.session_unarchive, { sessionId: "s1" }],
[AGENT_METHODS.session_status, { sessionId: "s1" }],
[AGENT_METHODS.session_options, { cwd: "/work" }],
[AGENT_METHODS.session_set_title, { sessionId: "s1", title: "t" }],
[AGENT_METHODS.auth_status, {}],
] as const) {
Expand All @@ -4667,6 +4668,141 @@ describe("Connection", () => {
}
});

it("round-trips unstable session/options and initial config option values", async () => {
const received: Array<{ method: string; params: unknown }> = [];
const configOptions = [
{
type: "boolean" as const,
id: "fast",
name: "Fast",
currentValue: false,
},
];
createAgent()
.onRequest(AGENT_METHODS.session_options, ({ method, params }) => {
received.push({ method, params });
return { configOptions };
})
.onRequest(AGENT_METHODS.session_new, ({ method, params }) => {
received.push({ method, params });
return { sessionId: "s1", configOptions };
})
.connect(ndJsonStream(agentToClient.writable, clientToAgent.readable));
const agent = createClient().connect(
ndJsonStream(clientToAgent.writable, agentToClient.readable),
).agent;

expect(
await agent.request(AGENT_METHODS.session_options, {
cwd: "/work",
sessionId: "s0",
}),
).toEqual({ configOptions });
await agent.request(AGENT_METHODS.session_new, {
cwd: "/work",
mcpServers: [],
configOptions: [
{ configId: "model", value: "model-2" },
{ configId: "fast", type: "boolean", value: true },
],
});
// A malformed entry fails the request instead of being dropped.
await expect(
agent.request(AGENT_METHODS.session_new, {
cwd: "/work",
mcpServers: [],
configOptions: [{ type: "boolean", value: true }],
} as never),
).rejects.toMatchObject({ code: -32602 });
await expect(
agent.request(AGENT_METHODS.session_options, {} as never),
).rejects.toMatchObject({ code: -32602 });

expect(received).toEqual([
{
method: "session/options",
params: { cwd: "/work", sessionId: "s0" },
},
{
method: "session/new",
params: {
cwd: "/work",
mcpServers: [],
configOptions: [
{ configId: "model", value: "model-2" },
{ configId: "fast", type: "boolean", value: true },
],
},
},
]);
expect(methods.agent.session.options).toBe("session/options");
});

it("validates unstable session options, session references and account descriptions", () => {
// Malformed values mean nothing is advertised.
expect(
unstableZod.zSessionOptionsResponse.parse({
modes: 3,
configOptions: [{ malformed: true }],
}),
).toEqual({ configOptions: [] });
expect(
unstableZod.zSessionCapabilities.parse({ options: {} }),
).toMatchObject({ options: {} });
expect(
unstableZod.zSessionCapabilities.parse({ options: 3 }).options,
).toBeUndefined();
// `null` means an empty list on every setup request.
for (const validator of [
unstableZod.zNewSessionRequest,
unstableZod.zLoadSessionRequest,
unstableZod.zResumeSessionRequest,
]) {
expect(
validator.parse({
sessionId: "s1",
cwd: "/work",
mcpServers: [],
configOptions: null,
}),
).toMatchObject({ configOptions: [] });
}
// The stable validators do not know the field.
expect(
stableZod.zNewSessionRequest.parse({
cwd: "/work",
mcpServers: [],
configOptions: [{ malformed: true }],
}),
).not.toHaveProperty("configOptions");

expect(
unstableZod.zToolCallContent.parse({
type: "session",
sessionId: "child-1",
}),
).toEqual({ type: "session", sessionId: "child-1" });
expect(() =>
unstableZod.zToolCallContent.parse({ type: "session" }),
).toThrow();

expect(
unstableZod.zAuthStatusResponse.parse({
state: "authenticated",
accounts: [
{ label: "Key", description: "API key helper" },
{ label: "Vertex", description: 42 },
],
}),
).toEqual({
state: "authenticated",
accounts: [
{ label: "Key", description: "API key helper" },
{ label: "Vertex" },
],
});
});

it("handles NES notifications", async () => {
const notificationLog: unknown[] = [];

Expand Down
17 changes: 17 additions & 0 deletions src/v1/acp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,7 @@ export const methods = {
archive: schema.AGENT_METHODS.session_archive,
unarchive: schema.AGENT_METHODS.session_unarchive,
status: schema.AGENT_METHODS.session_status,
options: schema.AGENT_METHODS.session_options,
setTitle: schema.AGENT_METHODS.session_set_title,
resume: schema.AGENT_METHODS.session_resume,
close: schema.AGENT_METHODS.session_close,
Expand Down Expand Up @@ -1267,6 +1268,10 @@ const agentRequestSpecs = {
schema.SessionStatusRequest,
schema.SessionStatusResponse
>(schema.AGENT_METHODS.session_status, validate.zSessionStatusRequest),
unstable_sessionOptions: requestSpec<
schema.SessionOptionsRequest,
schema.SessionOptionsResponse
>(schema.AGENT_METHODS.session_options, validate.zSessionOptionsRequest),
unstable_setSessionTitle: requestSpec<
schema.SetSessionTitleRequest,
schema.SetSessionTitleResponse
Expand Down Expand Up @@ -1505,6 +1510,18 @@ export type AgentRequestHandlersByMethod = {
schema.SessionStatusRequest,
schema.SessionStatusResponse
>;
/**
* Handles `session/options`. Respond with the modes and config options a
* session would start with. With `sessionId`, respond with what
* `session/load` or `session/resume` would return for that session. It
* must not create, load, resume, or change a session, send
* `session/update` notifications, or add an entry to `session/list`. An
* unknown session gets `-32002`.
*/
[schema.AGENT_METHODS.session_options]: AgentRequestHandler<
schema.SessionOptionsRequest,
schema.SessionOptionsResponse
>;
/**
* Handles `session/set_title`. Respond with the stored title after storing
* it. A title that is invalid after normalization gets `-32602`, and an
Expand Down
6 changes: 6 additions & 0 deletions src/v1/unstable/schema/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ export type {
InitializeProxyResponse,
InitializeRequest,
InitializeResponse,
InitialSessionConfigOption,
IntegerPropertySchema,
KillTerminalRequest,
KillTerminalResponse,
Expand Down Expand Up @@ -200,6 +201,10 @@ export type {
SessionModeId,
SessionModeState,
SessionNotification,
SessionOptionsCapabilities,
SessionOptionsRequest,
SessionOptionsResponse,
SessionReference,
SessionResumeCapabilities,
SessionStatus,
SessionStatusCapabilities,
Expand Down Expand Up @@ -274,6 +279,7 @@ export const AGENT_METHODS = {
session_archive: "session/archive",
session_unarchive: "session/unarchive",
session_status: "session/status",
session_options: "session/options",
session_set_title: "session/set_title",
session_resume: "session/resume",
session_close: "session/close",
Expand Down
Loading
Loading