@visual-z/xeno 0.5.0 → 0.6.0

package/src/runtime/acp-agent.ts

@@ -0,0 +1,289 @@
+/** ACP is a transport over the existing session owner, never a second agent loop (Q24/D8). */
+import { isAbsolute, resolve } from "node:path";
+import { agent, PROTOCOL_VERSION, RequestError, type AgentApp, type AgentConnection, type AgentContext,
+  type ClientCapabilities, type ContentBlock, type ElicitationPropertySchema, type McpServer,
+  type SessionModeState, type SessionUpdate, type StopReason, type ToolCall, type RequestPermissionResponse } from "@agentclientprotocol/sdk";
+import { CONTROL_SCHEMA } from "../core/control-protocol.ts";
+import { parseMcpServers, type McpServers } from "../core/mcp-config.ts";
+import type { LogEvent } from "../core/events.ts";
+import type { QuestionRequest, QuestionReply } from "../core/question.ts";
+import type { ExecutionOutcome } from "../core/outcome.ts";
+import type { PendingApproval, SessionControl } from "./session-control.ts";
+import type { ApprovalChoice } from "./tools.ts";
+import type { SessionHub } from "./session-hub.ts";
+
+function invalid(message: string): never { throw RequestError.invalidParams(undefined, message); }
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+/** Normalize explicit client configuration; annotations and tool output cannot configure processes. */
+export function acpMcpServers(servers: readonly McpServer[]): McpServers {
+  const result: Record<string, unknown> = Object.create(null);
+  for (const server of servers) {
+    if (Object.hasOwn(result, server.name)) invalid("MCP server names must be unique");
+    if ("type" in server) {
+      if (server.type !== "http") invalid("This agent supports stdio and HTTP MCP servers only");
+      result[server.name] = { transport: "http", url: server.url, headers: pairs(server.headers) };
+    } else result[server.name] = { transport: "stdio", command: server.command, args: [...server.args], env: pairs(server.env) };
+  }
+  try { return parseMcpServers(result); } catch { return invalid("Invalid MCP server configuration"); }
+}
+function pairs(values: readonly { name: string; value: string }[]): Record<string, string> {
+  const result: Record<string, string> = Object.create(null);
+  for (const value of values) {
+    if (Object.hasOwn(result, value.name)) invalid("Duplicate MCP environment or header name");
+    result[value.name] = value.value;
+  }
+  return result;
+}
+function modes(control: SessionControl): SessionModeState | undefined {
+  return control.configureWorkflow ? { currentModeId: control.session.config.tools.workflowMode ?? "build", availableModes: [
+    { id: "build", name: "Build", description: "Implement and verify workspace changes." },
+    { id: "plan", name: "Plan", description: "Inspect and plan with read-only tools." },
+  ] } : undefined;
+}
+function promptText(blocks: readonly ContentBlock[]): string {
+  const parts = blocks.map(block => {
+    if (block.type === "text") return block.text;
+    // Baseline resource links remain references. Reading them goes through the normal tool admission.
+    if (block.type === "resource_link") return `Resource ${JSON.stringify(block.name)}: ${JSON.stringify(block.uri)}${block.description ? `\n${block.description}` : ""}`;
+    if (block.type === "resource" && "text" in block.resource) return `Resource ${JSON.stringify(block.resource.uri)}:\n${block.resource.text}`;
+    return invalid("This agent accepts text, resource links and embedded text; image/audio/binary prompts are unavailable");
+  });
+  const text = parts.join("\n\n");
+  if (!text.trim() || Buffer.byteLength(text) > CONTROL_SCHEMA.limits.frameBytes) invalid("Prompt must contain text within the ACP message limit");
+  return text;
+}
+function stopReason(outcome: ExecutionOutcome | undefined, cancelled: boolean): StopReason {
+  if (cancelled || outcome?.status === "cancelled") return "cancelled";
+  if (outcome?.reason === "model_refusal") return "refusal";
+  if (outcome?.reason === "output_limit") return "max_tokens";
+  if (outcome?.status === "completed") return "end_turn";
+  if (outcome?.status === "stopped") return "max_turn_requests";
+  throw RequestError.internalError(undefined, "The session failed or its termination is unknown; inspect the durable outcome");
+}
+function title(name: string, input: unknown): string {
+  const raw = object(input), detail = raw?.["cmd"] ?? raw?.["command"] ?? raw?.["path"];
+  return typeof detail === "string" ? `${name}: ${detail}` : name;
+}
+function kind(name: string): ToolCall["kind"] {
+  if (["read", "diff"].includes(name)) return "read";
+  if (["write", "edit", "apply_patch", "format"].includes(name)) return "edit";
+  if (["bash", "exec_command", "write_stdin"].includes(name)) return "execute";
+  if (["search", "glob", "grep"].includes(name)) return "search";
+  if (["webfetch", "websearch"].includes(name)) return "fetch";
+  return "other";
+}
+function content(text: string) { return [{ type: "content" as const, content: { type: "text" as const, text } }]; }
+
+/** SDK cancellation is cooperative; a peer ignoring it cannot hold the tool owner indefinitely. */
+async function cancellable<T>(request: Promise<T>, signal: AbortSignal): Promise<T | undefined> {
+  if (signal.aborted) { void request.catch(() => {}); return undefined; }
+  let cancel = () => {};
+  const aborted = new Promise<undefined>(done => { cancel = () => done(undefined); signal.addEventListener("abort", cancel, { once: true }); });
+  try { return await Promise.race([request, aborted]); } finally { signal.removeEventListener("abort", cancel); }
+}
+
+async function elicit(client: AgentContext, sessionId: string, toolCallId: string, request: QuestionRequest, signal: AbortSignal): Promise<QuestionReply | undefined> {
+  const properties: Record<string, ElicitationPropertySchema> = Object.create(null), required: string[] = [];
+  request.questions.forEach((question, index) => {
+    const key = `q${index}`, options = question.options.map(option => ({ const: option.id, title: option.label,
+      ...(option.description ? { description: option.description } : {}) }));
+    if (options.length) {
+      properties[key] = question.multiple ? { type: "array", title: question.header, description: question.question,
+        items: { anyOf: options }, minItems: question.custom ? 0 : 1, maxItems: options.length } :
+        { type: "string", title: question.header, description: question.question, oneOf: options };
+      if (!question.custom) required.push(key);
+    }
+    if (question.custom || !options.length) {
+      properties[`${key}_text`] = { type: "string", title: `${question.header}: your answer`, description: question.question, minLength: 1 };
+      if (!options.length) required.push(`${key}_text`);
+    }
+  });
+  const response = await cancellable(client.request("elicitation/create", { sessionId, toolCallId, mode: "form",
+    message: request.questions.map(question => question.question).join("\n"), requestedSchema: { type: "object", properties, required } },
+    { cancellationSignal: signal }), signal);
+  if (response?.action !== "accept") return undefined;
+  const answers = object(response["content"]);
+  if (!answers || Object.keys(answers).some(key => !Object.hasOwn(properties, key))) return undefined;
+  return { request_id: request.request_id, turn_id: request.turn_id, answers: request.questions.map((question, index) => {
+    const value = answers[`q${index}`], text = answers[`q${index}_text`];
+    return { id: question.id, choices: typeof value === "string" ? [value] : Array.isArray(value) && value.every(item => typeof item === "string") ? value : [],
+      ...(typeof text === "string" && text.trim() ? { text } : {}) };
+  }) };
+}
+
+interface Binding {
+  control: SessionControl;
+  abort: AbortController | null;
+  pending: Map<string, ToolCall>;
+  send(update: SessionUpdate): void;
+  replay(node: number, event: LogEvent): void;
+  drain(): Promise<void>;
+  close(): void;
+}
+
+/** One AgentApp serves one client connection. Each workspace has an explicit host-owned hub. */
+export function createAcpAgent(hub: SessionHub): AgentApp {
+  const app = agent({ name: "xeno" }), bindings = new Map<string, Binding>();
+  let connection: AgentConnection | undefined, initialized = false, capabilities: ClientCapabilities = {};
+  let inFlight = 0;
+  const admit = async <T>(operation: () => Promise<T>): Promise<T> => {
+    // Assumed ingress cap: SDK schema validation bounds frames, not concurrent async handlers.
+    if (inFlight >= CONTROL_SCHEMA.limits.queuedRequests) throw RequestError.invalidRequest(undefined, "ACP request concurrency limit exceeded");
+    inFlight++; try { return await operation(); } finally { inFlight--; }
+  };
+  const requireInitialized = () => { if (!initialized || !connection || connection.signal.aborted) throw RequestError.invalidRequest(undefined, "initialize must complete before session requests"); };
+  const workspace = (params: { cwd: string; additionalDirectories?: string[]; mcpServers: McpServer[] }) => {
+    requireInitialized();
+    if (!isAbsolute(params.cwd) || resolve(params.cwd) !== resolve(hub.initial.session.config.tools.root))
+      invalid("cwd must match this agent process workspace; start one process per workspace");
+    if (params.additionalDirectories?.length) invalid("Additional workspace directories are unavailable");
+    return { cwd: params.cwd, acpMcpServers: acpMcpServers(params.mcpServers) };
+  };
+  const get = (id: string) => { requireInitialized(); const value = bindings.get(id); if (!value) throw RequestError.resourceNotFound(id); return value; };
+  const bind = (control: SessionControl): Binding => {
+    const existing = bindings.get(control.threadId); if (existing) return existing;
+    const peer = connection!;
+    let queuedBytes = 0, tail: Promise<void> = Promise.resolve(), deliveryError: unknown;
+    const pending = new Map<string, ToolCall>(), originalInputs = new Map<string, unknown>();
+    const send = (update: SessionUpdate) => {
+      const bytes = Buffer.byteLength(JSON.stringify(update)); queuedBytes += bytes;
+      if (bytes > CONTROL_SCHEMA.limits.frameBytes || queuedBytes > CONTROL_SCHEMA.limits.outputBytes) { peer.close(Error("ACP output queue exceeded its limit")); return; }
+      tail = tail.then(async () => { if (deliveryError) return; await peer.client.notify("session/update", { sessionId: control.threadId, update }); })
+        .catch(error => { deliveryError = error; peer.close(Error("ACP notification delivery failed")); })
+        .finally(() => { queuedBytes -= bytes; });
+    };
+    const record = (node: number, event: LogEvent, replay = false) => {
+      if (event.t === "user" && replay) send({ sessionUpdate: "user_message_chunk", content: { type: "text", text: event.text }, messageId: `${node}:${event.id}` });
+      if (event.t === "assistant" && replay) for (const block of event.blocks) if (block.type === "text")
+        send({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: block.text }, messageId: `${node}:${event.id}` });
+      if (event.t === "assistant") for (const block of event.blocks) if (block.type === "tool_use") originalInputs.set(`${node}:${block.call_id}`, block.input);
+      if (event.t === "tool_invocation") {
+        // Unchanged direct calls omit inline input; recover it from the original model request.
+        const key = `${node}:${event.call_id}`, input = event.input ?? originalInputs.get(key); originalInputs.delete(key);
+        const call: ToolCall = { toolCallId: `${node}:${event.id}`, name: event.name, title: title(event.name, input), kind: kind(event.name)!, status: "pending",
+          ...(input !== undefined ? { rawInput: input } : {}) };
+        pending.set(`${node}:${event.call_id}`, call); send({ sessionUpdate: "tool_call", ...call });
+      }
+      if (event.t === "tool_result") {
+        const key = `${node}:${event.call_id}`, call = pending.get(key);
+        if (!call) {
+          send({ sessionUpdate: "tool_call", toolCallId: `${node}:${event.id}`, title: "Recorded tool result", status: "pending" });
+        }
+        send({ sessionUpdate: "tool_call_update", toolCallId: call?.toolCallId ?? `${node}:${event.id}`,
+          status: event.ok && (!event.outcome || event.outcome.status === "completed") ? "completed" : "failed", content: content(event.content), rawOutput: event.data ?? event.content });
+        pending.delete(key);
+      }
+    };
+    const permission = async (approval: PendingApproval) => {
+      const abort = binding.abort; if (!abort || abort.signal.aborted || peer.signal.aborted) return;
+      const request = approval.request;
+      const matches = [...pending.values()].filter(call => call.name === request.tool &&
+        (!request.command || object(call.rawInput)?.["cmd"] === request.command || object(call.rawInput)?.["command"] === request.command));
+      const call = matches.length === 1 ? matches[0]! : undefined;
+      const toolCall = { toolCallId: call?.toolCallId ?? `permission:${approval.id}`, name: request.tool,
+        title: title(request.tool, request), status: "pending" as const,
+        rawInput: call?.rawInput ?? request, ...(request.paths ? { locations: request.paths.map(path => ({ path: resolve(control.session.config.tools.root, path) })) } : {}) };
+      if (!call) send({ sessionUpdate: "tool_call", ...toolCall });
+      let choice: ApprovalChoice = "deny";
+      try {
+        await binding.drain();
+        if (abort.signal.aborted || peer.signal.aborted) return;
+        const response = await cancellable(peer.client.request<RequestPermissionResponse>("session/request_permission", { sessionId: control.threadId, toolCall,
+          options: [{ optionId: "once", name: "Allow once", kind: "allow_once" }, { optionId: "deny", name: "Reject", kind: "reject_once" }] },
+          { cancellationSignal: abort.signal }), abort.signal);
+        if (response?.outcome.outcome === "selected" && response.outcome.optionId === "once") choice = "once";
+      } catch { /* A failed permission request denies the original invocation; never retry it. */ }
+      if (!abort.signal.aborted && control.activeTurnId === approval.turnId) {
+        try { control.respond(approval.turnId, approval.id, choice); } catch { /* another legitimate client/cancel already resolved it */ }
+      }
+      if (!call) send({ sessionUpdate: "tool_call_update", toolCallId: toolCall.toolCallId, status: choice === "once" ? "completed" : "failed" });
+    };
+    const previousAsk = control.session.config.tools.askSlot?.current;
+    const ask = (request: Parameters<SessionControl["ask"]>[0]) => control.ask(request);
+    const askSlot = control.session.config.tools.askSlot;
+    if (askSlot) askSlot.current = ask;
+    const slot = control.questionSlot, previousQuestion = slot.current;
+    const question = (request: QuestionRequest, signal: AbortSignal) => control.askQuestion(request, signal,
+      value => elicit(peer.client, control.threadId, pending.get(`${control.session.state.node}:${value.call_id}`)?.toolCallId ?? value.call_id, value, signal));
+    // Capability negotiation must precede installation; unsupported form questions fail explicitly.
+    if (capabilities.elicitation?.form != null) slot.current = question;
+    const unsubscribe = control.subscribe(notice => {
+      if (notice.method === "approval/request") void permission(notice.params["approval"] as PendingApproval);
+      if (notice.method === "item/completed") {
+        const item = notice.params["item"] as { id: string; node: number };
+        const event = control.session.state.events.find(value => value.id === item.id);
+        if (event) record(item.node, event);
+      }
+    });
+    const binding: Binding = { control, abort: null, pending, send, replay: (node, event) => record(node, event, true), drain: async () => { await tail; if (deliveryError) throw RequestError.internalError(undefined, "ACP notification delivery failed"); },
+      close: () => { binding.abort?.abort(); if (control.activeTurnId && binding.abort) control.interrupt(control.activeTurnId); unsubscribe();
+        if (askSlot?.current === ask) { if (previousAsk) askSlot.current = previousAsk; else delete askSlot.current; }
+        if (slot.current === question) { if (previousQuestion) slot.current = previousQuestion; else delete slot.current; }
+      } };
+    bindings.set(control.threadId, binding);
+    return binding;
+  };
+  app.onConnect(peer => {
+    if (connection && !connection.signal.aborted) throw Error("ACP AgentApp already has a client connection");
+    connection = peer; initialized = false; capabilities = {};
+    peer.signal.addEventListener("abort", () => { for (const binding of bindings.values()) binding.close(); bindings.clear(); }, { once: true });
+  });
+  app.onRequest("initialize", ({ params }) => {
+    if (initialized) throw RequestError.invalidRequest(undefined, "Connection is already initialized");
+    if (params.protocolVersion < 1) invalid("ACP protocol version 1 is required");
+    capabilities = params.clientCapabilities ?? {}; initialized = true;
+    return { protocolVersion: PROTOCOL_VERSION, agentInfo: { name: "xeno", version: "0.1.0" },
+      agentCapabilities: { loadSession: true, promptCapabilities: { embeddedContext: true }, mcpCapabilities: { http: true }, sessionCapabilities: { close: {} } } };
+  });
+  app.onRequest("session/new", ({ params, signal }) => admit(async () => {
+    const forwarded = workspace(params), control = await hub.open("new", forwarded);
+    if (signal.aborted || connection!.signal.aborted) { await hub.close(control.threadId); throw RequestError.requestCancelled(); }
+    bind(control); const state = modes(control);
+    return { sessionId: control.threadId, ...(state ? { modes: state } : {}) };
+  }));
+  app.onRequest("session/load", ({ params, signal }) => admit(async () => {
+    const forwarded = workspace(params), control = await hub.open("resume", { ...forwarded, session: params.sessionId });
+    if (signal.aborted || connection!.signal.aborted) throw RequestError.requestCancelled();
+    if (control.busy) throw RequestError.invalidRequest(undefined, "Cannot replay a session with an active turn");
+    const binding = bind(control);
+    // Replay durable original messages/results only. Loading never executes tools or sends provider requests.
+    for (const { node, event } of await control.items()) { binding.replay(node, event); await binding.drain(); }
+    await binding.drain(); const state = modes(control); return state ? { modes: state } : {};
+  }));
+  app.onRequest("session/prompt", ({ params, signal }) => admit(async () => {
+    const binding = get(params.sessionId), control = binding.control, input = promptText(params.prompt);
+    if (control.busy || binding.abort) throw RequestError.invalidRequest(undefined, "A prompt is already running for this session");
+    const abort = new AbortController(); binding.abort = abort; binding.pending.clear();
+    const signals = AbortSignal.any([signal, abort.signal, connection!.signal]);
+    let outcome: ExecutionOutcome | undefined;
+    try {
+      for await (const event of control.send(input, signals)) {
+        // Emit committed model text once. Provider retry/discard deltas cannot become durable conversation.
+        if (event.kind === "assistant_text" && event.text) { binding.send({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: event.text } }); await binding.drain(); }
+        if (event.kind === "done") outcome = event.outcome;
+      }
+      await binding.drain(); return { stopReason: stopReason(outcome, signals.aborted) };
+    } catch {
+      if (signals.aborted) return { stopReason: "cancelled" as const };
+      throw RequestError.internalError(undefined, "Session prompt failed; inspect its durable outcome before continuing");
+    } finally { binding.abort = null; binding.pending.clear(); }
+  }));
+  app.onNotification("session/cancel", ({ params }) => {
+    const binding = get(params.sessionId); binding.abort?.abort();
+    if (binding.abort && binding.control.activeTurnId) binding.control.interrupt(binding.control.activeTurnId);
+  });
+  app.onRequest("session/set_mode", ({ params }) => admit(async () => {
+    const binding = get(params.sessionId), control = binding.control;
+    if (params.modeId !== "plan" && params.modeId !== "build") invalid("Unknown session mode");
+    if (!control.configureWorkflow) throw RequestError.methodNotFound("session/set_mode");
+    if (control.busy) throw RequestError.invalidRequest(undefined, "Mode changes require an idle checkpoint");
+    await control.configureWorkflow(params.modeId); binding.send({ sessionUpdate: "current_mode_update", currentModeId: params.modeId }); await binding.drain(); return {};
+  }));
+  app.onRequest("session/close", ({ params }) => admit(async () => {
+    const binding = get(params.sessionId); binding.close(); bindings.delete(params.sessionId); await hub.close(binding.control.threadId); return {};
+  }));
+  return app;
+}

