@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/engineBrokerMcpCallLog.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The in-flight MCP tool calls of one brokered turn.
+ *
+ * Daimon writes a tool receipt only when a call *completes*, so a call that
+ * started and never returned is byte-identical, in every artifact, to a call
+ * that was never made. A live Grok turn stopped acting after its eighth
+ * provider response and was killed by the trial deadline seven minutes later
+ * with the proxy's per-request ledger reporting `open: 0` — every provider
+ * request closed — which leaves exactly one unlit path: a tool call the worker
+ * issued and the facade never answered.
+ *
+ * This is that light, and it follows the per-request ledger's rules rather
+ * than inventing its own:
+ *
+ * - **names and timings only.** The tool name off the JSON-RPC envelope and
+ *   two clocks. Never arguments, never a result, never a session id, never a
+ *   capability or bearer. A name that is not a plain short identifier is
+ *   recorded as {@link ENGINE_BROKER_MCP_CALL_INVALID} rather than passed
+ *   through, and the list is bounded at
+ *   {@link ENGINE_BROKER_MCP_OUTSTANDING_MAX} with
+ *   {@link ENGINE_BROKER_MCP_CALL_TRUNCATED} as its last entry.
+ * - **absence stays absence.** A turn the log never opened observes as
+ *   `undefined`; a turn that made no call observes `started: 0`, which is not
+ *   the same statement as an answered call. A POST whose body the facade could
+ *   not read counts in `undecoded` and never as a call with a name, because a
+ *   fabricated name is byte-identical to a measured one — and because "zero
+ *   calls started" is exactly the reading this instrument exists to make
+ *   trustworthy.
+ * - **it cannot fail a turn.** Every operation here is arithmetic over a map,
+ *   the one parse is wrapped, and the facade treats a missing handle as a
+ *   no-op.
+ *
+ * The same map carries the facade's *other* channel, and for the same reason.
+ * A `tools/call` is a POST that answers; the standalone `GET` SSE tunnel the
+ * Streamable HTTP transport opens once per session is the route a server
+ * notification or progress frame takes, and it stays open for the whole
+ * session by design. A worker parked reading that tunnel is, in every artifact
+ * the broker writes, indistinguishable from a worker doing nothing at all:
+ * every provider request closed, every tool call answered, and the turn idle
+ * until its deadline. {@link EngineBrokerMcpCallLog.openTunnel} records the
+ * lifecycle — how many the facade relayed, how many ended, and for the ones
+ * still open at seal time how long each has been open and whether the mount
+ * ever pushed a single byte through it. A tunnel held open having delivered
+ * nothing is a different fact from one actively carrying frames, and it is the
+ * difference that decides whether the tunnel is the blocker.
+ *
+ * Observing is all it does. The facade's behaviour is unchanged: nothing here
+ * closes, times out or refuses a tunnel, because an instrument that tore down
+ * the stream would destroy the evidence it exists to gather.
+ *
+ * "Answered" means the facade wrote a complete response back to the worker —
+ * the relay reached its own `end()`. A relay that was torn down (the worker
+ * died, the tunnel broke, the turn aborted) did *not* answer, so its calls stay
+ * outstanding with the elapsed time they had reached. That is the whole point:
+ * the turn's death must not retroactively mark the call it was blocked on as
+ * finished.
+ */
+/**
+ * The same map carries the facade's *refusals*, for the sharpest form of the
+ * same problem. A refused request never reaches the relay at all, so a turn
+ * every one of whose requests was 403'd sealed as `answered == started,
+ * outstanding: []` — byte-identical to a healthy turn, which is precisely the
+ * reading this instrument exists to make trustworthy. The reason class is what
+ * makes it actionable: an exhausted per-turn capability budget — the facade's
+ * `ENGINE_BROKER_MCP_CAPABILITY_REQUESTS`, derived from the compiled turn
+ * bound times what a round may spend — is a different fault from a mount that
+ * was never registered, and both differ from a worker asking for a route the
+ * facade does not serve. Counts only, keyed by a closed vocabulary:
+ * never the token, the capability, the URL or the body. A refusal the facade
+ * cannot attribute to a turn — a bearer no live grant matches — is recorded
+ * nowhere, because attributing it to a turn would be inventing the fact.
+ */
+export declare const ENGINE_BROKER_MCP_OUTSTANDING_MAX = 16;
+export declare const ENGINE_BROKER_MCP_CALL_INVALID = "<invalid>";
+export declare const ENGINE_BROKER_MCP_CALL_TRUNCATED = "<truncated>";
+/** A plain short identifier, or one of the two sentinels above. */
+export declare const ENGINE_BROKER_MCP_CALL_NAME: RegExp;
+/** Open GET tunnels reported: a session opens one, so more than a handful is already the anomaly. */
+export declare const ENGINE_BROKER_MCP_TUNNEL_MAX = 8;
+/**
+ * Why the facade refused one relayed request, as a closed vocabulary:
+ * - `route`: a path or method the facade does not serve.
+ * - `expired`: the turn capability's TTL had passed.
+ * - `exhausted`: the turn capability's request budget was spent.
+ * - `unrouted`: a live capability whose turn has no registered mount.
+ * - `oversized`: a POST body past the facade's own request bound.
+ */
+export declare const ENGINE_BROKER_MCP_REFUSAL_REASONS: readonly ["route", "expired", "exhausted", "unrouted", "oversized"];
+export type EngineBrokerMcpRefusalReason = (typeof ENGINE_BROKER_MCP_REFUSAL_REASONS)[number];
+/** How many requests of this turn the facade refused, by reason class. Every member is a measurement; the whole member is absent only where it was never measured. */
+export type EngineBrokerMcpRefusalObservation = Readonly<Record<EngineBrokerMcpRefusalReason, number>>;
+export type EngineBrokerOutstandingMcpCall = Readonly<{
+    name: string;
+    outstandingMs: number;
+}>;
+/** One GET SSE tunnel still open at observation: how long it has been open, and whether the mount ever pushed through it. */
+export type EngineBrokerOpenMcpTunnel = Readonly<{
+    openMs: number;
+    delivered: boolean;
+}>;
+/**
+ * What the facade saw of one turn's standalone GET SSE tunnels: how many it
+ * relayed, how many ended, how many ever carried a byte from the mount, and
+ * the ones still open with the age of each.
+ */
+export type EngineBrokerMcpTunnelObservation = Readonly<{
+    opened: number;
+    closed: number;
+    delivered: number;
+    open: readonly EngineBrokerOpenMcpTunnel[];
+}>;
+/**
+ * What the facade saw of one turn's tool calls: how many started, how many the
+ * facade answered, how many POST bodies it could not read, and the ones still
+ * unanswered with the time each has been outstanding.
+ */
+export type EngineBrokerMcpCallObservation = Readonly<{
+    started: number;
+    answered: number;
+    undecoded: number;
+    outstanding: readonly EngineBrokerOutstandingMcpCall[];
+    tunnels?: EngineBrokerMcpTunnelObservation;
+    refusals?: EngineBrokerMcpRefusalObservation;
+}>;
+/** One relayed POST's calls. `answer` marks a complete relay; `close` ends it unanswered. Both are idempotent. */
+export interface EngineBrokerMcpCallHandle {
+    answer(): void;
+    close(): void;
+}
+/** One relayed GET tunnel. `deliver` marks the first byte the mount pushed; `close` ends it. Both are idempotent. */
+export interface EngineBrokerMcpTunnelHandle {
+    deliver(): void;
+    close(): void;
+}
+export declare class EngineBrokerMcpCallLog {
+    private readonly now;
+    private readonly turns;
+    constructor(now?: () => number);
+    /** A turn the facade registered. Re-opening an id resets it: a turn id is unique per turn. */
+    open(turnId: string): void;
+    close(turnId: string): void;
+    /** A POST body the facade is about to relay. Anything that is not a `tools/call` records nothing. */
+    begin(turnId: string, body: Uint8Array | undefined): EngineBrokerMcpCallHandle;
+    /**
+     * A GET SSE tunnel the facade is about to relay. Counted when it opens, not
+     * when it succeeds: a tunnel the mount refused still ends, so `opened` and
+     * `closed` stay a pair and an open one is exactly `opened - closed`.
+     */
+    openTunnel(turnId: string): EngineBrokerMcpTunnelHandle;
+    /**
+     * A request the facade refused before it could ever be relayed. A refusal it
+     * cannot attribute to a turn is never recorded against one, so an unknown
+     * turn is a no-op here exactly as every other operation is.
+     */
+    refuse(turnId: string, reason: EngineBrokerMcpRefusalReason): void;
+    /** A POST whose body the facade refused to read (over its own bound), which is a call it cannot name. */
+    undecodable(turnId: string): void;
+    observe(turnId: string): EngineBrokerMcpCallObservation | undefined;
+}
+//# sourceMappingURL=engineBrokerMcpCallLog.d.ts.map

