@visual-z/xeno 0.4.0 → 0.6.0

package/src/runtime/mcp-oauth.ts

@@ -0,0 +1,168 @@
+/** OAuth is a user-owned repair operation; the SDK owns discovery, PKCE and issuer/resource binding. */
+import { randomUUID } from "node:crypto";
+import { auth, checkResourceAllowed, resourceUrlFromServerUrl, StreamableHTTPClientTransport,
+  type OAuthClientProvider, type OAuthClientInformationContext, type StoredOAuthClientInformation, type StoredOAuthTokens,
+  type OAuthClientMetadata, type OAuthDiscoveryState, type FetchLike } from "@modelcontextprotocol/client";
+import type { McpOAuthConfig } from "../core/mcp-config.ts";
+import { isJsonValue } from "../core/tool-contract.ts";
+import type { McpCredentials, McpCredentialsStore } from "../store/mcp-credentials.ts";
+import { boundedResponseBytes } from "./web-http.ts";
+
+export class McpAuthRequired extends Error { constructor() { super("MCP authentication requires an explicit login"); this.name = "McpAuthRequired"; } }
+/** The SDK warns with OAuth error_description; normalize peer errors before they can reach its console path. */
+export function safeOAuthFetch(fetcher: FetchLike): FetchLike {
+  return async (input, init) => {
+    let response: Response;
+    try { response = await fetcher(input, init); } catch { throw new McpAuthRequired(); }
+    if (response.ok) return response;
+    let code = "server_error";
+    try {
+      const value: unknown = JSON.parse(new TextDecoder().decode(await boundedResponseBytes(response, 16 * 1024)));
+      if (value && typeof value === "object" && "error" in value && typeof value.error === "string"
+        && ["invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope", "access_denied", "server_error", "temporarily_unavailable"].includes(value.error)) code = value.error;
+    } catch { /* Unknown peer bodies contribute status only, never diagnostics containing secrets. */ }
+    return Response.json({ error: code, error_description: "OAuth request rejected" }, { status: response.status, headers: { "content-type": "application/json" } });
+  };
+}
+function savedClient(value: unknown): value is StoredOAuthClientInformation {
+  return !!value && typeof value === "object" && "client_id" in value && typeof value.client_id === "string";
+}
+function savedTokens(value: unknown): value is StoredOAuthTokens {
+  return !!value && typeof value === "object" && "access_token" in value && typeof value.access_token === "string"
+    && "token_type" in value && typeof value.token_type === "string";
+}
+/** A per-resource provider; discovery/verifier/state exist only during this owned process's login. */
+export class McpOAuthProvider implements OAuthClientProvider {
+  private readonly url: string;
+  private readonly config: McpOAuthConfig;
+  private readonly store: McpCredentialsStore;
+  private readonly env: Readonly<Record<string, string | undefined>>;
+  private credentials: McpCredentials;
+  private verifier: string | undefined;
+  private discovery: OAuthDiscoveryState | undefined;
+  private expectedState: string | undefined;
+  private redirect: ((url: URL) => void | Promise<void>) | undefined;
+  private refreshing: Promise<void> | undefined;
+  private resourceMetadataUrl: URL | undefined;
+  private challengedScope: string | undefined;
+  private constructor(url: string, config: McpOAuthConfig,
+    store: McpCredentialsStore, env: Readonly<Record<string, string | undefined>>, credentials?: McpCredentials) {
+    this.url = url; this.config = config; this.store = store; this.env = env;
+    this.credentials = credentials ?? { version: 1, serverUrl: url, redirectUrl: config.redirectUrl ?? "http://127.0.0.1:0/callback",
+      clients: {}, tokens: {}, expiresAt: {}, activeIssuer: null, ...(config.clientId ? { clientIdentity: config.clientId } : {}) };
+    if (config.redirectUrl) this.credentials.redirectUrl = config.redirectUrl;
+  }
+  static async create(url: string, config: McpOAuthConfig, store: McpCredentialsStore, env: Readonly<Record<string, string | undefined>>) {
+    return new McpOAuthProvider(url, config, store, env, await store.read(url, config.clientId));
+  }
+  get redirectUrl() { return this.credentials.redirectUrl; }
+  get clientMetadata(): OAuthClientMetadata {
+    return { client_name: "xeno", application_type: "native", redirect_uris: [this.redirectUrl], response_types: ["code"],
+      grant_types: ["authorization_code", "refresh_token"], token_endpoint_auth_method: this.config.clientSecretEnv ? "client_secret_basic" : "none",
+      ...(this.config.scope ? { scope: this.config.scope } : {}) };
+  }
+  clientInformation(ctx?: OAuthClientInformationContext): StoredOAuthClientInformation | undefined {
+    if (this.config.clientId) {
+      const secret = this.config.clientSecretEnv ? this.env[this.config.clientSecretEnv] : undefined;
+      if (this.config.clientSecretEnv && !secret) throw new McpAuthRequired();
+      return { client_id: this.config.clientId, ...(secret ? { client_secret: secret } : {}), ...(ctx ? { issuer: ctx.issuer } : {}) };
+    }
+    const value = ctx ? this.credentials.clients[ctx.issuer] : undefined;
+    return savedClient(value) ? value : undefined;
+  }
+  async saveClientInformation(info: StoredOAuthClientInformation, ctx?: OAuthClientInformationContext) {
+    const issuer = ctx?.issuer ?? info.issuer;
+    if (!issuer || !isJsonValue(info)) throw new McpAuthRequired();
+    this.credentials.clients[issuer] = info;
+    await this.store.write(this.credentials);
+  }
+  tokens(ctx?: OAuthClientInformationContext): StoredOAuthTokens | undefined {
+    const issuer = ctx?.issuer ?? this.credentials.activeIssuer, value = issuer ? this.credentials.tokens[issuer] : undefined;
+    return savedTokens(value) ? value : undefined;
+  }
+  async saveTokens(tokens: StoredOAuthTokens, ctx?: OAuthClientInformationContext) {
+    const issuer = ctx?.issuer ?? tokens.issuer;
+    if (!issuer || !isJsonValue(tokens)) throw new McpAuthRequired();
+    this.credentials.tokens[issuer] = tokens; this.credentials.activeIssuer = issuer;
+    if (tokens.expires_in !== undefined) this.credentials.expiresAt[issuer] = Date.now() + tokens.expires_in * 1_000;
+    else delete this.credentials.expiresAt[issuer];
+    await this.store.write(this.credentials);
+  }
+  state() { this.expectedState = randomUUID(); return this.expectedState; }
+  redirectToAuthorization(url: URL) {
+    if (!this.redirect) throw new McpAuthRequired();
+    return this.redirect(url);
+  }
+  saveCodeVerifier(verifier: string) { this.verifier = verifier; }
+  codeVerifier() { if (!this.verifier) throw new McpAuthRequired(); return this.verifier; }
+  saveDiscoveryState(state: OAuthDiscoveryState) { this.discovery = state; }
+  discoveryState() { return this.discovery; }
+  setChallenge(resourceMetadataUrl: URL | undefined, scope: string | undefined) {
+    this.resourceMetadataUrl = resourceMetadataUrl; this.challengedScope = scope; this.discovery = undefined;
+  }
+  private authOptions(fetcher: FetchLike) {
+    const scope = this.config.scope ?? this.challengedScope;
+    return { serverUrl: this.url, fetchFn: safeOAuthFetch(fetcher), ...(this.resourceMetadataUrl ? { resourceMetadataUrl: this.resourceMetadataUrl } : {}), ...(scope ? { scope } : {}) };
+  }
+  async validateResourceURL(serverUrl: string | URL, resource?: string) {
+    const expected = resourceUrlFromServerUrl(serverUrl);
+    if (resource && !checkResourceAllowed({ requestedResource: expected, configuredResource: resource })) throw new McpAuthRequired();
+    return expected;
+  }
+  async invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery") {
+    if (scope === "all" || scope === "client") this.credentials.clients = {};
+    if (scope === "all" || scope === "tokens") { this.credentials.tokens = {}; this.credentials.expiresAt = {}; this.credentials.activeIssuer = null; }
+    if (scope === "all" || scope === "verifier") this.verifier = undefined;
+    if (scope === "all" || scope === "discovery") this.discovery = undefined;
+    if (scope === "all") await this.store.remove(this.url, this.config.clientId); else await this.store.write(this.credentials);
+  }
+  async token(fetcher: FetchLike): Promise<string | undefined> {
+    const issuer = this.credentials.activeIssuer, expiresAt = issuer ? this.credentials.expiresAt[issuer] : undefined;
+    // Assumed 30s skew prevents sending a token that expires while the new request is in flight.
+    if (expiresAt !== undefined && expiresAt <= Date.now() + 30_000) {
+      if (!this.refreshing) {
+        this.refreshing = (async () => {
+          if (!this.tokens()?.refresh_token) { await this.invalidateCredentials("tokens"); throw new McpAuthRequired(); }
+          try { if (await auth(this, this.authOptions(fetcher)) !== "AUTHORIZED") throw new McpAuthRequired(); }
+          catch { await this.invalidateCredentials("tokens"); throw new McpAuthRequired(); }
+        })().finally(() => { this.refreshing = undefined; });
+      }
+      await this.refreshing;
+    }
+    return this.tokens()?.access_token;
+  }
+  async login(onAuthorizationUrl: (url: URL) => void | Promise<void>, fetcher: FetchLike, signal: AbortSignal): Promise<void> {
+    if (this.redirect) throw new McpAuthRequired();
+    signal.throwIfAborted();
+    const callback = new URL(this.redirectUrl);
+    let resolveCallback: (value: URLSearchParams) => void = () => {}, rejectCallback: (error: Error) => void = () => {};
+    const received = new Promise<URLSearchParams>((resolve, reject) => { resolveCallback = resolve; rejectCallback = reject; });
+    // Reject handlers are installed before starting auth; cancellation never leaves an unhandled callback promise.
+    void received.catch(() => {});
+    const server = Bun.serve({ hostname: "127.0.0.1", port: Number(callback.port), fetch: request => {
+      const current = new URL(request.url);
+      if (current.pathname !== callback.pathname) return new Response("Not found", { status: 404 });
+      if (request.method !== "GET" || !this.expectedState || current.searchParams.get("state") !== this.expectedState) return new Response("Invalid authorization state", { status: 400 });
+      if (current.searchParams.has("error") || !current.searchParams.get("code")) {
+        rejectCallback(new McpAuthRequired()); return new Response("Authorization was not completed", { status: 400 });
+      }
+      resolveCallback(current.searchParams); return new Response("Authorization received. Return to xeno.", { headers: { "content-type": "text/plain" } });
+    } });
+    const selected = new URL(callback.pathname, server.url).href;
+    if (selected !== this.credentials.redirectUrl && !this.config.clientId) this.credentials.clients = {};
+    this.credentials.redirectUrl = selected; this.redirect = onAuthorizationUrl;
+    const onAbort = () => rejectCallback(new McpAuthRequired());
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      const safeFetch = safeOAuthFetch(fetcher);
+      const result = await auth(this, this.authOptions(fetcher));
+      if (result === "AUTHORIZED") return;
+      const params = await received;
+      const transport = new StreamableHTTPClientTransport(new URL(this.url), { authProvider: this, fetch: safeFetch, onInsufficientScope: "throw" });
+      try { await transport.finishAuth(params); } finally { await transport.close(); }
+    } finally {
+      signal.removeEventListener("abort", onAbort); server.stop(true); this.redirect = undefined;
+      this.expectedState = undefined; this.verifier = undefined; this.discovery = undefined;
+    }
+  }
+}

