@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/work/src/runtime/worker-pool-entry.ts

@@ -0,0 +1,102 @@
+import { parentPort } from "node:worker_threads";
+import { DocumentReaderError } from "../document-reader/errors.js";
+import type { DocumentParser } from "../document-reader/index.js";
+
+/**
+ * Module worker entry for `worker-pool.ts` (plan 127 Task 2). The parent sends typed
+ * `{ kind, payload }` objects; handlers are a static map — never a path or source from a message.
+ *
+ * Product handlers (plan 127 Task 3) run the measured CPU-bound cores off the agent's event loop.
+ * Only `document.extract` survived the Task 3 revert: the sheets/documents model parses cloned a
+ * result larger than the input and regressed their own wall clock (see evidence §9), while the
+ * document reader's extract returns literal text and gained loop freedom at ~no cost. The handler
+ * calls the same parser the inline path calls; inside a worker `shouldOffloadToPool()` is false,
+ * so it cannot recursively spawn another pool. `probe.*` handlers are the pool's own self-check
+ * surface.
+ */
+
+export type WorkerPoolReply = { ok: true; value: unknown } | { ok: false; error: { name: string; message: string } };
+
+type Handler = (payload: unknown) => unknown | Promise<unknown>;
+
+let workerDocumentParsers: Promise<Map<string, DocumentParser>> | undefined;
+
+/** Same default wiring as `createDocumentReader`, built once per worker and memoized. */
+async function documentParsers(): Promise<Map<string, DocumentParser>> {
+  workerDocumentParsers ??= (async () => {
+    const { createDocxParser, createOoxmlParser, createPdfParser } = await import("../document-reader/parsers.js");
+    const parsers = [
+      await createPdfParser(),
+      await createDocxParser(),
+      createOoxmlParser("xlsx", "sheet", "xl/workbook.xml"),
+      createOoxmlParser("pptx", "deck", "ppt/presentation.xml"),
+    ];
+    return new Map(parsers.map((parser) => [parser.format, parser]));
+  })();
+  return workerDocumentParsers;
+}
+
+const HANDLERS: Record<string, Handler> = {
+  // --- product surface (plan 127 Task 3): the document reader's large-buffer extract ---
+  "document.extract": async (payload) => {
+    const { format, bytes, maxPages, maxTextBytes } = payload as {
+      format: string;
+      bytes: Uint8Array;
+      maxPages: number;
+      maxTextBytes: number;
+    };
+    const parser = (await documentParsers()).get(format);
+    if (!parser) throw new DocumentReaderError(`document-reader: no worker parser for format "${format}"`);
+    // The payload arrives as a plain Uint8Array (structured clone); the reader's byte gates accept it
+    // directly, so no Buffer wrap is needed (plan 127 further action #2).
+    return parser.extract(bytes, { maxPages, maxTextBytes });
+  },
+  // --- pool self-checks ---
+  "probe.echo": (payload) => payload,
+  "probe.spin": (payload) => {
+    const ms = typeof (payload as { ms?: unknown } | undefined)?.ms === "number" ? (payload as { ms: number }).ms : 0;
+    const end = Date.now() + Math.min(Math.max(ms, 0), 60_000);
+    while (Date.now() < end) {
+      // deliberately synchronous: the pool's bounded-concurrency test needs a blocking task
+    }
+    return { spunMs: ms };
+  },
+  // The kill-mid-task check: an uncaught throw inside the worker (never the parent process).
+  "probe.crash": () => {
+    setTimeout(() => {
+      throw new Error("planned worker crash (pool self-check)");
+    }, 10);
+    return new Promise<never>(() => {});
+  },
+  // Credential-free check: proves the pool's env allowlist reached this worker.
+  "probe.env": () => ({ envKeys: Object.keys(process.env).length, secret: process.env.PRISM_POOL_PROBE_SECRET ?? null }),
+};
+
+async function handle(message: unknown): Promise<void> {
+  if (message === null || typeof message !== "object") return;
+  const task = message as { kind?: unknown; payload?: unknown };
+  const handler = typeof task.kind === "string" ? HANDLERS[task.kind] : undefined;
+  if (!handler) {
+    post({ ok: false, error: { name: "WorkerPoolError", message: `unknown worker task kind: ${String(task.kind)}` } });
+    return;
+  }
+  try {
+    post({ ok: true, value: await handler(task.payload) });
+  } catch (error) {
+    post({
+      ok: false,
+      error: {
+        name: error instanceof Error ? error.name : "Error",
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+function post(reply: WorkerPoolReply): void {
+  parentPort?.postMessage(reply);
+}
+
+parentPort?.on("message", (message: unknown) => {
+  void handle(message);
+});

package/work/src/runtime/worker-pool.ts

@@ -0,0 +1,267 @@
+import { isMainThread, Worker } from "node:worker_threads";
+
+/**
+ * Internal bounded worker pool for the measured CPU-bound surfaces (plan 127 Task 2).
+ *
+ * Why it exists: `docs/_evidence/phase127-bun-concurrency.md` §3 measured four
+ * `cpu-offload-candidate` surfaces whose compute blocks the event loop far longer than a warm
+ * worker round-trip costs — PDF extract (~250-360 ms), docx parse (~52 ms), xlsx parse
+ * (~218-326 ms), csv parse (~50-65 ms) against 0.02 ms round-trip at 1 KiB … 7.2 ms at 16 MiB,
+ * i.e. ≥ 1 order of magnitude at every realistic payload. Three of those four were reverted
+ * (Task 3) because their *results* clone far slower than their inputs (§12) — the pricing rule
+ * that keeps that decision honest lives in `shouldOffloadToPool` below.
+ *
+ * Size: 8 x ~500 ms PDF extracts through a pool of N workers on a loaded 16-CPU host
+ * (2026-09-26, load/cpu ~1.1-1.5): wall 5032 / 1905 / 1122 / 920 ms and per-extract p50
+ * 542 / 471 / 548 / 852 ms for N = 1 / 2 / 4 / 8, with the parent 5 ms tick gap at 5.1 ms p50
+ * for every N. N = 2 is the winner: best per-task latency and the smallest co-tenant CPU claim
+ * (a bigger pool adds parallel CPU claim, not loop freedom, and the workspace suites are bounded
+ * to 2 concurrent leaves because those budgets flake at 3-4).
+ * ponytail: fixed 2 workers — raise only after re-measuring per-task latency and the co-tenant
+ * budget suites on an idle host.
+ *
+ * Fail-closed: a worker error or exit rejects its in-flight task (never hangs); the slot is
+ * dropped and replaced lazily by the next task. `closeWorkerPool()` rejects queued and in-flight
+ * tasks and terminates every worker (the next task spawns fresh ones). Workers get an explicit
+ * env allowlist (probe: a default Bun worker inherits all 69 parent env keys, including planted
+ * secrets, while `env: {…}` is honored and left 1 key). Nothing here logs payload contents;
+ * `workerPoolStats()` reports counts only.
+ */
+export const WORKER_POOL_MAX_WORKERS = 2;
+
+/**
+ * Input size below which a hop cannot pay for itself (plan 127 Task 1 §3): at 64 KiB inline compute
+ * is ~7 ms (csv), ~20 ms (xlsx), ~52 ms (docx) and >50 ms (pdf) against a 0.063 ms round-trip, and
+ * below it a tiny parse must not pay a cold worker spawn. This is only the input half of the price —
+ * `shouldOffloadToPool` also charges the result side.
+ */
+export const WORKER_POOL_OFFLOAD_MIN_BYTES = 64 * 1024;
+
+/** Measured one-way structured-clone prices, plan 127 §12 (Bun 1.4.2, loaded 16-CPU host). */
+const FLAT_BYTES_PER_MS = 1_250_000; // Uint8Array: 1 MiB -> 0.71 ms, 4 MiB -> 2.24 ms, 16 MiB -> 13.07 ms
+const RESULT_VALUES_PER_MS = 2_000; // model graphs: csv/xlsx 260k values -> 108/115 ms, docx 40k -> 12 ms
+const WORKER_POOL_SCHEDULING_MS = 0.1; // measured warm dispatch + settle overhead
+const OFFLOAD_MIN_COMPUTE_MARGIN = 10; // the moved pdf row is ~1500x; the reverted three were ~1-6x
+
+/**
+ * Price a hop in both directions before taking it (plan 127 further action #1).
+ *
+ * Task 1's break-even table priced only the input round-trip, and on that basis csv/xlsx/docx were
+ * offloaded and then reverted: their results are object graphs, which clone 100x slower per byte
+ * than a flat buffer (§9, §12), so the hop cost more than the parse it saved. Text and byte inputs
+ * are cheap (a 2 MB string clones in 0.06 ms — strings are shared, not copied), so the result shape
+ * is what decides. `resultValues` counts every value the clone must rebuild — containers plus leaf
+ * strings/numbers, e.g. `rows x (columns + 1)` for a sheet model — and `computeMs` is the measured
+ * (or per-unit-derived) inline cost. Offload only when the compute dwarfs both clones.
+ */
+export function shouldOffloadToPool(pricing: {
+  /** Bytes sent to the worker. */
+  readonly inputBytes: number;
+  /** Values the clone must rebuild in the result (containers plus leaf strings/numbers). */
+  readonly resultValues: number;
+  /** Expected inline compute time — measured, or derived from a measured per-unit cost. */
+  readonly computeMs: number;
+}): boolean {
+  if (!isMainThread) return false;
+  if (pricing.inputBytes < WORKER_POOL_OFFLOAD_MIN_BYTES) return false;
+  const cloneMs = pricing.inputBytes / FLAT_BYTES_PER_MS + pricing.resultValues / RESULT_VALUES_PER_MS;
+  return pricing.computeMs >= OFFLOAD_MIN_COMPUTE_MARGIN * (cloneMs + WORKER_POOL_SCHEDULING_MS);
+}
+
+/** Typed task object crossing the thread boundary — never a function, never `eval`-shaped. */
+export interface WorkerPoolTask {
+  /** Handler name registered in `worker-pool-entry.ts`, e.g. `probe.echo`. */
+  readonly kind: string;
+  /** Structured-cloneable payload. Byte caps stay at each caller's trust boundary. */
+  readonly payload?: unknown;
+}
+
+export interface WorkerPoolStats {
+  readonly workers: number;
+  readonly busy: number;
+  readonly queued: number;
+  readonly peak: number;
+  readonly completed: number;
+  readonly failed: number;
+}
+
+export class WorkerPoolError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "WorkerPoolError";
+  }
+}
+
+/** A task that failed inside the worker; carries the remote error identity for revival. */
+export class WorkerTaskError extends WorkerPoolError {
+  readonly remoteName: string;
+  readonly remoteMessage: string;
+
+  constructor(remoteName: string, remoteMessage: string) {
+    super(remoteMessage);
+    this.name = "WorkerTaskError";
+    this.remoteName = remoteName;
+    this.remoteMessage = remoteMessage;
+  }
+}
+
+/**
+ * Rebuild the caller's own error class from a remote worker failure so `instanceof` checks keep
+ * working (each class takes a message; the worker reply carries name + message only). Returns
+ * `undefined` when the failure is not a known remote task error — callers rethrow the original.
+ */
+export function reviveWorkerTaskError(error: unknown, classes: readonly (new (message: string) => Error)[]): Error | undefined {
+  if (!(error instanceof WorkerTaskError)) return undefined;
+  for (const errorClass of classes) {
+    if (errorClass.name === error.remoteName) return new errorClass(error.remoteMessage);
+  }
+  return undefined;
+}
+
+interface Job {
+  readonly task: WorkerPoolTask;
+  readonly resolve: (value: unknown) => void;
+  readonly reject: (error: Error) => void;
+}
+
+interface Slot {
+  readonly worker: Worker;
+  job: Job | null;
+  dead: boolean;
+}
+
+type WorkerReply = { ok: true; value: unknown } | { ok: false; error: { name: string; message: string } };
+
+const WORKER_ENTRY = new URL("./worker-pool-entry.js", import.meta.url);
+const ENV_ALLOWLIST = ["PATH", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL"] as const;
+
+const slots = new Set<Slot>();
+const idle: Slot[] = [];
+const queue: Job[] = [];
+let busy = 0;
+let peak = 0;
+let completed = 0;
+let failed = 0;
+
+/** Run one task on the pool; the pool spawns workers lazily and never hangs. */
+export function runInPool<TOut = unknown>(task: WorkerPoolTask): Promise<TOut> {
+  return new Promise<TOut>((resolve, reject) => {
+    const job: Job = { task, resolve: resolve as (value: unknown) => void, reject };
+    const slot = idle.pop();
+    if (slot) {
+      dispatch(slot, job);
+      return;
+    }
+    if (slots.size < WORKER_POOL_MAX_WORKERS) {
+      dispatch(createSlot(), job);
+      return;
+    }
+    queue.push(job);
+  });
+}
+
+export function workerPoolStats(): WorkerPoolStats {
+  return { workers: slots.size, busy, queued: queue.length, peak, completed, failed };
+}
+
+/**
+ * Terminate every worker and reject queued/in-flight tasks. Idempotent; the pool lazily spawns
+ * fresh workers on the next task, so a host (or a test file) that shut it down can still use it.
+ */
+export async function closeWorkerPool(): Promise<void> {
+  const error = new WorkerPoolError("worker pool is closed");
+  while (queue.length > 0) {
+    failed += 1;
+    queue.shift()?.reject(error);
+  }
+  await Promise.all([...slots].map((slot) => dropSlot(slot, error, { terminate: true })));
+  idle.length = 0;
+}
+
+function createSlot(): Slot {
+  const env: Record<string, string> = {};
+  for (const key of ENV_ALLOWLIST) {
+    const value = process.env[key];
+    if (value !== undefined) env[key] = value;
+  }
+  const worker = new Worker(WORKER_ENTRY, { env });
+  const slot: Slot = { worker, job: null, dead: false };
+  worker.on("message", (reply: WorkerReply) => settle(slot, reply));
+  worker.on("error", (error: Error) => {
+    void dropSlot(slot, new WorkerPoolError(`worker failed: ${error.message}`, { cause: error }));
+  });
+  worker.on("exit", (code: number) => {
+    void dropSlot(slot, new WorkerPoolError(`worker exited with code ${code}`));
+  });
+  worker.unref();
+  slots.add(slot);
+  return slot;
+}
+
+function dispatch(slot: Slot, job: Job): void {
+  slot.job = job;
+  busy += 1;
+  peak = Math.max(peak, busy);
+  slot.worker.ref();
+  try {
+    slot.worker.postMessage(job.task);
+  } catch (error) {
+    // Clone failure rejects this task; the worker itself is still healthy.
+    slot.job = null;
+    busy -= 1;
+    failed += 1;
+    idle.push(slot);
+    slot.worker.unref();
+    job.reject(new WorkerPoolError(`worker task is not structured-cloneable: ${(error as Error).message}`, { cause: error }));
+    pump();
+  }
+}
+
+function settle(slot: Slot, reply: WorkerReply): void {
+  const job = slot.job;
+  if (!job) return;
+  slot.job = null;
+  busy -= 1;
+  idle.push(slot);
+  slot.worker.unref();
+  if (reply?.ok === true) {
+    completed += 1;
+    job.resolve(reply.value);
+  } else {
+    failed += 1;
+    const detail = reply && reply.ok === false ? reply.error : undefined;
+    job.reject(new WorkerTaskError(detail?.name ?? "WorkerPoolError", detail?.message ?? "worker task failed"));
+  }
+  pump();
+}
+
+function pump(): void {
+  while (queue.length > 0) {
+    const slot = idle.pop();
+    if (slot) {
+      dispatch(slot, queue.shift() as Job);
+      continue;
+    }
+    if (slots.size < WORKER_POOL_MAX_WORKERS) {
+      dispatch(createSlot(), queue.shift() as Job);
+      continue;
+    }
+    return;
+  }
+}
+
+async function dropSlot(slot: Slot, error: Error, options: { terminate?: boolean } = {}): Promise<void> {
+  if (slot.dead) return;
+  slot.dead = true;
+  slots.delete(slot);
+  const index = idle.indexOf(slot);
+  if (index >= 0) idle.splice(index, 1);
+  if (slot.job) {
+    slot.job.reject(error);
+    slot.job = null;
+    busy -= 1;
+    failed += 1;
+  }
+  if (options.terminate) await slot.worker.terminate();
+  pump();
+}

package/work/src/sandbox/composition.ts

@@ -0,0 +1,212 @@
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import { createWorkTools } from "../connectors/tools.js";
+import type { WorkToolsOptions } from "../connectors/types.js";
+import type { DocumentReader } from "../document-reader/index.js";
+import type { WorkSandboxFilesystem } from "../tools/filesystem.js";
+import { createOfficeTools, type OfficeToolsOptions } from "../tools/office.js";
+
+const TOKEN_ENV = /^(M365_|GOOGLE_)/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SOFFICE = /(^|\/)soffice(\.bin)?$/;
+const CAPABILITY_KEYS = [
+  "workspaceCoherent",
+  "filesystemIsolated",
+  "networkIsolated",
+  "processIsolated",
+  "privilegeIsolated",
+  "egressRestricted",
+] as const;
+
+const EMPTY_CAPABILITIES: WorkSandboxCapabilities = Object.freeze({
+  workspaceCoherent: false,
+  filesystemIsolated: false,
+  networkIsolated: false,
+  processIsolated: false,
+  privilegeIsolated: false,
+  egressRestricted: false,
+});
+
+/** Default container env: no token names. Host may add non-token keys via `env`. */
+export const DEFAULT_WORK_SANDBOX_ENV: Readonly<Record<string, string>> = Object.freeze({});
+
+export class WorkSandboxError extends Error {
+  readonly code = "ERR_PRISM_WORK_SANDBOX";
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkSandboxError";
+  }
+}
+
+export interface WorkSandboxCapabilities {
+  readonly workspaceCoherent: boolean;
+  readonly filesystemIsolated: boolean;
+  readonly networkIsolated: boolean;
+  readonly processIsolated: boolean;
+  readonly privilegeIsolated: boolean;
+  readonly egressRestricted: boolean;
+}
+
+export interface WorkSandboxExecFileRequest {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly timeout?: number;
+  readonly signal?: AbortSignal;
+  readonly onData?: (chunk: Uint8Array) => void;
+}
+
+/** Duck-typed `DisposableSandbox` plus optional filesystem. Host injects; this package does not import coding-tools. */
+export interface WorkSandbox {
+  readonly capabilities?: Readonly<WorkSandboxCapabilities>;
+  readonly root?: string;
+  execFile(request: WorkSandboxExecFileRequest): Promise<{ exitCode: number | null }>;
+  readFile?(path: string, options: { readonly maxBytes: number; readonly signal?: AbortSignal }): Promise<Uint8Array>;
+  writeFile?(path: string, bytes: Uint8Array, options: { readonly maxBytes: number; readonly signal?: AbortSignal }): Promise<void>;
+}
+
+export interface WorkCompositionOptions {
+  readonly sandbox: WorkSandbox;
+  readonly connectors?: WorkToolsOptions;
+  readonly office?: OfficeToolsOptions;
+  readonly reader?: DocumentReader;
+  readonly filesystem?: WorkSandboxFilesystem;
+  readonly env?: Readonly<Record<string, string>>;
+}
+
+export interface WorkComposition {
+  readonly capabilities: WorkSandboxCapabilities;
+  readonly env: Readonly<Record<string, string>>;
+  readonly sandbox: WorkSandbox;
+  readonly reader?: DocumentReader;
+  execFile(request: WorkSandboxExecFileRequest): Promise<{ exitCode: number | null }>;
+}
+
+export interface WorkCompositionResult {
+  readonly tools: readonly ToolDefinition[];
+  readonly composition: WorkComposition;
+}
+
+export function createWorkComposition(options: WorkCompositionOptions): WorkCompositionResult {
+  if (!options?.sandbox || typeof options.sandbox.execFile !== "function") {
+    throw new WorkSandboxError("sandbox.execFile is required");
+  }
+  const env = Object.freeze(assertWorkSandboxEnv(options.env ?? DEFAULT_WORK_SANDBOX_ENV));
+  const capabilities = resolveWorkSandboxCapabilities(options.sandbox.capabilities);
+  const filesystem = options.filesystem ?? asFilesystem(options.sandbox);
+  const execFile = (request: WorkSandboxExecFileRequest) => runWorkExecFile(options.sandbox, request, env);
+
+  const tools: ToolDefinition[] = [
+    ...createOfficeTools({ ...options.office, ...(filesystem ? { filesystem } : {}) }),
+    workExecTool(execFile),
+  ];
+  if (options.connectors) {
+    tools.push(...createWorkTools({ ...options.connectors, filesystem: options.connectors.filesystem ?? filesystem }));
+  }
+
+  return {
+    tools,
+    composition: {
+      capabilities,
+      env,
+      sandbox: options.sandbox,
+      ...(options.reader ? { reader: options.reader } : {}),
+      execFile,
+    },
+  };
+}
+
+export function assertWorkSandboxEnv(env: Readonly<Record<string, string>>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!ENV_NAME.test(key)) throw new WorkSandboxError(`invalid env name: ${key}`);
+    if (TOKEN_ENV.test(key)) throw new WorkSandboxError(`${key} is not allowed in the work sandbox`);
+    if (typeof value !== "string") throw new WorkSandboxError(`env value for ${key} must be a string`);
+    out[key] = value;
+  }
+  return out;
+}
+
+export function resolveWorkSandboxCapabilities(metadata: Readonly<WorkSandboxCapabilities> | undefined): WorkSandboxCapabilities {
+  if (!metadata || typeof metadata !== "object") return EMPTY_CAPABILITIES;
+  const keys = Object.keys(metadata);
+  if (keys.length !== CAPABILITY_KEYS.length) return EMPTY_CAPABILITIES;
+  for (const key of CAPABILITY_KEYS) {
+    if (typeof (metadata as Record<string, unknown>)[key] !== "boolean") return EMPTY_CAPABILITIES;
+  }
+  return Object.freeze({
+    workspaceCoherent: metadata.workspaceCoherent,
+    filesystemIsolated: metadata.filesystemIsolated,
+    networkIsolated: metadata.networkIsolated,
+    processIsolated: metadata.processIsolated,
+    privilegeIsolated: metadata.privilegeIsolated,
+    egressRestricted: metadata.egressRestricted,
+  });
+}
+
+function asFilesystem(sandbox: WorkSandbox): WorkSandboxFilesystem | undefined {
+  if (typeof sandbox.root !== "string" || !sandbox.root.startsWith("/")) return undefined;
+  if (typeof sandbox.readFile !== "function" || typeof sandbox.writeFile !== "function") return undefined;
+  return sandbox as WorkSandboxFilesystem;
+}
+
+async function runWorkExecFile(
+  sandbox: WorkSandbox,
+  request: WorkSandboxExecFileRequest,
+  defaultEnv: Readonly<Record<string, string>>,
+): Promise<{ exitCode: number | null }> {
+  if (!request.file || request.file.includes("\0")) throw new WorkSandboxError("execFile requires a non-empty file path");
+  if (!Array.isArray(request.args) || request.args.some((arg) => typeof arg !== "string" || arg.includes("\0"))) {
+    throw new WorkSandboxError("execFile args must be a string array without NUL");
+  }
+  const args = sofficeArgs(request.file, request.args);
+  const env = assertWorkSandboxEnv({ ...defaultEnv, ...request.env });
+  return sandbox.execFile({ ...request, args, env });
+}
+
+function sofficeArgs(file: string, args: readonly string[]): readonly string[] {
+  if (!SOFFICE.test(file)) return args;
+  if (args.some((arg) => arg.startsWith("--accept") || /macro/i.test(arg))) {
+    throw new WorkSandboxError("LibreOffice macro/socket flags are not allowed");
+  }
+  if (args.some((arg) => arg.startsWith("-env:UserInstallation="))) return args;
+  return ["-env:UserInstallation=file:///tmp/lo-profile", "--headless", "--norestore", ...args];
+}
+
+function workExecTool(execFile: WorkComposition["execFile"]): ToolDefinition {
+  return {
+    name: "work_exec",
+    description: "Run an argv command inside the injected work sandbox. Results are untrusted.",
+    parameters: {
+      type: "object",
+      properties: {
+        file: { type: "string" },
+        args: { type: "array", items: { type: "string" } },
+        cwd: { type: "string" },
+      },
+      required: ["file", "args"],
+      additionalProperties: false,
+    },
+    effect: { kind: "external_mutation", idempotency: "unsupported" },
+    effects: ["execute"],
+    async execute(args: JsonObject, context: ToolExecutionContext): Promise<ToolResult> {
+      try {
+        const file = args.file;
+        if (typeof file !== "string" || !file) throw new WorkSandboxError("file must be a non-empty string");
+        const rawArgs = args.args;
+        if (!Array.isArray(rawArgs) || rawArgs.some((arg) => typeof arg !== "string")) {
+          throw new WorkSandboxError("args must be a string array");
+        }
+        const cwd = args.cwd;
+        if (cwd !== undefined && (typeof cwd !== "string" || !cwd.startsWith("/"))) {
+          throw new WorkSandboxError("cwd must be an absolute sandbox path");
+        }
+        const result = await execFile({ file, args: rawArgs as string[], ...(cwd ? { cwd } : {}) });
+        return { toolCallId: context.toolCallId, name: "work_exec", value: { exitCode: result.exitCode, untrusted: true } };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { toolCallId: context.toolCallId, name: "work_exec", content: [{ type: "text", text: message }], error: { message } };
+      }
+    },
+  };
+}

package/work/src/sandbox/image.ts

@@ -0,0 +1,6 @@
+/**
+ * Host-pinned work sandbox image. The 64-zero digest is a fixture placeholder —
+ * operators replace it with `docker image inspect --format '{{.Id}}'` after build.
+ * `createDockerSandbox` requires `name@sha256:<64-hex>` and never pulls.
+ */
+export const WORK_SANDBOX_IMAGE = "prism-work-sandbox@sha256:0000000000000000000000000000000000000000000000000000000000000000";

package/work/src/sandbox/index.ts

@@ -0,0 +1,14 @@
+export {
+  assertWorkSandboxEnv,
+  createWorkComposition,
+  DEFAULT_WORK_SANDBOX_ENV,
+  resolveWorkSandboxCapabilities,
+  type WorkComposition,
+  type WorkCompositionOptions,
+  type WorkCompositionResult,
+  type WorkSandbox,
+  type WorkSandboxCapabilities,
+  WorkSandboxError,
+  type WorkSandboxExecFileRequest,
+} from "./composition.js";
+export { WORK_SANDBOX_IMAGE } from "./image.js";

package/work/src/sheets/caps.ts

@@ -0,0 +1,68 @@
+import { SheetsCapError, SheetsFormatError, SheetsValidationError } from "./errors.js";
+import type { ResolvedSheetsCaps, SheetsCaps } from "./types.js";
+
+// --- Default and Hard Ceiling Constants ---
+
+export const DEFAULT_MAX_SHEET_BYTES = 32 * 1024 * 1024; // 32 MiB
+export const HARD_MAX_SHEET_BYTES = 512 * 1024 * 1024; // 512 MiB
+
+export const DEFAULT_MAX_SHEETS = 100;
+export const HARD_MAX_SHEETS = 1_000;
+
+export const DEFAULT_MAX_ROWS = 100_000;
+export const HARD_MAX_ROWS = 1_000_000;
+
+export const DEFAULT_MAX_COLUMNS = 1_000;
+export const HARD_MAX_COLUMNS = 16_384;
+
+export const DEFAULT_INFERENCE_WINDOW_ROWS = 500;
+export const HARD_INFERENCE_WINDOW_ROWS = 5_000;
+
+export const DEFAULT_MAX_WARNINGS = 100;
+export const HARD_MAX_WARNINGS = 1_000;
+
+function resolveCap(name: string, value: number | undefined, defaultVal: number, hardCap: number): number {
+  if (value === undefined) return defaultVal;
+  if (!Number.isInteger(value) || value <= 0 || value > hardCap) {
+    throw new SheetsValidationError(`sheets cap ${name} must be an integer in (0, ${hardCap}], got ${value}`);
+  }
+  return value;
+}
+
+/**
+ * Resolves user-supplied caps against safe defaults and hard ceilings.
+ */
+export function resolveSheetsCaps(caps?: SheetsCaps): ResolvedSheetsCaps {
+  return {
+    maxBytes: resolveCap("maxBytes", caps?.maxBytes, DEFAULT_MAX_SHEET_BYTES, HARD_MAX_SHEET_BYTES),
+    maxSheets: resolveCap("maxSheets", caps?.maxSheets, DEFAULT_MAX_SHEETS, HARD_MAX_SHEETS),
+    maxRows: resolveCap("maxRows", caps?.maxRows, DEFAULT_MAX_ROWS, HARD_MAX_ROWS),
+    maxColumns: resolveCap("maxColumns", caps?.maxColumns, DEFAULT_MAX_COLUMNS, HARD_MAX_COLUMNS),
+    inferenceWindowRows: resolveCap(
+      "inferenceWindowRows",
+      caps?.inferenceWindowRows,
+      DEFAULT_INFERENCE_WINDOW_ROWS,
+      HARD_INFERENCE_WINDOW_ROWS,
+    ),
+    maxWarnings: resolveCap("maxWarnings", caps?.maxWarnings, DEFAULT_MAX_WARNINGS, HARD_MAX_WARNINGS),
+  };
+}
+
+/**
+ * Enforces byte size ceiling. Throws {@link SheetsCapError} if exceeded.
+ */
+export function validateByteCap(byteLength: number, caps: ResolvedSheetsCaps): void {
+  if (byteLength > caps.maxBytes) {
+    throw new SheetsCapError(`input size ${byteLength} bytes exceeds maxBytes cap (${caps.maxBytes})`);
+  }
+}
+
+/**
+ * Validates standard PKZIP magic bytes (PK\x03\x04 = 0x50, 0x4b, 0x03, 0x04) at the container boundary.
+ * Throws {@link SheetsFormatError} if the buffer does not begin with the ZIP signature.
+ */
+export function validateZipSignature(bytes: Uint8Array): void {
+  if (bytes.length < 4 || bytes[0] !== 0x50 || bytes[1] !== 0x4b || bytes[2] !== 0x03 || bytes[3] !== 0x04) {
+    throw new SheetsFormatError("Invalid XLSX container: missing ZIP signature (PK\\x03\\x04)");
+  }
+}