xo-harness 0.1.2 → 0.2.1

package/README.md

@@ -29,7 +29,24 @@ Additional entry points are available for focused imports:
 - `xo-harness/provider`
 - `xo-harness/provider/workers`
 - `xo-harness/storage`
+- `xo-harness/storage/memory` (portable, without Node JSONL persistence)
+- `xo-harness/skills` (catalogs, bundled skills, and on-demand reading tools)
+- `xo-harness/skills/node` (filesystem discovery)
+- `xo-harness/tools/openai` (web search and background reasoning with `createOpenAITools`)
 - `xo-harness/testing`
 
+Skills follow the standard `SKILL.md` format. Compose `createSkillTools(skills)` with your application
+tools; reads use the existing admission policy and durable event log. See the repository's
+[skills guide](https://github.com/zvadaadam/XO/blob/main/docs/skills.md) for usage and limits.
+
+`createOpenAITools({ apiKey })` adds sourced `web_search` and non-blocking `delegate` tools. The worker
+uses GPT-5.6 Terra with medium reasoning and reuses one worker conversation per XO session. Follow-ups
+queue and remember earlier tasks and results. The harness reports status/results and aborts outstanding
+work on session close. Voice and worker reasoning efforts are independent. See the
+[tools guide](https://github.com/zvadaadam/XO/blob/main/docs/tools.md) for configuration and limits.
+
+Tool results are delivered in full by default. `maxToolResultBytes` opts into string previews for
+oversized results; finite values must be integers of at least 128 bytes, excluding provider envelopes.
+
 See the [XO repository](https://github.com/zvadaadam/XO) for the complete documentation and voice
 application.

package/dist/internal/harness/index.d.ts

@@ -1,7 +1,10 @@
 export * from "./message.js";
 export * from "./report.js";
+export * from "./report-diff.js";
 export * from "./shadow.js";
 export * from "./socket-bridge.js";
+export * from "./tool-delivery.js";
+export * from "./tool-policy.js";
 export * from "./tools.js";
 export * from "./voice-session.js";
 export * from "./xo.js";

package/dist/internal/harness/index.js

@@ -1,7 +1,10 @@
 export * from "./message.js";
 export * from "./report.js";
+export * from "./report-diff.js";
 export * from "./shadow.js";
 export * from "./socket-bridge.js";
+export * from "./tool-delivery.js";
+export * from "./tool-policy.js";
 export * from "./tools.js";
 export * from "./voice-session.js";
 export * from "./xo.js";

package/dist/internal/harness/message.d.ts

@@ -9,8 +9,7 @@ import type { HarnessEvent, Message } from "../protocol/index.js";
  * Folding rules:
  *  - `message.input` → a user message; its recorded `parts` project with full fidelity
  *    (image/file parts become `file` parts), a bare-text input becomes one text part.
- *  - user `transcript` → a user message with one text part.
- *  - assistant `transcript.delta` → a `streaming` text part accumulating deltas,
+ *  - `transcript.delta` from either speaker → a `streaming` text part accumulating deltas,
  *    finalized in place by the matching `transcript` (streamId-correlated, so a
  *    barge-in interrupted stream still finalizes into its original part).
  *  - `audio.output` → an `audio` part on the current assistant message (deduped per

package/dist/internal/harness/message.js

@@ -1,3 +1,4 @@
+import { toolDenialError } from "./tool-policy.js";
 /**
  * Projects the flat, sequence-ordered event log into the v2 `Message[]` part model —
  * the shape every agent harness renders and persists (opencode / Vercel AI SDK v5 /
@@ -8,8 +9,7 @@
  * Folding rules:
  *  - `message.input` → a user message; its recorded `parts` project with full fidelity
  *    (image/file parts become `file` parts), a bare-text input becomes one text part.
- *  - user `transcript` → a user message with one text part.
- *  - assistant `transcript.delta` → a `streaming` text part accumulating deltas,
+ *  - `transcript.delta` from either speaker → a `streaming` text part accumulating deltas,
  *    finalized in place by the matching `transcript` (streamId-correlated, so a
  *    barge-in interrupted stream still finalizes into its original part).
  *  - `audio.output` → an `audio` part on the current assistant message (deduped per
@@ -32,9 +32,9 @@ export function projectMessages(events) {
     // streamId → the assistant message + audio part, so repeated chunks fold into one.
     const audioParts = new Map();
     // stream key → the streaming text part accumulating deltas, finalized by `transcript`.
-    // Deltas without a streamId key on the open assistant message, so a new message
-    // naturally starts a new default stream — no sentinel, no clearing.
     const textParts = new Map();
+    // Speakers can overlap even when a provider omits stream IDs.
+    const streamlessTextKeys = new Map();
     // Identity is the opening event: message id = event id, part id = event id + ordinal.
     const partBase = (message, event, ordinal = 0) => ({
         id: `${event.id}/p${ordinal}`,
@@ -69,15 +69,19 @@ export function projectMessages(events) {
                 break;
             }
             case "transcript.delta": {
-                if (event.role !== "assistant")
-                    break;
-                const message = assistantMessage(event);
-                const key = event.streamId ?? message.id;
-                const existing = textParts.get(key);
+                const activeKey = event.streamId === undefined
+                    ? streamlessTextKeys.get(event.role)
+                    : `${event.role}:${event.streamId}`;
+                const existing = activeKey === undefined ? undefined : textParts.get(activeKey);
                 if (existing) {
-                    existing.text += event.delta;
+                    if (existing.state === "streaming")
+                        existing.text += event.delta;
                     break;
                 }
+                const message = event.role === "assistant" ? assistantMessage(event) : openMessage("user", event);
+                const key = `${event.role}:${event.streamId ?? message.id}`;
+                if (event.streamId === undefined)
+                    streamlessTextKeys.set(event.role, key);
                 const part = {
                     ...partBase(message, event),
                     type: "text",
@@ -89,23 +93,31 @@ export function projectMessages(events) {
                 break;
             }
             case "transcript": {
-                if (event.role === "user") {
-                    const message = openMessage("user", event);
-                    message.parts.push({ ...partBase(message, event), type: "text", text: event.text, state: "done" });
-                    break;
-                }
                 // Finalize the streaming part these deltas were building, if any — even when a
                 // barge-in already moved the conversation on — else record a fresh done part.
-                const key = event.streamId ?? (current?.role === "assistant" ? current.id : undefined);
+                const key = event.streamId === undefined
+                    ? streamlessTextKeys.get(event.role)
+                    : `${event.role}:${event.streamId}`;
                 const streaming = key === undefined ? undefined : textParts.get(key);
                 if (key !== undefined && streaming !== undefined) {
                     streaming.text = event.text;
                     streaming.state = "done";
-                    textParts.delete(key);
+                    if (event.streamId === undefined) {
+                        textParts.delete(key);
+                        streamlessTextKeys.delete(event.role);
+                    }
                     break;
                 }
-                const message = assistantMessage(event);
-                message.parts.push({ ...partBase(message, event), type: "text", text: event.text, state: "done" });
+                const message = event.role === "assistant" ? assistantMessage(event) : openMessage("user", event);
+                const part = {
+                    ...partBase(message, event),
+                    type: "text",
+                    text: event.text,
+                    state: "done",
+                };
+                if (event.streamId !== undefined)
+                    textParts.set(`${event.role}:${event.streamId}`, part);
+                message.parts.push(part);
                 break;
             }
             case "audio.output": {
@@ -165,6 +177,20 @@ export function projectMessages(events) {
                 };
                 break;
             }
+            case "tool.denied": {
+                // Admission refusal settles the part like a failure; the log keeps the distinction.
+                const part = toolParts.get(event.callId);
+                if (part?.state.status !== "running")
+                    break;
+                part.state = {
+                    status: "settled",
+                    input: part.state.input,
+                    outcome: { type: "failed", error: toolDenialError(event.reason) },
+                    startedAtMs: part.state.startedAtMs,
+                    endedAtMs: event.recordedAtMs,
+                };
+                break;
+            }
             case "task.completed":
             case "task.failed":
             case "task.cancelled": {

package/dist/internal/harness/report-diff.d.ts

@@ -0,0 +1,46 @@
+import type { SessionReport, UsageTotals } from "./report.js";
+/** One metric compared across two reports; `delta` = candidate − baseline when both exist. */
+export interface MetricDelta {
+    baseline?: number;
+    candidate?: number;
+    delta?: number;
+}
+/** Per-tool-name comparison; a denial counts as a failure (its outcome is the delivered one). */
+export interface ToolCallDiff {
+    name: string;
+    baselineCalls: number;
+    candidateCalls: number;
+    baselineFailures: number;
+    candidateFailures: number;
+    meanLatencyMs: MetricDelta;
+}
+export interface SessionReportDiff {
+    baseline: {
+        sessionId: string;
+        providerId: string;
+        endedReason?: string;
+    };
+    candidate: {
+        sessionId: string;
+        providerId: string;
+        endedReason?: string;
+    };
+    durationMs: MetricDelta;
+    readyAtMs: MetricDelta;
+    responseLatencyMs: MetricDelta;
+    inputAudioMs: MetricDelta;
+    outputAudioMs: MetricDelta;
+    transcriptLines: MetricDelta;
+    errorCount: MetricDelta;
+    usage: Record<keyof UsageTotals, MetricDelta>;
+    /** Union of tool names from both reports, sorted, one row each. */
+    toolCalls: ToolCallDiff[];
+}
+/**
+ * Compares two session reports metric by metric — typically a recorded baseline against
+ * a `runShadowSession` re-drive of the same input at another provider (or another build).
+ * Pure and deterministic over its inputs, like the reports themselves. Numbers only:
+ * judging transcript *content* needs a semantic oracle (e.g. re-transcribing the PCM),
+ * which stays outside the harness.
+ */
+export declare function diffSessionReports(baseline: SessionReport, candidate: SessionReport): SessionReportDiff;

package/dist/internal/harness/report-diff.js

@@ -0,0 +1,62 @@
+/**
+ * Compares two session reports metric by metric — typically a recorded baseline against
+ * a `runShadowSession` re-drive of the same input at another provider (or another build).
+ * Pure and deterministic over its inputs, like the reports themselves. Numbers only:
+ * judging transcript *content* needs a semantic oracle (e.g. re-transcribing the PCM),
+ * which stays outside the harness.
+ */
+export function diffSessionReports(baseline, candidate) {
+    const usage = {};
+    for (const key of Object.keys(baseline.usage)) {
+        usage[key] = metric(baseline.usage[key], candidate.usage[key]);
+    }
+    const names = [...new Set([...baseline.toolCalls, ...candidate.toolCalls].map((call) => call.name))].sort();
+    return {
+        baseline: identity(baseline),
+        candidate: identity(candidate),
+        durationMs: metric(baseline.durationMs, candidate.durationMs),
+        readyAtMs: metric(baseline.readyAtMs, candidate.readyAtMs),
+        responseLatencyMs: metric(baseline.responseLatencyMs, candidate.responseLatencyMs),
+        inputAudioMs: metric(baseline.inputAudioMs, candidate.inputAudioMs),
+        outputAudioMs: metric(baseline.outputAudioMs, candidate.outputAudioMs),
+        transcriptLines: metric(baseline.transcripts.length, candidate.transcripts.length),
+        errorCount: metric(baseline.errors.length, candidate.errors.length),
+        usage,
+        toolCalls: names.map((name) => toolDiff(name, baseline.toolCalls, candidate.toolCalls)),
+    };
+}
+function identity(report) {
+    return {
+        sessionId: report.sessionId,
+        providerId: report.providerId,
+        ...(report.endedReason === undefined ? {} : { endedReason: report.endedReason }),
+    };
+}
+function toolDiff(name, baseline, candidate) {
+    const base = baseline.filter((call) => call.name === name);
+    const cand = candidate.filter((call) => call.name === name);
+    return {
+        name,
+        baselineCalls: base.length,
+        candidateCalls: cand.length,
+        baselineFailures: failures(base),
+        candidateFailures: failures(cand),
+        meanLatencyMs: metric(meanLatency(base), meanLatency(cand)),
+    };
+}
+function failures(calls) {
+    return calls.filter((call) => call.outcome?.type === "failed").length;
+}
+function meanLatency(calls) {
+    const latencies = calls.map((call) => call.latencyMs).filter((value) => value !== undefined);
+    if (latencies.length === 0)
+        return undefined;
+    return latencies.reduce((sum, value) => sum + value, 0) / latencies.length;
+}
+function metric(baseline, candidate) {
+    return {
+        ...(baseline === undefined ? {} : { baseline }),
+        ...(candidate === undefined ? {} : { candidate }),
+        ...(baseline === undefined || candidate === undefined ? {} : { delta: candidate - baseline }),
+    };
+}

package/dist/internal/harness/report.d.ts

@@ -6,6 +6,8 @@ export interface ToolCallReport {
     requestedAtMs: number;
     outcome?: ToolOutcome;
     latencyMs?: number;
+    /** Present when the admission policy refused the call; `outcome` is the delivered failure. */
+    deniedReason?: string;
 }
 export interface TranscriptLine {
     role: "user" | "assistant";

package/dist/internal/harness/report.js

@@ -1,4 +1,5 @@
 import { audioSampleCount } from "../protocol/index.js";
+import { toolDenialError } from "./tool-policy.js";
 /**
  * Derives latency and outcome metrics from a session log. Pure over the recorded events,
  * so it works identically on live sessions, replays, and shadow runs.
@@ -80,6 +81,15 @@ export function summarizeSession(events) {
                 }
                 break;
             }
+            case "tool.denied": {
+                const call = toolCalls.get(event.callId);
+                if (call) {
+                    call.outcome = { type: "failed", error: toolDenialError(event.reason) };
+                    call.latencyMs = event.sessionTimeMs - call.requestedAtMs;
+                    call.deniedReason = event.reason;
+                }
+                break;
+            }
             case "task.accepted":
                 taskIds.add(event.taskId);
                 break;

package/dist/internal/harness/shadow.d.ts

@@ -1,15 +1,20 @@
 import type { HarnessEvent } from "../protocol/index.js";
 import type { VoiceProvider } from "../provider/index.js";
-import { type EventStore } from "../storage/index.js";
+import { type EventStore } from "../storage/memory.js";
 import { type SessionReport } from "./report.js";
+import type { ToolPolicy } from "./tool-policy.js";
 import type { VoiceTool } from "./tools.js";
 export interface ShadowRunOptions {
     /** The recorded session whose microphone audio is re-driven. */
     events: readonly HarnessEvent[];
     /** The provider to shadow-test with the recorded input. */
     provider: VoiceProvider;
-    /** Tools to expose; usually the same implementations the original session had. */
+    /** Tools to execute during the shadow run; use substitutes when side effects are unwanted. */
     tools?: readonly VoiceTool[];
+    /** Admission for this run. Defaults to allow-all; never inferred from the recorded log. */
+    toolPolicy?: ToolPolicy;
+    /** Byte budget for delivered results in this run; follows the normal session default. */
+    maxToolResultBytes?: number;
     /** Where the shadow session records. Defaults to an in-memory store. */
     store?: EventStore;
     sessionId?: string;
@@ -22,6 +27,8 @@ export interface ShadowRunOptions {
 /**
  * The silent-test primitive: re-drives a recorded session's input audio against another
  * provider and returns the resulting session report for comparison with the original.
+ * The shadow run executes supplied tools and applies only the policy provided here;
+ * a recording's denials do not establish permissions for a new session.
  * Input is sent as fast as the provider accepts it; server-side VAD sees the recorded
  * speech and trailing silence exactly as the original session did.
  */

package/dist/internal/harness/shadow.js

@@ -1,9 +1,11 @@
-import { MemoryEventStore } from "../storage/index.js";
+import { MemoryEventStore } from "../storage/memory.js";
 import { summarizeSession } from "./report.js";
 import { XO } from "./xo.js";
 /**
  * The silent-test primitive: re-drives a recorded session's input audio against another
  * provider and returns the resulting session report for comparison with the original.
+ * The shadow run executes supplied tools and applies only the policy provided here;
+ * a recording's denials do not establish permissions for a new session.
  * Input is sent as fast as the provider accepts it; server-side VAD sees the recorded
  * speech and trailing silence exactly as the original session did.
  */
@@ -18,6 +20,8 @@ export async function runShadowSession(options) {
     const harness = new XO({
         store: options.store ?? new MemoryEventStore(),
         ...(options.tools === undefined ? {} : { tools: options.tools }),
+        ...(options.toolPolicy === undefined ? {} : { toolPolicy: options.toolPolicy }),
+        ...(options.maxToolResultBytes === undefined ? {} : { maxToolResultBytes: options.maxToolResultBytes }),
     });
     const session = await harness.startSession({
         provider: options.provider,

package/dist/internal/harness/task-supervisor.js

@@ -16,7 +16,7 @@ export class TaskSupervisor {
     }
     forCall(callId) {
         return {
-            start: (runner) => this.#register(callId, runner),
+            start: (runner, options) => this.#register(callId, runner, options),
         };
     }
     async activate(taskId, callId) {
@@ -43,6 +43,7 @@ export class TaskSupervisor {
         this.#tasks.delete(taskId);
         task.detachSessionAbort();
         task.controller.abort(reason);
+        this.#releasePending(task);
         await this.#settle({ type: "task.cancelled", taskId, callId, reason }, false);
         return true;
     }
@@ -54,6 +55,7 @@ export class TaskSupervisor {
                 this.#tasks.delete(taskId);
                 task.detachSessionAbort();
                 task.controller.abort(reason);
+                this.#releasePending(task);
                 pendingCancellations.push(this.#settle({ type: "task.cancelled", taskId, callId: task.callId, reason }, true).then(() => undefined));
             }
             else {
@@ -64,27 +66,40 @@ export class TaskSupervisor {
         }
         await Promise.allSettled([...pendingCancellations, ...running]);
     }
-    async #register(callId, runner) {
+    #releasePending(task) {
+        try {
+            task.onPendingCancel?.();
+        }
+        catch (error) {
+            this.#onError(error);
+        }
+    }
+    async #register(callId, runner, options) {
         if (this.#sessionSignal.aborted)
             throw new Error("Session is closing");
         const taskId = crypto.randomUUID();
         const controller = new AbortController();
         const abortFromSession = () => controller.abort(this.#sessionSignal.reason);
         this.#sessionSignal.addEventListener("abort", abortFromSession, { once: true });
-        this.#tasks.set(taskId, {
+        const task = {
             callId,
             controller,
             runner,
+            onPendingCancel: options?.onPendingCancel,
             state: "pending",
             detachSessionAbort: () => this.#sessionSignal.removeEventListener("abort", abortFromSession),
-        });
+        };
+        this.#tasks.set(taskId, task);
         try {
             await this.#record({ type: "task.accepted", taskId, callId });
         }
         catch (error) {
-            this.#tasks.delete(taskId);
-            this.#sessionSignal.removeEventListener("abort", abortFromSession);
+            // Cancellation may already have released the reservation while recording waited.
+            const removed = this.#tasks.delete(taskId);
+            task.detachSessionAbort();
             controller.abort("task_acceptance_failed");
+            if (removed)
+                this.#releasePending(task);
             throw error;
         }
         return taskId;

package/dist/internal/harness/tool-delivery.d.ts

@@ -0,0 +1,17 @@
+import type { ToolOutcome } from "../protocol/index.js";
+/**
+ * Results are delivered in full by default. Hosts can opt into a finite byte budget
+ * to limit model context; the durable log always keeps the full outcome.
+ */
+export declare const DEFAULT_MAX_TOOL_RESULT_BYTES: number;
+/** Finite budgets must leave room for the preview marker and JSON encoding. */
+export declare function validateMaxToolResultBytes(maxBytes: number): void;
+/**
+ * Bounds the UTF-8 JSON encoding of a completed value or failure string, excluding
+ * provider-specific envelopes. Accepted task handles are unchanged. Finite budgets
+ * must be integers of at least 128 bytes; Infinity disables truncation.
+ *
+ * An oversized payload becomes a prefix of its JSON representation plus a marker
+ * identifying the source byte count. Only the provider-bound copy changes.
+ */
+export declare function boundToolOutcomeForDelivery(outcome: ToolOutcome, maxBytes: number): ToolOutcome;

package/dist/internal/harness/tool-delivery.js

@@ -0,0 +1,53 @@
+/**
+ * Results are delivered in full by default. Hosts can opt into a finite byte budget
+ * to limit model context; the durable log always keeps the full outcome.
+ */
+export const DEFAULT_MAX_TOOL_RESULT_BYTES = Number.POSITIVE_INFINITY;
+/** Finite budgets must leave room for the preview marker and JSON encoding. */
+export function validateMaxToolResultBytes(maxBytes) {
+    if (maxBytes !== Number.POSITIVE_INFINITY && (!Number.isInteger(maxBytes) || maxBytes < 128)) {
+        throw new RangeError("maxToolResultBytes must be an integer of at least 128 bytes or Infinity");
+    }
+}
+/**
+ * Bounds the UTF-8 JSON encoding of a completed value or failure string, excluding
+ * provider-specific envelopes. Accepted task handles are unchanged. Finite budgets
+ * must be integers of at least 128 bytes; Infinity disables truncation.
+ *
+ * An oversized payload becomes a prefix of its JSON representation plus a marker
+ * identifying the source byte count. Only the provider-bound copy changes.
+ */
+export function boundToolOutcomeForDelivery(outcome, maxBytes) {
+    validateMaxToolResultBytes(maxBytes);
+    if (maxBytes === Number.POSITIVE_INFINITY || outcome.type === "accepted_task")
+        return outcome;
+    const serialized = JSON.stringify(outcome.type === "completed" ? outcome.value : outcome.error);
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(serialized);
+    if (bytes.byteLength <= maxBytes)
+        return outcome;
+    // The preview is itself delivered as a JSON string. Include its escaping and the
+    // widest possible marker when finding a prefix, not just the source's raw bytes.
+    const suffix = marker(maxBytes, bytes.byteLength);
+    let low = 0;
+    let high = Math.min(maxBytes, bytes.byteLength);
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        const candidate = decodeUtf8Prefix(bytes, middle) + suffix;
+        if (encoder.encode(JSON.stringify(candidate)).byteLength <= maxBytes)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    const preview = decodeUtf8Prefix(bytes, low);
+    const text = preview + marker(encoder.encode(preview).byteLength, bytes.byteLength);
+    return outcome.type === "completed" ? { type: "completed", value: text } : { type: "failed", error: text };
+}
+function marker(shown, total) {
+    return `\n[truncated for delivery: showing the first ${shown} of ${total} bytes]`;
+}
+function decodeUtf8Prefix(bytes, byteLength) {
+    // Streaming decode withholds an incomplete trailing codepoint while preserving
+    // genuine U+FFFD characters already present in the source.
+    return new TextDecoder().decode(bytes.subarray(0, byteLength), { stream: true });
+}

package/dist/internal/harness/tool-policy.d.ts

@@ -0,0 +1,52 @@
+import type { HarnessEvent, ToolCall } from "../protocol/index.js";
+import type { ToolAnnotations } from "./tools.js";
+/** Everything a policy may consult when admitting one tool call. */
+export interface ToolAdmissionContext {
+    readonly call: ToolCall;
+    /** Behavior hints of the registered tool; absent when the call names an unknown tool. */
+    readonly annotations?: ToolAnnotations;
+    /**
+     * Aborts when the session closes. A policy that awaits external input — a client
+     * approval round-trip (e.g. ACP `session/request_permission`), a reviewer model —
+     * must abandon its work when this fires; the runtime stops waiting either way.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * The durable session log so far — e.g. transcript evidence that the user asked for
+     * this. Reads the store (audio events included), so call it only when a decision
+     * needs it, and project with `projectMessages` rather than scanning raw events.
+     */
+    history(): Promise<readonly HarnessEvent[]>;
+}
+export type ToolAdmission = {
+    decision: "allow";
+} | {
+    decision: "deny";
+    reason: string;
+};
+/**
+ * Admits or refuses model-requested tool calls before execution begins. A refusal is
+ * not a dead end: it is recorded as `tool.denied` and delivered to the provider as a
+ * failed outcome carrying the reason, so the model can revise its plan or ask the user
+ * out loud — in a voice session, permission conversations happen in the conversation.
+ * A policy that throws or returns a malformed decision refuses the call (the gate
+ * fails closed). Denials need a nonblank reason. Policies decide admission only;
+ * argument validation and execution stay in the tool runtime.
+ */
+export interface ToolPolicy {
+    admit(context: ToolAdmissionContext): ToolAdmission | Promise<ToolAdmission>;
+}
+/** The default policy: every requested tool executes. Preserves pre-policy behavior. */
+export declare const allowAllToolPolicy: ToolPolicy;
+export interface ToolPolicyRules {
+    /** Tool names that always execute. */
+    allow?: readonly string[];
+    /** Tool names that are always refused. A name on both lists is refused. */
+    deny?: readonly string[];
+    /** Decision for names on neither list. Default: "allow". */
+    otherwise?: "allow" | "deny";
+}
+/** A deterministic name-list policy; richer policies implement `ToolPolicy` directly. */
+export declare function toolPolicyFromRules(rules: ToolPolicyRules): ToolPolicy;
+/** The canonical rendering of a denial as a failed outcome, shared by delivery and projections. */
+export declare function toolDenialError(reason: string): string;

package/dist/internal/harness/tool-policy.js

@@ -0,0 +1,22 @@
+/** The default policy: every requested tool executes. Preserves pre-policy behavior. */
+export const allowAllToolPolicy = { admit: () => ({ decision: "allow" }) };
+/** A deterministic name-list policy; richer policies implement `ToolPolicy` directly. */
+export function toolPolicyFromRules(rules) {
+    const allow = new Set(rules.allow ?? []);
+    const deny = new Set(rules.deny ?? []);
+    const otherwise = rules.otherwise ?? "allow";
+    return {
+        admit: ({ call }) => {
+            if (deny.has(call.name)) {
+                return { decision: "deny", reason: `Tool "${call.name}" is denied by session policy.` };
+            }
+            if (allow.has(call.name) || otherwise === "allow")
+                return { decision: "allow" };
+            return { decision: "deny", reason: `Tool "${call.name}" is not on the session's allow list.` };
+        },
+    };
+}
+/** The canonical rendering of a denial as a failed outcome, shared by delivery and projections. */
+export function toolDenialError(reason) {
+    return `Tool call denied: ${reason}`;
+}

package/dist/internal/harness/tool-runtime.d.ts

@@ -1,5 +1,6 @@
 import { type HarnessEvent, type NewHarnessEvent, type ProviderToolResult, type ToolCall } from "../protocol/index.js";
 import type { TaskSupervisor } from "./task-supervisor.js";
+import { type ToolPolicy } from "./tool-policy.js";
 import type { ToolRegistry } from "./tools.js";
 type RecordEvent = (event: NewHarnessEvent) => Promise<HarnessEvent>;
 export interface ToolResultSink {
@@ -14,6 +15,9 @@ export declare class ToolRuntime {
         resultSink: ToolResultSink;
         signal: AbortSignal;
         flush: () => Promise<void>;
+        policy: ToolPolicy;
+        history: () => Promise<readonly HarnessEvent[]>;
+        maxResultBytes: number;
     });
     execute(call: ToolCall): Promise<void>;
 }