package/src/runtime/mcp-schema.ts

@@ -0,0 +1,51 @@
+/** MCP 2025-11-25 defaults to 2020-12; validation never repairs the frozen invocation. */
+import { Ajv, type ValidateFunction } from "ajv";
+import { Ajv2019 } from "ajv/dist/2019.js";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { addFormats } from "@modelcontextprotocol/client/validators/ajv";
+import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator } from "@modelcontextprotocol/client";
+import { NOT_STARTED, ToolFault } from "../core/tool-failure.ts";
+
+export class McpSchemaError extends Error {
+  constructor() { super("MCP schema is invalid or uses an unsupported dialect, reference, keyword or format; repair the server schema before reloading."); this.name = "McpSchemaError"; }
+}
+
+/** The official client's format package is bundled in its public validator entry; no extra dependency. */
+export class McpSchemas implements jsonSchemaValidator {
+  private readonly compiled = new Map<string, ValidateFunction>();
+  validator(schema: unknown): ValidateFunction {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) throw new McpSchemaError();
+    const key = JSON.stringify(schema), cached = this.compiled.get(key);
+    if (cached) return cached;
+    try {
+      const dialect = (schema as Record<string, unknown>)["$schema"];
+      const options = { strictSchema: true, strictNumbers: true, strictTypes: false, strictTuples: false, strictRequired: false,
+        validateFormats: true, coerceTypes: false, useDefaults: false, removeAdditional: false, allErrors: false, logger: false as const };
+      // Strict schema rejects unknown semantics, while strict style checks are disabled:
+      // valid JSON Schema need not spell out every tuple bound or repeat inherited types.
+      const ajv = dialect === undefined || dialect === "https://json-schema.org/draft/2020-12/schema" ? new Ajv2020(options)
+        : dialect === "https://json-schema.org/draft/2019-09/schema" ? new Ajv2019(options)
+        : dialect === "http://json-schema.org/draft-07/schema#" || dialect === "http://json-schema.org/draft-07/schema" ? new Ajv(options)
+        : undefined;
+      if (!ajv) throw new McpSchemaError();
+      addFormats(ajv);
+      // MCP's header annotation is interpreted by the official transport, not a validation constraint.
+      ajv.addKeyword({ keyword: "x-mcp-header", schemaType: "string", valid: true });
+      // Ajv validates this entire JSON schema; the assertion only bridges the SDK's wider wire type.
+      const validate = ajv.compile(structuredClone(schema) as JsonSchemaType);
+      this.compiled.set(key, validate); return validate;
+    } catch { throw new McpSchemaError(); }
+  }
+  getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
+    const validate = this.validator(schema);
+    return input => validate(input) ? { valid: true, data: input as T, errorMessage: undefined }
+      : { valid: false, data: undefined, errorMessage: "MCP structured output failed the advertised schema." };
+  }
+  prepare(schema: unknown): (input: unknown) => unknown {
+    const validate = this.validator(schema);
+    return input => {
+      if (!validate(input)) throw new ToolFault("invalid_input", "MCP arguments do not satisfy the complete advertised schema. Correct the input before calling the remote tool.", NOT_STARTED);
+      return input;
+    };
+  }
+}

