@openscout/runtime 0.2.38 → 0.2.39

package/dist/broker-daemon.js

@@ -7,11 +7,12 @@ import { FileBackedBrokerJournal } from "./broker-journal.js";
 import { buildDispatchEnvelope, resolveAgentLabel, } from "./scout-dispatcher.js";
 import { buildCollaborationInvocation } from "./collaboration-invocations.js";
 import { discoverMeshNodes } from "./mesh-discovery.js";
-import { buildMeshCollaborationEventBundle, buildMeshCollaborationRecordBundle, buildMeshInvocationBundle, buildMeshMessageBundle, forwardMeshCollaborationEvent, forwardMeshCollaborationRecord, forwardMeshInvocation, fetchPeerAgents, forwardMeshMessage, } from "./mesh-forwarding.js";
+import { buildMeshCollaborationEventBundle, buildMeshCollaborationRecordBundle, buildMeshMessageBundle, forwardMeshCollaborationEvent, forwardMeshCollaborationRecord, fetchPeerAgents, forwardMeshMessage, } from "./mesh-forwarding.js";
+import { createPeerDeliveryWorker } from "./peer-delivery.js";
 import { ensureLocalAgentBindingOnline, isLocalAgentEndpointAlive, isLocalAgentSessionAlive, invokeLocalAgentEndpoint, loadRegisteredLocalAgentBindings, shouldDisableGeneratedCodexEndpoint, } from "./local-agents.js";
 import { RecoverableSQLiteProjection } from "./sqlite-projection.js";
 import { ensureOpenScoutCleanSlateSync } from "./support-paths.js";