package/src/runtime/agent-profiles.ts

@@ -0,0 +1,21 @@
+/** R13: configuration loading is separate from applying a role to a live Session. */
+import { join } from "node:path";
+import { configDir } from "../store/config.ts";
+import { readAgentProfileFile } from "../store/agent-profile-files.ts";
+import { parseAgentProfiles, type AgentProfileLayer } from "../core/agent-profile.ts";
+
+export async function loadAgentProfileLayers(options: { readonly workspace: string; readonly trustProject: boolean; readonly userDir?: string }):
+  Promise<{ readonly layers: readonly AgentProfileLayer[]; readonly diagnostics: readonly string[] }> {
+  const paths = [{ kind: "user" as const, path: join(options.userDir ?? configDir(), "agents.json") },
+    ...(options.trustProject ? [{ kind: "project" as const, path: join(options.workspace, ".xeno", "agents.json") }] : [])];
+  const layers: AgentProfileLayer[] = [], diagnostics: string[] = [];
+  for (const source of paths) {
+    const file = await readAgentProfileFile(source.path);
+    if (!file) continue;
+    if (file.diagnostic) { diagnostics.push(file.diagnostic); continue; }
+    const parsed = parseAgentProfiles(file.value);
+    diagnostics.push(...parsed.diagnostics.map(diagnostic => `${source.path}: ${diagnostic}`));
+    if (parsed.diagnostics.length === 0) layers.push({ source, profiles: parsed.profiles });
+  }
+  return { layers, diagnostics };
+}

