humanish 0.104.3 → 0.106.0

package/dist/routes/terminal/recorder.d.ts

@@ -0,0 +1,23 @@
+import { type CommandLogRecord, type InterventionRecord, type LifecycleRecord, type TerminalEventRecord } from "./types.js";
+/**
+ * The terminal run's ledgers and capture buffers, mutated through the live lifecycle. Every chunk
+ * is scrubbed and redacted as it is stored; raw bytes never leave the append functions.
+ */
+export declare function createTerminalRecorder(args: {
+    nowIso: () => string;
+    sanitize: (text: string) => string;
+    knownSecretValues: readonly string[];
+}): {
+    lifecycle: LifecycleRecord[];
+    commandLog: CommandLogRecord[];
+    terminalEvents: TerminalEventRecord[];
+    interventions: InterventionRecord[];
+    discardedPrefixes: {
+        stdout: string;
+        stderr: string;
+        combined: string;
+    };
+    recordLifecycle: (event: string, message: string) => void;
+    recordStreamedTerminalChunk: (stream: "stdout" | "stderr", raw: string) => void;
+    appendReturnedTerminalOutput: (stream: "stdout" | "stderr", raw: string) => void;
+};

package/dist/routes/terminal/recorder.js

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { MAX_TRANSCRIPT_BYTES, } from "./types.js";
+/**
+ * The terminal run's ledgers and capture buffers, mutated through the live lifecycle. Every chunk
+ * is scrubbed and redacted as it is stored; raw bytes never leave the append functions.
+ */
+export function createTerminalRecorder(args) {
+    const { nowIso, sanitize, knownSecretValues } = args;
+    const lifecycle = [];
+    const commandLog = [];
+    const terminalEvents = [];
+    // Capture may stop inside a known key. Keep only enough following characters to finish the
+    // cross-chunk redaction below; this overlap is never added to terminal events/artifacts.
+    const discardedPrefixes = { stdout: "", stderr: "", combined: "" };
+    const maxDiscardedPrefixChars = Math.max(0, ...knownSecretValues.map((value) => value.length - 1));
+    const interventions = []; // ALWAYS empty while no assisted-input path ships.
+    let transcriptBytes = 0;
+    const recordLifecycle = (event, message) => {
+        lifecycle.push({ at: nowIso(), event, message: sanitize(message) });
+    };
+    const appendTerminalChunk = (stream, raw) => {
+        if (transcriptBytes >= MAX_TRANSCRIPT_BYTES) {
+            for (const order of [stream, "combined"]) {
+                const remaining = maxDiscardedPrefixChars - discardedPrefixes[order].length;
+                if (remaining > 0)
+                    discardedPrefixes[order] += raw.slice(0, remaining);
+            }
+            return;
+        }
+        transcriptBytes += Buffer.byteLength(raw, "utf8");
+        // Scrub THEN redact at the SOURCE — raw bytes never leave this function (safety contract item 5).
+        terminalEvents.push({ at: nowIso(), stream, chunk: sanitize(raw) });
+    };
+    // E2B can stream every byte through callbacks AND return the same complete output (#667).
+    // Track transport delivery, independently per stream, rather than deduplicating participant
+    // lines or equal usage records. Hash raw callback bytes before redaction/truncation so the
+    // comparison cannot confuse two values that redact identically or lose capped-away delivery.
+    // Delivery tracking retains only counts and hashes; payloads still pass the artifact sanitizer.
+    const streamedOutput = {
+        stdout: { bytes: 0, hash: createHash("sha256") },
+        stderr: { bytes: 0, hash: createHash("sha256") },
+    };
+    const recordStreamedTerminalChunk = (stream, raw) => {
+        streamedOutput[stream].bytes += Buffer.byteLength(raw, "utf8");
+        streamedOutput[stream].hash.update(raw, "utf8");
+        appendTerminalChunk(stream, raw);
+    };
+    const appendReturnedTerminalOutput = (stream, raw) => {
+        const delivered = streamedOutput[stream];
+        const returned = Buffer.from(raw, "utf8");
+        if (delivered.bytes > 0 && returned.length >= delivered.bytes) {
+            const returnedPrefixHash = createHash("sha256")
+                .update(returned.subarray(0, delivered.bytes))
+                .digest("hex");
+            if (returnedPrefixHash === delivered.hash.copy().digest("hex")) {
+                // A complete replay adds nothing; a partly streamed prefix keeps only the unseen tail.
+                const suffix = returned.subarray(delivered.bytes).toString("utf8");
+                if (suffix)
+                    appendTerminalChunk(stream, suffix);
+                return;
+            }
+        }
+        // Older/final-only SDK delivery, or output that does not match the streamed prefix: keep it.
+        // Guessing at overlap here could erase legitimate repeated participant text.
+        appendTerminalChunk(stream, raw);
+    };
+    return {
+        lifecycle,
+        commandLog,
+        terminalEvents,
+        interventions,
+        discardedPrefixes,
+        recordLifecycle,
+        recordStreamedTerminalChunk,
+        appendReturnedTerminalOutput,
+    };
+}