package/src/runtime/oauth.ts

@@ -18,7 +18,7 @@ import { pollDeviceCode } from "./oauth-device.ts";
 import { parseDeviceAuthorization, parseOAuthTokens } from "../core/oauth-fields.ts";
 
 /** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.4.0";
+export const XENO_VERSION = "0.6.0";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge

package/src/runtime/output-schema.ts

@@ -0,0 +1,26 @@
+/** Ajv owns JSON Schema semantics; validation never repairs model output (D11/D13). */
+import { Ajv } from "ajv";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { Ajv2019 } from "ajv/dist/2019.js";
+import { addFormats } from "@modelcontextprotocol/client/validators/ajv";
+
+export type OutputValidation = { ok: true; value: unknown } | { ok: false; error: string };
+export function outputValidator(schema: unknown): (text: string) => OutputValidation {
+  if (typeof schema !== "boolean" && (schema === null || typeof schema !== "object" || Array.isArray(schema))) throw Error("output schema must be a JSON Schema object or boolean");
+  const dialect = typeof schema === "object" && schema !== null && "$schema" in schema ? String(schema.$schema) : "";
+  const options = { allErrors: true, strictSchema: true, strictTypes: false, strictTuples: false, strictRequired: false, validateFormats: true,
+    coerceTypes: false, useDefaults: false, removeAdditional: false, logger: false as const };
+  const ajv = dialect === "https://json-schema.org/draft/2020-12/schema" ? new Ajv2020(options)
+    : dialect === "https://json-schema.org/draft/2019-09/schema" ? new Ajv2019(options)
+    : dialect === "" || dialect === "http://json-schema.org/draft-07/schema#" || dialect === "http://json-schema.org/draft-07/schema" ? new Ajv(options) : undefined;
+  if (!ajv) throw Error("unsupported output schema dialect");
+  // The approved MCP client exposes Ajv's standard formats; share them rather than silently ignoring formats.
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  return text => {
+    let value: unknown;
+    try { value = JSON.parse(text); } catch { return { ok: false, error: "final output is not JSON" }; }
+    if (!validate(value)) return { ok: false, error: ajv.errorsText(validate.errors, { separator: "; " }).slice(0, 2048) };
+    return { ok: true, value };
+  };
+}

