@draht/rlm 2026.7.12-1

package/dist/prompts.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Prompt tier selection and templating for `@draht/rlm`'s root loop.
+ *
+ * Three tuned system-prompt templates (`packages/rlm/prompts/*.md`) mirror
+ * the technique's documented mechanics (root LM writes Python that peeks,
+ * chunks, and searches `context`, calls `llm_query` for recursive sub-calls,
+ * terminates via `FINAL`/`FINAL_VAR` — see R26-RLM.4-7) at three levels of
+ * verbosity, auto-selected from the resolved root model's context window per
+ * R27-SLM.1/.4. See .planning/phases/27-sub-llm-integration/27-01-PLAN.md,
+ * Architecture sections 3-4.
+ */
+export type PromptTier = "frontier" | "coder-mid" | "small-context";
+/** Substitution variables for {@link renderPrompt}. */
+export interface PromptVars {
+    /** What kind of content `context` holds (e.g. "text", "code", "logs", "json"). */
+    contextType: string;
+    /** Total character length of the full `context` string. */
+    contextTotalLength: number;
+    /** Suggested chunk boundary sizes (characters), in order. */
+    chunkLengths: number[];
+    /** Max number of `llm_query` sub-calls allowed this session. */
+    maxSubCallBudget: number;
+    /** Max characters per `llm_query` sub-call prompt. */
+    subCallCharBudget: number;
+}
+/**
+ * Picks a prompt tier from the resolved root model's `contextWindow`
+ * (per @draht/ai's `Model.contextWindow`).
+ *
+ * Thresholds (chosen to track real-world context-window tiers rather than
+ * arbitrary round numbers):
+ *  - `>= 500_000`: "frontier" — models with genuinely huge (500k-2M token)
+ *    windows (e.g. 1M-context Claude/Gemini variants) that can afford a
+ *    terser prompt because they have ample headroom even after the
+ *    constant-size history metadata (R26-RLM.7) accumulates over many
+ *    steps.
+ *  - `>= 128_000`: "coder-mid" — 128k-500k is the most common modern
+ *    context ceiling (GPT-4-class, Claude default, DeepSeek-V3, etc.);
+ *    plenty of room for a step-by-step prompt but not so much that
+ *    verbosity is free.
+ *  - below `128_000`: "small-context" — constrained-window models need the
+ *    most explicit scaffolding and the smallest suggested chunk/peek sizes,
+ *    since the prompt itself is a proportionally larger share of their
+ *    budget.
+ */
+export declare function selectTier(contextWindow: number): PromptTier;
+/** Simple `{{token}}` substitution -- no templating engine dependency needed. */
+export declare function renderPrompt(tier: PromptTier, vars: PromptVars): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,eAAe,CAAC;AAEpE,uDAAuD;AACvD,MAAM,WAAW,UAAU;IAC1B,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAqBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAI5D;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAQvE"}

package/dist/prompts.js