package/dist/runtime/engineBrokerMcpCallLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineBrokerMcpCallLog.d.ts","sourceRoot":"","sources":["../../src/runtime/engineBrokerMcpCallLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,8BAA8B,cAAc,CAAC;AAC1D,eAAO,MAAM,gCAAgC,gBAAgB,CAAC;AAC9D,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,QAAsD,CAAC;AAG/F,qGAAqG;AACrG,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,qEAAsE,CAAC;AACrH,MAAM,MAAM,4BAA4B,GAAG,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9F,sKAAsK;AACtK,MAAM,MAAM,iCAAiC,GAAG,QAAQ,CAAC,MAAM,CAAC,4BAA4B,EAAE,MAAM,CAAC,CAAC,CAAC;AAEvG,MAAM,MAAM,8BAA8B,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAC/F,6HAA6H;AAC7H,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AACzF;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAAE,CAAC,CAAC;AAC3J;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,gCAAgC,CAAC;IAAC,QAAQ,CAAC,EAAE,iCAAiC,CAAA;CAAE,CAAC,CAAC;AAElQ,kHAAkH;AAClH,MAAM,WAAW,yBAAyB;IAAG,MAAM,IAAI,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE;AAE5E,qHAAqH;AACrH,MAAM,WAAW,2BAA2B;IAAG,OAAO,IAAI,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE;AAY/E,qBAAa,sBAAsB;IAErB,OAAO,CAAC,QAAQ,CAAC,GAAG;IADhC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;gBACvB,GAAG,GAAE,MAAM,MAAiB;IAEzD,8FAA8F;IAC9F,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAC1B,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAE3B,qGAAqG;IACrG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,yBAAyB;IA8B9E;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,2BAA2B;IAavD;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,4BAA4B,GAAG,IAAI;IAElE,yGAAyG;IACzG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAEjC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,8BAA8B,GAAG,SAAS;CAmBpE"}