package/dist/routes/terminal/result.d.ts

@@ -0,0 +1,47 @@
+import type { ObserverResult } from "../../observer/render.js";
+import type { ActorCompletionReason, ActorStatus, ActorTrace } from "../../actors/contract.js";
+import { type ExecutionFailure, type ExecutionOutcome, type Judgment, type ParticipantFacts } from "../../run/judge.js";
+import { type NoSpendProof, type TerminalCostLedger, type TerminalLedgers, type TerminalProductLabResult } from "./types.js";
+/**
+ * What judge.ts reads from a finished terminal session, after a blown cap has overridden it. It has
+ * no engagement or blocker rule: the agent's nonce-verified marker is its declared outcome.
+ */
+export declare function terminalParticipantFacts(trace: ActorTrace, sessionError: string | undefined): ParticipantFacts;
+/**
+ * The live run's execution failures: a harness error, a blown spend cap, an unproven sandbox
+ * teardown, and an Observer that failed.
+ */
+export declare function terminalExecutionFailures(args: {
+    participant: ParticipantFacts;
+    /** The cap check's message when known spend or jobs exceeded the caps. */
+    capFailure: string | undefined;
+    /** Already scrubbed and redacted. */
+    sessionReason: string;
+    cleanup: TerminalLedgers["cleanup"];
+    observer: Pick<ObserverResult, "ok" | "error">;
+}): ExecutionFailure[];
+/** The terminal-product lab result for a live run, from its session, cleanup and cost ledger. */
+export declare function terminalLabResult(args: {
+    cwd: string;
+    labId: string;
+    actorId: string;
+    productName: string;
+    runId: string;
+    sessionStatus: ActorStatus;
+    completionReason: ActorCompletionReason;
+    /** Already scrubbed and redacted. */
+    sessionReason: string;
+    sessionError: string | undefined;
+    sandboxId: string | undefined;
+    cleanup: TerminalLedgers["cleanup"];
+    cost: TerminalCostLedger;
+    noSpendProof: NoSpendProof;
+    /** The cap check's message when known spend or jobs exceeded the caps. */
+    capFailure: string | undefined;
+    declaredScorerFailure: string | undefined;
+    /** The run's judgment. On this evidence route ok does not read whether the agent passed. */
+    judgment: Judgment;
+    execution: ExecutionOutcome;
+    observer: ObserverResult;
+    warnings: string[];
+}): TerminalProductLabResult;

package/dist/routes/terminal/result.js