@@ -0,0 +1,71 @@
+/**
+ * Prompt tier selection and templating for `@draht/rlm`'s root loop.
+ *
+ * Three tuned system-prompt templates (`packages/rlm/prompts/*.md`) mirror
+ * the technique's documented mechanics (root LM writes Python that peeks,
+ * chunks, and searches `context`, calls `llm_query` for recursive sub-calls,
+ * terminates via `FINAL`/`FINAL_VAR` — see R26-RLM.4-7) at three levels of
+ * verbosity, auto-selected from the resolved root model's context window per
+ * R27-SLM.1/.4. See .planning/phases/27-sub-llm-integration/27-01-PLAN.md,
+ * Architecture sections 3-4.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROMPTS_DIR = join(__dirname, "..", "prompts");
+const TIER_FILENAMES = {
+    frontier: "frontier.md",
+    "coder-mid": "coder-mid.md",
+    "small-context": "small-context.md",
+};
+// Templates are static files on disk; read once per tier and cache rather
+// than re-reading on every renderPrompt() call.
+const templateCache = new Map();
+function loadTemplate(tier) {
+    const cached = templateCache.get(tier);
+    if (cached !== undefined)
+        return cached;
+    const path = join(PROMPTS_DIR, TIER_FILENAMES[tier]);
+    const template = readFileSync(path, "utf8");
+    templateCache.set(tier, template);
+    return template;
+}
+/**
+ * Picks a prompt tier from the resolved root model's `contextWindow`
+ * (per @draht/ai's `Model.contextWindow`).
+ *
+ * Thresholds (chosen to track real-world context-window tiers rather than
+ * arbitrary round numbers):
+ *  - `>= 500_000`: "frontier" — models with genuinely huge (500k-2M token)
+ *    windows (e.g. 1M-context Claude/Gemini variants) that can afford a
+ *    terser prompt because they have ample headroom even after the
+ *    constant-size history metadata (R26-RLM.7) accumulates over many
+ *    steps.
+ *  - `>= 128_000`: "coder-mid" — 128k-500k is the most common modern
+ *    context ceiling (GPT-4-class, Claude default, DeepSeek-V3, etc.);
+ *    plenty of room for a step-by-step prompt but not so much that
+ *    verbosity is free.
+ *  - below `128_000`: "small-context" — constrained-window models need the
+ *    most explicit scaffolding and the smallest suggested chunk/peek sizes,
+ *    since the prompt itself is a proportionally larger share of their
+ *    budget.
+ */
+export function selectTier(contextWindow) {
+    if (contextWindow >= 500_000)
+        return "frontier";
+    if (contextWindow >= 128_000)
+        return "coder-mid";
+    return "small-context";
+}
+/** Simple `{{token}}` substitution -- no templating engine dependency needed. */
+export function renderPrompt(tier, vars) {
+    const template = loadTemplate(tier);
+    return template
+        .replaceAll("{{context_type}}", vars.contextType)
+        .replaceAll("{{context_total_length}}", String(vars.contextTotalLength))
+        .replaceAll("{{chunk_lengths}}", JSON.stringify(vars.chunkLengths))
+        .replaceAll("{{max_sub_call_budget}}", String(vars.maxSubCallBudget))
+        .replaceAll("{{sub_call_char_budget}}", String(vars.subCallCharBudget));
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AAkBrD,MAAM,cAAc,GAA+B;IAClD,QAAQ,EAAE,aAAa;IACvB,WAAW,EAAE,cAAc;IAC3B,eAAe,EAAE,kBAAkB;CACnC,CAAC;AAEF,0EAA0E;AAC1E,gDAAgD;AAChD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAsB,CAAC;AAEpD,SAAS,YAAY,CAAC,IAAgB;IACrC,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAClC,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,UAAU,CAAC,aAAqB;IAC/C,IAAI,aAAa,IAAI,OAAO;QAAE,OAAO,UAAU,CAAC;IAChD,IAAI,aAAa,IAAI,OAAO;QAAE,OAAO,WAAW,CAAC;IACjD,OAAO,eAAe,CAAC;AACxB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,IAAgB,EAAE,IAAgB;IAC9D,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,QAAQ;SACb,UAAU,CAAC,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC;SAChD,UAAU,CAAC,0BAA0B,EAAE,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;SACvE,UAAU,CAAC,mBAAmB,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;SAClE,UAAU,CAAC,yBAAyB,EAAE,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;SACpE,UAAU,CAAC,0BAA0B,EAAE,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAC1E,CAAC","sourcesContent":["/**\n * Prompt tier selection and templating for `@draht/rlm`'s root loop.\n *\n * Three tuned system-prompt templates (`packages/rlm/prompts/*.md`) mirror\n * the technique's documented mechanics (root LM writes Python that peeks,\n * chunks, and searches `context`, calls `llm_query` for recursive sub-calls,\n * terminates via `FINAL`/`FINAL_VAR` — see R26-RLM.4-7) at three levels of\n * verbosity, auto-selected from the resolved root model's context window per\n * R27-SLM.1/.4. See .planning/phases/27-sub-llm-integration/27-01-PLAN.md,\n * Architecture sections 3-4.\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst PROMPTS_DIR = join(__dirname, \"..\", \"prompts\");\n\nexport type PromptTier = \"frontier\" | \"coder-mid\" | \"small-context\";\n\n/** Substitution variables for {@link renderPrompt}. */\nexport interface PromptVars {\n\t/** What kind of content `context` holds (e.g. \"text\", \"code\", \"logs\", \"json\"). */\n\tcontextType: string;\n\t/** Total character length of the full `context` string. */\n\tcontextTotalLength: number;\n\t/** Suggested chunk boundary sizes (characters), in order. */\n\tchunkLengths: number[];\n\t/** Max number of `llm_query` sub-calls allowed this session. */\n\tmaxSubCallBudget: number;\n\t/** Max characters per `llm_query` sub-call prompt. */\n\tsubCallCharBudget: number;\n}\n\nconst TIER_FILENAMES: Record<PromptTier, string> = {\n\tfrontier: \"frontier.md\",\n\t\"coder-mid\": \"coder-mid.md\",\n\t\"small-context\": \"small-context.md\",\n};\n\n// Templates are static files on disk; read once per tier and cache rather\n// than re-reading on every renderPrompt() call.\nconst templateCache = new Map<PromptTier, string>();\n\nfunction loadTemplate(tier: PromptTier): string {\n\tconst cached = templateCache.get(tier);\n\tif (cached !== undefined) return cached;\n\tconst path = join(PROMPTS_DIR, TIER_FILENAMES[tier]);\n\tconst template = readFileSync(path, \"utf8\");\n\ttemplateCache.set(tier, template);\n\treturn template;\n}\n\n/**\n * Picks a prompt tier from the resolved root model's `contextWindow`\n * (per @draht/ai's `Model.contextWindow`).\n *\n * Thresholds (chosen to track real-world context-window tiers rather than\n * arbitrary round numbers):\n *  - `>= 500_000`: \"frontier\" — models with genuinely huge (500k-2M token)\n *    windows (e.g. 1M-context Claude/Gemini variants) that can afford a\n *    terser prompt because they have ample headroom even after the\n *    constant-size history metadata (R26-RLM.7) accumulates over many\n *    steps.\n *  - `>= 128_000`: \"coder-mid\" — 128k-500k is the most common modern\n *    context ceiling (GPT-4-class, Claude default, DeepSeek-V3, etc.);\n *    plenty of room for a step-by-step prompt but not so much that\n *    verbosity is free.\n *  - below `128_000`: \"small-context\" — constrained-window models need the\n *    most explicit scaffolding and the smallest suggested chunk/peek sizes,\n *    since the prompt itself is a proportionally larger share of their\n *    budget.\n */\nexport function selectTier(contextWindow: number): PromptTier {\n\tif (contextWindow >= 500_000) return \"frontier\";\n\tif (contextWindow >= 128_000) return \"coder-mid\";\n\treturn \"small-context\";\n}\n\n/** Simple `{{token}}` substitution -- no templating engine dependency needed. */\nexport function renderPrompt(tier: PromptTier, vars: PromptVars): string {\n\tconst template = loadTemplate(tier);\n\treturn template\n\t\t.replaceAll(\"{{context_type}}\", vars.contextType)\n\t\t.replaceAll(\"{{context_total_length}}\", String(vars.contextTotalLength))\n\t\t.replaceAll(\"{{chunk_lengths}}\", JSON.stringify(vars.chunkLengths))\n\t\t.replaceAll(\"{{max_sub_call_budget}}\", String(vars.maxSubCallBudget))\n\t\t.replaceAll(\"{{sub_call_char_budget}}\", String(vars.subCallCharBudget));\n}\n"]}

