agent-embassy 1.7.0 → 1.8.0

package/dist/src/gateway/claude-helper-supervisor.js

@@ -1,537 +1,346 @@
+import { fork } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { BridgeError } from "../errors.js";
-import { createClaudeNativeHelper, } from "./claude-helper-client.js";
-import { isGatewayProvider, } from "./types.js";
-const TERMINAL_DELIVERY_STATES = new Set([
-    "released",
-    "unconfirmed",
-    "denied",
-    "expired",
-    "ambiguous",
-    "completed",
-    "failed",
-    "cancelled",
-]);
-const PUBLIC_ALIAS = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
-const CONVERSATION_ID = /^conv_[A-Za-z0-9_-]{16,64}$/;
-const MAX_RAW_BODY_BYTES = 16 * 1024;
+import { gatewayRegistrationIngressPrefixes, isGatewayProvider } from "./types.js";
+import { assertClaudeNativeHelperIpcSize, CLAUDE_NATIVE_HELPER_MAX_REQUESTS, isClaudeNativeHelperChildMessage, } from "./claude-helper-protocol.js";
+const TIMEOUT = 5_000, CLOSE_TIMEOUT = 2_000;
+const ALIAS = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
+const CONVERSATION = /^conv_[A-Za-z0-9_-]{16,64}$/;
 function fault(code, recoverable = false) {
-    return new BridgeError(code, "The supervised native Claude advertisement could not complete its bounded operation.", recoverable);
+    return new BridgeError(code, "The supervised native Claude helper could not complete its bounded operation.", recoverable);
 }
-function ok(result) {
-    if (!("ok" in result) || result.ok !== true) {
+const id = () => randomBytes(18).toString("base64url");
+function requireOk(result) {
+    if (!("ok" in result) || result.ok !== true)
         throw fault("CLAUDE_NATIVE_HELPER_INVALID_RESPONSE");
+}
+export class ClaudeNativeHelperClient {
+    child;
+    callbacks;
+    pid;
+    registration;
+    generation = "";
+    #pending = new Map();
+    #exit;
+    #resolveExit;
+    #closed = false;
+    #exited = false;
+    constructor(child, registration, callbacks) {
+        this.child = child;
+        this.callbacks = callbacks;
+        if (!Number.isSafeInteger(child.pid) || child.pid <= 0)
+            throw fault("CLAUDE_NATIVE_HELPER_PID_INVALID");
+        this.pid = child.pid;
+        this.registration = registration;
+        this.#exit = new Promise((resolve) => { this.#resolveExit = resolve; });
+        child.on("message", (value) => this.#message(value));
+        child.once("error", () => this.#fail(fault("CLAUDE_NATIVE_HELPER_SPAWN_FAILED")));
+        child.once("exit", (code, signal) => {
+            if (this.#exited)
+                return;
+            this.#exited = true;
+            this.#fail(fault("CLAUDE_NATIVE_HELPER_EXITED"));
+            this.#resolveExit();
+            callbacks.onExit({ code, signal });
+        });
+    }
+    static async start(options) {
+        const child = fork(options.entryPath ?? fileURLToPath(new URL("./claude-helper.js", import.meta.url)), [], {
+            cwd: "/", env: { LANG: "C", LC_ALL: "C", TZ: "UTC" }, execPath: process.execPath,
+            execArgv: [], serialization: "json", stdio: ["ignore", "ignore", "ignore", "ipc"],
+        });
+        const client = new ClaudeNativeHelperClient(child, options.registration, options.callbacks);
+        const init = { protocolVersion: 1, type: "initialize", requestId: id(),
+            runtime: options.runtime, hostId: options.hostId, locale: options.locale, deliveryNotices: options.deliveryNotices,
+            maxPendingMessages: options.maxPendingMessages, registration: options.registration };
+        try {
+            const result = await client.#send(init);
+            if (!("generation" in result))
+                throw fault("CLAUDE_NATIVE_HELPER_INVALID_RESPONSE");
+            client.generation = result.generation;
+            return client;
+        }
+        catch (error) {
+            await client.forceClose();
+            throw error;
+        }
+    }
+    request(command, timeoutMs = TIMEOUT) {
+        return this.#send({ protocolVersion: 1, type: "request", requestId: id(), command }, timeoutMs);
+    }
+    async close() {
+        if (!this.#closed) {
+            try {
+                await this.request({ method: "close" }, CLOSE_TIMEOUT);
+            }
+            catch {
+                this.child.kill("SIGTERM");
+            }
+            this.#closed = true;
+        }
+        await this.#awaitExit();
+    }
+    async forceClose() { this.#closed = true; if (!this.#exited)
+        this.child.kill("SIGTERM"); await this.#awaitExit(); }
+    async #awaitExit() {
+        const timer = setTimeout(() => this.child.kill("SIGKILL"), CLOSE_TIMEOUT);
+        timer.unref();
+        await this.#exit;
+        clearTimeout(timer);
+    }
+    async #send(message, timeoutMs = TIMEOUT) {
+        if (this.#closed || this.#exited || !this.child.connected || this.child.killed)
+            throw fault("CLAUDE_NATIVE_HELPER_UNAVAILABLE", true);
+        if (this.#pending.size >= CLAUDE_NATIVE_HELPER_MAX_REQUESTS)
+            throw fault("CLAUDE_NATIVE_HELPER_REQUEST_CAPACITY", true);
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+            throw fault("CLAUDE_NATIVE_HELPER_TIMEOUT_INVALID");
+        assertClaudeNativeHelperIpcSize(message);
+        const pending = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(message.requestId);
+                reject(fault("CLAUDE_NATIVE_HELPER_REQUEST_TIMEOUT"));
+            }, timeoutMs);
+            timer.unref();
+            this.#pending.set(message.requestId, { resolve, reject, timer });
+        });
+        this.child.send(message, (error) => {
+            if (error === null)
+                return;
+            const entry = this.#pending.get(message.requestId);
+            if (entry) {
+                clearTimeout(entry.timer);
+                this.#pending.delete(message.requestId);
+                entry.reject(fault("CLAUDE_NATIVE_HELPER_IPC_FAILED", true));
+            }
+        });
+        return await pending;
+    }
+    #message(value) {
+        try {
+            assertClaudeNativeHelperIpcSize(value);
+            if (!isClaudeNativeHelperChildMessage(value))
+                throw fault("CLAUDE_NATIVE_HELPER_PROTOCOL_INVALID");
+        }
+        catch (error) {
+            this.#fail(error);
+            this.child.kill("SIGTERM");
+            return;
+        }
+        const message = value;
+        if (message.type === "event") {
+            this.callbacks.onEvent(message.value);
+            return;
+        }
+        const pending = this.#pending.get(message.requestId);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.#pending.delete(message.requestId);
+        if (message.ok)
+            pending.resolve(message.result);
+        else
+            pending.reject(fault(message.error.code, message.error.recoverable));
     }
+    #fail(error) { for (const pending of this.#pending.values()) {
+        clearTimeout(pending.timer);
+        pending.reject(error);
+    } this.#pending.clear(); }
 }
