@masons/agent-network 0.5.31 → 0.5.321

package/dist/broker/broker-daemon.d.ts

@@ -1,12 +1,17 @@
+import { spawn as spawnChild } from "node:child_process";
 import type { IncomingMessage } from "node:http";
 import type { ClosedEndpointLookup } from "./closed-endpoint-lookup.js";
 import type { ConnectorWS } from "./connector-ws.js";
 import { type ControlEventDispatcher } from "./control-event-dispatcher.js";
+import type { ControlAck } from "./control-event-types.js";
 import { type EndpointState } from "./endpoint-state-machine.js";
 import type { BrokerLogger } from "./logger.js";
+import { type NetworkPresence } from "./network-presence.js";
 import type { BrokerPaths } from "./paths.js";
 import { type BufferedMessage } from "./reconnecting-buffer.js";
 import type { RuntimeEndpointPort } from "./runtime-endpoint-port.js";
+import type { ServicesEventClient } from "./services-event-client.js";
+import type { SpawnDriverRegistry } from "./spawn-driver.js";
 import { type UndispatchedInbox } from "./undispatched-inbox.js";
 export interface BrokerDaemonOptions {
     paths: BrokerPaths;
@@ -18,6 +23,20 @@ export interface BrokerDaemonOptions {
     inboxCapacity?: number;
     graceMs?: number;
     livenessProbe?: (plugin_pid: number) => boolean;
+    spawnDriverRegistry?: SpawnDriverRegistry;
+    spawnFn?: typeof spawnChild;
+    spawnRateLimitMaxInWindow?: number;
+    spawnRateLimitWindowMs?: number;
+    spawnCorrelationTimeoutMs?: number;
+    presenceGraceMs?: number;
+    retryQueueCapacity?: number;
+    servicesEventClientFactory?: (deps: {
+        dispatcher: ControlEventDispatcher;
+        logger: BrokerLogger;
+    }) => ServicesEventClient;
+    postControlAck?: (ack: ControlAck) => Promise<void>;
+    replyCorrelationTtlMs?: number;
+    replyCorrelationCapPerEndpoint?: number;
 }
 export interface RunningBroker {
     bearerToken: string;
@@ -27,6 +46,10 @@ export interface RunningBroker {
     state(endpoint_id: string): EndpointState | undefined;
     undispatchedInbox: UndispatchedInbox;
     controlEventDispatcher: ControlEventDispatcher;
+    networkPresence(): NetworkPresence;
+    pendingSpawnCount(): number;
+    retryQueueSize(): number;
+    replyCorrelationCacheSize(endpoint_id: string): number;
 }
 export declare function startBrokerDaemon(opts: BrokerDaemonOptions): Promise<RunningBroker>;
 export declare function readPluginPidHeader(req: IncomingMessage): number | null;

package/dist/broker/broker-daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-daemon.d.ts","sourceRoot":"","sources":["../../src/broker/broker-daemon.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,+BAA+B,CAAC;AAQvC,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,6BAA6B,CAAC;AAarC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,WAAW,CAAC;IACvB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,MAAM,EAAE,YAAY,CAAC;IAGrB,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAE5C,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC,YAAY,IAAI,MAAM,CAAC;IAGvB,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAEtD,iBAAiB,EAAE,iBAAiB,CAAC;IAErC,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CAqnBxB;AAGD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAMvE;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"broker-daemon.d.ts","sourceRoot":"","sources":["../../src/broker/broker-daemon.ts"],"names":[],"mappings":"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"}

package/dist/broker/broker-daemon.js

@@ -1,3 +1,4 @@
+import { spawn as spawnChild } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createControlEventDispatcher, } from "./control-event-dispatcher.js";
 import { deleteDiscoveryFile, mintBearerToken, writeDiscoveryFile, } from "./discovery-file.js";
@@ -5,13 +6,22 @@ import { EndpointRegistry } from "./endpoint-registry.js";
 import { DEFAULT_GRACE_MS, transition, } from "./endpoint-state-machine.js";
 import { createGraceTimerManager } from "./grace-timer.js";
 import { BrokerHttpError, pushToPlugin, startIPCServer, } from "./ipc-server.js";