package/src/runtime/catalog.ts

@@ -58,10 +58,10 @@ export function loadCatalog(opts: { userText: string | null; cacheText?: string
         // Refresh metadata without replacing already verified wire dialects for existing sessions.
         const next = { ...spec, api: known.api, reasoning: known.reasoning };
         delete next.driver; delete next.compat; delete next.nativeCompat; delete next.thinkingLevelMap;
-        if (known.compat) next.compat = known.compat;
-        if (known.thinkingLevelMap) next.thinkingLevelMap = known.thinkingLevelMap;
         if (known.driver) next.driver = known.driver;
         if (known.nativeCompat) next.nativeCompat = known.nativeCompat;
+        if (known.compat) next.compat = known.compat;
+        if (known.thinkingLevelMap) next.thinkingLevelMap = known.thinkingLevelMap;
         if (known.baseUrl !== undefined) next.baseUrl = known.baseUrl;
         copyProviderAccess(spec, next);
         return next;

package/src/runtime/control-client.ts

@@ -0,0 +1,149 @@
+/** Typed local control client; requests are never retried after a delivery error. */
+import { CONTROL_SCHEMA, parseControlRequest } from "../core/control-protocol.ts";
+import type { ContextLens, LensFocus } from "../core/control-view.ts";
+import type { LogEvent } from "../core/events.ts";
+import type { QuestionReply } from "../core/question.ts";
+import type { SessionList } from "../store/sessions.ts";
+import type { ControlNotice, ControlSnapshot } from "./session-control.ts";
+
+export interface ControlApi {
+  "thread/read": { params: { threadId: string }; result: ControlSnapshot };
+  "thread/list": { params: Record<string, never>; result: SessionList & { live: string[] } };
+  "thread/new": { params: { name?: string }; result: ControlSnapshot };
+  "thread/resume": { params: { session: string }; result: ControlSnapshot };
+  "thread/fork": { params: { threadId: string; name?: string }; result: ControlSnapshot };
+  "thread/close": { params: { threadId: string }; result: { closed: boolean } };
+  "thread/mode": { params: { threadId: string; mode: "build" | "plan" }; result: ControlSnapshot };
+  "turn/start": { params: { threadId: string; input: string }; result: { turnId: string } };
+  "turn/steer": { params: { threadId: string; turnId: string; input: string }; result: { queued: boolean } };
+  "turn/interrupt": { params: { threadId: string; turnId: string }; result: { interruptRequested: boolean } };
+  "approval/respond": { params: { threadId: string; turnId: string; approvalId: string; choice: "once" | "command" | "tool" | "deny" }; result: { accepted: boolean } };
+  "question/respond": { params: { threadId: string; turnId: string; requestId: string; reply: string }; result: { accepted: boolean } };
+  "acceptance/accept": { params: { threadId: string; requestId: string; criterionId: string }; result: { accepted: boolean } };
+  "context/read": { params: { threadId: string; focus: LensFocus; offset?: number; limit?: number }; result: {
+    node: number; streamId: string; sequence: number; focus: LensFocus; total: number; entries: readonly unknown[]; nextOffset: number | null;
+    components: ContextLens["components"]; used: ContextLens["used"]; countKind: ContextLens["countKind"] } };
+  "item/list": { params: { threadId: string; after?: { node: number; event: string }; limit?: number }; result: {
+    items: { node: number; id: string; type: LogEvent["t"] }[]; nextCursor: { node: number; event: string } | null } };
+  "item/read": { params: { threadId: string; node: number; event: string }; result: { node: number; event: LogEvent } };
+  "thread/subscribe": { params: { threadId: string; after?: { streamId: string; sequence: number } }; result: { snapshot: ControlSnapshot; resyncRequired: boolean } };
+}
+function record(value: unknown): value is Record<string, unknown> { return !!value && typeof value === "object" && !Array.isArray(value); }
+function identity(value: unknown): value is string { return typeof value === "string" && value.length > 0 && value.length <= 128; }
+function count(value: unknown): value is number { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0; }
+function snapshot(value: unknown): boolean {
+  return record(value) && value["version"] === CONTROL_SCHEMA.protocol && identity(value["threadId"]) && identity(value["streamId"]) && count(value["sequence"])
+    && count(value["node"]) && (value["activeTurnId"] === null || identity(value["activeTurnId"])) && (value["goal"] === null || record(value["goal"]))
+    && [null, "permission", "question", "auth"].includes(value["waiting"] as null) && Array.isArray(value["approvals"]) && Array.isArray(value["questions"]) && record(value["context"]);
+}
+function result(method: keyof ControlApi, value: unknown): boolean {
+  if (["thread/read", "thread/new", "thread/resume", "thread/fork", "thread/mode"].includes(method)) return snapshot(value);
+  if (!record(value)) return false;
+  switch (method) {
+    case "thread/list": return Array.isArray(value["sessions"]) && count(value["truncated"]) && Array.isArray(value["live"]) && value["live"].every(identity);
+    case "thread/close": return typeof value["closed"] === "boolean";
+    case "turn/start": return identity(value["turnId"]);
+    case "turn/steer": return typeof value["queued"] === "boolean";
+    case "turn/interrupt": return typeof value["interruptRequested"] === "boolean";
+    case "approval/respond": case "question/respond": case "acceptance/accept": return typeof value["accepted"] === "boolean";
+    case "thread/subscribe": return snapshot(value["snapshot"]) && typeof value["resyncRequired"] === "boolean";
+    case "context/read": return count(value["node"]) && identity(value["streamId"]) && count(value["sequence"]) && ["messages", "omitted", "history"].includes(String(value["focus"]))
+      && count(value["total"]) && Array.isArray(value["entries"]) && (value["nextOffset"] === null || count(value["nextOffset"])) && record(value["components"])
+      && typeof value["used"] === "number" && typeof value["countKind"] === "string";
+    case "item/list": return Array.isArray(value["items"]) && value["items"].every(item => record(item) && count(item["node"]) && identity(item["id"]) && typeof item["type"] === "string")
+      && (value["nextCursor"] === null || record(value["nextCursor"]) && count(value["nextCursor"]["node"]) && identity(value["nextCursor"]["event"]));
+    case "item/read": return count(value["node"]) && record(value["event"]) && identity(value["event"]["id"]) && typeof value["event"]["t"] === "string";
+    default: return false;
+  }
+}
+export class ControlClient {
+  private readonly write: (line: string) => void;
+  private readonly closeTransport: (() => void) | undefined;
+  private next = 1;
+  private buffer = "";
+  private closed = false;
+  private ready = false;
+  private initializing = false;
+  private readonly pending = new Map<number, { resolve(value: unknown): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>();
+  private readonly listeners = new Set<(notice: ControlNotice) => void>();
+  constructor(write: (line: string) => void, options: { close?: () => void } = {}) { this.write = write; this.closeTransport = options.close; }
+  onNotice(listener: (notice: ControlNotice) => void, threadId?: string): () => void {
+    const actual = threadId ? (notice: ControlNotice) => { if (notice.params.threadId === threadId) listener(notice); } : listener;
+    this.listeners.add(actual); return () => { this.listeners.delete(actual); };
+  }
+  async initialize(name: string, version: string): Promise<{ threadId: string; streamId: string }> {
+    if (this.ready || this.initializing) throw Error("control client already initialized or initializing");
+    this.initializing = true;
+    try {
+      const value = await this.raw("initialize", { clientInfo: { name, version } });
+      if (!record(value) || value["protocol"] !== CONTROL_SCHEMA.protocol || !identity(value["threadId"]) || !identity(value["streamId"])) {
+        this.close("unsupported or invalid control initialize result"); throw Error("unsupported or invalid control initialize result");
+      }
+      try { this.write(JSON.stringify({ method: "initialized", params: {} }) + "\n"); }
+      catch { this.close("control handshake delivery failed"); throw Error("control handshake delivery failed"); }
+      this.ready = true; return { threadId: value["threadId"], streamId: value["streamId"] };
+    } finally { this.initializing = false; }
+  }
+  request<M extends keyof ControlApi>(method: M, params: ControlApi[M]["params"]): Promise<ControlApi[M]["result"]> {
+    if (!this.ready) return Promise.reject(Error("initialize the control client before making requests"));
+    return this.raw(method, params).then(value => {
+      if (!result(method, value)) { this.close("invalid typed control result"); throw Error("invalid typed control result"); }
+      return value as ControlApi[M]["result"];
+    });
+  }
+  respondQuestion(threadId: string, turnId: string, requestId: string, reply: QuestionReply): Promise<{ accepted: boolean }> {
+    return this.request("question/respond", { threadId, turnId, requestId, reply: JSON.stringify(reply) });
+  }
+  raw(method: string, params: Record<string, unknown>, timeoutMs = 30_000): Promise<unknown> {
+    if (this.closed) return Promise.reject(Error("control client is closed"));
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000) return Promise.reject(Error("control timeout must be 1..300000 ms"));
+    if (this.pending.size >= CONTROL_SCHEMA.limits.queuedRequests) return Promise.reject(Error("client request limit reached"));
+    const id = this.next++, line = JSON.stringify({ id, method, params }) + "\n";
+    try { parseControlRequest({ id, method, params }); } catch { return Promise.reject(Error("invalid control request parameters")); }
+    if (Buffer.byteLength(line) > CONTROL_SCHEMA.limits.frameBytes) return Promise.reject(Error("request exceeds frame limit"));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(Error("request timed out; effect is unknown, inspect before retrying")); }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try { this.write(line); } catch { clearTimeout(timer); this.pending.delete(id); reject(Error("control delivery failed; effects are unknown, inspect before retrying")); }
+    });
+  }
+  feed(text: string): void {
+    if (this.closed) return;
+    this.buffer += text;
+    for (;;) {
+      const at = this.buffer.indexOf("\n");
+      if (at < 0) { if (Buffer.byteLength(this.buffer) > CONTROL_SCHEMA.limits.frameBytes) this.close("oversized control frame"); return; }
+      const line = this.buffer.slice(0, at); this.buffer = this.buffer.slice(at + 1);
+      if (Buffer.byteLength(line) > CONTROL_SCHEMA.limits.frameBytes) { this.close("oversized control frame"); return; }
+      if (!line.trim()) continue;
+      let data: unknown;
+      try { data = JSON.parse(line); } catch { this.close("invalid control JSON"); return; }
+      if (!record(data)) { this.close("invalid control envelope"); return; }
+      if (Object.hasOwn(data, "id")) {
+        const id = data["id"], error = data["error"];
+        if (!(id === null || typeof id === "number" && Number.isSafeInteger(id) && id >= 1) || Object.keys(data).some(key => !["id", "result", "error"].includes(key))
+          || Object.hasOwn(data, "result") === Object.hasOwn(data, "error")
+          || Object.hasOwn(data, "error") && (!record(error) || !Number.isSafeInteger(error["code"]) || typeof error["message"] !== "string" || Object.keys(error).some(key => !["code", "message"].includes(key)))) {
+          this.close("invalid control response envelope"); return;
+        }
+        if (id === null) { this.close("control server rejected the connection frame"); return; }
+        const pending = this.pending.get(id); if (!pending) continue;
+        this.pending.delete(id); clearTimeout(pending.timer);
+        if (record(error)) pending.reject(Error(`Control request rejected (${String(error["code"])}): ${String(error["message"]).slice(0, 512)}`)); else pending.resolve(data["result"]);
+      } else {
+        const params = data["params"], method = data["method"];
+        if (Object.keys(data).some(key => !["method", "params"].includes(key)) || typeof method !== "string" || !CONTROL_SCHEMA.notifications.some(name => name === method)
+          || !record(params) || !identity(params["threadId"]) || !identity(params["streamId"]) || !count(params["sequence"]) || params["sequence"] === 0
+          || params["turnId"] !== undefined && !identity(params["turnId"])) { this.close("invalid control notification envelope"); return; }
+        for (const listener of this.listeners) try { listener(structuredClone(data) as ControlNotice); } catch { /* observers do not own transport */ }
+      }
+    }
+  }
+  close(reason = "control transport closed; unresolved effects are unknown"): void {
+    if (this.closed) return;
+    this.closed = true; this.ready = false; this.buffer = "";
+    for (const item of this.pending.values()) { clearTimeout(item.timer); item.reject(Error(reason)); }
+    this.pending.clear(); this.listeners.clear();
+    try { this.closeTransport?.(); } catch { /* transport failures cannot reopen this client or replay requests */ }
+  }
+}

