@code-yeongyu/senpi 2026.10.18-1 → 2026.10.19

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

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

@@ -0,0 +1,42 @@
+import type { BrowserEngine } from "../../../core/browser-engine.ts";
+import type { ExtensionMode } from "../../../core/extensions/types.ts";
+/**
+ * What a tool body running in the tool child may see of its extension context: plain, serializable data only.
+ * No functions, no `ui`, no `sessionManager` - those stay on the server and are reached through host calls.
+ */
+export interface ChildToolContext {
+    cwd: string;
+    agentDir: string;
+    mode: ExtensionMode;
+    toolCallId: string;
+    projectTrusted: boolean;
+    sessionId?: string;
+    model?: {
+        provider: string;
+        id: string;
+    };
+    thinkingLevel?: string;
+    serviceTier?: string;
+    browserEngine?: BrowserEngine;
+    goalStoreFile?: string;
+}
+/** The fields `narrowContext` reads; `ExtensionContext` satisfies it structurally. */
+export interface NarrowableContext {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly mode: ExtensionMode;
+    readonly model: {
+        readonly provider: string;
+        readonly id: string;
+    } | undefined;
+    readonly thinkingLevel?: string | undefined;
+    readonly serviceTier?: string | undefined;
+    readonly browserEngine?: BrowserEngine | undefined;
+    readonly goalStoreFile?: string | undefined;
+    isProjectTrusted(): boolean;
+}
+export declare function narrowContext(ctx: NarrowableContext, ids: {
+    sessionId?: string | undefined;
+    toolCallId: string;
+}): ChildToolContext;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1,23 @@
+export function narrowContext(ctx, ids) {
+    const narrowed = {
+        cwd: ctx.cwd,
+        agentDir: ctx.agentDir,
+        mode: ctx.mode,
+        toolCallId: ids.toolCallId,
+        projectTrusted: ctx.isProjectTrusted(),
+    };
+    if (ids.sessionId !== undefined)
+        narrowed.sessionId = ids.sessionId;
+    if (ctx.model !== undefined)
+        narrowed.model = { provider: ctx.model.provider, id: ctx.model.id };
+    if (ctx.thinkingLevel !== undefined)
+        narrowed.thinkingLevel = ctx.thinkingLevel;
+    if (ctx.serviceTier !== undefined)
+        narrowed.serviceTier = ctx.serviceTier;
+    if (ctx.browserEngine !== undefined)
+        narrowed.browserEngine = ctx.browserEngine;
+    if (ctx.goalStoreFile !== undefined)
+        narrowed.goalStoreFile = ctx.goalStoreFile;
+    return narrowed;
+}
+//# sourceMappingURL=context.js.map

package/dist/modes/rpc/tool-child/flow-control.d.ts

@@ -0,0 +1,24 @@
+import { type ToolChildMessage, type ToolChildMessageOf } from "./protocol.ts";
+export declare class WakeAdmissionError extends Error {
+    readonly code = "wake_too_large";
+    constructor(bytes: number);
+}
+/**
+ * Wake notifications awaiting `wake_ack`, bounded by count and summed bytes. A wake past either bound waits, FIFO,
+ * until an ack frees room: wakes are durable wake-source demand and are never dropped.
+ */
+export declare class WakeAdmission {
+    #private;
+    get pending(): number;
+    get blocked(): number;
+    send(wakeId: string, bytes: number): Promise<void>;
+    ack(wakeId: string): void;
+}
+/** Per-second budget for `trace` frames, the only lossy class: an over-budget frame is dropped and counted. */
+export declare class TraceBudget {
+    #private;
+    get dropped(): number;
+    admit(_frame: ToolChildMessageOf<"trace">, nowMs: number): boolean;
+}
+export declare function isLossy(message: ToolChildMessage): boolean;
+//# sourceMappingURL=flow-control.d.ts.map

package/dist/modes/rpc/tool-child/flow-control.js

