@masons/agent-network 0.5.31 → 0.5.321

package/dist/broker/entry.js

@@ -4,9 +4,13 @@ import { readConfig } from "../config-fs.js";
 import { DEFAULT_API_HOST } from "../platform-client.js";
 import { heartbeatRuntimeEndpoint, registerRuntimeEndpoint, transitionRuntimeEndpointState, unregisterRuntimeEndpoint, } from "../runtime-endpoint-client.js";
 import { startBrokerDaemon } from "./broker-daemon.js";
+import { ClaudeCodeSpawnDriver } from "./claude-code-spawn-driver.js";
+import { CodexSpawnDriverStub } from "./codex-spawn-driver-stub.js";
 import { ConnectorWS } from "./connector-ws.js";
 import { createBrokerLogger } from "./logger.js";
 import { resolveBrokerPaths } from "./paths.js";
+import { createServicesEventClient } from "./services-event-client.js";
+import { SpawnDriverRegistry } from "./spawn-driver.js";
 const DEFAULT_ACCOUNT_ID = "default";
 export async function resolveCredentialsFromFile(filePath, accountId, envApiHost) {
     let raw;
@@ -159,12 +163,49 @@ export async function main() {
         token: creds.token,
     });
     const apiPort = buildApiPort(creds.apiHost, creds.token, logger);
