@masons/runtime-broker 0.1.0

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"}

package/dist/broker/spawn-correlation.js

@@ -0,0 +1,77 @@
+export const DEFAULT_SPAWN_TIMEOUT_MS = 30_000;
+export const DEFAULT_RATE_LIMIT_WINDOW_MS = 30_000;
+export const DEFAULT_RATE_LIMIT_MAX = 3;
+export function createSpawnCorrelationManager(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
+    const entries = new Map();
+    const timers = new Map();
+    return {
+        track(spawn_token, onTimeout) {
+            const priorTimer = timers.get(spawn_token);
+            if (priorTimer)
+                clearTimeout(priorTimer);
+            entries.set(spawn_token, {
+                spawn_token,
+                expires_at: Date.now() + timeoutMs,
+            });
+            const handle = setTimeout(() => {
+                entries.delete(spawn_token);
+                timers.delete(spawn_token);
+                onTimeout();
+            }, timeoutMs);
+            handle.unref?.();
+            timers.set(spawn_token, handle);
+        },
+        consume(spawn_token) {
+            const entry = entries.get(spawn_token);
+            if (!entry)
+                return undefined;
+            entries.delete(spawn_token);
+            const timer = timers.get(spawn_token);
+            if (timer) {
+                clearTimeout(timer);
+                timers.delete(spawn_token);
+            }
+            return entry;
+        },
+        isTracked(spawn_token) {
+            return entries.has(spawn_token);
+        },
+        size() {
+            return entries.size;
+        },
+        cancelAll() {
+            for (const [, t] of timers)
+                clearTimeout(t);
+            timers.clear();
+            entries.clear();
+        },
+    };
+}
+export function createSpawnRateLimiter(opts = {}) {
+    const max = opts.maxInWindow ?? DEFAULT_RATE_LIMIT_MAX;
+    const windowMs = opts.windowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS;
+    const timestamps = [];
+    const sweep = (now) => {
+        const cutoff = now - windowMs;
+        while (timestamps.length > 0) {
+            const head = timestamps[0];
+            if (head === undefined || head >= cutoff)
+                break;
+            timestamps.shift();
+        }
+    };
+    return {
+        tryConsume(now = Date.now()) {
+            sweep(now);
+            if (timestamps.length >= max)
+                return false;
+            timestamps.push(now);
+            return true;
+        },
+        count(now = Date.now()) {
+            sweep(now);
+            return timestamps.length;
+        },
+    };
+}

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

