@wardby/cli 0.5.3 → 0.7.0

package/dist/native-worker/sandbox-executor.js

@@ -0,0 +1,284 @@
+/**
+ * The Executor for sandbox-mode native runs (docs/native-sandbox.md). Phase 1's
+ * RoutingExecutor sends every run whose snapshot says `sandbox` here.
+ *
+ * - start: creates the run's gateway session (pinning the run and recording
+ *   `native-sandbox` as its backend before any worker exists), launches the
+ *   worker, and returns. Whichever gateway replica serves the worker's
+ *   `finish` makes the terminal write; this executor only watches for a
+ *   worker that exits without one, and for its deadline.
+ * - stop: records the run cancelled, ends the session (every further gateway
+ *   call is refused, so the worker exits at its next one), gives the worker a
+ *   short grace to exit, then kills and removes it (a warm pool worker is
+ *   discarded, never reused), and stops its open delegations.
+ * - recover: answers the reconciler from the worker's container state, and
+ *   never launches one.
+ * - launch: the janitor removes workers whose runs have ended.
+ */
+import { logger } from "../core/logger.js";
+import { failNativeRun, nativeRunIntegrations, RunCancelledError, NATIVE_SANDBOX_BACKEND, } from "../core/runner.js";
+import { nativeRunLabel } from "./docker-isolation.js";
+import { HEARTBEAT_TIMEOUT_MS } from "../core/timing.js";
+import { startSandboxRun } from "./launch.js";
+import { NATIVE_SANDBOX_CAPACITY } from "./kubernetes-launcher.js";
+import { PrismaGatewayLedger } from "./ledger.js";
+const executorLog = logger.child({ module: "native-sandbox-executor" });
+const isUniqueViolation = (err) => typeof err === "object" && err !== null && err.code === "P2002";
+/** A stopped sandbox run's worker exits at its next (refused) gateway call; past this it is killed. */
+export const NATIVE_SANDBOX_STOP_GRACE_MS = 5_000;
+export const NATIVE_SANDBOX_WORKER_EXITED = "native_sandbox_worker_exited";
+export const NATIVE_SANDBOX_DEADLINE = "native_sandbox_deadline_exceeded";
+export class NativeSandboxExecutor {
+    options;
+    ledger;
+    watching = new Map();
+    deadlineKilled = new Set();
+    constructor(options) {
+        this.options = options;
+        this.ledger = new PrismaGatewayLedger(options.db);
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    finishContext(runId) {
+        const { db, providers } = this.options;
+        return { runId, db, providers, ...nativeRunIntegrations(providers, db) };
+    }
+    async start(runId) {
+        const { db, providers, launcher, gatewayUrl } = this.options;
+        // A second start (a retried dispatch) attaches to the run's worker; it never launches another.
+        const existing = await db.nativeGatewaySession.findUnique({ where: { runId }, select: { deadlineAt: true } });
+        if (existing) {
+            this.watch(runId, launcher.handle(runId), existing.deadlineAt);
+            return;
+        }
+        // Fail fast rather than queue (a warm pool's job): every replica counts the same sessions, and a
+        // near-simultaneous start that overshoots by one is still bounded by the cluster's ResourceQuota.
+        const cap = this.options.maxConcurrent;
+        if (cap !== undefined && (await db.nativeGatewaySession.count({ where: { status: "active" } })) >= cap) {
+            throw new Error(`${NATIVE_SANDBOX_CAPACITY}: ${cap} sandbox runs are already active (NATIVE_SANDBOX_MAX_CONCURRENT).`);
+        }
+        let outcome;
+        try {
+            const url = launcher.resolveGatewayUrl ? await launcher.resolveGatewayUrl() : gatewayUrl;
+            // A cold launch (a low-power gateway wake, a sandbox node scale-up) can outlast the reconciler's
+            // heartbeat timeout, and the worker has no pod to find yet: beat for it until it exists. The
+            // launch's own timeouts bound this (wake, pod ready, isolation proof), each failing the run.
+            outcome = await this.whileHeartbeating(runId, () => startSandboxRun({
+                runId,
+                providers,
+                db,
+                gatewayUrl: url,
+                launcher,
+                stillWanted: () => this.stillWanted(runId),
+            }));
+        }
+        catch (err) {
+            // A concurrent start won the race for the run's one session: attach to its worker.
+            if (!isUniqueViolation(err)) {
+                // The launch failed after the session was created (e.g. isolation could not be proven):
+                // end the session so nothing can use its capability; the caller fails the run.
+                await this.endSession(runId, "cancelled").catch(() => { });
+                throw err;
+            }
+            const raced = await db.nativeGatewaySession.findUniqueOrThrow({ where: { runId }, select: { deadlineAt: true } });
+            this.watch(runId, launcher.handle(runId), raced.deadlineAt);
+            return;
+        }
+        if (outcome.kind === "ended")
+            return;
+        const session = await db.nativeGatewaySession.findUniqueOrThrow({
+            where: { id: outcome.sessionId },
+            select: { deadlineAt: true },
+        });
+        this.watch(runId, outcome.handle, session.deadlineAt);
+    }
+    /** Refreshes a still-live run's heartbeat while `work` runs. */
+    async whileHeartbeating(runId, work) {
+        const beat = () => this.options.db.run
+            .updateMany({
+            where: { id: runId, status: { in: ["pending", "running"] } },
+            data: { heartbeatAt: new Date(this.now()) },
+        })
+            .catch((err) => executorLog.warn({ err, runId }, "could not refresh a launching run's heartbeat"));
+        // At most one beat in flight: a tick while one is pending is skipped. Overlapping beats could
+        // commit out of order, and only the last one sent would be awaited below.
+        let inFlight;
+        const timer = setInterval(() => {
+            inFlight ??= beat().finally(() => {
+                inFlight = undefined;
+            });
+        }, this.options.heartbeatIntervalMs ?? Math.floor(HEARTBEAT_TIMEOUT_MS / 3));
+        // Never hold the process open for a heartbeat: shutdown should not wait on one.
+        timer.unref?.();
+        try {
+            return await work();
+        }
+        finally {
+            clearInterval(timer);
+            // The beat in flight, if any, lands before the launch returns, never after the worker's own beats.
+            await inFlight;
+        }
+    }
+    /** The run is still live and its session open: a worker launched now would have work to do. */
+    async stillWanted(runId) {
+        const { db } = this.options;
+        const [run, session] = await Promise.all([
+            db.run.findUnique({ where: { id: runId }, select: { status: true } }),
+            db.nativeGatewaySession.findUnique({ where: { runId }, select: { status: true } }),
+        ]);
+        return !!run && (run.status === "pending" || run.status === "running") && session?.status === "active";
+    }
+    /** Watches one worker in this process: its exit, and its deadline. */
+    watch(runId, handle, deadlineAt) {
+        if (this.watching.has(runId))
+            return;
+        const msLeft = deadlineAt.getTime() - this.now();
+        const timer = msLeft > 0
+            ? setTimeout(() => {
+                this.deadlineKilled.add(runId);
+                handle.kill();
+            }, msLeft)
+            : undefined;
+        if (msLeft <= 0) {
+            this.deadlineKilled.add(runId);
+            handle.kill();
+        }
+        this.watching.set(runId, timer);
+        void handle.exited
+            .then((code) => this.onWorkerExit(runId, code))
+            .catch((err) => executorLog.error({ err, runId }, "watching a native sandbox worker failed"));
+    }
+    async onWorkerExit(runId, exitCode) {
+        const timer = this.watching.get(runId);
+        if (timer)
+            clearTimeout(timer);
+        this.watching.delete(runId);
+        const { db } = this.options;
+        const run = await db.run.findUnique({ where: { id: runId }, select: { status: true } });
+        if (run && (run.status === "pending" || run.status === "running")) {
+            // The worker ended without its `finish`: nothing will write a result for it, so this does.
+            const reason = this.deadlineKilled.has(runId)
+                ? `${NATIVE_SANDBOX_DEADLINE}: the sandbox run passed its deadline and its worker was stopped.`
+                : `${NATIVE_SANDBOX_WORKER_EXITED}: the sandbox worker exited (code ${exitCode ?? "unknown"}) without a result.`;
+            await failNativeRun(this.finishContext(runId), new Error(reason));
+        }
+        this.deadlineKilled.delete(runId);
+        await this.endSession(runId, "finished");
+        await this.options.launcher.remove(runId).catch((err) => {
+            executorLog.warn({ err, runId }, "removing a native sandbox worker failed; the janitor will retry");
+        });
+    }
+    async endSession(runId, status) {
+        const session = await this.options.db.nativeGatewaySession.findUnique({ where: { runId }, select: { id: true } });
+        if (session)
+            await this.ledger.endSession(session.id, status);
+        return session?.id;
+    }
+    async stop(runId, reason) {
+        // Recorded first, before the session ends or the worker is killed: either of those makes the
+        // worker exit, and its exit watcher must then find the run already ended (and leave it
+        // cancelled) rather than record the exit as a failure.
+        await failNativeRun(this.finishContext(runId), new RunCancelledError(reason ?? "The run was cancelled."));
+        // The stop reaches the worker through the gateway: with its run cancelled and its session ended,
+        // its next call (a model turn, a tool, its result) is refused and it exits on its own. It gets a
+        // bounded grace for that, then is killed either way.
+        const sessionId = await this.endSession(runId, "cancelled");
+        if (!(await this.awaitWorkerExit(runId))) {
+            executorLog.info({ runId }, "a stopped sandbox run's worker did not exit within its grace; killing it");
+            await this.options.launcher.kill(runId).catch(() => { });
+        }
+        if (sessionId) {
+            // Its delegations' children belong to the server's executor; a child left running would
+            // spend on behalf of a parent that no longer waits for it.
+            for (const child of await this.ledger.openDelegationChildren(sessionId)) {
+                await this.options.providers.executor?.stop(child, "parent run cancelled").catch((err) => {
+                    executorLog.warn({ err, runId, child }, "failed to stop a cancelled sandbox run's child");
+                });
+            }
+        }
+        // Removed, never returned to a warm pool: a claimed pool worker is discarded with its row.
+        await this.options.launcher.remove(runId).catch(() => { });
+    }
+    /** Waits up to stopGraceMs for the run's worker to exit or be gone; false when it still runs. Never throws. */
+    async awaitWorkerExit(runId) {
+        const graceMs = this.options.stopGraceMs ?? NATIVE_SANDBOX_STOP_GRACE_MS;
+        const sleep = this.options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        const until = this.now() + graceMs;
+        for (;;) {
+            const state = await this.options.launcher.inspect(runId).catch(() => undefined);
+            // An unreadable state counts as still running: the kill below is the safe default.
+            if (state && state.state !== "running")
+                return true;
+            const left = until - this.now();
+            if (left <= 0)
+                return false;
+            await sleep(Math.min(250, left));
+        }
+    }
+    async recover(handle) {
+        if (handle.backend !== NATIVE_SANDBOX_BACKEND) {
+            return { state: "lost", reason: `NativeSandboxExecutor cannot recover backend "${handle.backend}".` };
+        }
+        const runId = handle.runId;
+        const { db, launcher } = this.options;
+        const [state, run, session] = await Promise.all([
+            launcher.inspect(runId),
+            db.run.findUnique({ where: { id: runId }, select: { status: true } }),
+            db.nativeGatewaySession.findUnique({ where: { runId }, select: { status: true, deadlineAt: true } }),
+        ]);
+        const runEnded = !run || !(run.status === "pending" || run.status === "running");
+        if (state.state === "running") {
+            if (runEnded) {
+                await launcher.kill(runId).catch(() => { });
+                await launcher.remove(runId).catch(() => { });
+                return { state: "terminal" };
+            }
+            // Re-attach (a restarted server): watch its exit and deadline from here.
+            if (session)
+                this.watch(runId, launcher.handle(runId), session.deadlineAt);
+            return { state: "active" };
+        }
+        if (state.state === "exited") {
+            await this.onWorkerExit(runId, state.exitCode);
+            return { state: "terminal" };
+        }
+        if (runEnded || session?.status === "finished")
+            return { state: "terminal" };
+        return {
+            state: "lost",
+            reason: "native_sandbox_worker_lost: the run's sandbox worker is gone and left no result; it was not relaunched.",
+        };
+    }
+    /** Startup janitor: removes worker containers whose runs have ended or passed their deadline. Starts the warm pool. */
+    async launch() {
+        await this.sweep().catch((err) => executorLog.warn({ err }, "native sandbox janitor failed"));
+        await this.options.launcher
+            .start?.()
+            .catch((err) => executorLog.warn({ err }, "native warm pool failed to start"));
+    }
+    async sweep() {
+        const { db, launcher } = this.options;
+        const workers = await launcher.listWorkers();
+        if (workers.length === 0)
+            return 0;
+        const sessions = await db.nativeGatewaySession.findMany({
+            select: { runId: true, status: true, deadlineAt: true, run: { select: { status: true } } },
+        });
+        // Docker labels carry the full run hash; Kubernetes label values carry its first 40 characters.
+        const labelled = sessions.map((s) => ({ hash: nativeRunLabel(s.runId), session: s }));
+        let removed = 0;
+        for (const worker of workers) {
+            const session = labelled.find((l) => l.hash.startsWith(worker.runHash))?.session;
+            const live = session &&
+                session.status === "active" &&
+                session.deadlineAt.getTime() > this.now() &&
+                (session.run.status === "pending" || session.run.status === "running");
+            if (live)
+                continue;
+            await launcher.removeByWorkerName(worker.name);
+            removed += 1;
+        }
+        return removed;
+    }
+}

package/dist/native-worker/stderr-redaction.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The sandbox worker's stderr is not a redacted channel by itself: a failed worker's stderr tail
+ * reaches the server's log (docker-launcher.ts, kubernetes-launcher.ts; the launcher masks it
+ * again, as the worker is untrusted), and a tool's host calls hand the worker secret
+ * values (`secrets.get`). The worker knows those exact values (raw and JSON-escaped), so it masks
+ * them in everything it writes to stderr — its own failure line and the shared logger's lines —
+ * with the shared redactor's spans (secretSpans: the union of every occurrence, overlapping ones
+ * included, minimum length included). One set per worker process.
+ *
+ * process.stderr writes are buffered (StderrRedactionBuffer), because a value may arrive split
+ * across writes. A string is matched as text, whatever encoding it was written with (its trailing
+ * high surrogate is held for the next write, so a split surrogate pair still matches); a hex or
+ * base64 string and any ArrayBufferView go through one UTF-8 byte decoder; any other chunk type is
+ * refused, never written raw. Emitted text is written as UTF-8. On each write the buffer:
+ * 1. holds back `hold`: the longest suffix of the buffer that is a proper prefix of a remembered
+ *    value, since those characters could still become a value;
+ * 2. picks a cut `c` <= length − hold: after the last "\n" there, or, once the text after that
+ *    exceeds MAX_PENDING_STDERR_CHARS, at length − hold; otherwise it emits nothing yet;
+ * 3. masks spans over the whole buffer, with its first `maskedLead` characters forced into a span;
+ * 4. when `c` falls inside a span [s, e), emits [s, c) as the marker and carries `maskedLead` =
+ *    e − c, so the rest of that span is masked when it is emitted later;
+ * 5. emits the masked text before `c` and keeps the rest.
+ * Masking is safe at any cut, so no cut is ever searched for. On exit, SIGTERM/SIGINT and the
+ * worker's fail path the remainder is emitted with its spans, `maskedLead` and the held suffix all
+ * masked: fail closed, a possible value start is emitted as `[REDACTED]`, never raw.
+ *
+ * Why no value character is emitted: an occurrence that begins before `c` either ends within the
+ * buffer (it is a span, masked here, and its part past `c` is carried as `maskedLead`) or runs
+ * past the buffer's end, in which case the text from its start to the end is a proper prefix of
+ * the value, so `hold` >= length − start and `c` <= its start, a contradiction. By induction over
+ * writes, every character emitted that belongs to an occurrence is inside a masked span.
+ *
+ * The shared logger does not write through process.stderr: pino serializes each log call to one
+ * whole line (ending in "\n") and hands that line to its `streamWrite` hook before writing it to
+ * fd 2 itself, so the line filter below (the shared redactor) sees whole lines.
+ */
+/** Records a secret value this process received, and its JSON-escaped form (as a log line holds it). */
+export declare function rememberSecretValue(value: string): void;
+/** `text` without any secret value this process received. */
+export declare function redactReceivedSecrets(text: string): string;
+/**
+ * Text after the last "\n" longer than this (64 KiB) is emitted without waiting for its "\n", so an
+ * unterminated stream cannot grow the buffer without bound: it stays within this plus the longest
+ * remembered value plus one write.
+ */
+export declare const MAX_PENDING_STDERR_CHARS: number;
+/**
+ * The stderr buffer as a value: text in (`write`), masked text out, never a remembered value's
+ * character unmasked (see the module comment). `values` is read on every call, so a value
+ * remembered later applies to what is still buffered.
+ */
+export declare class StderrRedactionBuffer {
+    private readonly values;
+    private readonly bound;
+    private pending;
+    private maskedLead;
+    private atLineStart;
+    constructor(values: () => readonly string[], bound?: number);
+    /** Characters still buffered. */
+    get pendingLength(): number;
+    /** Adds `text` and returns what may be emitted now (possibly ""). */
+    write(text: string): string;
+    /**
+     * Everything still buffered, masked, fail closed (the held suffix too), ending with "\n" if output
+     * is mid-line. `maskTail` masks one more character at the end: a write's trailing lone high
+     * surrogate that never got its low half.
+     */
+    flush(maskTail?: boolean): string;
+    private redactable;
+    /** Spans over the whole buffer, the carried `maskedLead` and any `extra` forced in. */
+    private spans;
+    private emitted;
+}
+/** Emits the buffered remainder, masked fail closed and ended with "\n". Safe to call any number of times. */
+export declare function flushStderrRedaction(): void;
+/** Routes process.stderr writes through the buffer, and the shared logger's lines through redactReceivedSecrets. */
+export declare function installStderrRedaction(): void;

