@code-yeongyu/senpi 2026.10.18 → 2026.10.19

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

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