@@ -0,0 +1,114 @@
+import { OUTCOME_POLICIES, participantHarnessFailed, resultOk, } from "../../run/judge.js";
+import { TERMINAL_PRODUCT_LAB_SCHEMA, } from "./types.js";
+/**
+ * What judge.ts reads from a finished terminal session, after a blown cap has overridden it. It has
+ * no engagement or blocker rule: the agent's nonce-verified marker is its declared outcome.
+ */
+export function terminalParticipantFacts(trace, sessionError) {
+    return {
+        status: trace.status,
+        completionReason: trace.completionReason,
+        ...(sessionError === undefined ? {} : { sessionError }),
+        skipped: false,
+        noEngagement: false,
+        selfReportedBlocker: false,
+    };
+}
+/**
+ * The live run's execution failures: a harness error, a blown spend cap, an unproven sandbox
+ * teardown, and an Observer that failed.
+ */
+export function terminalExecutionFailures(args) {
+    const { participant, cleanup, observer } = args;
+    return [
+        ...(participantHarnessFailed(participant)
+            ? [{ kind: "harness", message: participant.sessionError ?? args.sessionReason }]
+            : []),
+        ...(args.capFailure === undefined ? [] : [{ kind: "cap", message: args.capFailure }]),
+        ...(cleanup.killed && cleanup.remaining === 0
+            ? []
+            : [
+                {
+                    kind: "sandbox-cleanup",
+                    message: `Sandbox teardown unproven (killed=${cleanup.killed}, remaining=${cleanup.remaining}): ${cleanup.reason}`,
+                },
+            ]),
+        ...(observer.ok
+            ? []
+            : [
+                {
+                    kind: "evidence",
+                    message: observer.error?.message ?? "Observer failed for the terminal-product lab run.",
+                },
+            ]),
+    ];
+}
+/** The terminal-product lab result for a live run, from its session, cleanup and cost ledger. */
+export function terminalLabResult(args) {
+    const { cwd, labId, actorId, productName, runId, sessionStatus, completionReason, sessionReason, sessionError, sandboxId, cleanup, cost, noSpendProof, capFailure, declaredScorerFailure, judgment, execution, observer, warnings, } = args;
+    // The lab's exit code: verified evidence AND no harness error AND proven cleanup. A blocked/
+    // timed-out agent run is STILL ok-as-evidence at the bundle level (the failure is the evidence),
+    // but the LAB result surfaces ok:false on a harness error or unproven teardown (fail-closed).
+    // remaining===0 is the by-id-confirmed-reclaimed state; remaining===1 (still present) and
+    // remaining===-1 (kill(id) itself failed) are both unproven by design.
+    const cleanupProven = cleanup.killed && cleanup.remaining === 0;
+    // A CONFIG-DECLARED scorer that failed to render a pass (status:"fail" / malformed / throw) fails the
+    // run RESULT too, not just the persisted verdict — the keystone lane's declared rubric is a gate, so
+    // its fail must drive exit code. Library callers never set this (additive, back-compat).
+    const ok = resultOk({
+        judgment,
+        execution,
+        scorerFailures: declaredScorerFailure === undefined ? [] : [declaredScorerFailure],
+        policy: OUTCOME_POLICIES.terminal,
+    });
+    return {
+        schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+        ok,
+        cwd,
+        labId,
+        actor: actorId,
+        product: productName,
+        dryRun: false,
+        runId,
+        session: { status: sessionStatus, completionReason, reason: sessionReason },
+        ...(sandboxId
+            ? { sandbox: { sandboxId, killed: cleanup.killed, remaining: cleanup.remaining } }
+            : {}),
+        cost: {
+            knownTotalUsd: cost.knownTotalUsd,
+            fullyMeasured: cost.fullyMeasured,
+            lines: {
+                product: cost.lines.product.usd,
+                media: cost.lines.media.usd,
+                payment: cost.lines.payment.usd,
+                provider: cost.lines.provider.usd,
+            },
+        },
+        noSpend: {
+            satisfied: noSpendProof.satisfied,
+            maxUsd: noSpendProof.maxUsd,
+            knownZeroLines: noSpendProof.knownZeroLines,
+            unmeasuredLines: noSpendProof.unmeasuredLines,
+        },
+        observer,
+        warnings: [...warnings, ...observer.warnings],
+        ...(ok
+            ? {}
+            : {
+                error: {
+                    code: (!cleanupProven
+                        ? "HUMANISH_TERMINAL_LAB_CLEANUP_UNPROVEN"
+                        : capFailure !== undefined
+                            ? "HUMANISH_TERMINAL_LAB_CAPS_EXCEEDED"
+                            : "HUMANISH_TERMINAL_LAB_FAILED"),
+                    message: !cleanupProven
+                        ? `Live terminal-product run could not prove sandbox teardown (killed=${cleanup.killed}, remaining=${cleanup.remaining}): ${cleanup.reason}. A run that cannot prove teardown fails closed.${sessionError !== undefined ? ` Session failure: ${sessionError}` : ""}`
+                        : (declaredScorerFailure ??
+                            capFailure ??
+                            sessionError ??
+                            observer.error?.message ??
+                            sessionReason),
+                },
+            }),
+    };
+}

