@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/session-control.ts

@@ -0,0 +1,198 @@
+/** Q24: one controller per live Session, shared by the TUI and structured adapters. */
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { goalView, contextLens, type GoalView, type ContextLens } from "../core/control-view.ts";
+import { DEFAULT_CONTEXT_POLICY } from "../core/context-policy.ts";
+import { userInputData, type UserInput } from "../core/images.ts";
+import type { Phase } from "../core/queue.ts";
+import type { PermissionRequest } from "../core/permissions.ts";
+import type { ExecutionOutcome } from "../core/outcome.ts";
+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";
+
+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[];
+};
+
+export class SessionControl {
+  readonly session: Session;
+  readonly threadId: string;
+  readonly streamId = randomUUID();
+  private sequence = 0;
+  private listeners = new Set<(event: ControlNotice) => void>();
+  private active: { id: string; abort: AbortController; queue: UserInput[] } | null = null;
+  private task: Promise<void> | null = null;
+  private approvals = new Map<string, { data: PendingApproval; resolve: (choice: ApprovalChoice) => void }>();
+  private waiting: ControlSnapshot["waiting"] = null;
+  private changing = false;
+  private inputSource: ((phase: Phase) => Promise<UserInput | null>) | undefined;
+
+  constructor(session: Session) {
+    this.session = session;
+    // 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 }));
+  }
+  get activeTurnId(): string | null { return this.active?.id ?? null; }
+  get busy(): boolean { return this.changing || this.active !== null || this.session.running; }
+
+  subscribe(listener: (event: ControlNotice) => void): () => void {
+    this.listeners.add(listener); return () => { this.listeners.delete(listener); };
+  }
+  /** The attached editor owns retractable drafts even when an adapter starts the turn. */
+  attachInput(pull: (phase: Phase) => Promise<UserInput | null>): () => void {
+    if (this.inputSource) throw Error("the session already has an attached input owner");
+    this.inputSource = pull;
+    return () => { if (this.inputSource === pull) this.inputSource = undefined; };
+  }
+  private emit(method: string, data: Record<string, unknown> = {}): void {
+    const event: ControlNotice = { method, params: { ...data, threadId: this.threadId, streamId: this.streamId,
+      sequence: ++this.sequence, ...(this.active ? { turnId: this.active.id } : {}) } };
+    for (const listener of this.listeners) {
+      // Observers are outside the evidence owner: mutations and failures cannot alter execution.
+      try { listener(structuredClone(event)); } catch { /* the transport owns delivery errors */ }
+    }
+  }
+  async snapshot(observe = true): Promise<ControlSnapshot> {
+    if (observe && !this.busy) await this.session.acceptanceState();
+    const node = this.session.state.node;
+    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
+    if (!history.ok) throw Error(history.error);
+    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
+    const s = this.session;
+    // Ancestors are sealed. The live segment must share the cursor's publication
+    // boundary: a disk read can finish between append and in-memory publication.
+    const parts = history.nodes.map(part => part.node === node ? { node, events: structuredClone(s.state.events) } : part);
+    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,
+      approvals: structuredClone([...this.approvals.values()].map(item => item.data)),
+      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 } : {}) }) };
+  }
+  async items(): Promise<{ node: number; event: LogEvent }[]> {
+    const node = this.session.state.node;
+    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
+    if (!history.ok) throw Error(history.error);
+    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
+    return history.nodes.flatMap(part => (part.node === node ? structuredClone(this.session.state.events) : part.events)
+      .map(event => ({ node: part.node, event })));
+  }
+
+  /** Both local and remote turns pass through this iterator; Session remains the execution owner. */
+  async *send(input: UserInput, signal?: AbortSignal, pull?: (phase: Phase) => Promise<UserInput | null>): AsyncGenerator<LoopEvent> {
+    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;
+    const signals = signal ? AbortSignal.any([signal, active.abort.signal]) : active.abort.signal;
+    let outcome: ExecutionOutcome | undefined;
+    try {
+      this.emit("turn/started");
+      const steering = async (phase: Phase): Promise<UserInput | null> => {
+        const external = active.queue.splice(0), local = await (pull ?? this.inputSource)?.(phase);
+        if (local) external.push(local);
+        const data = external.map(value => userInputData(value));
+        const text = data.map(value => value.text).join("\n\n"), images = data.flatMap(value => value.images ?? []);
+        return images.length ? { text, images } : text || null;
+      };
+      for await (const event of this.session.send(input, signals, steering, active.id)) {
+        this.emit("turn/event", { event });
+        if (event.kind === "done") outcome = event.outcome;
+        yield event;
+      }
+    } catch (error) {
+      // Raw provider errors may contain credentials. The owner can report a sanitized error separately.
+      this.emit("turn/error", { message: "turn failed; inspect the session outcome" });
+      throw error;
+    } finally {
+      for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+      this.waiting = null;
+      // A thrown provider error also appends an outcome. Clients must be able to discover it.
+      try {
+        if (!outcome) {
+          const state = (await this.snapshot(false)).goal?.state;
+          if (state?.request.event === active.id) outcome = state.execution;
+        }
+      } catch { /* unreadable storage stays unknown, never an invented completion */ }
+      this.emit("turn/completed", { ...(outcome ? { outcome } : {}), steeringUndelivered: active.queue.length });
+      this.active = null;
+    }
+  }
+  start(input: UserInput): string {
+    if (this.busy) throw Error("a turn is already running");
+    this.task = (async () => { for await (const _event of this.send(input)) { /* notices are the client stream */ } })();
+    void this.task.catch(() => {});
+    return this.active!.id;
+  }
+  async whenIdle(): Promise<void> { await this.task; await this.session.whenIdle(); }
+  private current(turnId: string): NonNullable<SessionControl["active"]> {
+    if (!this.active || this.active.id !== turnId) throw Error("stale or unknown turnId");
+    return this.active;
+  }
+  steer(turnId: string, input: UserInput): void {
+    const turn = this.current(turnId);
+    // Assumed ingress bound, not an execution policy. Keep a client from queuing unbounded work.
+    if (turn.queue.length >= 32) throw Error("steering queue is full");
+    turn.queue.push(structuredClone(input));
+    this.emit("turn/steeringQueued", { count: turn.queue.length });
+  }
+  interrupt(turnId: string): void {
+    this.current(turnId).abort.abort();
+    for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+    this.session.cancel();
+  }
+  setWaiting(kind: ControlSnapshot["waiting"]): void {
+    this.waiting = this.approvals.size ? "permission" : kind;
+    this.emit("thread/statusChanged", { waiting: this.waiting });
+  }
+  ask(request: PermissionRequest, present?: (id: string, resolve: (choice: ApprovalChoice) => void) => (() => void)): Promise<ApprovalChoice> {
+    if (!this.active) return Promise.resolve("deny");
+    const data = { id: randomUUID(), turnId: this.active.id, request: structuredClone(request) };
+    return new Promise(resolveChoice => {
+      let close: (() => void) | undefined;
+      const resolveOnce = (choice: ApprovalChoice) => {
+        if (!this.approvals.delete(data.id)) return;
+        close?.(); this.waiting = this.approvals.size ? "permission" : null;
+        this.emit("approval/resolved", { approvalId: data.id }); resolveChoice(choice);
+      };
+      this.approvals.set(data.id, { data, resolve: resolveOnce }); this.waiting = "permission";
+      this.emit("approval/request", { approval: data });
+      if (this.approvals.has(data.id)) {
+        try { close = present?.(data.id, resolveOnce); }
+        catch { resolveOnce("deny"); }
+      }
+    });
+  }
+  respond(turnId: string, id: string, choice: ApprovalChoice): void {
+    this.current(turnId);
+    const approval = this.approvals.get(id);
+    if (!approval || approval.data.turnId !== turnId) throw Error("stale or unknown approvalId");
+    approval.resolve(choice);
+  }
+  denyApprovals(): void { for (const approval of [...this.approvals.values()]) approval.resolve("deny"); }
+  async accept(requestId: string, criterion: string): Promise<void> {
+    if (this.busy) throw Error("acceptance requires an idle session");
+    this.changing = true;
+    try {
+      const state = await this.session.requestState();
+      if (state?.request.event !== requestId) throw Error("stale or unknown requestId");
+      await this.session.acceptCriterion(criterion);
+      this.emit("thread/statusChanged");
+    } finally { this.changing = false; }
+  }
+}
+
+const controls = new WeakMap<Session, SessionControl>();
+export function sessionControl(session: Session): SessionControl {
+  let control = controls.get(session);
+  if (!control) { control = new SessionControl(session); controls.set(session, control); }
+  return control;
+}