+    const spawnDriverRegistry = new SpawnDriverRegistry();
+    spawnDriverRegistry.register(new ClaudeCodeSpawnDriver());
+    spawnDriverRegistry.register(new CodexSpawnDriverStub());
+    const postControlAck = async (ack) => {
+        const url = `https://${creds.apiHost.replace(/^https?:\/\//, "").replace(/\/+$/, "")}/v1/runtime/control-ack`;
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${creds.token}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(ack),
+            });
+            if (!res.ok) {
+                logger.warn("post_control_ack_non_ok", {
+                    status: res.status,
+                    idempotency_key: ack.idempotency_key,
+                });
+            }
+        }
+        catch (err) {
+            logger.warn("post_control_ack_error", {
+                err: err instanceof Error ? err.message : String(err),
+                idempotency_key: ack.idempotency_key,
+            });
+        }
+    };
     const broker = await startBrokerDaemon({
         paths,
         asNodeId,
         connector,
         apiPort,
         logger,
+        spawnDriverRegistry,
+        postControlAck,
+        servicesEventClientFactory: ({ dispatcher, logger: clientLogger }) => createServicesEventClient({
+            apiHost: creds.apiHost,
+            runtimeKey: creds.token,
+            agentId: creds.accountId,
+            dispatcher,
+            logger: clientLogger,
+        }),
     });
     let shuttingDown = false;
     const handleSignal = (sig) => async () => {

package/dist/broker/ipc-server.d.ts

@@ -8,6 +8,7 @@ export interface IPCServerHandlers {
     reattachEndpoint(endpoint_id: string, plugin_pid: number, ipcWs: WebSocket): Promise<ReattachResponse>;
     listUndispatched(): Promise<UndispatchedListResponse>;
     dispatch(undispatched_id: string, target_endpoint_id: string): Promise<void>;
+    setTaskHint(body: TaskHintBody): Promise<void>;
 }
 export interface ReattachResponse {
     restored: true;
@@ -23,6 +24,12 @@ export interface RegisterEndpointBody {
     tracking_ref?: string;
     session_name?: string;
     task_hint?: string;
+    spawn_token?: string;
+}
+export interface TaskHintBody {
+    endpoint_id: string;
+    plugin_pid: number;
+    task_hint: string;
 }
 export interface RegisterEndpointResponse {
     endpoint_id: string;

package/dist/broker/ipc-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ipc-server.d.ts","sourceRoot":"","sources":["../../src/broker/ipc-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ipc-server.d.ts","sourceRoot":"","sources":["../../src/broker/ipc-server.ts"],"names":[],"mappings":"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"}

package/dist/broker/ipc-server.js

@@ -137,6 +137,26 @@ async function routeHttp(req, res, bearerToken, handlers, logger) {
             sendJson(res, 200, { ok: true });
             return;
         }
+        const taskHintMatch = /^\/v1\/endpoint\/([^/]+)\/task-hint$/.exec(url);
+        if (method === "POST" && taskHintMatch && taskHintMatch[1]) {
+            const endpointId = decodeURIComponent(taskHintMatch[1]);
+            const body = await readJson(req);
+            const pid = typeof body.plugin_pid === "number" ? body.plugin_pid : Number.NaN;
+            if (!Number.isFinite(pid) || pid <= 0) {
+                throw new BrokerHttpError(400, "plugin_pid_invalid", "plugin_pid is required and must be a positive number");
+            }
+            const hint = typeof body.task_hint === "string" ? body.task_hint : undefined;
+            if (hint === undefined) {
+                throw new BrokerHttpError(400, "task_hint_invalid", "task_hint is required and must be a string");
+            }
+            await handlers.setTaskHint({
+                endpoint_id: endpointId,
+                plugin_pid: pid,
+                task_hint: hint,
+            });
+            sendJson(res, 200, { ok: true });
+            return;
+        }
         sendJson(res, 404, { error: "not_found", path: url });
     }
     catch (err) {

package/dist/broker/network-presence.d.ts

@@ -0,0 +1,31 @@
+export declare const DEFAULT_PRESENCE_GRACE_MS: number;
+export type NetworkPresence = "online" | "reconnecting" | "offline";
+export type PresenceEvent = {
+    type: "connector_connected";
+} | {
+    type: "connector_disconnected";
+} | {
+    type: "presence_grace_expired";
+} | {
+    type: "shutdown";
+};
+export type PresenceEffect = {
+    type: "start_grace_timer";
+    deadline_ms: number;
+} | {
+    type: "cancel_grace_timer";
+} | {
+    type: "emit_presence";
+    presence: NetworkPresence;
+    reason: string;
+};
+export interface PresenceTransitionResult {
+    next: NetworkPresence;
+    effects: readonly PresenceEffect[];
+    ignored?: boolean;
+}
+export interface PresenceTransitionOptions {
+    graceMs?: number;
+}
+export declare function transitionPresence(current: NetworkPresence, event: PresenceEvent, opts?: PresenceTransitionOptions): PresenceTransitionResult;
+//# sourceMappingURL=network-presence.d.ts.map

package/dist/broker/network-presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-presence.d.ts","sourceRoot":"","sources":["../../src/broker/network-presence.ts"],"names":[],"mappings":"AA8BA,eAAO,MAAM,yBAAyB,QAAiB,CAAC;AAExD,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,cAAc,GAAG,SAAS,CAAC;AAEpE,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,wBAAwB,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,wBAAwB,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEzB,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAOD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,aAAa,EACpB,IAAI,GAAE,yBAA8B,GACnC,wBAAwB,CAgH1B"}

package/dist/broker/network-presence.js

@@ -0,0 +1,109 @@
+export const DEFAULT_PRESENCE_GRACE_MS = 10 * 60 * 1000;
+export function transitionPresence(current, event, opts = {}) {
+    const graceMs = opts.graceMs ?? DEFAULT_PRESENCE_GRACE_MS;
+    switch (current) {
+        case "offline": {
+            switch (event.type) {
+                case "connector_connected":
+                    return {
+                        next: "online",
+                        effects: [
+                            {
+                                type: "emit_presence",
+                                presence: "online",
+                                reason: "connector_connected",
+                            },
+                        ],
+                    };
+                case "shutdown":
+                    return {
+                        next: "offline",
+                        effects: [
+                            {
+                                type: "emit_presence",
+                                presence: "offline",
+                                reason: "broker_shutdown",
+                            },
+                        ],
+                    };
+                case "connector_disconnected":
+                case "presence_grace_expired":
+                    return { next: "offline", effects: [], ignored: true };
+            }
+            return { next: current, effects: [], ignored: true };
+        }
+        case "online": {
+            switch (event.type) {
+                case "connector_disconnected":
+                    return {
+                        next: "reconnecting",
+                        effects: [
+                            { type: "start_grace_timer", deadline_ms: graceMs },
+                            {
+                                type: "emit_presence",
+                                presence: "reconnecting",
+                                reason: "connector_disconnected",
+                            },
+                        ],
+                    };
+                case "shutdown":
+                    return {
+                        next: "offline",
+                        effects: [
+                            {
+                                type: "emit_presence",
+                                presence: "offline",
+                                reason: "broker_shutdown",
+                            },
+                        ],
+                    };
+                case "connector_connected":
+                case "presence_grace_expired":
+                    return { next: "online", effects: [], ignored: true };
+            }
+            return { next: current, effects: [], ignored: true };
+        }
+        case "reconnecting": {
+            switch (event.type) {
+                case "connector_connected":
+                    return {
+                        next: "online",
+                        effects: [
+                            { type: "cancel_grace_timer" },
+                            {
+                                type: "emit_presence",
+                                presence: "online",
+                                reason: "connector_reconnected",
+                            },
+                        ],
+                    };
+                case "presence_grace_expired":
+                    return {
+                        next: "offline",
+                        effects: [
+                            {
+                                type: "emit_presence",
+                                presence: "offline",
+                                reason: "grace_timeout",
+                            },
+                        ],
+                    };
+                case "shutdown":
+                    return {
+                        next: "offline",
+                        effects: [
+                            { type: "cancel_grace_timer" },
+                            {
+                                type: "emit_presence",
+                                presence: "offline",
+                                reason: "broker_shutdown",
+                            },
+                        ],
+                    };
+                case "connector_disconnected":
+                    return { next: "reconnecting", effects: [], ignored: true };
+            }
+            return { next: current, effects: [], ignored: true };
+        }
+    }
+}

package/dist/broker/received-message-correlation-cache.d.ts

@@ -0,0 +1,23 @@
+export declare const DEFAULT_TTL_MS = 86400000;
+export declare const DEFAULT_CAP_PER_ENDPOINT = 1000;
+export interface ReceivedMessageCorrelationCacheOptions {
+    ttlMs?: number;
+    capPerEndpoint?: number;
+    now?: () => number;
+}
+export type ReplyAwareResolve = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unknown_correlation_id" | "wrong_endpoint" | "ttl_expired";
+};
+export interface ReceivedMessageCorrelationCache {
+    record(endpoint_id: string, correlation_id: string): void;
+    resolve(endpoint_id: string, correlation_id: string): ReplyAwareResolve;
+    size(): number;
+    sizeForEndpoint(endpoint_id: string): number;
+    sweep(now?: number): number;
+    forgetEndpoint(endpoint_id: string): void;
+}
+export declare function createReceivedMessageCorrelationCache(opts?: ReceivedMessageCorrelationCacheOptions): ReceivedMessageCorrelationCache;
+//# sourceMappingURL=received-message-correlation-cache.d.ts.map

package/dist/broker/received-message-correlation-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"received-message-correlation-cache.d.ts","sourceRoot":"","sources":["../../src/broker/received-message-correlation-cache.ts"],"names":[],"mappings":"AA8DA,eAAO,MAAM,cAAc,WAAa,CAAC;AAGzC,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,MAAM,WAAW,sCAAsC;IAErD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,wBAAwB,GAAG,gBAAgB,GAAG,aAAa,CAAC;CACrE,CAAC;AAMN,MAAM,WAAW,+BAA+B;IAa9C,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAQ1D,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAGxE,IAAI,IAAI,MAAM,CAAC;IAGf,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IAQ7C,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAM5B,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,wBAAgB,qCAAqC,CACnD,IAAI,GAAE,sCAA2C,GAChD,+BAA+B,CAgIjC"}

package/dist/broker/received-message-correlation-cache.js

@@ -0,0 +1,114 @@
+export const DEFAULT_TTL_MS = 86_400_000;
+export const DEFAULT_CAP_PER_ENDPOINT = 1000;
+export function createReceivedMessageCorrelationCache(opts = {}) {
+    const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const cap = opts.capPerEndpoint ?? DEFAULT_CAP_PER_ENDPOINT;
+    const clock = opts.now ?? Date.now;
+    if (ttlMs <= 0)
+        throw new Error(`ttlMs must be positive: ${ttlMs}`);
+    if (cap <= 0)
+        throw new Error(`capPerEndpoint must be positive: ${cap}`);
+    const perEndpoint = new Map();
+    const correlationOwner = new Map();
+    const evict = (endpoint_id, correlation_id) => {
+        const inner = perEndpoint.get(endpoint_id);
+        if (!inner)
+            return;
+        inner.delete(correlation_id);
+        if (inner.size === 0)
+            perEndpoint.delete(endpoint_id);
+        if (correlationOwner.get(correlation_id) === endpoint_id) {
+            correlationOwner.delete(correlation_id);
+        }
+    };
+    return {
+        record(endpoint_id, correlation_id) {
+            const priorOwner = correlationOwner.get(correlation_id);
+            if (priorOwner && priorOwner !== endpoint_id) {
+                const priorInner = perEndpoint.get(priorOwner);
+                priorInner?.delete(correlation_id);
+                if (priorInner && priorInner.size === 0) {
+                    perEndpoint.delete(priorOwner);
+                }
+            }
+            let inner = perEndpoint.get(endpoint_id);
+            if (!inner) {
+                inner = new Map();
+                perEndpoint.set(endpoint_id, inner);
+            }
+            inner.delete(correlation_id);
+            inner.set(correlation_id, { received_at: clock() });
+            correlationOwner.set(correlation_id, endpoint_id);
+            while (inner.size > cap) {
+                const oldestKey = inner.keys().next().value;
+                if (oldestKey === undefined)
+                    break;
+                inner.delete(oldestKey);
+                if (correlationOwner.get(oldestKey) === endpoint_id) {
+                    correlationOwner.delete(oldestKey);
+                }
+            }
+        },
+        resolve(endpoint_id, correlation_id) {
+            const owner = correlationOwner.get(correlation_id);
+            if (!owner) {
+                return { ok: false, reason: "unknown_correlation_id" };
+            }
+            if (owner !== endpoint_id) {
+                return { ok: false, reason: "wrong_endpoint" };
+            }
+            const inner = perEndpoint.get(endpoint_id);
+            const entry = inner?.get(correlation_id);
+            if (!entry) {
+                correlationOwner.delete(correlation_id);
+                return { ok: false, reason: "unknown_correlation_id" };
+            }
+            if (clock() - entry.received_at >= ttlMs) {
+                evict(endpoint_id, correlation_id);
+                return { ok: false, reason: "ttl_expired" };
+            }
+            return { ok: true };
+        },
+        size() {
+            let total = 0;
+            for (const inner of perEndpoint.values())
+                total += inner.size;
+            return total;
+        },
+        sizeForEndpoint(endpoint_id) {
+            return perEndpoint.get(endpoint_id)?.size ?? 0;
+        },
+        sweep(now = clock()) {
+            let evicted = 0;
+            for (const [endpoint_id, inner] of perEndpoint) {
+                const expired = [];
+                for (const [correlation_id, entry] of inner) {
+                    if (now - entry.received_at >= ttlMs) {
+                        expired.push(correlation_id);
+                    }
+                }
+                for (const correlation_id of expired) {
+                    inner.delete(correlation_id);
+                    if (correlationOwner.get(correlation_id) === endpoint_id) {
+                        correlationOwner.delete(correlation_id);
+                    }
+                    evicted++;
+                }
+                if (inner.size === 0)
+                    perEndpoint.delete(endpoint_id);
+            }
+            return evicted;
+        },
+        forgetEndpoint(endpoint_id) {
+            const inner = perEndpoint.get(endpoint_id);
+            if (!inner)
+                return;
+            for (const correlation_id of inner.keys()) {
+                if (correlationOwner.get(correlation_id) === endpoint_id) {
+                    correlationOwner.delete(correlation_id);
+                }
+            }
+            perEndpoint.delete(endpoint_id);
+        },
+    };
+}

package/dist/broker/services-event-client.d.ts

@@ -0,0 +1,21 @@
+import type { ControlEventDispatcher } from "./control-event-dispatcher.js";
+import type { BrokerLogger } from "./logger.js";
+export declare const DEFAULT_BACKOFF_INITIAL_MS = 1000;
+export declare const DEFAULT_BACKOFF_MAX_MS = 30000;
+export interface ServicesEventClientOptions {
+    apiHost: string;
+    runtimeKey: string;
+    agentId: string;
+    dispatcher: ControlEventDispatcher;
+    logger: BrokerLogger;
+    fetchImpl?: typeof globalThis.fetch;
+    backoffInitialMs?: number;
+    backoffMaxMs?: number;
+}
+export interface ServicesEventClient {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    lastSeenKey(): string | undefined;
+}
+export declare function createServicesEventClient(opts: ServicesEventClientOptions): ServicesEventClient;
+//# sourceMappingURL=services-event-client.d.ts.map

package/dist/broker/services-event-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services-event-client.d.ts","sourceRoot":"","sources":["../../src/broker/services-event-client.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,sBAAsB,EAEvB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAChD,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,MAAM,WAAW,0BAA0B;IAEzC,OAAO,EAAE,MAAM,CAAC;IAEhB,UAAU,EAAE,MAAM,CAAC;IAEnB,OAAO,EAAE,MAAM,CAAC;IAEhB,UAAU,EAAE,sBAAsB,CAAC;IAEnC,MAAM,EAAE,YAAY,CAAC;IAErB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAEpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IASlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,WAAW,IAAI,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,mBAAmB,CAuMrB"}

package/dist/broker/services-event-client.js

@@ -0,0 +1,221 @@
+export const DEFAULT_BACKOFF_INITIAL_MS = 1_000;
+export const DEFAULT_BACKOFF_MAX_MS = 30_000;
+export function createServicesEventClient(opts) {
+    const { dispatcher, logger } = opts;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const backoffInitial = opts.backoffInitialMs ?? DEFAULT_BACKOFF_INITIAL_MS;
+    const backoffMax = opts.backoffMaxMs ?? DEFAULT_BACKOFF_MAX_MS;
+    let stopped = false;
+    let lastEventId;
+    let currentAbort = null;
+    let backoffMs = backoffInitial;
+    let loopPromise = null;
+    let started = false;
+    const baseUrl = makeBaseUrl(opts.apiHost);
+    const subscribeOnce = async () => {
+        const ctrl = new AbortController();
+        currentAbort = ctrl;
+        const url = new URL(`${baseUrl}/runtime/control-events`);
+        url.searchParams.set("agent_id", opts.agentId);
+        const headers = {
+            Authorization: `Bearer ${opts.runtimeKey}`,
+            Accept: "text/event-stream",
+        };
+        if (lastEventId)
+            headers["Last-Event-ID"] = lastEventId;
+        const res = await fetchImpl(url.toString(), {
+            method: "GET",
+            headers,
+            signal: ctrl.signal,
+        });
+        if (!res.ok || !res.body) {
+            throw new Error(`SSE subscribe failed: ${res.status}`);
+        }
+        backoffMs = backoffInitial;
+        const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+        let buffer = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += value.replace(/\r\n?/g, "\n");
+            let sep = buffer.indexOf("\n\n");
+            while (sep >= 0) {
+                const frame = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                await handleFrame(frame).catch((err) => {
+                    logger.warn("sse_frame_error", {
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                });
+                sep = buffer.indexOf("\n\n");
+            }
+        }
+    };
+    const handleFrame = async (frame) => {
+        let id;
+        const dataLines = [];
+        for (const line of frame.split("\n")) {
+            if (line === "" || line.startsWith(":"))
+                continue;
+            const colon = line.indexOf(":");
+            const field = colon === -1 ? line : line.slice(0, colon);
+            let value = colon === -1 ? "" : line.slice(colon + 1);
+            if (value.startsWith(" "))
+                value = value.slice(1);
+            if (field === "id")
+                id = value;
+            else if (field === "data")
+                dataLines.push(value);
+        }
+        if (dataLines.length === 0)
+            return;
+        const data = dataLines.join("\n");
+        if (id)
+            lastEventId = id;
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch {
+            logger.warn("sse_frame_unparseable", { data: data.slice(0, 80) });
+            return;
+        }
+        if (hasIdempotencyKey(parsed) && hasUnsupportedVersion(parsed)) {
+            await postAck({
+                idempotency_key: parsed.idempotency_key,
+                status: "failed",
+                detail: "unsupported_protocol_version",
+            });
+            return;
+        }
+        if (!isControlEvent(parsed)) {
+            if (hasIdempotencyKey(parsed)) {
+                await postAck({
+                    idempotency_key: parsed.idempotency_key,
+                    status: "applied",
+                    detail: "unknown_variant_dropped",
+                });
+            }
+            return;
+        }
+        const outcome = await dispatcher.dispatch(parsed);
+        await postAck(outcomeToAck(parsed.idempotency_key, outcome));
+    };
+    const postAck = async (ack) => {
+        try {
+            const res = await fetchImpl(`${baseUrl}/runtime/control-ack`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${opts.runtimeKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(ack),
+            });
+            if (!res.ok) {
+                logger.warn("ack_post_failed", {
+                    status: res.status,
+                    idempotency_key: ack.idempotency_key,
+                });
+            }
+        }
+        catch (err) {
+            logger.warn("ack_post_error", {
+                err: err instanceof Error ? err.message : String(err),
+                idempotency_key: ack.idempotency_key,
+            });
+        }
+    };
+    const loop = async () => {
+        while (!stopped) {
+            try {
+                await subscribeOnce();
+            }
+            catch (err) {
+                if (stopped)
+                    return;
+                logger.warn("sse_reconnect", {
+                    backoff_ms: backoffMs,
+                    err: err instanceof Error ? err.message : String(err),
+                });
+            }
+            if (stopped)
+                return;
+            await sleep(backoffMs);
+            backoffMs = Math.min(backoffMs * 2, backoffMax);
+        }
+    };
+    return {
+        async start() {
+            if (started)
+                return;
+            started = true;
+            stopped = false;
+            loopPromise = loop();
+        },
+        async stop() {
+            stopped = true;
+            if (currentAbort) {
+                try {
+                    currentAbort.abort();
+                }
+                catch {
+                }
+            }
+            if (loopPromise) {
+                await loopPromise.catch(() => { });
+            }
+        },
+        lastSeenKey() {
+            return lastEventId;
+        },
+    };
+}
+function outcomeToAck(idempotency_key, outcome) {
+    if (outcome.ok) {
+        if (outcome.ack_hint === "received") {
+            return { idempotency_key, status: "received" };
+        }
+        return { idempotency_key, status: "applied" };
+    }
+    return {
+        idempotency_key,
+        status: "failed",
+        detail: outcome.detail,
+    };
+}
+function isControlEvent(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v.version !== 1)
+        return false;
+    if (typeof v.idempotency_key !== "string")
+        return false;
+    if (typeof v.emitted_at !== "number")
+        return false;
+    if (typeof v.type !== "string")
+        return false;
+    return (v.type === "dispatch_undispatched" ||
+        v.type === "spawn_request" ||
+        v.type === "force_unregister");
+}
+function hasIdempotencyKey(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.idempotency_key === "string");
+}
+function hasUnsupportedVersion(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return typeof v.version === "number" && v.version !== 1;
+}
+function makeBaseUrl(apiHost) {
+    const trimmed = apiHost.replace(/\/+$/, "");
+    const origin = /^https?:\/\//.test(trimmed) ? trimmed : `https://${trimmed}`;
+    return `${origin}/v1`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}