@celestea/tools 2.7.1

package/dist/platform/exec.js

@@ -0,0 +1,218 @@
+/**
+ * Shell resolution (W885) — WHICH shell runs a `run_shell` / `run_code` command.
+ *
+ * Product decision (W885): on Windows the priority is
+ *
+ *   gitbash > pwsh > cmd
+ *
+ * and the choice is **probe-based, never guessed**: every candidate is looked up
+ * through the injected `which` / `exists` callbacks (defaults: the filesystem +
+ * `PATH`), and when nothing is found the resolver **fails closed** with a
+ * structured [ShellNotFoundError] instead of silently picking a shell the host
+ * may not have.
+ *
+ * Linux behaviour is byte-identical to the pre-W885 code: the POSIX answer is
+ * the literal `/bin/sh` with argv `["-c", command]` (W883 B8 anchored that
+ * shape in `config.ts` / `bwrap-argv.ts`). `$SHELL` is deliberately NOT
+ * consulted implicitly — that would change what runs on every Linux host that
+ * exports it; an operator pins a shell explicitly with `CELESTEA_SHELL`.
+ *
+ * Pure and injectable: the platform / env / homedir inputs are arguments (the
+ * `celestea-home.ts` pattern), so the win32 branches are unit-testable on
+ * Linux.
+ */
+import { existsSync } from "node:fs";
+import { envValue, execSuffixes, isWindows, pathApi, pathDelimiter } from "./paths.js";
+/** Env var pinning one explicit shell executable (any platform, fail-closed). */
+export const ENV_SHELL_PIN = "CELESTEA_SHELL";
+/** Structured failure: no usable shell on this host (never a fallback guess). */
+export class ShellNotFoundError extends Error {
+    code = "shell_not_found";
+    constructor(message) {
+        super(message);
+        this.name = "ShellNotFoundError";
+    }
+}
+/** The argv shape of one shell carrying exactly one command string. */
+export function shellArgv(kind, command) {
+    if (kind === "pwsh")
+        return ["-NoProfile", "-NonInteractive", "-Command", command];
+    if (kind === "cmd")
+        return ["/d", "/s", "/c", command];
+    // posix + gitbash both speak `sh -c`.
+    return ["-c", command];
+}
+/**
+ * Resolve the shell that should carry `command` on `platform`.
+ *
+ * Precedence: an explicit `CELESTEA_SHELL` pin > the platform ladder
+ * (POSIX: `/bin/sh`; Windows: gitbash > pwsh > cmd). Nothing found ⇒ throws.
+ */
+export function resolveShell(command, input = {}) {
+    const chosen = resolveShellKind(input);
+    return { ...chosen, argv: shellArgv(chosen.kind, command) };
+}
+/**
+ * The shell a command WOULD be given to, without a command (W885: `run_code`
+ * needs the kind to quote its interpreter line before it has one).
+ */
+export function resolveShellKind(input = {}) {
+    const platform = input.platform ?? process.platform;
+    const env = input.env ?? process.env;
+    const lookup = lookupFor(platform, env, input);
+    const pinned = envValue(env, ENV_SHELL_PIN);
+    if (pinned !== undefined)
+        return pinnedShell(pinned, platform, lookup);
+    return isWindows(platform) ? resolveWindows(env, lookup) : resolvePosix();
+}
+/** The default lookups: real filesystem, PATH split per platform delimiter. */
+export function lookupFor(platform, env, input = {}) {
+    const exists = input.exists ?? ((path) => existsSync(path));
+    return { which: input.which ?? ((bin) => whichInPath(bin, platform, env, exists)), exists };
+}
+function resolvePosix() {
+    // Byte-for-byte the pre-W885 answer; `$SHELL` is intentionally ignored (see
+    // the module header) so no existing Linux deployment changes behaviour.
+    return { kind: "posix", path: "/bin/sh" };
+}
+function resolveWindows(env, lookup) {
+    const gitbash = findGitBash(env, lookup);
+    if (gitbash !== null)
+        return { kind: "gitbash", path: gitbash };
+    const pwsh = findPwsh(env, lookup);
+    if (pwsh !== null)
+        return { kind: "pwsh", path: pwsh };
+    const cmd = findCmd(env, lookup);
+    if (cmd !== null)
+        return { kind: "cmd", path: cmd };
+    throw new ShellNotFoundError("no usable shell on this Windows host: looked for bash.exe (Git for Windows: " +
+        "%ProgramFiles%\\Git\\bin\\bash.exe, %ProgramFiles(x86)%\\Git\\bin\\bash.exe, " +
+        "%LOCALAPPDATA%\\Programs\\Git\\bin\\bash.exe, PATH), pwsh.exe (PATH, " +
+        "%ProgramFiles%\\PowerShell\\7\\pwsh.exe) and cmd.exe (%ComSpec%, PATH, %SystemRoot%\\System32). " +
+        "Install Git for Windows / PowerShell 7, or pin one with " + ENV_SHELL_PIN + ".");
+}
+/** Git for Windows, in the order the user's priority implies. */
+function findGitBash(env, lookup) {
+    const onPath = lookup.which("bash.exe");
+    if (onPath !== null)
+        return onPath;
+    return firstExisting(underRoots(env, GITBASH_ROOTS), lookup.exists);
+}
+function findPwsh(env, lookup) {
+    const onPath = lookup.which("pwsh.exe");
+    if (onPath !== null)
+        return onPath;
+    return firstExisting(underRoots(env, PWSH_ROOTS), lookup.exists);
+}
+/**
+ * cmd.exe: `%ComSpec%` first (the OS's own answer), then PATH, then the
+ * canonical `%SystemRoot%\\System32` location. Never invented beyond that.
+ */
+function findCmd(env, lookup) {
+    const comspec = envValue(env, "ComSpec");
+    if (comspec !== undefined && lookup.exists(comspec))
+        return comspec;
+    const onPath = lookup.which("cmd.exe");
+    if (onPath !== null)
+        return onPath;
+    return firstExisting(underRoots(env, CMD_ROOTS), lookup.exists);
+}
+/**
+ * `[install-root env var, path under it]` pairs, in the order Git for Windows
+ * actually uses. Program Files first (the machine-wide installer), then the
+ * per-user default — the W883 §2.2 note that a Git installed "for me only"
+ * lives under `%LOCALAPPDATA%\Programs`.
+ */
+const GITBASH_ROOTS = [
+    ["ProgramFiles", ["Git", "bin", "bash.exe"]],
+    ["ProgramFiles(x86)", ["Git", "bin", "bash.exe"]],
+    ["LOCALAPPDATA", ["Programs", "Git", "bin", "bash.exe"]],
+];
+/** PowerShell 7's documented install root (pwsh is never under Program Files (x86)). */
+const PWSH_ROOTS = [["ProgramFiles", ["PowerShell", "7", "pwsh.exe"]]];
+/** cmd.exe's canonical location when `%ComSpec%` and PATH are both silent. */
+const CMD_ROOTS = [
+    ["SystemRoot", ["System32", "cmd.exe"]],
+    ["windir", ["System32", "cmd.exe"]],
+];
+/** Absolute candidates for `[envVar, segments]` pairs under one install root. */
+function underRoots(env, roots) {
+    const api = pathApi("win32");
+    const out = [];
+    for (const [key, segments] of roots) {
+        const root = envValue(env, key);
+        if (root !== undefined)
+            out.push(api.join(root, ...segments));
+    }
+    return out;
+}
+function firstExisting(candidates, exists) {
+    for (const candidate of candidates)
+        if (exists(candidate))
+            return candidate;
+    return null;
+}
+/**
+ * An explicitly pinned shell (`CELESTEA_SHELL`). The kind is derived from the
+ * file name so the argv shape matches; an unrecognised name is a structured
+ * error rather than a silent guess.
+ */
+function pinnedShell(path, platform, lookup) {
+    if (!lookup.exists(path))
+        throw new ShellNotFoundError(ENV_SHELL_PIN + "='" + path + "' does not exist on this host");
+    return { kind: kindOfExecutable(path, platform), path };
+}
+const PINNED_KINDS = new Map([
+    ["bash", "gitbash"],
+    ["sh", "posix"],
+    ["dash", "posix"],
+    ["pwsh", "pwsh"],
+    ["powershell", "pwsh"],
+    ["cmd", "cmd"],
+]);
+/** `pwsh.exe` -> `pwsh`; the kind a pinned executable's argv shape follows. */
+export function kindOfExecutable(path, platform = process.platform) {
+    const base = pathApi(platform).basename(path).toLowerCase().replace(/\.(exe|cmd|bat|com)$/, "");
+    const kind = PINNED_KINDS.get(base);
+    if (kind === undefined) {
+        throw new ShellNotFoundError(ENV_SHELL_PIN + "='" + path + "' is not a recognised shell (expected sh, bash, dash, pwsh, powershell or cmd)");
+    }
+    // `bash` on a POSIX host is the ordinary POSIX shell; on Windows it is Git Bash.
+    return kind === "gitbash" && !isWindows(platform) ? "posix" : kind;
+}
+/**
+ * PATH lookup that honours the injected env and the platform's delimiter —
+ * `;` plus `PATHEXT` suffixes on Windows, `:` with no suffixes elsewhere. A
+ * value that looks like a path is checked directly (the pre-W885 rule).
+ */
+export function whichInPath(bin, platform = process.platform, env = {}, exists = existsSync) {
+    if (looksLikePath(bin, platform))
+        return exists(bin) ? bin : null;
+    const api = pathApi(platform);
+    for (const dir of searchPath(platform, env)) {
+        if (dir === "")
+            continue;
+        for (const name of candidateNames(bin, platform, env)) {
+            const candidate = api.join(dir, name);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** The PATH entries to search (POSIX keeps the historical /usr/bin:/bin floor). */
+function searchPath(platform, env) {
+    const raw = env["PATH"] ?? (isWindows(platform) ? "" : "/usr/bin:/bin");
+    return raw.split(pathDelimiter(platform));
+}
+/** Exact name first, then the platform suffixes (Windows only). */
+function candidateNames(bin, platform, env) {
+    if (pathApi(platform).extname(bin) !== "")
+        return [bin];
+    return [bin, ...execSuffixes(platform, env).map((suffix) => bin + suffix)];
+}
+function looksLikePath(bin, platform) {
+    if (isWindows(platform))
+        return pathApi(platform).isAbsolute(bin) || bin.includes("\\");
+    return bin.includes("/");
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * W885 — the platform seam barrel (`@celestea/tools/platform` internals).
+ *
+ * Three concerns, deliberately split so each file stays inside the repo's
+ * 400-line / 80-line-per-function shape rules:
+ *   paths.ts   platform ids, path API, PATH delimiter, PATHEXT suffixes
+ *   exec.ts    shell resolution (gitbash > pwsh > cmd) + PATH lookup
+ *   quote.ts   per-shell command quoting + the run_code interpreter line
+ */
+export * from "./paths.js";
+export * from "./exec.js";
+export * from "./quote.js";

package/dist/platform/index.js

@@ -0,0 +1,12 @@
+/**
+ * W885 — the platform seam barrel (`@celestea/tools/platform` internals).
+ *
+ * Three concerns, deliberately split so each file stays inside the repo's
+ * 400-line / 80-line-per-function shape rules:
+ *   paths.ts   platform ids, path API, PATH delimiter, PATHEXT suffixes
+ *   exec.ts    shell resolution (gitbash > pwsh > cmd) + PATH lookup
+ *   quote.ts   per-shell command quoting + the run_code interpreter line
+ */
+export * from "./paths.js";
+export * from "./exec.js";
+export * from "./quote.js";

package/dist/platform/paths.d.ts

@@ -0,0 +1,51 @@
+/**
+ * W885 (Windows slice 1) — the injectable platform seam.
+ *
+ * `celestea-home.ts` (W880) set the pattern: a platform decision takes its
+ * inputs as ARGUMENTS (`platform` / `env` / `homedir`) and stays a pure
+ * function, so the win32 branch is unit-testable on a Linux host and the global
+ * `process` is read only where a default is unavoidable. This module is that
+ * seam for everything the sandbox/guard/broker layers need.
+ *
+ * It lives in `@celestea/tools` (not core): `probe.ts`, `path-guard.ts`,
+ * `config.ts`, `child.ts` and `broker.ts` — the consumers — are all in this
+ * package, the dependency direction stays L1 → L0, and core keeps its leaf
+ * promise (W883 §6.2 P0-2 listed both locations as acceptable).
+ */
+import { posix } from "node:path";
+/** Everything a platform decision may depend on (injectable; never global). */
+export interface PlatformInput {
+    /** Defaults to `process.platform` at the call site only. */
+    platform?: NodeJS.Platform | string;
+    /** Defaults to `process.env` at the call site only. */
+    env?: Record<string, string | undefined>;
+    /** Defaults to `os.homedir()` at the call site only. */
+    homedir?: string;
+}
+/** true for the Windows platform id (the only place the literal lives). */
+export declare function isWindows(platform?: string): boolean;
+/**
+ * The path implementation of a platform (same rule as `celestea-home.ts`):
+ * deterministic across hosts, so a win32 test never touches the host's path
+ * semantics.
+ */
+export declare function pathApi(platform?: string): typeof posix;
+/** `PATH` list separator: `;` on Windows, `:` everywhere else. */
+export declare function pathDelimiter(platform?: string): string;
+/**
+ * Executable suffixes tried when resolving a bare name on Windows. The real
+ * rule is `PATHEXT` (plus an exact-name match first, which command lookup also
+ * allows); the two ARE checked independently and must not be collapsed.
+ */
+export declare const WINDOWS_EXEC_SUFFIXES: readonly string[];
+/**
+ * The suffixes to try for `bin` on `platform`, from the injected env.
+ *
+ * `PATHEXT` is honoured when present (the operator's real resolution order) and
+ * the defaults are used otherwise. The order inside the list is significant:
+ * `.exe` before `.cmd` is what makes `bash.exe` win over a `bash.cmd`
+ * shim, which matters for the gitbash > pwsh > cmd priority.
+ */
+export declare function execSuffixes(platform?: string, env?: Record<string, string | undefined>): readonly string[];
+/** A non-blank, trimmed env value; `undefined` when unset or blank. */
+export declare function envValue(env: Record<string, string | undefined>, name: string): string | undefined;

package/dist/platform/paths.js

@@ -0,0 +1,60 @@
+/**
+ * W885 (Windows slice 1) — the injectable platform seam.
+ *
+ * `celestea-home.ts` (W880) set the pattern: a platform decision takes its
+ * inputs as ARGUMENTS (`platform` / `env` / `homedir`) and stays a pure
+ * function, so the win32 branch is unit-testable on a Linux host and the global
+ * `process` is read only where a default is unavoidable. This module is that
+ * seam for everything the sandbox/guard/broker layers need.
+ *
+ * It lives in `@celestea/tools` (not core): `probe.ts`, `path-guard.ts`,
+ * `config.ts`, `child.ts` and `broker.ts` — the consumers — are all in this
+ * package, the dependency direction stays L1 → L0, and core keeps its leaf
+ * promise (W883 §6.2 P0-2 listed both locations as acceptable).
+ */
+import { posix, win32 } from "node:path";
+/** true for the Windows platform id (the only place the literal lives). */
+export function isWindows(platform = process.platform) {
+    return platform === "win32";
+}
+/**
+ * The path implementation of a platform (same rule as `celestea-home.ts`):
+ * deterministic across hosts, so a win32 test never touches the host's path
+ * semantics.
+ */
+export function pathApi(platform = process.platform) {
+    return isWindows(platform) ? win32 : posix;
+}
+/** `PATH` list separator: `;` on Windows, `:` everywhere else. */
+export function pathDelimiter(platform = process.platform) {
+    return isWindows(platform) ? ";" : ":";
+}
+/**
+ * Executable suffixes tried when resolving a bare name on Windows. The real
+ * rule is `PATHEXT` (plus an exact-name match first, which command lookup also
+ * allows); the two ARE checked independently and must not be collapsed.
+ */
+export const WINDOWS_EXEC_SUFFIXES = [".exe", ".cmd", ".bat", ".com"];
+/**
+ * The suffixes to try for `bin` on `platform`, from the injected env.
+ *
+ * `PATHEXT` is honoured when present (the operator's real resolution order) and
+ * the defaults are used otherwise. The order inside the list is significant:
+ * `.exe` before `.cmd` is what makes `bash.exe` win over a `bash.cmd`
+ * shim, which matters for the gitbash > pwsh > cmd priority.
+ */
+export function execSuffixes(platform = process.platform, env = {}) {
+    if (!isWindows(platform))
+        return [];
+    const raw = env["PATHEXT"];
+    const parsed = (raw ?? "").split(";").map((entry) => entry.trim().toLowerCase()).filter((entry) => entry !== "");
+    return parsed.length > 0 ? parsed : WINDOWS_EXEC_SUFFIXES;
+}
+/** A non-blank, trimmed env value; `undefined` when unset or blank. */
+export function envValue(env, name) {
+    const raw = env[name];
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed === "" ? undefined : trimmed;
+}

package/dist/platform/quote.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Command assembly + quoting per shell (W885) — the arg the CHILD sees must be
+ * one string, whatever the shell.
+ *
+ * Three dialects, three rules, and they are not interchangeable:
+ *
+ * | shell   | argv shape                                              | quote rule |
+ * |---------|---------------------------------------------------------|------------|
+ * | posix   | `sh -c <command>`                                       | none — the command IS the argument (byte-identical to pre-W885) |
+ * | gitbash | `bash -c <command>`                                     | POSIX single quotes (same as posix) |
+ * | pwsh    | `pwsh -NoProfile -NonInteractive -Command <command>`     | single quotes; an embedded `'` doubles |
+ * | cmd     | `cmd /d /s /c <command>`                                | double quotes; an embedded `"` is backslash-escaped, and a trailing backslash run doubles |
+ *
+ * The POSIX branch is deliberately a **pass-through**: W885's hard requirement
+ * is that Linux behaviour does not change by a single byte, so no quoting is
+ * introduced where there was none.
+ *
+ * Honest limitation (this host is Linux): cmd.exe's parser is not a regular
+ * language and has no fully general escaping rule. [quoteCmd] implements the
+ * documented "wrap in double quotes, escape an embedded quote, double a
+ * trailing backslash" convention, which is correct for the lines this repo
+ * builds (`<interpreter> <script path>`) and is unit-tested for the
+ * meta-characters below — it is NOT a proof of cmd-safety for arbitrary user
+ * commands. The same caveat applies to PowerShell's single-quote rule, which is
+ * well-defined but only exercised here against strings, not against a real pwsh.
+ */
+import type { ShellKind } from "./exec.js";
+/** Quote `value` for the given shell's parser (POSIX + gitbash: verbatim). */
+export declare function quoteForShell(kind: ShellKind, value: string): string;
+/**
+ * One shell WORD — an interpreter, a flag, a path — quoted for `kind`, and
+ * quoted ONLY when the dialect needs it.
+ *
+ * The POSIX "only when needed" rule is what keeps the `run_code` line
+ * byte-identical to pre-W885: `python3` and `/usr/bin/node` go through
+ * verbatim exactly as they used to, while a word that WOULD be mangled (a space,
+ * a quote, a glob) now gets the historical single-quote treatment instead of
+ * being pasted in raw. pwsh and cmd quote unconditionally — their parsers have
+ * no safe set to rely on.
+ */
+export declare function quoteWord(kind: ShellKind, word: string): string;
+/**
+ * A path that is ALWAYS quoted for `kind`. The `run_code` script path has been
+ * single-quoted on POSIX since before W885 (`broker.ts` `shellQuote`), so this
+ * keeps those bytes exactly and gives cmd/pwsh their own dialect.
+ */
+export declare function quotePath(kind: ShellKind, path: string): string;
+/**
+ * POSIX single-quote a word so an absolute path with spaces stays one word
+ * (pre-W885 `broker.ts` behaviour, preserved verbatim).
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * cmd.exe double-quoting: wrap in `"…"`, escape an embedded quote, and double
+ * a trailing run of backslashes (command-line quoting consumes them before the
+ * closing quote).
+ */
+export declare function quoteCmd(value: string): string;
+/** Interpreters a `run_code` program can be executed with. */
+export type RunCodeLanguageName = "typescript" | "python";
+/** Python interpreters tried on POSIX, in order (`python3` keeps its priority). */
+export declare const PYTHON_CANDIDATES_POSIX: readonly string[];
+/** Python interpreters Windows actually ships (the `py` launcher included). */
+export declare const PYTHON_CANDIDATES_WINDOWS: readonly string[];
+/** The interpreter names to try, most preferred first, for `platform`. */
+export declare function pythonCandidates(platform?: string): readonly string[];
+/**
+ * The full command line one `run_code` program is executed with, quoted for
+ * `kind`. `interpreter` is an already-resolved absolute path or bare name
+ * (see `resolveInterpreter` in `run-code/broker.ts`).
+ */
+export declare function runCodeCommand(kind: ShellKind, language: RunCodeLanguageName, interpreter: string, scriptPath: string): string;

package/dist/platform/quote.js

@@ -0,0 +1,102 @@
+/**
+ * Command assembly + quoting per shell (W885) — the arg the CHILD sees must be
+ * one string, whatever the shell.
+ *
+ * Three dialects, three rules, and they are not interchangeable:
+ *
+ * | shell   | argv shape                                              | quote rule |
+ * |---------|---------------------------------------------------------|------------|
+ * | posix   | `sh -c <command>`                                       | none — the command IS the argument (byte-identical to pre-W885) |
+ * | gitbash | `bash -c <command>`                                     | POSIX single quotes (same as posix) |
+ * | pwsh    | `pwsh -NoProfile -NonInteractive -Command <command>`     | single quotes; an embedded `'` doubles |
+ * | cmd     | `cmd /d /s /c <command>`                                | double quotes; an embedded `"` is backslash-escaped, and a trailing backslash run doubles |
+ *
+ * The POSIX branch is deliberately a **pass-through**: W885's hard requirement
+ * is that Linux behaviour does not change by a single byte, so no quoting is
+ * introduced where there was none.
+ *
+ * Honest limitation (this host is Linux): cmd.exe's parser is not a regular
+ * language and has no fully general escaping rule. [quoteCmd] implements the
+ * documented "wrap in double quotes, escape an embedded quote, double a
+ * trailing backslash" convention, which is correct for the lines this repo
+ * builds (`<interpreter> <script path>`) and is unit-tested for the
+ * meta-characters below — it is NOT a proof of cmd-safety for arbitrary user
+ * commands. The same caveat applies to PowerShell's single-quote rule, which is
+ * well-defined but only exercised here against strings, not against a real pwsh.
+ */
+import { isWindows } from "./paths.js";
+/** POSIX: a literal single quote inside single quotes. */
+const POSIX_QUOTE = String.raw `'\''`;
+/** cmd.exe: a literal double quote inside a double-quoted argument. */
+const CMD_QUOTE = String.raw `\"`;
+/** Quote `value` for the given shell's parser (POSIX + gitbash: verbatim). */
+export function quoteForShell(kind, value) {
+    if (kind === "cmd")
+        return quoteCmd(value);
+    if (kind === "pwsh")
+        return `'${value.replace(/'/g, "''")}'`;
+    return value;
+}
+/** Characters a POSIX shell passes through unchanged (no quoting needed). */
+const SAFE_WORD = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/**
+ * One shell WORD — an interpreter, a flag, a path — quoted for `kind`, and
+ * quoted ONLY when the dialect needs it.
+ *
+ * The POSIX "only when needed" rule is what keeps the `run_code` line
+ * byte-identical to pre-W885: `python3` and `/usr/bin/node` go through
+ * verbatim exactly as they used to, while a word that WOULD be mangled (a space,
+ * a quote, a glob) now gets the historical single-quote treatment instead of
+ * being pasted in raw. pwsh and cmd quote unconditionally — their parsers have
+ * no safe set to rely on.
+ */
+export function quoteWord(kind, word) {
+    if (kind === "cmd" || kind === "pwsh")
+        return quoteForShell(kind, word);
+    return SAFE_WORD.test(word) ? word : shellQuote(word);
+}
+/**
+ * A path that is ALWAYS quoted for `kind`. The `run_code` script path has been
+ * single-quoted on POSIX since before W885 (`broker.ts` `shellQuote`), so this
+ * keeps those bytes exactly and gives cmd/pwsh their own dialect.
+ */
+export function quotePath(kind, path) {
+    if (kind === "cmd" || kind === "pwsh")
+        return quoteForShell(kind, path);
+    return shellQuote(path);
+}
+/**
+ * POSIX single-quote a word so an absolute path with spaces stays one word
+ * (pre-W885 `broker.ts` behaviour, preserved verbatim).
+ */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, POSIX_QUOTE)}'`;
+}
+/**
+ * cmd.exe double-quoting: wrap in `"…"`, escape an embedded quote, and double
+ * a trailing run of backslashes (command-line quoting consumes them before the
+ * closing quote).
+ */
+export function quoteCmd(value) {
+    const escaped = value.replace(/"/g, CMD_QUOTE);
+    const trailing = /\\+$/.exec(escaped);
+    const padded = trailing === null ? escaped : escaped + trailing[0];
+    return `"${padded}"`;
+}
+/** Python interpreters tried on POSIX, in order (`python3` keeps its priority). */
+export const PYTHON_CANDIDATES_POSIX = ["python3", "python"];
+/** Python interpreters Windows actually ships (the `py` launcher included). */
+export const PYTHON_CANDIDATES_WINDOWS = ["python.exe", "python3.exe", "py.exe"];
+/** The interpreter names to try, most preferred first, for `platform`. */
+export function pythonCandidates(platform = process.platform) {
+    return isWindows(platform) ? PYTHON_CANDIDATES_WINDOWS : PYTHON_CANDIDATES_POSIX;
+}
+/**
+ * The full command line one `run_code` program is executed with, quoted for
+ * `kind`. `interpreter` is an already-resolved absolute path or bare name
+ * (see `resolveInterpreter` in `run-code/broker.ts`).
+ */
+export function runCodeCommand(kind, language, interpreter, scriptPath) {
+    const flags = language === "python" ? " -uB" : "";
+    return `${quoteWord(kind, interpreter)}${flags} ${quotePath(kind, scriptPath)}`;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The tools plugin — `mount(ctx)` is the only installation path (nothing
+ * self-registers at runtime), and it publishes exactly three services:
+ *
+ * - `ToolRegistryService` → the assembled registry (schema → guard → execute);
+ * - `SandboxService`      → the execution boundary `run_shell` orchestrates;
+ * - `ProcessRegistryService` → the session-scoped background process registry.
+ *
+ * The guard chain is mounted here because **order is security semantics**: the
+ * path whitelist must run before any tool execution, and `CELESTEA_TOOL_GUARD=0`
+ * is the only (explicit, documented) way to skip it.
+ *
+ * `run_code` (W255) is mounted here too, not in `builtinTools`: it needs a
+ * late-bound handle on the very registry it will dispatch sub-calls through,
+ * which only the assembly can bind — exactly like the runtime compose
+ * (`crates/runtime/src/tools.rs`). Pass `runCode: false` to leave it out.
+ */
+import { type Plugin, type Sandbox, type Tool, type ToolGuard, type UserQuestionService } from "@celestea/core";
+import type { AttachmentStore } from "./attachments/store.js";
+import { type PathGuardGrants } from "./guard/path-guard.js";
+import { type SsrfGrantView } from "./http/ssrf.js";
+import type { HttpRequestToolOptions } from "./tools/http-request.js";
+import { ProcessRegistry } from "./process/registry.js";
+import { ToolRegistryImpl } from "./registry.js";
+import type { RunCodeEventSink } from "./run-code/broker.js";
+import type { RunCodeConfig } from "./run-code/limits.js";
+import { type SessionFsScope } from "./sandbox/config.js";
+import { type SandboxGrantView } from "./sandbox/provider.js";
+import { RegistryHandle } from "./tools/run-code.js";
+export declare const TOOLS_PLUGIN_NAME = "celestea.tools";
+/** `run_code` wiring (W255): broker limits + the optional sub-call event sink. */
+export interface RunCodeMount {
+    /** Broker limits; default = `runCodeConfigFromEnv()` (CELAESTEA_RUN_CODE_TIMEOUT_MS). */
+    config?: RunCodeConfig;
+    /** Session-log sink for nested sub-call rows (see `RunCodeEventSink`). */
+    events?: RunCodeEventSink;
+}
+/**
+ * Per-session grants (W516) reaching the assembly point. All three views are
+ * widen-only; `undefined` (no `grants.json`) reproduces the env-derived posture
+ * byte for byte.
+ */
+export interface ToolAssemblyGrants extends PathGuardGrants, SandboxGrantView, SsrfGrantView {
+}
+export interface ToolsPluginOptions {
+    /** Tool set; default: the six builtins sharing [processes] + [sandbox]. */
+    tools?: readonly Tool[];
+    sandbox?: Sandbox;
+    processes?: ProcessRegistry;
+    /** Guard chain override: `null` disables guarding, `undefined` = env default. */
+    guard?: ToolGuard | null;
+    env?: NodeJS.ProcessEnv;
+    /** Session grants (W516): read from the session's `grants.json` by the host. */
+    grants?: ToolAssemblyGrants;
+    /**
+     * W768: the composing SESSION's own workspace (cwd + containment root for the
+     * default sandbox, writable root for the path guard). Omitted/null = the
+     * process-wide env posture, which is what a detached or legacy session keeps.
+     */
+    scope?: SessionFsScope | null;
+    /**
+     * `run_code` mount: default = mounted; `false` = not registered. The tool is
+     * registered *before* its registry handle is bound, so sub-calls ride this
+     * assembly's exact pipeline (runtime compose parity).
+     */
+    runCode?: RunCodeMount | false;
+    /**
+     * W783: the host's user-question service. Supplied = the default tool set also
+     * carries `ask_user_question`; absent = it does not (an embedding with no human
+     * answerer must not offer a tool that could only ever hang).
+     */
+    questions?: UserQuestionService | null;
+    /**
+     * W804: the session's attachment store. Supplied = the default tool set also
+     * carries `read_image`; absent = it does not (no store, no image tool).
+     */
+    attachments?: AttachmentStore | null;
+    /** W804: false ONLY when the model explicitly excludes image input (section 6.6). */
+    imageInputAllowed?: boolean;
+    /** W804: the target model id, for the read_image refusal text. */
+    model?: string;
+}
+/** The wired handles a compose root keeps after mounting the plugin. */
+export interface ToolAssembly {
+    registry: ToolRegistryImpl;
+    sandbox: Sandbox;
+    processes: ProcessRegistry;
+    guardMounted: boolean;
+    /** Late-bound handle of the mounted `run_code` (`null` when disabled). */
+    runCode: RegistryHandle | null;
+}
+/** Build the tool assembly without mounting it (compose roots / tests). */
+export declare function assembleTools(options?: ToolsPluginOptions): ToolAssembly;
+/** The `http_request` options of this assembly (grants merged into allow). */
+export declare function httpOptions(env: NodeJS.ProcessEnv, grants: SsrfGrantView): HttpRequestToolOptions;
+export declare function toolsPlugin(options?: ToolsPluginOptions): Plugin;