@celestea/tools 2.7.1

package/dist/sandbox/userspace.js

@@ -0,0 +1,107 @@
+/**
+ * `UserspaceSandbox` — the P2b implementation of the `Sandbox` seam, kept as the
+ * explicit **fallback** (and as the "no OS isolation at all" reference the
+ * tests compare against).
+ *
+ * It is honest about what it is: no namespaces, no seccomp, no private /tmp, and
+ * — W274 §6.2/§6.3 — a `setsid()`ing grandchild or a SIGKILLed Node parent leaks
+ * processes that the bwrap path reaps. What it does enforce, and what the tool
+ * contract depends on:
+ * - a fixed workdir that must resolve inside the configured root;
+ * - an allowlisted child environment (never the host environment, never HOME);
+ * - a kill deadline that SIGKILLs the whole process group;
+ * - per-stream output caps, with the truncation flag reported;
+ * - structured failures (`run_shell-sandbox: code=timeout|workdir|arg|config|spawn`).
+ *
+ * Which provider a deployment actually gets is decided in `provider.ts`; the
+ * OS-isolated one is `bwrap.ts`.
+ */
+import { USERSPACE_SANDBOX_META } from "@celestea/core";
+import { wrapChild } from "./child.js";
+import { shellInvocation, sanitizedEnv, buildSandboxConfig, sandboxConfigFromEnv } from "./config.js";
+import { captureRun, resolveTimeout, spawnPlan, validateSandboxConfig } from "./launch.js";
+import { limitsForCpu, limitsFromEnv, resolveCpuSec, rlimitsEnabled } from "./limits.js";
+import { probeHost } from "./probe.js";
+import { applyLimits, rlimitDiagnostics } from "./rlimit.js";
+import { resolveWorkdir } from "./workdir.js";
+/** The effective mode every result reports (never inferred by the caller). */
+export const USERSPACE_META = USERSPACE_SANDBOX_META;
+export class UserspaceSandbox {
+    config;
+    probe;
+    limits;
+    /** W885: injected platform view; `undefined` = the host's own defaults. */
+    shell;
+    rlimits;
+    constructor(config = sandboxConfigFromEnv(), options = {}) {
+        this.config = config;
+        this.probe = options.probe ?? probeHost();
+        this.limits = options.limits ?? limitsFromEnv(process.env, this.probe.uidThreads);
+        this.rlimits = options.rlimits ?? rlimitsEnabled(process.env);
+        this.shell = options.shell;
+    }
+    static fromEnv(env = process.env) {
+        return new UserspaceSandbox(sandboxConfigFromEnv(env), {
+            probe: probeHost({ env }),
+            rlimits: rlimitsEnabled(env),
+        });
+    }
+    async run(request) {
+        validateSandboxConfig(this.config);
+        const timeoutMs = resolveTimeout(this.config, request.timeoutMs);
+        const { child, meta } = await this.launch(request.command, request.workdir, false, this.limitsFor(request.cpuSec), request.noAddressSpaceLimit === true);
+        return captureRun(this.config, child, timeoutMs, meta);
+    }
+    async spawn(request) {
+        validateSandboxConfig(this.config);
+        const { child, meta } = await this.launch(request.command, request.workdir, true, this.limitsFor(request.cpuSec), request.noAddressSpaceLimit === true);
+        return { child: wrapChild(child, { detached: true }), sandbox: meta };
+    }
+    /** W6: the base limits with the per-call `cpu_sec` merged in (clamped). */
+    limitsFor(cpuSec) {
+        return limitsForCpu(this.limits, resolveCpuSec(this.limits.cpuSec, cpuSec, this.config.maxCpuSec));
+    }
+    /** F4: diagnostic view of what would be enforced (never SandboxMeta). */
+    describe(options = {}) {
+        const diag = rlimitDiagnostics(this.probe, this.rlimits, options.noAddressSpaceLimit === true);
+        return {
+            ...USERSPACE_META,
+            cpu_sec: this.limits.cpuSec,
+            rlimit_via: diag.via,
+            address_space_limited: diag.address_space_limited,
+        };
+    }
+    async launch(command, requestedWorkdir, withStdin, limits, noAddressSpaceLimit) {
+        const workdir = await resolveWorkdir(this.config, requestedWorkdir);
+        const { program, args } = shellInvocation(command, this.shell);
+        let plan = { program, args };
+        if (this.rlimits) {
+            try {
+                const limited = applyLimits(program, args, limits, this.probe, { enabled: true, noAddressSpaceLimit });
+                plan = { program: limited.program, args: limited.args };
+            }
+            catch {
+                // W6: userspace is the DEGRADED fallback: unlike the fail-closed bwrap
+                // path, a host with no rlimit mechanism must still run (best effort).
+                process.stderr.write("[celestea-tools] userspace sandbox: no rlimit mechanism; running without limits\n");
+            }
+        }
+        const child = await spawnPlan({
+            program: plan.program,
+            args: plan.args,
+            workdir,
+            env: sanitizedEnv(this.config),
+            withStdin,
+            label: command,
+        });
+        return { child, meta: { ...USERSPACE_META, cpu_sec: limits.cpuSec } };
+    }
+}
+/** Factory used by the policy layer as the explicit fallback. */
+export function userspaceSandbox(config) {
+    return new UserspaceSandbox(config ?? sandboxConfigFromEnv());
+}
+/** Factory with explicit knobs (tests / embeddings). */
+export function userspaceSandboxWith(overrides) {
+    return new UserspaceSandbox(buildSandboxConfig(overrides));
+}