package/dist/routes/terminal/route.d.ts

@@ -0,0 +1,23 @@
+import { type TerminalRefusal } from "./plan.js";
+import type { TerminalPlan } from "../../lab/plan-types.js";
+import type { AdmittedPlan } from "../../run-lab.js";
+import { type RunTerminalProductLabOptions, type TerminalProductLabResult, type TerminalRunInput } from "./types.js";
+/**
+ * The config-taking entry point. It plans, returns a refusal with the same envelope and analysis
+ * record the route has always returned, and otherwise runs the plan.
+ */
+export declare function runTerminalProductLab(options: RunTerminalProductLabOptions): Promise<TerminalProductLabResult>;
+/** A refused terminal lab's result: the route's envelope, and the analysis record a refusal gets. */
+export declare function terminalLabRefusal(options: RunTerminalProductLabOptions, refusal: TerminalRefusal): Promise<TerminalProductLabResult>;
+/**
+ * Run a terminal plan. The run scope gives a direct library caller the same run lifetime the CLI
+ * gets: whichever of its fail-closed exits the lab takes, the run it started is closed, and only a
+ * run that published its final bundle reaches automatic analysis.
+ */
+export declare function runTerminalPlan(plan: TerminalPlan, input: TerminalRunInput): Promise<TerminalProductLabResult>;
+/**
+ * runLab's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
+ * before any run scope opens, so the CLI can present their refusal before it loads a declared
+ * scorer, and returns the run that continues from them with that scorer.
+ */
+export declare function admitTerminalPlan(plan: TerminalPlan, input: TerminalRunInput): Promise<AdmittedPlan<"terminal">>;

package/dist/routes/terminal/route.js

