@visual-z/xeno 0.8.4 → 0.9.0

package/src/runtime/provider.ts

@@ -1,580 +0,0 @@
-/**
- * The Anthropic adapter, and the interface every adapter implements.
- *
- * Everything the core produces is provider-neutral by construction, so the
- * mapping lives here and nowhere else.
- *
- * `Provider` is an interface rather than a base class on purpose. Two adapters
- * share a contract, not an implementation -- there is nothing for a base class
- * to hold. Worse, a base class that constructs an Anthropic client drags the
- * SDK into every subclass, including test fakes that never make a request,
- * which is how an SDK dependency ends up in code that has nothing to do with
- * Anthropic.
- *
- * Three rules this file exists to honour, all of which would otherwise be
- * discovered as production failures:
- *
- *   THINKING BLOCKS REPLAY VERBATIM. The API rejects blocks whose content was
- *   modified, and a block whose text is empty still has to go back unchanged.
- *   The core therefore carries the raw block opaquely and this file passes it
- *   straight through -- it never reconstructs one from text.
- *
- *   THE FROZEN PREFIX CARRIES THE CACHE BREAKPOINT. System and tools render at
- *   the front of the prompt, so one explicit breakpoint on the system block
- *   gives the expensive shared part a read point that survives whatever
- *   happens later in messages. Top-level auto-caching then handles the growing
- *   tail.
- *
- *   EVERY RESPONSE IS MEASURED. Usage comes back on each call and is returned
- *   alongside the message, because a cache that silently stopped working costs
- *   money without ever raising an error.
- */
-
-import Anthropic from "@anthropic-ai/sdk";
-import type { Message, ContentBlock, FrozenPrefix } from "../core/project.ts";
-import { imageData } from "./images.ts";
-import type { AssistantBlock } from "../core/events.ts";
-import { assertNever } from "../core/exhaustive.ts";
-import { isToolStopWithoutCall } from "../core/response-recovery.ts";
-import type { UsageSample } from "./usage.ts";
-import { type Effort, type ModelSpec, CLAUDE_OPUS_5 } from "./model.ts";
-import { withRetry, retryLabel, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
-import { ConnectionReuse } from "./connection-reuse.ts";
-import { watchIdle, type IdleWatch } from "./stream-idle.ts";
-
-import { anthropicOAuthHeaders } from "./oauth.ts";
-import { XENO_VERSION } from "./version.ts";
-import type { ProviderSendOptions } from "./provider-tool-policy.ts";
-
-export interface ToolSchema {
-  name: string;
-  description: string;
-  input_schema: {
-    /** Standard JSON Schema keywords from MCP must survive the frozen declaration. */
-    [keyword: string]: unknown;
-    type: "object";
-    properties: Record<string, unknown>;
-    required: string[];
-  };
-}
-
-export interface ProviderConfig {
-  /** Which model, and everything the runtime needs to know about it. */
-  spec: ModelSpec;
-  maxTokens: number;
-  /** Controls thinking depth and spend. */
-  effort: Effort;
-  /**
-   * Summarized thinking is opt-in: the default returns thinking blocks with
-   * empty text, which to a user looks like a long pause before any output.
-   */
-  thinkingDisplay: "summarized" | "omitted";
-}
-
-export const DEFAULT_PROVIDER: ProviderConfig = {
-  spec: CLAUDE_OPUS_5,
-  maxTokens: 16_000,
-  effort: "high",
-  thinkingDisplay: "summarized",
-};
-
-/**
- * What the loop needs from a model, and the entire surface an adapter has to
- * implement. Anything wider would be an Anthropic concept leaking into the
- * contract; anything narrower could not report usage, which the whole design
- * rests on measuring.
- */
-/**
- * A display increment. Adapters emit these through `onDelta`; the loop
- * turns them into UI events. They never become log events -- a turn that
- * landed N deltas in the log would project as N assistant messages and
- * break prefix stability (P7).
- *
- * Shared by both adapters so the loop never sees an Anthropic or OpenAI
- * wire name. Discard is the same channel: a retry or a refusal has to
- * wipe what the user already saw, and inventing a second callback would
- * let one path forget.
- */
-export type StreamDelta =
-  | { kind: "text"; text: string }
-  | { kind: "thinking"; text: string }
-  | { kind: "tool"; id: string; name: string; arguments: string }
-  // `max` is the policy's budget and `reason` a few words from retryLabel;
-  // optional so a view written against the older shape still renders.
-  | { kind: "retry"; attempt: number; delayMs: number; max?: number; reason?: string }
-  | { kind: "discard" };
-
-export type OnDelta = (delta: StreamDelta) => void;
-
-export interface Provider {
-  readonly config: ProviderConfig;
-  send(
-    frozen: FrozenPrefix,
-    messages: readonly Message[],
-    node: number,
-    signal?: AbortSignal,
-    onDelta?: OnDelta,
-    options?: ProviderSendOptions,
-  ): Promise<Turn>;
-}
-
-/**
- * The SDK methods this adapter actually calls.
- *
- * Structural rather than `Anthropic` so a test can inject a fake without
- * constructing a client -- that would pull credentials and the SDK retry
- * loop, which is the opposite of what a fake is for. Tests cannot import
- * the SDK package (the boundary checker forbids package imports outside
- * runtime/apps).
- */
-/** The complete-message shape, also what a non-streaming test fake returns. */
-export interface AnthropicMessage {
-  stop_reason: string | null;
-  stop_details?: { category?: string | null; explanation?: string | null } | null;
-  content: Anthropic.ContentBlock[];
-  usage: {
-    input_tokens: number;
-    output_tokens: number;
-    cache_creation_input_tokens?: number | null;
-    cache_read_input_tokens?: number | null;
-  };
-}
-
-export interface AnthropicTransport {
-  messages: {
-    create(
-      params: Anthropic.MessageCreateParamsNonStreaming | Anthropic.MessageCreateParamsStreaming,
-      options?: { signal?: AbortSignal | null },
-    ): Promise<AnthropicMessage | AsyncIterable<unknown>>;
-  };
-}
-
-export interface Turn {
-  blocks: AssistantBlock[];
-  stopReason: string | null;
-  usage: UsageSample;
-}
-
-/** D11: a rejected response can still prove usage; arbitrary errors cannot prove a billable receipt. */
-export class FailedResponseError extends Error {
-  readonly usage: UsageSample | undefined;
-
-  constructor(message: string, usage?: UsageSample) {
-    super(message);
-    this.name = "FailedResponseError";
-    this.usage = usage === undefined ? undefined : { ...usage };
-  }
-}
-
-/**
- * A 200 response that contradicts itself, such as a tool stop with no tool
- * call. retry.ts treats it like a transient stream failure: a fresh sample is
- * the remedy, and exhausting retries must surface as a provider error rather
- * than reach the loop as a silent final answer. The output token count tells
- * "generated but lost in transit" apart from "nothing generated".
- */
-export class MalformedResponseError extends FailedResponseError {
-  constructor(detail: string, usage?: UsageSample) {
-    super(`malformed provider response: ${detail}${usage ? ` (${usage.output_tokens} output tokens)` : ""}`, usage);
-    this.name = "MalformedResponseError";
-  }
-}
-
-/** Every adapter returns through this, so no dialect can hand the loop a contradictory turn. */
-export function coherentTurn(turn: Turn, usageKnown = true): Turn {
-  if (isToolStopWithoutCall(turn.stopReason, turn.blocks))
-    throw new MalformedResponseError(`stop_reason ${JSON.stringify(turn.stopReason)} without a tool call`, usageKnown ? turn.usage : undefined);
-  return turn;
-}
-
-/** Thrown for a refusal, which arrives as HTTP 200 rather than an error. */
-export class RefusalError extends FailedResponseError {
-  readonly category: string | null;
-  readonly explanation: string | null;
-
-  constructor(category: string | null, explanation: string | null, usage?: UsageSample) {
-    super(`model refused the request${category ? ` (${category})` : ""}`, usage);
-    this.name = "RefusalError";
-    this.category = category;
-    this.explanation = explanation;
-  }
-}
-
-function buildAnthropicClient(
-  apiKey: string | undefined,
-  options: { fetch?: typeof fetch; oauth?: boolean; baseUrl?: string },
-): AnthropicTransport {
-  // D18: the User-Agent, not SDK headers, identifies xeno on the wire. Left alone
-  // the SDK sends `Anthropic/JS <version>`, which model gateways fold into "custom
-  // client" attribution; provider-request.ts already stamps xeno's UA on the Pi
-  // path. Constructor defaultHeaders merge after the SDK's built-in UA, so this
-  // entry wins without touching per-request headers.
-  const identity = { "User-Agent": `xeno/${XENO_VERSION}` };
-  if (options.oauth === true && apiKey) {
-    // authToken is Bearer. Passing apiKey here would send x-api-key, which
-    // an OAuth token is not accepted as.
-    return new Anthropic({
-      maxRetries: 0,
-      ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
-      authToken: apiKey,
-      defaultHeaders: { ...anthropicOAuthHeaders(), ...identity },
-      ...(options.fetch ? { fetch: options.fetch } : {}),
-    });
-  }
-  return new Anthropic({
-    maxRetries: 0,
-    ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
-    ...(apiKey ? { apiKey } : {}),
-    defaultHeaders: identity,
-    ...(options.fetch ? { fetch: options.fetch } : {}),
-  });
-}
-
-export class AnthropicProvider implements Provider {
-  readonly config: ProviderConfig;
-  private readonly client: AnthropicTransport;
-  private readonly connections = new ConnectionReuse();
-  private readonly streamIdleMs: number | undefined;
-  private readonly retry: RetryPolicy;
-  private readonly onRetry: ((attempt: number, delayMs: number, error: unknown) => void) | undefined;
-
-  /**
-   * `apiKey` comes from the resolution chain when there is one. Omitting it
-   * falls back to the SDK's own lookup (environment, `ant auth login`
-   * profile), which is what makes a machine already set up for Claude work
-   * with no configuration at all.
-   */
-  constructor(
-    config: ProviderConfig = DEFAULT_PROVIDER,
-    apiKey?: string,
-    options: {
-      client?: AnthropicTransport;
-      retry?: RetryPolicy;
-      onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
-      fetch?: typeof fetch;
-      /** OAuth access token: Bearer + oauth-2025-04-20, never x-api-key (D18). */
-      oauth?: boolean;
-      /** Silence after which one attempt is abandoned; tests shorten it (stream-idle.ts). */
-      streamIdleMs?: number;
-    } = {},
-  ) {
-    this.config = config;
-    // maxRetries: 0 because this adapter retries. Leaving the SDK's own on
-    // would multiply the two -- four attempts becoming sixteen -- and the
-    // outer layer could neither see how long the inner one slept nor count
-    // it, so the usage report would quietly stop adding up. The SDK timer
-    // also ignores AbortSignal, so an outer wait is the only one Escape
-    // can actually cancel.
-    this.client = options.client ?? buildAnthropicClient(apiKey, { ...options, fetch: this.connections.wrap(options.fetch ?? fetch),
-      ...(config.spec.baseUrl ? { baseUrl: config.spec.baseUrl } : {}) });
-    this.retry = options.retry ?? DEFAULT_RETRY;
-    this.onRetry = options.onRetry;
-    this.streamIdleMs = options.streamIdleMs;
-  }
-
-  send(
-    frozen: FrozenPrefix,
-    messages: readonly Message[],
-    node: number,
-    signal?: AbortSignal,
-    onDelta?: OnDelta,
-    options?: ProviderSendOptions,
-  ): Promise<Turn> {
-    return withRetry(
-      () => watchIdle(signal, this.streamIdleMs, idle => this.attempt(frozen, messages, node, idle, onDelta, options)).catch((error: unknown) => { this.connections.note(error); throw error; }),
-      this.retry,
-      undefined,
-      (attempt, delayMs, error) => {
-        // The next attempt starts from empty. Without this the UI concatenates
-        // two openings of the same sentence and has no sign a retry happened.
-        onDelta?.({ kind: "discard" });
-        onDelta?.({ kind: "retry", attempt, delayMs, max: this.retry.maxRetries, reason: retryLabel(error) });
-        this.onRetry?.(attempt, delayMs, error);
-      },
-      signal,
-    );
-  }
-
-  private async attempt(
-    frozen: FrozenPrefix,
-    messages: readonly Message[],
-    node: number,
-    idle: IdleWatch,
-    onDelta?: OnDelta,
-    options?: ProviderSendOptions,
-  ): Promise<Turn> {
-    const started = Date.now();
-
-    const response = await this.client.messages.create(
-      {
-        model: this.config.spec.id,
-        max_tokens: this.config.maxTokens,
-        stream: true,
-        // One explicit breakpoint on the frozen prefix. It renders before
-        // messages, so this read point holds regardless of how the tail grows.
-        system: [
-          {
-            type: "text",
-            text: frozen.system,
-            cache_control: { type: "ephemeral" },
-          },
-        ],
-        // Auto-caching walks the breakpoint forward over the growing tail.
-        cache_control: { type: "ephemeral" },
-        tools: frozen.tools as Anthropic.Tool[],
-        ...(options?.toolUse === "disabled" ? { tool_choice: { type: "none" as const } } : {}),
-        // Only a reasoning model understands these. An older Claude, or an
-        // Anthropic-compatible endpoint serving some other model, answers
-        // them with a 400 or silently ignores them.
-        ...(this.config.spec.reasoning
-          ? this.config.effort === "off" ? { thinking: { type: "disabled" as const } }
-            : { thinking: { type: "adaptive" as const, display: this.config.thinkingDisplay },
-              output_config: { effort: anthropicEffort(this.config) } }
-          : {}),
-        messages: messages.map(toWireMessage),
-      },
-      { signal: idle.signal },
-    );
-
-    const assembled = isAsyncIterable(response)
-      ? await consumeAnthropicStream(idle.events(response), onDelta)
-      : {
-          blocks: response.content.map(fromWireBlock),
-          stopReason: response.stop_reason,
-          stopDetails: response.stop_details ?? null,
-          usageKnown: true,
-          usage: {
-            input_tokens: response.usage.input_tokens,
-            output_tokens: response.usage.output_tokens,
-            cache_creation_input_tokens: response.usage.cache_creation_input_tokens ?? 0,
-            cache_read_input_tokens: response.usage.cache_read_input_tokens ?? 0,
-          },
-        };
-    const usage = { ...assembled.usage, node, ms: Date.now() - started };
-
-    // A refusal is HTTP 200 with stop_reason "refusal", so content must not be
-    // trusted after it. Anything already painted has to go with it.
-    if (assembled.stopReason === "refusal") {
-      onDelta?.({ kind: "discard" });
-      const details = assembled.stopDetails;
-      throw new RefusalError(details?.category ?? null, details?.explanation ?? null, assembled.usageKnown ? usage : undefined);
-    }
-
-    return coherentTurn({
-      blocks: assembled.blocks,
-      stopReason: assembled.stopReason,
-      usage,
-    }, assembled.usageKnown);
-  }
-}
-
-/** Pi maps minimal to low for adaptive thinking; off is a thinking switch, never an effort string. */
-function anthropicEffort(config: ProviderConfig): "low" | "medium" | "high" | "xhigh" | "max" {
-  const level = config.spec.thinkingLevelMap?.[config.effort] ?? config.effort;
-  return level === "minimal" || level === "off" ? "low" :
-    level === "low" || level === "medium" || level === "high" || level === "xhigh" || level === "max" ? level : "high";
-}
-
-function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
-  return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
-}
-
-interface AssembledTurn {
-  blocks: AssistantBlock[];
-  stopReason: string | null;
-  stopDetails: { category?: string | null; explanation?: string | null } | null;
-  /** Provider receipt presence distinguishes a measured zero from absent usage (D11). */
-  usageKnown: boolean;
-  usage: {
-    input_tokens: number;
-    output_tokens: number;
-    cache_creation_input_tokens: number;
-    cache_read_input_tokens: number;
-  };
-}
-
-interface UsageFields {
-  input_tokens?: number | null;
-  output_tokens?: number | null;
-  cache_creation_input_tokens?: number | null;
-  cache_read_input_tokens?: number | null;
-}
-
-function takeUsage(
-  into: AssembledTurn["usage"],
-  raw: UsageFields | undefined,
-): void {
-  if (raw === undefined) return;
-  if (raw.input_tokens != null) into.input_tokens = raw.input_tokens;
-  if (raw.output_tokens != null) into.output_tokens = raw.output_tokens;
-  if (raw.cache_creation_input_tokens != null) {
-    into.cache_creation_input_tokens = raw.cache_creation_input_tokens;
-  }
-  if (raw.cache_read_input_tokens != null) {
-    into.cache_read_input_tokens = raw.cache_read_input_tokens;
-  }
-}
-
-function parseToolInput(raw: string): unknown {
-  if (raw.length === 0) return {};
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return { __unparsed_arguments: raw };
-  }
-}
-
-/**
- * Walks the SDK stream (or a test fake of the same events) into a Turn.
- *
- * Usage is the sum of message_start (input / cache) and message_delta
- * (output, and any field a proxy omitted at start). Deltas go to onDelta
- * as they arrive so the loop can paint before this function returns.
- */
-async function consumeAnthropicStream(
-  stream: AsyncIterable<unknown>,
-  onDelta: OnDelta | undefined,
-): Promise<AssembledTurn> {
-  const content: Anthropic.ContentBlock[] = [];
-  const jsonBuf = new Map<number, string>();
-  const assembled: AssembledTurn = {
-    blocks: [],
-    stopReason: null,
-    stopDetails: null,
-    usageKnown: false,
-    usage: {
-      input_tokens: 0,
-      output_tokens: 0,
-      cache_creation_input_tokens: 0,
-      cache_read_input_tokens: 0,
-    },
-  };
-
-  for await (const raw of stream) {
-    const event = raw as {
-      type?: string;
-      index?: number;
-      message?: { usage?: UsageFields };
-      content_block?: Anthropic.ContentBlock;
-      delta?: {
-        type?: string;
-        text?: string;
-        thinking?: string;
-        signature?: string;
-        partial_json?: string;
-        stop_reason?: string | null;
-        stop_details?: { category?: string | null; explanation?: string | null } | null;
-      };
-      usage?: UsageFields;
-    };
-
-    switch (event.type) {
-      case "message_start":
-        takeUsage(assembled.usage, event.message?.usage);
-        if (event.message?.usage !== undefined) assembled.usageKnown = true;
-        break;
-      case "content_block_start": {
-        const index = event.index ?? content.length;
-        if (event.content_block !== undefined) {
-          content[index] = { ...event.content_block } as Anthropic.ContentBlock;
-          if (event.content_block.type === "tool_use") {
-            jsonBuf.set(index, "");
-            onDelta?.({ kind: "tool", id: event.content_block.id, name: event.content_block.name, arguments: "" });
-          }
-        }
-        break;
-      }
-      case "content_block_delta": {
-        const index = event.index ?? 0;
-        const delta = event.delta;
-        const block = content[index];
-        if (delta === undefined || block === undefined) break;
-        if (delta.type === "text_delta" && delta.text) {
-          if (block.type === "text") block.text += delta.text;
-          onDelta?.({ kind: "text", text: delta.text });
-        } else if (delta.type === "thinking_delta" && delta.thinking) {
-          if (block.type === "thinking") block.thinking += delta.thinking;
-          onDelta?.({ kind: "thinking", text: delta.thinking });
-        } else if (delta.type === "signature_delta" && delta.signature && block.type === "thinking") {
-          block.signature = (block.signature ?? "") + delta.signature;
-        } else if (delta.type === "input_json_delta" && delta.partial_json) {
-          jsonBuf.set(index, (jsonBuf.get(index) ?? "") + delta.partial_json);
-          if (block.type === "tool_use") onDelta?.({ kind: "tool", id: block.id, name: block.name, arguments: jsonBuf.get(index)! });
-        }
-        break;
-      }
-      case "content_block_stop": {
-        const index = event.index ?? 0;
-        const block = content[index];
-        if (block?.type === "tool_use") {
-          block.input = parseToolInput(jsonBuf.get(index) ?? "");
-        }
-        break;
-      }
-      case "message_delta": {
-        if (event.delta?.stop_reason) assembled.stopReason = event.delta.stop_reason;
-        if (event.delta?.stop_details !== undefined) {
-          assembled.stopDetails = event.delta.stop_details;
-        }
-        takeUsage(assembled.usage, event.usage);
-        if (event.usage !== undefined) assembled.usageKnown = true;
-        break;
-      }
-      default:
-        break;
-    }
-  }
-
-  assembled.blocks = content.filter((b) => b !== undefined).map(fromWireBlock);
-  return assembled;
-}
-
-function toWireMessage(m: Message): Anthropic.MessageParam {
-  return {
-    role: m.role,
-    // Anthropic requires all parallel tool results before any text or image in the user message.
-    content: [...m.content.filter(b => b.type === "tool_result"), ...m.content.filter(b => b.type !== "tool_result")].map(toWireBlock) as Anthropic.ContentBlockParam[],
-  };
-}
-
-function toWireBlock(b: ContentBlock): unknown {
-  switch (b.type) {
-    case "image": return { type: "image", source: { type: "base64", media_type: b.image.mimeType, data: imageData(b) } };
-    case "text":
-      return { type: "text", text: b.text };
-    case "thinking":
-      // Verbatim. Reconstructing the block would drop its signature and the
-      // next request would be rejected.
-      return b.raw;
-    case "tool_use":
-      return { type: "tool_use", id: b.id, name: b.name, input: b.input };
-    case "tool_result":
-      return {
-        type: "tool_result",
-        tool_use_id: b.tool_use_id,
-        content: b.content,
-        ...(b.is_error ? { is_error: true } : {}),
-      };
-    default:
-      return assertNever(b, "toWireBlock");
-  }
-}
-
-function fromWireBlock(b: Anthropic.ContentBlock): AssistantBlock {
-  switch (b.type) {
-    case "text":
-      return { type: "text", text: b.text };
-    case "thinking":
-      // `raw` is what goes back to the API; `text` is only for display.
-      return { type: "thinking", text: b.thinking, raw: b };
-    case "redacted_thinking":
-      return { type: "thinking", text: "", raw: b };
-    case "tool_use":
-      return { type: "tool_use", call_id: b.id, name: b.name, input: b.input };
-    default:
-      // Server-tool blocks land here. They are kept verbatim as thinking-like
-      // opaque content so a replay stays byte-identical, rather than being
-      // dropped and breaking the turn.
-      return { type: "thinking", text: "", raw: b };
-  }
-}

