@masons/runtime-broker 0.1.0

package/dist/broker/endpoint-registry.js

@@ -0,0 +1,83 @@
+import { CorrelationRingBuffer } from "./correlation-ring.js";
+export class EndpointRegistry {
+    byId = new Map();
+    register(args) {
+        if (this.byId.has(args.endpoint_id)) {
+            throw new Error(`endpoint_id already registered: ${args.endpoint_id}`);
+        }
+        const entry = {
+            endpoint_id: args.endpoint_id,
+            agent_id: args.agent_id,
+            plugin_pid: args.plugin_pid,
+            ipc_ws: args.ipc_ws,
+            state: "active",
+            state_since: new Date(),
+            display_metadata: args.display_metadata,
+            correlation_ring: new CorrelationRingBuffer(),
+        };
+        this.byId.set(args.endpoint_id, entry);
+        return entry;
+    }
+    get(endpoint_id) {
+        return this.byId.get(endpoint_id);
+    }
+    unregister(endpoint_id) {
+        const entry = this.byId.get(endpoint_id);
+        if (entry)
+            this.byId.delete(endpoint_id);
+        return entry;
+    }
+    markReconnecting(endpoint_id, grace_deadline) {
+        const entry = this.byId.get(endpoint_id);
+        if (!entry) {
+            throw new Error(`unknown endpoint_id: ${endpoint_id}`);
+        }
+        if (entry.state !== "active") {
+            throw new Error(`markReconnecting requires state=active, got state=${entry.state}`);
+        }
+        entry.state = "reconnecting";
+        entry.state_since = new Date();
+        entry.grace_deadline = grace_deadline;
+        return entry;
+    }
+    markActive(endpoint_id, new_ws) {
+        const entry = this.byId.get(endpoint_id);
+        if (!entry) {
+            throw new Error(`unknown endpoint_id: ${endpoint_id}`);
+        }
+        if (entry.state !== "reconnecting") {
+            throw new Error(`markActive requires state=reconnecting, got state=${entry.state}`);
+        }
+        entry.state = "active";
+        entry.state_since = new Date();
+        entry.grace_deadline = undefined;
+        entry.ipc_ws = new_ws;
+        return entry;
+    }
+    preconditionForReattach(endpoint_id, plugin_pid) {
+        const entry = this.byId.get(endpoint_id);
+        if (!entry)
+            return undefined;
+        if (entry.plugin_pid !== plugin_pid)
+            return undefined;
+        if (entry.state !== "reconnecting")
+            return undefined;
+        return entry;
+    }
+    getReattachStatus(endpoint_id, plugin_pid) {
+        const entry = this.byId.get(endpoint_id);
+        if (!entry)
+            return { ok: false, reason: "endpoint_unknown" };
+        if (entry.plugin_pid !== plugin_pid)
+            return { ok: false, reason: "reattach_pid_mismatch" };
+        if (entry.state !== "reconnecting")
+            return { ok: false, reason: "endpoint_not_reconnecting" };
+        return { ok: true, entry };
+    }
+    list() {
+        return Array.from(this.byId.values());
+    }
+    size() {
+        return this.byId.size;
+    }
+}

package/dist/broker/endpoint-state-machine.d.ts

@@ -0,0 +1,40 @@
+export declare const DEFAULT_GRACE_MS: number;
+export type EndpointState = "active" | "reconnecting" | "closed";
+export type TransitionEvent = {
+    type: "register";
+} | {
+    type: "ipc_close";
+    plugin_alive: boolean;
+} | {
+    type: "reattach";
+} | {
+    type: "grace_expired";
+} | {
+    type: "explicit_unregister";
+};
+export type TransitionEffect = {
+    type: "start_grace_timer";
+    deadline_ms: number;
+} | {
+    type: "cancel_grace_timer";
+} | {
+    type: "emit_state";
+    state: EndpointState;
+    reason: string;
+} | {
+    type: "drain_buffer";
+} | {
+    type: "remove_from_registry";
+} | {
+    type: "delete_buffer";
+};
+export interface TransitionResult {
+    next: EndpointState;
+    effects: readonly TransitionEffect[];
+    ignored?: boolean;
+}
+export interface TransitionOptions {
+    graceMs?: number;
+}
+export declare function transition(current: EndpointState, event: TransitionEvent, opts?: TransitionOptions): TransitionResult;
+//# sourceMappingURL=endpoint-state-machine.d.ts.map