-import { buildDefaultBrokerUrl, DEFAULT_BROKER_HOST, DEFAULT_BROKER_PORT, } from "./broker-service.js";
+import { buildDefaultBrokerUrl, DEFAULT_BROKER_PORT, isLoopbackHost, resolveAdvertiseScope, resolveBrokerHost, } from "./broker-service.js";
 function createRuntimeId(prefix) {
     return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -52,7 +53,8 @@ const controlHome = resolveControlPlaneHome();
 const dbPath = join(controlHome, "control-plane.sqlite");
 const journalPath = join(controlHome, "broker-journal.jsonl");
 const port = Number.parseInt(process.env.OPENSCOUT_BROKER_PORT ?? String(DEFAULT_BROKER_PORT), 10);
-const host = process.env.OPENSCOUT_BROKER_HOST ?? DEFAULT_BROKER_HOST;
+const advertiseScope = resolveAdvertiseScope();
+const host = resolveBrokerHost(advertiseScope);
 const meshId = process.env.OPENSCOUT_MESH_ID ?? "openscout";
 const nodeName = process.env.OPENSCOUT_NODE_NAME ?? hostname();
 const tailnetName = process.env.TAILSCALE_TAILNET ?? undefined;
@@ -85,20 +87,59 @@ const activeInvocationTasks = new Map();
 const knownInvocations = new Map();
 const sseKeepAliveIntervalMs = Number.parseInt(process.env.OPENSCOUT_SSE_KEEPALIVE_MS ?? "15000", 10);
 const operatorActorId = "operator";
+// Per-invocation SSE subscribers. A single caller can watch one invocation
+// without draining the entire global event firehose.
+const invocationStreamClients = new Map();
+function invocationIdsForEvent(event) {
+    switch (event.kind) {
+        case "invocation.requested":
+            return [event.payload.invocation.id];
+        case "flight.updated":
+            return event.payload.flight.invocationId ? [event.payload.flight.invocationId] : [];
+        case "delivery.planned":
+            return event.payload.delivery.invocationId ? [event.payload.delivery.invocationId] : [];
+        case "delivery.attempted": {
+            const deliveryId = event.payload.attempt.deliveryId;
+            const delivery = journal.listDeliveries({ limit: 1000 }).find((d) => d.id === deliveryId);
+            return delivery?.invocationId ? [delivery.invocationId] : [];
+        }
+        case "delivery.state.changed":
+            return event.payload.delivery.invocationId ? [event.payload.delivery.invocationId] : [];
+        case "scout.dispatched":
+            return event.payload.dispatch.invocationId ? [event.payload.dispatch.invocationId] : [];
+        case "message.posted": {
+            const dispatch = event.payload.message.metadata
+                ?.scoutDispatch;
+            return dispatch?.invocationId ? [dispatch.invocationId] : [];
+        }
+        default:
+            return [];
+    }
+}
 function streamEvent(event) {
     projection.enqueueEvent(event);
     const payload = `event: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`;
     for (const client of eventClients) {
         client.write(payload);
     }
+    for (const invocationId of invocationIdsForEvent(event)) {
+        const subscribers = invocationStreamClients.get(invocationId);
+        if (!subscribers)
+            continue;
+        for (const client of subscribers) {
+            client.write(payload);
+        }
+    }
 }
 function streamKeepAlive() {
-    if (eventClients.size == 0) {
-        return;
-    }
     for (const client of eventClients) {
         client.write(": keepalive\n\n");
     }
+    for (const subscribers of invocationStreamClients.values()) {
+        for (const client of subscribers) {
+            client.write(": keepalive\n\n");
+        }
+    }
 }
 runtime.subscribe((event) => {
     streamEvent(event);
@@ -113,7 +154,7 @@ const localNode = {
     meshId,
     name: nodeName,
     hostName: hostname(),
-    advertiseScope: host === DEFAULT_BROKER_HOST ? "local" : "mesh",
+    advertiseScope,
     brokerUrl,
     tailnetName,
     capabilities: ["broker", "mesh", "local_runtime"],
@@ -144,6 +185,9 @@ async function discoverPeers(seeds = []) {
     });
     for (const node of result.discovered) {
         await upsertNodeDurably(node);
+        // A previously-unreachable peer may have come back — flush any deferred
+        // outbox entries targeting it without waiting for the next backoff window.
+        peerDelivery.notifyPeerOnline(node.id);
     }
     // Sync agents from each discovered peer so local broker knows about remote agents.
     // This enables @mention resolution and message forwarding across the mesh.
@@ -351,6 +395,11 @@ async function recordFlightDurably(flight) {
         });
     });
 }
