@celestea/tools 2.7.1

package/dist/builtin.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The six builtin tools (`crates/tools/src/builtin.rs`): `read_file`,
+ * `write_file`, `list_dir`, `run_shell`, `process_control`, `http_request`.
+ *
+ * One `ProcessRegistry` and one `Sandbox` are shared by `run_shell` /
+ * `process_control` within a tool set, so a background process started in one
+ * call is controllable from the next. Embeddings that mount several tool sets
+ * pass `builtinTools({ processes, sandbox })` a shared pair.
+ *
+ * W783: `ask_user_question` is mounted here too when the caller supplies the
+ * user-question service. It is NOT one of the six builtins, and it is
+ * OPTIONAL: `packages/tools` may only depend on `@celestea/core`, so the service
+ * arrives by construction and an embedding that has no human answerer simply
+ * leaves `questions` out instead of registering a tool that can never work.
+ */
+import type { Sandbox, Tool, UserQuestionService } from "@celestea/core";
+import { type HttpRequestToolOptions } from "./tools/http-request.js";
+import type { AttachmentStore } from "./attachments/store.js";
+import { ProcessRegistry } from "./process/registry.js";
+export interface BuiltinToolsOptions {
+    sandbox?: Sandbox;
+    processes?: ProcessRegistry;
+    http?: HttpRequestToolOptions;
+    /**
+     * W783: the host's user-question service. Present = `ask_user_question` is
+     * registered (11 tools); absent = it is not (the frozen 10).
+     */
+    questions?: UserQuestionService | null;
+    /**
+     * W804: the session's attachment store. Present = `read_image` is mounted
+     * (12 tools); absent = the tool is not offered, so the model is never told it
+     * exists (the same "register only what works" rule as ask_user_question).
+     */
+    attachments?: AttachmentStore | null;
+    /**
+     * W804: false ONLY when the target model's input_modalities was explicitly
+     * configured without "image" (section 6.6). Absent/true = optimistic default.
+     */
+    imageInputAllowed?: boolean;
+    /** W804: the model id, for the read_image refusal text. */
+    model?: string;
+    /**
+     * W884: the composing SESSION's workspace root for `load_skill` (W768's
+     * `sessionWorkspaceOf` — the single source of truth). `null`/absent = a
+     * generation with no workspace (the detached default); the tool is still
+     * REGISTERED so every face advertises the same names, and a call fails with a
+     * structured `no_workspace` error instead of guessing a path.
+     */
+    workspace?: string | null;
+    /** W884: environment the CELESTEA_HOME global skill layer resolves under. */
+    env?: NodeJS.ProcessEnv;
+}
+/** The six builtins, sharing one sandbox + one process registry. */
+export declare function builtinTools(options?: BuiltinToolsOptions): Tool[];

package/dist/builtin.js

