@masons/agent-network 0.5.31 → 0.5.32

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

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