@@ -0,0 +1,170 @@
+// The terminal-product route: a real autonomous agent (Codex) studies a CLI or product from its
+// public surfaces only, inside an E2B shell. The flow:
+//   1. admit: planTerminalLab refuses what the plan cannot hold, then a live plan's machine checks
+//      (checkLiveTerminalMachine) run before any run scope opens, so the CLI can refuse before it
+//      loads a declared scorer;
+//   2. open the run scope;
+//   3. a live plan runs its session in an E2B sandbox (runLiveTerminalSession, session.ts, with
+//      live-sandbox.ts and live-finish.ts); a dry plan publishes its contract bundle (dry-run.ts);
+//   4. automatic analysis of a run that published its final bundle.
+//
+// THE SAFETY CONTRACT (docs/goals/terminal-product-lane/goal.md) is enforced BY CONSTRUCTION in
+// the files each item names, and CHECKED by the verifier (verify/actor.ts
+// validateTerminalProductEvidence):
+//   1. EXPLICIT KEY PLACEMENT. openai-env (default) injects the raw runtime key command-scoped,
+//      NEVER Sandbox.create({envs}). Opt-in openai-egress sends it only in the host-side E2B
+//      header transform and passes an inert command placeholder. The proxy is spendable by every
+//      sandbox process from creation; this protects the raw key, not provider spending.
+//      Enforced in credentials.ts and runtime-auth.ts.
+//   2. FAIL-CLOSED CAP. The live key is never exercised without scenario.caps in force: maxUsd
+//      (default/require 0 = no-spend) + maxMinutes (wall-clock kill of the codex command).
+//      Enforced in plan.ts (caps required), live-sandbox.ts and lifetime.ts (the wall clock).
+//   3. PUBLIC SURFACES ONLY. The mission references only subject.product.publicSurfaces + the
+//      author mission. No clone, no private-source access — nothing is git-cloned in this lane.
+//      Enforced in session.ts, which composes the prompt.
+//   4. DENY-BY-DEFAULT CREDENTIALS. The command envs are built from an ALLOWLIST of ONLY the
+//      declared runtime key; GITHUB_TOKEN/GH_TOKEN/payment/deploy/db/media keys are excluded by
+//      construction (a banned-name guard also fails closed if one is ever requested).
+//      Enforced in credentials.ts.
+//   5. NO SECRET VALUES IN EVIDENCE. Every captured byte (event stream, transcript, command logs,
+//      agent report, metadata) passes scrubKnownValues (literal scrub of the runtime key + any
+//      provisioned values, >=4 chars, PRE-truncation) THEN redactText (shape patterns) BEFORE
+//      persisting. The transport is labeled HONESTLY (exec-stream/snapshot, NOT an interactive pty).
+//      Enforced in recorder.ts, with the scrubber session.ts builds.
+//   6. METADATA POSITIVE ALLOWLIST. buildSandboxMetadata(allowlist) is the ONLY way metadata is
+//      set; it carries solely non-secret labels (mode/tool/labId/simId/provider/runId).
+//      Enforced in credentials.ts.
+//   7. STDIN DISABLED + INTERVENTIONS LEDGER. stdin is never wired to the codex command; the
+//      bundle ALWAYS carries an interventions ledger (empty array is valid + required-present).
+//      Enforced in live-sandbox.ts (stdin) and recorder.ts (the ledger).
+//   8. PROVEN CLEANUP, BY ID, NEVER ACCOUNT-WIDE. Sandbox.kill(id) in a finally; the cleanup
+//      proof is BY EXACT ID: kill(id)'s own found-and-killed boolean, confirmed further by
+//      Sandbox.getInfo(id) when the SDK exposes it (a thrown SandboxNotFoundError means gone).
+//      humanish NEVER calls Sandbox.list to prove cleanup, so a shared operator key never reaches a
+//      sandbox it did not create. A live run that cannot prove teardown fails closed.
+//      Enforced in sandbox.ts.
+import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
+import path from "node:path";
+import { runScope } from "../../run/run.js";
+import { planTerminalLab } from "./plan.js";
+import { runDryTerminalLab } from "./dry-run.js";
+import { checkLiveTerminalMachine, runLiveTerminalSession } from "./session.js";
+import { terminalInputWithScorer } from "../../lab/route-inputs.js";
+import { TERMINAL_PRODUCT_LAB_SCHEMA, } from "./types.js";
+/**
+ * The config-taking entry point. It plans, returns a refusal with the same envelope and analysis
+ * record the route has always returned, and otherwise runs the plan.
+ */
+export async function runTerminalProductLab(options) {
+    const { config, dryRun, lab, ...input } = options;
+    const planned = planTerminalLab(config, {
+        dryRun,
+        ...(lab === undefined ? {} : { lab }),
+        ...(input.hooks === undefined ? {} : { hooks: input.hooks }),
+    });
+    if (planned.ok)
+        return runTerminalPlan(planned.plan, input);
+    return terminalLabRefusal(options, planned.refusal);
+}
+/** A refused terminal lab's result: the route's envelope, and the analysis record a refusal gets. */
+export function terminalLabRefusal(options, refusal) {
+    const { config, dryRun } = options;
+    const refused = {
+        schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+        ok: false,
+        cwd: path.resolve(options.cwd),
+        labId: config.id,
+        actor: refusal.actor ?? config.actors[0]?.type ?? "",
+        product: config.subject.product?.name ?? "",
+        dryRun,
+        runId: options.runId ?? "not-created",
+        warnings: [],
+        error: { code: refusal.code, message: refusal.message },
+    };
+    // A refusal starts no run, so a declared or default analysis is recorded as skipped.
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, options.automaticAnalysis, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+}
+/**
+ * Run a terminal plan. The run scope gives a direct library caller the same run lifetime the CLI
+ * gets: whichever of its fail-closed exits the lab takes, the run it started is closed, and only a
+ * run that published its final bundle reaches automatic analysis.
+ */
+export async function runTerminalPlan(plan, input) {
+    const admission = await admitTerminalRun(plan, input);
+    return admission.ok ? runAdmittedTerminalRun(admission.admitted, input) : admission.result;
+}
+/**
+ * runLab's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
+ * before any run scope opens, so the CLI can present their refusal before it loads a declared
+ * scorer, and returns the run that continues from them with that scorer.
+ */
+export async function admitTerminalPlan(plan, input) {
+    const admission = await admitTerminalRun(plan, input);
+    if (!admission.ok)
+        return { ok: false, outcome: terminalOutcome(admission.result) };
+    return {
+        ok: true,
+        run: async (scorer) => terminalOutcome(await runAdmittedTerminalRun(admission.admitted, terminalInputWithScorer(input, scorer))),
+    };
+}
+function terminalOutcome(result) {
+    return { route: "terminal", backend: "terminal", result };
+}
+/**
+ * A live plan's local checks, made outside any run scope. A refusal is the result runTerminalPlan
+ * returns for it, with the analysis record of a run that never started.
+ */
+async function admitTerminalRun(plan, input) {
+    const warnings = [];
+    if (plan.dryRun)
+        return { ok: true, admitted: { plan, warnings } };
+    const checked = checkLiveTerminalMachine(plan, input, warnings);
+    if (checked.ok)
+        return { ok: true, admitted: { plan, warnings, runtimeEnv: checked.runtimeEnv } };
+    const refused = terminalFailure(plan, input, warnings)(checked.code, checked.message);
+    return { ok: false, result: await completeTerminalAnalysis(plan, input, refused, undefined) };
+}
+/** Runs an admitted plan in its own run scope, then its automatic analysis. */
+async function runAdmittedTerminalRun(admitted, input) {
+    const { result, finished } = await runScope((scope) => runTerminalPlanInScope(admitted, input, scope));
+    return completeTerminalAnalysis(admitted.plan, input, result, finished);
+}
+function completeTerminalAnalysis(plan, input, result, finished) {
+    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input.automaticAnalysis, {
+        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
+        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
+    });
+}
+/** The route's envelope for a run that stops before its bundle. */
+function terminalFailure(plan, input, warnings) {
+    const cwd = path.resolve(input.cwd);
+    return (code, message) => ({
+        schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+        ok: false,
+        cwd,
+        labId: plan.labId,
+        actor: plan.actor,
+        product: plan.product.name,
+        dryRun: plan.dryRun,
+        runId: input.runId ?? "not-created",
+        warnings,
+        error: { code, message },
+    });
+}
+async function runTerminalPlanInScope(admitted, input, scope) {
+    const cwd = path.resolve(input.cwd);
+    const { warnings } = admitted;
+    const failed = terminalFailure(admitted.plan, input, warnings);
+    // LIVE path: the real in-sandbox agent session. A separate orchestrator owns the
+    // create -> inject (command-scoped) -> run -> capture -> teardown lifecycle so the dry-run path
+    // below stays a pure contract builder. It enforces the safety contract by construction (the
+    // keyPlacement-routed command-scoped key, the deny-by-default allowlist, the fail-closed cap,
+    // the proven cleanup) and fails closed before any sandbox/key/spend on any precondition miss.
+    if ("runtimeEnv" in admitted) {
+        const { plan, runtimeEnv } = admitted;
+        return runLiveTerminalSession({ plan, input, cwd, warnings, failed, scope, runtimeEnv });
+    }
+    return runDryTerminalLab({ plan: admitted.plan, input, cwd, warnings, failed, scope });
+}