@@ -0,0 +1,77 @@
+/**
+ * The six builtin tools (`crates/tools/src/builtin.rs`): `read_file`,
+ * `write_file`, `list_dir`, `run_shell`, `process_control`, `http_request`.
+ *
+ * One `ProcessRegistry` and one `Sandbox` are shared by `run_shell` /
+ * `process_control` within a tool set, so a background process started in one
+ * call is controllable from the next. Embeddings that mount several tool sets
+ * pass `builtinTools({ processes, sandbox })` a shared pair.
+ *
+ * W783: `ask_user_question` is mounted here too when the caller supplies the
+ * user-question service. It is NOT one of the six builtins, and it is
+ * OPTIONAL: `packages/tools` may only depend on `@celestea/core`, so the service
+ * arrives by construction and an embedding that has no human answerer simply
+ * leaves `questions` out instead of registering a tool that can never work.
+ */
+import { askUserTool } from "./tools/ask-user.js";
+import { httpRequestTool } from "./tools/http-request.js";
+import { listDirTool } from "./tools/list-dir.js";
+import { processControlTool } from "./tools/process-control.js";
+import { loadSkillTool } from "./tools/load-skill.js";
+import { forgetTool, rememberTool } from "./tools/memory.js";
+import { readImageTool } from "./tools/read-image.js";
+import { readFileTool } from "./tools/read-file.js";
+import { browserActTool, browserOpenTool } from "./tools/browser.js";
+import { BrowserManager } from "./browser/session.js";
+import { runShellTool } from "./tools/run-shell.js";
+import { writeFileTool } from "./tools/write-file.js";
+import { ProcessRegistry } from "./process/registry.js";
+import { selectSandbox } from "./sandbox/provider.js";
+/** The six builtins, sharing one sandbox + one process registry. */
+export function builtinTools(options = {}) {
+    const processes = options.processes ?? new ProcessRegistry();
+    const sandbox = options.sandbox ?? selectSandbox();
+    const tools = [
+        readFileTool(),
+        writeFileTool(),
+        listDirTool(),
+        runShellTool({ sandbox, processes }),
+        processControlTool(processes),
+        httpRequestTool(options.http ?? {}),
+        // W884: the 7th builtin — always mounted so the model face cannot drift
+        // between the detached default generation and a real session.
+        loadSkillTool({
+            workspace: options.workspace ?? null,
+            ...(options.env === undefined ? {} : { env: options.env }),
+        }),
+        // B2 (F3 P1): the memory write pair. HOST tools like load_skill: the global
+        // memory layer lives OUTSIDE the workspace (so the path guard cannot reach
+        // it), and a generation with no workspace still advertises the names and
+        // fails closed with no_workspace on a call.
+        rememberTool({
+            workspace: options.workspace ?? null,
+            ...(options.env === undefined ? {} : { env: options.env }),
+        }),
+        forgetTool({
+            workspace: options.workspace ?? null,
+            ...(options.env === undefined ? {} : { env: options.env }),
+        }),
+    ];
+    // W783: only when a human answerer actually exists in this host.
+    if (options.questions !== undefined && options.questions !== null)
+        tools.push(askUserTool({ questions: options.questions }));
+    // W804: only when the session has an attachment store to read from / write to.
+    if (options.attachments !== undefined && options.attachments !== null) {
+        tools.push(readImageTool({
+            attachments: options.attachments,
+            imageInputAllowed: options.imageInputAllowed ?? true,
+            ...(options.model === undefined ? {} : { model: options.model }),
+        }));
+        // F4 step 2b: the browser tools need the SAME session attachment store
+        // (the screenshot rides the existing image chain) and share ONE manager, so
+        // browser_open and browser_act drive the same page and process.
+        const manager = new BrowserManager({ sandbox, processes, attachments: options.attachments });
+        tools.push(browserOpenTool({ manager }), browserActTool({ manager }));
+    }
+    return tools;
+}

package/dist/desc.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `desc` UI-label parameter (W779 T1).
+ *
+ * EVERY tool takes one optional `desc` string: a one-line label describing what
+ * this particular call is doing, which the UI shows on the tool card. It is
+ * pure presentation:
+ *   - no executor reads it (nothing but the specs mentions `desc`), so a call
+ *     behaves exactly the same with or without it;
+ *   - the schema declares it as a plain optional `string` — deliberately NO
+ *     `maxLength`, because the 80-character budget is a display concern and the
+ *     dispatch validator is a frozen subset (`schema.ts`); a long label must
+ *     never turn a working call into `toolargs: code=schema`.
+ *
+ * The text is shared so the 7 builtin specs and `contracts/tools.json` cannot
+ * drift word by word; `tests/contract-parity.test.ts` compares them all.
+ */
+/** The one-line contract text of the `desc` parameter. */
+export declare const DESC_DESCRIPTION = "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short.";
+/** A fresh `desc` property schema (never share the object: specs are values). */
+export declare function descParam(): Record<string, unknown>;

package/dist/desc.js

@@ -0,0 +1,22 @@
+/**
+ * The `desc` UI-label parameter (W779 T1).
+ *
+ * EVERY tool takes one optional `desc` string: a one-line label describing what
+ * this particular call is doing, which the UI shows on the tool card. It is
+ * pure presentation:
+ *   - no executor reads it (nothing but the specs mentions `desc`), so a call
+ *     behaves exactly the same with or without it;
+ *   - the schema declares it as a plain optional `string` — deliberately NO
+ *     `maxLength`, because the 80-character budget is a display concern and the
+ *     dispatch validator is a frozen subset (`schema.ts`); a long label must
+ *     never turn a working call into `toolargs: code=schema`.
+ *
+ * The text is shared so the 7 builtin specs and `contracts/tools.json` cannot
+ * drift word by word; `tests/contract-parity.test.ts` compares them all.
+ */
+/** The one-line contract text of the `desc` parameter. */
+export const DESC_DESCRIPTION = "Optional one-line label (max 80 chars) describing what this call is doing; shown on the tool card in the UI. Keep it short.";
+/** A fresh `desc` property schema (never share the object: specs are values). */
+export function descParam() {
+    return { type: "string", description: DESC_DESCRIPTION };
+}

