@code-yeongyu/senpi 2026.10.18 → 2026.10.19

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

@@ -0,0 +1,254 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { encodeFrame, FrameDecoder, ToolChildCodecError } from "./codec.js";
+import { PayloadRefError, PayloadRefReader, PayloadRefWriter } from "./payload-ref.js";
+import { refFilePath, spoolDir, sweepRefGenerations, teardownRefGeneration } from "./payload-ref-paths.js";
+import { packPayload, unpackPayload } from "./payload-wire.js";
+import { TOOL_CHILD_LIMITS } from "./protocol.js";
+const MIB = 1024 * 1024;
+let root = "";
+beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "senpi-tool-child-refs-"));
+});
+afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+});
+const exists = (path) => access(path).then(() => true, () => false);
+function deferred() {
+    let resolve = () => undefined;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+function bytesOf(size, seed = 7) {
+    const bytes = new Uint8Array(size);
+    for (let index = 0; index < size; index += 1)
+        bytes[index] = (index * 31 + seed) & 0xff;
+    return bytes;
+}
+/** A fake transport: every ref control the receiver sends is delivered to the writer, in order. */
+function link(writer, options = {}) {
+    const sent = [];
+    const deliveries = [];
+    const reader = new PayloadRefReader({
+        root,
+        generation: writer.generation,
+        budget: options.budget,
+        send: (control) => {
+            sent.push(control);
+            deliveries.push(writer.handle(control));
+        },
+    });
+    return { reader, sent, delivered: () => Promise.all(deliveries) };
+}
+function received(frame) {
+    const [message] = new FrameDecoder().push(frame);
+    if (message === undefined)
+        throw new Error("no frame decoded");
+    return message;
+}
+/**
+ * The delayed-consumption scenario: the writer sends a 5 MiB `result_ref`, its sender-side operation settles, and the
+ * receiver opens the file only later, behind an event gate. `onSenderSettled` is the writer's settlement behavior.
+ */
+async function delayedConsumption(onSenderSettled) {
+    const writer = new PayloadRefWriter({ root, generation: 1 });
+    const { reader, sent, delivered } = link(writer);
+    const payload = bytesOf(5 * MIB);
+    const ref = await writer.create(payload);
+    const frame = received(encodeFrame({ type: "result_ref", jobId: "j1", ref }));
+    if (frame.type !== "result_ref")
+        throw new Error("expected result_ref");
+    const gate = deferred();
+    const consumer = (async () => {
+        await gate.promise;
+        const acceptance = await reader.accept(frame.ref);
+        await delivered();
+        const existsAfterAck = await exists(refFilePath(root, frame.ref));
+        const bytes = acceptance.ok ? await reader.consume(frame.ref.refId) : undefined;
+        return { acceptance, existsAfterAck, bytes };
+    })();
+    await onSenderSettled(ref);
+    const existsAfterSettlement = await exists(refFilePath(root, ref));
+    gate.resolve();
+    const consumed = await consumer;
+    return {
+        existsAfterSettlement,
+        ...consumed,
+        sha256Verified: consumed.bytes !== undefined && createHash("sha256").update(consumed.bytes).digest("hex") === ref.sha256,
+        sent,
+        writerPending: writer.pendingIds(),
+        existsAfterConsume: await exists(refFilePath(root, ref)),
+    };
+}
+const meetsOwnershipTransfer = (result) => result.existsAfterSettlement &&
+    result.acceptance.ok &&
+    result.existsAfterAck &&
+    result.sha256Verified &&
+    result.sent.length === 1 &&
+    result.sent[0]?.type === "ref_ack" &&
+    result.writerPending.length === 0 &&
+    !result.existsAfterConsume;
+describe("payload ref lifetime", () => {
+    it("delayed consumption: the file outlives sender-side settlement, ownership moves on ref_ack, the owner deletes", async () => {
+        const result = await delayedConsumption(async () => undefined);
+        expect(result.existsAfterSettlement).toBe(true);
+        expect(result.acceptance).toEqual({ ok: true });
+        expect(result.sent).toEqual([{ type: "ref_ack", refId: expect.any(String) }]);
+        expect(result.existsAfterAck).toBe(true);
+        expect(result.sha256Verified).toBe(true);
+        expect(result.existsAfterConsume).toBe(false);
+        expect(meetsOwnershipTransfer(result)).toBe(true);
+    });
+    it("delayed consumption negative control: the old writer-deletes-on-settlement rule is rejected", async () => {
+        const oldRule = (ref) => rm(refFilePath(root, ref), { force: true });
+        const result = await delayedConsumption(oldRule);
+        expect(result.acceptance).toEqual({ ok: false, reason: "missing" });
+        expect(result.sent).toEqual([{ type: "ref_nack", refId: expect.any(String), reason: "missing" }]);
+        expect(meetsOwnershipTransfer(result)).toBe(false);
+    });
+    it("a corrupted file is nacked and the writer deletes it", async () => {
+        const writer = new PayloadRefWriter({ root, generation: 1 });
+        const { reader, sent, delivered } = link(writer);
+        const ref = await writer.create(bytesOf(1024));
+        await writeFile(refFilePath(root, ref), bytesOf(1024, 99));
+        expect(await reader.accept(ref)).toEqual({ ok: false, reason: "corrupt" });
+        await delivered();
+        expect(sent).toEqual([{ type: "ref_nack", refId: ref.refId, reason: "corrupt" }]);
+        expect(await exists(refFilePath(root, ref))).toBe(false);
+        expect(writer.pendingIds()).toEqual([]);
+        expect(writer.ownedBytes).toBe(0);
+    });
+    it("cancellation before ack sends ref_nack{cancelled} and the writer deletes", async () => {
+        const writer = new PayloadRefWriter({ root, generation: 1 });
+        const { reader, sent, delivered } = link(writer);
+        const first = await writer.create(bytesOf(2048));
+        const second = await writer.create(bytesOf(2048));
+        const controller = new AbortController();
+        controller.abort();
+        expect(await reader.accept(first, controller.signal)).toEqual({ ok: false, reason: "cancelled" });
+        reader.refuse(second, "cancelled");
+        await delivered();
+        expect(sent).toEqual([
+            { type: "ref_nack", refId: first.refId, reason: "cancelled" },
+            { type: "ref_nack", refId: second.refId, reason: "cancelled" },
+        ]);
+        expect(await exists(refFilePath(root, first))).toBe(false);
+        expect(await exists(refFilePath(root, second))).toBe(false);
+    });
+    it("receiver death before ack: generation teardown deletes the ref and spool/", async () => {
+        const writer = new PayloadRefWriter({ root, generation: 4 });
+        const ref = await writer.create(bytesOf(4096));
+        received(encodeFrame({ type: "result_ref", jobId: "j1", ref }));
+        await mkdir(spoolDir(root, 4), { recursive: true });
+        await writeFile(join(spoolDir(root, 4), "entry-1.chunk"), "spooled");
+        await writer.teardown();
+        expect(await exists(refFilePath(root, ref))).toBe(false);
+        expect(await exists(spoolDir(root, 4))).toBe(false);
+        expect(writer.pendingIds()).toEqual([]);
+    });
+    it("death before ack of an earlier process: the generation sweep removes every generation that is not live", async () => {
+        const stale = new PayloadRefWriter({ root, generation: 2 });
+        const staleRef = await stale.create(bytesOf(64));
+        await mkdir(spoolDir(root, 2), { recursive: true });
+        const live = new PayloadRefWriter({ root, generation: 3 });
+        const liveRef = await live.create(bytesOf(64));
+        expect(await sweepRefGenerations(root, new Set([3]))).toEqual([2]);
+        expect(await exists(refFilePath(root, staleRef))).toBe(false);
+        expect(await exists(spoolDir(root, 2))).toBe(false);
+        expect(await exists(refFilePath(root, liveRef))).toBe(true);
+    });
+    it("an acked ref whose owner dies is deleted by the teardown sweep", async () => {
+        const writer = new PayloadRefWriter({ root, generation: 1 });
+        const { reader, delivered } = link(writer);
+        const ref = await writer.create(bytesOf(8192));
+        expect(await reader.accept(ref)).toEqual({ ok: true });
+        await delivered();
+        expect(writer.pendingIds()).toEqual([]);
+        expect(reader.ownedIds()).toEqual([ref.refId]);
+        expect(await exists(refFilePath(root, ref))).toBe(true);
+        await teardownRefGeneration(root, 1);
+        expect(await exists(refFilePath(root, ref))).toBe(false);
+    });
+    it("refuses a ref past refsBudget with ref_budget_exceeded, on both sides", async () => {
+        expect(new PayloadRefWriter({ root, generation: 1 }).budget).toBe(TOOL_CHILD_LIMITS.refsBudget);
+        const writer = new PayloadRefWriter({ root, generation: 1, budget: 6 * MIB });
+        const first = await writer.create(bytesOf(5 * MIB));
+        await expect(writer.create(bytesOf(2 * MIB))).rejects.toMatchObject({ code: "ref_budget_exceeded" });
+        await expect(writer.create(bytesOf(2 * MIB))).rejects.toBeInstanceOf(PayloadRefError);
+        expect(await readdir(join(refFilePath(root, first), ".."))).toEqual([first.refId]);
+        const { reader, sent, delivered } = link(writer, { budget: 4 * MIB });
+        expect(await reader.accept(first)).toEqual({ ok: false, reason: "budget" });
+        await delivered();
+        expect(sent).toEqual([{ type: "ref_nack", refId: first.refId, reason: "budget" }]);
+        expect(writer.ownedBytes).toBe(0);
+        await writer.create(bytesOf(5 * MIB));
+    });
+    it("reports an unacknowledged ref overdue after refAckMs without deleting it", async () => {
+        let now = 1_000;
+        const writer = new PayloadRefWriter({ root, generation: 1, now: () => now });
+        const ref = await writer.create(bytesOf(16));
+        now += TOOL_CHILD_LIMITS.refAckMs - 1;
+        expect(writer.overdue()).toEqual([]);
+        now += 1;
+        expect(writer.overdue()).toEqual([ref.refId]);
+        expect(await exists(refFilePath(root, ref))).toBe(true);
+    });
+});
+describe("payloads above the reference threshold, in both directions", () => {
+    it("a 17 MiB host_call.args (child -> server) round-trips by acknowledged reference", async () => {
+        const childWriter = new PayloadRefWriter({ root, generation: 5 });
+        const { reader: serverReader, sent, delivered } = link(childWriter);
+        const args = { path: "big.txt", content: "a".repeat(17 * MIB) };
+        const inlineAttempt = () => encodeFrame({ type: "host_call", callId: "c1", jobId: "j1", tool: "write", args });
+        expect(inlineAttempt).toThrow(ToolChildCodecError);
+        const packed = await packPayload(args, childWriter);
+        if (packed.inline)
+            throw new Error("17 MiB args must move by reference");
+        const frame = received(encodeFrame({ type: "host_call", callId: "c1", jobId: "j1", tool: "write", argsRef: packed.ref }));
+        if (frame.type !== "host_call" || frame.argsRef === undefined)
+            throw new Error("expected host_call with argsRef");
+        expect(await unpackPayload(frame.argsRef, serverReader)).toEqual(args);
+        await delivered();
+        expect(sent).toEqual([{ type: "ref_ack", refId: packed.ref.refId }]);
+        expect(await exists(refFilePath(root, packed.ref))).toBe(false);
+        expect(childWriter.pendingIds()).toEqual([]);
+    });
+    it("a 20 MiB host_reply.value (server -> child) round-trips by acknowledged reference", async () => {
+        const serverWriter = new PayloadRefWriter({ root, generation: 5 });
+        const { reader: childReader, sent, delivered } = link(serverWriter);
+        const value = "v".repeat(20 * MIB);
+        const packed = await packPayload(value, serverWriter);
+        if (packed.inline)
+            throw new Error("20 MiB value must move by reference");
+        const frame = received(encodeFrame({ type: "host_reply", callId: "c1", valueRef: packed.ref }));
+        if (frame.type !== "host_reply" || frame.valueRef === undefined)
+            throw new Error("expected host_reply with valueRef");
+        expect(await unpackPayload(frame.valueRef, childReader)).toEqual(value);
+        await delivered();
+        expect(sent).toEqual([{ type: "ref_ack", refId: packed.ref.refId }]);
+        expect(await exists(refFilePath(root, packed.ref))).toBe(false);
+    });
+    it("keeps a payload at or below REF_THRESHOLD inline and writes no file", async () => {
+        const writer = new PayloadRefWriter({ root, generation: 1 });
+        expect(await packPayload({ small: true }, writer)).toEqual({ inline: true, value: { small: true } });
+        expect(await exists(join(root, "gen-1"))).toBe(false);
+    });
+    it("unpackPayload rejects a ref it had to nack", async () => {
+        const writer = new PayloadRefWriter({ root, generation: 1 });
+        const { reader } = link(writer);
+        const packed = await packPayload("x".repeat(TOOL_CHILD_LIMITS.REF_THRESHOLD + 1), writer);
+        if (packed.inline)
+            throw new Error("expected a ref");
+        await rm(refFilePath(root, packed.ref));
+        await expect(unpackPayload(packed.ref, reader)).rejects.toMatchObject({
+            code: "ref_rejected",
+            reason: "missing",
+        });
+    });
+});
+//# sourceMappingURL=payload-ref.test.js.map

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

@@ -0,0 +1,13 @@
+import { type PayloadRefReader, type PayloadRefWriter } from "./payload-ref.ts";
+import { type PayloadRef } from "./protocol.ts";
+export type PackedPayload = {
+    inline: true;
+    value: unknown;
+} | {
+    inline: false;
+    ref: PayloadRef;
+};
+/** Inline at or below `REF_THRESHOLD` JSON bytes; above it, by acknowledged reference. Same rule in both directions. */
+export declare function packPayload(value: unknown, writer: PayloadRefWriter): Promise<PackedPayload>;
+export declare function unpackPayload(ref: PayloadRef, reader: PayloadRefReader, signal?: AbortSignal): Promise<unknown>;
+//# sourceMappingURL=payload-wire.d.ts.map

package/dist/modes/rpc/tool-child/payload-wire.js

@@ -0,0 +1,22 @@
+import { PayloadRefError } from "./payload-ref.js";
+import { TOOL_CHILD_LIMITS } from "./protocol.js";
+/** Inline at or below `REF_THRESHOLD` JSON bytes; above it, by acknowledged reference. Same rule in both directions. */
+export async function packPayload(value, writer) {
+    // `undefined` stringifies to nothing (JSON.stringify returns undefined), which no decoder accepts; the explicit
+    // null is the encoding the peer's guard takes (senpi#3569 review).
+    const normalized = value === undefined ? null : value;
+    const json = JSON.stringify(normalized);
+    if (json === undefined || Buffer.byteLength(json, "utf8") <= TOOL_CHILD_LIMITS.REF_THRESHOLD) {
+        return { inline: true, value: normalized };
+    }
+    return { inline: false, ref: await writer.create(Buffer.from(json, "utf8")) };
+}
+export async function unpackPayload(ref, reader, signal) {
+    const acceptance = await reader.accept(ref, signal);
+    if (!acceptance.ok) {
+        throw new PayloadRefError("ref_rejected", `ref ${ref.refId} was refused (${acceptance.reason})`, acceptance.reason);
+    }
+    const bytes = await reader.consume(ref.refId);
+    return JSON.parse(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("utf8"));
+}
+//# sourceMappingURL=payload-wire.js.map

package/dist/modes/rpc/tool-child/protocol-guard.d.ts

@@ -0,0 +1,9 @@
+import { type ToolChildMessage } from "./protocol.ts";
+export declare const TOOL_CHILD_MESSAGE_TYPES: readonly string[];
+export declare const isRefId: (value: unknown) => value is string;
+/**
+ * Boundary check for a decoded frame: a known `type`, every required field of the right kind, no unknown field.
+ * An unknown field is refused rather than ignored, so a `trace` frame can never smuggle a result, proof or tick.
+ */
+export declare function isToolChildMessage(value: unknown): value is ToolChildMessage;
+//# sourceMappingURL=protocol-guard.d.ts.map

package/dist/modes/rpc/tool-child/protocol-guard.js

@@ -0,0 +1,128 @@
+import { LAUNCH_APIS, LAUNCH_CONTAINMENTS, LAUNCH_LIFETIMES, LAUNCH_ORIGINS, REF_NACK_REASONS, TRACE_RESERVED_KEYS, } from "./protocol.js";
+const req = (kind) => ({ kind });
+const opt = (kind) => ({ kind, optional: true });
+const SHAPES = {
+    hello_ack: { generation: req("number") },
+    job: {
+        jobId: req("string"),
+        kind: req("string"),
+        parentJobId: opt("string"),
+        args: opt("json"),
+        argsRef: opt("ref"),
+    },
+    cancel: { jobId: req("string") },
+    host_reply: { callId: req("string"), value: opt("json"), valueRef: opt("ref"), error: opt("string") },
+    host_call_refused: { callId: req("string"), code: req("string") },
+    launch_ack: { launchId: req("string") },
+    wake_ack: { wakeId: req("string") },
+    slot_query: { launchId: req("string") },
+    shutdown: {},
+    hello: { generation: req("number"), pid: req("number"), protocol: req("number") },
+    heartbeat: { seq: req("number") },
+    result: { jobId: req("string"), value: req("json") },
+    result_ref: { jobId: req("string"), ref: req("ref") },
+    job_error: { jobId: req("string"), code: req("string"), message: req("string") },
+    job_refused: { jobId: req("string"), code: req("string") },
+    host_call: {
+        callId: req("string"),
+        jobId: req("string"),
+        tool: req("string"),
+        args: opt("json"),
+        argsRef: opt("ref"),
+    },
+    launch: {
+        launchId: req("string"),
+        jobId: req("string"),
+        origin: req(LAUNCH_ORIGINS),
+        api: req(LAUNCH_APIS),
+        containment: req(LAUNCH_CONTAINMENTS),
+        lifetime: req(LAUNCH_LIFETIMES),
+        pid: opt("number"),
+        pgid: opt("number"),
+    },
+    launch_proof: { launchId: req("string"), ackTick: req("number"), invokeTick: req("number") },
+    launch_done: { launchId: req("string"), exitCode: opt("number"), signal: opt("string") },
+    command_started: {
+        launchId: req("string"),
+        pid: req("number"),
+        startedAtMs: req("number"),
+        creatorInJob: req("boolean"),
+        breakaway: req("boolean"),
+    },
+    slot_state: {
+        launchId: req("string"),
+        ackTick: req("number|null"),
+        invokeTick: req("number|null"),
+        invocations: req("number"),
+    },
+    wake: { wakeId: req("string"), source: req("string"), bytes: req("number") },
+    batch: { jobId: req("string"), entries: req("entries"), done: req("boolean") },
+    trace: { atMs: req("number"), event: req("string"), detail: opt("detail") },
+    ref_ack: { refId: req("string") },
+    ref_nack: { refId: req("string"), reason: req(REF_NACK_REASONS) },
+};
+export const TOOL_CHILD_MESSAGE_TYPES = Object.keys(SHAPES);
+const REF_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const RESERVED = new Set(TRACE_RESERVED_KEYS);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isCount = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+export const isRefId = (value) => typeof value === "string" && REF_ID.test(value);
+function isPayloadRef(value) {
+    return (isRecord(value) &&
+        isRefId(value.refId) &&
+        isCount(value.generation) &&
+        isCount(value.bytes) &&
+        typeof value.sha256 === "string" &&
+        SHA256.test(value.sha256));
+}
+function isEntryMeta(value) {
+    return (isRecord(value) &&
+        typeof value.id === "string" &&
+        (value.parentId === null || typeof value.parentId === "string") &&
+        isCount(value.lineOffset) &&
+        isCount(value.lineBytes) &&
+        Number.isSafeInteger(value.lineDelta));
+}
+function isTraceDetail(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.entries(value).every(([key, item]) => !RESERVED.has(key) && (typeof item === "string" || typeof item === "number" || typeof item === "boolean"));
+}
+function matches(kind, value) {
+    if (typeof kind !== "string")
+        return typeof value === "string" && kind.includes(value);
+    switch (kind) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "json":
+            return value !== undefined;
+        case "ref":
+            return isPayloadRef(value);
+        case "entries":
+            return Array.isArray(value) && value.every(isEntryMeta);
+        case "detail":
+            return isTraceDetail(value);
+        case "number|null":
+            return value === null || (typeof value === "number" && Number.isFinite(value));
+    }
+}
+const isMessageType = (value) => typeof value === "string" && Object.hasOwn(SHAPES, value);
+/**
+ * Boundary check for a decoded frame: a known `type`, every required field of the right kind, no unknown field.
+ * An unknown field is refused rather than ignored, so a `trace` frame can never smuggle a result, proof or tick.
+ */
+export function isToolChildMessage(value) {
+    if (!isRecord(value) || !isMessageType(value.type))
+        return false;
+    const rules = SHAPES[value.type];
+    for (const key of Object.keys(value))
+        if (key !== "type" && !Object.hasOwn(rules, key))
+            return false;
+    return Object.entries(rules).every(([key, rule]) => value[key] === undefined ? rule.optional === true : matches(rule.kind, value[key]));
+}
+//# sourceMappingURL=protocol-guard.js.map

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