@@ -0,0 +1,80 @@
+import { LOSSY_FRAME_TYPES, TOOL_CHILD_LIMITS } from "./protocol.js";
+export class WakeAdmissionError extends Error {
+    constructor(bytes) {
+        super(`wake_too_large: ${bytes} bytes exceeds the ${TOOL_CHILD_LIMITS.wakePendingBytes}-byte pending budget`);
+        this.code = "wake_too_large";
+        this.name = "WakeAdmissionError";
+    }
+}
+/**
+ * Wake notifications awaiting `wake_ack`, bounded by count and summed bytes. A wake past either bound waits, FIFO,
+ * until an ack frees room: wakes are durable wake-source demand and are never dropped.
+ */
+export class WakeAdmission {
+    #pending = new Map();
+    #blocked = [];
+    #pendingBytes = 0;
+    get pending() {
+        return this.#pending.size;
+    }
+    get blocked() {
+        return this.#blocked.length;
+    }
+    send(wakeId, bytes) {
+        if (bytes > TOOL_CHILD_LIMITS.wakePendingBytes)
+            return Promise.reject(new WakeAdmissionError(bytes));
+        if (this.#blocked.length === 0 && this.#fits(bytes)) {
+            this.#admit(wakeId, bytes);
+            return Promise.resolve();
+        }
+        return new Promise((release) => {
+            this.#blocked.push({ wakeId, bytes, release });
+        });
+    }
+    ack(wakeId) {
+        const bytes = this.#pending.get(wakeId);
+        if (bytes === undefined)
+            return;
+        this.#pending.delete(wakeId);
+        this.#pendingBytes -= bytes;
+        for (let next = this.#blocked[0]; next !== undefined && this.#fits(next.bytes); next = this.#blocked[0]) {
+            this.#blocked.shift();
+            this.#admit(next.wakeId, next.bytes);
+            next.release();
+        }
+    }
+    #fits(bytes) {
+        return (this.#pending.size < TOOL_CHILD_LIMITS.wakePending &&
+            this.#pendingBytes + bytes <= TOOL_CHILD_LIMITS.wakePendingBytes);
+    }
+    #admit(wakeId, bytes) {
+        this.#pending.set(wakeId, bytes);
+        this.#pendingBytes += bytes;
+    }
+}
+/** Per-second budget for `trace` frames, the only lossy class: an over-budget frame is dropped and counted. */
+export class TraceBudget {
+    #second = Number.NaN;
+    #admitted = 0;
+    #dropped = 0;
+    get dropped() {
+        return this.#dropped;
+    }
+    admit(_frame, nowMs) {
+        const second = Math.floor(nowMs / 1000);
+        if (second !== this.#second) {
+            this.#second = second;
+            this.#admitted = 0;
+        }
+        if (this.#admitted >= TOOL_CHILD_LIMITS.tracePerSecond) {
+            this.#dropped += 1;
+            return false;
+        }
+        this.#admitted += 1;
+        return true;
+    }
+}
+export function isLossy(message) {
+    return LOSSY_FRAME_TYPES.has(message.type);
+}
+//# sourceMappingURL=flow-control.js.map

package/dist/modes/rpc/tool-child/payload-ref-paths.d.ts

@@ -0,0 +1,9 @@
+import type { PayloadRef } from "./protocol.ts";
+export declare function refGenerationDir(root: string, generation: number): string;
+export declare function refFilePath(root: string, ref: Pick<PayloadRef, "refId" | "generation">): string;
+export declare function spoolDir(root: string, generation: number): string;
+/** Generation teardown: every ref of that generation, acknowledged or not, and its `spool/`. */
+export declare function teardownRefGeneration(root: string, generation: number): Promise<void>;
+/** Removes the directory of every generation not in `live` (left by a dead child or server); returns them, sorted. */
+export declare function sweepRefGenerations(root: string, live: ReadonlySet<number>): Promise<number[]>;
+//# sourceMappingURL=payload-ref-paths.d.ts.map

package/dist/modes/rpc/tool-child/payload-ref-paths.js