package/dist/runtime/engineBrokerMcpCallLog.js

@@ -0,0 +1,219 @@
+/**
+ * The in-flight MCP tool calls of one brokered turn.
+ *
+ * Daimon writes a tool receipt only when a call *completes*, so a call that
+ * started and never returned is byte-identical, in every artifact, to a call
+ * that was never made. A live Grok turn stopped acting after its eighth
+ * provider response and was killed by the trial deadline seven minutes later
+ * with the proxy's per-request ledger reporting `open: 0` — every provider
+ * request closed — which leaves exactly one unlit path: a tool call the worker
+ * issued and the facade never answered.
+ *
+ * This is that light, and it follows the per-request ledger's rules rather
+ * than inventing its own:
+ *
+ * - **names and timings only.** The tool name off the JSON-RPC envelope and
+ *   two clocks. Never arguments, never a result, never a session id, never a
+ *   capability or bearer. A name that is not a plain short identifier is
+ *   recorded as {@link ENGINE_BROKER_MCP_CALL_INVALID} rather than passed
+ *   through, and the list is bounded at
+ *   {@link ENGINE_BROKER_MCP_OUTSTANDING_MAX} with
+ *   {@link ENGINE_BROKER_MCP_CALL_TRUNCATED} as its last entry.
+ * - **absence stays absence.** A turn the log never opened observes as
+ *   `undefined`; a turn that made no call observes `started: 0`, which is not
+ *   the same statement as an answered call. A POST whose body the facade could
+ *   not read counts in `undecoded` and never as a call with a name, because a
+ *   fabricated name is byte-identical to a measured one — and because "zero
+ *   calls started" is exactly the reading this instrument exists to make
+ *   trustworthy.
+ * - **it cannot fail a turn.** Every operation here is arithmetic over a map,
+ *   the one parse is wrapped, and the facade treats a missing handle as a
+ *   no-op.
+ *
+ * The same map carries the facade's *other* channel, and for the same reason.
+ * A `tools/call` is a POST that answers; the standalone `GET` SSE tunnel the
+ * Streamable HTTP transport opens once per session is the route a server
+ * notification or progress frame takes, and it stays open for the whole
+ * session by design. A worker parked reading that tunnel is, in every artifact
+ * the broker writes, indistinguishable from a worker doing nothing at all:
+ * every provider request closed, every tool call answered, and the turn idle
+ * until its deadline. {@link EngineBrokerMcpCallLog.openTunnel} records the
+ * lifecycle — how many the facade relayed, how many ended, and for the ones
+ * still open at seal time how long each has been open and whether the mount
+ * ever pushed a single byte through it. A tunnel held open having delivered
+ * nothing is a different fact from one actively carrying frames, and it is the
+ * difference that decides whether the tunnel is the blocker.
+ *
+ * Observing is all it does. The facade's behaviour is unchanged: nothing here
+ * closes, times out or refuses a tunnel, because an instrument that tore down
+ * the stream would destroy the evidence it exists to gather.
+ *
+ * "Answered" means the facade wrote a complete response back to the worker —
+ * the relay reached its own `end()`. A relay that was torn down (the worker
+ * died, the tunnel broke, the turn aborted) did *not* answer, so its calls stay
+ * outstanding with the elapsed time they had reached. That is the whole point:
+ * the turn's death must not retroactively mark the call it was blocked on as
+ * finished.
+ */
+/**
+ * The same map carries the facade's *refusals*, for the sharpest form of the
+ * same problem. A refused request never reaches the relay at all, so a turn
+ * every one of whose requests was 403'd sealed as `answered == started,
+ * outstanding: []` — byte-identical to a healthy turn, which is precisely the
+ * reading this instrument exists to make trustworthy. The reason class is what
+ * makes it actionable: an exhausted per-turn capability budget — the facade's
+ * `ENGINE_BROKER_MCP_CAPABILITY_REQUESTS`, derived from the compiled turn
+ * bound times what a round may spend — is a different fault from a mount that
+ * was never registered, and both differ from a worker asking for a route the
+ * facade does not serve. Counts only, keyed by a closed vocabulary:
+ * never the token, the capability, the URL or the body. A refusal the facade
+ * cannot attribute to a turn — a bearer no live grant matches — is recorded
+ * nowhere, because attributing it to a turn would be inventing the fact.
+ */
+export const ENGINE_BROKER_MCP_OUTSTANDING_MAX = 16;
+export const ENGINE_BROKER_MCP_CALL_INVALID = "<invalid>";
+export const ENGINE_BROKER_MCP_CALL_TRUNCATED = "<truncated>";
+/** A plain short identifier, or one of the two sentinels above. */
+export const ENGINE_BROKER_MCP_CALL_NAME = /^(?:<invalid>|<truncated>|[A-Za-z0-9_.-]{1,64})$/u;
+const TOOL_NAME = /^[A-Za-z0-9_.-]{1,64}$/u;
+/** Open GET tunnels reported: a session opens one, so more than a handful is already the anomaly. */
+export const ENGINE_BROKER_MCP_TUNNEL_MAX = 8;
+/**
+ * Why the facade refused one relayed request, as a closed vocabulary:
+ * - `route`: a path or method the facade does not serve.
+ * - `expired`: the turn capability's TTL had passed.
+ * - `exhausted`: the turn capability's request budget was spent.
+ * - `unrouted`: a live capability whose turn has no registered mount.
+ * - `oversized`: a POST body past the facade's own request bound.
+ */
+export const ENGINE_BROKER_MCP_REFUSAL_REASONS = ["route", "expired", "exhausted", "unrouted", "oversized"];
+const INERT = { answer: () => undefined, close: () => undefined };
+const INERT_TUNNEL = { deliver: () => undefined, close: () => undefined };
+const noRefusals = () => ({ route: 0, expired: 0, exhausted: 0, unrouted: 0, oversized: 0 });
+export class EngineBrokerMcpCallLog {
+    now;
+    turns = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** A turn the facade registered. Re-opening an id resets it: a turn id is unique per turn. */
+    open(turnId) { this.turns.set(turnId, { started: 0, answered: 0, undecoded: 0, live: new Set(), ended: [], tunnelsOpened: 0, tunnelsClosed: 0, tunnelsDelivered: 0, openTunnels: new Set(), refusals: noRefusals() }); }
+    close(turnId) { this.turns.delete(turnId); }
+    /** A POST body the facade is about to relay. Anything that is not a `tools/call` records nothing. */
+    begin(turnId, body) {
+        const log = this.turns.get(turnId);
+        if (log === undefined || body === undefined || body.byteLength === 0)
+            return INERT;
+        const names = toolCallNames(body);
+        if (names === undefined) {
+            log.undecoded += 1;
+            return INERT;
+        }
+        if (names.length === 0)
+            return INERT;
+        const startedAt = this.now();
+        const records = names.map((name) => ({ name, startedAt }));
+        log.started += records.length;
+        for (const record of records)
+            log.live.add(record);
+        let settled = false;
+        return {
+            answer: () => {
+                if (settled)
+                    return;
+                settled = true;
+                log.answered += records.length;
+                for (const record of records)
+                    log.live.delete(record);
+            },
+            close: () => {
+                if (settled)
+                    return;
+                settled = true;
+                const endedAt = this.now();
+                for (const record of records) {
+                    log.live.delete(record);
+                    record.endedAt = endedAt;
+                    // Retain only as many as can be reported; the earliest are the ones
+                    // a hang is about, so a later flood cannot displace them.
+                    if (log.ended.length < ENGINE_BROKER_MCP_OUTSTANDING_MAX)
+                        log.ended.push(record);
+                }
+            }
+        };
+    }
+    /**
+     * A GET SSE tunnel the facade is about to relay. Counted when it opens, not
+     * when it succeeds: a tunnel the mount refused still ends, so `opened` and
+     * `closed` stay a pair and an open one is exactly `opened - closed`.
+     */
+    openTunnel(turnId) {
+        const log = this.turns.get(turnId);
+        if (log === undefined)
+            return INERT_TUNNEL;
+        const record = { openedAt: this.now(), delivered: false };
+        log.tunnelsOpened += 1;
+        log.openTunnels.add(record);
+        let ended = false;
+        return {
+            deliver: () => { if (record.delivered)
+                return; record.delivered = true; log.tunnelsDelivered += 1; },
+            close: () => { if (ended)
+                return; ended = true; log.tunnelsClosed += 1; log.openTunnels.delete(record); }
+        };
+    }
+    /**
+     * A request the facade refused before it could ever be relayed. A refusal it
+     * cannot attribute to a turn is never recorded against one, so an unknown
+     * turn is a no-op here exactly as every other operation is.
+     */
+    refuse(turnId, reason) { const log = this.turns.get(turnId); if (log !== undefined)
+        log.refusals[reason] += 1; }
+    /** A POST whose body the facade refused to read (over its own bound), which is a call it cannot name. */
+    undecodable(turnId) { const log = this.turns.get(turnId); if (log !== undefined)
+        log.undecoded += 1; }
+    observe(turnId) {
+        const log = this.turns.get(turnId);
+        if (log === undefined)
+            return undefined;
+        const at = this.now();
+        const pending = [...log.live, ...log.ended].sort((left, right) => left.startedAt - right.startedAt);
+        const outstanding = pending.map((record) => ({ name: record.name, outstandingMs: Math.max(0, (record.endedAt ?? at) - record.startedAt) }));
+        const open = [...log.openTunnels]
+            .sort((left, right) => left.openedAt - right.openedAt)
+            .slice(0, ENGINE_BROKER_MCP_TUNNEL_MAX)
+            .map((record) => ({ openMs: Math.max(0, at - record.openedAt), delivered: record.delivered }));
+        return {
+            started: log.started, answered: log.answered, undecoded: log.undecoded,
+            refusals: { ...log.refusals },
+            tunnels: { opened: log.tunnelsOpened, closed: log.tunnelsClosed, delivered: log.tunnelsDelivered, open },
+            outstanding: outstanding.length > ENGINE_BROKER_MCP_OUTSTANDING_MAX
+                ? [...outstanding.slice(0, ENGINE_BROKER_MCP_OUTSTANDING_MAX - 1), { name: ENGINE_BROKER_MCP_CALL_TRUNCATED, outstandingMs: 0 }]
+                : outstanding
+        };
+    }
+}
+/**
+ * The tool names one JSON-RPC POST asks for: `undefined` when the body did not
+ * decode at all (which is a fact of its own, not zero calls), `[]` when it
+ * decoded and asked for no tool. A batch names each of its calls.
+ */
+function toolCallNames(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const entries = Array.isArray(parsed) ? parsed : [parsed];
+    const names = [];
+    for (const entry of entries) {
+        if (!isRecord(entry) || entry.method !== "tools/call")
+            continue;
+        const name = isRecord(entry.params) ? entry.params.name : undefined;
+        names.push(typeof name === "string" && TOOL_NAME.test(name) ? name : ENGINE_BROKER_MCP_CALL_INVALID);
+    }
+    return names;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/runtime/engineBrokerMcpFacade.d.ts

@@ -0,0 +1,56 @@
+import { type ServerResponse } from "node:http";
+import { type EngineBrokerMcpCallObservation } from "./engineBrokerMcpCallLog.js";
+export declare const ENGINE_BROKER_MCP_FACADE_PORT = 43124;
+/** Requests one worker round may legitimately make: its `search_tool`, its `use_tool`, and one spare for a retry or a second discovery. */
+export declare const ENGINE_BROKER_MCP_ROUND_REQUESTS = 3;
+/** The session's fixed cost, once per turn: `initialize`, `notifications/initialized`, `tools/list`, the standalone GET tunnel, the closing DELETE. */
+export declare const ENGINE_BROKER_MCP_SESSION_REQUESTS = 5;
+/**
+ * Requests one turn capability may spend, across all three methods — *derived*
+ * from the compiled turn bound rather than chosen.
+ *
+ * It was 128, and a legitimate 48-round wake needs ~101 of them: a worker's
+ * round is a `search_tool` and a `use_tool`, so the first round that also
+ * retries, or looks something up twice, eats the margin. A bound that can be
+ * predicted to bite mid-turn is not a bound, it is a 403 storm waiting for a
+ * real wake — and a number raised until it feels comfortable is not one
+ * either, because the budget exists to cap a *compromised* worker.
+ *
+ * So the two numbers that must agree are kept in one place: the launcher's
+ * `--max-turns` backstop ({@link GROK_WORKER_MAX_TURNS}) times what a round
+ * may legitimately spend, plus the session's fixed cost. Raising the turn
+ * bound raises this with it, and a compromised worker still gets exactly three
+ * MCP calls per round it was compiled to take and not one more. The arithmetic
+ * is spelled out rather than folded into a literal so it can be audited: the
+ * two multiplicands above each say what they are.
+ */
+export declare const ENGINE_BROKER_MCP_CAPABILITY_REQUESTS: number;
+export declare const ENGINE_BROKER_MCP_CAPABILITY_TTL_MS: number;
+export declare function startEngineBrokerMcpFacade(): Promise<{
+    register(agentId: string, turnId: string, endpoint: string): string;
+    revoke(turnId: string): void;
+    /**
+     * What the facade saw of this turn's tool calls, GET tunnels and refusals,
+     * or `undefined` for a turn
+     * it never registered. Read on the failure path, before `revoke`.
+     */
+    observe: (turnId: string) => EngineBrokerMcpCallObservation | undefined;
+    close: () => Promise<void>;
+}>;
+/**
+ * Waits for a backpressured tunnel to drain, or for the tunnel to end —
+ * whichever happens first, but always one of them.
+ *
+ * A bare `once("drain")` never settles for a client that hung up mid-write:
+ * `drain` cannot fire on a socket nobody is reading, and neither the
+ * response's own `close` nor the turn's abort woke that await. The GET SSE
+ * tunnel stays open for a whole session, so the handler — and the upstream
+ * call it was relaying — leaked for the life of the broker process, with no
+ * refusal, no status and no line anywhere to read. Every outcome settles this
+ * now, and every outcome but an actual drain *rejects*, so the caller tears
+ * the tunnel down instead of writing into a socket that is gone.
+ *
+ * Exported for its own test: a hang is only observable from inside.
+ */
+export declare function awaitMcpTunnelDrain(response: ServerResponse, signal: AbortSignal): Promise<void>;
+//# sourceMappingURL=engineBrokerMcpFacade.d.ts.map

package/dist/runtime/engineBrokerMcpFacade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineBrokerMcpFacade.d.ts","sourceRoot":"","sources":["../../src/runtime/engineBrokerMcpFacade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAIpF,OAAO,EAA0B,KAAK,8BAA8B,EAAuE,MAAM,6BAA6B,CAAC;AA4C/K,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,2IAA2I;AAC3I,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAClD,uJAAuJ;AACvJ,eAAO,MAAM,kCAAkC,IAAI,CAAC;AACpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qCAAqC,QAAgG,CAAC;AACnJ,eAAO,MAAM,mCAAmC,QAAc,CAAC;AAI/D,wBAAsB,0BAA0B;sBA0G1B,MAAM,UAAU,MAAM,YAAY,MAAM,GAAG,MAAM;mBAQpD,MAAM,GAAG,IAAI;IAM5B;;;;OAIG;sBACe,MAAM,KAAG,8BAA8B,GAAG,SAAS;iBACpD,OAAO,CAAC,IAAI,CAAC;GAUjC;AAoED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAehG"}