package/src/runtime/tool-broker.ts

@@ -0,0 +1,137 @@
+/** Pi A / D8 / D11: direct and nested execution share one admitted, durable call contract. */
+import type { AssistantBlock, ToolInvocationEvent } from "../core/events.ts";
+import { failureDiagnostic, NOT_STARTED, UNKNOWN_EFFECT, ToolFault } from "../core/tool-failure.ts";
+import { executionOutcome } from "../core/outcome.ts";
+import { finishToolResult, nativeCommandContext, NATIVE_COMMAND_NAME, normalizeToolInput, type ToolContext, type ToolResult, type NestedInvocationOptions } from "./tools.ts";
+import { ToolQueue } from "./tool-queue.ts";
+
+export type BrokerCall = Extract<AssistantBlock, { type: "tool_use" }>;
+type Mode = "parallel" | "exclusive";
+/** Inherits the existing extension limit, now shared by the entire invocation tree. */
+export const MAX_NESTED_CALLS = 32;
+export const MAX_NESTED_DEPTH = 32;
+/** Assumed per-call composition budget; direct large edits retain their existing interface. */
+export const MAX_NESTED_ARGUMENT_BYTES = 64 * 1024;
+/** Assumed log metadata bound; complete structured results are independent artifacts. */
+export const MAX_INLINE_RESULT_DATA_BYTES = 64 * 1024;
+
+export interface BrokerHost<Result extends ToolResult> {
+  parallelLimit: number;
+  callId(): string;
+  mode(call: BrokerCall): Mode;
+  invocation(call: BrokerCall, ctx: ToolContext, parent: ToolInvocationEvent | undefined): Promise<ToolInvocationEvent>;
+  /** Receives normalized input and must still apply admission, including Session-owned tools. */
+  prepare(call: BrokerCall, ctx: ToolContext): Promise<Result | (() => Promise<Result>)>;
+  /** Session annotations and branch receipts are accepted before their result becomes evidence. */
+  settle(result: Result): Promise<void>;
+  result(invocation: ToolInvocationEvent, result: Result): Promise<void>;
+}
+export interface BrokerReceipt<Result extends ToolResult> {
+  value: Result;
+  invocation: ToolInvocationEvent;
+  settle(): Promise<void>;
+  commit(): Promise<void>;
+}
+export type BrokerExecution<Result extends ToolResult> = (() => Promise<BrokerReceipt<Result>>) & { close(): Promise<void> };
+type Budget = { calls: number };
+type Parent = { invocation: ToolInvocationEvent; budget: Budget; depth: number };
+
+/** Scheduling belongs to a live scope; immutable requests/results belong to the host log. */
+export class ToolBroker<Result extends ToolResult = ToolResult> {
+  private readonly host: BrokerHost<Result>;
+  constructor(host: BrokerHost<Result>) { this.host = host; }
+
+  async prepare(call: BrokerCall, context: ToolContext, parent?: Parent): Promise<BrokerExecution<Result>> {
+    let actual = call;
+    let invalid: ToolResult | undefined;
+    try {
+      // Extension argument preparation cannot rewrite the already-recorded model
+      // request. Hooks receive the exact immutable value archived for admission.
+      actual = { ...call, input: freezeInput(structuredClone(normalizeToolInput(context, call.name, structuredClone(call.input)))) };
+    }
+    catch (error) { invalid = error instanceof ToolFault ? finishToolResult({ ok: false, content: error.message, diagnostic: error.diagnostic }) : refused(`Invalid ${call.name} arguments: ${String(error)}`); }
+    const invocation = await this.host.invocation(actual, context, parent?.invocation);
+    if (parent && invocation.input === undefined) invalid = refused("nested arguments exceed the inline composition budget or are not JSON; pass a bounded request or use the direct tool");
+    const budget = parent?.budget ?? { calls: 0 }, depth = (parent?.depth ?? 0) + 1;
+    const children = new ToolQueue(this.host.parallelLimit);
+    const pending = new Set<Promise<ToolResult>>();
+    const failures: string[] = [];
+    let incomplete = false;
+    const mode = this.host.mode(actual);
+    let open = true;
+    const invoke = (name: string, input: unknown, options?: NestedInvocationOptions, native = false): Promise<ToolResult> => {
+      if (!open) return Promise.resolve(refused("tool scope is closed; no invocation started"));
+      if (mode !== "exclusive") return Promise.resolve(refused("only an exclusive composing tool may request nested execution"));
+      if (depth >= MAX_NESTED_DEPTH || budget.calls >= MAX_NESTED_CALLS) return Promise.resolve(refused("nested tool budget exhausted; no invocation started"));
+      // Capture at submission, before an asynchronous queue can observe a
+      // caller's later mutation of the same object.
+      try { input = structuredClone(input); }
+      catch { return Promise.resolve(refused("nested arguments must be serializable; no invocation started")); }
+      budget.calls++;
+      const nested: BrokerCall = { type: "tool_use", call_id: this.host.callId(), name, input };
+      const signals = [ctx.signal, options?.signal].filter((signal): signal is AbortSignal => signal !== undefined);
+      const nestedContext: ToolContext = native ? nativeCommandContext(ctx, options?.signal) : { ...ctx,
+        ...(signals.length ? { signal: AbortSignal.any(signals) } : {}) };
+      const result = children.submit(this.host.mode(nested), async () => {
+        const execute = await this.prepare(nested, nestedContext, { invocation, budget, depth });
+        return async () => {
+          const receipt = await execute();
+          await receipt.settle(); await receipt.commit();
+          if (!receipt.value.ok) failures.push(`nested call ${receipt.invocation.call_id} failed`);
+          return { ...receipt.value, invocation: { call_id: receipt.invocation.call_id, event: receipt.invocation.id } };
+        };
+      });
+      pending.add(result);
+      // The broker owns the lifetime even when extension code drops the promise.
+      void result.then(() => pending.delete(result), error => { incomplete = true; failures.push(`nested execution or persistence failed: ${String(error)}`); pending.delete(result); });
+      return result;
+    };
+    const ctx: ToolContext = { ...context, callId: call.call_id,
+      ...(parent ? { parentCallId: parent.invocation.call_id } : {}),
+      invoke: (name, input, options) => invoke(name, input, options),
+      runOwnedCommand: execute => children.submit("exclusive", async () => execute),
+      drainNested: () => children.whenIdle(),
+      invokeHost: (input, signal) => invoke(NATIVE_COMMAND_NAME, input, signal ? { signal } : {}, true) };
+    let closing: Promise<void> | undefined;
+    const close = () => {
+      open = false;
+      return closing ??= (async () => { await children.close(); await Promise.allSettled(pending); })();
+    };
+    let prepared: ToolResult | (() => Promise<Result>);
+    try { prepared = invalid ?? await this.host.prepare(actual, ctx); }
+    catch (error) { prepared = finishToolResult({ ok: false, content: String(error), diagnostic: failureDiagnostic("unknown_effect", String(error), UNKNOWN_EFFECT) }); }
+    return Object.assign(async () => {
+      let value: Result;
+      try { value = (typeof prepared === "function" ? await prepared() : prepared) as Result; }
+      catch (error) {
+        value = finishToolResult({ ok: false, content: `tool ${call.name} failed: ${String(error)}`,
+          diagnostic: failureDiagnostic("unknown_effect", String(error), UNKNOWN_EFFECT) }) as Result;
+      } finally {
+        await close();
+      }
+      if (failures.length) value = { ...value, warnings: [...(value.warnings ?? []),
+        failureDiagnostic("unknown_effect", `${failures.length} nested failures; inspect the original invocation receipts. ${failures[0]}`, UNKNOWN_EFFECT)] };
+      if (incomplete) value = { ...value, ok: false, outcome: executionOutcome("unknown"),
+        diagnostic: failureDiagnostic("unknown_effect", "nested execution or persistence did not produce a complete receipt", UNKNOWN_EFFECT) };
+      let settled: Promise<void> | undefined, committed: Promise<void> | undefined;
+      const settle = () => settled ??= this.host.settle(value);
+      return { value, invocation, settle,
+        commit: () => committed ??= settle().then(() => this.host.result(invocation, value)) };
+    }, { close });
+  }
+}
+
+function refused(message: string): ToolResult {
+  return finishToolResult({ ok: false, content: message, diagnostic: failureDiagnostic("invalid_input", message, NOT_STARTED) });
+}
+
+function freezeInput(value: unknown, ancestors = new Set<unknown>()): unknown {
+  if (value !== null && typeof value === "object") {
+    if (ancestors.has(value)) throw new Error("cyclic tool arguments are not JSON");
+    ancestors.add(value);
+    for (const child of Object.values(value)) freezeInput(child, ancestors);
+    ancestors.delete(value);
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/runtime/tool-discovery.ts

@@ -0,0 +1,57 @@
+/** R11: a harness-owned discovery entry shares normal Session admission and result persistence. */
+import { createHash } from "node:crypto";
+import { discoverTools, MAX_DISCOVERY_QUERY, MAX_DISCOVERY_RESULTS, type DeclarationRequest } from "../core/tool-discovery.ts";
+import { decide } from "../core/permissions.ts";
+import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
+import type { ToolSchema } from "./provider.ts";
+import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
+
+export const DISCOVERY_TOOL_NAME = "tool_search";
+export const DISCOVERY_TOOL: ToolDefinition = {
+  name: DISCOVERY_TOOL_NAME,
+  description: "Find optional registered tools by name or purpose. Reads the local catalog without connecting to services or executing tools. Returns purpose, important input types and declaration status. Matching permitted tools become declared only after the complete tool batch, for the next model request; then call them with their actual schema. Discovery does not grant execution permission or prove service health. Example: {\"query\":\"issue tracker\",\"limit\":3}.",
+  input_schema: { type: "object", properties: {
+    query: { type: "string", minLength: 1, maxLength: MAX_DISCOVERY_QUERY },
+    limit: { type: "integer", minimum: 1, maximum: MAX_DISCOVERY_RESULTS, description: "Maximum matches to request; defaults to 5." },
+  }, required: ["query"] },
+  access: "state", execution: "exclusive", branch: "none",
+  run: async () => ({ ok: false, content: "Tool discovery requires a live Session checkpoint." }),
+};
+
+/** Bind a request to the observed contract; an edited/replaced registration needs another lookup. */
+export function discoveryFingerprint(tool: ToolSchema): string {
+  return createHash("sha256").update(JSON.stringify({ name: tool.name, description: tool.description, input_schema: tool.input_schema })).digest("hex");
+}
+export function discoveryPermitted(ctx: ToolContext, name: string): boolean {
+  return decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], { tool: name }) !== "deny";
+}
+/** A directory entry without its matching live implementation is unavailable, regardless of history. */
+export function currentDeferredTools(ctx: ToolContext): readonly ToolSchema[] {
+  return (ctx.deferredTools ?? []).filter(tool => {
+    const definition = ctx.extensions?.get(tool.name);
+    return definition !== undefined && discoveryFingerprint(definition) === discoveryFingerprint(tool);
+  });
+}
+export function searchDeferredTools(ctx: ToolContext, input: Record<string, unknown>, declared: readonly string[]): ToolResult {
+  const catalog = currentDeferredTools(ctx);
+  let matches;
+  try { matches = discoverTools(catalog, input["query"] as string, input["limit"] as number | undefined); }
+  catch {
+    const content = "Discovery requires a nonblank query of at most 256 characters and an integer limit from 1 to 8.";
+    return { ok: false, content, diagnostic: failureDiagnostic("invalid_input", content, NOT_STARTED) };
+  }
+  const requested: DeclarationRequest[] = [];
+  const result = matches.map(match => {
+    const tool = catalog.find(item => item.name === match.name)!;
+    const permitted = discoveryPermitted(ctx, match.name);
+    const status = !permitted ? "permission_denied" : declared.includes(match.name) ? "declared" : "requested_for_next_request";
+    if (status === "requested_for_next_request") requested.push({ name: tool.name, fingerprint: discoveryFingerprint(tool) });
+    const health = ctx.extensions?.get(match.name)?.integrationHealth?.();
+    return { ...match, declaration: status, service_health: health?.state ?? "not_checked", ...(health ? { service_observation: health } : {}) };
+  });
+  return { ok: true, content: JSON.stringify({ matches: result, note: result.length
+    ? "Only declared tools can run. Requested schemas become available after the current batch at a checkpoint; execution permissions still apply."
+    : "No matching tools in the currently permitted discovery catalog. No service was contacted." }),
+    // Keep only small, original requests inline so cold recovery never depends on a generated summary.
+    data: { kind: "tool_discovery", version: 1, requested: requested.map(item => ({ ...item })) } };
+}