@@ -0,0 +1,45 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { isRefId } from "./protocol-guard.js";
+/**
+ * Layout under the channel's ref root: `gen-<generation>/refs/<refId>` and `gen-<generation>/spool/`. Refs of both
+ * directions live under the child generation that owns the channel, so one teardown removes all of them.
+ */
+const GENERATION_DIR = /^gen-(\d+)$/;
+export function refGenerationDir(root, generation) {
+    return join(root, `gen-${generation}`);
+}
+export function refFilePath(root, ref) {
+    if (!isRefId(ref.refId))
+        throw new Error(`invalid ref id: ${JSON.stringify(ref.refId)}`);
+    return join(refGenerationDir(root, ref.generation), "refs", ref.refId);
+}
+export function spoolDir(root, generation) {
+    return join(refGenerationDir(root, generation), "spool");
+}
+/** Generation teardown: every ref of that generation, acknowledged or not, and its `spool/`. */
+export async function teardownRefGeneration(root, generation) {
+    await rm(refGenerationDir(root, generation), { recursive: true, force: true });
+}
+/** Removes the directory of every generation not in `live` (left by a dead child or server); returns them, sorted. */
+export async function sweepRefGenerations(root, live) {
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const stale = names
+        .map((name) => GENERATION_DIR.exec(name)?.[1])
+        .filter((digits) => digits !== undefined)
+        .map(Number)
+        .filter((generation) => !live.has(generation))
+        .sort((left, right) => left - right);
+    for (const generation of stale)
+        await teardownRefGeneration(root, generation);
+    return stale;
+}
+//# sourceMappingURL=payload-ref-paths.js.map

package/dist/modes/rpc/tool-child/payload-ref.d.ts

@@ -0,0 +1,58 @@
+import { type PayloadRef, type RefControl, type RefNackReason } from "./protocol.ts";
+export type PayloadRefErrorCode = "ref_budget_exceeded" | "ref_rejected" | "ref_not_owned";
+export declare class PayloadRefError extends Error {
+    readonly code: PayloadRefErrorCode;
+    readonly reason: RefNackReason | undefined;
+    constructor(code: PayloadRefErrorCode, message: string, reason?: RefNackReason);
+}
+export interface PayloadRefWriterOptions {
+    root: string;
+    generation: number;
+    budget?: number | undefined;
+    now?: (() => number) | undefined;
+}
+/**
+ * Writer side of an acknowledged payload reference. The writer owns a ref only until the receiver answers:
+ * `ref_ack` transfers ownership (the writer forgets the file and never deletes it), `ref_nack` makes the writer
+ * delete it. Settling the sending operation changes nothing; only generation teardown removes an unanswered ref.
+ */
+export declare class PayloadRefWriter {
+    #private;
+    readonly generation: number;
+    readonly budget: number;
+    constructor(options: PayloadRefWriterOptions);
+    get ownedBytes(): number;
+    create(payload: Uint8Array): Promise<PayloadRef>;
+    /** A `ref_ack` or `ref_nack` from the receiver; an answer for a ref this writer does not hold is ignored. */
+    handle(control: RefControl): Promise<void>;
+    pendingIds(): string[];
+    /** Refs still unanswered after `refAckMs`; reported for liveness handling, never deleted here. */
+    overdue(): string[];
+    teardown(): Promise<void>;
+}
+export interface PayloadRefReaderOptions {
+    root: string;
+    generation: number;
+    budget?: number | undefined;
+    send: (control: RefControl) => void;
+}
+export type RefAcceptance = {
+    ok: true;
+} | {
+    ok: false;
+    reason: RefNackReason;
+};
+/**
+ * Receiver side. `accept` verifies size and sha256 and answers `ref_ack` (taking ownership) or `ref_nack`.
+ * The owner deletes the file when it consumes it; a dead owner's files go with its generation's teardown.
+ */
+export declare class PayloadRefReader {
+    #private;
+    constructor(options: PayloadRefReaderOptions);
+    accept(ref: PayloadRef, signal?: AbortSignal): Promise<RefAcceptance>;
+    /** Answers `ref_nack` for a ref this side will not take, e.g. one whose job was cancelled before it was opened. */
+    refuse(ref: PayloadRef, reason: RefNackReason): void;
+    consume(refId: string): Promise<Uint8Array>;
+    ownedIds(): string[];
+}
+//# sourceMappingURL=payload-ref.d.ts.map