package/dist/routes/terminal/runtime-auth.d.ts

@@ -0,0 +1,12 @@
+import type { E2BNetworkOptions } from "../../substrates/e2b/sdk.js";
+/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
+export declare const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
+/** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */
+export declare const OPENAI_EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
+/**
+ * Keep the runtime key in the host-side E2B request, outside sandbox env/files. The installed
+ * E2B SDK declares that transform headers override existing request headers. This adds no routing
+ * restrictions: every sandbox process can still spend via the provider proxy. Never log the
+ * returned options. An adopter's existing exact-host rule must not be silently overwritten.
+ */
+export declare function buildOpenAiEgressNetwork(keyValue: string, existing?: E2BNetworkOptions): E2BNetworkOptions;

package/dist/routes/terminal/runtime-auth.js

@@ -0,0 +1,23 @@
+const OPENAI_EGRESS_HOST = "api.openai.com";
+/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
+export const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
+/** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */
+export const OPENAI_EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
+/**
+ * Keep the runtime key in the host-side E2B request, outside sandbox env/files. The installed
+ * E2B SDK declares that transform headers override existing request headers. This adds no routing
+ * restrictions: every sandbox process can still spend via the provider proxy. Never log the
+ * returned options. An adopter's existing exact-host rule must not be silently overwritten.
+ */
+export function buildOpenAiEgressNetwork(keyValue, existing) {
+    if (Object.keys(existing?.rules ?? {}).some((host) => host.toLowerCase().replace(/\.$/, "") === OPENAI_EGRESS_HOST)) {
+        throw new Error("openai-egress conflicts with an existing api.openai.com network rule; refusing to overwrite it.");
+    }
+    return {
+        ...existing,
+        rules: {
+            ...existing?.rules,
+            [OPENAI_EGRESS_HOST]: [{ transform: { headers: { Authorization: `Bearer ${keyValue}` } } }],
+        },
+    };
+}