package/src/runtime/tool-mode-eval.ts

@@ -0,0 +1,146 @@
+/** Q.19: fixed workloads and admission overlays share production tools and the v2 auditor. */
+import { queryEvalVerifier } from "./query-eval-verifier.ts";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { seededRandom, type EvalJob } from "../core/experiment.ts";
+import { TOOL_MODE_TASKS, type ToolModeTask, type ToolModeMetrics } from "../core/tool-mode-protocol.ts";
+import { queryEvalContract } from "../core/query-eval-contract.ts";
+import { inputError } from "../core/tool-contract.ts";
+import type { LogEvent, ArtifactRef } from "../core/events.ts";
+import { readObservation } from "../store/observations.ts";
+import { TOOL_DEFINITIONS, modelToolSchema, type ToolContext } from "./tools.ts";
+import type { ToolSchema } from "./provider.ts";
+import type { ComparisonBackend } from "./harness-comparison.ts";
+import type { EvalFixture } from "./harness-eval.ts";
+
+const digest = (text: string) => createHash("sha256").update(text).digest("hex");
+export const TOOL_MODE_SYSTEM = "Solve the supplied data task using query over the complete source files. Preserve inputs and verifier. " +
+  "Use the declared query syntax. Inspect all failures and original evidence. " +
+  "Write only answer.txt, run bun run gate, and report the observed outcome. Do not delegate.";
+export interface ToolModeFixture {
+  answer: string;
+  queries: { path: string; json: Record<string, unknown>; sql: Record<string, unknown> }[];
+}
+export function toolModeFixture(seed: number, task: ToolModeTask, repeat: number): EvalFixture {
+  const random = seededRandom(seed + TOOL_MODE_TASKS.indexOf(task) * 1000 + repeat);
+  const count = task === "tool-batch" ? 8 : 1, rows = task === "tool-small" ? 1 : task === "tool-batch" ? 25 : 9000;
+  const files: Record<string, string> = {}, queries: ToolModeFixture["queries"] = [], expected: { path: string; rows: unknown[] }[] = [];
+  for (let i = 0; i < count; i++) {
+    const path = "data-" + i + ".jsonl", data = Array.from({ length: rows }, (_, row) => ({
+      team: "team" + row % 4, enabled: row % 3 !== 0, amount: 1 + Math.floor(random() * 97),
+    }));
+    files[path] = data.map(row => JSON.stringify(row)).join("\n") + "\n";
+    const base = { paths: [path], format: "jsonl" };
+    if (task === "tool-small") {
+      queries.push({ path, json: { ...base, select: ["amount"] }, sql: { ...base, sql: "SELECT amount FROM source" } });
+      expected.push({ path, rows: [{ amount: data[0]!.amount }] });
+    } else if (task === "tool-batch") {
+      queries.push({ path, json: { ...base, aggregate: [{ op: "sum", field: "amount", as: "total" }] }, sql: { ...base, sql: "SELECT SUM(amount) AS total FROM source" } });
+      expected.push({ path, rows: [{ total: data.reduce((n, row) => n + row.amount, 0) }] });
+    } else {
+      queries.push({ path, json: { ...base, where: [{ field: "enabled", op: "eq", value: true }], group_by: ["team"],
+        aggregate: [{ op: "sum", field: "amount", as: "total" }], order_by: [{ field: "team" }] },
+        sql: { ...base, sql: "SELECT team, SUM(amount) AS total FROM source WHERE enabled = TRUE GROUP BY team ORDER BY team" } });
+      // Independent fixture arithmetic; do not ask the query kernel to grade itself.
+      expected.push({ path, rows: Array.from({ length: 4 }, (_, n) => {
+        const team = "team" + n;
+        return { team, total: data.filter(row => row.enabled && row.team === team).reduce((sum, row) => sum + row.amount, 0) };
+      }) });
+    }
+  }
+  const answer = JSON.stringify(expected) + "\n", answerSha256 = digest(answer);
+  files["package.json"] = JSON.stringify({ scripts: { gate: "bun verify.ts" } }) + "\n";
+  const contract = queryEvalContract(task, queries.map(query => query.path), answerSha256);
+  files["verify.ts"] = queryEvalVerifier(contract);
+  return { task, repeat, files, digests: Object.fromEntries(Object.entries(files).map(([path, body]) => [path, digest(body)])),
+    answerSha256, prompts: [contract.instruction], toolMode: { answer, queries } };
+}
+export type ToolModeSchemas = Record<"json" | "sql", ToolSchema[]>;
+export function toolModeSchemas(): ToolModeSchemas {
+  const build = (syntax: "json" | "sql"): ToolSchema[] => {
+    const names = ["read", "query", "history", "write", "exec_command", "write_stdin", "note"];
+    return names.map(name => {
+      const definition = TOOL_DEFINITIONS.find(tool => tool.name === name)!;
+      if (name !== "query") return modelToolSchema(definition, names);
+      const schema = structuredClone(definition.input_schema) as ToolSchema["input_schema"] & { additionalProperties?: boolean };
+      const jsonKeys = ["where", "select", "group_by", "aggregate", "order_by"];
+      for (const key of syntax === "json" ? ["sql"] : jsonKeys) delete schema.properties[key];
+      if (syntax === "sql") schema.required.push("sql");
+      schema.additionalProperties = false;
+      return { name, description: definition.description + " This trial admits only " + syntax.toUpperCase() + " query syntax.", input_schema: schema };
+    });
+  };
+  return { json: build("json"), sql: build("sql") };
+}
+export const toolModeSchemaKey = (job: EvalJob): keyof ToolModeSchemas => job.policy.querySyntax === "sql" ? "sql" : "json";
+/** Schema visibility is not authority: the same frozen restriction runs before every admitted query. */
+export function toolModeHooks(schemas: readonly ToolSchema[]): NonNullable<ToolContext["extensionHooks"]> {
+  const query = schemas.find(schema => schema.name === "query")!;
+  return { async before(name, input) {
+    if (name !== "query") return undefined;
+    const error = inputError(query.input_schema, input);
+    const properties = (query.input_schema as { properties: Record<string, unknown> }).properties;
+    const extra = input && typeof input === "object" ? Object.keys(input).find(key => !Object.hasOwn(properties, key)) : undefined;
+    return error || extra ? "Frozen query syntax restriction: " + (error ?? "unsupported field " + extra) : undefined;
+  }, async event() {} };
+}
+/** Oracle driver tests the machinery; neither its answers nor call choices are model evidence. */
+export function toolModeBackend(input: EvalFixture): ComparisonBackend {
+  const fixture = input.toolMode!;
+  let step = 0;
+  return async payload => {
+    const declarations = payload["tools"] as { function: { name: string; parameters: { properties: Record<string, unknown> } } }[];
+    const syntax = declarations.find(tool => tool.function.name === "query")!.function.parameters.properties["sql"] ? "sql" : "json";
+    const calls: { name: string; input: unknown }[] = [], index = step++;
+    if (index === 0) {
+      for (const query of fixture.queries) calls.push({ name: "query", input: query[syntax] });
+    }
+    if (index === 1) {
+      const messages = payload["messages"] as { role: string; content?: unknown }[];
+      const observed = messages.filter(message => message.role === "tool").flatMap(message => {
+        const value = JSON.parse(String(message.content));
+        return [value];
+      }) as { sources: { path: string }[]; rows: unknown[] }[];
+      const answer = fixture.queries.map(query => {
+        const value = observed.find(value => value.sources?.length === 1 && value.sources[0]!.path === query.path);
+        if (!value) throw Error("mechanical driver lacks a successful source query receipt");
+        return { path: query.path, rows: value.rows };
+      });
+      calls.push({ name: "write", input: { path: "answer.txt", content: JSON.stringify(answer) + "\n" } });
+    }
+    if (index === 2) calls.push({ name: "exec_command", input: { cmd: "bun run gate", yield_time_ms: 1000 } });
+    return { id: "tool-mode-" + index, model: "eval-mechanical", choices: [{ index: 0, message: {
+      role: "assistant", content: calls.length ? null : "Mechanical protocol fixture finished.",
+      ...(calls.length ? { tool_calls: calls.map((call, i) => ({ id: "mode-" + index + "-" + i, type: "function",
+        function: { name: call.name, arguments: JSON.stringify(call.input) } })) } : {}),
+    }, finish_reason: calls.length ? "tool_calls" : "stop" }], usage: { prompt_tokens: 200, completion_tokens: 32, prompt_cache_hit_tokens: 0 } };
+  };
+}
+export async function toolModeMetrics(directory: string, input: EvalFixture, events: readonly LogEvent[], elapsedMs: number): Promise<ToolModeMetrics> {
+  if (!Number.isFinite(elapsedMs) || elapsedMs < 0) throw Error("missing tool mode elapsed observation");
+  const fixture = input.toolMode!, invocations = new Map(events.filter(event => event.t === "tool_invocation").map(event => [event.id, event]));
+  const sources = new Set<string>();
+  const original = async (ref: ArtifactRef): Promise<unknown> => {
+    const parts: Uint8Array[] = [];
+    for (let offset = 0;;) {
+      const page = await readObservation(join(directory, "observations"), ref.sha256, offset, 1024 * 1024);
+      parts.push(Buffer.from(page.base64, "base64"));
+      if (page.next === null) break;
+      offset = page.next;
+    }
+    return JSON.parse(Buffer.concat(parts).toString("utf8"));
+  };
+  for (const event of events) if (event.t === "tool_result" && event.ok && event.invocation_ref) {
+    const invocation = invocations.get(event.invocation_ref.event);
+    if (!invocation || invocation.call_id !== event.call_id || invocation.name !== "query") continue;
+    const value = event.data_ref ? await original(event.data_ref) : event.content_ref ? await original(event.content_ref) : event.data;
+    if (!value || typeof value !== "object" || !("sources" in value) || !Array.isArray(value.sources)) continue;
+    for (const source of value.sources as { path?: string; sha256?: string }[]) {
+      if (typeof source.path === "string" && fixture.queries.some(query => query.path === source.path) && input.digests[source.path] === source.sha256) sources.add(source.path);
+    }
+  }
+  const calls = [...invocations.values()], sourcePaths = [...sources].sort(), requiredSourcePaths = fixture.queries.map(query => query.path).sort();
+  return { elapsedMs, queryCalls: calls.filter(call => call.name === "query").length,
+    primitiveCalls: calls.length, sourcePaths, requiredSourcePaths,
+    sourceComplete: requiredSourcePaths.every(path => sources.has(path)) };
+}