package/dist/router-session.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Router-backed `RlmSession` factory.
+ *
+ * `RlmSession` (session.ts) takes `rootLlm`/`llmQuery` as injected callbacks
+ * -- this module is the production wiring that builds those callbacks on top
+ * of `@draht/router`'s `ModelRouter`, selects the right system-prompt tier
+ * from the resolved `rlm-root` model's context window (prompts.ts), and logs
+ * a cost entry (via `@draht/router`'s `estimateCost`/`logCost`) for every
+ * root and sub call, tagged with a single `trajectoryId` shared across the
+ * whole session. See .planning/phases/27-sub-llm-integration/27-01-PLAN.md,
+ * Architecture section 5.
+ */
+import type { ModelRouter } from "@draht/router";
+import { RlmSession } from "./session.js";
+export interface CreateRouterBackedSessionOptions {
+    /** Becomes the `context` variable inside the REPL (see `RlmSessionOptions.prompt`). */
+    prompt: string;
+    /**
+     * Router used to resolve models and stream completions for both the
+     * "rlm-root" and "rlm-sub" roles. Caller-supplied so production code
+     * passes a real `ModelRouter` and tests can inject a fake one shaped
+     * like its public API, with no real network calls.
+     */
+    router: ModelRouter;
+    /** What kind of content `prompt` holds (e.g. "text", "code", "logs", "json"). Default "text". */
+    contextType?: string;
+    /** Max number of `llm_query` sub-calls advertised to the root LM this session. Default 50. */
+    maxSubCallBudget?: number;
+    /** Max characters per `llm_query` sub-call prompt advertised to the root LM. Default 12_000. */
+    subCallCharBudget?: number;
+    /** Passthrough to `logCost`'s `logPath` param; defaults to `.draht/cost-log.jsonl`. */
+    costLogPath?: string;
+    /** `CostEntry.sessionId` for every cost entry this session logs. Defaults to the generated `trajectoryId`. */
+    sessionId?: string;
+    /**
+     * Directory the trajectory JSONL log (`.draht/rlm/<trajectoryId>.jsonl`)
+     * is written under (Phase 30, `trajectory.ts`). Passed straight through to
+     * `appendTrajectoryEntry`'s `logDir` param; defaults to `.draht/rlm/`.
+     */
+    trajectoryLogDir?: string;
+}
+/**
+ * Builds a real `@draht/router`-backed `RlmSession`: resolves the "rlm-root"
+ * model to pick a prompt tier, renders that tier's system prompt with the
+ * real prompt's length/chunk info, and wires `rootLlm`/`llmQuery` to call
+ * `router.streamSimple("rlm-root" | "rlm-sub", ...)`, logging a cost entry
+ * (tagged with one `trajectoryId` per session) after every call.
+ */
+export declare function createRouterBackedSession(opts: CreateRouterBackedSessionOptions): RlmSession;
+//# sourceMappingURL=router-session.d.ts.map

package/dist/router-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-session.d.ts","sourceRoot":"","sources":["../src/router-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C,MAAM,WAAW,gCAAgC;IAChD,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8GAA8G;IAC9G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoID;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,gCAAgC,GAAG,UAAU,CA2I5F"}

package/dist/router-session.js

@@ -0,0 +1,251 @@
+/**
+ * Router-backed `RlmSession` factory.
+ *
+ * `RlmSession` (session.ts) takes `rootLlm`/`llmQuery` as injected callbacks
+ * -- this module is the production wiring that builds those callbacks on top
+ * of `@draht/router`'s `ModelRouter`, selects the right system-prompt tier
+ * from the resolved `rlm-root` model's context window (prompts.ts), and logs
+ * a cost entry (via `@draht/router`'s `estimateCost`/`logCost`) for every
+ * root and sub call, tagged with a single `trajectoryId` shared across the
+ * whole session. See .planning/phases/27-sub-llm-integration/27-01-PLAN.md,
+ * Architecture section 5.
+ */
+import { randomUUID } from "node:crypto";
+import { estimateCost, logCost } from "@draht/router";
+import { renderPrompt, selectTier } from "./prompts.js";
+import { RlmSession } from "./session.js";
+import { appendTrajectoryEntry } from "./trajectory.js";
+const DEFAULT_CONTEXT_TYPE = "text";
+const DEFAULT_MAX_SUB_CALL_BUDGET = 50;
+const DEFAULT_SUB_CALL_CHAR_BUDGET = 12_000;
+/**
+ * Fallback context window used only when the "rlm-root" role's primary
+ * model can't be resolved against the `@draht/ai` registry (should not
+ * happen with a correctly configured router, but `selectTier` still needs
+ * *some* number). 128_000 lands squarely in "coder-mid" -- the safest
+ * middle ground between over-terse (frontier) and over-verbose
+ * (small-context) prompting when we genuinely don't know the model.
+ */
+const FALLBACK_ROOT_CONTEXT_WINDOW = 128_000;
+/**
+ * Splits `totalLength` into near-equal chunks no larger than
+ * `chunkCharBudget`, used only to populate the `chunk_lengths` prompt
+ * variable with concrete, addable suggestions (not enforced anywhere).
+ */
+function computeChunkLengths(totalLength, chunkCharBudget) {
+    if (totalLength <= 0 || chunkCharBudget <= 0)
+        return [];
+    const numChunks = Math.max(1, Math.ceil(totalLength / chunkCharBudget));
+    const base = Math.floor(totalLength / numChunks);
+    const remainder = totalLength % numChunks;
+    const lengths = [];
+    for (let i = 0; i < numChunks; i++) {
+        lengths.push(base + (i < remainder ? 1 : 0));
+    }
+    return lengths;
+}
+/** Renders the single user turn sent to the root LM: prior history + what's expected next. */
+function buildRootUserTurn(contextTotalLength, contextType, history) {
+    const header = `A Python REPL is running. The variable \`context\` already holds ${contextTotalLength} ` +
+        `characters of ${contextType} content -- follow the system instructions for how to inspect, ` +
+        "chunk, and search it, and call FINAL(...)/FINAL_VAR(...) once you have the answer.";
+    if (history.length === 0) {
+        return `${header}\n\nWrite your first \`\`\`repl fenced code block now.`;
+    }
+    const steps = history.map((entry) => {
+        const lines = [
+            `--- step ${entry.step} ---`,
+            "```repl",
+            entry.code,
+            "```",
+            `stdout: ${entry.truncatedStdout || "(empty)"}`,
+        ];
+        if (entry.error)
+            lines.push(`error: ${entry.error}`);
+        return lines.join("\n");
+    });
+    return [
+        header,
+        "",
+        "History so far:",
+        "",
+        ...steps,
+        "",
+        "Continue with the next ```repl fenced code block, or call FINAL/FINAL_VAR if you already have the answer.",
+    ].join("\n");
+}
+/** Drains a `streamSimple`-shaped event stream down to its terminal `done`/`error` message. */
+async function collectAssistantMessage(stream) {
+    let final;
+    for await (const event of stream) {
+        if (event.type === "done") {
+            final = event.message;
+        }
+        else if (event.type === "error") {
+            final = event.error;
+        }
+    }
+    if (!final) {
+        throw new Error("createRouterBackedSession: router stream ended without a done/error event");
+    }
+    return final;
+}
+/** Concatenates every `text` content block of an assistant message (ignores thinking/tool-call blocks). */
+function messageText(message) {
+    let text = "";
+    for (const block of message.content) {
+        if (block.type === "text")
+            text += block.text;
+    }
+    return text;
+}
+/** Computes and appends one `CostEntry` for a completed router call, returning its `estimatedCostUsd`. */
+function logRouterCall(role, message, trajectoryId, sessionId, costLogPath) {
+    const reasoningTokens = message.usage.reasoning ?? 0;
+    const estimatedCostUsd = estimateCost(message.provider, message.model, message.usage.input, message.usage.output, reasoningTokens);
+    logCost({
+        timestamp: new Date().toISOString(),
+        role,
+        provider: message.provider,
+        model: message.model,
+        inputTokens: message.usage.input,
+        outputTokens: message.usage.output,
+        ...(reasoningTokens > 0 && { reasoningTokens }),
+        estimatedCostUsd,
+        sessionId,
+        trajectoryId,
+    }, costLogPath);
+    return estimatedCostUsd;
+}
+/**
+ * Builds a real `@draht/router`-backed `RlmSession`: resolves the "rlm-root"
+ * model to pick a prompt tier, renders that tier's system prompt with the
+ * real prompt's length/chunk info, and wires `rootLlm`/`llmQuery` to call
+ * `router.streamSimple("rlm-root" | "rlm-sub", ...)`, logging a cost entry
+ * (tagged with one `trajectoryId` per session) after every call.
+ */
+export function createRouterBackedSession(opts) {
+    const trajectoryId = randomUUID();
+    const sessionId = opts.sessionId ?? trajectoryId;
+    const contextType = opts.contextType ?? DEFAULT_CONTEXT_TYPE;
+    const maxSubCallBudget = opts.maxSubCallBudget ?? DEFAULT_MAX_SUB_CALL_BUDGET;
+    const subCallCharBudget = opts.subCallCharBudget ?? DEFAULT_SUB_CALL_CHAR_BUDGET;
+    const costLogPath = opts.costLogPath;
+    const trajectoryLogDir = opts.trajectoryLogDir;
+    // Trajectory JSONL logging (Phase 30, trajectory.ts): `rootLlm` is called
+    // once per step, always *before* that step's own `llm_query` sub-calls
+    // happen (they occur later, inside the driver's `runExec`, which
+    // `session.ts` only invokes after `rootLlm` resolves -- see session.ts's
+    // `step()`). So a step's sub-calls always land between one `rootLlm` call
+    // and the next, and the simplest correct way to correlate them without
+    // touching session.ts's core loop is: accumulate sub-call costs into
+    // `pendingStep` as they happen, and finalize+append the *previous* step's
+    // `TrajectoryStepEntry` the moment the *next* `rootLlm` call (or the final
+    // `run()` resolution, for the very last step) tells us -- via the
+    // `history` array it's handed -- that the previous step actually
+    // completed.
+    let pendingStep = null;
+    let finalizedThroughStep = 0;
+    let totalCostUsd = 0;
+    function finalizeStepIfPending(history) {
+        if (!pendingStep)
+            return;
+        const entry = history[history.length - 1];
+        // No new completed entry since the last finalize (e.g. the step that
+        // started this accumulator never finished -- a hard-killed/errored
+        // step never gets pushed to `history`): nothing to log, and don't
+        // double-log the previous step either.
+        if (!entry || entry.step <= finalizedThroughStep)
+            return;
+        const stepCostUsd = pendingStep.rootCostUsd + pendingStep.subCalls.reduce((sum, sub) => sum + sub.costUsd, 0);
+        totalCostUsd += stepCostUsd;
+        appendTrajectoryEntry(trajectoryId, {
+            type: "step",
+            trajectoryId,
+            step: entry.step,
+            code: entry.code,
+            truncatedStdout: entry.truncatedStdout,
+            error: entry.error,
+            subCalls: pendingStep.subCalls,
+            costUsd: stepCostUsd,
+            timestamp: entry.timestamp,
+        }, trajectoryLogDir);
+        finalizedThroughStep = entry.step;
+        pendingStep = null;
+    }
+    const rootRef = opts.router.resolve("rlm-root");
+    const rootModel = opts.router.resolveModel(rootRef);
+    const contextWindow = rootModel?.contextWindow ?? FALLBACK_ROOT_CONTEXT_WINDOW;
+    const tier = selectTier(contextWindow);
+    const contextTotalLength = opts.prompt.length;
+    const chunkLengths = computeChunkLengths(contextTotalLength, subCallCharBudget);
+    const vars = {
+        contextType,
+        contextTotalLength,
+        chunkLengths,
+        maxSubCallBudget,
+        subCallCharBudget,
+    };
+    const systemPrompt = renderPrompt(tier, vars);
+    const rootLlm = async (history) => {
+        // `history` reflects every step completed *before* this one -- so if a
+        // previous step's accumulator is still pending, this call is exactly
+        // the signal that it (and only it) has now fully completed (its own
+        // root call plus every sub-call it triggered).
+        finalizeStepIfPending(history);
+        pendingStep = { rootCostUsd: 0, subCalls: [] };
+        const context = {
+            systemPrompt,
+            messages: [
+                {
+                    role: "user",
+                    content: buildRootUserTurn(contextTotalLength, contextType, history),
+                    timestamp: Date.now(),
+                },
+            ],
+        };
+        const message = await collectAssistantMessage(opts.router.streamSimple("rlm-root", context));
+        const costUsd = logRouterCall("rlm-root", message, trajectoryId, sessionId, costLogPath);
+        pendingStep.rootCostUsd = costUsd;
+        return messageText(message);
+    };
+    const llmQuery = async (prompt) => {
+        const context = {
+            messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
+        };
+        const message = await collectAssistantMessage(opts.router.streamSimple("rlm-sub", context));
+        const costUsd = logRouterCall("rlm-sub", message, trajectoryId, sessionId, costLogPath);
+        // A sub-call always happens after `rootLlm` resolved for the step that
+        // triggered it (and before the next `rootLlm` call) -- see session.ts's
+        // `step()`/`runExec` -- so `pendingStep` is always the right step to
+        // attribute this cost to. `pendingStep` is only ever null before the
+        // very first `rootLlm` call, at which point no `llm_query` could have
+        // been dispatched yet either.
+        pendingStep?.subCalls.push({ costUsd, provider: message.provider, model: message.model });
+        return messageText(message);
+    };
+    const session = new RlmSession({ prompt: opts.prompt, rootLlm, llmQuery });
+    // Wrap (not replace the class's core loop -- session.ts is untouched)
+    // `run()` so the trajectory's last step and its terminal
+    // `TrajectoryFinalEntry` get logged once the whole session resolves.
+    // There's no other hook to observe "the session is done" from outside
+    // session.ts: `rootLlm` is never called again after the last step, so
+    // nothing else would ever finalize that step's accumulator.
+    const originalRun = session.run.bind(session);
+    session.run = async () => {
+        const result = await originalRun();
+        finalizeStepIfPending(result.history);
+        appendTrajectoryEntry(trajectoryId, {
+            type: "final",
+            trajectoryId,
+            kind: result.kind,
+            value: result.value,
+            totalCostUsd,
+            totalSteps: result.steps,
+            timestamp: new Date().toISOString(),
+        }, trajectoryLogDir);
+        return result;
+    };
+    return session;
+}
+//# sourceMappingURL=router-session.js.map

package/dist/router-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-session.js","sourceRoot":"","sources":["../src/router-session.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Router-backed `RlmSession` factory.\n *\n * `RlmSession` (session.ts) takes `rootLlm`/`llmQuery` as injected callbacks\n * -- this module is the production wiring that builds those callbacks on top\n * of `@draht/router`'s `ModelRouter`, selects the right system-prompt tier\n * from the resolved `rlm-root` model's context window (prompts.ts), and logs\n * a cost entry (via `@draht/router`'s `estimateCost`/`logCost`) for every\n * root and sub call, tagged with a single `trajectoryId` shared across the\n * whole session. See .planning/phases/27-sub-llm-integration/27-01-PLAN.md,\n * Architecture section 5.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport type { AssistantMessage, AssistantMessageEvent, Context } from \"@draht/ai/compat\";\nimport type { ModelRouter } from \"@draht/router\";\nimport { estimateCost, logCost } from \"@draht/router\";\nimport type { PromptVars } from \"./prompts.js\";\nimport { renderPrompt, selectTier } from \"./prompts.js\";\nimport { RlmSession } from \"./session.js\";\nimport { appendTrajectoryEntry } from \"./trajectory.js\";\nimport type { RlmHistoryEntry } from \"./types.js\";\n\n/** RLM-specific router roles (see `@draht/router`'s `DEFAULT_CONFIG`). */\ntype RlmRole = \"rlm-root\" | \"rlm-sub\";\n\nexport interface CreateRouterBackedSessionOptions {\n\t/** Becomes the `context` variable inside the REPL (see `RlmSessionOptions.prompt`). */\n\tprompt: string;\n\t/**\n\t * Router used to resolve models and stream completions for both the\n\t * \"rlm-root\" and \"rlm-sub\" roles. Caller-supplied so production code\n\t * passes a real `ModelRouter` and tests can inject a fake one shaped\n\t * like its public API, with no real network calls.\n\t */\n\trouter: ModelRouter;\n\t/** What kind of content `prompt` holds (e.g. \"text\", \"code\", \"logs\", \"json\"). Default \"text\". */\n\tcontextType?: string;\n\t/** Max number of `llm_query` sub-calls advertised to the root LM this session. Default 50. */\n\tmaxSubCallBudget?: number;\n\t/** Max characters per `llm_query` sub-call prompt advertised to the root LM. Default 12_000. */\n\tsubCallCharBudget?: number;\n\t/** Passthrough to `logCost`'s `logPath` param; defaults to `.draht/cost-log.jsonl`. */\n\tcostLogPath?: string;\n\t/** `CostEntry.sessionId` for every cost entry this session logs. Defaults to the generated `trajectoryId`. */\n\tsessionId?: string;\n\t/**\n\t * Directory the trajectory JSONL log (`.draht/rlm/<trajectoryId>.jsonl`)\n\t * is written under (Phase 30, `trajectory.ts`). Passed straight through to\n\t * `appendTrajectoryEntry`'s `logDir` param; defaults to `.draht/rlm/`.\n\t */\n\ttrajectoryLogDir?: string;\n}\n\nconst DEFAULT_CONTEXT_TYPE = \"text\";\nconst DEFAULT_MAX_SUB_CALL_BUDGET = 50;\nconst DEFAULT_SUB_CALL_CHAR_BUDGET = 12_000;\n\n/**\n * Fallback context window used only when the \"rlm-root\" role's primary\n * model can't be resolved against the `@draht/ai` registry (should not\n * happen with a correctly configured router, but `selectTier` still needs\n * *some* number). 128_000 lands squarely in \"coder-mid\" -- the safest\n * middle ground between over-terse (frontier) and over-verbose\n * (small-context) prompting when we genuinely don't know the model.\n */\nconst FALLBACK_ROOT_CONTEXT_WINDOW = 128_000;\n\n/**\n * Splits `totalLength` into near-equal chunks no larger than\n * `chunkCharBudget`, used only to populate the `chunk_lengths` prompt\n * variable with concrete, addable suggestions (not enforced anywhere).\n */\nfunction computeChunkLengths(totalLength: number, chunkCharBudget: number): number[] {\n\tif (totalLength <= 0 || chunkCharBudget <= 0) return [];\n\tconst numChunks = Math.max(1, Math.ceil(totalLength / chunkCharBudget));\n\tconst base = Math.floor(totalLength / numChunks);\n\tconst remainder = totalLength % numChunks;\n\tconst lengths: number[] = [];\n\tfor (let i = 0; i < numChunks; i++) {\n\t\tlengths.push(base + (i < remainder ? 1 : 0));\n\t}\n\treturn lengths;\n}\n\n/** Renders the single user turn sent to the root LM: prior history + what's expected next. */\nfunction buildRootUserTurn(contextTotalLength: number, contextType: string, history: RlmHistoryEntry[]): string {\n\tconst header =\n\t\t`A Python REPL is running. The variable \\`context\\` already holds ${contextTotalLength} ` +\n\t\t`characters of ${contextType} content -- follow the system instructions for how to inspect, ` +\n\t\t\"chunk, and search it, and call FINAL(...)/FINAL_VAR(...) once you have the answer.\";\n\n\tif (history.length === 0) {\n\t\treturn `${header}\\n\\nWrite your first \\`\\`\\`repl fenced code block now.`;\n\t}\n\n\tconst steps = history.map((entry) => {\n\t\tconst lines = [\n\t\t\t`--- step ${entry.step} ---`,\n\t\t\t\"```repl\",\n\t\t\tentry.code,\n\t\t\t\"```\",\n\t\t\t`stdout: ${entry.truncatedStdout || \"(empty)\"}`,\n\t\t];\n\t\tif (entry.error) lines.push(`error: ${entry.error}`);\n\t\treturn lines.join(\"\\n\");\n\t});\n\n\treturn [\n\t\theader,\n\t\t\"\",\n\t\t\"History so far:\",\n\t\t\"\",\n\t\t...steps,\n\t\t\"\",\n\t\t\"Continue with the next ```repl fenced code block, or call FINAL/FINAL_VAR if you already have the answer.\",\n\t].join(\"\\n\");\n}\n\n/** Drains a `streamSimple`-shaped event stream down to its terminal `done`/`error` message. */\nasync function collectAssistantMessage(stream: AsyncIterable<AssistantMessageEvent>): Promise<AssistantMessage> {\n\tlet final: AssistantMessage | undefined;\n\tfor await (const event of stream) {\n\t\tif (event.type === \"done\") {\n\t\t\tfinal = event.message;\n\t\t} else if (event.type === \"error\") {\n\t\t\tfinal = event.error;\n\t\t}\n\t}\n\tif (!final) {\n\t\tthrow new Error(\"createRouterBackedSession: router stream ended without a done/error event\");\n\t}\n\treturn final;\n}\n\n/** Concatenates every `text` content block of an assistant message (ignores thinking/tool-call blocks). */\nfunction messageText(message: AssistantMessage): string {\n\tlet text = \"\";\n\tfor (const block of message.content) {\n\t\tif (block.type === \"text\") text += block.text;\n\t}\n\treturn text;\n}\n\n/** Computes and appends one `CostEntry` for a completed router call, returning its `estimatedCostUsd`. */\nfunction logRouterCall(\n\trole: RlmRole,\n\tmessage: AssistantMessage,\n\ttrajectoryId: string,\n\tsessionId: string,\n\tcostLogPath: string | undefined,\n): number {\n\tconst reasoningTokens = message.usage.reasoning ?? 0;\n\tconst estimatedCostUsd = estimateCost(\n\t\tmessage.provider,\n\t\tmessage.model,\n\t\tmessage.usage.input,\n\t\tmessage.usage.output,\n\t\treasoningTokens,\n\t);\n\tlogCost(\n\t\t{\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t\trole,\n\t\t\tprovider: message.provider,\n\t\t\tmodel: message.model,\n\t\t\tinputTokens: message.usage.input,\n\t\t\toutputTokens: message.usage.output,\n\t\t\t...(reasoningTokens > 0 && { reasoningTokens }),\n\t\t\testimatedCostUsd,\n\t\t\tsessionId,\n\t\t\ttrajectoryId,\n\t\t},\n\t\tcostLogPath,\n\t);\n\treturn estimatedCostUsd;\n}\n\n/** A trajectory step's cost tally, accumulated between one `rootLlm` call and the next. */\ninterface StepCostAccumulator {\n\trootCostUsd: number;\n\tsubCalls: Array<{ costUsd: number; provider: string; model: string }>;\n}\n\n/**\n * Builds a real `@draht/router`-backed `RlmSession`: resolves the \"rlm-root\"\n * model to pick a prompt tier, renders that tier's system prompt with the\n * real prompt's length/chunk info, and wires `rootLlm`/`llmQuery` to call\n * `router.streamSimple(\"rlm-root\" | \"rlm-sub\", ...)`, logging a cost entry\n * (tagged with one `trajectoryId` per session) after every call.\n */\nexport function createRouterBackedSession(opts: CreateRouterBackedSessionOptions): RlmSession {\n\tconst trajectoryId = randomUUID();\n\tconst sessionId = opts.sessionId ?? trajectoryId;\n\tconst contextType = opts.contextType ?? DEFAULT_CONTEXT_TYPE;\n\tconst maxSubCallBudget = opts.maxSubCallBudget ?? DEFAULT_MAX_SUB_CALL_BUDGET;\n\tconst subCallCharBudget = opts.subCallCharBudget ?? DEFAULT_SUB_CALL_CHAR_BUDGET;\n\tconst costLogPath = opts.costLogPath;\n\tconst trajectoryLogDir = opts.trajectoryLogDir;\n\n\t// Trajectory JSONL logging (Phase 30, trajectory.ts): `rootLlm` is called\n\t// once per step, always *before* that step's own `llm_query` sub-calls\n\t// happen (they occur later, inside the driver's `runExec`, which\n\t// `session.ts` only invokes after `rootLlm` resolves -- see session.ts's\n\t// `step()`). So a step's sub-calls always land between one `rootLlm` call\n\t// and the next, and the simplest correct way to correlate them without\n\t// touching session.ts's core loop is: accumulate sub-call costs into\n\t// `pendingStep` as they happen, and finalize+append the *previous* step's\n\t// `TrajectoryStepEntry` the moment the *next* `rootLlm` call (or the final\n\t// `run()` resolution, for the very last step) tells us -- via the\n\t// `history` array it's handed -- that the previous step actually\n\t// completed.\n\tlet pendingStep: StepCostAccumulator | null = null;\n\tlet finalizedThroughStep = 0;\n\tlet totalCostUsd = 0;\n\n\tfunction finalizeStepIfPending(history: RlmHistoryEntry[]): void {\n\t\tif (!pendingStep) return;\n\t\tconst entry = history[history.length - 1];\n\t\t// No new completed entry since the last finalize (e.g. the step that\n\t\t// started this accumulator never finished -- a hard-killed/errored\n\t\t// step never gets pushed to `history`): nothing to log, and don't\n\t\t// double-log the previous step either.\n\t\tif (!entry || entry.step <= finalizedThroughStep) return;\n\t\tconst stepCostUsd = pendingStep.rootCostUsd + pendingStep.subCalls.reduce((sum, sub) => sum + sub.costUsd, 0);\n\t\ttotalCostUsd += stepCostUsd;\n\t\tappendTrajectoryEntry(\n\t\t\ttrajectoryId,\n\t\t\t{\n\t\t\t\ttype: \"step\",\n\t\t\t\ttrajectoryId,\n\t\t\t\tstep: entry.step,\n\t\t\t\tcode: entry.code,\n\t\t\t\ttruncatedStdout: entry.truncatedStdout,\n\t\t\t\terror: entry.error,\n\t\t\t\tsubCalls: pendingStep.subCalls,\n\t\t\t\tcostUsd: stepCostUsd,\n\t\t\t\ttimestamp: entry.timestamp,\n\t\t\t},\n\t\t\ttrajectoryLogDir,\n\t\t);\n\t\tfinalizedThroughStep = entry.step;\n\t\tpendingStep = null;\n\t}\n\n\tconst rootRef = opts.router.resolve(\"rlm-root\");\n\tconst rootModel = opts.router.resolveModel(rootRef);\n\tconst contextWindow = rootModel?.contextWindow ?? FALLBACK_ROOT_CONTEXT_WINDOW;\n\n\tconst tier = selectTier(contextWindow);\n\tconst contextTotalLength = opts.prompt.length;\n\tconst chunkLengths = computeChunkLengths(contextTotalLength, subCallCharBudget);\n\n\tconst vars: PromptVars = {\n\t\tcontextType,\n\t\tcontextTotalLength,\n\t\tchunkLengths,\n\t\tmaxSubCallBudget,\n\t\tsubCallCharBudget,\n\t};\n\tconst systemPrompt = renderPrompt(tier, vars);\n\n\tconst rootLlm = async (history: RlmHistoryEntry[]): Promise<string> => {\n\t\t// `history` reflects every step completed *before* this one -- so if a\n\t\t// previous step's accumulator is still pending, this call is exactly\n\t\t// the signal that it (and only it) has now fully completed (its own\n\t\t// root call plus every sub-call it triggered).\n\t\tfinalizeStepIfPending(history);\n\t\tpendingStep = { rootCostUsd: 0, subCalls: [] };\n\t\tconst context: Context = {\n\t\t\tsystemPrompt,\n\t\t\tmessages: [\n\t\t\t\t{\n\t\t\t\t\trole: \"user\",\n\t\t\t\t\tcontent: buildRootUserTurn(contextTotalLength, contextType, history),\n\t\t\t\t\ttimestamp: Date.now(),\n\t\t\t\t},\n\t\t\t],\n\t\t};\n\t\tconst message = await collectAssistantMessage(opts.router.streamSimple(\"rlm-root\", context));\n\t\tconst costUsd = logRouterCall(\"rlm-root\", message, trajectoryId, sessionId, costLogPath);\n\t\tpendingStep.rootCostUsd = costUsd;\n\t\treturn messageText(message);\n\t};\n\n\tconst llmQuery = async (prompt: string): Promise<string> => {\n\t\tconst context: Context = {\n\t\t\tmessages: [{ role: \"user\", content: prompt, timestamp: Date.now() }],\n\t\t};\n\t\tconst message = await collectAssistantMessage(opts.router.streamSimple(\"rlm-sub\", context));\n\t\tconst costUsd = logRouterCall(\"rlm-sub\", message, trajectoryId, sessionId, costLogPath);\n\t\t// A sub-call always happens after `rootLlm` resolved for the step that\n\t\t// triggered it (and before the next `rootLlm` call) -- see session.ts's\n\t\t// `step()`/`runExec` -- so `pendingStep` is always the right step to\n\t\t// attribute this cost to. `pendingStep` is only ever null before the\n\t\t// very first `rootLlm` call, at which point no `llm_query` could have\n\t\t// been dispatched yet either.\n\t\tpendingStep?.subCalls.push({ costUsd, provider: message.provider, model: message.model });\n\t\treturn messageText(message);\n\t};\n\n\tconst session = new RlmSession({ prompt: opts.prompt, rootLlm, llmQuery });\n\n\t// Wrap (not replace the class's core loop -- session.ts is untouched)\n\t// `run()` so the trajectory's last step and its terminal\n\t// `TrajectoryFinalEntry` get logged once the whole session resolves.\n\t// There's no other hook to observe \"the session is done\" from outside\n\t// session.ts: `rootLlm` is never called again after the last step, so\n\t// nothing else would ever finalize that step's accumulator.\n\tconst originalRun = session.run.bind(session);\n\tsession.run = async () => {\n\t\tconst result = await originalRun();\n\t\tfinalizeStepIfPending(result.history);\n\t\tappendTrajectoryEntry(\n\t\t\ttrajectoryId,\n\t\t\t{\n\t\t\t\ttype: \"final\",\n\t\t\t\ttrajectoryId,\n\t\t\t\tkind: result.kind,\n\t\t\t\tvalue: result.value,\n\t\t\t\ttotalCostUsd,\n\t\t\t\ttotalSteps: result.steps,\n\t\t\t\ttimestamp: new Date().toISOString(),\n\t\t\t},\n\t\t\ttrajectoryLogDir,\n\t\t);\n\t\treturn result;\n\t};\n\n\treturn session;\n}\n"]}