package/dist/routes/terminal/runtime.d.ts

@@ -0,0 +1,14 @@
+import type { ActorRuntimeProvenance } from "../../actors/contract.js";
+import type { ReasoningEffort } from "../../actors/reasoning-effort.js";
+export declare const TERMINAL_RUNTIME_VERSION_TIMEOUT_MS = 60000;
+/** Exact semver only: no registry tags, ranges, URLs, or shell syntax. */
+export declare function isExactRuntimeVersion(value: unknown): value is string;
+/** Captured Codex CLI output: `codex-cli 0.153.3\n`. Other shapes fail closed. */
+export declare function parseTerminalRuntimeVersion(stdout: string): string | undefined;
+export declare function buildRuntimeVersionCommand(requestedVersion?: string): string;
+export declare function buildRuntimeExecPrefix(version: string, model?: string, reasoningEffort?: ReasoningEffort): string;
+export declare function declaredRuntimeProvenance(args: {
+    version?: string;
+    model?: string;
+    reasoningEffort?: ReasoningEffort;
+}): ActorRuntimeProvenance;

package/dist/routes/terminal/runtime.js

@@ -0,0 +1,47 @@
+import { shellQuote } from "../../substrates/shell.js";
+const TERMINAL_RUNTIME_PACKAGE = "@openai/codex";
+export const TERMINAL_RUNTIME_VERSION_TIMEOUT_MS = 60_000;
+/** Exact semver only: no registry tags, ranges, URLs, or shell syntax. */
+export function isExactRuntimeVersion(value) {
+    if (typeof value !== "string" || value.length > 120)
+        return false;
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(value);
+    return (match !== null &&
+        (match[4]
+            ?.split(".")
+            .every((part) => !/^\d+$/.test(part) || part === "0" || !part.startsWith("0")) ??
+            true));
+}
+/** Captured Codex CLI output: `codex-cli 0.153.3\n`. Other shapes fail closed. */
+export function parseTerminalRuntimeVersion(stdout) {
+    const match = /^codex-cli ([^\s]+)$/.exec(stdout.trim());
+    return match && isExactRuntimeVersion(match[1]) ? match[1] : undefined;
+}
+export function buildRuntimeVersionCommand(requestedVersion) {
+    if (requestedVersion !== undefined && !isExactRuntimeVersion(requestedVersion))
+        throw new Error("Invalid exact Codex runtime version.");
+    return `npm_config_update_notifier=false npx -y ${TERMINAL_RUNTIME_PACKAGE}@${requestedVersion ?? "latest"} --version`;
+}
+export function buildRuntimeExecPrefix(version, model, reasoningEffort) {
+    if (!isExactRuntimeVersion(version))
+        throw new Error("Codex execution requires a verified exact runtime version.");
+    return (`npm_config_update_notifier=false npx -y ${TERMINAL_RUNTIME_PACKAGE}@${version} exec` +
+        (model === undefined ? "" : ` --model ${shellQuote(model)}`) +
+        (reasoningEffort === undefined
+            ? ""
+            : ` -c ${shellQuote(`model_reasoning_effort=${JSON.stringify(reasoningEffort)}`)}`));
+}
+export function declaredRuntimeProvenance(args) {
+    return {
+        schema: "humanish.actor-runtime.v1",
+        package: TERMINAL_RUNTIME_PACKAGE,
+        requestedVersion: args.version ?? "latest",
+        versionStatus: "unobserved",
+        ...(args.model === undefined ? {} : { requestedModel: args.model }),
+        modelStatus: args.model === undefined ? "runtime_default_unobserved" : "declared",
+        ...(args.reasoningEffort === undefined
+            ? {}
+            : { requestedReasoningEffort: args.reasoningEffort }),
+        usageGranularity: "runtime_turn",
+    };
+}