@@ -0,0 +1,192 @@
+/**
+ * Wire vocabulary between the server and a session's tool child (senpi#3566).
+ *
+ * Every frame crosses the private channel as one length-prefixed binary frame (`codec.ts`), never as NDJSON. Payloads
+ * above `REF_THRESHOLD` never travel inline: they move as an acknowledged `PayloadRef` (`payload-ref.ts`) in either
+ * direction. `trace` is the only lossy frame class; it never carries a job result, a launch proof or a tick.
+ */
+export declare const TOOL_CHILD_LIMITS: {
+    /** Largest encoded frame body, in bytes; a larger length header is refused before its body is allocated. */
+    readonly frameBytes: number;
+    /** Ordinary jobs one child runs at once; nested jobs are bounded by `hostCallCapacity()` instead. */
+    readonly jobs: 32;
+    /** Wake notifications awaiting `wake_ack`, by count and by summed size; the next one waits (never dropped). */
+    readonly wakePending: 64;
+    readonly wakePendingBytes: number;
+    readonly HOST_CALL_ACTIVE: 8;
+    readonly HOST_CALL_WAITING: 256;
+    /** A payload whose JSON exceeds this many bytes moves by reference, never inline. */
+    readonly REF_THRESHOLD: number;
+    /** A ref still unacknowledged after this long is reported overdue (the writer still does not delete it). */
+    readonly refAckMs: 30000;
+    /** Bytes of ref files one side may own at once. */
+    readonly refsBudget: number;
+    readonly tracePerSecond: 1024;
+};
+export declare const LAUNCH_CONTAINMENTS: readonly ["own-group", "inherited", "job", "breakaway"];
+export type LaunchContainment = (typeof LAUNCH_CONTAINMENTS)[number];
+export declare const LAUNCH_LIFETIMES: readonly ["owned", "detached"];
+export type LaunchLifetime = (typeof LAUNCH_LIFETIMES)[number];
+/** Which surface asked for the process. */
+export declare const LAUNCH_ORIGINS: readonly ["tool", "terminal", "user_bash", "interpreter", "monitor", "kernel"];
+export type LaunchOrigin = (typeof LAUNCH_ORIGINS)[number];
+/** The launch API the command came through; group semantics differ per API. */
+export declare const LAUNCH_APIS: readonly ["bun.spawn", "bun.spawnSync", "bun.shell", "cp.spawn", "cp.spawnSync", "cp.execFileSync"];
+export type LaunchApi = (typeof LAUNCH_APIS)[number];
+export declare const REF_NACK_REASONS: readonly ["cancelled", "corrupt", "missing", "budget", "foreign"];
+export type RefNackReason = (typeof REF_NACK_REASONS)[number];
+/** A payload moved through a file in the channel generation's directory. The receiver derives the path itself. */
+export interface PayloadRef {
+    refId: string;
+    /** The channel's child generation; refs of both directions live under that generation's directory. */
+    generation: number;
+    bytes: number;
+    sha256: string;
+}
+/** One parsed transcript entry, with its canonical identity and its exact place in the file. */
+export interface ParsedEntryMeta {
+    id: string;
+    /** Canonical parent from the file line, never from a compacted in-memory mirror. */
+    parentId: string | null;
+    lineOffset: number;
+    lineBytes: number;
+    /** Wire bytes minus line bytes after the canonical transform. */
+    lineDelta: number;
+    entry?: unknown;
+}
+export type TraceDetail = Readonly<Record<string, string | number | boolean>>;
+/** Keys a `trace` detail may never carry: the lossy class never transports results, proofs or ticks. */
+export declare const TRACE_RESERVED_KEYS: readonly ["value", "valueRef", "result", "ref", "args", "argsRef", "ackTick", "invokeTick"];
+export type ServerToChild = {
+    type: "hello_ack";
+    generation: number;
+} | {
+    type: "job";
+    jobId: string;
+    kind: string;
+    parentJobId?: string;
+    args?: unknown;
+    argsRef?: PayloadRef;
+} | {
+    type: "cancel";
+    jobId: string;
+} | {
+    type: "host_reply";
+    callId: string;
+    value?: unknown;
+    valueRef?: PayloadRef;
+    error?: string;
+} | {
+    type: "host_call_refused";
+    callId: string;
+    code: string;
+} | {
+    type: "launch_ack";
+    launchId: string;
+} | {
+    type: "wake_ack";
+    wakeId: string;
+} | {
+    type: "slot_query";
+    launchId: string;
+} | {
+    type: "shutdown";
+};
+export type ChildToServer = {
+    type: "hello";
+    generation: number;
+    pid: number;
+    protocol: number;
+} | {
+    type: "heartbeat";
+    seq: number;
+} | {
+    type: "result";
+    jobId: string;
+    value: unknown;
+} | {
+    type: "result_ref";
+    jobId: string;
+    ref: PayloadRef;
+} | {
+    type: "job_error";
+    jobId: string;
+    code: string;
+    message: string;
+} | {
+    type: "job_refused";
+    jobId: string;
+    code: string;
+} | {
+    type: "host_call";
+    callId: string;
+    jobId: string;
+    tool: string;
+    args?: unknown;
+    argsRef?: PayloadRef;
+} | {
+    type: "launch";
+    launchId: string;
+    jobId: string;
+    origin: LaunchOrigin;
+    api: LaunchApi;
+    containment: LaunchContainment;
+    lifetime: LaunchLifetime;
+    pid?: number;
+    pgid?: number;
+} | {
+    type: "launch_proof";
+    launchId: string;
+    ackTick: number;
+    invokeTick: number;
+} | {
+    type: "launch_done";
+    launchId: string;
+    exitCode?: number;
+    signal?: string;
+} | {
+    type: "command_started";
+    launchId: string;
+    pid: number;
+    startedAtMs: number;
+    creatorInJob: boolean;
+    breakaway: boolean;
+} | {
+    type: "slot_state";
+    launchId: string;
+    ackTick: number | null;
+    invokeTick: number | null;
+    invocations: number;
+} | {
+    type: "wake";
+    wakeId: string;
+    source: string;
+    bytes: number;
+} | {
+    type: "batch";
+    jobId: string;
+    entries: ParsedEntryMeta[];
+    done: boolean;
+} | {
+    type: "trace";
+    atMs: number;
+    event: string;
+    detail?: TraceDetail;
+};
+/** Either side acknowledges or refuses a ref the other side wrote. */
+export type RefControl = {
+    type: "ref_ack";
+    refId: string;
+} | {
+    type: "ref_nack";
+    refId: string;
+    reason: RefNackReason;
+};
+export type ToolChildMessage = ServerToChild | ChildToServer | RefControl;
+export type ToolChildMessageType = ToolChildMessage["type"];
+export type ToolChildMessageOf<T extends ToolChildMessageType> = Extract<ToolChildMessage, {
+    type: T;
+}>;
+/** The only frame class a full budget may drop (counted). */
+export declare const LOSSY_FRAME_TYPES: ReadonlySet<ToolChildMessageType>;
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -0,0 +1,54 @@
+/**
+ * Wire vocabulary between the server and a session's tool child (senpi#3566).
+ *
+ * Every frame crosses the private channel as one length-prefixed binary frame (`codec.ts`), never as NDJSON. Payloads
+ * above `REF_THRESHOLD` never travel inline: they move as an acknowledged `PayloadRef` (`payload-ref.ts`) in either
+ * direction. `trace` is the only lossy frame class; it never carries a job result, a launch proof or a tick.
+ */
+const MIB = 1024 * 1024;
+export const TOOL_CHILD_LIMITS = {
+    /** Largest encoded frame body, in bytes; a larger length header is refused before its body is allocated. */
+    frameBytes: 16 * MIB,
+    /** Ordinary jobs one child runs at once; nested jobs are bounded by `hostCallCapacity()` instead. */
+    jobs: 32,
+    /** Wake notifications awaiting `wake_ack`, by count and by summed size; the next one waits (never dropped). */
+    wakePending: 64,
+    wakePendingBytes: 1 * MIB,
+    HOST_CALL_ACTIVE: 8,
+    HOST_CALL_WAITING: 256,
+    /** A payload whose JSON exceeds this many bytes moves by reference, never inline. */
+    REF_THRESHOLD: 4 * MIB,
+    /** A ref still unacknowledged after this long is reported overdue (the writer still does not delete it). */
+    refAckMs: 30_000,
+    /** Bytes of ref files one side may own at once. */
+    refsBudget: 1024 * MIB,
+    tracePerSecond: 1024,
+};
+export const LAUNCH_CONTAINMENTS = ["own-group", "inherited", "job", "breakaway"];
+export const LAUNCH_LIFETIMES = ["owned", "detached"];
+/** Which surface asked for the process. */
+export const LAUNCH_ORIGINS = ["tool", "terminal", "user_bash", "interpreter", "monitor", "kernel"];
+/** The launch API the command came through; group semantics differ per API. */
+export const LAUNCH_APIS = [
+    "bun.spawn",
+    "bun.spawnSync",
+    "bun.shell",
+    "cp.spawn",
+    "cp.spawnSync",
+    "cp.execFileSync",
+];
+export const REF_NACK_REASONS = ["cancelled", "corrupt", "missing", "budget", "foreign"];
+/** Keys a `trace` detail may never carry: the lossy class never transports results, proofs or ticks. */
+export const TRACE_RESERVED_KEYS = [
+    "value",
+    "valueRef",
+    "result",
+    "ref",
+    "args",
+    "argsRef",
+    "ackTick",
+    "invokeTick",
+];
+/** The only frame class a full budget may drop (counted). */
+export const LOSSY_FRAME_TYPES = new Set(["trace"]);
+//# sourceMappingURL=protocol.js.map