package/src/runtime/patch-tool.ts

@@ -0,0 +1,38 @@
+/** One durable mutation owner for multi-file Patch, independent of provider syntax. */
+import { changedPaths } from "../core/checkpoints.ts";
+import { NOT_STARTED, READ_ATTEMPTED, UNKNOWN_EFFECT, failureDiagnostic, failureFromError } from "../core/tool-failure.ts";
+import { preparePatch, applyPreparedPatch } from "../store/patch.ts";
+import { presentObservation, type ToolDefinition } from "./tools.ts";
+
+export function createPatchTool(): ToolDefinition {
+  return {
+    name: "apply_patch", access: "write", execution: "exclusive", branch: "write",
+    description: "Apply a Codex-style multi-file patch containing Add File, Update File, optional Move to, and Delete File. Existing sources require a prior session read or explicit expected_sha256. All targets and exact unique hunks are preflighted before changes; add/move destinations must be absent. Uses durable file checkpoints and compensates partial application without overwriting external changes. Preserves original BOM, line endings and modes. Return contains resulting file SHA-256 versions.",
+    input_schema: { type: "object", required: ["patchText"], properties: {
+      patchText: { type: "string", description: "Full *** Begin Patch ... *** End Patch text; update hunks start with @@ and lines use space/+/- prefixes." },
+      expected_sha256: { type: "object", additionalProperties: { type: "string", pattern: "^[a-f0-9]{64}$" }, description: "Optional source path to exact SHA-256 premise; otherwise use observed session versions." },
+    } },
+    run: async (ctx, input) => {
+      if (!ctx.workspace) return { ok: false, content: "Patch requires the session's durable workspace checkpoint owner.", diagnostic: failureDiagnostic("environment_missing", "Patch requires the session's durable workspace checkpoint owner.", NOT_STARTED) };
+      let admitted = false;
+      try {
+        const expected = input["expected_sha256"];
+        if (expected !== undefined && (expected === null || typeof expected !== "object" || Array.isArray(expected))) throw new Error("expected_sha256 must be an object of source digests");
+        const prepared = await preparePatch(ctx.root, ctx.workspace.blobs, String(input["patchText"]), {
+          ...(ctx.observedFileVersion === undefined ? {} : { observedFileVersion: ctx.observedFileVersion }),
+          ...(expected === undefined ? {} : { expectedSha256: expected as Record<string, string> }),
+          ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+        });
+        admitted = true;
+        await ctx.workspace.patch(prepared.changes, () => applyPreparedPatch(ctx.root, ctx.workspace!.blobs, prepared, ctx.signal), ctx.signal);
+        const paths = changedPaths(prepared.changes);
+        const summary = paths.map(path => `${path}: ${prepared.changes[path]!.after?.sha256 ?? "deleted"}`).join("\n");
+        const data = paths.map(path => ({ path, before: prepared.changes[path]!.before?.sha256 ?? null, after: prepared.changes[path]!.after?.sha256 ?? null }));
+        return { ...await presentObservation(ctx, `Applied patch to ${paths.length} file path(s).\n${summary}\n\n${prepared.diffs.map(diff => diff.diff).join("\n")}`), ok: true, data: { files: data } };
+      } catch (error) {
+        const diagnostic = failureFromError(error, admitted ? UNKNOWN_EFFECT : READ_ATTEMPTED);
+        return { ok: false, content: diagnostic.message, diagnostic };
+      }
+    },
+  };
+}