+export const createClaudeNativeHelper = ClaudeNativeHelperClient.start;
 export class ClaudeNativeHelperSupervisor {
-    #identity;
-    #runtime;
-    #locale;
-    #deliveryNotices;
-    #maxPendingMessages;
-    #maxHelpers;
-    #callbacks;
+    options;
+    #helpers = new Map();
+    #receipts = new Map();
+    #preparations = new Set();
     #factory;
-    #helpersByAlias = new Map();
-    #helpersByGeneration = new Map();
-    #receiptOwners = new Map();
-    #pendingDispatches = new Map();
     #closed = false;
     constructor(options) {
-        this.#identity = { ...options.identity };
-        this.#runtime = { ...options.runtime };
-        this.#locale = options.locale;
-        this.#deliveryNotices = options.deliveryNotices;
-        this.#maxPendingMessages = options.maxPendingMessages;
-        this.#maxHelpers = options.maxHelpers;
-        this.#callbacks = options.callbacks;
+        this.options = options;
         this.#factory = options.factory ?? createClaudeNativeHelper;
     }
-    get size() {
-        return this.#helpersByAlias.size;
-    }
+    get size() { return this.#helpers.size; }
     async advertise(input) {
-        this.#assertOpen();
-        if (!isGatewayProvider(input.sourceProvider)) {
+        if (this.#closed)
+            throw fault("CLAUDE_NATIVE_HELPER_SUPERVISOR_CLOSED");
+        if (!isGatewayProvider(input.sourceProvider) || !gatewayRegistrationIngressPrefixes[input.sourceProvider] ||
+            !input.alias.startsWith(gatewayRegistrationIngressPrefixes[input.sourceProvider]))
             throw fault("PROVENANCE_ENVELOPE_INVALID");
-        }
-        const incumbent = this.#helpersByAlias.get(input.alias);
-        if (incumbent !== undefined) {
-            if (incumbent.sourceProvider !== input.sourceProvider) {
+        const old = this.#helpers.get(input.alias);
+        if (old) {
+            if (old.sourceProvider !== input.sourceProvider)
                 throw fault("PROVENANCE_ENVELOPE_INVALID");
-            }
             return;
         }
-        if (this.#helpersByAlias.size >= this.#maxHelpers) {
+        if (this.#helpers.size >= this.options.maxHelpers)
             throw fault("CLAUDE_NATIVE_HELPER_CAPACITY", true);
-        }
-        let record;
+        let helper, earlyExit = false;
         const buffered = [];
-        let exitedBeforeReady = false;
-        const client = await this.#factory({
-            runtime: this.#runtime,
-            hostId: "this-mac",
-            locale: this.#locale,
-            deliveryNotices: this.#deliveryNotices,
-            maxPendingMessages: this.#maxPendingMessages,
-            registration: input,
-            callbacks: {
-                onEvent: (event) => {
-                    if (record === undefined)
-                        buffered.push(event);
-                    else
-                        this.#onEvent(record, event);
-                },
-                onExit: () => {
-                    if (record === undefined)
-                        exitedBeforeReady = true;
-                    else
-                        this.#onExit(record);
-                },
-            },
-        });
-        if (this.#closed || exitedBeforeReady) {
+        const client = await this.#factory({ runtime: this.options.runtime, hostId: "this-mac", locale: this.options.locale,
+            deliveryNotices: this.options.deliveryNotices, maxPendingMessages: this.options.maxPendingMessages, registration: input,
+            callbacks: { onEvent: (event) => helper ? this.#event(helper, event) : buffered.push(event),
+                onExit: () => helper ? this.#exit(helper) : earlyExit = true } });
+        if (this.#closed || earlyExit) {
             await client.forceClose().catch(() => undefined);
             throw fault("CLAUDE_NATIVE_HELPER_UNAVAILABLE", true);
         }
-        record = {
-            client,
-            activeAlias: input.alias,
-            sourceProvider: input.sourceProvider,
-            activeGeneration: client.generation,
-            authorizedRoutes: new Map(),
-            closing: false,
-        };
-        this.#helpersByAlias.set(input.alias, record);
-        this.#helpersByGeneration.set(client.generation, record);
+        helper = { client, alias: input.alias, sourceProvider: input.sourceProvider, closing: false };
+        this.#helpers.set(input.alias, helper);
         for (const event of buffered)
-            this.#onEvent(record, event);
-        try {
-            ok(await client.request({
-                method: "resume_generation",
-                generation: client.generation,
-            }));
-        }
-        catch (error) {
-            // The child may have activated before the response was lost. Preserve
-            // exact ownership in the supervisor so ordinary rollback can close it.
-            throw error;
-        }
-    }
-    currentGeneration(alias) {
-        const helper = this.#helpersByAlias.get(alias);
-        if (helper === undefined || helper.closing) {
-            throw fault("CODEX_PEER_GENERATION_MISMATCH");
-        }
-        return helper.activeGeneration;
+            this.#event(helper, event);
     }
     async updateStatus(alias, status) {
-        const helper = this.#helpersByAlias.get(alias);
-        if (helper === undefined || helper.closing)
-            return;
-        ok(await helper.client.request({ method: "update_status", alias, status }));
+        const helper = this.#helpers.get(alias);
+        if (helper && !helper.closing)
+            requireOk(await helper.client.request({ method: "update_status", alias, status }));
     }
     async unadvertise(alias) {
-        const helper = this.#helpersByAlias.get(alias);
-        if (helper === undefined)
+        const helper = this.#helpers.get(alias);
+        if (!helper)
             return;
         helper.closing = true;
         let failure;
         try {
-            ok(await helper.client.request({ method: "unadvertise", alias }));
+            requireOk(await helper.client.request({ method: "unadvertise", alias }));
         }
         catch (error) {
             failure = error;
         }
-        await helper.client.close().catch((error) => {
-            failure ??= error;
-        });
-        this.#removeHelper(helper);
-        if (failure !== undefined)
+        await helper.client.close().catch((error) => { failure ??= error; });
+        this.#remove(helper);
+        if (failure)
             throw failure;
     }
-    async dispatch(input) {
-        if (typeof input.sourceAlias !== "string" ||
-            !PUBLIC_ALIAS.test(input.sourceAlias) ||
-            !isGatewayProvider(input.sourceProvider) ||
-            typeof input.targetAlias !== "string" ||
-            !PUBLIC_ALIAS.test(input.targetAlias) ||
-            typeof input.conversationId !== "string" ||
-            !CONVERSATION_ID.test(input.conversationId) ||
-            typeof input.text !== "string") {
-            return { state: "failed", safeErrorCode: "PROVENANCE_ENVELOPE_INVALID" };
-        }
-        if (Buffer.byteLength(input.text, "utf8") > MAX_RAW_BODY_BYTES) {
-            return {
-                state: "failed",
-                safeErrorCode: "PROVENANCE_ENVELOPE_TOO_LARGE",
-            };
-        }
-        const helper = this.#helpersByAlias.get(input.sourceAlias);
-        if (helper === undefined || helper.closing) {
-            return { state: "failed", safeErrorCode: "CLAUDE_NATIVE_HELPER_UNAVAILABLE" };
-        }
-        if (helper.sourceProvider !== input.sourceProvider) {
-            return { state: "failed", safeErrorCode: "PROVENANCE_ENVELOPE_INVALID" };
-        }
-        if (input.authorization === "selected_route") {
-            if (input.selectedAlias === undefined ||
-                input.stateRoot === undefined) {
-                return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
-            }
-            const authority = `${input.selectedAlias}\0${input.stateRoot}`;
-            if (helper.authorizedRoutes.get(input.binding.routeHandle) !== authority) {
-                ok(await helper.client.request({
-                    method: "authorize_route",
-                    alias: input.selectedAlias,
-                    routeHandle: input.binding.routeHandle,
-                    stateRoot: input.stateRoot,
-                }));
-                helper.authorizedRoutes.set(input.binding.routeHandle, authority);
+    async prepareDispatch(input) {
+        if (!ALIAS.test(input.sourceAlias) || !ALIAS.test(input.targetAlias) || !CONVERSATION.test(input.conversationId) ||
+            !isGatewayProvider(input.sourceProvider))
+            throw fault("PROVENANCE_ENVELOPE_INVALID");
+        if (Buffer.byteLength(input.text) > 16 * 1024)
+            throw fault("PROVENANCE_ENVELOPE_TOO_LARGE");
+        const helper = this.#helpers.get(input.sourceAlias);
+        if (!helper || helper.closing)
+            throw fault("CLAUDE_NATIVE_HELPER_UNAVAILABLE", true);
+        if (helper.sourceProvider !== input.sourceProvider)
+            throw fault("PROVENANCE_ENVELOPE_INVALID");
+        if (input.authorization === "selected_route" && !input.stateRoot)
+            throw fault("CLAUDE_ROUTE_UNAVAILABLE", true);
+        const result = await helper.client.request({ method: "prepare_dispatch", binding: input.binding,
+            authorization: input.authorization, ...(input.authorization === "selected_route" ? { stateRoot: input.stateRoot } : {}),
+            messageId: input.messageId, sourceAlias: helper.alias, sourceProvider: helper.sourceProvider,
+            targetAlias: input.targetAlias, conversationId: input.conversationId, text: input.text,
+            expectsReply: input.expectsReply, deadlineAt: input.deadlineAt,
+            ...(input.progressWatchActive ? { progressWatchActive: true } : {}) }, this.#deadline(input.deadlineAt));
+        if (!("preparationId" in result))
+            throw fault("CLAUDE_NATIVE_HELPER_INVALID_RESPONSE");
+        let state = "prepared";
+        let tracked;
+        const cancel = async () => {
+            if (state !== "prepared")
+                return;
+            state = "consumed";
+            this.#preparations.delete(tracked);
+            try {
+                requireOk(await helper.client.request({ method: "cancel_dispatch", preparationId: result.preparationId }));
             }
-        }
-        this.#pendingDispatches.set(input.messageId, {
-            helper,
-            evidence: "none",
-        });
-        try {
-            const result = await helper.client.request({
-                method: "dispatch",
-                binding: input.binding,
-                authorization: input.authorization,
-                messageId: input.messageId,
-                sourceAlias: helper.activeAlias,
-                sourceProvider: helper.sourceProvider,
-                targetAlias: input.targetAlias,
-                conversationId: input.conversationId,
-                text: input.text,
-                expectsReply: input.expectsReply,
-                deadlineAt: input.deadlineAt,
-                ...(input.progressWatchActive === true
-                    ? { progressWatchActive: true }
-                    : {}),
-            }, Math.max(1, Math.min(60_000, Date.parse(input.deadlineAt) - Date.now())));
-            if (!("state" in result) ||
-                ![
-                    "pending",
-                    "accepted",
-                    "deferred",
-                    "delivered",
-                    "failed",
-                    "ambiguous",
-                    "cancelled",
-                ].includes(String(result.state))) {
-                throw fault("CLAUDE_NATIVE_HELPER_INVALID_RESPONSE");
+            catch (error) {
+                if (!(error instanceof BridgeError) || error.code !== "CLAUDE_NATIVE_PREPARATION_UNKNOWN")
+                    throw error;
             }
-            if (result.state !== "pending")
-                this.#pendingDispatches.delete(input.messageId);
-            return result;
-        }
-        catch (error) {
-            const pending = this.#pendingDispatches.get(input.messageId);
-            if (pending?.evidence === "none")
-                this.#pendingDispatches.delete(input.messageId);
-            throw error;
-        }
-    }
-    async releaseRoute(routeHandle) {
-        const results = await Promise.allSettled([...new Set(this.#helpersByAlias.values())].map(async (helper) => {
-            helper.authorizedRoutes.delete(routeHandle);
-            ok(await helper.client.request({ method: "release_route", routeHandle }));
-        }));
-        const failed = results.find((result) => result.status === "rejected");
-        if (failed !== undefined)
-            throw failed.reason;
+        };
+        const perform = () => {
+            if (state !== "prepared")
+                return Promise.resolve({ state: "failed", safeErrorCode: "CLAUDE_NATIVE_PREPARATION_CONSUMED" });
+            state = "consumed";
+            this.#preparations.delete(tracked);
+            return helper.client.request({ method: "perform_dispatch", preparationId: result.preparationId }, this.#deadline(input.deadlineAt)).then((value) => "state" in value ? value : { state: "ambiguous", safeErrorCode: "CLAUDE_NATIVE_HELPER_INVALID_RESPONSE" }, (error) => error instanceof BridgeError && ["CLAUDE_NATIVE_PREPARATION_UNKNOWN", "CLAUDE_NATIVE_PREPARATION_MISMATCH", "CLAUDE_PEER_PREPARATION_CONSUMED"].includes(error.code)
+                ? { state: "failed", safeErrorCode: error.code } : { state: "ambiguous", safeErrorCode: "CLAUDE_NATIVE_HELPER_PERFORM_UNCERTAIN" });
+        };
+        tracked = { helper, cancel };
+        this.#preparations.add(tracked);
+        return Object.freeze({ frameBytes: result.frameBytes, sha256: result.sha256, perform, cancel });
     }
     async updateInboundStatus(receiptHandle, status, diagnosticCode) {
-        const owner = this.#requireReceipt(receiptHandle);
+        const owner = this.#receipt(receiptHandle);
         try {
-            ok(await owner.helper.client.request({
-                method: "update_inbound_status",
-                receiptHandle: owner.childHandle,
-                status,
-                ...(diagnosticCode === undefined ? {} : { diagnosticCode }),
-            }));
+            requireOk(await owner.helper.client.request({ method: "update_inbound_status",
+                receiptHandle: owner.childHandle, status, ...(diagnosticCode ? { diagnosticCode } : {}) }));
             if (status !== "held")
-                this.#receiptOwners.delete(receiptHandle);
+                this.#receipts.delete(receiptHandle);
         }
         catch (error) {
-            if (status !== "held" &&
-                (!(error instanceof BridgeError) || !error.recoverable)) {
-                this.#receiptOwners.delete(receiptHandle);
-            }
+            if (status !== "held" && (!(error instanceof BridgeError) || !error.recoverable))
+                this.#receipts.delete(receiptHandle);
             throw error;
         }
     }
     async notifyInboundProgress(receiptHandle, progress) {
-        const owner = this.#requireReceipt(receiptHandle);
-        ok(await owner.helper.client.request({
-            method: "notify_inbound_progress",
-            receiptHandle: owner.childHandle,
-            progress,
-        }));
+        const owner = this.#receipt(receiptHandle);
+        requireOk(await owner.helper.client.request({ method: "notify_inbound_progress", receiptHandle: owner.childHandle, progress }));
     }
     async releaseInboundReceipt(receiptHandle) {
-        const owner = this.#receiptOwners.get(receiptHandle);
-        if (owner === undefined)
+        const owner = this.#receipts.get(receiptHandle);
+        if (!owner)
             return false;
-        this.#receiptOwners.delete(receiptHandle);
-        const result = await owner.helper.client.request({
-            method: "release_inbound_receipt",
-            receiptHandle: owner.childHandle,
-        });
-        return "released" in result && result.released === true;
-    }
-    async quiesceAll() {
-        const results = await Promise.allSettled([...new Set(this.#helpersByAlias.values())].map(async (helper) => {
-            ok(await helper.client.request({
-                method: "quiesce_generation",
-                generation: helper.activeGeneration,
-            }));
-        }));
-        const failed = results.find((result) => result.status === "rejected");
-        if (failed !== undefined)
-            throw failed.reason;
-    }
-    async quiesceGeneration(generation) {
-        const helper = this.#requireGeneration(generation);
-        ok(await helper.client.request({ method: "quiesce_generation", generation }));
-    }
-    async observeBarrier(generation) {
-        const helper = this.#requireGeneration(generation);
-        const result = await helper.client.request({ method: "observe_barrier", generation });
-        if (!("clean" in result) || !("generation" in result)) {
-            throw fault("CLAUDE_NATIVE_HELPER_INVALID_RESPONSE");
-        }
-        return result;
-    }
-    async prepareGeneration(input) {
-        const helper = this.#helpersByGeneration.get(input.currentGeneration);
-        if (helper === undefined ||
-            helper.activeGeneration !== input.currentGeneration ||
-            helper.prepared !== undefined) {
-            throw fault("CODEX_PEER_SUCCESSION_CAPACITY");
-        }
-        ok(await helper.client.request({
-            method: "prepare_generation",
-            alias: input.alias,
-            cwd: input.cwd,
-            generation: input.generation,
-        }));
-        helper.prepared = { alias: input.alias, generation: input.generation };
-        this.#helpersByGeneration.set(input.generation, helper);
-    }
-    async publishPrepared(input) {
-        const helper = this.#requireGeneration(input.currentGeneration);
-        if (this.#requireGeneration(input.preparedGeneration) !== helper) {
-            throw fault("CODEX_PEER_SUCCESSION_GENERATION_MISMATCH");
-        }
-        const result = await helper.client.request({
-            method: "publish_prepared",
-            ...input,
-        });
-        if (!("publication" in result)) {
-            throw fault("CLAUDE_NATIVE_HELPER_INVALID_RESPONSE");
-        }
-        return result.publication;
-    }
-    async activatePrepared(generation) {
-        const helper = this.#requireGeneration(generation);
-        const prepared = helper.prepared;
-        if (prepared?.generation !== generation) {
-            throw fault("CODEX_PEER_SUCCESSION_GENERATION_MISMATCH");
-        }
-        const oldAlias = helper.activeAlias;
-        const oldGeneration = helper.activeGeneration;
-        ok(await helper.client.request({ method: "activate_prepared", generation }));
-        this.#helpersByAlias.delete(oldAlias);
-        helper.retiredGeneration = oldGeneration;
-        helper.activeAlias = prepared.alias;
-        helper.activeGeneration = prepared.generation;
-        delete helper.prepared;
-        helper.authorizedRoutes.clear();
-        this.#helpersByAlias.set(helper.activeAlias, helper);
-    }
-    async cleanupPrepared(generation) {
-        const helper = this.#requireGeneration(generation);
-        ok(await helper.client.request({ method: "cleanup_prepared", generation }));
-        if (helper.prepared?.generation === generation)
-            delete helper.prepared;
-        this.#helpersByGeneration.delete(generation);
-    }
-    async resumeGeneration(generation) {
-        const helper = this.#requireGeneration(generation);
-        ok(await helper.client.request({ method: "resume_generation", generation }));
-    }
-    async rollbackPrepared(input) {
-        const helper = this.#requireGeneration(input.resumeGeneration);
-        if (this.#requireGeneration(input.preparedGeneration) !== helper) {
-            throw fault("CODEX_PEER_SUCCESSION_GENERATION_MISMATCH");
-        }
-        ok(await helper.client.request({ method: "rollback_prepared", ...input }));
-        if (helper.prepared?.generation === input.preparedGeneration) {
-            delete helper.prepared;
-        }
-        this.#helpersByGeneration.delete(input.preparedGeneration);
-    }
-    async retireGeneration(input) {
-        const helper = this.#requireGeneration(input.protectedActiveGeneration);
-        if (this.#requireGeneration(input.retiredGeneration) !== helper) {
-            throw fault("CODEX_PEER_SUCCESSION_GENERATION_MISMATCH");
-        }
-        ok(await helper.client.request({ method: "retire_generation", ...input }));
-        if (helper.retiredGeneration === input.retiredGeneration) {
-            delete helper.retiredGeneration;
-        }
-        this.#helpersByGeneration.delete(input.retiredGeneration);
-    }
-    async purgeGenerationReplies(generation) {
-        const helper = this.#requireGeneration(generation);
-        const result = await helper.client.request({
-            method: "purge_generation_replies",
-            generation,
-        });
-        if (!("purged" in result) || !Number.isSafeInteger(result.purged)) {
-            throw fault("CLAUDE_NATIVE_HELPER_INVALID_RESPONSE");
-        }
-        return result.purged;
+        this.#receipts.delete(receiptHandle);
+        const result = await owner.helper.client.request({ method: "release_inbound_receipt", receiptHandle: owner.childHandle });
+        return "released" in result && result.released;
     }
     async close() {
         if (this.#closed)
             return;
         this.#closed = true;
-        const helpers = [...new Set(this.#helpersByAlias.values())];
+        await Promise.allSettled([...this.#preparations].map((item) => item.cancel()));
+        const helpers = [...this.#helpers.values()];
         for (const helper of helpers)
             helper.closing = true;
-        const results = await Promise.allSettled(helpers.map(async (helper) => await helper.client.close()));
+        const results = await Promise.allSettled(helpers.map((helper) => helper.client.close()));
         for (const helper of helpers)
-            this.#removeHelper(helper);
+            this.#remove(helper);
         const failed = results.find((result) => result.status === "rejected");
-        if (failed !== undefined)
+        if (failed)
             throw failed.reason;
     }
-    #onEvent(helper, event) {
+    #event(helper, event) {
         if (helper.closing || this.#closed)
             return;
-        const callbacks = this.#callbacks();
-        if (event.event === "delivery") {
-            const pending = this.#pendingDispatches.get(event.value.messageId);
-            if (pending?.helper !== helper)
-                return;
-            if (event.value.state === "transport_uncertain") {
-                pending.evidence = "transport_uncertain";
-            }
-            else if (event.value.state === "transport_written" ||
-                event.value.state === "held") {
-                pending.evidence = "transport_written";
-            }
-            if (TERMINAL_DELIVERY_STATES.has(event.value.state)) {
-                this.#pendingDispatches.delete(event.value.messageId);
-            }
-            callbacks?.onDelivery({ ...event.value });
-            return;
-        }
-        if (event.event === "claude_reply") {
-            callbacks?.onClaudeReply({
-                endpoint: { ...this.#identity, routeHandle: event.value.routeHandle },
-                text: event.value.text,
-            });
-            return;
-        }
+        const callbacks = this.options.callbacks();
         if (event.event === "protocol_notice") {
-            callbacks?.onProtocolNotice?.({ code: event.value.code });
+            callbacks?.onProtocolNotice?.(event.value);
             return;
         }
-        if (event.value.targetAlias !== helper.activeAlias) {
+        if (event.value.targetAlias !== helper.alias) {
             callbacks?.onProtocolNotice?.({ code: "CLAUDE_NATIVE_HELPER_TARGET_MISMATCH" });
             return;
         }
         let receiptHandle;
-        if (event.value.receiptHandle !== undefined) {
-            if (this.#receiptOwners.size >= this.#maxPendingMessages) {
-                void helper.client
-                    .request({
-                    method: "update_inbound_status",
-                    receiptHandle: event.value.receiptHandle,
-                    status: "expired",
-                    diagnosticCode: "CLAUDE_NATIVE_INGRESS_CAPACITY",
-                })
-                    .catch(() => undefined);
+        if (event.value.receiptHandle) {
+            if (this.#receipts.size >= this.options.maxPendingMessages) {
+                void helper.client.request({ method: "update_inbound_status",
+                    receiptHandle: event.value.receiptHandle, status: "expired", diagnosticCode: "CLAUDE_NATIVE_INGRESS_CAPACITY" }).catch(() => undefined);
                 return;
             }
-            receiptHandle = `nrc_${randomBytes(18).toString("base64url")}`;
-            this.#receiptOwners.set(receiptHandle, {
-                helper,
-                childHandle: event.value.receiptHandle,
-            });
+            receiptHandle = `nrc_${id()}`;
+            this.#receipts.set(receiptHandle, { helper, childHandle: event.value.receiptHandle });
         }
-        callbacks?.onClaudeMessage?.({
-            endpoint: { ...this.#identity, routeHandle: event.value.routeHandle },
-            sourceAlias: event.value.sourceAlias,
-            targetAlias: event.value.targetAlias,
-            text: event.value.text,
-            ...(receiptHandle === undefined ? {} : { receiptHandle }),
-        });
-    }
-    #onExit(helper) {
-        const intentional = helper.closing || this.#closed;
-        if (intentional) {
-            this.#removeHelper(helper);
-            return;
-        }
-        const callbacks = this.#callbacks();
-        for (const [messageId, pending] of this.#pendingDispatches) {
-            if (pending.helper !== helper)
-                continue;
-            this.#pendingDispatches.delete(messageId);
-            callbacks?.onDelivery({
-                messageId,
-                state: pending.evidence === "transport_written"
-                    ? "unconfirmed"
-                    : pending.evidence === "transport_uncertain"
-                        ? "ambiguous"
-                        : "failed",
-                safeErrorCode: "CLAUDE_NATIVE_HELPER_EXITED",
-            });
-        }
-        callbacks?.onProtocolNotice?.({ code: "CLAUDE_NATIVE_HELPER_EXITED" });
-        this.#removeHelper(helper);
+        callbacks?.onClaudeMessage?.({ endpoint: { ...this.options.identity, routeHandle: event.value.routeHandle },
+            sourceAlias: event.value.sourceAlias, targetAlias: event.value.targetAlias, text: event.value.text,
+            ...(receiptHandle ? { receiptHandle } : {}) });
     }
-    #removeHelper(helper) {
-        for (const [alias, candidate] of this.#helpersByAlias) {
-            if (candidate === helper)
-                this.#helpersByAlias.delete(alias);
-        }
-        for (const [generation, candidate] of this.#helpersByGeneration) {
-            if (candidate === helper)
-                this.#helpersByGeneration.delete(generation);
-        }
-        for (const [handle, owner] of this.#receiptOwners) {
+    #exit(helper) { if (!helper.closing && !this.#closed)
+        this.options.callbacks()?.onProtocolNotice?.({ code: "CLAUDE_NATIVE_HELPER_EXITED" }); this.#remove(helper); }
+    #remove(helper) {
+        if (this.#helpers.get(helper.alias) === helper)
+            this.#helpers.delete(helper.alias);
+        for (const [id, owner] of this.#receipts)
             if (owner.helper === helper)
-                this.#receiptOwners.delete(handle);
-        }
-        for (const [messageId, pending] of this.#pendingDispatches) {
-            if (pending.helper === helper)
-                this.#pendingDispatches.delete(messageId);
-        }
-    }
-    #requireGeneration(generation) {
-        const helper = this.#helpersByGeneration.get(generation);
-        if (helper === undefined || helper.closing) {
-            throw fault("CODEX_PEER_SUCCESSION_GENERATION_MISMATCH");
-        }
-        return helper;
-    }
-    #requireReceipt(receiptHandle) {
-        const owner = this.#receiptOwners.get(receiptHandle);
-        if (owner === undefined || owner.helper.closing) {
-            throw fault("CLAUDE_PEER_RECEIPT_UNKNOWN");
-        }
-        return owner;
-    }
-    #assertOpen() {
-        if (this.#closed)
-            throw fault("CLAUDE_NATIVE_HELPER_SUPERVISOR_CLOSED");
+                this.#receipts.delete(id);
+        for (const prepared of [...this.#preparations])
+            if (prepared.helper === helper)
+                this.#preparations.delete(prepared);
     }
+    #receipt(id) { const owner = this.#receipts.get(id); if (!owner || owner.helper.closing)
+        throw fault("CLAUDE_PEER_RECEIPT_UNKNOWN"); return owner; }
+    #deadline(value) { return Math.max(1, Math.min(60_000, Date.parse(value) - Date.now())); }
 }
 //# sourceMappingURL=claude-helper-supervisor.js.map