@masons/agent-network 0.5.30 → 0.5.32

package/dist/broker/entry.js

@@ -1,13 +1,74 @@
+import { readFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 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";
-async function resolveCredentials(accountId, envApiHost) {
+export async function resolveCredentialsFromFile(filePath, accountId, envApiHost) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new Error(`MASONS_BROKER_CREDENTIALS_FILE points to non-existent path: ${filePath}`);
+        }
+        throw new Error(`failed to read MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath} is not valid JSON: ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: top-level must be an object`);
+    }
+    const accounts = parsed.accounts;
+    if (typeof accounts !== "object" ||
+        accounts === null ||
+        Array.isArray(accounts)) {
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: missing or invalid "accounts" object`);
+    }
+    const accountRaw = accounts[accountId];
+    if (typeof accountRaw !== "object" ||
+        accountRaw === null ||
+        Array.isArray(accountRaw)) {
+        const available = Object.keys(accounts).join(", ") || "<none>";
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: account "${accountId}" not found (available: ${available})`);
+    }
+    const acct = accountRaw;
+    const connectorUrl = typeof acct.connectorUrl === "string" ? acct.connectorUrl : null;
+    const token = typeof acct.token === "string" ? acct.token : null;
+    if (!connectorUrl) {
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: account "${accountId}" missing required field "connectorUrl"`);
+    }
+    if (!token) {
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: account "${accountId}" missing required field "token"`);
+    }
+    if (acct.apiHost !== undefined && typeof acct.apiHost !== "string") {
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: account "${accountId}" optional field "apiHost" must be a string when present`);
+    }
+    if (acct.handle !== undefined && typeof acct.handle !== "string") {
+        throw new Error(`MASONS_BROKER_CREDENTIALS_FILE at ${filePath}: account "${accountId}" optional field "handle" must be a string when present`);
+    }
+    const apiHost = envApiHost ??
+        (typeof acct.apiHost === "string" ? acct.apiHost : DEFAULT_API_HOST);
+    return { accountId, connectorUrl, token, apiHost };
+}
+async function resolveCredentialsFromOpenClawConfig(accountId, envApiHost) {
     const config = await readConfig();
     const channels = config.channels;
     const network = channels?.["agent-network"];
@@ -19,10 +80,18 @@ async function resolveCredentials(accountId, envApiHost) {
     const token = typeof account?.token === "string" ? account.token : null;
     if (!connectorUrl || !token) {
         throw new Error(`agent-network credentials missing for account "${accountId}"; ` +
-            "run setup before lazy-spawning the broker");
+            "run setup before lazy-spawning the broker " +
+            "(or set MASONS_BROKER_CREDENTIALS_FILE for Plugin hosts)");
     }
     return { accountId, connectorUrl, token, apiHost };
 }
+async function resolveCredentials(accountId, envApiHost) {
+    const credentialsFile = process.env.MASONS_BROKER_CREDENTIALS_FILE;
+    if (credentialsFile) {
+        return resolveCredentialsFromFile(credentialsFile, accountId, envApiHost);
+    }
+    return resolveCredentialsFromOpenClawConfig(accountId, envApiHost);
+}
 export function buildApiPort(apiHost, runtimeKey, logger) {
     return {
         async register(params) {
@@ -94,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/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));
+}

package/dist/broker/spawn-correlation.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_SPAWN_TIMEOUT_MS = 30000;
+export declare const DEFAULT_RATE_LIMIT_WINDOW_MS = 30000;
+export declare const DEFAULT_RATE_LIMIT_MAX = 3;
+export interface PendingSpawn {
+    spawn_token: string;
+    expires_at: number;
+}
+export interface SpawnCorrelationOptions {
+    timeoutMs?: number;
+}
+export interface SpawnCorrelationManager {
+    track(spawn_token: string, onTimeout: () => void): void;
+    consume(spawn_token: string): PendingSpawn | undefined;
+    isTracked(spawn_token: string): boolean;
+    size(): number;
+    cancelAll(): void;
+}
+export declare function createSpawnCorrelationManager(opts?: SpawnCorrelationOptions): SpawnCorrelationManager;
+export interface SpawnRateLimiter {
+    tryConsume(now?: number): boolean;
+    count(now?: number): number;
+}
+export interface SpawnRateLimiterOptions {
+    maxInWindow?: number;
+    windowMs?: number;
+}
+export declare function createSpawnRateLimiter(opts?: SpawnRateLimiterOptions): SpawnRateLimiter;
+//# sourceMappingURL=spawn-correlation.d.ts.map

package/dist/broker/spawn-correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-correlation.d.ts","sourceRoot":"","sources":["../../src/broker/spawn-correlation.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,4BAA4B,QAAS,CAAC;AACnD,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IAEpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IAOtC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAMxD,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAEvD,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAExC,IAAI,IAAI,MAAM,CAAC;IAEf,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,GAAE,uBAA4B,GACjC,uBAAuB,CA+CzB;AAOD,MAAM,WAAW,gBAAgB;IAE/B,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,GAAE,uBAA4B,GACjC,gBAAgB,CA0BlB"}