package/src/runtime/permission-resources.ts

@@ -0,0 +1,11 @@
+/** R13: an indirect content reader must retain the same read-resource policy. */
+import { decideWithSessionRules, type PermissionAction, type PermissionRule } from "../core/permissions.ts";
+import { permissionPaths } from "../store/permission-paths.ts";
+
+export async function permissionResourceAction(root: string, path: string, configured: readonly PermissionRule[],
+  remembered: readonly PermissionRule[] = [], tool = "read"): Promise<PermissionAction> {
+  const paths = await permissionPaths(root, [path]);
+  const read = decideWithSessionRules(configured, remembered, { tool: "read", paths });
+  const specific = decideWithSessionRules(configured, remembered, { tool, paths });
+  return read === "deny" || specific === "deny" ? "deny" : read === "ask" || specific === "ask" ? "ask" : "allow";
+}

package/src/runtime/provider.ts

@@ -44,6 +44,8 @@ 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[];

package/src/runtime/question-tool.ts

@@ -0,0 +1,62 @@
+/** 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) };
+}

package/src/runtime/review-tool.ts

@@ -0,0 +1,48 @@
+/** Shared diff preparation for model tools and user review commands; no provider calls. */
+import type { FileChanges } from "../core/checkpoints.ts";
+import type { ReviewScope } from "../core/review.ts";
+import { failureFromError, READ_ATTEMPTED } from "../core/tool-failure.ts";
+import { readReview, readCheckpointReview } from "../store/review.ts";
+import { presentObservation, type ToolContext, type ToolDefinition } from "./tools.ts";
+
+export interface LastTurnReview { blobs: string; changes: FileChanges; limitations: string[] }
+export interface DiffToolOptions {
+  lastTurn?: (context: ToolContext) => Promise<LastTurnReview>;
+  /** Current resource policy must be checked before diff bytes enter an artifact or model output. */
+  canRead?: (context: ToolContext, path: string) => Promise<boolean>;
+}
+export function parseReviewScope(input: Record<string, unknown>): ReviewScope {
+  const kind = input["scope"] ?? "working";
+  if (kind === "working" || kind === "last-turn") {
+    if (input["base"] !== undefined || input["commit"] !== undefined) throw new Error(`${kind} scope accepts no revision`);
+    return { kind };
+  }
+  if (kind === "branch" && typeof input["base"] === "string" && input["base"].trim() && input["commit"] === undefined) return { kind, base: input["base"] };
+  if (kind === "commit" && typeof input["commit"] === "string" && input["commit"].trim() && input["base"] === undefined) return { kind, commit: input["commit"] };
+  throw new Error("review scope must be working, branch with base, commit with commit, or last-turn");
+}
+
+export function createDiffTool(options: DiffToolOptions = {}): ToolDefinition {
+  return {
+    name: "diff", access: "read", execution: "parallel", branch: "read",
+    description: "Read a unified diff for current staged/unstaged/untracked changes, a branch merge base, a selected commit, or durable checkpoints in the last user turn. Fixed Git argv disables external diff/textconv drivers and confines paths to the workspace. Reports uncaptured or unavailable data explicitly. This observes changes; it does not change files or run a model review.",
+    input_schema: { type: "object", required: [], properties: { scope: { type: "string", enum: ["working", "branch", "commit", "last-turn"] }, base: { type: "string" }, commit: { type: "string" } } },
+    run: async (ctx, input) => {
+      try {
+        const scope = parseReviewScope(input);
+        const canRead = options.canRead === undefined ? undefined : (path: string) => options.canRead!(ctx, path);
+        const snapshot = scope.kind === "last-turn" ? await (async () => {
+          if (!options.lastTurn) throw new Error("last-turn diff requires original session checkpoint history");
+          const original = await options.lastTurn(ctx);
+          return readCheckpointReview(original.blobs, original.changes, original.limitations, canRead);
+        })() : await readReview(ctx.root, scope, ctx.signal, canRead);
+        const notices = snapshot.limitations.length ? "\nLimitations:\n" + snapshot.limitations.map(line => "- " + line).join("\n") : "";
+        return { ...await presentObservation(ctx, `${snapshot.label}\n${snapshot.diff || "(no captured changes)"}${notices}`), ok: true,
+          data: { scope: scope.kind, paths: snapshot.paths, limitations: snapshot.limitations, ...(snapshot.base === undefined ? {} : { base: snapshot.base }) } };
+      } catch (error) {
+        const diagnostic = failureFromError(error, READ_ATTEMPTED);
+        return { ok: false, content: diagnostic.message, diagnostic };
+      }
+    },
+  };
+}