+async function recordDeliveryDurably(delivery) {
+    await runDurableWrite(async () => {
+        await commitDurableEntries({ kind: "deliveries.record", deliveries: [delivery] }, async () => { });
+    });
+}
 async function recordDeliveryAttemptDurably(attempt) {
     await runDurableWrite(async () => {
         await commitDurableEntries({
@@ -1247,27 +1296,6 @@ async function forwardPeerBrokerCollaborationEvent(event) {
     }
     return { forwarded, failed };
 }
-async function maybeForwardInvocation(invocation) {
-    const targetAgent = runtime.agent(invocation.targetAgentId);
-    if (!targetAgent) {
-        throw new Error(`unknown agent ${invocation.targetAgentId}`);
-    }
-    if (targetAgent.authorityNodeId === nodeId) {
-        return { forwarded: false };
-    }
-    const authorityNode = runtime.node(targetAgent.authorityNodeId);
-    if (!authorityNode?.brokerUrl) {
-        throw new Error(`authority node ${targetAgent.authorityNodeId} is not reachable`);
-    }
-    const bundle = buildMeshInvocationBundle(runtime.peek(), currentLocalNode(), invocation);
-    const result = await forwardMeshInvocation(authorityNode.brokerUrl, bundle);
-    const { entries } = await recordInvocationDurably(invocation, {
-        flight: result.flight,
-        enqueueProjection: false,
-    });
-    projection.enqueueEntries(entries);
-    return { forwarded: true, flight: result.flight };
-}
 function parseLimit(url) {
     const limit = Number.parseInt(url.searchParams.get("limit") ?? "100", 10);
     if (!Number.isFinite(limit) || limit <= 0)
@@ -1382,23 +1410,20 @@ async function handleCommand(command) {
             return { ok: true, message: command.message, deliveries, mesh };
         }
         case "agent.invoke": {
-            const forwarded = await maybeForwardInvocation(command.invocation);
-            if (forwarded.forwarded) {
-                console.log(`[openscout-runtime] invocation ${command.invocation.id} forwarded to ${command.invocation.targetAgentId}`);
-                return { ok: true, flight: forwarded.flight, forwarded: true };
-            }
-            const { flight, entries } = await recordInvocationDurably(command.invocation, {
-                enqueueProjection: false,
+            const flight = await acceptInvocationDurably(command.invocation);
+            console.log(`[openscout-runtime] invocation ${command.invocation.id} accepted for ${command.invocation.targetAgentId} (state=${flight.state})`);
+            dispatchAcceptedInvocation(command.invocation).catch((error) => {
+                console.error(`[openscout-runtime] background dispatch failed for invocation ${command.invocation.id}:`, error);
             });
-            console.log(`[openscout-runtime] invocation ${command.invocation.id} -> ${command.invocation.targetAgentId} is ${flight.state}${flight.summary ? ` (${flight.summary})` : ""}`);
-            if (flight.state === "failed") {
-                await postInvocationStatusMessage(command.invocation, flight);
-            }
-            else {
-                launchLocalInvocation(command.invocation, flight);
-            }
-            projection.enqueueEntries(entries);
-            return { ok: true, flight };
+            return {
+                ok: true,
+                accepted: true,
+                invocationId: command.invocation.id,
+                flightId: flight.id,
+                targetAgentId: command.invocation.targetAgentId,
+                state: flight.state,
+                flight,
+            };
         }
         case "agent.ensure_awake":
             await runtime.dispatch(command);
@@ -1411,6 +1436,76 @@ async function handleCommand(command) {
         }
     }
 }
+async function acceptInvocationDurably(invocation) {
+    const { flight, entries } = await recordInvocationDurably(invocation, {
+        enqueueProjection: false,
+    });
+    projection.enqueueEntries(entries);
+    return flight;
+}
+async function dispatchAcceptedInvocation(invocation) {
+    const targetAgent = runtime.agent(invocation.targetAgentId);
+    if (!targetAgent) {
+        await failAcceptedInvocation(invocation, `unknown agent ${invocation.targetAgentId}`);
+        return;
+    }
+    const flight = runtime.flightForInvocation(invocation.id);
+    if (!flight) {
+        console.warn(`[openscout-runtime] dispatch skipped — flight missing for invocation ${invocation.id}`);
+        return;
+    }
+    if (targetAgent.authorityNodeId && targetAgent.authorityNodeId !== nodeId) {
+        // Cross-node: hand off to the outbox worker. Peer reachability is now a
+        // delivery concern (deferred ↔ accepted retries), not an HTTP error.
+        const authorityNode = runtime.node(targetAgent.authorityNodeId);
+        if (!authorityNode) {
+            await failAcceptedInvocation(invocation, `authority node ${targetAgent.authorityNodeId} is not reachable`);
+            return;
+        }
+        await peerDelivery.enqueue(invocation, authorityNode);
+        return;
+    }
+    // Local authority — run the normal launch path.
+    if (flight.state === "failed") {
+        await postInvocationStatusMessage(invocation, flight);
+    }
+    else {
+        launchLocalInvocation(invocation, flight);
+    }
+}
+async function failAcceptedInvocation(invocation, detail) {
+    const now = Date.now();
+    const existing = runtime.flightForInvocation(invocation.id);
+    const failed = {
+        id: existing?.id ?? createRuntimeId("flt"),
+        invocationId: invocation.id,
+        requesterId: invocation.requesterId,
+        targetAgentId: invocation.targetAgentId,
+        state: "failed",
+        startedAt: existing?.startedAt ?? now,
+        completedAt: now,
+        summary: detail,
+        error: detail,
+        metadata: invocation.metadata,
+    };
+    await recordFlightDurably(failed);
+    await postInvocationStatusMessage(invocation, failed);
+}
+const peerDelivery = createPeerDeliveryWorker({
+    journal,
+    snapshot: () => runtime.peek(),
+    localNode: currentLocalNode,
+    localNodeId: nodeId,
+    nodeFor: (id) => runtime.node(id),
+    agentFor: (id) => runtime.agent(id),
+    invocationFor: (id) => knownInvocations.get(id),
+    recordDelivery: recordDeliveryDurably,
+    updateDeliveryStatus: updateDeliveryStatusDurably,
+    recordDeliveryAttempt: recordDeliveryAttemptDurably,
+    recordFlight: recordFlightDurably,
+    failInvocation: failAcceptedInvocation,
+    emit: streamEvent,
+});
 async function routeRequest(request, response) {
     const method = request.method ?? "GET";
     const url = new URL(request.url ?? "/", `http://${request.headers.host ?? `${host}:${port}`}`);
@@ -1524,6 +1619,75 @@ async function routeRequest(request, response) {
         json(response, 200, runtime.snapshot().nodes);
         return;
     }
+    // Per-invocation snapshot — current state of the invocation, its flight,
+    // its deliveries, and any scout dispatch that fired for it. Callers use
+    // this to seed UI state before subscribing to the stream.
+    const invocationSnapshotMatch = method === "GET"
+        ? url.pathname.match(/^\/v1\/invocations\/([^/]+)$/)
+        : null;
+    if (invocationSnapshotMatch) {
+        const invocationId = decodeURIComponent(invocationSnapshotMatch[1] ?? "");
+        const flight = runtime.flightForInvocation(invocationId);
+        const deliveries = journal
+            .listDeliveries({ limit: 500 })
+            .filter((delivery) => delivery.invocationId === invocationId);
+        const dispatches = journal
+            .listScoutDispatches({ limit: 50 })
+            .filter((record) => record.invocationId === invocationId);
+        const invocation = knownInvocations.get(invocationId);
+        json(response, 200, {
+            invocationId,
+            invocation: invocation ?? null,
+            flight: flight ?? null,
+            deliveries,
+            dispatches,
+        });
+        return;
+    }
+    // Per-invocation SSE — initial snapshot frame, then every event whose
+    // payload references this invocation. Caller closes the stream when done.
+    const invocationStreamMatch = method === "GET"
+        ? url.pathname.match(/^\/v1\/invocations\/([^/]+)\/stream$/)
+        : null;
+    if (invocationStreamMatch) {
+        const invocationId = decodeURIComponent(invocationStreamMatch[1] ?? "");
+        response.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache, no-transform",
+            connection: "keep-alive",
+        });
+        const flight = runtime.flightForInvocation(invocationId);
+        const deliveries = journal
+            .listDeliveries({ limit: 500 })
+            .filter((delivery) => delivery.invocationId === invocationId);
+        const dispatches = journal
+            .listScoutDispatches({ limit: 50 })
+            .filter((record) => record.invocationId === invocationId);
+        const invocation = knownInvocations.get(invocationId);
+        response.write(`event: snapshot\ndata: ${JSON.stringify({
+            invocationId,
+            invocation: invocation ?? null,
+            flight: flight ?? null,
+            deliveries,
+            dispatches,
+        })}\n\n`);
+        let subscribers = invocationStreamClients.get(invocationId);
+        if (!subscribers) {
+            subscribers = new Set();
+            invocationStreamClients.set(invocationId, subscribers);
+        }
+        subscribers.add(response);
+        request.on("close", () => {
+            const set = invocationStreamClients.get(invocationId);
+            if (set) {
+                set.delete(response);
+                if (set.size === 0)
+                    invocationStreamClients.delete(invocationId);
+            }
+            response.end();
+        });
+        return;
+    }
     if (method === "GET" && url.pathname === "/v1/events/stream") {
         response.writeHead(200, {
             "content-type": "text/event-stream",
@@ -1862,15 +2026,29 @@ async function routeRequest(request, response) {
                     conversationId: payload.conversationId,
                     requesterId: payload.requesterId,
                 });
-                json(response, 200, buildScoutDispatchResponse(record, payload));
+                json(response, 202, {
+                    accepted: true,
+                    invocationId: payload.id,
+                    dispatch: record,
+                });
                 return;
             }
             const invocation = {
                 ...payload,
                 targetAgentId: resolved.agent.id,
             };
-            const result = await handleCommand({ kind: "agent.invoke", invocation });
-            json(response, 200, result);
+            const flight = await acceptInvocationDurably(invocation);
+            json(response, 202, {
+                accepted: true,
+                invocationId: invocation.id,
+                flightId: flight.id,
+                targetAgentId: invocation.targetAgentId,
+                state: flight.state,
+                flight,
+            });
+            dispatchAcceptedInvocation(invocation).catch((error) => {
+                console.error(`[openscout-runtime] background dispatch failed for invocation ${invocation.id}:`, error);
+            });
         }
         catch (error) {
             badRequest(response, error);
@@ -1897,14 +2075,6 @@ function resolveInvocationTarget(payload) {
         helpers: { isStale: isStaleLocalAgent },
     });
 }
-function buildScoutDispatchResponse(record, payload) {
-    return {
-        ok: false,
-        dispatchedTo: SCOUT_DISPATCHER_AGENT_ID,
-        invocationId: payload.id,
-        dispatch: record,
-    };
-}
 const server = createServer((request, response) => {
     routeRequest(request, response).catch((error) => {
         json(response, 500, {
@@ -1915,7 +2085,11 @@ const server = createServer((request, response) => {
 });
 try {
     await listen(server);
-    console.log(`[openscout-runtime] broker listening on ${brokerUrl}`);
+    peerDelivery.start();
+    console.log(`[openscout-runtime] broker listening on ${host}:${port} (scope: ${advertiseScope}, url: ${brokerUrl})`);
+    if (advertiseScope === "mesh" && isLoopbackHost(host)) {
+        console.warn(`[openscout-runtime] WARNING: mesh scope bound to loopback ${host} — peers cannot reach this broker. Set OPENSCOUT_BROKER_HOST=0.0.0.0 or unset to use the mesh default.`);
+    }
     console.log(`[openscout-runtime] node ${nodeId} in mesh ${meshId}`);
     console.log(`[openscout-runtime] journal ${journalPath}`);
     console.log(`[openscout-runtime] sqlite ${sqliteDisabled ? "disabled" : dbPath}`);
@@ -1955,9 +2129,16 @@ if (Number.isFinite(discoveryIntervalMs) && discoveryIntervalMs > 0) {
 }
 for (const signal of ["SIGINT", "SIGTERM"]) {
     process.on(signal, () => {
+        peerDelivery.stop();
         for (const client of eventClients) {
             client.end();
         }
+        for (const subscribers of invocationStreamClients.values()) {
+            for (const client of subscribers) {
+                client.end();
+            }
+        }
+        invocationStreamClients.clear();
         projection.close();
         server.close(() => process.exit(0));
     });

package/dist/broker-service.d.ts

@@ -1,4 +1,5 @@
 export type BrokerServiceMode = "dev" | "prod" | "custom";
+export type BrokerAdvertiseScope = "local" | "mesh";
 export type BrokerServiceConfig = {
     label: string;
     mode: BrokerServiceMode;
@@ -16,6 +17,7 @@ export type BrokerServiceConfig = {
     brokerHost: string;
     brokerPort: number;
     brokerUrl: string;
+    advertiseScope: BrokerAdvertiseScope;
 };
 export type BrokerHealthSnapshot = {
     reachable: boolean;
@@ -59,7 +61,12 @@ type LaunchctlStatus = {
     raw: string;
 };
 export declare const DEFAULT_BROKER_HOST = "127.0.0.1";
+export declare const DEFAULT_BROKER_HOST_MESH = "0.0.0.0";
 export declare const DEFAULT_BROKER_PORT = 65535;
+export declare const DEFAULT_ADVERTISE_SCOPE: BrokerAdvertiseScope;
+export declare function resolveAdvertiseScope(): BrokerAdvertiseScope;
+export declare function resolveBrokerHost(scope?: BrokerAdvertiseScope): string;
+export declare function isLoopbackHost(host: string): boolean;
 export declare function buildDefaultBrokerUrl(host?: string, port?: number): string;
 export declare const DEFAULT_BROKER_URL: string;
 export declare function resolveBrokerServiceConfig(): BrokerServiceConfig;

package/dist/broker-service.js

@@ -9,7 +9,28 @@ function isTmpPath(p) {
     return /^\/(?:private\/)?tmp\//.test(p);
 }
 export const DEFAULT_BROKER_HOST = "127.0.0.1";
+export const DEFAULT_BROKER_HOST_MESH = "0.0.0.0";
 export const DEFAULT_BROKER_PORT = 65535;
+export const DEFAULT_ADVERTISE_SCOPE = "local";
+export function resolveAdvertiseScope() {
+    const raw = (process.env.OPENSCOUT_ADVERTISE_SCOPE ?? "").trim().toLowerCase();
+    if (raw === "mesh")
+        return "mesh";
+    if (raw === "local")
+        return "local";
+    return DEFAULT_ADVERTISE_SCOPE;
+}
+export function resolveBrokerHost(scope = resolveAdvertiseScope()) {
+    const explicit = process.env.OPENSCOUT_BROKER_HOST;
+    if (typeof explicit === "string" && explicit.trim().length > 0) {
+        return explicit;
+    }
+    return scope === "mesh" ? DEFAULT_BROKER_HOST_MESH : DEFAULT_BROKER_HOST;
+}
+export function isLoopbackHost(host) {
+    const trimmed = host.trim();
+    return trimmed === "127.0.0.1" || trimmed === "::1" || trimmed === "localhost";
+}
 const BROKER_SERVICE_POLL_INTERVAL_MS = 100;
 const DEFAULT_BROKER_START_TIMEOUT_MS = 15_000;
 export function buildDefaultBrokerUrl(host = DEFAULT_BROKER_HOST, port = DEFAULT_BROKER_PORT) {
@@ -149,7 +170,8 @@ export function resolveBrokerServiceConfig() {
     const controlHome = isTmpPath(supportPaths.controlHome)
         ? join(homedir(), ".openscout", "control-plane")
         : supportPaths.controlHome;
-    const brokerHost = process.env.OPENSCOUT_BROKER_HOST ?? DEFAULT_BROKER_HOST;
+    const advertiseScope = resolveAdvertiseScope();
+    const brokerHost = resolveBrokerHost(advertiseScope);
     const brokerPort = Number.parseInt(process.env.OPENSCOUT_BROKER_PORT ?? String(DEFAULT_BROKER_PORT), 10);
     const brokerUrl = process.env.OPENSCOUT_BROKER_URL ?? buildDefaultBrokerUrl(brokerHost, brokerPort);
     const launchAgentPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
@@ -170,6 +192,7 @@ export function resolveBrokerServiceConfig() {
         brokerHost,
         brokerPort,
         brokerUrl,
+        advertiseScope,
     };
 }
 export function renderLaunchAgentPlist(config) {
@@ -181,6 +204,7 @@ export function renderLaunchAgentPlist(config) {
         OPENSCOUT_CONTROL_HOME: config.controlHome,
         OPENSCOUT_BROKER_SERVICE_MODE: config.mode,
         OPENSCOUT_BROKER_SERVICE_LABEL: config.label,
+        OPENSCOUT_ADVERTISE_SCOPE: config.advertiseScope,
         HOME: homedir(),
         PATH: launchPath,
         ...collectOptionalEnvVars([

package/dist/mesh-forwarding.d.ts

@@ -37,6 +37,29 @@ export declare function buildMeshMessageBundle(snapshot: Readonly<RuntimeRegistr
 export declare function buildMeshInvocationBundle(snapshot: Readonly<RuntimeRegistrySnapshot>, originNode: NodeDefinition, invocation: InvocationRequest): MeshInvocationBundle;
 export declare function buildMeshCollaborationRecordBundle(snapshot: Readonly<RuntimeRegistrySnapshot>, originNode: NodeDefinition, record: CollaborationRecord): MeshCollaborationRecordBundle;
 export declare function buildMeshCollaborationEventBundle(snapshot: Readonly<RuntimeRegistrySnapshot>, originNode: NodeDefinition, event: CollaborationEvent, record?: CollaborationRecord): MeshCollaborationEventBundle;
+/**
+ * Network-level failure reaching the peer broker (DNS, TCP, TLS, abort).
+ * Originator outbox treats this as retry-able.
+ */
+export declare class PeerUnreachableError extends Error {
+    readonly url: string;
+    readonly cause?: unknown | undefined;
+    readonly name = "PeerUnreachableError";
+    constructor(message: string, url: string, cause?: unknown | undefined);
+}
+/**
+ * Peer broker responded but rejected the request (HTTP non-2xx).
+ * Originator outbox treats 5xx as retry-able and 4xx as terminal.
+ */
+export declare class PeerRejectedError extends Error {
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly body?: string | undefined;
+    readonly name = "PeerRejectedError";
+    constructor(message: string, url: string, status: number, statusText: string, body?: string | undefined);
+    get retryable(): boolean;
+}
 export declare function forwardMeshMessage(brokerUrl: string, bundle: MeshMessageBundle): Promise<{
     ok: true;
     deliveries?: DeliveryIntent[];

package/dist/mesh-forwarding.js

@@ -153,17 +153,65 @@ export function buildMeshCollaborationEventBundle(snapshot, originNode, event, r
         event,
     };
 }
+/**
+ * Network-level failure reaching the peer broker (DNS, TCP, TLS, abort).
+ * Originator outbox treats this as retry-able.
+ */
+export class PeerUnreachableError extends Error {
+    url;
+    cause;
+    name = "PeerUnreachableError";
+    constructor(message, url, cause) {
+        super(message);
+        this.url = url;
+        this.cause = cause;
+    }
+}
+/**
+ * Peer broker responded but rejected the request (HTTP non-2xx).
+ * Originator outbox treats 5xx as retry-able and 4xx as terminal.
+ */
+export class PeerRejectedError extends Error {
+    url;
+    status;
+    statusText;
+    body;
+    name = "PeerRejectedError";
+    constructor(message, url, status, statusText, body) {
+        super(message);
+        this.url = url;
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+    get retryable() {
+        return this.status >= 500;
+    }
+}
 async function postJson(url, payload) {
-    const response = await fetch(url, {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-            accept: "application/json",
-        },
-        body: JSON.stringify(payload),
-    });
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (error) {
+        throw new PeerUnreachableError(`peer broker unreachable: ${error instanceof Error ? error.message : String(error)}`, url, error);
+    }
     if (!response.ok) {
-        throw new Error(`peer broker request failed: ${response.status} ${response.statusText}`);
+        let body;
+        try {
+            body = await response.text();
+        }
+        catch {
+            body = undefined;
+        }
+        throw new PeerRejectedError(`peer broker rejected request: ${response.status} ${response.statusText}`, url, response.status, response.statusText, body);
     }
     return await response.json();
 }