package/dist/disclosure.d.ts

@@ -0,0 +1,113 @@
+/**
+ * W806 (P0) — dynamic tool disclosure: the cache-safe second hidden layer.
+ *
+ * `exposedRegistry` already owns the MODE fold (a static keep list). This module
+ * adds the layer the design doc (`docs/feature-dynamic-tool-disclosure.md` §7.1)
+ * calls for on top of it: a policy that withholds part of the mode's disclosable
+ * universe and reveals it ONE TURN AT A TIME.
+ *
+ * The whole point is the upstream cache. The provider is billed on a strict
+ * token BYTE PREFIX (`system -> tools -> messages`), so a change in the middle
+ * of the tools array invalidates every cached token after it — including the
+ * whole conversation history. These three invariants are therefore policy, not
+ * taste (design §3.5):
+ *
+ *   1. **monotonic** — a name disclosed in this session is never taken back;
+ *   2. **tail-append** — a newly disclosed name is appended AFTER every name
+ *      already on the wire, never inserted into the middle;
+ *   3. **turn boundary** — only `beginTurn()` changes the set. A refused call
+ *      during a turn is only a PROPOSAL; the next turn is the first one that
+ *      sees it (the design's "被拒后披露" trigger, Q1).
+ *
+ * Nothing here is authorization: the policy only decides what the model is
+ * OFFERED. A withheld tool still runs the same guard chain when reached from a
+ * `run_code` program, and a direct call is refused before execution.
+ */
+import { type ExposureOptions } from "./exposure.js";
+/** One immutable view of the policy (diagnostics / assertions). */
+export interface DisclosureSnapshot {
+    /** Offered names, in stable disclosure order (baseline ++ first-disclosure). */
+    readonly disclosed: readonly string[];
+    /** Refused names, in universe order (blocked fold ∪ not-yet-disclosed). */
+    readonly hidden: readonly string[];
+}
+export interface DisclosurePolicyOptions {
+    /** Every registered tool name, in the baseline wire order. */
+    universe: readonly string[];
+    /**
+     * Names offered from the start. Default: the whole non-blocked universe,
+     * which is exactly today's mode baseline (so the default is a no-op).
+     */
+    initial?: readonly string[];
+    /** Names that must NEVER be disclosed — the static mode fold it may not undo. */
+    blocked?: readonly string[];
+}
+/**
+ * The disclosure state of ONE session generation.
+ *
+ * Mutable by design (the live face has to move at a turn boundary), but every
+ * reader gets a fresh array from `disclosed()`/`hidden()`, so a reader can
+ * never observe a half-applied change: `beginTurn()` builds the promoted list
+ * before it publishes anything.
+ */
+export declare class DisclosurePolicy {
+    private readonly universe;
+    private readonly universeSet;
+    private readonly blocked;
+    /** The fixed initial face, in its given order (never reordered afterwards). */
+    private readonly baseline;
+    private readonly baselineSet;
+    /** Names appended by a turn boundary, in first-disclosure order. */
+    private readonly added;
+    private readonly addedSet;
+    /** Refused-but-disclosable names seen since the last turn boundary. */
+    private readonly pending;
+    private readonly pendingSet;
+    constructor(options: DisclosurePolicyOptions);
+    /**
+     * The names this face offers, in stable disclosure order: the initial
+     * baseline first (its own order), then every name a turn boundary appended,
+     * in first-disclosure order. Append-only by construction.
+     */
+    disclosed(): string[];
+    /**
+     * The names this face refuses: the mode fold ∪ everything not yet disclosed,
+     * in universe order. Reading it is a pure function of the current state.
+     */
+    hidden(): string[];
+    /** The names a `{{tools}}` rendering may announce (the static universe). */
+    universeNames(): string[];
+    /** Is `name` part of the static mode fold (never disclosable)? */
+    isBlocked(name: string): boolean;
+    /** Is anything withheld that could still be disclosed? */
+    get active(): boolean;
+    /**
+     * Record a DIRECT call the face refused because `name` was not disclosed.
+     * This is only a proposal: it changes nothing until [beginTurn]. Returns true
+     * when the name was accepted as a proposal (known, disclosable, not already
+     * offered or pending).
+     */
+    propose(name: string): boolean;
+    /**
+     * The turn boundary: promote every proposal recorded since the previous call.
+     * Monotonic (nothing is ever removed) and tail-appending (promotion order is
+     * first-proposal order). Returns the names DISCLOSED by this call — empty
+     * means the wire array is unchanged and no cache prefix is invalidated.
+     */
+    beginTurn(): string[];
+    /** One immutable view of this policy. */
+    snapshot(): DisclosureSnapshot;
+}
+/** The per-name guidance pair a dynamic face needs (mode fold vs withheld). */
+export interface DisclosureGuidance {
+    /** Prose for a name folded by the MODE (default [EXECUTION_GUIDANCE]). */
+    folded?: string;
+    /** Prose for a name merely not yet disclosed (default [DISCLOSURE_GUIDANCE]). */
+    withheld?: string;
+}
+/**
+ * The [ExposureOptions] of a dynamic face: `hidden`/`order` read the policy live,
+ * a refused direct call becomes a proposal, and each refusal gets the prose that
+ * fits WHY the name is hidden (the mode fold vs merely not-yet-disclosed).
+ */
+export declare function disclosureExposure(policy: DisclosurePolicy, guidance?: DisclosureGuidance): ExposureOptions;