package/dist/broker/endpoint-state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-state-machine.d.ts","sourceRoot":"","sources":["../../src/broker/endpoint-state-machine.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEjE,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAOpB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,GAE5C;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAEpB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GAEzB;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAMrC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAEhC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,wBAAgB,UAAU,CACxB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,iBAAsB,GAC3B,gBAAgB,CAiGlB"}

package/dist/broker/endpoint-state-machine.js

@@ -0,0 +1,92 @@
+export const DEFAULT_GRACE_MS = 10 * 60 * 1000;
+export function transition(current, event, opts = {}) {
+    const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
+    switch (current) {
+        case "active": {
+            switch (event.type) {
+                case "ipc_close":
+                    if (event.plugin_alive) {
+                        return {
+                            next: "reconnecting",
+                            effects: [
+                                { type: "start_grace_timer", deadline_ms: graceMs },
+                                {
+                                    type: "emit_state",
+                                    state: "reconnecting",
+                                    reason: "ipc_close",
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        next: "closed",
+                        effects: [
+                            { type: "emit_state", state: "closed", reason: "plugin_exit" },
+                            { type: "delete_buffer" },
+                            { type: "remove_from_registry" },
+                        ],
+                    };
+                case "explicit_unregister":
+                    return {
+                        next: "closed",
+                        effects: [
+                            {
+                                type: "emit_state",
+                                state: "closed",
+                                reason: "explicit_unregister",
+                            },
+                            { type: "delete_buffer" },
+                            { type: "remove_from_registry" },
+                        ],
+                    };
+                case "register":
+                case "reattach":
+                case "grace_expired":
+                    return { next: "active", effects: [], ignored: true };
+            }
+            return { next: current, effects: [], ignored: true };
+        }
+        case "reconnecting": {
+            switch (event.type) {
+                case "reattach":
+                    return {
+                        next: "active",
+                        effects: [
+                            { type: "cancel_grace_timer" },
+                            { type: "drain_buffer" },
+                            { type: "emit_state", state: "active", reason: "reattach" },
+                        ],
+                    };
+                case "grace_expired":
+                    return {
+                        next: "closed",
+                        effects: [
+                            { type: "emit_state", state: "closed", reason: "grace_timeout" },
+                            { type: "delete_buffer" },
+                            { type: "remove_from_registry" },
+                        ],
+                    };
+                case "explicit_unregister":
+                    return {
+                        next: "closed",
+                        effects: [
+                            { type: "cancel_grace_timer" },
+                            {
+                                type: "emit_state",
+                                state: "closed",
+                                reason: "explicit_unregister",
+                            },
+                            { type: "delete_buffer" },
+                            { type: "remove_from_registry" },
+                        ],
+                    };
+                case "ipc_close":
+                case "register":
+                    return { next: "reconnecting", effects: [], ignored: true };
+            }
+            return { next: current, effects: [], ignored: true };
+        }
+        case "closed":
+            return { next: "closed", effects: [], ignored: true };
+    }
+}

package/dist/broker/entry.d.ts

@@ -0,0 +1,13 @@
+import { type BrokerLogger } from "./logger.js";
+import type { RuntimeEndpointPort } from "./runtime-endpoint-port.js";
+interface ResolvedCredentials {
+    accountId: string;
+    connectorUrl: string;
+    token: string;
+    apiHost: string;
+}
+export declare function resolveCredentialsFromFile(filePath: string, accountId: string, envApiHost: string | undefined): Promise<ResolvedCredentials>;
+export declare function buildApiPort(apiHost: string, runtimeKey: string, logger: BrokerLogger): RuntimeEndpointPort;
+export declare function main(): Promise<void>;
+export {};
+//# sourceMappingURL=entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/broker/entry.ts"],"names":[],"mappings":"AA+EA,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;AAwDD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,GACnB,mBAAmB,CAwGrB;AAYD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA8F1C"}

package/dist/broker/entry.js

@@ -0,0 +1,235 @@
+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 { emitRuntimeNetworkPresenceChanged, emitRuntimeUndispatchedChanged, 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;
+    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"];
+    const apiHost = envApiHost ??
+        (typeof network?.apiHost === "string" ? network.apiHost : DEFAULT_API_HOST);
+    const accounts = network?.accounts;
+    const account = accounts?.[accountId];
+    const connectorUrl = typeof account?.connectorUrl === "string" ? account.connectorUrl : null;
+    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 " +
+            "(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) {
+            return registerRuntimeEndpoint({ apiHost }, runtimeKey, params);
+        },
+        async heartbeat(endpointId) {
+            await heartbeatRuntimeEndpoint({ apiHost }, runtimeKey, endpointId);
+        },
+        async unregister(endpointId, asNodeId) {
+            await unregisterRuntimeEndpoint({ apiHost }, runtimeKey, endpointId, asNodeId);
+        },
+        async transitionState(endpointId, params) {
+            try {
+                await transitionRuntimeEndpointState({ apiHost }, runtimeKey, endpointId, params);
+            }
+            catch (err) {
+                const status = errorStatus(err);
+                if (status === 404) {
+                    logger.info("transitionState_404_degraded", {
+                        endpoint_id: endpointId,
+                        state: params.state,
+                        reason: params.reason,
+                        note: "apps/api state endpoint not yet shipped (PR-B1 in flight); state propagation skipped",
+                    });
+                    return;
+                }
+                await sleep(500);
+                try {
+                    await transitionRuntimeEndpointState({ apiHost }, runtimeKey, endpointId, params);
+                }
+                catch (err2) {
+                    logger.warn("transitionState_failed", {
+                        endpoint_id: endpointId,
+                        state: params.state,
+                        reason: params.reason,
+                        err: err2 instanceof Error ? err2.message : String(err2),
+                    });
+                }
+            }
+        },
+        async emitUndispatchedChanged(event) {
+            return emitRuntimeUndispatchedChanged({ apiHost }, runtimeKey, event);
+        },
+        async emitNetworkPresenceChanged(event) {
+            return emitRuntimeNetworkPresenceChanged({ apiHost }, runtimeKey, event);
+        },
+    };
+}
+function errorStatus(err) {
+    if (typeof err !== "object" || err === null)
+        return null;
+    const status = err.status;
+    return typeof status === "number" ? status : null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function main() {
+    const accountId = process.env.MASONS_BROKER_ACCOUNT_ID ?? DEFAULT_ACCOUNT_ID;
+    const envApiHost = process.env.MASONS_BROKER_API_HOST;
+    const userDataOverride = process.env.MASONS_BROKER_USER_DATA;
+    const creds = await resolveCredentials(accountId, envApiHost);
+    const paths = resolveBrokerPaths(creds.accountId, creds.token, {
+        userDataDir: userDataOverride,
+    });
+    const logger = createBrokerLogger(paths.logDir);
+    logger.info("broker_entry_starting", {
+        accountId: creds.accountId,
+        apiHost: creds.apiHost,
+        pid: process.pid,
+    });
+    const asNodeId = creds.accountId;
+    const connector = new ConnectorWS({
+        url: creds.connectorUrl,
+        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 () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info("broker_signal", { sig });
+        await broker.shutdown(`signal:${sig}`);
+        process.exit(0);
+    };
+    process.on("SIGTERM", handleSignal("SIGTERM"));
+    process.on("SIGINT", handleSignal("SIGINT"));
+    logger.info("broker_ready", { ipcUrl: broker.ipcUrl });
+}
+const argvUrl = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === argvUrl) {
+    main().catch((err) => {
+        console.error("broker_entry_fatal", err);
+        process.exit(1);
+    });
+}

package/dist/broker/grace-timer.d.ts

@@ -0,0 +1,9 @@
+export interface GraceTimerManager {
+    start(endpoint_id: string, ms: number, onExpire: () => void): void;
+    cancel(endpoint_id: string): void;
+    has(endpoint_id: string): boolean;
+    cancelAll(): void;
+    active(): readonly string[];
+}
+export declare function createGraceTimerManager(): GraceTimerManager;
+//# sourceMappingURL=grace-timer.d.ts.map

package/dist/broker/grace-timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grace-timer.d.ts","sourceRoot":"","sources":["../../src/broker/grace-timer.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,iBAAiB;IAGhC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAEnE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC,SAAS,IAAI,IAAI,CAAC;IAElB,MAAM,IAAI,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAmC3D"}

package/dist/broker/grace-timer.js

@@ -0,0 +1,34 @@
+export function createGraceTimerManager() {
+    const timers = new Map();
+    return {
+        start(endpoint_id, ms, onExpire) {
+            const existing = timers.get(endpoint_id);
+            if (existing)
+                clearTimeout(existing);
+            const handle = setTimeout(() => {
+                timers.delete(endpoint_id);
+                onExpire();
+            }, ms);
+            handle.unref?.();
+            timers.set(endpoint_id, handle);
+        },
+        cancel(endpoint_id) {
+            const handle = timers.get(endpoint_id);
+            if (handle) {
+                clearTimeout(handle);
+                timers.delete(endpoint_id);
+            }
+        },
+        has(endpoint_id) {
+            return timers.has(endpoint_id);
+        },
+        cancelAll() {
+            for (const [, handle] of timers)
+                clearTimeout(handle);
+            timers.clear();
+        },
+        active() {
+            return Array.from(timers.keys());
+        },
+    };
+}

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

@@ -0,0 +1,79 @@
+import { type RawData, WebSocket } from "ws";
+import type { BrokerLogger } from "./logger.js";
+export interface IPCServerHandlers {
+    registerEndpoint(body: RegisterEndpointBody, ipcWs: WebSocket): Promise<RegisterEndpointResponse>;
+    heartbeatEndpoint(endpoint_id: string): Promise<void>;
+    unregisterEndpoint(endpoint_id: string): Promise<void>;
+    send(body: SendBody): Promise<SendResponse>;
+    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;
+    reconnecting_buffer_count: number;
+}
+export type UndispatchedListResponse = import("./undispatched-inbox.js").UndispatchedMessage[];
+export interface RegisterEndpointBody {
+    agent_id: string;
+    plugin_pid: number;
+    kind: string;
+    started_at?: string;
+    workspace?: string;
+    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;
+}
+export interface SendBody {
+    endpoint_id: string;
+    to: string;
+    content: string;
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+    require_live?: boolean;
+}
+export interface SendResponse {
+    messageId: string;
+    status: string;
+}
+export declare class BrokerHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface IPCServerOptions {
+    bearerToken: string;
+    handlers: IPCServerHandlers;
+    logger: BrokerLogger;
+    onChannelOpened?: (plugin_pid: number, ws: WebSocket) => void;
+    onChannelClosed?: (plugin_pid: number, ws: WebSocket) => void;
+}
+export interface RunningIPCServer {
+    ipcUrl: string;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startIPCServer(opts: IPCServerOptions): Promise<RunningIPCServer>;
+export declare function pushToPlugin(ws: WebSocket, event: PushEvent): void;
+export type PushEvent = {
+    event: "message_received";
+    from: string;
+    content: string;
+    contentType: string;
+    metadata?: Record<string, unknown>;
+} | {
+    event: "ping";
+    ts: string;
+};
+export declare function parsePluginFrame(data: RawData): unknown;
+//# sourceMappingURL=ipc-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-server.d.ts","sourceRoot":"","sources":["../../src/broker/ipc-server.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,KAAK,OAAO,EAAE,SAAS,EAAmB,MAAM,IAAI,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQhD,MAAM,WAAW,iBAAiB;IAEhC,gBAAgB,CACd,IAAI,EAAE,oBAAoB,EAC1B,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAErC,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAG5C,gBAAgB,CACd,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE7B,gBAAgB,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAItD,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI7E,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,IAAI,CAAC;IACf,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,MAAM,wBAAwB,GAClC,OAAO,yBAAyB,EAAE,mBAAmB,EAAE,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IAKnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMnC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAOD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM1D;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,YAAY,CAAC;IAIrB,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,KAAK,IAAI,CAAC;IAE9D,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,KAAK,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,gBAAgB;IAE/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD,wBAAsB,cAAc,CAClC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAqD3B;AAkRD,wBAAgB,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAGlE;AAED,MAAM,MAAM,SAAS,GACjB;IACE,KAAK,EAAE,kBAAkB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GACD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAGlC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAMvD"}