package/src/runtime/tool-queue.ts

@@ -0,0 +1,77 @@
+/** Pi A / O.5: ordered admission, bounded readers and an exclusive write barrier. */
+import { schedulingWindow } from "../core/scheduling.ts";
+
+type Mode = "parallel" | "exclusive";
+type Job = { mode: Mode; prepare(): Promise<() => Promise<unknown>>; resolve(value: unknown): void; reject(error: unknown): void };
+
+/**
+ * A composing call owns an exclusive slot in its parent queue and gives its
+ * children a fresh queue. Re-entering the held parent slot would deadlock.
+ * Only exclusive tools may compose; concurrent readers therefore cannot each
+ * multiply the session's parallel limit with another queue.
+ */
+export class ToolQueue {
+  private readonly limit: number;
+  private readonly pending: Job[] = [];
+  private active = 0;
+  private exclusive = false;
+  private pumping = false;
+  private readonly idle = new Set<() => void>();
+  private closed = false;
+
+  constructor(limit: number) {
+    schedulingWindow([], 0, limit);
+    this.limit = limit;
+  }
+
+  submit<T>(mode: Mode, prepare: () => Promise<() => Promise<T>>): Promise<T> {
+    if (this.closed) return Promise.reject(new Error("tool scope is closed; no invocation started"));
+    const result = new Promise<T>((resolve, reject) => {
+      this.pending.push({ mode, prepare, resolve: value => resolve(value as T), reject });
+    });
+    this.kick();
+    return result;
+  }
+
+  private kick(): void { if (!this.pumping) { this.pumping = true; void this.pump(); } }
+
+  private async pump(): Promise<void> {
+    try {
+      while (this.pending.length > 0) {
+        const next = this.pending[0]!;
+        const occupied: Mode[] = Array.from({ length: this.active }, () => this.exclusive ? "exclusive" : "parallel");
+        if (schedulingWindow([...occupied, next.mode], 0, this.limit) <= this.active) break;
+        const job = this.pending.shift()!;
+        this.active++; this.exclusive = job.mode === "exclusive";
+        const finished = () => { this.active--; if (job.mode === "exclusive") this.exclusive = false; this.kick(); };
+        try {
+          const execute = await job.prepare();
+          void Promise.resolve().then(execute).then(job.resolve, job.reject).finally(finished);
+        } catch (error) { job.reject(error); this.active--; this.exclusive = false; }
+      }
+    } finally {
+      this.pumping = false;
+      if (this.active === 0 && this.pending.length === 0) { for (const resolve of this.idle) resolve(); this.idle.clear(); }
+    }
+  }
+
+  /** A generator can retain its slot across admission/display yields without executing early. */
+  acquire(mode: Mode): Promise<() => void> {
+    return new Promise((resolve, reject) => {
+      let release!: () => void;
+      const done = new Promise<void>(finish => { release = finish; });
+      void this.submit(mode, async () => async () => { resolve(release); await done; }).catch(reject);
+    });
+  }
+
+  whenIdle(): Promise<void> {
+    if (!this.pumping && this.active === 0 && this.pending.length === 0) return Promise.resolve();
+    return new Promise(resolve => this.idle.add(resolve));
+  }
+
+  /** Accepted jobs drain even when their caller forgot to await their promises. */
+  async close(): Promise<void> {
+    this.closed = true;
+    await this.whenIdle();
+  }
+}