package/dist/disclosure.js

@@ -0,0 +1,141 @@
+/**
+ * W806 (P0) — dynamic tool disclosure: the cache-safe second hidden layer.
+ *
+ * `exposedRegistry` already owns the MODE fold (a static keep list). This module
+ * adds the layer the design doc (`docs/feature-dynamic-tool-disclosure.md` §7.1)
+ * calls for on top of it: a policy that withholds part of the mode's disclosable
+ * universe and reveals it ONE TURN AT A TIME.
+ *
+ * The whole point is the upstream cache. The provider is billed on a strict
+ * token BYTE PREFIX (`system -> tools -> messages`), so a change in the middle
+ * of the tools array invalidates every cached token after it — including the
+ * whole conversation history. These three invariants are therefore policy, not
+ * taste (design §3.5):
+ *
+ *   1. **monotonic** — a name disclosed in this session is never taken back;
+ *   2. **tail-append** — a newly disclosed name is appended AFTER every name
+ *      already on the wire, never inserted into the middle;
+ *   3. **turn boundary** — only `beginTurn()` changes the set. A refused call
+ *      during a turn is only a PROPOSAL; the next turn is the first one that
+ *      sees it (the design's "被拒后披露" trigger, Q1).
+ *
+ * Nothing here is authorization: the policy only decides what the model is
+ * OFFERED. A withheld tool still runs the same guard chain when reached from a
+ * `run_code` program, and a direct call is refused before execution.
+ */
+import { DISCLOSURE_GUIDANCE, EXECUTION_GUIDANCE } from "./exposure.js";
+/**
+ * The disclosure state of ONE session generation.
+ *
+ * Mutable by design (the live face has to move at a turn boundary), but every
+ * reader gets a fresh array from `disclosed()`/`hidden()`, so a reader can
+ * never observe a half-applied change: `beginTurn()` builds the promoted list
+ * before it publishes anything.
+ */
+export class DisclosurePolicy {
+    universe;
+    universeSet;
+    blocked;
+    /** The fixed initial face, in its given order (never reordered afterwards). */
+    baseline;
+    baselineSet;
+    /** Names appended by a turn boundary, in first-disclosure order. */
+    added = [];
+    addedSet = new Set();
+    /** Refused-but-disclosable names seen since the last turn boundary. */
+    pending = [];
+    pendingSet = new Set();
+    constructor(options) {
+        this.universe = [...options.universe];
+        this.universeSet = new Set(this.universe);
+        this.blocked = new Set(options.blocked ?? []);
+        const wanted = options.initial ?? this.universe;
+        this.baseline = wanted.filter((name) => this.universeSet.has(name) && !this.blocked.has(name));
+        this.baselineSet = new Set(this.baseline);
+    }
+    /**
+     * The names this face offers, in stable disclosure order: the initial
+     * baseline first (its own order), then every name a turn boundary appended,
+     * in first-disclosure order. Append-only by construction.
+     */
+    disclosed() {
+        return [...this.baseline, ...this.added];
+    }
+    /**
+     * The names this face refuses: the mode fold ∪ everything not yet disclosed,
+     * in universe order. Reading it is a pure function of the current state.
+     */
+    hidden() {
+        const offered = new Set(this.disclosed());
+        return this.universe.filter((name) => this.blocked.has(name) || !offered.has(name));
+    }
+    /** The names a `{{tools}}` rendering may announce (the static universe). */
+    universeNames() {
+        return [...this.universe];
+    }
+    /** Is `name` part of the static mode fold (never disclosable)? */
+    isBlocked(name) {
+        return this.blocked.has(name);
+    }
+    /** Is anything withheld that could still be disclosed? */
+    get active() {
+        return this.hidden().some((name) => !this.blocked.has(name));
+    }
+    /**
+     * Record a DIRECT call the face refused because `name` was not disclosed.
+     * This is only a proposal: it changes nothing until [beginTurn]. Returns true
+     * when the name was accepted as a proposal (known, disclosable, not already
+     * offered or pending).
+     */
+    propose(name) {
+        if (!this.universeSet.has(name))
+            return false;
+        if (this.blocked.has(name))
+            return false;
+        if (this.baselineSet.has(name) || this.addedSet.has(name))
+            return false;
+        if (this.pendingSet.has(name))
+            return false;
+        this.pendingSet.add(name);
+        this.pending.push(name);
+        return true;
+    }
+    /**
+     * The turn boundary: promote every proposal recorded since the previous call.
+     * Monotonic (nothing is ever removed) and tail-appending (promotion order is
+     * first-proposal order). Returns the names DISCLOSED by this call — empty
+     * means the wire array is unchanged and no cache prefix is invalidated.
+     */
+    beginTurn() {
+        const promoted = [];
+        for (const name of this.pending) {
+            if (this.addedSet.has(name))
+                continue;
+            this.addedSet.add(name);
+            this.added.push(name);
+            promoted.push(name);
+        }
+        this.pending.length = 0;
+        this.pendingSet.clear();
+        return promoted;
+    }
+    /** One immutable view of this policy. */
+    snapshot() {
+        return { disclosed: this.disclosed(), hidden: this.hidden() };
+    }
+}
+/**
+ * The [ExposureOptions] of a dynamic face: `hidden`/`order` read the policy live,
+ * a refused direct call becomes a proposal, and each refusal gets the prose that
+ * fits WHY the name is hidden (the mode fold vs merely not-yet-disclosed).
+ */
+export function disclosureExposure(policy, guidance = {}) {
+    const folded = guidance.folded ?? EXECUTION_GUIDANCE;
+    const withheld = guidance.withheld ?? DISCLOSURE_GUIDANCE;
+    return {
+        hidden: () => policy.hidden(),
+        order: () => policy.disclosed(),
+        guidanceFor: (name) => (policy.isBlocked(name) ? folded : withheld),
+        onHidden: (name) => void policy.propose(name),
+    };
+}

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Environment helpers shared by the guard, the http policy and the sandbox
+ * config. Env is always passed in explicitly (default `process.env`) so every
+ * knob is testable without mutating global state.
+ */
+/** One env knob: read a string, a positive integer, or an on/off flag. */
+export declare function envString(env: NodeJS.ProcessEnv, name: string): string | undefined;
+export declare function envInt(env: NodeJS.ProcessEnv, name: string): number | undefined;
+/** On/off flag (`1/true/on/yes` vs `0/false/off/no`); anything else = fallback. */
+export declare function envFlag(value: string | undefined, fallback: boolean): boolean;

