@code-yeongyu/senpi 2026.10.18 → 2026.10.19

package/dist/modes/rpc/tool-child/admission.js

@@ -0,0 +1,81 @@
+import { TOOL_CHILD_LIMITS } from "./protocol.js";
+/**
+ * The one host-call capacity both sides enforce: `HOST_CALL_ACTIVE` running plus `HOST_CALL_WAITING` queued (264).
+ * The child admits against it before sending, the server admits against it on receipt; there is no second constant.
+ */
+export function hostCallCapacity() {
+    return TOOL_CHILD_LIMITS.HOST_CALL_ACTIVE + TOOL_CHILD_LIMITS.HOST_CALL_WAITING;
+}
+/** Lossless host-call admission: a call is running, queued FIFO, or refused with a frame naming its `callId`. */
+export class HostCallAdmission {
+    #active = new Set();
+    #waiting = [];
+    get active() {
+        return this.#active.size;
+    }
+    get waiting() {
+        return this.#waiting.length;
+    }
+    submit(callId) {
+        if (this.#active.has(callId) || this.#waiting.includes(callId))
+            return refuse(callId, "host_call_duplicate");
+        if (this.#active.size < TOOL_CHILD_LIMITS.HOST_CALL_ACTIVE && this.#waiting.length === 0) {
+            this.#active.add(callId);
+            return { state: "active" };
+        }
+        if (this.#active.size + this.#waiting.length >= hostCallCapacity())
+            return refuse(callId, "host_call_capacity");
+        this.#waiting.push(callId);
+        return { state: "waiting" };
+    }
+    /** Ends a call (or withdraws a queued one) and returns the call promoted into the freed active slot, if any. */
+    settle(callId) {
+        if (!this.#active.delete(callId)) {
+            const index = this.#waiting.indexOf(callId);
+            if (index >= 0)
+                this.#waiting.splice(index, 1);
+            return undefined;
+        }
+        const next = this.#waiting.shift();
+        if (next !== undefined)
+            this.#active.add(next);
+        return next;
+    }
+}
+function refuse(callId, code) {
+    return { state: "refused", frame: { type: "host_call_refused", callId, code } };
+}
+/**
+ * Per-child job budget. Ordinary jobs are capped at `TOOL_CHILD_LIMITS.jobs`. A nested job (started on behalf of a
+ * running job, e.g. a tool an eval cell calls) is admitted past that cap, so a full child cannot deadlock its own
+ * callers; nested jobs arrive through host calls and are bounded by `hostCallCapacity()`.
+ */
+export class JobAdmission {
+    #ordinary = new Set();
+    #nested = new Map();
+    admit(jobId, parentJobId) {
+        if (this.#ordinary.has(jobId) || this.#nested.has(jobId))
+            return refuseJob(jobId, "tool_child_job_duplicate");
+        if (parentJobId === undefined) {
+            if (this.#ordinary.size >= TOOL_CHILD_LIMITS.jobs)
+                return refuseJob(jobId, "tool_child_jobs_full");
+            this.#ordinary.add(jobId);
+            return { admitted: true };
+        }
+        if (!this.#ordinary.has(parentJobId) && !this.#nested.has(parentJobId)) {
+            return refuseJob(jobId, "tool_child_parent_unknown");
+        }
+        if (this.#nested.size >= hostCallCapacity())
+            return refuseJob(jobId, "tool_child_nested_full");
+        this.#nested.set(jobId, parentJobId);
+        return { admitted: true };
+    }
+    finish(jobId) {
+        this.#ordinary.delete(jobId);
+        this.#nested.delete(jobId);
+    }
+}
+function refuseJob(jobId, code) {
+    return { admitted: false, frame: { type: "job_refused", jobId, code } };
+}
+//# sourceMappingURL=admission.js.map

package/dist/modes/rpc/tool-child/admission.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=admission.test.d.ts.map

package/dist/modes/rpc/tool-child/admission.test.js

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import { HostCallAdmission, hostCallCapacity, JobAdmission } from "./admission.js";
+import { encodeFrame, FrameDecoder } from "./codec.js";
+import { isLossy, TraceBudget, WakeAdmission, WakeAdmissionError } from "./flow-control.js";
+import { LOSSY_FRAME_TYPES, TOOL_CHILD_LIMITS } from "./protocol.js";
+import { isToolChildMessage } from "./protocol-guard.js";
+const callId = (index) => `call-${index}`;
+function submitMany(admission, count) {
+    const states = { active: 0, waiting: 0, refused: [] };
+    for (let index = 1; index <= count; index += 1) {
+        const decision = admission.submit(callId(index));
+        if (decision.state === "refused")
+            states.refused.push(decision.frame.callId);
+        else
+            states[decision.state] += 1;
+    }
+    return states;
+}
+/** One loop turn: enough for an already-resolved promise to settle, never a timed wait. */
+const turn = () => new Promise((resolve) => setImmediate(resolve));
+function tracked(promise) {
+    const state = { settled: false };
+    promise.then(() => {
+        state.settled = true;
+    });
+    return state;
+}
+describe("host-call admission", () => {
+    it("has one capacity: 8 active + 256 waiting = 264", () => {
+        expect(hostCallCapacity()).toBe(264);
+        expect(hostCallCapacity()).toBe(TOOL_CHILD_LIMITS.HOST_CALL_ACTIVE + TOOL_CHILD_LIMITS.HOST_CALL_WAITING);
+    });
+    it("264 concurrent submissions -> 8 active, 256 waiting, 0 refused", () => {
+        const admission = new HostCallAdmission();
+        expect(submitMany(admission, 264)).toEqual({ active: 8, waiting: 256, refused: [] });
+        expect(admission.active).toBe(8);
+        expect(admission.waiting).toBe(256);
+    });
+    it("265 -> exactly the 265th is refused with a correlated host_call_refused frame", () => {
+        const admission = new HostCallAdmission();
+        expect(submitMany(admission, 265).refused).toEqual(["call-265"]);
+        const decision = new HostCallAdmission().submit("x");
+        expect(decision.state).toBe("active");
+        const full = new HostCallAdmission();
+        submitMany(full, 264);
+        const refused = full.submit("call-265");
+        if (refused.state !== "refused")
+            throw new Error("expected a refusal");
+        expect(refused.frame).toEqual({ type: "host_call_refused", callId: "call-265", code: "host_call_capacity" });
+        expect(isToolChildMessage(refused.frame)).toBe(true);
+        expect(new FrameDecoder().push(encodeFrame(refused.frame))).toEqual([refused.frame]);
+    });
+    it("promotes waiting calls in FIFO order", () => {
+        const admission = new HostCallAdmission();
+        submitMany(admission, 264);
+        const promoted = [];
+        for (let index = 1; index <= 264; index += 1)
+            promoted.push(admission.settle(callId(index)));
+        expect(promoted.slice(0, 256)).toEqual(Array.from({ length: 256 }, (_, offset) => callId(offset + 9)));
+        expect(promoted.slice(256)).toEqual(Array(8).fill(undefined));
+        expect(admission.active + admission.waiting).toBe(0);
+    });
+    it("child and server share the capacity: the child never forwards a call the server would refuse", () => {
+        const child = new HostCallAdmission();
+        const server = new HostCallAdmission();
+        const refusedByServer = [];
+        for (let index = 1; index <= 300; index += 1) {
+            if (child.submit(callId(index)).state === "refused")
+                continue;
+            const decision = server.submit(callId(index));
+            if (decision.state === "refused")
+                refusedByServer.push(decision.frame.callId);
+        }
+        expect(refusedByServer).toEqual([]);
+        expect(server.active + server.waiting).toBe(hostCallCapacity());
+    });
+    it("refuses a duplicate call id", () => {
+        const admission = new HostCallAdmission();
+        admission.submit("same");
+        const duplicate = admission.submit("same");
+        expect(duplicate.state === "refused" && duplicate.frame.code).toBe("host_call_duplicate");
+    });
+});
+describe("job admission", () => {
+    it("refuses the 33rd ordinary job while a nested job is still admitted", () => {
+        const jobs = new JobAdmission();
+        for (let index = 1; index <= 32; index += 1)
+            expect(jobs.admit(`job-${index}`)).toEqual({ admitted: true });
+        expect(jobs.admit("job-33")).toEqual({
+            admitted: false,
+            frame: { type: "job_refused", jobId: "job-33", code: "tool_child_jobs_full" },
+        });
+        expect(jobs.admit("nested-1", "job-1")).toEqual({ admitted: true });
+        expect(jobs.admit("nested-2", "missing")).toEqual({
+            admitted: false,
+            frame: { type: "job_refused", jobId: "nested-2", code: "tool_child_parent_unknown" },
+        });
+        jobs.finish("job-2");
+        expect(jobs.admit("job-33")).toEqual({ admitted: true });
+    });
+    it("bounds nested jobs by the host-call capacity, not by a second constant", () => {
+        const jobs = new JobAdmission();
+        jobs.admit("parent");
+        for (let index = 1; index <= hostCallCapacity(); index += 1) {
+            expect(jobs.admit(`nested-${index}`, "parent")).toEqual({ admitted: true });
+        }
+        const over = jobs.admit("nested-over", "parent");
+        expect(over.admitted === false && over.frame.code).toBe("tool_child_nested_full");
+    });
+});
+describe("wake flow control", () => {
+    it("the 65th pending wake waits for wake_ack and is never dropped", async () => {
+        const wakes = new WakeAdmission();
+        for (let index = 1; index <= 64; index += 1)
+            await wakes.send(`w-${index}`, 10);
+        const sixtyFifth = tracked(wakes.send("w-65", 10));
+        const sixtySixth = tracked(wakes.send("w-66", 10));
+        await turn();
+        expect(sixtyFifth.settled).toBe(false);
+        expect(wakes.blocked).toBe(2);
+        expect(wakes.pending).toBe(64);
+        wakes.ack("w-1");
+        await turn();
+        expect(sixtyFifth.settled).toBe(true);
+        expect(sixtySixth.settled).toBe(false);
+        wakes.ack("w-2");
+        await turn();
+        expect(sixtySixth.settled).toBe(true);
+        expect(wakes.pending).toBe(64);
+        expect(wakes.blocked).toBe(0);
+    });
+    it("bounds pending wakes by summed bytes and refuses one larger than the whole budget", async () => {
+        const wakes = new WakeAdmission();
+        const part = 600 * 1024;
+        await wakes.send("a", part);
+        const second = tracked(wakes.send("b", part));
+        await turn();
+        expect(second.settled).toBe(false);
+        wakes.ack("a");
+        await turn();
+        expect(second.settled).toBe(true);
+        await expect(wakes.send("huge", TOOL_CHILD_LIMITS.wakePendingBytes + 1)).rejects.toBeInstanceOf(WakeAdmissionError);
+    });
+});
+describe("trace budget", () => {
+    it("drops and counts the 1,025th trace frame in one second, then admits again in the next", () => {
+        const budget = new TraceBudget();
+        const frame = { type: "trace", atMs: 0, event: "tick" };
+        const admitted = Array.from({ length: 1025 }, () => budget.admit(frame, 5_000));
+        expect(admitted.filter(Boolean)).toHaveLength(1024);
+        expect(admitted.at(-1)).toBe(false);
+        expect(budget.dropped).toBe(1);
+        expect(budget.admit(frame, 6_000)).toBe(true);
+        expect(budget.dropped).toBe(1);
+    });
+    it("trace is the only lossy class; results, proofs and ticks are never lossy", () => {
+        expect([...LOSSY_FRAME_TYPES]).toEqual(["trace"]);
+        expect(isLossy({ type: "trace", atMs: 1, event: "e" })).toBe(true);
+        expect(isLossy({ type: "launch_proof", launchId: "l", ackTick: 1, invokeTick: 2 })).toBe(false);
+        expect(isLossy({ type: "result", jobId: "j", value: 1 })).toBe(false);
+        expect(isLossy({ type: "slot_state", launchId: "l", ackTick: 1, invokeTick: 2, invocations: 1 })).toBe(false);
+        expect(isToolChildMessage({ type: "trace", atMs: 1, event: "e", detail: { invokeTick: 2 } })).toBe(false);
+        expect(isToolChildMessage({ type: "trace", atMs: 1, event: "e", result: 1 })).toBe(false);
+    });
+});
+//# sourceMappingURL=admission.test.js.map

package/dist/modes/rpc/tool-child/codec.d.ts

@@ -0,0 +1,21 @@
+import { type ToolChildMessage } from "./protocol.ts";
+export type ToolChildCodecErrorCode = "tool_child_frame_too_large" | "tool_child_truncated" | "tool_child_malformed" | "tool_child_encode_invalid";
+export declare class ToolChildCodecError extends Error {
+    readonly code: ToolChildCodecErrorCode;
+    constructor(code: ToolChildCodecErrorCode, message: string);
+}
+/** A frame is a 4-byte big-endian body length followed by that many bytes of UTF-8 JSON. No delimiter, no NDJSON. */
+export declare const FRAME_HEADER_BYTES = 4;
+export declare function encodeFrame(message: ToolChildMessage): Uint8Array;
+/**
+ * Incremental decoder for one channel direction. A length header above the cap is refused as soon as its four bytes
+ * arrive, before any body buffer exists. Any codec error is terminal: the stream is never resynchronized, so nothing
+ * after a bad frame can be silently skipped.
+ */
+export declare class FrameDecoder {
+    #private;
+    get bufferedBytes(): number;
+    push(chunk: Uint8Array): ToolChildMessage[];
+    end(): void;
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/modes/rpc/tool-child/codec.js

@@ -0,0 +1,137 @@
+import { TOOL_CHILD_LIMITS } from "./protocol.js";
+import { isToolChildMessage } from "./protocol-guard.js";
+export class ToolChildCodecError extends Error {
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = "ToolChildCodecError";
+        this.code = code;
+    }
+}
+/** A frame is a 4-byte big-endian body length followed by that many bytes of UTF-8 JSON. No delimiter, no NDJSON. */
+export const FRAME_HEADER_BYTES = 4;
+const tooLarge = (bytes) => new ToolChildCodecError("tool_child_frame_too_large", `${bytes} bytes exceeds ${TOOL_CHILD_LIMITS.frameBytes}`);
+export function encodeFrame(message) {
+    // JSON.stringify drops undefined-valued properties (what optional fields rely on) and natively serializes
+    // NaN/Infinity as null on BOTH the inline and the ref path, so payload contents encode identically either way.
+    // The one case JSON cannot represent is a REQUIRED json field that is undefined (today only result.value - a
+    // tool returning undefined); it becomes an explicit null the guard takes. The round-trip with the decoder's own
+    // predicate refuses anything else unsendable HERE - a typed per-message error, never a channel-killing frame
+    // (senpi#3569 delta review: optional undefined must keep stringify's default drop).
+    const normalized = message.type === "result" && message.value === undefined ? { ...message, value: null } : message;
+    const json = JSON.stringify(normalized);
+    const bodyBytes = Buffer.byteLength(json, "utf8");
+    if (bodyBytes > TOOL_CHILD_LIMITS.frameBytes)
+        throw tooLarge(bodyBytes);
+    if (!isToolChildMessage(JSON.parse(json))) {
+        throw new ToolChildCodecError("tool_child_encode_invalid", "the message serializes to a frame the peer's guard rejects");
+    }
+    return frameFromBody(json, bodyBytes);
+}
+function frameFromBody(json, bodyBytes) {
+    const frame = Buffer.allocUnsafe(FRAME_HEADER_BYTES + bodyBytes);
+    frame.writeUInt32BE(bodyBytes, 0);
+    frame.write(json, FRAME_HEADER_BYTES, "utf8");
+    return frame;
+}
+function parseBody(body) {
+    let value;
+    try {
+        value = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        throw new ToolChildCodecError("tool_child_malformed", "frame body is not JSON");
+    }
+    if (!isToolChildMessage(value))
+        throw new ToolChildCodecError("tool_child_malformed", "frame is not a protocol message");
+    return value;
+}
+/**
+ * Incremental decoder for one channel direction. A length header above the cap is refused as soon as its four bytes
+ * arrive, before any body buffer exists. Any codec error is terminal: the stream is never resynchronized, so nothing
+ * after a bad frame can be silently skipped.
+ */
+export class FrameDecoder {
+    #chunks = [];
+    #buffered = 0;
+    #bodyBytes;
+    #failure;
+    get bufferedBytes() {
+        return this.#buffered;
+    }
+    push(chunk) {
+        if (this.#failure)
+            throw this.#failure;
+        if (chunk.length > 0) {
+            this.#chunks.push(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+            this.#buffered += chunk.length;
+        }
+        const messages = [];
+        try {
+            for (;;) {
+                if (this.#bodyBytes === undefined) {
+                    if (this.#buffered < FRAME_HEADER_BYTES)
+                        break;
+                    const length = this.#take(FRAME_HEADER_BYTES).readUInt32BE(0);
+                    if (length > TOOL_CHILD_LIMITS.frameBytes)
+                        throw tooLarge(length);
+                    this.#bodyBytes = length;
+                }
+                if (this.#buffered < this.#bodyBytes)
+                    break;
+                const body = this.#take(this.#bodyBytes);
+                this.#bodyBytes = undefined;
+                messages.push(parseBody(body));
+            }
+        }
+        catch (error) {
+            if (error instanceof ToolChildCodecError)
+                this.#fail(error);
+            throw error;
+        }
+        return messages;
+    }
+    end() {
+        if (this.#failure)
+            throw this.#failure;
+        if (this.#buffered === 0 && this.#bodyBytes === undefined)
+            return;
+        const truncated = new ToolChildCodecError("tool_child_truncated", `stream ended inside a frame (${this.#buffered} of ${this.#bodyBytes ?? FRAME_HEADER_BYTES} bytes)`);
+        this.#fail(truncated);
+        throw truncated;
+    }
+    #fail(error) {
+        this.#failure = error;
+        this.#chunks = [];
+        this.#buffered = 0;
+        this.#bodyBytes = undefined;
+    }
+    #take(bytes) {
+        const first = this.#chunks[0];
+        if (first !== undefined && first.length >= bytes) {
+            const taken = first.subarray(0, bytes);
+            if (first.length === bytes)
+                this.#chunks.shift();
+            else
+                this.#chunks[0] = first.subarray(bytes);
+            this.#buffered -= bytes;
+            return taken;
+        }
+        const out = Buffer.allocUnsafe(bytes);
+        let filled = 0;
+        while (filled < bytes) {
+            const chunk = this.#chunks[0];
+            if (chunk === undefined)
+                break;
+            const count = Math.min(chunk.length, bytes - filled);
+            chunk.copy(out, filled, 0, count);
+            filled += count;
+            if (count === chunk.length)
+                this.#chunks.shift();
+            else
+                this.#chunks[0] = chunk.subarray(count);
+        }
+        this.#buffered -= bytes;
+        return out;
+    }
+}
+//# sourceMappingURL=codec.js.map

package/dist/modes/rpc/tool-child/codec.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec.test.d.ts.map

package/dist/modes/rpc/tool-child/codec.test.js

@@ -0,0 +1,234 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { encodeFrame, FRAME_HEADER_BYTES, FrameDecoder, ToolChildCodecError } from "./codec.js";
+import { narrowContext } from "./context.js";
+import { LAUNCH_CONTAINMENTS, TOOL_CHILD_LIMITS } from "./protocol.js";
+import { TOOL_CHILD_MESSAGE_TYPES } from "./protocol-guard.js";
+const ref = { refId: "r-1", generation: 3, bytes: 10, sha256: "a".repeat(64) };
+const SAMPLES = [
+    ...LAUNCH_CONTAINMENTS.map((containment) => ({
+        type: "launch",
+        launchId: `l-${containment}`,
+        jobId: "j1",
+        origin: "tool",
+        api: "bun.spawn",
+        containment,
+        lifetime: "owned",
+        pid: 10,
+        pgid: 10,
+    })),
+    {
+        type: "launch",
+        launchId: "l-det",
+        jobId: "j1",
+        origin: "kernel",
+        api: "cp.spawn",
+        containment: "breakaway",
+        lifetime: "detached",
+    },
+    { type: "launch_ack", launchId: "l-1" },
+    { type: "launch_proof", launchId: "l-1", ackTick: 4, invokeTick: 5 },
+    { type: "launch_done", launchId: "l-1", exitCode: 0 },
+    { type: "launch_done", launchId: "l-2", signal: "SIGTERM" },
+    { type: "command_started", launchId: "l-1", pid: 77, startedAtMs: 1234, creatorInJob: true, breakaway: false },
+    { type: "slot_query", launchId: "l-1" },
+    { type: "slot_state", launchId: "l-1", ackTick: null, invokeTick: null, invocations: 0 },
+    { type: "slot_state", launchId: "l-1", ackTick: 4, invokeTick: 5, invocations: 1 },
+    { type: "trace", atMs: 1, event: "job_start", detail: { kind: "grep", ok: true, n: 3 } },
+    { type: "trace", atMs: 2, event: "idle" },
+    {
+        type: "batch",
+        jobId: "j-parse",
+        done: false,
+        entries: [
+            { id: "e1", parentId: null, lineOffset: 0, lineBytes: 120, lineDelta: 0, entry: { type: "message" } },
+            { id: "e2", parentId: "e1", lineOffset: 121, lineBytes: 4096, lineDelta: -3500 },
+        ],
+    },
+    { type: "hello", generation: 3, pid: 99, protocol: 1 },
+    { type: "hello_ack", generation: 3 },
+    { type: "heartbeat", seq: 7 },
+    { type: "job", jobId: "j1", kind: "read", args: { path: "a\nb.txt" } },
+    { type: "job", jobId: "j2", kind: "write", parentJobId: "j1", argsRef: ref },
+    { type: "cancel", jobId: "j1" },
+    { type: "result", jobId: "j1", value: { content: [{ type: "text", text: "line\n" }] } },
+    { type: "result", jobId: "j3", value: null },
+    { type: "result_ref", jobId: "j1", ref },
+    { type: "job_error", jobId: "j1", code: "tool_failed", message: "boom" },
+    { type: "job_refused", jobId: "j9", code: "tool_child_jobs_full" },
+    { type: "host_call", callId: "c1", jobId: "j1", tool: "read", args: { path: "x" } },
+    { type: "host_call", callId: "c2", jobId: "j1", tool: "write", argsRef: ref },
+    { type: "host_reply", callId: "c1", value: [1, 2] },
+    { type: "host_reply", callId: "c2", valueRef: ref },
+    { type: "host_reply", callId: "c3", error: "denied" },
+    { type: "host_call_refused", callId: "c265", code: "host_call_capacity" },
+    { type: "wake", wakeId: "w1", source: "monitor", bytes: 12 },
+    { type: "wake_ack", wakeId: "w1" },
+    { type: "ref_ack", refId: "r-1" },
+    { type: "ref_nack", refId: "r-1", reason: "cancelled" },
+    { type: "shutdown" },
+];
+function concat(parts) {
+    return Buffer.concat(parts.map((part) => Buffer.from(part)));
+}
+function codecError(run) {
+    try {
+        run();
+    }
+    catch (error) {
+        if (error instanceof ToolChildCodecError)
+            return error.code;
+        throw error;
+    }
+    return undefined;
+}
+function frameWithBody(body) {
+    const bytes = Buffer.from(body, "utf8");
+    const header = Buffer.alloc(FRAME_HEADER_BYTES);
+    header.writeUInt32BE(bytes.length, 0);
+    return concat([header, bytes]);
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("tool-child codec", () => {
+    it("round-trips every message type through one chunked stream", () => {
+        expect(new Set(SAMPLES.map((message) => message.type))).toEqual(new Set(TOOL_CHILD_MESSAGE_TYPES));
+        const stream = concat(SAMPLES.map(encodeFrame));
+        const decoder = new FrameDecoder();
+        const decoded = [];
+        for (let offset = 0; offset < stream.length; offset += 7) {
+            decoded.push(...decoder.push(stream.subarray(offset, offset + 7)));
+        }
+        decoder.end();
+        expect(decoded).toEqual(SAMPLES);
+    });
+    it("frames with a big-endian length prefix, not NDJSON", () => {
+        const frame = Buffer.from(encodeFrame({ type: "job", jobId: "j1", kind: "read", args: { text: "a\nb" } }));
+        const bodyBytes = frame.readUInt32BE(0);
+        expect(frame.length).toBe(FRAME_HEADER_BYTES + bodyBytes);
+        expect(frame.at(-1)).not.toBe(0x0a);
+    });
+    it("accepts a body of exactly the cap and refuses one byte more on encode", () => {
+        const overhead = JSON.stringify({ type: "result", jobId: "j", value: "" }).length;
+        const fits = "x".repeat(TOOL_CHILD_LIMITS.frameBytes - overhead);
+        const frame = encodeFrame({ type: "result", jobId: "j", value: fits });
+        expect(new FrameDecoder().push(frame)).toEqual([{ type: "result", jobId: "j", value: fits }]);
+        expect(codecError(() => encodeFrame({ type: "result", jobId: "j", value: `${fits}x` }))).toBe("tool_child_frame_too_large");
+    });
+    it("refuses a 16 MiB+1 length header before allocating its body, and stays failed", () => {
+        const alloc = vi.spyOn(Buffer, "alloc");
+        const allocUnsafe = vi.spyOn(Buffer, "allocUnsafe");
+        const header = Buffer.alloc(FRAME_HEADER_BYTES);
+        header.writeUInt32BE(TOOL_CHILD_LIMITS.frameBytes + 1, 0);
+        alloc.mockClear();
+        const decoder = new FrameDecoder();
+        expect(codecError(() => decoder.push(header))).toBe("tool_child_frame_too_large");
+        const large = (spy) => spy.mock.calls.filter(([size]) => Number(size) > 1024);
+        expect(large(alloc)).toEqual([]);
+        expect(large(allocUnsafe)).toEqual([]);
+        expect(decoder.bufferedBytes).toBe(0);
+        expect(codecError(() => decoder.push(encodeFrame({ type: "shutdown" })))).toBe("tool_child_frame_too_large");
+    });
+    it("reports a truncated stream as tool_child_truncated", () => {
+        const frame = encodeFrame({ type: "heartbeat", seq: 1 });
+        const partialBody = new FrameDecoder();
+        expect(partialBody.push(frame.subarray(0, frame.length - 1))).toEqual([]);
+        expect(codecError(() => partialBody.end())).toBe("tool_child_truncated");
+        const partialHeader = new FrameDecoder();
+        partialHeader.push(frame.subarray(0, 2));
+        expect(codecError(() => partialHeader.end())).toBe("tool_child_truncated");
+        const clean = new FrameDecoder();
+        clean.push(frame);
+        expect(codecError(() => clean.end())).toBeUndefined();
+    });
+    it("refuses malformed frames instead of dropping them", () => {
+        const cases = [
+            "not json",
+            JSON.stringify({ type: "unknown_type" }),
+            JSON.stringify({ type: "launch_proof", launchId: "l", ackTick: 1 }),
+            JSON.stringify({ type: "trace", atMs: 1, event: "e", value: { result: 1 } }),
+            JSON.stringify({ type: "trace", atMs: 1, event: "e", detail: { ackTick: 4 } }),
+            JSON.stringify({
+                type: "launch",
+                launchId: "l",
+                jobId: "j",
+                origin: "tool",
+                api: "bun.spawn",
+                containment: "pid",
+                lifetime: "owned",
+            }),
+        ];
+        for (const body of cases) {
+            expect(codecError(() => new FrameDecoder().push(frameWithBody(body)))).toBe("tool_child_malformed");
+        }
+    });
+});
+describe("ChildToolContext", () => {
+    it("narrowContext keeps plain data only: no functions, no ui, no sessionManager", () => {
+        const extensionContext = {
+            ui: { notify: () => undefined },
+            sessionManager: { getEntries: () => [] },
+            cwd: "/work",
+            agentDir: "/agent",
+            mode: "rpc",
+            model: { provider: "anthropic", id: "claude", api: "messages", compat: () => true },
+            thinkingLevel: "medium",
+            isProjectTrusted: () => true,
+            isIdle: () => false,
+            goalStoreFile: "/agent/goal.json",
+        };
+        const narrowed = narrowContext(extensionContext, { sessionId: "s1", toolCallId: "t1" });
+        const keys = [];
+        const functions = [];
+        const walk = (value, path) => {
+            if (typeof value === "function")
+                functions.push(path);
+            if (typeof value !== "object" || value === null)
+                return;
+            for (const [key, item] of Object.entries(value)) {
+                keys.push(key);
+                walk(item, `${path}.${key}`);
+            }
+        };
+        walk(narrowed, "ctx");
+        expect(functions).toEqual([]);
+        expect(keys).not.toContain("ui");
+        expect(keys).not.toContain("sessionManager");
+        expect(narrowed).toEqual({
+            cwd: "/work",
+            agentDir: "/agent",
+            mode: "rpc",
+            sessionId: "s1",
+            toolCallId: "t1",
+            projectTrusted: true,
+            model: { provider: "anthropic", id: "claude" },
+            thinkingLevel: "medium",
+            goalStoreFile: "/agent/goal.json",
+        });
+        const [decoded] = new FrameDecoder().push(encodeFrame({ type: "job", jobId: "j", kind: "read", args: narrowed }));
+        expect(decoded).toEqual({ type: "job", jobId: "j", kind: "read", args: narrowed });
+    });
+});
+describe("encode-time normalization (senpi#3569 review)", () => {
+    it("a job result of undefined encodes as an explicit null the decoder accepts", () => {
+        const [decoded] = new FrameDecoder().push(encodeFrame({ type: "result", jobId: "j", value: undefined }));
+        expect(decoded).toMatchObject({ type: "result", jobId: "j", value: null });
+    });
+    it("a NaN job result encodes as null instead of killing the channel", () => {
+        const [decoded] = new FrameDecoder().push(encodeFrame({ type: "result", jobId: "j", value: Number.NaN }));
+        expect(decoded).toMatchObject({ type: "result", jobId: "j", value: null });
+    });
+    it("optional fields set to undefined keep stringify's default drop and still encode (delta review HIGH 1)", () => {
+        const [decoded] = new FrameDecoder().push(encodeFrame({ type: "launch_done", launchId: "l1", signal: "SIGTERM" }));
+        expect(decoded).toEqual({ type: "launch_done", launchId: "l1", signal: "SIGTERM" });
+        expect("exitCode" in decoded).toBe(false);
+    });
+    it("nested undefined payload keys stay dropped, matching the ref path (delta review MEDIUM 2)", () => {
+        const [decoded] = new FrameDecoder().push(encodeFrame({ type: "result", jobId: "j", value: { content: "x", details: undefined } }));
+        expect(decoded.value).toEqual({ content: "x" });
+    });
+    it("a non-finite required number is refused at encode with a typed error, never as a frame", () => {
+        expect(() => encodeFrame({ type: "heartbeat", seq: Number.POSITIVE_INFINITY })).toThrow(ToolChildCodecError);
+    });
+});
+//# sourceMappingURL=codec.test.js.map