+import { transitionPresence, } from "./network-presence.js";
 import { isPluginAlive as defaultIsPluginAlive } from "./plugin-liveness.js";
+import { createReceivedMessageCorrelationCache, DEFAULT_TTL_MS as DEFAULT_REPLY_CORRELATION_TTL_MS, } from "./received-message-correlation-cache.js";
 import { createReconnectingBufferManager, } from "./reconnecting-buffer.js";
 import { RoutingTable } from "./routing-table.js";
+import { createSpawnCorrelationManager, createSpawnRateLimiter, } from "./spawn-correlation.js";
+import { TASK_HINT_MAX_LENGTH, updateTaskHint } from "./task-hint-handler.js";
+import { createTransitionStateRetryQueue } from "./transition-state-retry-queue.js";
 import { createUndispatchedInbox, } from "./undispatched-inbox.js";
 export async function startBrokerDaemon(opts) {
-    const { paths, asNodeId: _asNodeIdReservedForA3, connector, apiPort, logger, closedEndpointLookup, livenessProbe = defaultIsPluginAlive, } = opts;
+    const { paths, asNodeId: _asNodeIdReservedForA3, connector, apiPort, logger, closedEndpointLookup, livenessProbe = defaultIsPluginAlive, spawnDriverRegistry, spawnFn = spawnChild, servicesEventClientFactory, } = opts;
     const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
+    const presenceGraceMs = opts.presenceGraceMs;
+    const postControlAck = opts.postControlAck ??
+        (async () => {
+        });
     void _asNodeIdReservedForA3;
     logger.info("connecting_to_connector");
     await connector.connect();
@@ -28,14 +38,112 @@ export async function startBrokerDaemon(opts) {
     const reconnectingBuffers = createReconnectingBufferManager(paths.buffersDir);
     const graceTimers = createGraceTimerManager();
     const controlEventDispatcher = createControlEventDispatcher();
+    const spawnCorrelation = createSpawnCorrelationManager({
+        timeoutMs: opts.spawnCorrelationTimeoutMs,
+    });
+    const spawnRateLimiter = createSpawnRateLimiter({
+        maxInWindow: opts.spawnRateLimitMaxInWindow,
+        windowMs: opts.spawnRateLimitWindowMs,
+    });
+    const retryQueue = createTransitionStateRetryQueue({
+        capacity: opts.retryQueueCapacity,
+        onDrop: (dropped) => {
+            logger.warn("transition_state_retry_queue_overflow", {
+                endpoint_id: dropped.endpoint_id,
+                state: dropped.params.state,
+                reason: dropped.params.reason,
+                enqueued_at: dropped.enqueued_at,
+            });
+        },
+    });
+    const replyCorrelationCache = createReceivedMessageCorrelationCache({
+        ttlMs: opts.replyCorrelationTtlMs,
+        capPerEndpoint: opts.replyCorrelationCapPerEndpoint,
+    });
+    const replyCorrelationTtl = opts.replyCorrelationTtlMs ?? DEFAULT_REPLY_CORRELATION_TTL_MS;
+    const replyCorrelationSweepInterval = Math.max(Math.floor(replyCorrelationTtl / 4), 60_000);
+    const replyCorrelationSweepTimer = setInterval(() => {
+        const evicted = replyCorrelationCache.sweep();
+        if (evicted > 0) {
+            logger.info("reply_correlation_cache_sweep", { evicted });
+        }
+    }, replyCorrelationSweepInterval);
+    replyCorrelationSweepTimer.unref?.();
+    const recordInboundCorrelation = (endpoint_id, metadata) => {
+        const c = metadata && typeof metadata.correlation_id === "string"
+            ? metadata.correlation_id
+            : undefined;
+        if (!c)
+            return;
+        replyCorrelationCache.record(endpoint_id, c);
+    };
+    let networkPresence = "offline";
+    let presenceGraceTimer;
+    const applyPresenceTransition = (event) => {
+        const result = transitionPresence(networkPresence, event, {
+            graceMs: presenceGraceMs,
+        });
+        if (result.ignored)
+            return;
+        networkPresence = result.next;
+        for (const effect of result.effects) {
+            switch (effect.type) {
+                case "start_grace_timer":
+                    if (presenceGraceTimer)
+                        clearTimeout(presenceGraceTimer);
+                    presenceGraceTimer = setTimeout(() => {
+                        applyPresenceTransition({ type: "presence_grace_expired" });
+                    }, effect.deadline_ms);
+                    presenceGraceTimer.unref?.();
+                    break;
+                case "cancel_grace_timer":
+                    if (presenceGraceTimer) {
+                        clearTimeout(presenceGraceTimer);
+                        presenceGraceTimer = undefined;
+                    }
+                    break;
+                case "emit_presence":
+                    logger.info("network_presence_changed", {
+                        presence: effect.presence,
+                        reason: effect.reason,
+                    });
+                    if (effect.presence === "online") {
+                        void retryQueue.flush(async (entry) => {
+                            await apiPort.transitionState(entry.endpoint_id, entry.params);
+                        });
+                    }
+                    break;
+            }
+        }
+    };
+    applyPresenceTransition({ type: "connector_connected" });
+    connector.on("connected", () => {
+        applyPresenceTransition({ type: "connector_connected" });
+    });
+    connector.on("disconnected", () => {
+        applyPresenceTransition({ type: "connector_disconnected" });
+    });
     const channels = new Map();
     const wsEndpoints = new WeakMap();
     const displacedWs = new WeakSet();
     const emitTransition = (endpoint_id, state, reason) => {
-        void apiPort.transitionState(endpoint_id, {
+        const params = {
             state,
             reason,
             ts: new Date().toISOString(),
+        };
+        if (networkPresence === "online") {
+            void apiPort.transitionState(endpoint_id, params);
+            return;
+        }
+        const accepted = retryQueue.enqueue(endpoint_id, params);
+        logger.info("transition_state_deferred", {
+            endpoint_id,
+            state,
+            reason,
+            presence: networkPresence,
+            queued: accepted,
+            retry_queue_size: retryQueue.size(),
         });
     };
     const handleTransition = (endpoint_id, event) => {
@@ -89,6 +197,7 @@ export async function startBrokerDaemon(opts) {
                     break;
                 case "remove_from_registry":
                     registry.unregister(endpoint_id);
+                    replyCorrelationCache.forgetEndpoint(endpoint_id);
                     void apiPort.unregister(endpoint_id).catch(() => {
                     });
                     break;
@@ -130,6 +239,7 @@ export async function startBrokerDaemon(opts) {
                 dispatched_by: "passport",
             },
         };
+        recordInboundCorrelation(target.endpoint_id, stamped.metadata);
         if (target.state === "active") {
             pushToPlugin(target.ipc_ws, stamped);
         }
@@ -153,6 +263,84 @@ export async function startBrokerDaemon(opts) {
         });
         return { ok: true };
     });
+    controlEventDispatcher.on("spawn_request", async (event) => {
+        if (!spawnRateLimiter.tryConsume()) {
+            return {
+                ok: false,
+                detail: "spawn_rate_limited",
+            };
+        }
+        if (!spawnDriverRegistry) {
+            return {
+                ok: false,
+                detail: "spawn_driver_registry_not_configured",
+            };
+        }
+        const driver = spawnDriverRegistry.lookup(event.runtime_kind);
+        if (!driver) {
+            return {
+                ok: false,
+                detail: `runtime_kind_unsupported: ${event.runtime_kind}`,
+            };
+        }
+        const avail = await driver.isAvailable();
+        if (!avail.available) {
+            return {
+                ok: false,
+                detail: avail.reason ?? "driver_unavailable",
+            };
+        }
+        const cmd = driver.buildSpawnCommand({
+            prompt: event.prompt,
+            spawn_token: event.idempotency_key,
+        });
+        let child;
+        try {
+            child = spawnFn(cmd.binary, cmd.args, {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+                env: { ...process.env, ...(cmd.env ?? {}) },
+                cwd: cmd.cwd,
+            });
+            child.unref();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                detail: `spawn_failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        spawnCorrelation.track(event.idempotency_key, () => {
+            logger.warn("spawn_correlation_timeout", {
+                spawn_token: event.idempotency_key,
+                runtime_kind: event.runtime_kind,
+            });
+            void postControlAck({
+                idempotency_key: event.idempotency_key,
+                status: "failed",
+                detail: "spawn_correlation_timeout",
+            });
+        });
+        logger.info("spawn_request_initiated", {
+            spawn_token: event.idempotency_key,
+            runtime_kind: event.runtime_kind,
+            pid: child.pid,
+        });
+        return { ok: true, ack_hint: "received" };
+    });
+    controlEventDispatcher.on("force_unregister", async (event) => {
+        const entry = registry.get(event.endpoint_id);
+        if (!entry) {
+            return { ok: true };
+        }
+        logger.info("force_unregister_received", {
+            endpoint_id: event.endpoint_id,
+            reason: event.reason,
+        });
+        handleTransition(event.endpoint_id, { type: "explicit_unregister" });
+        return { ok: true };
+    });
     const handlers = {
         async registerEndpoint(body, _ipcWs) {
             const boundWs = channels.get(body.plugin_pid);
@@ -191,6 +379,25 @@ export async function startBrokerDaemon(opts) {
             }
             bound.add(apiResp.endpoint_id);
             emitTransition(apiResp.endpoint_id, "active", "register");
+            if (typeof body.spawn_token === "string") {
+                const pending = spawnCorrelation.consume(body.spawn_token);
+                if (pending) {
+                    logger.info("endpoint_spawned_correlation_resolved", {
+                        endpoint_id: apiResp.endpoint_id,
+                        spawn_token: body.spawn_token,
+                    });
+                    void postControlAck({
+                        idempotency_key: pending.spawn_token,
+                        status: "applied",
+                    });
+                }
+                else {
+                    logger.warn("endpoint_register_unknown_spawn_token", {
+                        endpoint_id: apiResp.endpoint_id,
+                        spawn_token: body.spawn_token,
+                    });
+                }
+            }
             logger.info("endpoint_registered", {
                 endpoint_id: apiResp.endpoint_id,
                 plugin_pid: body.plugin_pid,
@@ -230,7 +437,27 @@ export async function startBrokerDaemon(opts) {
                 incoming.source_endpoint_id !== body.endpoint_id) {
                 throw new BrokerHttpError(403, "source_endpoint_id_mismatch", "metadata.source_endpoint_id must equal body.endpoint_id");
             }
-            const correlationId = randomUUID();
+            const inReplyTo = typeof incoming.in_reply_to === "string"
+                ? incoming.in_reply_to
+                : undefined;
+            let correlationId;
+            if (inReplyTo) {
+                const resolved = replyCorrelationCache.resolve(body.endpoint_id, inReplyTo);
+                if (resolved.ok) {
+                    correlationId = inReplyTo;
+                }
+                else {
+                    logger.warn("reply_aware_fallback", {
+                        endpoint_id: body.endpoint_id,
+                        in_reply_to: inReplyTo,
+                        reason: resolved.reason,
+                    });
+                    correlationId = randomUUID();
+                }
+            }
+            else {
+                correlationId = randomUUID();
+            }
             entry.correlation_ring.add(correlationId);
             const metadata = {
                 ...incoming,
@@ -291,6 +518,7 @@ export async function startBrokerDaemon(opts) {
                 type: "dispatch_undispatched",
                 version: 1,
                 idempotency_key: `local-${randomUUID()}`,
+                emitted_at: Date.now(),
                 undispatched_id,
                 target_endpoint_id,
             });
@@ -298,6 +526,27 @@ export async function startBrokerDaemon(opts) {
                 throw new BrokerHttpError(400, "dispatch_failed", result.detail ?? "unknown");
             }
         },
+        async setTaskHint(body) {
+            const result = updateTaskHint({ registry }, {
+                endpoint_id: body.endpoint_id,
+                plugin_pid: body.plugin_pid,
+                task_hint: body.task_hint,
+            });
+            if (!result.ok) {
+                const status = result.code === "endpoint_unknown"
+                    ? 404
+                    : result.code === "ownership_mismatch"
+                        ? 403
+                        : 400;
+                throw new BrokerHttpError(status, result.code, result.message);
+            }
+            logger.info("task_hint_updated", {
+                endpoint_id: body.endpoint_id,
+                truncated: result.truncated,
+                length: result.effective.length,
+                max: TASK_HINT_MAX_LENGTH,
+            });
+        },
     };
     const bearerToken = mintBearerToken();
     const ipc = await startIPCServer({
@@ -342,6 +591,7 @@ export async function startBrokerDaemon(opts) {
         const correlation_id = typeof meta.correlation_id === "string" ? meta.correlation_id : undefined;
         const decision = router.route({ target_endpoint_id, correlation_id });
         if (decision.kind === "endpoint") {
+            recordInboundCorrelation(decision.entry.endpoint_id, meta);
             if (decision.entry.state === "active") {
                 pushToPlugin(decision.entry.ipc_ws, {
                     event: "message_received",
@@ -421,13 +671,47 @@ export async function startBrokerDaemon(opts) {
         bearerToken,
     });
     logger.info("discovery_written", { path: paths.discoveryFile });
+    let servicesEventClient;
+    if (servicesEventClientFactory) {
+        servicesEventClient = servicesEventClientFactory({
+            dispatcher: controlEventDispatcher,
+            logger,
+        });
+        try {
+            await servicesEventClient.start();
+        }
+        catch (err) {
+            logger.warn("services_event_client_start_failed", {
+                err: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
     let shutdownStarted = false;
     const shutdown = async (reason) => {
         if (shutdownStarted)
             return;
         shutdownStarted = true;
         logger.info("shutdown_begin", { reason });
+        if (servicesEventClient) {
+            try {
+                await servicesEventClient.stop();
+            }
+            catch {
+            }
+        }
         graceTimers.cancelAll();
+        spawnCorrelation.cancelAll();
+        if (presenceGraceTimer) {
+            clearTimeout(presenceGraceTimer);
+            presenceGraceTimer = undefined;
+        }
+        clearInterval(replyCorrelationSweepTimer);
+        if (retryQueue.size() > 0) {
+            logger.warn("retry_queue_dropped_on_shutdown", {
+                size: retryQueue.size(),
+                reason,
+            });
+        }
         const endpoints = registry.list();
         await Promise.all(endpoints.map(async (entry) => {
             try {
@@ -459,6 +743,10 @@ export async function startBrokerDaemon(opts) {
         state: (endpoint_id) => registry.get(endpoint_id)?.state,
         undispatchedInbox,
         controlEventDispatcher,
+        networkPresence: () => networkPresence,
+        pendingSpawnCount: () => spawnCorrelation.size(),
+        retryQueueSize: () => retryQueue.size(),
+        replyCorrelationCacheSize: (endpoint_id) => replyCorrelationCache.sizeForEndpoint(endpoint_id),
     };
 }
 export function readPluginPidHeader(req) {

package/dist/broker/claude-code-spawn-driver.d.ts

@@ -0,0 +1,14 @@
+import type { DriverAvailability, SpawnCommand, SpawnContext, SpawnDriver } from "./spawn-driver.js";
+export interface ClaudeCodeSpawnDriverOptions {
+    binary?: string;
+    isOnPath?: (binary: string) => boolean;
+}
+export declare class ClaudeCodeSpawnDriver implements SpawnDriver {
+    readonly runtime_kind = "claude-code";
+    private readonly binary;
+    private readonly isOnPath;
+    constructor(opts?: ClaudeCodeSpawnDriverOptions);
+    buildSpawnCommand(ctx: SpawnContext): SpawnCommand;
+    isAvailable(): Promise<DriverAvailability>;
+}
+//# sourceMappingURL=claude-code-spawn-driver.d.ts.map

package/dist/broker/claude-code-spawn-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code-spawn-driver.d.ts","sourceRoot":"","sources":["../../src/broker/claude-code-spawn-driver.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,4BAA4B;IAE3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAMhB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED,qBAAa,qBAAsB,YAAW,WAAW;IACvD,QAAQ,CAAC,YAAY,iBAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;gBAE3C,IAAI,GAAE,4BAAiC;IAKnD,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY;IAS5C,WAAW,IAAI,OAAO,CAAC,kBAAkB,CAAC;CASjD"}

package/dist/broker/claude-code-spawn-driver.js

@@ -0,0 +1,39 @@
+import { execFileSync } from "node:child_process";
+export class ClaudeCodeSpawnDriver {
+    runtime_kind = "claude-code";
+    binary;
+    isOnPath;
+    constructor(opts = {}) {
+        this.binary = opts.binary ?? "claude";
+        this.isOnPath = opts.isOnPath ?? defaultIsOnPath;
+    }
+    buildSpawnCommand(ctx) {
+        return {
+            binary: this.binary,
+            args: ["--bg", ctx.prompt],
+            env: { MASONS_SPAWN_TOKEN: ctx.spawn_token },
+            cwd: ctx.cwd,
+        };
+    }
+    async isAvailable() {
+        if (this.isOnPath(this.binary)) {
+            return { available: true };
+        }
+        return {
+            available: false,
+            reason: `\`${this.binary}\` CLI not found in PATH. Install Claude Code or check $PATH.`,
+        };
+    }
+}
+function defaultIsOnPath(binary) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(binary))
+        return false;
+    const probe = process.platform === "win32" ? "where" : "which";
+    try {
+        execFileSync(probe, [binary], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/broker/codex-spawn-driver-stub.d.ts

@@ -0,0 +1,7 @@
+import type { DriverAvailability, SpawnCommand, SpawnContext, SpawnDriver } from "./spawn-driver.js";
+export declare class CodexSpawnDriverStub implements SpawnDriver {
+    readonly runtime_kind = "codex";
+    buildSpawnCommand(_ctx: SpawnContext): SpawnCommand;
+    isAvailable(): Promise<DriverAvailability>;
+}
+//# sourceMappingURL=codex-spawn-driver-stub.d.ts.map

package/dist/broker/codex-spawn-driver-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-spawn-driver-stub.d.ts","sourceRoot":"","sources":["../../src/broker/codex-spawn-driver-stub.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,oBAAqB,YAAW,WAAW;IACtD,QAAQ,CAAC,YAAY,WAAW;IAEhC,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY;IAW7C,WAAW,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAYjD"}

package/dist/broker/codex-spawn-driver-stub.js

@@ -0,0 +1,13 @@
+export class CodexSpawnDriverStub {
+    runtime_kind = "codex";
+    buildSpawnCommand(_ctx) {
+        throw new Error("CodexSpawnDriverStub.buildSpawnCommand called — broker logic bug; " +
+            "isAvailable() should have short-circuited the spawn before this point");
+    }
+    async isAvailable() {
+        return {
+            available: false,
+            reason: "codex driver not registered on this broker — Codex distribution will ship a SpawnDriver in a future release (broker restart required after install)",
+        };
+    }
+}

package/dist/broker/control-event-dispatcher.d.ts

@@ -2,6 +2,7 @@ import type { ControlEvent } from "./control-event-types.js";
 export declare const DEFAULT_IDEMPOTENCY_RING_SIZE = 1024;
 export type ControlEventOutcome = {
     ok: true;
+    ack_hint?: "received";
 } | {
     ok: false;
     detail: string;

package/dist/broker/control-event-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-event-dispatcher.d.ts","sourceRoot":"","sources":["../../src/broker/control-event-dispatcher.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,CACvE,KAAK,EAAE,CAAC,KACL,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,MAAM,WAAW,sBAAsB;IAErC,EAAE,CAAC,CAAC,SAAS,YAAY,EACvB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EACf,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI,CAAC;IAKR,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAE5D,QAAQ,IAAI,MAAM,CAAC;IAEnB,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3C;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,6BAAkC,GACvC,sBAAsB,CAqDxB"}
+{"version":3,"file":"control-event-dispatcher.d.ts","sourceRoot":"","sources":["../../src/broker/control-event-dispatcher.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAYlD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,CACvE,KAAK,EAAE,CAAC,KACL,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,MAAM,WAAW,sBAAsB;IAErC,EAAE,CAAC,CAAC,SAAS,YAAY,EACvB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EACf,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI,CAAC;IAKR,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAE5D,QAAQ,IAAI,MAAM,CAAC;IAEnB,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3C;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,6BAAkC,GACvC,sBAAsB,CAqDxB"}

package/dist/broker/control-event-types.d.ts

@@ -1,30 +1,28 @@
-export type ControlEvent = DispatchUndispatchedEvent | SpawnRequestEvent | ForceUnregisterEvent;
-export interface DispatchUndispatchedEvent {
-    type: "dispatch_undispatched";
+export interface ControlEventBase {
     version: 1;
     idempotency_key: string;
+    emitted_at: number;
+}
+export type ControlEvent = DispatchUndispatchedEvent | SpawnRequestEvent | ForceUnregisterEvent;
+export interface DispatchUndispatchedEvent extends ControlEventBase {
+    type: "dispatch_undispatched";
     undispatched_id: string;
     target_endpoint_id: string;
 }
-export interface SpawnRequestEvent {
+export interface SpawnRequestEvent extends ControlEventBase {
     type: "spawn_request";
-    version: 1;
-    idempotency_key: string;
-    request_id: string;
     prompt: string;
-    runtime_kind: string;
+    runtime_kind: "claude-code" | "openclaw" | "codex" | "custom";
     origin: "passport-spawn";
 }
-export interface ForceUnregisterEvent {
+export interface ForceUnregisterEvent extends ControlEventBase {
     type: "force_unregister";
-    version: 1;
-    idempotency_key: string;
     endpoint_id: string;
     reason: string;
 }
 export interface ControlAck {
-    request_id: string;
-    status: "ok" | "error";
+    idempotency_key: string;
+    status: "received" | "applied" | "failed";
     detail?: string;
 }
 //# sourceMappingURL=control-event-types.d.ts.map

package/dist/broker/control-event-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-event-types.d.ts","sourceRoot":"","sources":["../../src/broker/control-event-types.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,YAAY,GACpB,yBAAyB,GACzB,iBAAiB,GACjB,oBAAoB,CAAC;AAGzB,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAGD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,CAAC,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAGD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,CAAC,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAGD,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"control-event-types.d.ts","sourceRoot":"","sources":["../../src/broker/control-event-types.ts"],"names":[],"mappings":"AAuCA,MAAM,WAAW,gBAAgB;IAI/B,OAAO,EAAE,CAAC,CAAC;IAWX,eAAe,EAAE,MAAM,CAAC;IAKxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,MAAM,YAAY,GACpB,yBAAyB,GACzB,iBAAiB,GACjB,oBAAoB,CAAC;AAGzB,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,IAAI,EAAE,uBAAuB,CAAC;IAE9B,eAAe,EAAE,MAAM,CAAC;IAExB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAGD,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,IAAI,EAAE,eAAe,CAAC;IAEtB,MAAM,EAAE,MAAM,CAAC;IAMf,YAAY,EAAE,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IAG9D,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAGD,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,IAAI,EAAE,kBAAkB,CAAC;IAEzB,WAAW,EAAE,MAAM,CAAC;IAEpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAwBD,MAAM,WAAW,UAAU;IAEzB,eAAe,EAAE,MAAM,CAAC;IAExB,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAE1C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/broker/entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/broker/entry.ts"],"names":[],"mappings":"AA0EA,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,aAAa,CAAC;AAEpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE,UAAU,mBAAmB;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CA8F9B;AAyDD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,GACnB,mBAAmB,CAkErB;AAYD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAgD1C"}
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/broker/entry.ts"],"names":[],"mappings":"AA6EA,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,aAAa,CAAC;AAEpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAMtE,UAAU,mBAAmB;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CA8F9B;AAyDD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,GACnB,mBAAmB,CAkErB;AAYD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA8F1C"}