@@ -0,0 +1,27 @@
+export interface SpawnCommand {
+    binary: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export interface SpawnContext {
+    prompt: string;
+    spawn_token: string;
+    cwd?: string;
+}
+export interface DriverAvailability {
+    available: boolean;
+    reason?: string;
+}
+export interface SpawnDriver {
+    readonly runtime_kind: string;
+    buildSpawnCommand(ctx: SpawnContext): SpawnCommand;
+    isAvailable(): Promise<DriverAvailability>;
+}
+export declare class SpawnDriverRegistry {
+    private readonly drivers;
+    register(driver: SpawnDriver): void;
+    lookup(runtime_kind: string): SpawnDriver | undefined;
+    list(): readonly string[];
+}
+//# sourceMappingURL=spawn-driver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-driver.d.ts","sourceRoot":"","sources":["../../src/broker/spawn-driver.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,YAAY;IAE3B,MAAM,EAAE,MAAM,CAAC;IAOf,WAAW,EAAE,MAAM,CAAC;IAEpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,CAAC;IAGnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAAC;IACnD,WAAW,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC5C;AAGD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAG1D,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAUnC,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAKrD,IAAI,IAAI,SAAS,MAAM,EAAE;CAG1B"}

package/dist/broker/spawn-driver.js

@@ -0,0 +1,15 @@
+export class SpawnDriverRegistry {
+    drivers = new Map();
+    register(driver) {
+        if (this.drivers.has(driver.runtime_kind)) {
+            throw new Error(`driver already registered for runtime_kind: ${driver.runtime_kind}`);
+        }
+        this.drivers.set(driver.runtime_kind, driver);
+    }
+    lookup(runtime_kind) {
+        return this.drivers.get(runtime_kind);
+    }
+    list() {
+        return Array.from(this.drivers.keys());
+    }
+}

package/dist/broker/task-hint-handler.d.ts

@@ -0,0 +1,21 @@
+import type { EndpointRegistry } from "./endpoint-registry.js";
+export declare const TASK_HINT_MAX_LENGTH = 200;
+export interface TaskHintHandlerOptions {
+    registry: EndpointRegistry;
+}
+export interface TaskHintUpdate {
+    endpoint_id: string;
+    plugin_pid: number;
+    task_hint: string;
+}
+export type TaskHintResult = {
+    ok: true;
+    truncated: boolean;
+    effective: string;
+} | {
+    ok: false;
+    code: "endpoint_unknown" | "ownership_mismatch" | "task_hint_invalid";
+    message: string;
+};
+export declare function updateTaskHint(opts: TaskHintHandlerOptions, update: TaskHintUpdate): TaskHintResult;
+//# sourceMappingURL=task-hint-handler.d.ts.map

package/dist/broker/task-hint-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-hint-handler.d.ts","sourceRoot":"","sources":["../../src/broker/task-hint-handler.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACnD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,kBAAkB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN,wBAAgB,cAAc,CAC5B,IAAI,EAAE,sBAAsB,EAC5B,MAAM,EAAE,cAAc,GACrB,cAAc,CAmChB"}

package/dist/broker/task-hint-handler.js

@@ -0,0 +1,33 @@
+export const TASK_HINT_MAX_LENGTH = 200;
+export function updateTaskHint(opts, update) {
+    if (typeof update.task_hint !== "string") {
+        return {
+            ok: false,
+            code: "task_hint_invalid",
+            message: "task_hint must be a string",
+        };
+    }
+    const entry = opts.registry.get(update.endpoint_id);
+    if (!entry) {
+        return {
+            ok: false,
+            code: "endpoint_unknown",
+            message: `unknown endpoint_id: ${update.endpoint_id}`,
+        };
+    }
+    if (entry.plugin_pid !== update.plugin_pid) {
+        return {
+            ok: false,
+            code: "ownership_mismatch",
+            message: "task_hint is Plugin-write-only; plugin_pid does not match",
+        };
+    }
+    const raw = update.task_hint;
+    const codePoints = [...raw];
+    const truncated = codePoints.length > TASK_HINT_MAX_LENGTH;
+    const effective = truncated
+        ? codePoints.slice(0, TASK_HINT_MAX_LENGTH).join("")
+        : raw;
+    entry.display_metadata.task_hint = effective;
+    return { ok: true, truncated, effective };
+}

package/dist/broker/transition-state-retry-queue.d.ts

@@ -0,0 +1,20 @@
+import type { TransitionRuntimeEndpointStateParams } from "../runtime-endpoint-client.js";
+export declare const DEFAULT_QUEUE_CAPACITY = 256;
+export interface QueuedTransition {
+    endpoint_id: string;
+    params: TransitionRuntimeEndpointStateParams;
+    enqueued_at: number;
+}
+export interface TransitionStateRetryQueue {
+    enqueue(endpoint_id: string, params: TransitionRuntimeEndpointStateParams): boolean;
+    flush(emit: (entry: QueuedTransition) => Promise<void>): Promise<void>;
+    size(): number;
+    capacity(): number;
+    peek(): readonly QueuedTransition[];
+}
+export interface TransitionStateRetryQueueOptions {
+    capacity?: number;
+    onDrop?: (dropped: QueuedTransition) => void;
+}
+export declare function createTransitionStateRetryQueue(opts?: TransitionStateRetryQueueOptions): TransitionStateRetryQueue;
+//# sourceMappingURL=transition-state-retry-queue.d.ts.map

package/dist/broker/transition-state-retry-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-state-retry-queue.d.ts","sourceRoot":"","sources":["../../src/broker/transition-state-retry-queue.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,+BAA+B,CAAC;AAE1F,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,oCAAoC,CAAC;IAE7C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IAExC,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,oCAAoC,GAC3C,OAAO,CAAC;IAOX,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,IAAI,IAAI,MAAM,CAAC;IACf,QAAQ,IAAI,MAAM,CAAC;IAEnB,IAAI,IAAI,SAAS,gBAAgB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC9C;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,GAAE,gCAAqC,GAC1C,yBAAyB,CA4C3B"}

package/dist/broker/transition-state-retry-queue.js

@@ -0,0 +1,48 @@
+export const DEFAULT_QUEUE_CAPACITY = 256;
+export function createTransitionStateRetryQueue(opts = {}) {
+    const cap = opts.capacity ?? DEFAULT_QUEUE_CAPACITY;
+    if (cap <= 0)
+        throw new Error(`capacity must be positive: ${cap}`);
+    const queue = [];
+    return {
+        enqueue(endpoint_id, params) {
+            const entry = {
+                endpoint_id,
+                params,
+                enqueued_at: Date.now(),
+            };
+            if (queue.length >= cap) {
+                const dropped = queue.shift();
+                if (dropped && opts.onDrop)
+                    opts.onDrop(dropped);
+                queue.push(entry);
+                return false;
+            }
+            queue.push(entry);
+            return true;
+        },
+        async flush(emit) {
+            while (queue.length > 0) {
+                const entry = queue[0];
+                if (!entry)
+                    break;
+                try {
+                    await emit(entry);
+                }
+                catch {
+                    return;
+                }
+                queue.shift();
+            }
+        },
+        size() {
+            return queue.length;
+        },
+        capacity() {
+            return cap;
+        },
+        peek() {
+            return queue.slice();
+        },
+    };
+}

package/dist/broker/undispatched-changed-event-types.d.ts

@@ -0,0 +1,29 @@
+export declare const CONTENT_PREVIEW_MAX_CODEPOINTS = 80;
+export type UndispatchedReason = "no_target_endpoint" | "closed_session_continuation";
+export type UndispatchedRemoveReason = "lost_at_capacity_during_redispatch_bounce";
+interface UndispatchedChangedEventBase {
+    type: "undispatched_changed";
+    version: 1;
+    undispatched_id: string;
+}
+export interface UndispatchedAddEvent extends UndispatchedChangedEventBase {
+    action: "add";
+    sender_address: string;
+    content_preview: string;
+    reason: UndispatchedReason;
+    target_endpoint_id_hint?: string;
+    in_reply_to?: string;
+    arrived_at: number;
+}
+export interface UndispatchedDispatchEvent extends UndispatchedChangedEventBase {
+    action: "dispatch";
+    dispatched_to_endpoint_id: string;
+}
+export interface UndispatchedRemoveEvent extends UndispatchedChangedEventBase {
+    action: "remove";
+    remove_reason: UndispatchedRemoveReason;
+}
+export type UndispatchedChangedEvent = UndispatchedAddEvent | UndispatchedDispatchEvent | UndispatchedRemoveEvent;
+export declare function truncateContentPreview(raw: string, n?: number): string;
+export {};
+//# sourceMappingURL=undispatched-changed-event-types.d.ts.map

package/dist/broker/undispatched-changed-event-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undispatched-changed-event-types.d.ts","sourceRoot":"","sources":["../../src/broker/undispatched-changed-event-types.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAMjD,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,6BAA6B,CAAC;AAOlC,MAAM,MAAM,wBAAwB,GAWlC,2CAA2C,CAAC;AAG9C,UAAU,4BAA4B;IACpC,IAAI,EAAE,sBAAsB,CAAC;IAG7B,OAAO,EAAE,CAAC,CAAC;IAEX,eAAe,EAAE,MAAM,CAAC;CACzB;AAGD,MAAM,WAAW,oBAAqB,SAAQ,4BAA4B;IACxE,MAAM,EAAE,KAAK,CAAC;IAEd,cAAc,EAAE,MAAM,CAAC;IASvB,eAAe,EAAE,MAAM,CAAC;IAExB,MAAM,EAAE,kBAAkB,CAAC;IAO3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAMjC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,yBACf,SAAQ,4BAA4B;IACpC,MAAM,EAAE,UAAU,CAAC;IAQnB,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAID,MAAM,WAAW,uBAAwB,SAAQ,4BAA4B;IAC3E,MAAM,EAAE,QAAQ,CAAC;IACjB,aAAa,EAAE,wBAAwB,CAAC;CACzC;AAED,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,yBAAyB,GACzB,uBAAuB,CAAC;AAqB5B,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,CAAC,GAAE,MAAuC,GACzC,MAAM,CAYR"}

package/dist/broker/undispatched-changed-event-types.js

@@ -0,0 +1,14 @@
+export const CONTENT_PREVIEW_MAX_CODEPOINTS = 80;
+export function truncateContentPreview(raw, n = CONTENT_PREVIEW_MAX_CODEPOINTS) {
+    if (raw.length <= n)
+        return raw;
+    let out = "";
+    let count = 0;
+    for (const cp of raw) {
+        if (count >= n)
+            break;
+        out += cp;
+        count++;
+    }
+    return out;
+}

package/dist/broker/undispatched-emitter.d.ts

@@ -0,0 +1,22 @@
+import type { BrokerLogger } from "./logger.js";
+import type { EmitOutcome, RuntimeEndpointPort } from "./runtime-endpoint-port.js";
+import type { UndispatchedChangedEvent } from "./undispatched-changed-event-types.js";
+export declare const DEFAULT_EMITTER_CAPACITY = 1024;
+export declare const DEFAULT_EMITTER_BACKOFF_INITIAL_MS = 500;
+export declare const DEFAULT_EMITTER_BACKOFF_MAX_MS = 30000;
+export declare const DEFAULT_EMITTER_MAX_RETRIES = 5;
+export interface UndispatchedChangedEmitterOptions {
+    capacity?: number;
+    backoffInitialMs?: number;
+    backoffMaxMs?: number;
+    maxRetries?: number;
+}
+export interface UndispatchedChangedEmitter {
+    enqueue(event: UndispatchedChangedEvent): boolean;
+    size(): number;
+    capacity(): number;
+    shutdown(): Promise<void>;
+}
+export declare function createUndispatchedChangedEmitter(post: (event: UndispatchedChangedEvent) => Promise<EmitOutcome>, logger: BrokerLogger, opts?: UndispatchedChangedEmitterOptions): UndispatchedChangedEmitter;
+export declare function postUndispatchedChangedViaPort(apiPort: RuntimeEndpointPort): (event: UndispatchedChangedEvent) => Promise<EmitOutcome>;
+//# sourceMappingURL=undispatched-emitter.d.ts.map

package/dist/broker/undispatched-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undispatched-emitter.d.ts","sourceRoot":"","sources":["../../src/broker/undispatched-emitter.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAEtF,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,kCAAkC,MAAM,CAAC;AACtD,eAAO,MAAM,8BAA8B,QAAS,CAAC;AACrD,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,MAAM,WAAW,iCAAiC;IAEhD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IAIzC,OAAO,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC;IAElD,IAAI,IAAI,MAAM,CAAC;IAEf,QAAQ,IAAI,MAAM,CAAC;IAGnB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,OAAO,CAAC,WAAW,CAAC,EAC/D,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE,iCAAsC,GAC3C,0BAA0B,CA8J5B;AAaD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,mBAAmB,GAC3B,CAAC,KAAK,EAAE,wBAAwB,KAAK,OAAO,CAAC,WAAW,CAAC,CAW3D"}

package/dist/broker/undispatched-emitter.js

@@ -0,0 +1,149 @@
+export const DEFAULT_EMITTER_CAPACITY = 1024;
+export const DEFAULT_EMITTER_BACKOFF_INITIAL_MS = 500;
+export const DEFAULT_EMITTER_BACKOFF_MAX_MS = 30_000;
+export const DEFAULT_EMITTER_MAX_RETRIES = 5;
+export function createUndispatchedChangedEmitter(post, logger, opts = {}) {
+    const cap = opts.capacity ?? DEFAULT_EMITTER_CAPACITY;
+    const initialBackoff = opts.backoffInitialMs ?? DEFAULT_EMITTER_BACKOFF_INITIAL_MS;
+    const maxBackoff = opts.backoffMaxMs ?? DEFAULT_EMITTER_BACKOFF_MAX_MS;
+    const maxRetries = opts.maxRetries ?? DEFAULT_EMITTER_MAX_RETRIES;
+    if (cap <= 0)
+        throw new Error(`capacity must be positive: ${cap}`);
+    if (initialBackoff <= 0)
+        throw new Error(`backoffInitialMs must be positive: ${initialBackoff}`);
+    if (maxBackoff < initialBackoff)
+        throw new Error(`backoffMaxMs must be >= backoffInitialMs`);
+    if (maxRetries < 0)
+        throw new Error(`maxRetries must be non-negative: ${maxRetries}`);
+    const queue = [];
+    let draining = false;
+    let stopped = false;
+    let activeDrain = null;
+    let wakeSleep = null;
+    const sleep = (ms) => new Promise((resolve) => {
+        const t = setTimeout(() => {
+            wakeSleep = null;
+            resolve();
+        }, ms);
+        t.unref?.();
+        wakeSleep = () => {
+            clearTimeout(t);
+            wakeSleep = null;
+            resolve();
+        };
+    });
+    const drain = async () => {
+        while (!stopped && queue.length > 0) {
+            const event = queue[0];
+            if (!event)
+                break;
+            let attempts = 0;
+            while (true) {
+                if (stopped)
+                    return;
+                let outcome;
+                try {
+                    outcome = await post(event);
+                }
+                catch (err) {
+                    outcome = {
+                        ok: false,
+                        terminal: false,
+                        detail: err instanceof Error ? err.message : String(err),
+                    };
+                }
+                if (outcome.ok)
+                    break;
+                if (outcome.terminal) {
+                    logger.warn("undispatched_changed_drop_terminal", {
+                        action: event.action,
+                        undispatched_id: event.undispatched_id,
+                        status: outcome.status,
+                        detail: outcome.detail,
+                    });
+                    break;
+                }
+                attempts++;
+                if (attempts > maxRetries) {
+                    logger.warn("undispatched_changed_drop_max_retries", {
+                        action: event.action,
+                        undispatched_id: event.undispatched_id,
+                        attempts,
+                        status: outcome.status,
+                        detail: outcome.detail,
+                    });
+                    break;
+                }
+                const backoff = Math.min(initialBackoff * 2 ** (attempts - 1), maxBackoff);
+                logger.info("undispatched_changed_retry", {
+                    action: event.action,
+                    undispatched_id: event.undispatched_id,
+                    attempt: attempts,
+                    backoff_ms: backoff,
+                    status: outcome.status,
+                });
+                await sleep(backoff);
+            }
+            queue.shift();
+        }
+        draining = false;
+    };
+    const kick = () => {
+        if (draining || stopped)
+            return;
+        draining = true;
+        activeDrain = drain().catch((err) => {
+            logger.error("undispatched_changed_drain_unexpected_error", {
+                err: err instanceof Error ? err.message : String(err),
+            });
+            draining = false;
+        });
+    };
+    return {
+        enqueue(event) {
+            if (stopped)
+                return true;
+            let evicted = false;
+            if (queue.length >= cap) {
+                const old = queue.shift();
+                if (old) {
+                    logger.warn("undispatched_changed_queue_overflow", {
+                        dropped_action: old.action,
+                        dropped_undispatched_id: old.undispatched_id,
+                        size: queue.length,
+                        capacity: cap,
+                    });
+                    evicted = true;
+                }
+            }
+            queue.push(event);
+            kick();
+            return !evicted;
+        },
+        size() {
+            return queue.length;
+        },
+        capacity() {
+            return cap;
+        },
+        async shutdown() {
+            stopped = true;
+            wakeSleep?.();
+            if (activeDrain) {
+                await activeDrain.catch(() => { });
+            }
+        },
+    };
+}
+export function postUndispatchedChangedViaPort(apiPort) {
+    return async (event) => {
+        if (!apiPort.emitUndispatchedChanged) {
+            return {
+                ok: false,
+                terminal: true,
+                detail: "emitUndispatchedChanged not implemented on this apiPort",
+            };
+        }
+        return apiPort.emitUndispatchedChanged(event);
+    };
+}

package/dist/broker/undispatched-inbox.d.ts

@@ -0,0 +1,26 @@
+export declare const DEFAULT_INBOX_CAPACITY = 256;
+export interface UndispatchedMessage {
+    id: string;
+    arrived_at: string;
+    sender_address: string;
+    content: string;
+    content_type: string;
+    metadata: Record<string, unknown>;
+    reason: "unaddressed" | "closed_session_continuation";
+    original_target_endpoint_id?: string;
+    original_correlation_id?: string;
+}
+export interface UndispatchedInbox {
+    tryAdd(msg: UndispatchedMessage): boolean;
+    list(): UndispatchedMessage[];
+    get(id: string): UndispatchedMessage | undefined;
+    take(id: string): UndispatchedMessage | undefined;
+    size(): number;
+    capacity(): number;
+    isUnderPressure(): boolean;
+}
+export interface UndispatchedInboxOptions {
+    capacity?: number;
+}
+export declare function createUndispatchedInbox(opts?: UndispatchedInboxOptions): UndispatchedInbox;
+//# sourceMappingURL=undispatched-inbox.d.ts.map

package/dist/broker/undispatched-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undispatched-inbox.d.ts","sourceRoot":"","sources":["../../src/broker/undispatched-inbox.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMlC,MAAM,EAAE,aAAa,GAAG,6BAA6B,CAAC;IAEtD,2BAA2B,CAAC,EAAE,MAAM,CAAC;IAErC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAMhC,MAAM,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC;IAE1C,IAAI,IAAI,mBAAmB,EAAE,CAAC;IAE9B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAKjD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAElD,IAAI,IAAI,MAAM,CAAC;IAEf,QAAQ,IAAI,MAAM,CAAC;IAEnB,eAAe,IAAI,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,GAAE,wBAA6B,GAClC,iBAAiB,CAkDnB"}

package/dist/broker/undispatched-inbox.js

@@ -0,0 +1,53 @@
+export const DEFAULT_INBOX_CAPACITY = 256;
+export function createUndispatchedInbox(opts = {}) {
+    const cap = opts.capacity ?? DEFAULT_INBOX_CAPACITY;
+    if (cap <= 0)
+        throw new Error(`capacity must be positive: ${cap}`);
+    const byId = new Map();
+    const order = [];
+    return {
+        tryAdd(msg) {
+            if (byId.has(msg.id)) {
+                byId.set(msg.id, msg);
+                return true;
+            }
+            if (byId.size >= cap) {
+                return false;
+            }
+            byId.set(msg.id, msg);
+            order.push(msg.id);
+            return true;
+        },
+        list() {
+            const out = [];
+            for (const id of order) {
+                const m = byId.get(id);
+                if (m)
+                    out.push(m);
+            }
+            return out;
+        },
+        get(id) {
+            return byId.get(id);
+        },
+        take(id) {
+            const m = byId.get(id);
+            if (!m)
+                return undefined;
+            byId.delete(id);
+            const idx = order.indexOf(id);
+            if (idx >= 0)
+                order.splice(idx, 1);
+            return m;
+        },
+        size() {
+            return byId.size;
+        },
+        capacity() {
+            return cap;
+        },
+        isUnderPressure() {
+            return byId.size >= Math.floor(cap * 0.9);
+        },
+    };
+}

package/dist/broker/version-handshake.d.ts

@@ -0,0 +1,30 @@
+export declare const IPC_PROTOCOL_VERSION = "1.0";
+export interface IpcCapabilities {
+    endpoint_metadata_v1?: boolean;
+    remote_spawn_v1?: boolean;
+    undispatched_inbox_v1?: boolean;
+}
+export declare const SERVER_CAPABILITIES: Readonly<IpcCapabilities>;
+export interface InitializeRequestBody {
+    client_protocol_version: string;
+    client_kind: string;
+    client_version: string;
+    capabilities?: IpcCapabilities;
+}
+export interface InitializeResponseBody {
+    server_protocol_version: string;
+    server_capabilities: IpcCapabilities;
+    session_id: string;
+}
+export interface InitializeErrorBody {
+    error: "protocol_version_mismatch" | "bad_request";
+    message: string;
+}
+export declare function handleInitialize(req: InitializeRequestBody): {
+    status: 200;
+    body: InitializeResponseBody;
+} | {
+    status: 400;
+    body: InitializeErrorBody;
+};
+//# sourceMappingURL=version-handshake.d.ts.map

package/dist/broker/version-handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-handshake.d.ts","sourceRoot":"","sources":["../../src/broker/version-handshake.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,oBAAoB,QAAQ,CAAC;AAM1C,MAAM,WAAW,eAAe;IAE9B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B,eAAe,CAAC,EAAE,OAAO,CAAC;IAG1B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAGD,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,eAAe,CAIxD,CAAC;AAEH,MAAM,WAAW,qBAAqB;IAEpC,uBAAuB,EAAE,MAAM,CAAC;IAEhC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,uBAAuB,EAAE,MAAM,CAAC;IAChC,mBAAmB,EAAE,eAAe,CAAC;IAErC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,2BAA2B,GAAG,aAAa,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,qBAAqB,GAExB;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,CA0C7C"}