@code-yeongyu/senpi 2026.10.18-1 → 2026.10.19

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

@@ -0,0 +1,166 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { refFilePath, teardownRefGeneration } from "./payload-ref-paths.js";
+import { TOOL_CHILD_LIMITS } from "./protocol.js";
+import { isRefId } from "./protocol-guard.js";
+export class PayloadRefError extends Error {
+    constructor(code, message, reason) {
+        super(`${code}: ${message}`);
+        this.name = "PayloadRefError";
+        this.code = code;
+        this.reason = reason;
+    }
+}
+/**
+ * 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 class PayloadRefWriter {
+    #root;
+    #now;
+    #pending = new Map();
+    #ownedBytes = 0;
+    constructor(options) {
+        this.generation = options.generation;
+        this.budget = options.budget ?? TOOL_CHILD_LIMITS.refsBudget;
+        this.#root = options.root;
+        this.#now = options.now ?? Date.now;
+    }
+    get ownedBytes() {
+        return this.#ownedBytes;
+    }
+    async create(payload) {
+        const size = payload.byteLength;
+        if (this.#ownedBytes + size > this.budget) {
+            throw new PayloadRefError("ref_budget_exceeded", `${size} bytes on top of ${this.#ownedBytes} owned exceeds ${this.budget}`);
+        }
+        this.#ownedBytes += size;
+        const ref = {
+            refId: randomBytes(12).toString("hex"),
+            generation: this.generation,
+            bytes: size,
+            sha256: createHash("sha256").update(payload).digest("hex"),
+        };
+        const path = refFilePath(this.#root, ref);
+        try {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            await writeFile(path, payload, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            this.#ownedBytes -= size;
+            await rm(path, { force: true });
+            throw error;
+        }
+        this.#pending.set(ref.refId, { bytes: size, createdAtMs: this.#now() });
+        return ref;
+    }
+    /** A `ref_ack` or `ref_nack` from the receiver; an answer for a ref this writer does not hold is ignored. */
+    async handle(control) {
+        const pending = this.#pending.get(control.refId);
+        if (pending === undefined)
+            return;
+        this.#pending.delete(control.refId);
+        this.#ownedBytes -= pending.bytes;
+        if (control.type === "ref_nack") {
+            await rm(refFilePath(this.#root, { refId: control.refId, generation: this.generation }), { force: true });
+        }
+    }
+    pendingIds() {
+        return [...this.#pending.keys()];
+    }
+    /** Refs still unanswered after `refAckMs`; reported for liveness handling, never deleted here. */
+    overdue() {
+        const deadline = this.#now() - TOOL_CHILD_LIMITS.refAckMs;
+        return [...this.#pending].filter(([, ref]) => ref.createdAtMs <= deadline).map(([refId]) => refId);
+    }
+    async teardown() {
+        this.#pending.clear();
+        this.#ownedBytes = 0;
+        await teardownRefGeneration(this.#root, this.generation);
+    }
+}
+const isMissingFile = (error) => error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+async function hashFile(path, signal) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path)) {
+        if (signal?.aborted)
+            return "cancelled";
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+/**
+ * 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 class PayloadRefReader {
+    #root;
+    #generation;
+    #budget;
+    #send;
+    #owned = new Map();
+    #ownedBytes = 0;
+    constructor(options) {
+        this.#root = options.root;
+        this.#generation = options.generation;
+        this.#budget = options.budget ?? TOOL_CHILD_LIMITS.refsBudget;
+        this.#send = options.send;
+    }
+    async accept(ref, signal) {
+        const reason = await this.#verify(ref, signal);
+        if (reason !== undefined) {
+            this.refuse(ref, reason);
+            return { ok: false, reason };
+        }
+        this.#owned.set(ref.refId, ref);
+        this.#ownedBytes += ref.bytes;
+        this.#send({ type: "ref_ack", refId: ref.refId });
+        return { ok: true };
+    }
+    /** Answers `ref_nack` for a ref this side will not take, e.g. one whose job was cancelled before it was opened. */
+    refuse(ref, reason) {
+        if (this.#owned.has(ref.refId))
+            return;
+        this.#send({ type: "ref_nack", refId: ref.refId, reason });
+    }
+    async consume(refId) {
+        const ref = this.#owned.get(refId);
+        if (ref === undefined)
+            throw new PayloadRefError("ref_not_owned", `ref ${refId} is not owned by this side`);
+        const path = refFilePath(this.#root, ref);
+        const bytes = await readFile(path);
+        await rm(path, { force: true });
+        this.#owned.delete(refId);
+        this.#ownedBytes -= ref.bytes;
+        return bytes;
+    }
+    ownedIds() {
+        return [...this.#owned.keys()];
+    }
+    async #verify(ref, signal) {
+        if (signal?.aborted)
+            return "cancelled";
+        if (ref.generation !== this.#generation || !isRefId(ref.refId) || this.#owned.has(ref.refId))
+            return "foreign";
+        if (this.#ownedBytes + ref.bytes > this.#budget)
+            return "budget";
+        const path = refFilePath(this.#root, ref);
+        try {
+            if ((await stat(path)).size !== ref.bytes)
+                return "corrupt";
+            const digest = await hashFile(path, signal);
+            if (digest === "cancelled")
+                return "cancelled";
+            return digest === ref.sha256 ? undefined : "corrupt";
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return "missing";
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=payload-ref.js.map

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

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

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