package/src/runtime/question-tool.ts

@@ -1,62 +0,0 @@
-/** R13: UI and protocol clients share one active-turn question adapter. */
-import { parseQuestions, questionRequest, validateQuestionReply, MAX_QUESTIONS, MAX_QUESTION_CHOICES,
-  type QuestionRequest, type QuestionReply } from "../core/question.ts";
-import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
-import { executionOutcome } from "../core/outcome.ts";
-import type { JsonValue, ToolDiagnostic } from "../core/tool-contract.ts";
-import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
-
-export type QuestionAdapter = (request: QuestionRequest, signal: AbortSignal) => Promise<unknown | undefined>;
-export interface QuestionSlot {
-  /** The Session/app owner changes this at user-turn boundaries, never model input. */
-  activeTurn?: string;
-  current?: QuestionAdapter;
-}
-function failure(code: ToolDiagnostic["code"], message: string): ToolResult {
-  return { ok: false, content: message, diagnostic: failureDiagnostic(code, message, NOT_STARTED),
-    outcome: executionOutcome(code === "cancelled" ? "cancelled" : "tool_failed") };
-}
-function plainReply(reply: QuestionReply): JsonValue {
-  return { request_id: reply.request_id, turn_id: reply.turn_id,
-    answers: reply.answers.map(answer => ({ id: answer.id, choices: [...answer.choices], ...(answer.text !== undefined ? { text: answer.text } : {}) })) };
-}
-async function ask(slot: QuestionSlot, ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  let questions;
-  try { questions = parseQuestions(input); }
-  catch (error) { return failure("invalid_input", error instanceof Error ? error.message : "Invalid question"); }
-  const turn = slot.activeTurn, call = ctx.callId, adapter = slot.current;
-  if (!turn || !call) return failure("permission_denied", "question requires an active turn and tool invocation");
-  if (!adapter) return failure("environment_missing", "question requires an interactive terminal or a connected client that can answer questions");
-  const signal = ctx.signal ?? new AbortController().signal;
-  if (signal.aborted) return failure("cancelled", "Question cancelled");
-  const request = questionRequest(turn, call, questions);
-  let stop = () => {};
-  const cancelled = new Promise<undefined>(resolve => { stop = () => resolve(undefined); signal.addEventListener("abort", stop, { once: true }); });
-  try {
-    // Late adapter rejection is observed by race; an adapter ignoring its
-    // signal cannot keep the original tool exchange unpaired (D5).
-    const answer = await Promise.race([Promise.resolve().then(() => adapter(structuredClone(request), signal)), cancelled]);
-    if (signal.aborted || answer === undefined || slot.activeTurn !== turn) return failure("cancelled", "Question cancelled or its turn is no longer active");
-    let reply;
-    try { reply = validateQuestionReply(request, answer); }
-    catch { return failure("invalid_input", "Question client returned an invalid answer or stale invocation identity"); }
-    const data = plainReply(reply);
-    return { ok: true, content: JSON.stringify(data), data, outcome: executionOutcome("tool_completed") };
-  } catch { return failure("execution_failed", "Question client failed before returning a validated answer"); }
-  finally { signal.removeEventListener("abort", stop); }
-}
-
-export function createQuestionTool(slot: QuestionSlot): ToolDefinition {
-  return { name: "question", access: "state", execution: "exclusive", branch: "none",
-    description: "Ask 1..3 concise questions for missing requirements or material decisions; await the user's answer in this turn. Use stable question and option ids. Set multiple=true for multiple choices; custom text is enabled by default. An absent/cancelled answer is not approval. This tool does not approve tool execution or change workflow mode.",
-    input_schema: { type: "object", required: ["questions"], properties: {
-      questions: { type: "array", minItems: 1, maxItems: MAX_QUESTIONS, items: { type: "object", additionalProperties: false,
-        required: ["id", "header", "question"], properties: {
-          id: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,63}$" }, header: { type: "string", minLength: 1, maxLength: 40 },
-          question: { type: "string", minLength: 1, maxLength: 2000 }, multiple: { type: "boolean" }, custom: { type: "boolean" },
-          options: { type: "array", maxItems: MAX_QUESTION_CHOICES, items: { type: "object", additionalProperties: false,
-            required: ["id", "label"], properties: { id: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,63}$" },
-              label: { type: "string", minLength: 1, maxLength: 120 }, description: { type: "string", minLength: 1, maxLength: 600 } } } },
-        } } },
-    } }, run: (ctx, input) => ask(slot, ctx, input) };
-}