package/dist/sandbox.d.ts

@@ -0,0 +1,95 @@
+/**
+ * OS-level sandbox spawn wrapper for the RLM Python REPL driver.
+ *
+ * This is the REAL security boundary described in
+ * .planning/phases/28-repl-sandbox-safety/28-01-PLAN.md ("IMPORTANT" section
+ * and Architecture section 1) -- NOT `repl_driver.py`'s Python-level
+ * builtins/import allowlist (that's defense-in-depth for a
+ * confused/prompt-injected LLM, not something that stops a deliberately
+ * adversarial payload; the Python object graph makes in-process
+ * confinement of arbitrary Python fundamentally unachievable -- see the
+ * plan for the `__subclasses__`/`gi_frame.f_builtins` escapes that defeat
+ * any purely in-process approach).
+ *
+ * **macOS**: wraps the interpreter with `sandbox-exec -f macos.sb ...`. The
+ * SBPL profile (`../sandbox/macos.sb`) denies network and process-exec
+ * entirely (which alone defeats `os.system`/`subprocess` -- they fork+exec
+ * a shell -- independent of any Python-level import block) and scopes file
+ * access to exactly the Python installation needed to boot plus the
+ * session's workdir. Machine-specific paths (where python3 actually lives)
+ * are discovered here at spawn time via a real subprocess call, never
+ * hardcoded/guessed -- see `resolvePythonInstallation`.
+ *
+ * **Linux**: wraps with `unshare --user --map-root-user --net --mount --`
+ * (empty net namespace = network unreachable at the kernel; mount
+ * namespace for FS confinement), falling back to `bwrap` with equivalent
+ * flags if `unshare` isn't available. Availability is detected at spawn
+ * time, never assumed.
+ *
+ * **Fail closed everywhere**: if the sandboxing mechanism for the current
+ * platform can't be established (wrapper binary missing, profile missing,
+ * Python installation can't be discovered, unsupported platform), every
+ * function here throws `SandboxUnavailableError` synchronously rather than
+ * returning a command that would run the driver unwrapped. There is no
+ * fallback path to an unsandboxed spawn anywhere in this module.
+ */
+import { type ChildProcess } from "node:child_process";
+/**
+ * Thrown whenever the OS-level sandbox can't be established for the current
+ * platform/environment. Callers (see `session.ts`) must let this propagate
+ * and refuse to run rather than catching it and falling back to an
+ * unwrapped spawn -- that fallback is exactly the failure mode Architecture
+ * section 1's "fail closed" requirement exists to prevent.
+ */
+export declare class SandboxUnavailableError extends Error {
+    constructor(message: string);
+}
+export interface SandboxSpawnOptions {
+    /** Absolute path to `repl_driver.py`. */
+    driverPath: string;
+    /**
+     * Absolute path to the session's scratch workdir. The only place the
+     * sandboxed process may read *and* write freely (besides the read-only
+     * Python installation itself).
+     */
+    workdir: string;
+    /**
+     * Which `python3` to sandbox. Defaults to whatever `python3` resolves to
+     * on `PATH`. Overridable mainly so tests can point at a specific
+     * interpreter without mutating `PATH`.
+     */
+    pythonBin?: string;
+    /**
+     * Override for the macOS `sandbox-exec` binary path. Mainly a test
+     * injection point for proving fail-closed behavior (point it at a
+     * nonexistent path and assert setup refuses rather than falling back to
+     * an unwrapped spawn) -- see Architecture section 1's fail-closed
+     * requirement and this plan's task 1 test 7.
+     */
+    sandboxExecBin?: string;
+    /** Override for the Linux `unshare` binary path. Mainly for tests. */
+    unshareBin?: string;
+    /** Override for the Linux `bwrap` binary path (used if `unshare` is unavailable). Mainly for tests. */
+    bwrapBin?: string;
+}
+/** The concrete command + args a `child_process.spawn` call should use. */
+export interface SandboxedCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * Computes the sandboxed command/args for the current platform without
+ * spawning anything. Exposed separately from `spawnSandboxed` so tests can
+ * assert on the resolved invocation and so fail-closed behavior (throwing
+ * `SandboxUnavailableError`) is observable synchronously, before any
+ * process exists.
+ */
+export declare function resolveSandboxedCommand(opts: SandboxSpawnOptions): SandboxedCommand;
+/**
+ * Spawns `repl_driver.py` wrapped in the platform's OS-level sandbox.
+ * Throws `SandboxUnavailableError` synchronously (before any process is
+ * created) if the sandbox can't be established -- there is no unwrapped
+ * fallback path.
+ */
+export declare function spawnSandboxed(opts: SandboxSpawnOptions): ChildProcess;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAuB,MAAM,oBAAoB,CAAC;AAS5E;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,YAAY,OAAO,EAAE,MAAM,EAG1B;CACD;AAED,MAAM,WAAW,mBAAmB;IACnC,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AA8MD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB,CAMnF;AA2CD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAGtE"}