package/dist/env.js

@@ -0,0 +1,33 @@
+/**
+ * Environment helpers shared by the guard, the http policy and the sandbox
+ * config. Env is always passed in explicitly (default `process.env`) so every
+ * knob is testable without mutating global state.
+ */
+/** One env knob: read a string, a positive integer, or an on/off flag. */
+export function envString(env, name) {
+    const raw = env[name];
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+export function envInt(env, name) {
+    const raw = envString(env, name);
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? Math.trunc(parsed) : undefined;
+}
+/** On/off flag (`1/true/on/yes` vs `0/false/off/no`); anything else = fallback. */
+export function envFlag(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "")
+        return fallback;
+    if (["1", "true", "on", "yes"].includes(normalized))
+        return true;
+    if (["0", "false", "off", "no"].includes(normalized))
+        return false;
+    return fallback;
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Structured tool-pipeline errors.
+ *
+ * The pipeline never throws across the `Tool` seam: a tool rejects with a
+ * `ToolFailure` whose `message` is the machine-readable contract string
+ * `<prefix>: code=<code> msg="<quoted>"` (parity: `toolguard: …`,
+ * `run_shell-sandbox: …`, `http_request: code=…`), and the registry captures it
+ * into `ToolOutput.error`. Callers branch on `kind`/`code`, never on prose.
+ */
+import { ToolFailure } from "./tool-failure.js";
+export { ToolFailure, isToolFailure } from "./tool-failure.js";
+/** Stable prefix of argument-validation failures (`registry` pipeline stage 1). */
+export declare const TOOLARG_ERROR_PREFIX = "toolargs";
+/** Stable prefix of guard denials (legacy `GUARD_ERROR_PREFIX`). */
+export declare const GUARD_ERROR_PREFIX = "toolguard";
+/** Escape + truncate a message so the one-line error contract stays parseable. */
+export declare function quoteMessage(message: string): string;
+/** `<prefix>: code=<code> msg="<quoted>"` — the tool-side contract error shape. */
+export declare function contractError(prefix: string, code: string, message: string): string;
+/** Build a structured failure with the contract message already formatted. */
+export declare function contractFailure(prefix: string, code: string, message: string): ToolFailure;
+/** Error text for `ToolOutput.error`; non-Error rejections are stringified. */
+export declare function errorText(value: unknown): string;
+/** `run_shell-sandbox: code=timeout msg="…"` → `timeout` (for tests/diagnostics). */
+export declare function errorCode(message: string): string | null;

package/dist/errors.js

@@ -0,0 +1,60 @@
+/**
+ * Structured tool-pipeline errors.
+ *
+ * The pipeline never throws across the `Tool` seam: a tool rejects with a
+ * `ToolFailure` whose `message` is the machine-readable contract string
+ * `<prefix>: code=<code> msg="<quoted>"` (parity: `toolguard: …`,
+ * `run_shell-sandbox: …`, `http_request: code=…`), and the registry captures it
+ * into `ToolOutput.error`. Callers branch on `kind`/`code`, never on prose.
+ */
+import { ToolFailure } from "./tool-failure.js";
+export { ToolFailure, isToolFailure } from "./tool-failure.js";
+/** Stable prefix of argument-validation failures (`registry` pipeline stage 1). */
+export const TOOLARG_ERROR_PREFIX = "toolargs";
+/** Stable prefix of guard denials (legacy `GUARD_ERROR_PREFIX`). */
+export const GUARD_ERROR_PREFIX = "toolguard";
+/** Escape + truncate a message so the one-line error contract stays parseable. */
+export function quoteMessage(message) {
+    let out = "";
+    let count = 0;
+    for (const ch of message) {
+        if (count >= 512)
+            break;
+        count += 1;
+        const cp = ch.codePointAt(0) ?? 0;
+        if (ch === "\\")
+            out += "\\\\";
+        else if (ch === '"')
+            out += '\\"';
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (cp < 0x20)
+            out += `\\u{${cp.toString(16)}}`;
+        else
+            out += ch;
+    }
+    return out;
+}
+/** `<prefix>: code=<code> msg="<quoted>"` — the tool-side contract error shape. */
+export function contractError(prefix, code, message) {
+    return `${prefix}: code=${code} msg="${quoteMessage(message)}"`;
+}
+/** Build a structured failure with the contract message already formatted. */
+export function contractFailure(prefix, code, message) {
+    return new ToolFailure(code, contractError(prefix, code, message));
+}
+/** Error text for `ToolOutput.error`; non-Error rejections are stringified. */
+export function errorText(value) {
+    if (value instanceof Error)
+        return value.message;
+    return String(value);
+}
+/** `run_shell-sandbox: code=timeout msg="…"` → `timeout` (for tests/diagnostics). */
+export function errorCode(message) {
+    const match = /(?:^|\s)code=([a-z_]+)/.exec(message);
+    return match?.[1] ?? null;
+}