package/dist/routes/terminal/sandbox.d.ts

@@ -0,0 +1,35 @@
+import type { OwnedDesktopAllocation } from "../../substrates/desktop-session.js";
+import { E2BDesktopStartupError, type E2BDesktopModule } from "../../substrates/e2b/sdk.js";
+import type { TerminalLedgers } from "./types.js";
+/**
+ * Tear the sandbox down and PROVE it BY EXACT ID -- NEVER Sandbox.list (humanish must never
+ * enumerate the operator's E2B account; see docs/principles/invariants-and-defaults.md). The
+ * allocation's release (src/substrates/e2b/sandbox.ts) kills the exact id and reads the answer the
+ * same way every route does: true is terminated, false or a not-found error is already gone. That
+ * is the PRIMARY proof. Where the SDK exposes Sandbox.getInfo(id), a thrown SandboxNotFoundError is
+ * a second by-id confirmation that the exact sandbox is gone; a returned SandboxInfo with a live
+ * state means teardown is NOT confirmed. Never throws -- teardown failure is recorded, the caller
+ * fails closed on an unproven teardown.
+ */
+export declare function teardownSandbox(args: {
+    /** The allocation from acquisition; its release kills the exact id it captured. */
+    allocation: OwnedDesktopAllocation | undefined;
+    /** For the Sandbox.getInfo(id) re-check only. */
+    sandboxModule: E2BDesktopModule | undefined;
+    startupCleanup?: E2BDesktopStartupError["cleanup"];
+    requestTimeoutMs: number;
+    sanitize: (text: string) => string;
+    recordLifecycle: (event: string, message: string) => void;
+    warnings: string[];
+}): Promise<TerminalLedgers["cleanup"]>;
+/**
+ * Race a commands.run promise against the maxMinutes wall-clock (safety contract item 2). The E2B
+ * commands.run timeoutMs is the primary kill; this injected-clock guard is the belt-and-suspenders
+ * backstop so a mock CLI (which ignores timeoutMs) is still bounded and fails closed in CI.
+ */
+export declare function runWithWallClock<T>(promise: Promise<T>, wallClockMs: number, now: () => number): Promise<{
+    timedOut: false;
+    value: T;
+} | {
+    timedOut: true;
+}>;