package/dist/native-worker/stderr-redaction.js

@@ -0,0 +1,237 @@
+/**
+ * The sandbox worker's stderr is not a redacted channel by itself: a failed worker's stderr tail
+ * reaches the server's log (docker-launcher.ts, kubernetes-launcher.ts; the launcher masks it
+ * again, as the worker is untrusted), and a tool's host calls hand the worker secret
+ * values (`secrets.get`). The worker knows those exact values (raw and JSON-escaped), so it masks
+ * them in everything it writes to stderr — its own failure line and the shared logger's lines —
+ * with the shared redactor's spans (secretSpans: the union of every occurrence, overlapping ones
+ * included, minimum length included). One set per worker process.
+ *
+ * process.stderr writes are buffered (StderrRedactionBuffer), because a value may arrive split
+ * across writes. A string is matched as text, whatever encoding it was written with (its trailing
+ * high surrogate is held for the next write, so a split surrogate pair still matches); a hex or
+ * base64 string and any ArrayBufferView go through one UTF-8 byte decoder; any other chunk type is
+ * refused, never written raw. Emitted text is written as UTF-8. On each write the buffer:
+ * 1. holds back `hold`: the longest suffix of the buffer that is a proper prefix of a remembered
+ *    value, since those characters could still become a value;
+ * 2. picks a cut `c` <= length − hold: after the last "\n" there, or, once the text after that
+ *    exceeds MAX_PENDING_STDERR_CHARS, at length − hold; otherwise it emits nothing yet;
+ * 3. masks spans over the whole buffer, with its first `maskedLead` characters forced into a span;
+ * 4. when `c` falls inside a span [s, e), emits [s, c) as the marker and carries `maskedLead` =
+ *    e − c, so the rest of that span is masked when it is emitted later;
+ * 5. emits the masked text before `c` and keeps the rest.
+ * Masking is safe at any cut, so no cut is ever searched for. On exit, SIGTERM/SIGINT and the
+ * worker's fail path the remainder is emitted with its spans, `maskedLead` and the held suffix all
+ * masked: fail closed, a possible value start is emitted as `[REDACTED]`, never raw.
+ *
+ * Why no value character is emitted: an occurrence that begins before `c` either ends within the
+ * buffer (it is a span, masked here, and its part past `c` is carried as `maskedLead`) or runs
+ * past the buffer's end, in which case the text from its start to the end is a proper prefix of
+ * the value, so `hold` >= length − start and `c` <= its start, a contradiction. By induction over
+ * writes, every character emitted that belongs to an occurrence is inside a masked span.
+ *
+ * The shared logger does not write through process.stderr: pino serializes each log call to one
+ * whole line (ending in "\n") and hands that line to its `streamWrite` hook before writing it to
+ * fd 2 itself, so the line filter below (the shared redactor) sees whole lines.
+ */
+import { StringDecoder } from "node:string_decoder";
+import { setLogLineFilter } from "../core/logger.js";
+import { maskSpans, mergeSpans, MIN_REDACTABLE_SECRET_LENGTH, redactExactSecretValues, secretSpans, withEscapedForms, } from "../core/secret-spans.js";
+const received = new Set();
+/** Records a secret value this process received, and its JSON-escaped form (as a log line holds it). */
+export function rememberSecretValue(value) {
+    for (const form of withEscapedForms([value]))
+        received.add(form);
+}
+/** `text` without any secret value this process received. */
+export function redactReceivedSecrets(text) {
+    return received.size === 0 ? text : redactExactSecretValues(text, received);
+}
+/**
+ * Text after the last "\n" longer than this (64 KiB) is emitted without waiting for its "\n", so an
+ * unterminated stream cannot grow the buffer without bound: it stays within this plus the longest
+ * remembered value plus one write.
+ */
+export const MAX_PENDING_STDERR_CHARS = 64 * 1024;
+/** The longest suffix of `text` that is a proper prefix of one of `values`. */
+function heldLength(text, values) {
+    let hold = 0;
+    for (const value of values) {
+        for (let k = Math.min(value.length - 1, text.length); k > hold; k -= 1) {
+            if (text.charCodeAt(text.length - k) === value.charCodeAt(0) && text.endsWith(value.slice(0, k))) {
+                hold = k;
+                break;
+            }
+        }
+    }
+    return hold;
+}
+/**
+ * The stderr buffer as a value: text in (`write`), masked text out, never a remembered value's
+ * character unmasked (see the module comment). `values` is read on every call, so a value
+ * remembered later applies to what is still buffered.
+ */
+export class StderrRedactionBuffer {
+    values;
+    bound;
+    pending = "";
+    maskedLead = 0;
+    atLineStart = true;
+    constructor(values, bound = MAX_PENDING_STDERR_CHARS) {
+        this.values = values;
+        this.bound = bound;
+    }
+    /** Characters still buffered. */
+    get pendingLength() {
+        return this.pending.length;
+    }
+    /** Adds `text` and returns what may be emitted now (possibly ""). */
+    write(text) {
+        this.pending += text;
+        const values = this.redactable();
+        const hold = heldLength(this.pending, values);
+        const limit = this.pending.length - hold;
+        // (lastIndexOf treats a negative start as 0, so an empty window is checked first.)
+        let cut = limit > 0 ? this.pending.lastIndexOf("\n", limit - 1) + 1 : 0;
+        if (this.pending.length - cut > this.bound)
+            cut = limit;
+        if (cut <= 0)
+            return "";
+        const spans = this.spans(values, []);
+        const inside = spans.find(([start, end]) => start < cut && cut < end);
+        this.maskedLead = inside ? inside[1] - cut : 0;
+        const ready = maskSpans(this.pending.slice(0, cut), spans.filter(([start]) => start < cut).map(([start, end]) => [start, Math.min(end, cut)]));
+        this.pending = this.pending.slice(cut);
+        return this.emitted(ready);
+    }
+    /**
+     * Everything still buffered, masked, fail closed (the held suffix too), ending with "\n" if output
+     * is mid-line. `maskTail` masks one more character at the end: a write's trailing lone high
+     * surrogate that never got its low half.
+     */
+    flush(maskTail = false) {
+        if (maskTail)
+            this.pending += "\uFFFD";
+        const values = this.redactable();
+        const text = this.pending;
+        const hold = heldLength(text, values);
+        const extra = [];
+        if (hold > 0)
+            extra.push([text.length - hold, text.length]);
+        if (maskTail)
+            extra.push([text.length - 1, text.length]);
+        const out = maskSpans(text, this.spans(values, extra));
+        this.pending = "";
+        this.maskedLead = 0;
+        const ready = this.emitted(out);
+        if (this.atLineStart)
+            return ready;
+        this.atLineStart = true;
+        return `${ready}\n`;
+    }
+    redactable() {
+        return this.values().filter((value) => value.length >= MIN_REDACTABLE_SECRET_LENGTH);
+    }
+    /** Spans over the whole buffer, the carried `maskedLead` and any `extra` forced in. */
+    spans(values, extra) {
+        const forced = this.maskedLead > 0 ? [[0, this.maskedLead], ...extra] : extra;
+        return mergeSpans([...secretSpans(this.pending, values), ...forced]);
+    }
+    emitted(text) {
+        if (text)
+            this.atLineStart = text.endsWith("\n");
+        return text;
+    }
+}
+const buffer = new StderrRedactionBuffer(() => [...received]);
+let installed = false;
+let rawWrite;
+const bytes = new StringDecoder("utf8");
+/**
+ * A string write's trailing high surrogate, held for the next write: encoded alone it would become
+ * U+FFFD, and a value whose non-BMP character is split between two writes would never match.
+ */
+let heldHighSurrogate = "";
+const isHighSurrogate = (code) => code >= 0xd800 && code <= 0xdbff;
+/** String encodings that name bytes rather than text: such a string is decoded to its bytes first. */
+const BYTE_STRING_ENCODINGS = new Set(["hex", "base64", "base64url"]);
+/**
+ * `chunk` as text for the buffer. A string is matched as the JavaScript string itself, whatever
+ * text encoding it was written with (utf16le, latin1, ...): re-encoding it and decoding the bytes as
+ * UTF-8 would turn an ASCII value into one with NULs that never matches. Its trailing high surrogate
+ * is held for the next write. A hex or base64 string, and any ArrayBufferView, goes through the one
+ * byte decoder. Any other chunk type throws (after emitting a held surrogate masked).
+ */
+function decodeChunk(chunk, encoding) {
+    if (typeof chunk === "string" && !BYTE_STRING_ENCODINGS.has(encoding?.toLowerCase() ?? "")) {
+        // An incomplete multi-byte character from an earlier byte write ends here (as U+FFFD), in order.
+        let text = bytes.end() + heldHighSurrogate + chunk;
+        heldHighSurrogate = "";
+        if (text.length > 0 && isHighSurrogate(text.charCodeAt(text.length - 1))) {
+            heldHighSurrogate = text.slice(-1);
+            text = text.slice(0, -1);
+        }
+        return text;
+    }
+    if (typeof chunk !== "string" && !ArrayBuffer.isView(chunk)) {
+        // Never handed to the raw write: its content is unknown. A held surrogate goes out masked
+        // first (fail closed, with everything buffered before it). The message names no content.
+        if (heldHighSurrogate) {
+            heldHighSurrogate = "";
+            const out = buffer.flush(true);
+            if (out)
+                rawWrite?.(out);
+        }
+        throw new TypeError("process.stderr.write takes a string or bytes (an ArrayBufferView).");
+    }
+    // Bytes end a held surrogate's chance of a low half: it is decoded alone (as U+FFFD).
+    const lone = heldHighSurrogate ? bytes.write(Buffer.from(heldHighSurrogate, "utf8")) : "";
+    heldHighSurrogate = "";
+    if (typeof chunk === "string")
+        return lone + bytes.write(Buffer.from(chunk, encoding));
+    return lone + bytes.write(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+}
+/** Emits the buffered remainder, masked fail closed and ended with "\n". Safe to call any number of times. */
+export function flushStderrRedaction() {
+    if (!rawWrite)
+        return;
+    const lone = heldHighSurrogate !== "";
+    heldHighSurrogate = "";
+    const tail = bytes.end();
+    const ready = (tail ? buffer.write(tail) : "") + buffer.flush(lone);
+    if (ready)
+        rawWrite(ready);
+}
+/** Routes process.stderr writes through the buffer, and the shared logger's lines through redactReceivedSecrets. */
+export function installStderrRedaction() {
+    if (installed)
+        return;
+    installed = true;
+    setLogLineFilter(redactReceivedSecrets);
+    const write = process.stderr.write.bind(process.stderr);
+    rawWrite = (chunk) => write(chunk);
+    process.stderr.write = (chunk, ...rest) => {
+        const encoding = typeof rest[0] === "string" ? rest[0] : undefined;
+        const callback = rest.find((arg) => typeof arg === "function");
+        // Every write goes through the one decoder, so a string after an incomplete multi-byte
+        // character from an earlier byte write keeps its place.
+        const text = decodeChunk(chunk, encoding);
+        const ready = buffer.write(text);
+        if (ready)
+            return write(ready, callback);
+        // Held for its line's end: the write is accepted, so its callback runs as if written.
+        if (callback)
+            process.nextTick(callback, null);
+        return true;
+    };
+    process.on("exit", flushStderrRedaction);
+    // A signal's default action would drop the buffered tail: flush it, then exit as the signal would.
+    process.once("SIGTERM", () => {
+        flushStderrRedaction();
+        process.exit(143);
+    });
+    process.once("SIGINT", () => {
+        flushStderrRedaction();
+        process.exit(130);
+    });
+}

package/dist/native-worker/stdio.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The worker contract over a child process's stdin/stdout, as newline-delimited
+ * JSON. The control plane writes the WorkerInput as the first line, then
+ * answers the worker's requests; the worker writes requests and reads answers.
+ * Both directions are capped at MAX_MESSAGE_BYTES per line. stderr is the
+ * worker's diagnostics only.
+ *
+ * Frames, worker → control:  { id, request }
+ * Frames, control → worker:  { id, ok: true, result } | { id, ok: false, error: { code, message, causeCode? } }
+ *                            | { id, event }  (llm.stream events)  | { id, end: true }
+ */
+import type { Readable, Writable } from "node:stream";
+import type { NativeGateway, WorkerLauncher } from "./gateway.js";
+import type { GatewayTransport } from "./worker.js";
+/** Splits a byte stream into lines, refusing any line over the cap. */
+export declare function readLines(stream: Readable, onLine: (line: string) => void, onError: (err: Error) => void): void;
+/** The worker's side: requests out on `output`, answers in on `input`. */
+export declare function createStdioTransport(input: Readable, output: Writable): GatewayTransport;
+/** Serves one worker's requests from `gateway`, answering on `output`. */
+export declare function serveStdioWorker(input: Readable, output: Writable, gateway: NativeGateway): void;
+export interface WorkerProcessSpec {
+    command: string;
+    args: string[];
+    /** The worker's whole environment. Defaults to empty: it needs nothing from the server's. */
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** Launches the worker as a child process speaking this transport on its stdio. */
+export declare function createProcessLauncher(spec: WorkerProcessSpec): WorkerLauncher;