package/src/runtime/control-connection.ts

@@ -4,6 +4,7 @@ import { selectLens, type LensFocus } from "../core/control-view.ts";
 import { assertNever } from "../core/exhaustive.ts";
 import type { SessionControl } from "./session-control.ts";
 import type { ApprovalChoice } from "./tools.ts";
+import type { SessionHub } from "./session-hub.ts";
 
 export type RpcOutput = { id: RpcId | null; result?: unknown; error?: { code: number; message: string } } | { method: string; params: unknown };
 
@@ -17,9 +18,13 @@ export class ControlConnection {
   private attached: SessionControl | undefined;
   private stop: (() => void) | undefined;
   private readonly denyOnClose: boolean;
+  private readonly hub: SessionHub | undefined;
+  private readonly subscriptions = new Map<SessionControl, () => void>();
+  private readonly questionClients = new Map<SessionControl, () => void>();
 
-  constructor(control: () => SessionControl, write: (output: RpcOutput) => void, options: { denyOnClose?: boolean } = {}) {
+  constructor(control: () => SessionControl, write: (output: RpcOutput) => void, options: { denyOnClose?: boolean; hub?: SessionHub } = {}) {
     this.control = control; this.write = write; this.denyOnClose = options.denyOnClose ?? false;
+    this.hub = options.hub;
   }
   private attach(): SessionControl {
     const control = this.control();
@@ -36,23 +41,50 @@ export class ControlConnection {
       if (typeof value === "object" && value !== null && "id" in value &&
         (typeof value.id === "string" && value.id.length <= 128 || typeof value.id === "number" && Number.isSafeInteger(value.id))) id = value.id;
       const request = parseControlRequest(value), params = request.params;
-      const control = this.attach();
+      let control = this.attach();
       if (request.method === "initialize") {
         if (this.initialized) throw new ControlProtocolError(-32000, "already initialized");
         this.initialized = true;
         this.write({ id, result: { protocol: CONTROL_SCHEMA.protocol, experimental: true, threadId: control.threadId, streamId: control.streamId,
-          capabilities: { turns: true, steering: true, approvals: true, contextLens: true, snapshotResync: true, durableEventReplay: "item/list", adaptiveExecution: false } } });
+          capabilities: { turns: true, steering: true, approvals: true, questions: true, contextLens: true, snapshotResync: true, durableEventReplay: "item/list", adaptiveExecution: false } } });
         return;
       }
       if (!this.initialized) throw new ControlProtocolError(-32000, "not initialized");
       if (request.method === "initialized") { if (this.ready) throw new ControlProtocolError(-32000, "already ready"); this.ready = true; return; }
       if (!this.ready) throw new ControlProtocolError(-32000, "send initialized before using the session");
+      if (request.method === "thread/list") {
+        if (!this.hub) throw Error("multi-session methods require app-server");
+        this.write({ id, result: await this.hub.list() }); return;
+      }
+      if (request.method === "thread/new" || request.method === "thread/resume") {
+        if (!this.hub) throw Error("multi-session methods require app-server");
+        const opened = await this.hub.open(request.method === "thread/new" ? "new" : "resume", params);
+        this.write({ id, result: await opened.snapshot() }); return;
+      }
+      if (this.hub && typeof params["threadId"] === "string") control = this.hub.get(params["threadId"]);
       if (params["threadId"] !== control.threadId) throw new ControlProtocolError(-32000, "stale or unknown threadId; initialize a new connection after changing sessions");
       let result: unknown;
       switch (request.method) {
+        case "thread/fork": {
+          if (!this.hub) throw Error("multi-session methods require app-server");
+          result = await (await this.hub.open("fork", { ...params, session: control.session.config.logDir })).snapshot(); break;
+        }
+        case "thread/close": {
+          if (!this.hub) throw Error("multi-session methods require app-server");
+          await this.hub.close(control.threadId); this.subscriptions.get(control)?.(); this.subscriptions.delete(control);
+          this.questionClients.get(control)?.(); this.questionClients.delete(control);
+          result = { closed: true }; break;
+        }
+        case "thread/mode": {
+          if (!control.configureWorkflow) throw Error("workflow changes are unavailable for this session");
+          await control.configureWorkflow(params["mode"] as "build" | "plan"); result = await control.snapshot(); break;
+        }
         case "thread/read": result = await control.snapshot(); break;
         case "thread/subscribe": {
-          this.subscribed = true;
+          if (!this.questionClients.has(control)) this.questionClients.set(control, control.attachQuestionClient());
+          if (this.hub) {
+            if (!this.subscriptions.has(control)) this.subscriptions.set(control, control.subscribe(notice => { if (!this.closed) this.write(notice); }));
+          } else this.subscribed = true;
           const snapshot = await control.snapshot();
           const after = params["after"] as { streamId: string; sequence: number } | undefined;
           result = { snapshot, resyncRequired: after !== undefined && (after.streamId !== snapshot.streamId || after.sequence !== snapshot.sequence) };
@@ -62,6 +94,7 @@ export class ControlConnection {
         case "turn/steer": control.steer(String(params["turnId"]), String(params["input"])); result = { queued: true }; break;
         case "turn/interrupt": control.interrupt(String(params["turnId"])); result = { interruptRequested: true }; break;
         case "approval/respond": control.respond(String(params["turnId"]), String(params["approvalId"]), params["choice"] as ApprovalChoice); result = { accepted: true }; break;
+        case "question/respond": control.respondQuestion(String(params["turnId"]), String(params["requestId"]), JSON.parse(String(params["reply"]))); result = { accepted: true }; break;
         case "acceptance/accept": await control.accept(String(params["requestId"]), String(params["criterionId"])); result = { accepted: true }; break;
         case "context/read": {
           const snapshot = await control.snapshot(false), all = selectLens(snapshot.context, params["focus"] as LensFocus);
@@ -96,6 +129,8 @@ export class ControlConnection {
   }
   close(): void {
     this.closed = true; this.stop?.();
+    for (const stop of this.subscriptions.values()) stop(); this.subscriptions.clear();
+    for (const stop of this.questionClients.values()) stop(); this.questionClients.clear();
     if (this.denyOnClose && this.attached) {
       this.attached.denyApprovals();
       if (this.attached.activeTurnId) this.attached.interrupt(this.attached.activeTurnId);