package/src/runtime/session-control.ts

@@ -11,16 +11,25 @@ import type { LogEvent } from "../core/events.ts";
 import { readNodeHistory } from "../store/restore.ts";
 import type { Session, LoopEvent } from "./loop.ts";
 import type { ApprovalChoice } from "./tools.ts";
+import { validateQuestionReply, type QuestionRequest, type QuestionReply } from "../core/question.ts";
+import type { QuestionSlot } from "./question-tool.ts";
 
 export type ControlNotice = { method: string; params: { threadId: string; streamId: string; sequence: number; turnId?: string; [key: string]: unknown } };
 export type PendingApproval = { id: string; turnId: string; request: PermissionRequest };
 export type ControlSnapshot = {
   version: "xeno-control/0.1"; threadId: string; streamId: string; sequence: number; node: number;
   activeTurnId: string | null; goal: GoalView | null; context: ContextLens;
-  waiting: "permission" | "question" | "auth" | null; approvals: PendingApproval[];
+  workflowMode: "build" | "plan";
+  waiting: "permission" | "question" | "auth" | null; approvals: PendingApproval[]; questions: QuestionRequest[];
 };
 
 export class SessionControl {
+  /** App-owned configuration switches resources at an idle checkpoint; observers cannot mutate it. */
+  configureWorkflow?: (mode: "build" | "plan") => Promise<void>;
+  readonly questionSlot: QuestionSlot;
+  private questionClients = 0;
+  private readonly questionAdapter: NonNullable<QuestionSlot["current"]> = (request, signal) => this.askQuestion(request, signal);
+  private readonly questions = new Map<string, { request: QuestionRequest; resolve(reply: QuestionReply | undefined): void }>();
   readonly session: Session;
   readonly threadId: string;
   readonly streamId = randomUUID();
@@ -35,6 +44,7 @@ export class SessionControl {
 
   constructor(session: Session) {
     this.session = session;
+    this.questionSlot = session.config.tools.questionSlot ?? {};
     // Same identity rule as provider affinity; no new durable identity store (D8).
     this.threadId = createHash("sha256").update(resolve(session.config.logDir)).digest("hex");
     session.subscribeRecords(item => this.emit("item/completed", { item }));
@@ -42,6 +52,14 @@ export class SessionControl {
   get activeTurnId(): string | null { return this.active?.id ?? null; }
   get busy(): boolean { return this.changing || this.active !== null || this.session.running; }
 
+  /** One owner excludes turn admission across asynchronous checkpoint/configuration work. */
+  async withIdleChange<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.busy) throw Error("configuration changes require an idle session");
+    this.changing = true;
+    try { const result = await operation(); this.emit("thread/statusChanged"); return result; }
+    finally { this.changing = false; }
+  }
+
   subscribe(listener: (event: ControlNotice) => void): () => void {
     this.listeners.add(listener); return () => { this.listeners.delete(listener); };
   }
@@ -72,8 +90,9 @@ export class SessionControl {
     const projectedGoal = goalView(parts);
     const goal = this.active && projectedGoal?.state.request.event !== this.active.id ? null : projectedGoal;
     return { version: "xeno-control/0.1", threadId: this.threadId, streamId: this.streamId, sequence: this.sequence, node,
-      activeTurnId: this.activeTurnId, goal, waiting: this.waiting,
+      activeTurnId: this.activeTurnId, goal, waiting: this.waiting, workflowMode: s.config.tools.workflowMode ?? "build",
       approvals: structuredClone([...this.approvals.values()].map(item => item.data)),
+      questions: structuredClone([...this.questions.values()].map(item => item.request)),
       context: contextLens({ ...s.contextInput(), anchor: s.state.anchor, policy: s.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
         contextWindow: s.provider.config.spec.contextWindow, outputReserve: s.provider.config.maxTokens,
         ...(s.config.counter ? { counter: s.config.counter } : {}), ...(s.config.boundary ? { boundary: s.config.boundary } : {}) }) };
@@ -92,6 +111,7 @@ export class SessionControl {
     if (this.busy) throw Error("a turn is already running");
     const active = { id: this.session.clock.nextId(), abort: new AbortController(), queue: [] as UserInput[] };
     this.active = active;
+    this.questionSlot.activeTurn = active.id;
     const signals = signal ? AbortSignal.any([signal, active.abort.signal]) : active.abort.signal;
     let outcome: ExecutionOutcome | undefined;
     try {
@@ -114,6 +134,8 @@ export class SessionControl {
       throw error;
     } finally {
       for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+      for (const question of [...this.questions.values()]) question.resolve(undefined);
+      delete this.questionSlot.activeTurn;
       this.waiting = null;
       // A thrown provider error also appends an outcome. Clients must be able to discover it.
       try {
@@ -147,6 +169,7 @@ export class SessionControl {
   interrupt(turnId: string): void {
     this.current(turnId).abort.abort();
     for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+    for (const question of [...this.questions.values()]) question.resolve(undefined);
     this.session.cancel();
   }
   setWaiting(kind: ControlSnapshot["waiting"]): void {
@@ -178,6 +201,41 @@ export class SessionControl {
     approval.resolve(choice);
   }
   denyApprovals(): void { for (const approval of [...this.approvals.values()]) approval.resolve("deny"); }
+  attachQuestionClient(): () => void {
+    this.questionClients++;
+    if (!this.questionSlot.current) this.questionSlot.current = this.questionAdapter;
+    let closed = false;
+    return () => {
+      if (closed) return; closed = true;
+      if (--this.questionClients === 0) {
+        if (this.questionSlot.current === this.questionAdapter) delete this.questionSlot.current;
+        for (const question of [...this.questions.values()]) question.resolve(undefined);
+      }
+    };
+  }
+  askQuestion(request: QuestionRequest, signal: AbortSignal, present?: (request: QuestionRequest) => Promise<unknown>): Promise<QuestionReply | undefined> {
+    if (!this.active || request.turn_id !== this.active.id || signal.aborted || !present && this.questionClients === 0) return Promise.resolve(undefined);
+    if (this.questions.has(request.request_id)) return Promise.reject(Error("duplicate question invocation"));
+    return new Promise(resolve => {
+      const finish = (reply: QuestionReply | undefined) => {
+        if (!this.questions.delete(request.request_id)) return;
+        signal.removeEventListener("abort", aborted); this.setWaiting(this.questions.size ? "question" : null);
+        this.emit("question/resolved", { requestId: request.request_id }); resolve(reply);
+      };
+      const aborted = () => finish(undefined);
+      this.questions.set(request.request_id, { request: structuredClone(request), resolve: finish });
+      signal.addEventListener("abort", aborted, { once: true }); this.setWaiting("question");
+      this.emit("question/request", { question: structuredClone(request) });
+      if (present) void present(structuredClone(request)).then(value => {
+        if (value === undefined) finish(undefined); else try { finish(validateQuestionReply(request, value)); } catch { finish(undefined); }
+      }).catch(() => finish(undefined));
+    });
+  }
+  respondQuestion(turnId: string, requestId: string, reply: unknown): void {
+    this.current(turnId); const question = this.questions.get(requestId);
+    if (!question || question.request.turn_id !== turnId) throw Error("stale or unknown question requestId");
+    question.resolve(validateQuestionReply(question.request, reply));
+  }
   async accept(requestId: string, criterion: string): Promise<void> {
     if (this.busy) throw Error("acceptance requires an idle session");
     this.changing = true;