Files
paseo/packages/plugin/src/server/acp.test.ts
T
Mohamed Boudra 76ff0f45da fix(agents): keep ACP background updates independent of foreground replies
Settle only tool calls owned by a failed prompt. Keep output from already running background tools from extending the autonomous reply timer.
2026-11-20 11:49:39 +01:00

3513 lines
125 KiB
TypeScript

import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { setImmediate as nextTurn } from "node:timers/promises";
import {
AgentSideConnection,
PROTOCOL_VERSION,
type Agent,
type SessionUpdate,
} from "@agentclientprotocol/sdk";
import type { ProviderConnection, ProviderEvent, ProviderInput } from "./provider.js";
import { afterEach, describe, expect, it } from "vitest";
import { AgentTimelineItemPayloadSchema } from "@getpaseo/protocol/messages";
import { runAcpProvider, type AcpStreamMessage } from "./acp.js";
const temporaryDirectories: string[] = [];
afterEach(async () => {
await Promise.all(
temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true })),
);
});
async function fakeAcp(source: string): Promise<string> {
const directory = await mkdtemp(path.join(tmpdir(), "paseo-acp-test-"));
temporaryDirectories.push(directory);
const executable = path.join(directory, "agent.cjs");
await writeFile(executable, source, "utf8");
return executable;
}
async function connect(
executable: string,
capabilities: string[],
transformers?: Parameters<typeof runAcpProvider>[0]["transformers"],
): Promise<{ connection: ProviderConnection; events: ProviderEvent[] }> {
const registration = runAcpProvider({
id: "test-acp",
label: "Test ACP",
command: [process.execPath, executable],
transformers,
});
const connection = await registration.connect({ versions: [1], capabilities });
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
return { connection, events };
}
function openInput(
settings: Record<string, string> = {},
): Extract<ProviderInput, { type: "session.open" }> {
return {
type: "session.open",
requestId: "open-1",
sessionId: "session-1",
config: { cwd: process.cwd(), env: {}, mcpServers: {}, settings, persist: true },
history: "skip",
};
}
async function waitForEvent(
events: ProviderEvent[],
predicate: (event: ProviderEvent) => boolean,
timeout = 3_000,
): Promise<ProviderEvent> {
await expect.poll(() => events.find(predicate), { timeout }).toBeTruthy();
return events.find(predicate)!;
}
type AcpRequestMessage = Extract<AcpStreamMessage, { id: string | number | null; method: string }>;
interface ConnectorInstance {
readonly requests: AcpRequestMessage[];
readsCanceled: boolean;
writesClosed: boolean;
closeFromAgent(): void;
request(method: string, params: unknown): Promise<unknown>;
respond(request: AcpRequestMessage, result: unknown): void;
reject(request: AcpRequestMessage, message: string): void;
notify(method: string, params: unknown): void;
}
interface ConnectorResponse {
resolve(value: unknown): void;
reject(error: Error): void;
}
interface ConnectorHarnessOptions {
capabilities?: Record<string, unknown>;
configOptions?: unknown[];
/** Session updates the agent streams for a prompt (keyed by its text) before ending the turn. */
promptUpdates?(promptText: string): unknown[];
handleMessage?(instance: ConnectorInstance, message: AcpStreamMessage): boolean;
afterMessage?(instance: ConnectorInstance, message: AcpStreamMessage): Promise<void>;
handleRequest?(instance: ConnectorInstance, request: AcpRequestMessage): boolean;
}
function countRequests(instance: ConnectorInstance, method: string): number {
return instance.requests.filter((request) => request.method === method).length;
}
function receiveConnectorMessage(
instance: ConnectorInstance,
message: AcpStreamMessage,
options?: ConnectorHarnessOptions,
): void {
if (!("method" in message)) return;
if ("id" in message) instance.requests.push(message as AcpRequestMessage);
if (options?.handleMessage?.(instance, message)) return;
if (!("id" in message)) return;
const request = message as AcpRequestMessage;
if (options?.handleRequest?.(instance, request)) return;
respondToConnectorRequest(instance, request, options);
}
function respondToConnectorRequest(
instance: ConnectorInstance,
request: AcpRequestMessage,
options?: ConnectorHarnessOptions,
): void {
if (request.method === "initialize") {
instance.respond(request, {
protocolVersion: request.params
? (request.params as { protocolVersion: number }).protocolVersion
: PROTOCOL_VERSION,
agentCapabilities: options?.capabilities ?? {},
});
} else if (request.method === "session/new" || request.method === "session/load") {
instance.respond(request, {
sessionId: "connector-session",
modes: null,
configOptions: options?.configOptions ?? [],
});
} else if (request.method === "session/prompt") {
const { prompt } = request.params as { prompt: Array<{ type: string; text?: string }> };
const promptText = prompt.find((part) => part.type === "text")?.text ?? "";
for (const update of options?.promptUpdates?.(promptText) ?? []) {
instance.notify("session/update", { sessionId: "connector-session", update });
}
instance.respond(request, { stopReason: "end_turn" });
} else if (request.method === "session/close") {
instance.respond(request, {});
} else if (request.method === "session/set_config_option") {
const params = request.params as { configId: string; value: string | boolean };
instance.respond(request, {
configOptions: (options?.configOptions ?? []).map((option) =>
(option as { id?: string }).id === params.configId
? Object.assign({}, option, { currentValue: params.value })
: option,
),
});
}
}
function connectorHarness(options?: ConnectorHarnessOptions) {
const instances: ConnectorInstance[] = [];
const connector = () => {
let controller!: ReadableStreamDefaultController<AcpStreamMessage>;
let requestSequence = 0;
const responses = new Map<number, ConnectorResponse>();
const instance: ConnectorInstance = {
requests: [],
readsCanceled: false,
writesClosed: false,
closeFromAgent: () => controller.close(),
request: (method, params) => {
const response = new Promise<unknown>((resolve, reject) => {
requestSequence += 1;
responses.set(requestSequence, { resolve, reject });
controller.enqueue({ jsonrpc: "2.0", id: requestSequence, method, params });
});
void response.catch(() => undefined);
return response;
},
respond: (request, result) => controller.enqueue({ jsonrpc: "2.0", id: request.id, result }),
reject: (request, message) =>
controller.enqueue({ jsonrpc: "2.0", id: request.id, error: { code: -32603, message } }),
notify: (method, params) => controller.enqueue({ jsonrpc: "2.0", method, params }),
};
instances.push(instance);
const readable = new ReadableStream<AcpStreamMessage>({
start(value) {
controller = value;
},
cancel() {
instance.readsCanceled = true;
},
});
const writable = new WritableStream<AcpStreamMessage>({
write(message) {
if (!("method" in message)) {
if (typeof message.id !== "number") return;
const response = responses.get(message.id);
if (!response) return;
responses.delete(message.id);
if ("error" in message) {
response.reject(
new Error(
message.error.data === undefined
? message.error.message
: `${message.error.message}: ${JSON.stringify(message.error.data)}`,
),
);
} else response.resolve(message.result);
return;
}
receiveConnectorMessage(instance, message, options);
return options?.afterMessage?.(instance, message);
},
close() {
instance.writesClosed = true;
},
abort() {
instance.writesClosed = true;
},
});
return { readable, writable };
};
return { connector, instances };
}
const basicAgent = `const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") setTimeout(() => send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", modes: null, configOptions: [] } }), 150);
else if (message.method === "session/prompt") send({ jsonrpc: "2.0", id: message.id, result: { stopReason: "end_turn" } });
});`;
describe("runAcpProvider", () => {
it.each([
["replay", false],
["skip", false],
["replay", true],
["skip", true],
] as const)(
"handles trailing load updates with %s history and out-of-turn activity %s",
async (history, outOfTurnActivity) => {
const sessionId = "connector-session";
const notifyUpdate = (runtime: ConnectorInstance, update: unknown) =>
runtime.notify("session/update", { sessionId, update });
const { connector, instances } = connectorHarness({
capabilities: { loadSession: true },
handleRequest(runtime, request) {
if (request.method !== "session/load") return false;
notifyUpdate(runtime, {
sessionUpdate: "available_commands_update",
availableCommands: [{ name: "help", description: "Help" }],
});
runtime.respond(request, { configOptions: [] });
setTimeout(() => {
notifyUpdate(runtime, {
sessionUpdate: "user_message_chunk",
content: { type: "text", text: "previous question" },
});
notifyUpdate(runtime, {
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "previous answer" },
});
}, 100);
return true;
},
});
const connection = await runAcpProvider({
id: "load",
label: "Load",
connector,
acpOptions: {
waitForInitialCommands: true,
initialCommandsTimeoutMs: 10_000,
loadReplayQuietPeriodMs: 200,
outOfTurnActivity,
},
}).connect({ versions: [1], capabilities: ["prompt.message", "session.persistence"] });
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send({
...openInput(),
history,
persistence: { version: 1, data: { sessionId } },
});
await waitForEvent(events, (event) => event.type === "session.ready");
const postReadyText = "Update after readiness";
notifyUpdate(instances[1], {
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: postReadyText },
});
notifyUpdate(instances[1], {
sessionUpdate: "available_commands_update",
availableCommands: [{ name: "different", description: "Different" }],
});
await waitForEvent(
events,
(event) => event.type === "session.commands" && event.commands[0]?.name === "different",
);
const items = events
.filter((event) => event.type === "timeline.item")
.map((event) => event.item);
const replayedItems =
history === "replay"
? [
expect.objectContaining({ type: "user_message", text: "previous question" }),
expect.objectContaining({ type: "assistant_message", text: "previous answer" }),
]
: [];
expect(items).toEqual([
...replayedItems,
...(outOfTurnActivity
? [expect.objectContaining({ type: "assistant_message", text: postReadyText })]
: []),
]);
expect(events.filter((event) => event.type === "session.turn")).toEqual(
outOfTurnActivity
? [
{
type: "session.turn",
sessionId: "session-1",
turnId: "acp:autonomous:1",
state: "started",
acceptsFollowUp: true,
},
]
: [],
);
} finally {
await connection.close();
}
},
);
it("auto-accepts ordinary permissions only in the unattended mode and refuses to switch while busy", async () => {
const modeConfig = {
id: "mode",
name: "Mode",
category: "mode",
type: "select",
currentValue: "default",
options: [
{ value: "default", name: "Default" },
{ value: "plan", name: "Plan" },
],
};
const approval = {
sessionId: "connector-session",
toolCall: { toolCallId: "tool", title: "Write a file", rawInput: {} },
options: [
{ optionId: "always", name: "Always allow", kind: "allow_always" },
{ optionId: "once", name: "Allow once", kind: "allow_once" },
{ optionId: "deny", name: "Deny", kind: "reject_once" },
],
};
let finishPrompt: (() => void) | undefined;
let stopping = false;
const outcomes: unknown[] = [];
const { connector } = connectorHarness({
configOptions: [modeConfig],
handleMessage(_runtime, message) {
if (!("method" in message) || message.method !== "session/cancel") return false;
stopping = true;
return true;
},
handleRequest(runtime, request) {
if (request.method !== "session/prompt") return false;
void runtime.request("session/request_permission", approval).then((outcome) => {
outcomes.push(outcome);
if (stopping) {
stopping = false;
runtime.respond(request, { stopReason: "cancelled" });
} else {
finishPrompt = () => runtime.respond(request, { stopReason: "end_turn" });
}
return undefined;
});
return true;
},
});
const connection = await runAcpProvider({
id: "unattended",
label: "Unattended",
connector,
acpOptions: {
autoAcceptMode: {
mode: { id: "full-access", label: "Full access" },
nativeMode: "default",
default: true,
},
},
}).connect({
versions: [1],
capabilities: ["prompt.message", "session.configure", "permission"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
const configure = async (requestId: string, mode: string) => {
await connection.send({
type: "session.configure",
requestId,
sessionId: "session-1",
changes: { mode },
});
return waitForEvent(events, (event) => "requestId" in event && event.requestId === requestId);
};
const prompt = (id: string) =>
connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: id,
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: id }] },
},
});
try {
await connection.send({ type: "catalog", requestId: "catalog" });
expect(await waitForEvent(events, (event) => event.type === "catalog")).toMatchObject({
catalog: {
defaultMode: "full-access",
modes: expect.arrayContaining([
{ id: "full-access", label: "Full access", isUnattended: true },
]),
},
});
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await prompt("unattended");
await expect
.poll(() => outcomes[0])
.toEqual({ outcome: { outcome: "selected", optionId: "once" } });
expect(events.some((event) => event.type === "session.permission")).toBe(false);
expect(await configure("busy", "plan")).toMatchObject({ type: "request.failed" });
finishPrompt!();
await waitForEvent(
events,
(event) => event.type === "session.turn" && event.state === "completed",
);
expect(await configure("leave", "default")).toMatchObject({ type: "request.completed" });
await prompt("interactive");
await waitForEvent(events, (event) => event.type === "session.permission");
expect(await configure("pending", "full-access")).toMatchObject({ type: "request.failed" });
expect(outcomes).toHaveLength(1);
await connection.send({
type: "session.interrupt",
requestId: "stop",
sessionId: "session-1",
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:interactive" &&
event.state === "canceled",
);
await expect.poll(() => outcomes[1]).toEqual({ outcome: { outcome: "cancelled" } });
await connection.send({
type: "session.permission",
sessionId: "session-1",
permissionId: "permission:tool",
response: { behavior: "allow" },
});
expect(await configure("enter", "full-access")).toMatchObject({ type: "request.completed" });
expect(events.some((event) => event.type === "session.runtime_failed")).toBe(false);
expect(
events.filter((event) => event.type === "session.config").map((event) => event.config.mode),
).toEqual(["full-access", "default", "full-access"]);
} finally {
await connection.close();
}
});
it("accepts a prompt as soon as the session reports ready", async () => {
const { connector } = connectorHarness();
const connection = await runAcpProvider({
id: "ready-acp",
label: "Ready ACP",
connector,
}).connect({ versions: [1], capabilities: ["prompt.message"] });
try {
const prompted = Promise.withResolvers<void>();
connection.onEvent((event) => {
if (event.type !== "session.ready") return;
void connection
.send({
type: "session.prompt",
sessionId: event.sessionId!,
prompt: {
clientMessageId: "first",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Hi" }] },
},
})
.then(prompted.resolve, prompted.reject);
});
await connection.send(openInput());
await prompted.promise;
} finally {
await connection.close();
}
});
it("uses config options for mode selection when the agent exposes no legacy modes", async () => {
const { connector } = connectorHarness({
configOptions: [
{
id: "permissions",
category: "mode",
name: "Permissions",
type: "select",
currentValue: "default",
options: [
{ value: "default", name: "Default" },
{ value: "edit", name: "Accept edits" },
],
},
],
});
const connection = await runAcpProvider({ id: "modes", label: "Modes", connector }).connect({
versions: [1],
capabilities: ["session.configure"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
const input = openInput();
input.config.mode = "edit";
await connection.send(input);
expect(
await waitForEvent(
events,
(event) => event.type === "session.config" || event.type === "request.failed",
),
).toMatchObject({
type: "session.config",
config: { mode: "edit", modes: [{ id: "default" }, { id: "edit" }], settings: [] },
});
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.configure",
requestId: "default",
sessionId: input.sessionId,
changes: { mode: "default" },
});
expect(
await waitForEvent(
events,
(event) => event.type === "session.config" && event.config.mode === "default",
),
).toBeDefined();
} finally {
await connection.close();
}
});
it("spawns the daemon-resolved launch for probes, catalogues, listing, and sessions", async () => {
const executable = await fakeAcp(`
if (process.env.LAUNCH_TOKEN !== "resolved" || process.env.CLAUDECODE || process.env.PASEO_NODE_ENV) process.exit(1);
const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
lines.on("line", (line) => {
const message = JSON.parse(line);
let result;
if (message.method === "initialize") result = { protocolVersion: message.params.protocolVersion, agentCapabilities: { sessionCapabilities: { list: {} } } };
else if (message.method === "session/new") result = { sessionId: "native", configOptions: [{ id: "model", name: "Model", category: "model", type: "select", currentValue: "resolved", options: [{ value: "resolved", name: require("node:fs").realpathSync(message.params.cwd) === process.cwd() ? (process.env.SESSION_TOKEN || "probe") : "wrong cwd" }] }] };
else if (message.method === "session/list") result = { sessions: [] };
else return;
send({ jsonrpc: "2.0", id: message.id, result });
});`);
const registration = runAcpProvider({
id: "launch-acp",
label: "Launch ACP",
command: ["missing-default-command"],
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.list"],
launch: { command: process.execPath, args: [executable], env: { LAUNCH_TOKEN: "resolved" } },
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send({
type: "catalog",
requestId: "catalog",
cwd: path.dirname(executable),
});
expect(await waitForEvent(events, (event) => event.type === "catalog")).toMatchObject({
catalog: { models: [{ id: "resolved", label: "probe" }] },
});
await connection.send({ type: "sessions", requestId: "list" });
expect(await waitForEvent(events, (event) => event.type === "sessions")).toMatchObject({
sessions: [],
});
const input = openInput();
input.config.env = { SESSION_TOKEN: "session" };
input.config.cwd = path.dirname(executable);
await connection.send(input);
expect(await waitForEvent(events, (event) => event.type === "session.config")).toMatchObject({
config: { models: [{ id: "resolved", label: "session" }] },
});
} finally {
await connection.close();
}
});
it("still reports initialization failures for workspace-only global discovery", async () => {
let unavailable = false;
const { connector } = connectorHarness({
handleRequest(instance, request) {
if (unavailable && request.method === "initialize") {
instance.reject(request, "Bridge unavailable");
return true;
}
return false;
},
});
const registration = runAcpProvider({
id: "workspace-acp",
label: "Workspace ACP",
connector,
acpOptions: { workspaceOnlyCatalog: true },
});
const connection = await registration.connect({ versions: [1], capabilities: [] });
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
unavailable = true;
await connection.send({ type: "catalog", requestId: "global" });
expect(await waitForEvent(events, (event) => event.type === "request.failed")).toMatchObject({
requestId: "global",
error: { message: expect.stringContaining("Bridge unavailable") },
});
expect(events.some((event) => event.type === "catalog")).toBe(false);
} finally {
await connection.close();
}
});
it("rejects connection cleanly when the ACP executable does not exist", async () => {
const registration = runAcpProvider({
id: "missing-acp",
label: "Missing ACP",
command: [path.join(tmpdir(), `missing-acp-${process.pid}`)],
acpOptions: { startupTimeoutMs: 250 },
});
await expect(
registration.connect({ versions: [1], capabilities: ["prompt.message"] }),
).rejects.toThrow(/ENOENT|spawn/u);
});
it("accepts an official ACP SDK stream connector instead of a command", async () => {
const connector = () => {
const clientToAgent = new TransformStream();
const agentToClient = new TransformStream();
const agent: Agent = {
initialize: async () => ({ protocolVersion: PROTOCOL_VERSION, agentCapabilities: {} }),
newSession: async () => ({ sessionId: "sdk-session", modes: null, configOptions: [] }),
prompt: async () => ({ stopReason: "end_turn" }),
cancel: async () => undefined,
};
const agentConnection = new AgentSideConnection(() => agent, {
writable: agentToClient.writable,
readable: clientToAgent.readable,
});
void agentConnection;
return {
writable: clientToAgent.writable,
readable: agentToClient.readable,
};
};
const registration = runAcpProvider({
id: "sdk-acp",
label: "SDK ACP",
connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
expect(connection.capabilities).toEqual(["prompt.message"]);
await connection.close();
});
it("maps permission behavior to the first matching ACP option", async () => {
const harness = connectorHarness();
const registration = runAcpProvider({
id: "sdk-acp",
label: "SDK ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "permission"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
const allow = harness.instances[1]!.request("session/request_permission", {
sessionId: "connector-session",
toolCall: {
toolCallId: "tool-allow",
title: "Allow tool",
kind: "execute",
status: "pending",
content: [],
rawInput: {},
},
options: [
{ optionId: "allow-always", name: "Always allow", kind: "allow_always" },
{ optionId: "allow-once", name: "Allow once", kind: "allow_once" },
{ optionId: "reject-once", name: "Reject", kind: "reject_once" },
],
});
await waitForEvent(
events,
(event) =>
event.type === "session.permission" && event.request.id === "permission:tool-allow",
);
await connection.send({
type: "session.permission",
sessionId: "session-1",
permissionId: "permission:tool-allow",
response: { behavior: "allow" },
});
await expect(allow).resolves.toEqual({
outcome: { outcome: "selected", optionId: "allow-always" },
});
const deny = harness.instances[1]!.request("session/request_permission", {
sessionId: "connector-session",
toolCall: {
toolCallId: "tool-deny",
title: "Deny tool",
kind: "execute",
status: "pending",
content: [],
rawInput: {},
},
options: [
{ optionId: "allow-once", name: "Allow", kind: "allow_once" },
{ optionId: "reject-always", name: "Always reject", kind: "reject_always" },
{ optionId: "reject-once", name: "Reject once", kind: "reject_once" },
],
});
await waitForEvent(
events,
(event) => event.type === "session.permission" && event.request.id === "permission:tool-deny",
);
await connection.send({
type: "session.permission",
sessionId: "session-1",
permissionId: "permission:tool-deny",
response: { behavior: "deny" },
});
await expect(deny).resolves.toEqual({
outcome: { outcome: "selected", optionId: "reject-always" },
});
await connection.close();
});
it("rejects an explicit ACP permission option with the wrong behavior", async () => {
const harness = connectorHarness();
const registration = runAcpProvider({
id: "sdk-acp",
label: "SDK ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "permission"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
const permission = harness.instances[1]!.request("session/request_permission", {
sessionId: "connector-session",
toolCall: {
toolCallId: "tool-explicit",
title: "Explicit tool",
kind: "execute",
status: "pending",
content: [],
rawInput: {},
},
options: [
{ optionId: "allow-once", name: "Allow", kind: "allow_once" },
{ optionId: "reject-once", name: "Reject", kind: "reject_once" },
],
});
await waitForEvent(
events,
(event) =>
event.type === "session.permission" && event.request.id === "permission:tool-explicit",
);
await connection.send({
type: "session.permission",
sessionId: "session-1",
permissionId: "permission:tool-explicit",
response: { behavior: "allow", selectedActionId: "missing" },
});
await expect(
waitForEvent(
events,
(event) =>
event.type === "session.runtime_failed" && event.error.message.includes("'missing'"),
),
).resolves.toBeDefined();
await connection.send({
type: "session.permission",
sessionId: "session-1",
permissionId: "permission:tool-explicit",
response: { behavior: "allow", selectedActionId: "reject-once" },
});
await expect(
waitForEvent(
events,
(event) =>
event.type === "session.runtime_failed" &&
event.error.message.includes("'reject-once'") &&
event.error.message.includes("does not match 'allow' behavior"),
),
).resolves.toBeDefined();
await connection.send({
type: "session.permission",
sessionId: "session-1",
permissionId: "permission:tool-explicit",
response: { behavior: "allow", selectedActionId: "allow-once" },
});
await expect(permission).resolves.toEqual({
outcome: { outcome: "selected", optionId: "allow-once" },
});
await connection.close();
});
it("closes both connector directions for the probe and live session", async () => {
const harness = connectorHarness();
const registration = runAcpProvider({
id: "owned-acp",
label: "Owned ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
expect(harness.instances).toHaveLength(1);
expect(harness.instances[0]).toMatchObject({ readsCanceled: true, writesClosed: true });
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.close();
expect(harness.instances).toHaveLength(2);
expect(harness.instances[1]).toMatchObject({ readsCanceled: true, writesClosed: true });
});
it("publishes runtime failure on unexpected connector EOF", async () => {
const harness = connectorHarness();
const registration = runAcpProvider({
id: "eof-acp",
label: "EOF ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
harness.instances[1]!.closeFromAgent();
await expect(
waitForEvent(events, (event) => event.type === "session.runtime_failed"),
).resolves.toMatchObject({
sessionId: "session-1",
error: { message: expect.stringContaining("closed") },
});
await connection.close();
});
it("settles an active auto prompt before admitting its auto replacement", async () => {
const order: string[] = [];
let firstPrompt: AcpRequestMessage | null = null;
let activePrompts = 0;
let maximumActivePrompts = 0;
const harness = connectorHarness({
handleMessage(instance, message) {
if (!("method" in message)) return false;
const request = "id" in message ? (message as AcpRequestMessage) : null;
if (message.method === "session/prompt" && request) {
const promptNumber = firstPrompt ? "second" : "first";
order.push(`prompt:${promptNumber}`);
activePrompts += 1;
maximumActivePrompts = Math.max(maximumActivePrompts, activePrompts);
if (!firstPrompt) {
firstPrompt = request;
} else {
activePrompts -= 1;
instance.respond(request, { stopReason: "end_turn" });
}
return true;
}
if (message.method === "session/cancel") {
order.push("cancel");
activePrompts -= 1;
instance.respond(firstPrompt!, { stopReason: "cancelled" });
return true;
}
return false;
},
});
const registration = runAcpProvider({
id: "overlap-acp",
label: "Overlap ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "first",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "first" }] },
},
});
await expect.poll(() => countRequests(harness.instances[1]!, "session/prompt")).toBe(1);
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "second",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "second" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:second" &&
event.state === "completed",
);
expect(order).toEqual(["prompt:first", "cancel", "prompt:second"]);
expect(maximumActivePrompts).toBe(1);
const firstTerminal = events.findIndex(
(event) =>
event.type === "session.turn" && event.turnId === "acp:first" && event.state === "canceled",
);
const secondAdmission = events.findIndex(
(event) => event.type === "session.prompt_result" && event.clientMessageId === "second",
);
expect(firstTerminal).toBeGreaterThan(-1);
expect(firstTerminal).toBeLessThan(secondAdmission);
await connection.close();
});
it.each([
["end_turn", "completed", "completed"],
["cancelled", "canceled", "canceled"],
] as const)(
"closes a transformer's running tool row when the turn ends with %s",
async (stopReason, turnState, rowStatus) => {
const harness = connectorHarness({
handleMessage(instance, message) {
if (!("method" in message) || !("id" in message)) return false;
if (message.method !== "session/prompt") return false;
instance.notify("vendor/phase", { id: "phase-1", label: "Preparing" });
instance.respond(message as AcpRequestMessage, { stopReason });
return true;
},
});
const registration = runAcpProvider({
id: "vendor-row-acp",
label: "Vendor row ACP",
connector: harness.connector,
transformers: [
{
notification(notification) {
if (notification.method !== "vendor/phase") return null;
return {
type: "timeline",
item: {
type: "tool_call",
id: "phase-1",
callId: "phase-1",
name: "Vendor phase",
detail: { type: "plain_text", label: "Preparing" },
status: "running",
error: null,
},
};
},
},
],
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "first",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "first" }] },
},
});
await waitForEvent(
events,
(event) => event.type === "session.turn" && event.state === turnState,
);
const rows = events.flatMap((event) =>
event.type === "timeline.item" && event.item.id === "phase-1" ? [event.item] : [],
);
expect(rows.map((row) => row.type === "tool_call" && row.status)).toEqual([
"running",
rowStatus,
]);
const closed = events.findIndex(
(event) =>
event.type === "timeline.item" &&
event.item.id === "phase-1" &&
event.item.type === "tool_call" &&
event.item.status === rowStatus,
);
const terminal = events.findIndex(
(event) => event.type === "session.turn" && event.state === turnState,
);
expect(closed).toBeLessThan(terminal);
// The wire contract only accepts a failed tool call with a non-null error.
expect(rows.at(-1)).toMatchObject({ error: null });
await connection.close();
},
);
it("cancels an in-progress ACP tool call with the canceled turn instead of failing it without an error", async () => {
const harness = connectorHarness({
handleMessage(instance, message) {
if (!("method" in message) || !("id" in message)) return false;
if (message.method !== "session/prompt") return false;
instance.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call",
toolCallId: "tool-1",
title: "Run tests",
kind: "execute",
status: "in_progress",
},
});
instance.respond(message as AcpRequestMessage, { stopReason: "cancelled" });
return true;
},
});
const registration = runAcpProvider({
id: "cancel-tool-acp",
label: "Cancel tool ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "first",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "first" }] },
},
});
await waitForEvent(
events,
(event) => event.type === "session.turn" && event.state === "canceled",
);
const rows = events.flatMap((event) =>
event.type === "timeline.item" && event.item.id === "tool-1" ? [event.item] : [],
);
expect(rows.at(-1)).toMatchObject({ type: "tool_call", status: "canceled", error: null });
await connection.close();
});
it.each([
{ counts: null, context: false, expected: [] },
{
counts: { totalTokens: 0, inputTokens: 0, outputTokens: 0 },
context: false,
expected: [
{
turnId: "acp:first",
usage: { inputTokens: 0, outputTokens: 0, cachedInputTokens: undefined },
},
],
},
{
counts: { totalTokens: 18971, inputTokens: 12152, outputTokens: 78, cachedReadTokens: 6741 },
context: true,
expected: [
{
turnId: undefined,
usage: { contextWindowUsedTokens: 42, contextWindowMaxTokens: 100, totalCostUsd: 0.25 },
},
{
turnId: "acp:first",
usage: {
inputTokens: 12152,
outputTokens: 78,
cachedInputTokens: 6741,
contextWindowUsedTokens: 42,
contextWindowMaxTokens: 100,
totalCostUsd: 0.25,
},
},
],
},
])(
"forwards prompt-result usage $counts while preserving context updates: $context",
async ({ counts, context, expected }) => {
const harness = connectorHarness({
handleRequest(instance, message) {
if (message.method !== "session/prompt") return false;
if (context)
instance.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "usage_update",
used: 42,
size: 100,
cost: { amount: 0.25, currency: "USD" },
},
});
instance.respond(message, {
stopReason: "end_turn",
...(counts ? { usage: counts } : {}),
});
return true;
},
});
const registration = runAcpProvider({
id: "usage-acp",
label: "Usage ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "first",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "hello" }] },
},
});
await waitForEvent(
events,
(event) => event.type === "session.turn" && event.state === "completed",
);
const usage = events.flatMap((event) =>
event.type === "session.usage" ? [{ turnId: event.turnId, usage: event.usage }] : [],
);
expect(usage).toEqual(expected);
const lastUsage = events.findLastIndex((event) => event.type === "session.usage");
const completed = events.findIndex(
(event) => event.type === "session.turn" && event.state === "completed",
);
expect(lastUsage).toBeLessThan(completed);
} finally {
await connection.close();
}
},
);
it.each([
{ status: "failed", output: undefined, error: { message: "Tool failed" } },
{ status: "failed", output: null, error: { message: "Tool failed" } },
{
status: "failed",
output: { message: "File not found" },
error: { message: "File not found" },
},
{ status: "failed", output: "Permission denied", error: "Permission denied" },
{ status: "completed", output: null, error: null },
] as const)(
"keeps a $status ACP tool with output $output valid on the history wire",
async ({ status, output, error }) => {
const harness = connectorHarness({
promptUpdates: () => [
{
sessionUpdate: "tool_call",
toolCallId: "read-1",
title: "Read file",
kind: "read",
status: "in_progress",
},
{ sessionUpdate: "tool_call_update", toolCallId: "read-1", status, rawOutput: output },
],
});
const registration = runAcpProvider({
id: "tool-history-acp",
label: "Tool history ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "first",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Read a file" }] },
},
});
await waitForEvent(
events,
(event) => event.type === "session.turn" && event.state === "completed",
);
const rows = events.flatMap((event) =>
event.type === "timeline.item" && event.item.id === "read-1" ? [event.item] : [],
);
expect(rows).toHaveLength(2);
for (const row of rows) {
expect(AgentTimelineItemPayloadSchema.safeParse(row).success).toBe(true);
}
expect(rows.at(-1)).toMatchObject({ type: "tool_call", status, error });
} finally {
await connection.close();
}
},
);
it("serializes configuration mutations", async () => {
let releaseMutation: (() => void) | null = null;
const configOptions = [
{
id: "model",
name: "Model",
category: "model",
type: "select",
currentValue: "a",
options: [
{ name: "A", value: "a" },
{ name: "B", value: "b" },
],
},
];
const harness = connectorHarness({
capabilities: { loadSession: true },
configOptions,
handleRequest(instance, request) {
if (request.method !== "session/set_config_option") return false;
const value = (request.params as { value: string }).value;
if (value !== "first") return false;
releaseMutation = () =>
instance.respond(request, {
configOptions: configOptions.map((option) =>
Object.assign({}, option, { currentValue: value }),
),
});
return true;
},
});
const registration = runAcpProvider({
id: "lane-acp",
label: "Lane ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.configure"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.configure",
requestId: "configure-first",
sessionId: "session-1",
changes: { model: "first" },
});
await connection.send({
type: "session.configure",
requestId: "configure-second",
sessionId: "session-1",
changes: { model: "second" },
});
await expect
.poll(() => countRequests(harness.instances[1]!, "session/set_config_option"))
.toBe(1);
releaseMutation!();
await waitForEvent(
events,
(event) => event.type === "request.completed" && event.requestId === "configure-second",
);
expect(
events
.filter(
(event) => event.type === "request.completed" && event.requestId.startsWith("configure-"),
)
.map((event) => (event as Extract<ProviderEvent, { type: "request.completed" }>).requestId),
).toEqual(["configure-first", "configure-second"]);
await connection.close();
});
it("does not claim exact permission policy, listing, image, or configuration support", async () => {
const executable = await fakeAcp(basicAgent);
const { connection, events } = await connect(executable, [
"prompt.message",
"prompt.image",
"session.configure",
"session.list",
"permission.tool_policy",
]);
expect(connection.capabilities).toEqual(["prompt.message", "session.configure"]);
await connection.send(openInput());
const opened = await waitForEvent(events, (event) => event.type === "session.opened");
expect(opened).toMatchObject({ capabilities: ["prompt.message"] });
await waitForEvent(events, (event) => event.type === "session.ready");
await expect(
connection.send({
type: "session.configure",
requestId: "configure-unsupported",
sessionId: "session-1",
changes: { model: "not-advertised" },
}),
).rejects.toThrow("session.configure");
await connection.close();
});
it("derives optional connection capabilities from ACP initialization", async () => {
const executable = await fakeAcp(`const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: {
protocolVersion: message.params.protocolVersion,
agentCapabilities: {
loadSession: true,
promptCapabilities: { image: true },
sessionCapabilities: { list: {} },
},
} });
});`);
const { connection } = await connect(executable, [
"prompt.message",
"prompt.image",
"session.list",
"session.persistence",
]);
expect(connection.capabilities).toEqual([
"prompt.message",
"prompt.image",
"session.list",
"session.persistence",
]);
await connection.close();
});
it("acknowledges admission before session creation completes", async () => {
const executable = await fakeAcp(basicAgent);
const { connection, events } = await connect(executable, ["prompt.message"]);
let ready = false;
const admission = connection.send(openInput()).then(() => {
ready = true;
return undefined;
});
await admission;
expect(ready).toBe(true);
expect(events).toEqual([]);
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.close();
});
it("rejects provider inputs after the ACP connection closes", async () => {
const harness = connectorHarness();
const registration = runAcpProvider({
id: "closed-acp",
label: "Closed ACP",
connector: harness.connector,
});
const connection = await registration.connect({ versions: [1], capabilities: [] });
await connection.close();
await expect(connection.send({ type: "catalog", requestId: "too-late" })).rejects.toThrow(
"ACP provider connection is closed",
);
expect(harness.instances).toHaveLength(1);
});
it("waits for delayed session creation and closes its connector after connection close", async () => {
let delayedNew: AcpRequestMessage | null = null;
const harness = connectorHarness({
handleRequest(_instance, request) {
if (request.method !== "session/new") return false;
delayedNew = request;
return true;
},
});
const registration = runAcpProvider({
id: "delayed-open-acp",
label: "Delayed open ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await expect.poll(() => delayedNew).not.toBeNull();
let closeSettled = false;
const closing = connection.close().then(() => {
closeSettled = true;
return undefined;
});
await Promise.resolve();
expect(closeSettled).toBe(false);
harness.instances[1]!.respond(delayedNew!, {
sessionId: "late-session",
modes: null,
configOptions: [],
});
await closing;
expect(harness.instances[1]).toMatchObject({ readsCanceled: true, writesClosed: true });
expect(events).toEqual([]);
});
it("refuses unsupported steering before sending an ACP prompt", async () => {
const executable = await fakeAcp(basicAgent);
const { connection, events } = await connect(executable, ["prompt.message"]);
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await expect(
connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "steer-1",
delivery: "steer",
input: { type: "message", content: [{ type: "text", text: "change course" }] },
},
}),
).rejects.toThrow("prompt.steer");
expect(events.some((event) => event.type === "session.prompt_result")).toBe(false);
await connection.close();
});
it("keeps configuration observable state atomic when a later field fails", async () => {
const executable = await fakeAcp(`const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
let model = "a";
const options = () => [
{ id: "model", name: "Model", category: "model", type: "select", currentValue: model, options: [{ name: "A", value: "a" }, { name: "B", value: "b" }] },
{ id: "verbosity", name: "Verbosity", type: "select", currentValue: "quiet", options: [{ name: "Quiet", value: "quiet" }, { name: "Loud", value: "loud" }] },
];
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", modes: null, configOptions: options() } });
else if (message.method === "session/set_config_option" && message.params.configId === "verbosity") send({ jsonrpc: "2.0", id: message.id, error: { code: -32602, message: "verbosity rejected" } });
else if (message.method === "session/set_config_option") { model = message.params.value; send({ jsonrpc: "2.0", id: message.id, result: { configOptions: options() } }); }
});`);
const { connection, events } = await connect(executable, [
"prompt.message",
"session.configure",
]);
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.configure",
requestId: "configure-1",
sessionId: "session-1",
changes: { model: "b", settings: { verbosity: "loud" } },
});
await waitForEvent(
events,
(event) => event.type === "request.failed" && event.requestId === "configure-1",
);
const configs = events.filter((event) => event.type === "session.config");
expect(configs).toHaveLength(1);
expect(configs[0]).toMatchObject({ config: { model: "a" } });
await connection.close();
});
it.each([1, 64])(
"commits transformer config notifications once and discards them on rollback (%i per response)",
async (notificationCount) => {
const executable = await fakeAcp(`const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (...messages) => process.stdout.write(messages.map((message) => JSON.stringify(message) + "\\n").join(""));
let model = "a";
const options = () => [
{ id: "model", name: "Model", category: "model", type: "select", currentValue: model, options: [{ name: "A", value: "a" }, { name: "B", value: "b" }] },
{ id: "late", name: "Late", type: "select", currentValue: "ok", options: [{ name: "Ok", value: "ok" }, { name: "Fail", value: "fail" }] },
];
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", modes: null, configOptions: options() } });
else if (message.method === "session/set_config_option" && message.params.configId === "late") send({ jsonrpc: "2.0", id: message.id, error: { code: -32602, message: "late rejected" } });
else if (message.method === "session/set_config_option") {
model = message.params.value;
send(
...Array.from({ length: ${notificationCount} }, () => ({ jsonrpc: "2.0", method: "vendor/config", params: { model } })),
{ jsonrpc: "2.0", id: message.id, result: { configOptions: options() } },
);
}
});`);
const transformer = {
notification(notification: { method: string; params: unknown }) {
if (notification.method !== "vendor/config") return null;
const params = notification.params as { model: string };
return {
type: "config" as const,
config: {
model: params.model,
models: [{ id: params.model, label: `Transformer ${params.model}` }],
modes: [],
thinkingOptions: [],
settings: [],
},
};
},
};
const { connection, events } = await connect(
executable,
["prompt.message", "session.configure"],
[transformer],
);
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
const initialConfigCount = events.filter((event) => event.type === "session.config").length;
await connection.send({
type: "session.configure",
requestId: "transformer-initial-failure",
sessionId: "session-1",
changes: { model: "b", settings: { late: "fail" } },
});
await waitForEvent(
events,
(event) =>
event.type === "request.failed" && event.requestId === "transformer-initial-failure",
);
expect(events.filter((event) => event.type === "session.config")).toHaveLength(
initialConfigCount,
);
await connection.send({
type: "session.configure",
requestId: "transformer-success",
sessionId: "session-1",
changes: { model: "b" },
});
await waitForEvent(
events,
(event) => event.type === "request.completed" && event.requestId === "transformer-success",
);
let configs = events.filter((event) => event.type === "session.config");
expect(configs).toHaveLength(initialConfigCount + 1);
expect(configs.at(-1)).toMatchObject({
config: { model: "b", models: [{ label: "Transformer b" }] },
});
await connection.send({
type: "session.configure",
requestId: "transformer-failure",
sessionId: "session-1",
changes: { model: "a", settings: { late: "fail" } },
});
await waitForEvent(
events,
(event) => event.type === "request.failed" && event.requestId === "transformer-failure",
);
configs = events.filter((event) => event.type === "session.config");
expect(configs).toHaveLength(initialConfigCount + 1);
expect(configs.at(-1)).toMatchObject({ config: { model: "b" } });
await connection.close();
},
);
it("selects the model control when an agent files several controls under the model category", async () => {
const executable = await fakeAcp(`const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
let model = "small";
const modes = { currentModeId: "auto", availableModes: [{ id: "auto", name: "Auto" }, { id: "ask", name: "Ask" }] };
const options = () => [
{ id: "provider", name: "Provider", category: "model", type: "select", currentValue: "gateway", options: [{ name: "Gateway", value: "gateway" }, { name: "Local", value: "local" }] },
{ id: "model", name: "Model", category: "model", type: "select", currentValue: model, options: [{ name: "Small", value: "small" }, { name: "Large", value: "large" }] },
{ id: "mode", name: "Session Mode", category: "mode", type: "select", currentValue: "auto", options: [{ name: "Auto", value: "auto" }, { name: "Ask", value: "ask" }] },
{ id: "fast", name: "Fast Mode", category: "model", type: "select", currentValue: "false", options: [{ name: "Off", value: "false" }, { name: "On", value: "true" }] },
];
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", modes, configOptions: options() } });
else if (message.method === "session/set_config_option") {
if (message.params.configId === "model") model = message.params.value;
send({ jsonrpc: "2.0", id: message.id, result: { configOptions: options() } });
}
});`);
const { connection, events } = await connect(executable, [
"prompt.message",
"session.configure",
]);
await connection.send({ type: "catalog", requestId: "catalog-1" });
await waitForEvent(events, (event) => event.type === "catalog");
expect(events.find((event) => event.type === "catalog")).toMatchObject({
catalog: {
defaultModel: "small",
models: [
{ id: "small", label: "Small" },
{ id: "large", label: "Large" },
],
},
});
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.configure",
requestId: "configure-1",
sessionId: "session-1",
changes: { model: "large" },
});
await waitForEvent(
events,
(event) => event.type === "request.completed" && event.requestId === "configure-1",
);
const config = events.findLast((event) => event.type === "session.config");
expect(config).toMatchObject({ config: { model: "large" } });
if (config?.type !== "session.config") throw new Error("Expected session.config");
expect(config.config.settings?.map((setting) => setting.id)).toEqual(["provider", "fast"]);
await connection.close();
});
it("applies opening configuration in the order the agent lists its options", async () => {
const executable = await fakeAcp(`const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
let provider = "first";
let model = "first-saved";
const saved = { first: "first-saved", second: "second-saved" };
const select = (id, currentValue, values) => ({ id, name: id, category: "model", type: "select", currentValue, options: values.map((value) => ({ name: value, value })) });
const options = () => [
select("provider", provider, ["first", "second"]),
select("model", model, ["first-saved", "second-saved", "second-chosen"]),
];
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", configOptions: options() } });
else if (message.method === "session/set_config_option") {
if (message.params.configId === "provider") { provider = message.params.value; model = saved[provider]; }
if (message.params.configId === "model") model = message.params.value;
send({ jsonrpc: "2.0", id: message.id, result: { configOptions: options() } });
}
});`);
const { connection, events } = await connect(executable, [
"prompt.message",
"session.configure",
]);
const input = openInput({ provider: "second" });
await connection.send({ ...input, config: { ...input.config, model: "second-chosen" } });
await waitForEvent(events, (event) => event.type === "session.ready");
expect(events.findLast((event) => event.type === "session.config")).toMatchObject({
config: { model: "second-chosen" },
});
await connection.close();
});
it("gives discovery transformers the discovered session configuration facade", async () => {
const executable = await fakeAcp(`const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "catalog-native", modes: null, configOptions: [{ id: "flavor", name: "Flavor", type: "select", currentValue: "mint", options: [{ name: "Mint", value: "mint" }] }] } });
});`);
let discovered: Readonly<Record<string, unknown>> | null = null;
const { connection, events } = await connect(
executable,
[],
[
{
async discover(catalog, context) {
discovered = await context.config.read();
return catalog;
},
},
],
);
await connection.send({ type: "catalog", requestId: "catalog-1" });
await waitForEvent(events, (event) => event.type === "catalog");
expect(discovered).toEqual({ flavor: "mint" });
await connection.close();
});
it("drains heavy ACP stderr while initializing", async () => {
const executable = await fakeAcp(
`process.stderr.write("x".repeat(2 * 1024 * 1024));\n${basicAgent}`,
);
const { connection, events } = await connect(executable, ["prompt.message"]);
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.close();
});
it("publishes runtime failure when the ACP process dies", async () => {
const executable = await fakeAcp(`const readline = require("node:readline");
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") {
send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", modes: null, configOptions: [] } });
setTimeout(() => process.exit(17), 20);
}
});`);
const { connection, events } = await connect(executable, ["prompt.message"]);
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
const failure = await waitForEvent(events, (event) => event.type === "session.runtime_failed");
expect(failure).toMatchObject({
sessionId: "session-1",
error: { message: expect.stringContaining("17") },
});
await connection.close();
});
it("escalates shutdown when an ACP process ignores SIGTERM", async () => {
const executable = await fakeAcp(`const readline = require("node:readline");
process.on("SIGTERM", () => {});
const lines = readline.createInterface({ input: process.stdin });
const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
lines.on("line", (line) => {
const message = JSON.parse(line);
if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", modes: null, configOptions: [] } });
});`);
const { connection, events } = await connect(executable, ["prompt.message"]);
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
const startedAt = Date.now();
await connection.close();
expect(Date.now() - startedAt).toBeGreaterThanOrEqual(900);
expect(Date.now() - startedAt).toBeLessThan(2_500);
});
});
describe("runAcpProvider streamed chunks without messageId (#4699)", () => {
interface Chunk {
kind: "agent_message_chunk" | "agent_thought_chunk";
text: string;
messageId?: string;
}
it("continues one timeline item per turn instead of one per chunk", async () => {
const chunksByPrompt: Record<string, Chunk[]> = {
first: [
{ kind: "agent_message_chunk", text: "- **Current tem" },
{ kind: "agent_message_chunk", text: "perature**: 25°C" },
],
second: [{ kind: "agent_message_chunk", text: "next turn" }],
// An explicit-id text chunk between two id-less thoughts separates them.
third: [
{ kind: "agent_thought_chunk", text: "think A" },
{ kind: "agent_message_chunk", text: "say", messageId: "m-explicit" },
{ kind: "agent_thought_chunk", text: "think B" },
],
};
const harness = connectorHarness({
promptUpdates: (promptText) =>
(chunksByPrompt[promptText] ?? []).map((chunk) => {
const update: Record<string, unknown> = {
sessionUpdate: chunk.kind,
content: { type: "text", text: chunk.text },
};
if (chunk.messageId) update.messageId = chunk.messageId;
return update;
}),
});
const registration = runAcpProvider({
id: "chunk-acp",
label: "Chunk ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
for (const clientMessageId of ["first", "second", "third"]) {
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId,
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: clientMessageId }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === `acp:${clientMessageId}` &&
event.state === "completed",
);
}
const items = events.flatMap((event) =>
event.type === "timeline.item" &&
(event.item.type === "assistant_message" || event.item.type === "reasoning")
? [
{
id: event.item.id,
text: event.item.text,
...(event.item.type === "assistant_message" && event.item.messageId
? { messageId: event.item.messageId }
: {}),
},
]
: [],
);
expect(items).toEqual([
{ id: "agent_message_chunk:1", text: "- **Current tem" },
{ id: "agent_message_chunk:1", text: "- **Current temperature**: 25°C" },
{ id: "agent_message_chunk:2", text: "next turn" },
{ id: "agent_thought_chunk:3", text: "think A" },
{
id: JSON.stringify(["agent_message_chunk", "m-explicit"]),
messageId: "m-explicit",
text: "say",
},
{ id: "agent_thought_chunk:4", text: "think B" },
]);
await connection.close();
});
});
function textChunk(
text: string,
kind: "agent_message_chunk" | "agent_thought_chunk" = "agent_message_chunk",
messageId?: string,
): SessionUpdate {
return {
sessionUpdate: kind,
content: { type: "text", text },
...(messageId === undefined ? {} : { messageId }),
};
}
async function streamChunkTurns(
updates: SessionUpdate[],
ending: "completed" | "canceled" | "failed" = "completed",
) {
let promptCount = 0;
const harness = connectorHarness({
handleRequest(instance, request) {
if (request.method !== "session/prompt") return false;
promptCount++;
for (const update of promptCount === 1 ? updates : [textChunk("Next turn")]) {
instance.notify("session/update", { sessionId: "connector-session", update });
}
if (promptCount === 1 && ending === "failed") instance.reject(request, "Prompt failed");
else
instance.respond(request, {
stopReason: promptCount === 1 && ending === "canceled" ? "cancelled" : "end_turn",
});
return true;
},
});
const registration = runAcpProvider({
id: "chunk-boundaries",
label: "Chunk boundaries",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
for (const clientMessageId of ["first", "second"]) {
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId,
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: clientMessageId }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === `acp:${clientMessageId}` &&
event.state === (clientMessageId === "first" ? ending : "completed"),
);
}
const messages = new Map<string, { type: string; text: string }>();
for (const event of events) {
if (
event.type === "timeline.item" &&
(event.item.type === "assistant_message" || event.item.type === "reasoning")
) {
messages.set(event.item.id, { type: event.item.type, text: event.item.text });
}
}
return [...messages.values()];
} finally {
await connection.close();
}
}
describe("ACP streamed message boundaries", () => {
it("keeps reasoning separate from a reply sharing its native message ID", async () => {
expect(
await streamChunkTurns([
textChunk("private ", "agent_thought_chunk", "shared-id"),
textChunk("reasoning", "agent_thought_chunk", "shared-id"),
textChunk("public ", "agent_message_chunk", "shared-id"),
textChunk("reply", "agent_message_chunk", "shared-id"),
]),
).toEqual([
{ type: "reasoning", text: "private reasoning" },
{ type: "assistant_message", text: "public reply" },
{ type: "assistant_message", text: "Next turn" },
]);
});
it.each([
{
name: "tool call",
update: {
sessionUpdate: "tool_call",
toolCallId: "tool",
title: "Read",
kind: "read",
status: "in_progress",
},
},
{ name: "plan", update: { sessionUpdate: "plan", entries: [] } },
{
name: "user message",
update: { sessionUpdate: "user_message_chunk", content: { type: "text", text: "User" } },
},
] satisfies Array<{ name: string; update: SessionUpdate }>)(
"starts a new message after a $name",
async ({ update }) => {
expect(
await streamChunkTurns([
textChunk("Before"),
update,
textChunk("After "),
textChunk("boundary"),
]),
).toEqual([
{ type: "assistant_message", text: "Before" },
{ type: "assistant_message", text: "After boundary" },
{ type: "assistant_message", text: "Next turn" },
]);
},
);
it("continues text while an existing tool receives a status update", async () => {
expect(
await streamChunkTurns([
{
sessionUpdate: "tool_call",
toolCallId: "tool",
title: "Read",
kind: "read",
status: "in_progress",
},
textChunk("Still "),
{ sessionUpdate: "tool_call_update", toolCallId: "tool", status: "completed" },
textChunk("speaking"),
]),
).toEqual([
{ type: "assistant_message", text: "Still speaking" },
{ type: "assistant_message", text: "Next turn" },
]);
});
it("keeps explicit messages separate from neighboring anonymous chunks", async () => {
expect(
await streamChunkTurns([
textChunk("Before"),
textChunk("Explicit ", "agent_message_chunk", "message"),
textChunk("message", "agent_message_chunk", "message"),
textChunk("After"),
]),
).toEqual([
{ type: "assistant_message", text: "Before" },
{ type: "assistant_message", text: "Explicit message" },
{ type: "assistant_message", text: "After" },
{ type: "assistant_message", text: "Next turn" },
]);
});
it("continues reasoning but starts a new segment after nontext assistant content", async () => {
expect(
await streamChunkTurns([
textChunk("Think ", "agent_thought_chunk"),
textChunk("first", "agent_thought_chunk"),
{
sessionUpdate: "agent_message_chunk",
content: { type: "image", data: "", mimeType: "image/png" },
},
textChunk("Then think", "agent_thought_chunk"),
]),
).toEqual([
{ type: "reasoning", text: "Think first" },
{ type: "reasoning", text: "Then think" },
{ type: "assistant_message", text: "Next turn" },
]);
});
it.each(["completed", "canceled", "failed"] as const)(
"keeps the next turn separate after a %s prompt",
async (ending) => {
expect(await streamChunkTurns([textChunk("First "), textChunk("turn")], ending)).toEqual([
{ type: "assistant_message", text: "First turn" },
{ type: "assistant_message", text: "Next turn" },
]);
},
);
});
function userChunk(text: string, messageId?: string): SessionUpdate {
return {
sessionUpdate: "user_message_chunk",
content: { type: "text", text },
...(messageId === undefined ? {} : { messageId }),
};
}
async function openReplaySession(
replay: SessionUpdate[],
history: "replay" | "skip",
): Promise<{ connection: ProviderConnection; events: ProviderEvent[] }> {
const harness = connectorHarness({
capabilities: { loadSession: true },
handleRequest(instance, request) {
if (request.method !== "session/load") return false;
for (const update of replay) {
instance.notify("session/update", { sessionId: "connector-session", update });
}
instance.respond(request, {
sessionId: "connector-session",
modes: null,
configOptions: [],
});
return true;
},
});
const registration = runAcpProvider({
id: "replay-acp",
label: "Replay ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.persistence"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
const input = openInput();
input.persistence = { version: 1, data: { sessionId: "connector-session" } };
input.history = history;
await connection.send(input);
await waitForEvent(events, (event) => event.type === "session.ready");
return { connection, events };
}
function timelineProjection(events: ProviderEvent[]): Array<Record<string, string>> {
return events.flatMap((event) => {
if (event.type !== "timeline.item") return [];
const item = event.item;
if (
item.type === "user_message" ||
item.type === "assistant_message" ||
item.type === "reasoning"
) {
return [{ type: item.type, id: item.id, text: item.text }];
}
if (item.type === "tool_call") return [{ type: item.type, id: item.id, status: item.status }];
return [{ type: item.type, id: item.id }];
});
}
describe("ACP session history replay", () => {
it("restores the timeline replayed before session/load resolves", async () => {
const { connection, events } = await openReplaySession(
[
userChunk("What is the ", "user-1"),
userChunk("temperature?", "user-1"),
textChunk("Checking the sensor", "agent_thought_chunk"),
{
sessionUpdate: "tool_call",
toolCallId: "tool-1",
title: "Read sensor",
kind: "read",
status: "in_progress",
},
{ sessionUpdate: "tool_call_update", toolCallId: "tool-1", status: "completed" },
textChunk("It is 25°C"),
],
"replay",
);
try {
expect(timelineProjection(events)).toEqual([
{ type: "user_message", id: '["user_message_chunk","user-1"]', text: "What is the " },
{
type: "user_message",
id: '["user_message_chunk","user-1"]',
text: "What is the temperature?",
},
{ type: "reasoning", id: "agent_thought_chunk:1", text: "Checking the sensor" },
{ type: "tool_call", id: "tool-1", status: "running" },
{ type: "tool_call", id: "tool-1", status: "completed" },
{ type: "assistant_message", id: "agent_message_chunk:2", text: "It is 25°C" },
]);
const lastReplayed = events.findLastIndex((event) => event.type === "timeline.item");
const opened = events.findIndex((event) => event.type === "session.opened");
expect(lastReplayed).toBeLessThan(opened);
} finally {
await connection.close();
}
});
it("keeps replayed user, reasoning and reply chunks separate when their native IDs match", async () => {
const { connection, events } = await openReplaySession(
[
userChunk("What is the ", "shared-id"),
userChunk("temperature?", "shared-id"),
textChunk("Checking ", "agent_thought_chunk", "shared-id"),
textChunk("the sensor", "agent_thought_chunk", "shared-id"),
textChunk("It is ", "agent_message_chunk", "shared-id"),
textChunk("25°C", "agent_message_chunk", "shared-id"),
],
"replay",
);
try {
const items = new Map(
events.flatMap((event) =>
event.type === "timeline.item" ? [[event.item.id, event.item] as const] : [],
),
);
expect([...items.values()]).toEqual([
{
type: "user_message",
id: '["user_message_chunk","shared-id"]',
messageId: "shared-id",
text: "What is the temperature?",
},
{
type: "reasoning",
id: '["agent_thought_chunk","shared-id"]',
text: "Checking the sensor",
},
{
type: "assistant_message",
id: '["agent_message_chunk","shared-id"]',
messageId: "shared-id",
text: "It is 25°C",
},
]);
} finally {
await connection.close();
}
});
it("continues anonymous user chunks into one message and starts a new one after an agent reply", async () => {
const { connection, events } = await openReplaySession(
[
userChunk("first "),
userChunk("question"),
textChunk("answer"),
userChunk("second question"),
],
"replay",
);
try {
expect(timelineProjection(events)).toEqual([
{ type: "user_message", id: "user_message_chunk:1", text: "first " },
{ type: "user_message", id: "user_message_chunk:1", text: "first question" },
{ type: "assistant_message", id: "agent_message_chunk:2", text: "answer" },
{ type: "user_message", id: "user_message_chunk:3", text: "second question" },
]);
} finally {
await connection.close();
}
});
it("does not duplicate the live prompt echo when the agent echoes it as a user chunk", async () => {
const harness = connectorHarness({
capabilities: { loadSession: true },
promptUpdates: (promptText) => [
{ sessionUpdate: "user_message_chunk", content: { type: "text", text: promptText } },
{ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "Acknowledged" } },
],
});
const registration = runAcpProvider({
id: "echo-acp",
label: "Echo ACP",
connector: harness.connector,
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.persistence"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
const input = openInput();
input.persistence = { version: 1, data: { sessionId: "connector-session" } };
input.history = "replay";
await connection.send(input);
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "echo-1",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "hello" }] },
},
});
try {
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:echo-1" &&
event.state === "completed",
);
expect(timelineProjection(events)).toEqual([
{ type: "user_message", id: "echo-1", text: "hello" },
{ type: "assistant_message", id: "agent_message_chunk:1", text: "Acknowledged" },
]);
} finally {
await connection.close();
}
});
it("drops replayed updates when the open request asks to skip history", async () => {
const { connection, events } = await openReplaySession(
[userChunk("What is in the README?", "user-1"), textChunk("It describes the project.")],
"skip",
);
try {
expect(timelineProjection(events)).toEqual([]);
} finally {
await connection.close();
}
});
});
it("sends extension requests from discovery and configure and preserves JSON-RPC errors", async () => {
const { connector, instances } = connectorHarness({
handleRequest(instance, request) {
if (request.method === "_example/catalog") {
instance.respond(request, { model: "vendor-model" });
return true;
}
if (request.method === "_example/select") {
instance.reject(request, "Vendor rejected the selection");
return true;
}
return false;
},
});
const registration = runAcpProvider({
id: "extensions",
label: "Extensions",
connector,
transformers: [
{
async discover(catalog, { request }) {
expect(await request("_example/catalog", { scope: "all" })).toEqual({
model: "vendor-model",
});
return { ...catalog, defaultModel: "vendor-model" };
},
async configure(change, { request }) {
await expect(request("_example/select", { model: change.value })).rejects.toMatchObject({
code: -32603,
message: "Vendor rejected the selection",
});
return "handled";
},
},
],
});
const connection = await registration.connect({
versions: [1],
capabilities: ["session.configure"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send({ type: "catalog", requestId: "catalog" });
expect(
await waitForEvent(
events,
(event) => event.type === "catalog" || event.type === "request.failed",
),
).toMatchObject({ type: "catalog", catalog: { defaultModel: "vendor-model" } });
expect(instances[1].requests).toContainEqual(
expect.objectContaining({
method: "_example/catalog",
params: { scope: "all" },
}),
);
const input = openInput();
await connection.send({ ...input, config: { ...input.config, model: "vendor-model" } });
expect(
await waitForEvent(
events,
(event) => event.type === "session.ready" || event.type === "request.failed",
),
).toMatchObject({ type: "session.ready" });
expect(instances[2].requests).toContainEqual(
expect.objectContaining({
method: "_example/select",
params: { model: "vendor-model" },
}),
);
} finally {
await connection.close();
}
});
it("rewrites the session-ready, notification and configure-commit config snapshots", async () => {
const modelOption = {
id: "model",
name: "Model",
category: "model",
type: "select",
currentValue: "first",
options: ["first", "second", "third"].map((value) => ({ name: value, value })),
};
const { connector, instances } = connectorHarness({ configOptions: [modelOption] });
const registration = runAcpProvider({
id: "config-transformer",
label: "Config Transformer",
connector,
transformers: [
{
config(state, { sessionId }) {
return { ...state, model: `${sessionId}/${state.model}` };
},
},
],
});
const connection = await registration.connect({
versions: [1],
capabilities: ["session.configure"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
const models = () =>
events.flatMap((event) => (event.type === "session.config" ? [event.config.model] : []));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
expect(models()).toEqual(["session-1/first"]);
instances[1].notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "config_option_update",
configOptions: [{ ...modelOption, currentValue: "second" }],
},
});
await expect.poll(models).toEqual(["session-1/first", "session-1/second"]);
await connection.send({
type: "session.configure",
requestId: "configure",
sessionId: "session-1",
changes: { model: "third" },
});
await expect.poll(models).toEqual(["session-1/first", "session-1/second", "session-1/third"]);
} finally {
await connection.close();
}
});
describe("ACP out-of-turn background activity", () => {
it.each(["idle interrupt", "foreground interrupt", "disconnect"] as const)(
"settles the command on %s",
async (action) => {
const toolCall = {
sessionUpdate: "tool_call",
toolCallId: "cmd",
kind: "execute",
title: "sleep 60",
status: "in_progress",
};
let foregroundPrompt: AcpRequestMessage | undefined;
const { connector, instances } = connectorHarness({
promptUpdates: () => [toolCall],
handleRequest(instance, request) {
if (action !== "foreground interrupt" || request.method !== "session/prompt")
return false;
foregroundPrompt = request;
instance.notify("session/update", { sessionId: "connector-session", update: toolCall });
return true;
},
async afterMessage(instance, message) {
if (!("method" in message) || message.method !== "session/cancel") return;
instance.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd", status: "failed" },
});
await nextTurn();
},
});
const registration = runAcpProvider({
id: "out-of-turn-idle-stop",
label: "Idle ACP Stop",
connector,
acpOptions: { outOfTurnActivity: true },
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.can_stop_runtime"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "command",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Start" }] },
},
});
const agent = instances[1];
if (action === "foreground interrupt") {
await waitForEvent(
events,
(event) => event.type === "timeline.item" && event.item.id === "cmd",
);
} else {
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:command" &&
event.state === "completed",
);
}
if (action !== "disconnect") {
await connection.send({
type: "session.interrupt",
requestId: "interrupt",
sessionId: "session-1",
});
await waitForEvent(
events,
(event) => event.type === "request.completed" && event.requestId === "interrupt",
);
if (foregroundPrompt) {
agent.respond(foregroundPrompt, { stopReason: "cancelled" });
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:command" &&
event.state === "canceled",
);
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call_update",
toolCallId: "cmd",
rawOutput: "late output",
},
});
await nextTurn();
}
expect(await queryCanStop(connection, events, "after-stop")).toBe(true);
} else {
agent.closeFromAgent();
await waitForEvent(events, (event) => event.type === "session.runtime_failed");
}
expect(
events.findLast((event) => event.type === "timeline.item" && event.item.id === "cmd"),
).toMatchObject({
turnId: "acp:command",
item: { status: action === "disconnect" ? "failed" : "canceled" },
});
const background = events.findLast((event) => event.type === "session.background_work");
if (action === "foreground interrupt") expect(background).toBeUndefined();
else expect(background).toMatchObject({ items: action === "idle interrupt" ? [] : null });
expect(
events.filter((event) => event.type === "session.turn").map((event) => event.turnId),
).toEqual(["acp:command", "acp:command"]);
} finally {
await connection.close();
}
},
);
async function queryCanStop(
connection: ProviderConnection,
events: ProviderEvent[],
requestId: string,
): Promise<boolean> {
await connection.send({
type: "session.can_stop_runtime",
requestId,
sessionId: "session-1",
});
const reply = await waitForEvent(
events,
(event) => event.type === "session.can_stop_runtime" && event.requestId === requestId,
);
return reply.type === "session.can_stop_runtime" ? reply.canStop : false;
}
it("tracks background tools across end_turn and opens autonomous turns for out-of-turn wakeups", async () => {
const { connector, instances } = connectorHarness({
promptUpdates: () => [
{
sessionUpdate: "tool_call",
toolCallId: "cmd-1",
name: "run_command",
kind: "execute",
title: "npm run typecheck",
status: "in_progress",
rawInput: { CommandLine: "npm run typecheck", toolSummary: "Typecheck workspace" },
},
{
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "Waiting for typecheck." },
},
{ sessionUpdate: "usage_update", used: 1000, size: 100000 },
],
});
const registration = runAcpProvider({
id: "out-of-turn-acp",
label: "Out-of-turn ACP",
connector,
acpOptions: { outOfTurnActivity: { settleDelayMs: 40 } },
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.can_stop_runtime"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
expect(await queryCanStop(connection, events, "stop-before")).toBe(true);
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-1",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Run typecheck" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-1" &&
event.state === "completed",
);
// The background tool stayed running across end_turn and is reported as background work.
const toolEventsAfterPrompt = events.filter(
(event) => event.type === "timeline.item" && event.item.id === "cmd-1",
);
expect(toolEventsAfterPrompt.at(-1)).toMatchObject({
item: { type: "tool_call", id: "cmd-1", status: "running" },
});
expect(events.findLast((event) => event.type === "session.background_work")).toEqual({
type: "session.background_work",
sessionId: "session-1",
canInterruptSession: true,
items: [
{
id: "cmd-1",
kind: "shell",
description: "Typecheck workspace",
command: "npm run typecheck",
},
],
});
expect(await queryCanStop(connection, events, "stop-while-bg")).toBe(false);
// Background command finishes out of turn and wakes the agent, which runs a chained command.
const agent = instances[1];
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call_update",
toolCallId: "cmd-1",
status: "completed",
rawOutput: { output: "ok" },
},
});
const autoStart = await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.state === "started",
);
const autoTurnId = autoStart.type === "session.turn" ? autoStart.turnId : "";
expect(await queryCanStop(connection, events, "stop-during-wakeup")).toBe(false);
expect(events.findLast((event) => event.type === "session.background_work")).toEqual({
type: "session.background_work",
sessionId: "session-1",
items: [],
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "agent_thought_chunk",
content: { type: "text", text: "Now running lint." },
},
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call",
toolCallId: "cmd-2",
name: "run_command",
kind: "execute",
title: "npm run lint",
status: "in_progress",
rawInput: { CommandLine: "npm run lint" },
},
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "Waiting for lint." },
},
});
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "usage_update", used: 1200, size: 100000 },
});
// The autonomous turn settles cleanly and hands off cmd-2 to backgroundWork.
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === autoTurnId &&
event.state === "completed",
);
expect(events.findLast((event) => event.type === "session.background_work")).toEqual({
type: "session.background_work",
sessionId: "session-1",
canInterruptSession: true,
items: [
{
id: "cmd-2",
kind: "shell",
description: "npm run lint",
command: "npm run lint",
},
],
});
expect(await queryCanStop(connection, events, "stop-while-cmd2")).toBe(false);
// cmd-2 completes and the agent delivers its final reply with no remaining background work.
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-2", status: "completed" },
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "All checks passed." },
},
});
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "usage_update", used: 1300, size: 100000 },
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.turnId !== autoTurnId &&
event.state === "completed",
);
expect(events.findLast((event) => event.type === "session.background_work")).toEqual({
type: "session.background_work",
sessionId: "session-1",
items: [],
});
expect(await queryCanStop(connection, events, "stop-after-all")).toBe(true);
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call_update",
toolCallId: "cmd-2",
rawOutput: "late output",
},
});
await nextTurn();
expect(await queryCanStop(connection, events, "stop-after-late-output")).toBe(true);
} finally {
await connection.close();
}
});
it("cancels an active out-of-turn wakeup and clears background work on interrupt", async () => {
const { connector, instances } = connectorHarness({
async afterMessage(instance, message) {
if (!("method" in message) || message.method !== "session/cancel") return;
instance.notify("session/update", {
sessionId: "connector-session",
update: textChunk("Reply chunk during Stop"),
});
await nextTurn();
},
promptUpdates: (text) =>
text === "Start"
? [
{
sessionUpdate: "tool_call",
toolCallId: "pending-before-stop",
kind: "execute",
title: "Pending command",
status: "pending",
},
{
sessionUpdate: "tool_call",
toolCallId: "cmd-1",
name: "run_command",
kind: "execute",
title: "sleep 30",
status: "in_progress",
},
{ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "Waiting." } },
]
: [textChunk("Follow-up accepted")],
});
const registration = runAcpProvider({
id: "out-of-turn-cancel",
label: "Out-of-turn Cancel",
connector,
acpOptions: { outOfTurnActivity: { settleDelayMs: 500 } },
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.can_stop_runtime"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-1",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Start" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-1" &&
event.state === "completed",
);
// Start an autonomous wakeup with a new running command, then interrupt it.
const agent = instances[1];
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-1", status: "completed" },
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call",
toolCallId: "cmd-2",
name: "run_command",
kind: "execute",
title: "sleep 60",
status: "in_progress",
},
});
const autoStart = await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.state === "started",
);
const autoTurnId = autoStart.type === "session.turn" ? autoStart.turnId : "";
await connection.send({
type: "session.interrupt",
requestId: "interrupt-1",
sessionId: "session-1",
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === autoTurnId &&
event.state === "canceled",
);
expect(events.findLast((event) => event.type === "session.background_work")).toEqual({
type: "session.background_work",
sessionId: "session-1",
items: [],
});
expect(await queryCanStop(connection, events, "stop-after-cancel")).toBe(true);
agent.notify("session/update", {
sessionId: "connector-session",
update: textChunk("Reply chunk after Stop"),
});
await nextTurn();
expect(await queryCanStop(connection, events, "stop-after-late-reply")).toBe(true);
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-2",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Follow-up" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-2" &&
event.state === "completed",
);
expect(events).toContainEqual(
expect.objectContaining({
type: "timeline.item",
item: expect.objectContaining({ type: "assistant_message", text: "Follow-up accepted" }),
}),
);
// The canceled tool's terminal echo can arrive after the next prompt finishes.
const turnCountAfterCancel = events.filter((event) => event.type === "session.turn").length;
const output = {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-2", rawOutput: "late line" },
};
agent.notify("session/update", output);
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-2", status: "failed" },
});
agent.notify("session/update", output);
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call_update",
toolCallId: "pending-before-stop",
status: "failed",
},
});
await new Promise((resolve) => setTimeout(resolve, 60));
expect(events.filter((event) => event.type === "session.turn")).toHaveLength(
turnCountAfterCancel,
);
expect(await queryCanStop(connection, events, "stop-after-cancel-echo")).toBe(true);
} finally {
await connection.close();
}
});
it("finishes a settling autonomous turn cleanly without sending cancel when a new prompt arrives", async () => {
let cancelCount = 0;
const { connector, instances } = connectorHarness({
handleMessage: (_instance, message) => {
if ("method" in message && message.method === "session/cancel") {
cancelCount += 1;
}
return false;
},
promptUpdates: (text) =>
text === "First"
? [
{
sessionUpdate: "tool_call",
toolCallId: "cmd-1",
name: "run_command",
kind: "execute",
title: "sleep 10",
status: "in_progress",
},
{
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "Waiting." },
},
]
: [
{
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "Second ok" },
},
],
});
const registration = runAcpProvider({
id: "out-of-turn-prompt",
label: "Out-of-turn Prompt",
connector,
acpOptions: { outOfTurnActivity: { settleDelayMs: 5_000 } },
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-1",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "First" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-1" &&
event.state === "completed",
);
const agent = instances[1];
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-1", status: "completed" },
});
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "Done." } },
});
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "usage_update", used: 1100, size: 100000 },
});
const autoStart = await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.state === "started",
);
const autoTurnId = autoStart.type === "session.turn" ? autoStart.turnId : "";
await waitForEvent(
events,
(event) => event.type === "session.usage" && event.usage.contextWindowUsedTokens === 1100,
);
// Send a follow-up prompt while the autonomous turn is in its settle window.
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-2",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Second" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-2" &&
event.state === "completed",
);
expect(events).toContainEqual({
type: "session.turn",
sessionId: "session-1",
turnId: autoTurnId,
state: "completed",
});
expect(cancelCount).toBe(0);
} finally {
await connection.close();
}
});
it("settles silent tool-only and thought-only wakeups via quietLimitMs", async () => {
const { connector, instances } = connectorHarness({
promptUpdates: () => [
{
sessionUpdate: "tool_call",
toolCallId: "cmd-1",
name: "run_command",
kind: "execute",
title: "sleep 10",
status: "in_progress",
},
{
sessionUpdate: "tool_call",
toolCallId: "cmd-2",
kind: "execute",
title: "Long command",
status: "pending",
},
{ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "Waiting." } },
],
});
const registration = runAcpProvider({
id: "out-of-turn-quiet-limit",
label: "Out-of-turn Quiet Limit",
connector,
acpOptions: { outOfTurnActivity: { settleDelayMs: 40, quietLimitMs: 120 } },
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.can_stop_runtime"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-1",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Start" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-1" &&
event.state === "completed",
);
// Tool completes with no assistant reply; quietLimitMs settles the wakeup cleanly.
const agent = instances[1];
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-1", status: "completed" },
});
const firstAuto = await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.state === "completed",
);
expect(await queryCanStop(connection, events, "stop-after-tool-only")).toBe(true);
// Thought-only wakeup also settles via quietLimitMs instead of hanging.
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "agent_thought_chunk",
content: { type: "text", text: "Nothing else needed." },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.turnId !== (firstAuto.type === "session.turn" ? firstAuto.turnId : "") &&
event.state === "completed",
);
expect(await queryCanStop(connection, events, "stop-after-thought-only")).toBe(true);
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call_update",
toolCallId: "cmd-2",
status: "in_progress",
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:autonomous:3" &&
event.state === "completed",
);
expect(events.findLast((event) => event.type === "session.background_work")).toMatchObject({
items: [{ id: "cmd-2", description: "Long command" }],
});
expect(await queryCanStop(connection, events, "stop-with-detached-command")).toBe(false);
} finally {
await connection.close();
}
});
it("keeps an open reply in one autonomous turn until usage_update closes it", async () => {
const { connector, instances } = connectorHarness({
promptUpdates: () => [
{
sessionUpdate: "tool_call",
toolCallId: "cmd-1",
name: "run_command",
kind: "execute",
title: "sleep 10",
status: "in_progress",
},
{
sessionUpdate: "tool_call",
toolCallId: "cmd-2",
kind: "execute",
title: "Other command",
status: "in_progress",
},
{ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "Waiting." } },
],
});
const registration = runAcpProvider({
id: "out-of-turn-open-reply",
label: "Out-of-turn Open Reply",
connector,
acpOptions: { outOfTurnActivity: { settleDelayMs: 30, quietLimitMs: 2_000 } },
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-1",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Start" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-1" &&
event.state === "completed",
);
const agent = instances[1];
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-1", status: "completed" },
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "Part 1. " },
},
});
const autoStart = await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.state === "started",
);
const autoTurnId = autoStart.type === "session.turn" ? autoStart.turnId : "";
// Wait longer than settleDelayMs without usage_update: replyOpen keeps the turn open.
await new Promise((resolve) => setTimeout(resolve, 120));
expect(
events.some(
(event) =>
event.type === "session.turn" &&
event.turnId === autoTurnId &&
event.state === "completed",
),
).toBe(false);
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "Part 2." },
},
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call_update",
toolCallId: "cmd-2",
rawOutput: "Background progress",
},
});
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "usage_update", used: 1200, size: 100000 },
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === autoTurnId &&
event.state === "completed",
1_000,
);
const startedAutonomousTurns = events.filter(
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.state === "started",
);
expect(startedAutonomousTurns).toHaveLength(1);
} finally {
await connection.close();
}
});
it("preserves earlier background work when a follow-up is rejected", async () => {
let cancelCount = 0;
const { connector, instances } = connectorHarness({
handleMessage: (_instance, message) => {
if ("method" in message && message.method === "session/cancel") {
cancelCount += 1;
}
return false;
},
handleRequest: (instance, request) => {
const params = request.params as { prompt?: Array<{ text?: string }> };
if (request.method !== "session/prompt" || params.prompt?.[0]?.text !== "Second")
return false;
instance.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-3", status: "in_progress" },
});
instance.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "tool_call",
toolCallId: "cmd-4",
kind: "execute",
title: "Follow-up command",
status: "in_progress",
},
});
instance.reject(request, "Follow-up rejected");
return true;
},
promptUpdates: (text) =>
text === "First"
? [
{
sessionUpdate: "tool_call",
toolCallId: "cmd-1",
name: "run_command",
kind: "execute",
title: "cmd-1",
status: "in_progress",
},
{
sessionUpdate: "tool_call",
toolCallId: "cmd-2",
name: "run_command",
kind: "execute",
title: "cmd-2",
status: "in_progress",
},
{
sessionUpdate: "tool_call",
toolCallId: "cmd-3",
kind: "execute",
title: "Earlier command",
status: "pending",
},
{
sessionUpdate: "agent_message_chunk",
content: { type: "text", text: "Waiting on both." },
},
]
: [],
});
const registration = runAcpProvider({
id: "out-of-turn-followup",
label: "Out-of-turn Followup",
connector,
acpOptions: { outOfTurnActivity: { settleDelayMs: 50, quietLimitMs: 5_000 } },
});
const connection = await registration.connect({
versions: [1],
capabilities: ["prompt.message", "session.can_stop_runtime"],
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
try {
await connection.send(openInput());
await waitForEvent(events, (event) => event.type === "session.ready");
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-1",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "First" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId === "acp:msg-1" &&
event.state === "completed",
);
// cmd-1 finishes and the agent is mid-thought (no assistant message or usage_update yet).
const agent = instances[1];
agent.notify("session/update", {
sessionId: "connector-session",
update: { sessionUpdate: "tool_call_update", toolCallId: "cmd-1", status: "completed" },
});
agent.notify("session/update", {
sessionId: "connector-session",
update: {
sessionUpdate: "agent_thought_chunk",
content: { type: "text", text: "Analyzing cmd-1 output..." },
},
});
const autoStart = await waitForEvent(
events,
(event) =>
event.type === "session.turn" &&
event.turnId.startsWith("acp:autonomous:") &&
event.state === "started",
);
const autoTurnId = autoStart.type === "session.turn" ? autoStart.turnId : "";
// Follow-up prompt completes the wakeup without sending session/cancel and keeps cmd-2 alive.
await connection.send({
type: "session.prompt",
sessionId: "session-1",
prompt: {
clientMessageId: "msg-2",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "Second" }] },
},
});
await waitForEvent(
events,
(event) =>
event.type === "session.turn" && event.turnId === "acp:msg-2" && event.state === "failed",
);
expect(events).toContainEqual({
type: "session.turn",
sessionId: "session-1",
turnId: autoTurnId,
state: "completed",
});
expect(cancelCount).toBe(0);
expect(events.findLast((event) => event.type === "session.background_work")).toEqual({
type: "session.background_work",
sessionId: "session-1",
canInterruptSession: true,
items: [
{
id: "cmd-2",
kind: "shell",
description: "cmd-2",
},
{ id: "cmd-3", kind: "shell", description: "Earlier command" },
],
});
expect(
events.findLast((event) => event.type === "timeline.item" && event.item.id === "cmd-3"),
).toMatchObject({
turnId: "acp:msg-1",
item: { status: "running" },
});
expect(
events.findLast((event) => event.type === "timeline.item" && event.item.id === "cmd-4"),
).toMatchObject({
turnId: "acp:msg-2",
item: { status: "failed" },
});
expect(await queryCanStop(connection, events, "stop-with-cmd2")).toBe(false);
} finally {
await connection.close();
}
});
});