package/dist/sandbox/workdir.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Workdir resolution shared by every sandbox provider.
+ *
+ * The workdir is the *only* thing a provider may assume is writable, so it is
+ * resolved once, canonically, and checked against the configured root before a
+ * single process is spawned. This is a **lexical** check (the host has no
+ * `CAP_SYS_CHROOT`, see W274 §5): it stops accidental escapes and report
+ * nonsense, it is not a containment boundary — containment comes from the
+ * provider (bwrap read-only root / masks).
+ */
+import type { SandboxConfig } from "@celestea/core";
+/** Resolve the effective workdir: existing, canonical, inside `config.root`. */
+export declare function resolveWorkdir(config: SandboxConfig, override?: string): Promise<string>;

package/dist/sandbox/workdir.js

@@ -0,0 +1,44 @@
+/**
+ * Workdir resolution shared by every sandbox provider.
+ *
+ * The workdir is the *only* thing a provider may assume is writable, so it is
+ * resolved once, canonically, and checked against the configured root before a
+ * single process is spawned. This is a **lexical** check (the host has no
+ * `CAP_SYS_CHROOT`, see W274 §5): it stops accidental escapes and report
+ * nonsense, it is not a containment boundary — containment comes from the
+ * provider (bwrap read-only root / masks).
+ */
+import { mkdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { SandboxError } from "@celestea/core";
+import { isInside } from "../guard/paths.js";
+import { ENV_SHELL_ROOT, ENV_SHELL_WORKDIR } from "./config.js";
+/** Resolve the effective workdir: existing, canonical, inside `config.root`. */
+export async function resolveWorkdir(config, override) {
+    const root = (await canonicalOf(config.root)) ?? resolve(config.root);
+    const target = override === undefined ? config.workdir : await resolveOverride(config.workdir, override);
+    if (override === undefined)
+        await mkdir(target, { recursive: true }).catch(() => undefined);
+    const resolved = await canonicalOf(target);
+    if (resolved === null) {
+        throw new SandboxError("workdir", `workdir '${target}' cannot be resolved`, { requested: target });
+    }
+    if (!isInside(resolved, root)) {
+        throw new SandboxError("workdir", `workdir '${target}' is outside the sandbox root '${root}' (widen with ${ENV_SHELL_ROOT} or adjust ${ENV_SHELL_WORKDIR})`, { requested: target, root });
+    }
+    return resolved;
+}
+async function resolveOverride(workdir, override) {
+    const target = isAbsolute(override) ? override : resolve(workdir, override);
+    const info = await stat(target).catch(() => null);
+    if (info === null) {
+        throw new SandboxError("workdir", `workdir '${override}' does not exist`, { requested: override });
+    }
+    if (!info.isDirectory()) {
+        throw new SandboxError("workdir", `workdir '${override}' is not a directory`, { requested: override });
+    }
+    return target;
+}
+async function canonicalOf(target) {
+    return realpath(target).catch(() => null);
+}

package/dist/schema.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal JSON-Schema subset validator for the dispatch pipeline.
+ *
+ * Pipeline stage 1 (before guards and execution): the agent-supplied `args`
+ * must satisfy the tool's own `spec().parameters`. The subset covers exactly
+ * what the frozen tool contracts use — `type`, `properties`, `required`,
+ * `additionalProperties`, `enum`, `minimum`, `items` — and is deliberately
+ * hand-written: `core` and `tools` ship zero runtime dependencies, and a full
+ * validator would be a new dependency for six schemas.
+ *
+ * A failure is a *result fact*, not an exception: the registry turns it into
+ * `toolargs: code=schema msg="…"` in `ToolOutput.error` and never runs the tool.
+ */
+export interface ArgsValidationFailure {
+    /** Human/agent-readable reason (single line). */
+    message: string;
+}
+/** Validate `args` against `schema`; `null` means "valid". */
+export declare function validateArgs(schema: unknown, args: unknown): ArgsValidationFailure | null;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/schema.js

@@ -0,0 +1,135 @@
+/**
+ * Minimal JSON-Schema subset validator for the dispatch pipeline.
+ *
+ * Pipeline stage 1 (before guards and execution): the agent-supplied `args`
+ * must satisfy the tool's own `spec().parameters`. The subset covers exactly
+ * what the frozen tool contracts use — `type`, `properties`, `required`,
+ * `additionalProperties`, `enum`, `minimum`, `items` — and is deliberately
+ * hand-written: `core` and `tools` ship zero runtime dependencies, and a full
+ * validator would be a new dependency for six schemas.
+ *
+ * A failure is a *result fact*, not an exception: the registry turns it into
+ * `toolargs: code=schema msg="…"` in `ToolOutput.error` and never runs the tool.
+ */
+/** Validate `args` against `schema`; `null` means "valid". */
+export function validateArgs(schema, args) {
+    if (!isPlainObject(schema))
+        return null;
+    return validateValue(schema, args, "");
+}
+function validateValue(schema, value, path) {
+    const type = schema["type"];
+    if (typeof type === "string" && !matchesType(type, value)) {
+        return { message: `${label(path)} must be ${type} (got ${typeName(value)})` };
+    }
+    const enumFail = checkEnum(schema, value, path);
+    if (enumFail !== null)
+        return enumFail;
+    const minimumFail = checkMinimum(schema, value, path);
+    if (minimumFail !== null)
+        return minimumFail;
+    if (isPlainObject(value))
+        return validateObject(schema, value, path);
+    if (Array.isArray(value))
+        return validateItems(schema, value, path);
+    return null;
+}
+function checkEnum(schema, value, path) {
+    const allowed = schema["enum"];
+    if (!Array.isArray(allowed))
+        return null;
+    if (allowed.some((candidate) => deepEqual(candidate, value)))
+        return null;
+    return { message: `${label(path)} must be one of [${allowed.map(show).join(", ")}]` };
+}
+function checkMinimum(schema, value, path) {
+    const minimum = schema["minimum"];
+    if (typeof minimum !== "number" || typeof value !== "number")
+        return null;
+    if (value >= minimum)
+        return null;
+    return { message: `${label(path)} must be >= ${minimum} (got ${value})` };
+}
+function validateObject(schema, value, path) {
+    const properties = isPlainObject(schema["properties"]) ? schema["properties"] : {};
+    const required = Array.isArray(schema["required"]) ? schema["required"] : [];
+    for (const key of required) {
+        if (typeof key === "string" && !(key in value)) {
+            return { message: `missing required property '${key}'${at(path)}` };
+        }
+    }
+    for (const [key, item] of Object.entries(value)) {
+        const fail = validateProperty(schema, properties, key, item, path);
+        if (fail !== null)
+            return fail;
+    }
+    return null;
+}
+function validateProperty(schema, properties, key, item, path) {
+    const propertySchema = properties[key];
+    const child = path === "" ? key : `${path}.${key}`;
+    if (propertySchema !== undefined) {
+        return validateValue(isPlainObject(propertySchema) ? propertySchema : {}, item, child);
+    }
+    const extra = schema["additionalProperties"];
+    if (extra === false)
+        return { message: `unexpected property '${key}' (additionalProperties: false)${at(path)}` };
+    // `additionalProperties: {schema}` constrains every unnamed property (the
+    // http_request `headers` map relies on it).
+    if (isPlainObject(extra))
+        return validateValue(extra, item, child);
+    return null;
+}
+function validateItems(schema, value, path) {
+    const items = schema["items"];
+    if (!isPlainObject(items))
+        return null;
+    for (const [index, item] of value.entries()) {
+        const fail = validateValue(items, item, path === "" ? `[${index}]` : `${path}[${index}]`);
+        if (fail !== null)
+            return fail;
+    }
+    return null;
+}
+function matchesType(type, value) {
+    switch (type) {
+        case "object":
+            return isPlainObject(value);
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        default:
+            return true;
+    }
+}
+function typeName(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function show(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function label(path) {
+    return path === "" ? "args" : `property '${path}'`;
+}
+function at(path) {
+    return path === "" ? "" : ` in '${path}'`;
+}

package/dist/testing/platform-gates.d.ts

@@ -0,0 +1,54 @@
+/**
+ * W885 — the shared platform capability gates (W883 §7).
+ *
+ * The repo already gates OS-specific suites with `describe.skipIf` /
+ * `it.skipIf` (`bwrap-live.test.ts`, `auth.test.ts`, `broker.test-util.ts`).
+ * This module is the ONE place those predicates live, so a Windows host can run
+ * `pnpm test` green with VISIBLE skips instead of a scattering of hardcoded
+ * `process.platform` checks — and so a new OS-specific assumption cannot be
+ * written as a bare `if (!ready) return` (which the repo counts as a PASS, not a
+ * skip).
+ *
+ * The snapshot is a **memoized function**, not four module-level constants:
+ * probeHost() costs two short execFileSyncs, and importing `@celestea/tools`
+ * must not pay for them. Call `platformGates()` once at the top of a test file:
+ *
+ *   const gates = platformGates();
+ *   describe.skipIf(!gates.posixScripts)("...", () => { ... });
+ */
+/** The capabilities a test suite may depend on, honestly measured. */
+export interface PlatformGates {
+    /** bubblewrap really works (ordered mount + device smoke already passed). */
+    readonly bwrapUsable: boolean;
+    /** `prlimit` is present (util-linux; absent on macOS and Windows). */
+    readonly prlimitUsable: boolean;
+    /** A POSIX `/bin/sh` exists (false on Windows). */
+    readonly posixShell: boolean;
+    /** `#!/bin/sh` scripts and `sh -c` are real (false on Windows). */
+    readonly posixScripts: boolean;
+    /** Signal / process-group semantics exist (false on Windows). */
+    readonly posixProcessGroups: boolean;
+    /** File permission bits are meaningful (false on Windows). */
+    readonly fileModesMeaningful: boolean;
+    /** The external `htpasswd` binary the login gate shells out to. */
+    readonly htpasswdUsable: boolean;
+    /** `python3` answers on the host (the Python matrix / broker probes). */
+    readonly python3Usable: boolean;
+    /** Everything a POSIX-only suite needs at once. */
+    readonly posixOnly: boolean;
+}
+/** Measure (once per process) what this host can honestly do. */
+export declare function platformGates(): PlatformGates;
+/** `spawnSync(bin, ["--version"])` exits 0 — an honest "the binary runs" test. */
+export declare function whichUsable(bin: string): boolean;
+/**
+ * W885 — cheap, probe-free capability flags for tests that only need the
+ * platform truth (no filesystem probe). Prefer [platformGates] when the answer
+ * needs the host probe; these two are safe to read at module scope.
+ */
+/** File permission bits are meaningful (false on Windows). */
+export declare const FILE_MODES_MEANINGFUL: boolean;
+/** POSIX signal / process-group semantics exist (false on Windows). */
+export declare const POSIX_PROCESS_GROUPS: boolean;
+/** A POSIX `/bin/sh` exists (false on Windows). */
+export declare const POSIX_SHELL: boolean;

package/dist/testing/platform-gates.js

@@ -0,0 +1,62 @@
+/**
+ * W885 — the shared platform capability gates (W883 §7).
+ *
+ * The repo already gates OS-specific suites with `describe.skipIf` /
+ * `it.skipIf` (`bwrap-live.test.ts`, `auth.test.ts`, `broker.test-util.ts`).
+ * This module is the ONE place those predicates live, so a Windows host can run
+ * `pnpm test` green with VISIBLE skips instead of a scattering of hardcoded
+ * `process.platform` checks — and so a new OS-specific assumption cannot be
+ * written as a bare `if (!ready) return` (which the repo counts as a PASS, not a
+ * skip).
+ *
+ * The snapshot is a **memoized function**, not four module-level constants:
+ * probeHost() costs two short execFileSyncs, and importing `@celestea/tools`
+ * must not pay for them. Call `platformGates()` once at the top of a test file:
+ *
+ *   const gates = platformGates();
+ *   describe.skipIf(!gates.posixScripts)("...", () => { ... });
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { probeHost } from "../sandbox/probe.js";
+let cached = null;
+/** Measure (once per process) what this host can honestly do. */
+export function platformGates() {
+    if (cached !== null)
+        return cached;
+    const probe = probeHost();
+    const posixShell = process.platform !== "win32" && existsSync("/bin/sh");
+    const posixProcessGroups = process.platform !== "win32";
+    cached = {
+        bwrapUsable: probe.bwrapUsable,
+        prlimitUsable: probe.prlimitPath !== null,
+        posixShell,
+        posixScripts: posixShell,
+        posixProcessGroups,
+        fileModesMeaningful: posixProcessGroups,
+        htpasswdUsable: whichUsable("htpasswd"),
+        python3Usable: whichUsable("python3"),
+        posixOnly: posixShell && posixProcessGroups,
+    };
+    return cached;
+}
+/** `spawnSync(bin, ["--version"])` exits 0 — an honest "the binary runs" test. */
+export function whichUsable(bin) {
+    try {
+        return spawnSync(bin, ["--version"], { stdio: "ignore", timeout: 5_000 }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * W885 — cheap, probe-free capability flags for tests that only need the
+ * platform truth (no filesystem probe). Prefer [platformGates] when the answer
+ * needs the host probe; these two are safe to read at module scope.
+ */
+/** File permission bits are meaningful (false on Windows). */
+export const FILE_MODES_MEANINGFUL = process.platform !== "win32";
+/** POSIX signal / process-group semantics exist (false on Windows). */
+export const POSIX_PROCESS_GROUPS = process.platform !== "win32";
+/** A POSIX `/bin/sh` exists (false on Windows). */
+export const POSIX_SHELL = process.platform !== "win32" && existsSync("/bin/sh");

package/dist/tool-failure.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `ToolFailure` — the single rejection type of a tool executor.
+ *
+ * Mirrors the legacy `Result<Value, String>`: the seam rejects with an `Error`
+ * (never a bare string) whose `message` is the structured contract error, so
+ * `ToolOutput.error` stays parseable while callers keep a typed handle.
+ */
+export declare class ToolFailure extends Error {
+    /** Stable machine-readable code (`schema`, `invalid_arg`, `binary_file`, …). */
+    readonly kind: string;
+    constructor(kind: string, message: string);
+}
+export declare function isToolFailure(value: unknown): value is ToolFailure;

package/dist/tool-failure.js

@@ -0,0 +1,19 @@
+/**
+ * `ToolFailure` — the single rejection type of a tool executor.
+ *
+ * Mirrors the legacy `Result<Value, String>`: the seam rejects with an `Error`
+ * (never a bare string) whose `message` is the structured contract error, so
+ * `ToolOutput.error` stays parseable while callers keep a typed handle.
+ */
+export class ToolFailure extends Error {
+    /** Stable machine-readable code (`schema`, `invalid_arg`, `binary_file`, …). */
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "ToolFailure";
+        this.kind = kind;
+    }
+}
+export function isToolFailure(value) {
+    return value instanceof ToolFailure;
+}

package/dist/tools/ask-user.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `ask_user_question` — the model-facing half of the user-question seam (W783).
+ *
+ * The schema is copied from the official DSH implementation
+ * (`dsh-tool-ask-user/lib/index.js`) so both hosts put the SAME request shape in
+ * front of the model; `packages/tools` may only depend on `@celestea/core`
+ * (L1), so the service arrives by CONSTRUCTION — exactly like
+ * `runShellTool({sandbox, processes})` — and never from a Context.
+ *
+ * The description carries two things the schema cannot:
+ *   - the `(Recommended)` convention, localised to 「（推荐）」 (§8);
+ *   - the TIMEOUT semantics (§6.3). This repo gives the wait a maximum, and the
+ *     system deliberately does NOT decide for the model when it expires: the
+ *     result is an empty answer set, and the model is told to carry on with its
+ *     own judgement instead of asking again.
+ */
+import type { Tool, ToolSpec, UserQuestionService } from "@celestea/core";
+/** What the tool needs: the seam, injected (never resolved from a Context). */
+export interface AskUserToolOptions {
+    /** The host's user-question service (`null` = the feature is not mounted). */
+    questions: UserQuestionService | null;
+}
+/** The tool description (localised DSH wording + the §6.3 timeout semantics). */
+export declare const ASK_USER_DESCRIPTION: string;
+/** The frozen spec of `ask_user_question`. */
+export declare function askUserSpec(): ToolSpec;
+/**
+ * The `ask_user_question` tool. A host that did not mount the service gets a
+ * structured failure instead of a silent no-op: the model must be able to tell
+ * "nobody can answer here" from "the user answered nothing".
+ */
+export declare function askUserTool(options: AskUserToolOptions): Tool;

package/dist/tools/ask-user.js

@@ -0,0 +1,145 @@
+/**
+ * `ask_user_question` — the model-facing half of the user-question seam (W783).
+ *
+ * The schema is copied from the official DSH implementation
+ * (`dsh-tool-ask-user/lib/index.js`) so both hosts put the SAME request shape in
+ * front of the model; `packages/tools` may only depend on `@celestea/core`
+ * (L1), so the service arrives by CONSTRUCTION — exactly like
+ * `runShellTool({sandbox, processes})` — and never from a Context.
+ *
+ * The description carries two things the schema cannot:
+ *   - the `(Recommended)` convention, localised to 「（推荐）」 (§8);
+ *   - the TIMEOUT semantics (§6.3). This repo gives the wait a maximum, and the
+ *     system deliberately does NOT decide for the model when it expires: the
+ *     result is an empty answer set, and the model is told to carry on with its
+ *     own judgement instead of asking again.
+ */
+import { descParam } from "../desc.js";
+import { fnTool } from "../fn-tool.js";
+/** The tool description (localised DSH wording + the §6.3 timeout semantics). */
+export const ASK_USER_DESCRIPTION = "Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. "
+    + "Send one or more questions, each with a stable id that will be echoed in the answer. The call PAUSES until the "
+    + "user answers, then returns `{answers:[{id,selected,custom}],timed_out:false}` as an ordinary tool result and you "
+    + "continue. If you recommend one option, put it first and append \"（推荐）\" to that label. The user may always "
+    + "type a free-text answer instead of choosing. Waiting is bounded (default 300000 ms, overridable with `timeout_ms`): "
+    + "on expiry the call returns `{answers:[],timed_out:true}` and NO choice is made for you — do not ask the same "
+    + "question again; state the assumption you are proceeding on (or stop and report) and continue with your own judgement.";
+/** The `questions` parameter schema (DSH, field for field). */
+function questionsParam() {
+    return {
+        type: "array",
+        description: "Questions to ask the user before continuing.",
+        items: {
+            type: "object",
+            additionalProperties: true,
+            properties: {
+                id: { type: "string", description: "Stable id for this question; echoed in the answer." },
+                question: { type: "string", description: "The specific question to ask the user." },
+                header: { type: "string", description: "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"." },
+                detail: {
+                    type: "string",
+                    description: "Optional supporting detail shown with the question. Kept out of the option labels, so it never takes part in label matching.",
+                },
+                options: {
+                    type: "array",
+                    description: "Optional choices to show the user. If you recommend one, put it first and append \"（推荐）\" to that label.",
+                    items: {
+                        type: "object",
+                        additionalProperties: true,
+                        properties: {
+                            label: { type: "string", description: "Short user-facing option label." },
+                            description: { type: "string", description: "One sentence explaining the tradeoff or impact." },
+                        },
+                        required: ["label"],
+                    },
+                },
+                multi_select: { type: "boolean", description: "Whether the user may select more than one option. Defaults to false." },
+                intent: {
+                    type: "object",
+                    additionalProperties: false,
+                    description: "Optional presentation intent. It changes how a capable UI renders the question, never the answer encoding; a UI that does not know the tag shows the generic option list.",
+                    properties: {
+                        kind: { type: "string", enum: ["plan-review"], description: "A plan submitted for review." },
+                        approve: { type: "string", description: "The option label that approves the plan; every other option declines it." },
+                    },
+                    required: ["kind", "approve"],
+                },
+            },
+            required: ["id", "question"],
+        },
+    };
+}
+/** The frozen spec of `ask_user_question`. */
+export function askUserSpec() {
+    return {
+        name: "ask_user_question",
+        description: ASK_USER_DESCRIPTION,
+        parameters: {
+            type: "object",
+            properties: {
+                questions: questionsParam(),
+                timeout_ms: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Optional maximum wait in milliseconds for the whole batch. Default 300000; capped at 3600000. On expiry the call returns an empty answer set with timed_out:true.",
+                },
+                desc: descParam(),
+            },
+            required: ["questions"],
+            additionalProperties: false,
+        },
+    };
+}
+/** Copy one model-supplied question into the seam's shape (optional keys kept absent). */
+function toQuestion(raw) {
+    const item = { id: String(raw.id), question: String(raw.question) };
+    if (raw.header !== undefined)
+        item.header = String(raw.header);
+    if (raw.detail !== undefined)
+        item.detail = String(raw.detail);
+    if (Array.isArray(raw.options))
+        item.options = raw.options;
+    if (raw.multi_select !== undefined)
+        item.multiSelect = raw.multi_select === true;
+    if (raw.intent !== undefined)
+        item.intent = raw.intent;
+    return item;
+}
+/** The model-supplied questions, in order. */
+function questionsOf(args) {
+    const list = args.questions;
+    if (!Array.isArray(list))
+        return [];
+    return list.map((raw) => toQuestion(raw));
+}
+/** `timeout_ms` when it is a positive integer, else undefined (the default). */
+function timeoutOf(args) {
+    const value = args.timeout_ms;
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+/**
+ * The `ask_user_question` tool. A host that did not mount the service gets a
+ * structured failure instead of a silent no-op: the model must be able to tell
+ * "nobody can answer here" from "the user answered nothing".
+ */
+export function askUserTool(options) {
+    const service = options.questions;
+    return fnTool(askUserSpec(), async (args) => {
+        if (service === null) {
+            throw new Error("ask_user_question: code=no_provider msg=\"no user-questions service is mounted in this host\"");
+        }
+        const requested = timeoutOf(args);
+        const outcome = await service.ask({
+            questions: questionsOf(args),
+            ...(requested === undefined ? {} : { timeoutMs: requested }),
+        });
+        return { answers: outcome.answers.map(copyAnswer), timed_out: outcome.timed_out };
+    });
+}
+/** One answer item, with `custom` omitted rather than written as null. */
+function copyAnswer(answer) {
+    const out = { id: answer.id, selected: [...answer.selected] };
+    if (answer.custom !== undefined)
+        out.custom = answer.custom;
+    return out;
+}