@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/engineBrokerProtocol.d.ts

@@ -0,0 +1,135 @@
+import { type EngineBrokerInferenceRequest, type EngineBrokerInferenceResponse } from "./engineBrokerInferenceProtocol.js";
+import { type EngineBrokerMcpCallObservation } from "./engineBrokerMcpCallLog.js";
+import { type EngineBrokerTurnAccounting, type EngineBrokerTurnLimitOverrides } from "./engineBrokerTurnAccounting.js";
+/**
+ * Control protocol v2. Both ends ship in the same Daimon package and image
+ * (organization runtime client, broker service), so the wire moved to v2 in
+ * one step: v1 frames are refused. v1 survives only as a *durable record*
+ * shape, which {@link parseEngineBrokerV1TerminalResponse} still reads so
+ * turns sealed before the upgrade keep replaying.
+ */
+declare const VERSION: "noopolis.daimon.engine-broker.v2";
+export declare const ENGINE_BROKER_VERSION: "noopolis.daimon.engine-broker.v2";
+declare const V1: "noopolis.daimon.engine-broker.v1";
+export declare const ENGINE_BROKER_MAX_FRAME_BYTES = 1048576;
+export type EngineBrokerRequest = Readonly<{
+    version: typeof VERSION;
+    kind: "health";
+    requestId: string;
+}> | Readonly<{
+    version: typeof VERSION;
+    kind: "start_turn";
+    requestId: string;
+    turnId: string;
+    agentId: string;
+    wakeId: string;
+    prompt: string;
+    mcpEndpoint: string;
+    limits?: EngineBrokerTurnLimitOverrides;
+}> | Readonly<{
+    version: typeof VERSION;
+    kind: "cancel_turn";
+    requestId: string;
+    turnId: string;
+}> | EngineBrokerInferenceRequest;
+/**
+ * `reason` is the worker's own last words (`engineBrokerNativeClient.ts`),
+ * already redacted and flattened to one bounded line by the broker. It is the
+ * only field a failed turn carries that the worker itself wrote, so it is
+ * optional, bounded, control-character free, and admitted only for the
+ * statuses where a worker actually ran and spoke.
+ */
+export interface EngineBrokerFailureDiagnostic {
+    status: string;
+    stage: string;
+    failureClass: string;
+    profileApplied: boolean;
+    reason?: string;
+    exitCode: number;
+    termSignal: number;
+    workerPid: number;
+    workerUid: number;
+    startTicks: string;
+}
+export declare const ENGINE_BROKER_MAX_DIAGNOSTIC_REASON_BYTES = 768;
+export type EngineBrokerResponse = Readonly<{
+    version: typeof VERSION;
+    kind: "ready";
+    requestId: string;
+    brokerUid: 2100;
+    providerProxyPort: 43123;
+    mcpFacadePort: 43124;
+    registrations: number;
+    credentialStale: false;
+    realmLease: true;
+    workerIsolation: true;
+}> | Readonly<{
+    version: typeof VERSION;
+    kind: "accepted";
+    requestId: string;
+    turnId: string;
+}> | (Readonly<{
+    version: typeof VERSION;
+    kind: "completed";
+    requestId: string;
+    turnId: string;
+    text: string;
+    workerPid: number;
+    workerUid: number;
+    workerStartTime: string;
+}> & EngineBrokerTurnAccounting) | (Readonly<{
+    version: typeof VERSION;
+    kind: "failed";
+    requestId: string;
+    turnId: string;
+    code: EngineBrokerFailureCode;
+    diagnostic?: EngineBrokerFailureDiagnostic;
+    mcpCalls?: EngineBrokerMcpCallObservation;
+}> & EngineBrokerTurnAccounting) | EngineBrokerInferenceResponse;
+/**
+ * The one name for a fenced credential realm. The turn's failure code, the
+ * proxy's refusal reason on a worker request, and the grant path's 401 body
+ * (`GROK_INFERENCE_AUTH_STALE_BODY`) all say this same word, so an operator
+ * greps one string across every surface instead of three spellings of it.
+ */
+export declare const ENGINE_BROKER_AUTH_STALE: "auth_stale";
+export declare const ENGINE_BROKER_FAILURE_CODES: readonly ["auth_stale", "cancelled", "engine_failed", "invalid_request", "limit_exceeded", "turn_conflict", "unavailable"];
+export type EngineBrokerFailureCode = (typeof ENGINE_BROKER_FAILURE_CODES)[number];
+export type EngineBrokerTerminalResponse = Extract<EngineBrokerResponse, {
+    kind: "completed" | "failed";
+}>;
+type V1Completed = Readonly<{
+    version: typeof V1;
+    kind: "completed";
+    requestId: string;
+    turnId: string;
+    text: string;
+    workerPid: number;
+    workerUid: number;
+    workerStartTime: string;
+}>;
+type V1Failed = Readonly<{
+    version: typeof V1;
+    kind: "failed";
+    requestId: string;
+    turnId: string;
+    code: Exclude<EngineBrokerFailureCode, "limit_exceeded">;
+    diagnostic?: EngineBrokerFailureDiagnostic;
+}>;
+export type EngineBrokerV1TerminalResponse = V1Completed | V1Failed;
+export declare function parseEngineBrokerRequest(value: unknown): EngineBrokerRequest;
+export declare function parseEngineBrokerResponse(value: unknown): EngineBrokerResponse;
+/**
+ * A terminal response persisted by a pre-v2 broker: the v1 field sets exactly,
+ * with no accounting. Accepted only from the durable turn registry, never from
+ * the wire.
+ */
+export declare function parseEngineBrokerV1TerminalResponse(value: unknown): EngineBrokerV1TerminalResponse;
+export declare function encodeEngineBrokerFrame(value: EngineBrokerRequest | EngineBrokerResponse): Buffer;
+export declare class EngineBrokerFrameDecoder {
+    private buffered;
+    push(chunk: Uint8Array): unknown[];
+    finish(): void;
+}
+export {};
+//# sourceMappingURL=engineBrokerProtocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engineBrokerProtocol.d.ts","sourceRoot":"","sources":["../../src/runtime/engineBrokerProtocol.ts"],"names":[],"mappings":"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"}

package/dist/runtime/engineBrokerProtocol.js

@@ -0,0 +1,274 @@
+import { isEngineBrokerInferenceRequestKind, isEngineBrokerInferenceResponseKind, parseEngineBrokerInferenceRequest, parseEngineBrokerInferenceResponse } from "./engineBrokerInferenceProtocol.js";
+import { ENGINE_BROKER_MCP_CALL_NAME, ENGINE_BROKER_MCP_OUTSTANDING_MAX, ENGINE_BROKER_MCP_REFUSAL_REASONS, ENGINE_BROKER_MCP_TUNNEL_MAX } from "./engineBrokerMcpCallLog.js";
+import { parseEngineBrokerTurnAccounting, parseEngineBrokerTurnLimitOverrides } from "./engineBrokerTurnAccounting.js";
+/**
+ * Control protocol v2. Both ends ship in the same Daimon package and image
+ * (organization runtime client, broker service), so the wire moved to v2 in
+ * one step: v1 frames are refused. v1 survives only as a *durable record*
+ * shape, which {@link parseEngineBrokerV1TerminalResponse} still reads so
+ * turns sealed before the upgrade keep replaying.
+ */
+const VERSION = "noopolis.daimon.engine-broker.v2";
+export const ENGINE_BROKER_VERSION = VERSION;
+const V1 = "noopolis.daimon.engine-broker.v1";
+export const ENGINE_BROKER_MAX_FRAME_BYTES = 1_048_576;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+export const ENGINE_BROKER_MAX_DIAGNOSTIC_REASON_BYTES = 768;
+/**
+ * The one name for a fenced credential realm. The turn's failure code, the
+ * proxy's refusal reason on a worker request, and the grant path's 401 body
+ * (`GROK_INFERENCE_AUTH_STALE_BODY`) all say this same word, so an operator
+ * greps one string across every surface instead of three spellings of it.
+ */
+export const ENGINE_BROKER_AUTH_STALE = "auth_stale";
+export const ENGINE_BROKER_FAILURE_CODES = [ENGINE_BROKER_AUTH_STALE, "cancelled", "engine_failed", "invalid_request", "limit_exceeded", "turn_conflict", "unavailable"];
+const ACCOUNTING = ["outcome", "usage", "model", "requests", "limitReason"];
+const record = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value) || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null))
+        throw new TypeError("invalid broker frame");
+    return value;
+};
+const exact = (value, fields) => {
+    if (Object.keys(value).length !== fields.length || fields.some((field) => !Object.hasOwn(value, field)))
+        throw new TypeError("invalid broker frame");
+};
+const text = (value, maxBytes) => {
+    if (typeof value !== "string" || value.length === 0 || Buffer.byteLength(value, "utf8") > maxBytes)
+        throw new TypeError("invalid broker frame");
+    return value;
+};
+const id = (value) => { const result = text(value, 128); if (!ID.test(result))
+    throw new TypeError("invalid broker frame"); return result; };
+const version = (value) => { if (value !== VERSION)
+    throw new TypeError("invalid broker frame"); return VERSION; };
+export function parseEngineBrokerRequest(value) {
+    const input = record(value);
+    version(input.version);
+    if (input.kind === "health") {
+        exact(input, ["version", "kind", "requestId"]);
+        return { version: VERSION, kind: "health", requestId: id(input.requestId) };
+    }
+    if (input.kind === "start_turn") {
+        const fields = ["version", "kind", "requestId", "turnId", "agentId", "wakeId", "prompt", "mcpEndpoint"];
+        exact(input, input.limits === undefined ? fields : [...fields, "limits"]);
+        const mcpEndpoint = text(input.mcpEndpoint, 2048);
+        const url = new URL(mcpEndpoint);
+        if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || url.pathname !== "/mcp")
+            throw new TypeError("invalid broker frame");
+        let limits;
+        if (input.limits !== undefined) {
+            try {
+                limits = parseEngineBrokerTurnLimitOverrides(input.limits);
+            }
+            catch {
+                throw new TypeError("invalid broker frame");
+            }
+        }
+        return { version: VERSION, kind: "start_turn", requestId: id(input.requestId), turnId: id(input.turnId), agentId: id(input.agentId), wakeId: id(input.wakeId), prompt: text(input.prompt, 65_536), mcpEndpoint, ...(limits === undefined ? {} : { limits }) };
+    }
+    if (input.kind === "cancel_turn") {
+        exact(input, ["version", "kind", "requestId", "turnId"]);
+        return { version: VERSION, kind: "cancel_turn", requestId: id(input.requestId), turnId: id(input.turnId) };
+    }
+    if (isEngineBrokerInferenceRequestKind(input.kind))
+        return parseEngineBrokerInferenceRequest(input, id(input.requestId), VERSION);
+    throw new TypeError("invalid broker frame");
+}
+export function parseEngineBrokerResponse(value) {
+    const input = record(value);
+    version(input.version);
+    if (input.kind === "ready") {
+        exact(input, ["version", "kind", "requestId", "brokerUid", "providerProxyPort", "mcpFacadePort", "registrations", "credentialStale", "realmLease", "workerIsolation"]);
+        if (input.brokerUid !== 2100 || input.providerProxyPort !== 43123 || input.mcpFacadePort !== 43124 || !Number.isSafeInteger(input.registrations) || input.registrations < 1 || input.credentialStale !== false || input.realmLease !== true || input.workerIsolation !== true)
+            throw new TypeError("invalid broker frame");
+        return { version: VERSION, kind: "ready", requestId: id(input.requestId), brokerUid: 2100, providerProxyPort: 43123, mcpFacadePort: 43124, registrations: input.registrations, credentialStale: false, realmLease: true, workerIsolation: true };
+    }
+    if (input.kind === "accepted") {
+        exact(input, ["version", "kind", "requestId", "turnId"]);
+        return { version: VERSION, kind: "accepted", requestId: id(input.requestId), turnId: id(input.turnId) };
+    }
+    if (input.kind === "completed" || input.kind === "failed")
+        return parseTerminal(input, VERSION);
+    if (isEngineBrokerInferenceResponseKind(input.kind))
+        return parseEngineBrokerInferenceResponse(input, id(input.requestId), VERSION);
+    throw new TypeError("invalid broker frame");
+}
+/**
+ * A terminal response persisted by a pre-v2 broker: the v1 field sets exactly,
+ * with no accounting. Accepted only from the durable turn registry, never from
+ * the wire.
+ */
+export function parseEngineBrokerV1TerminalResponse(value) {
+    const input = record(value);
+    if (input.version !== V1 || (input.kind !== "completed" && input.kind !== "failed"))
+        throw new TypeError("invalid broker frame");
+    return parseTerminal(input, V1);
+}
+function parseTerminal(input, expected) {
+    const accounting = expected === VERSION ? ACCOUNTING : [];
+    if (input.kind === "completed") {
+        exact(input, ["version", "kind", "requestId", "turnId", "text", "workerPid", "workerUid", "workerStartTime", ...accounting]);
+        if (!Number.isSafeInteger(input.workerPid) || input.workerPid < 1 || !Number.isSafeInteger(input.workerUid) || input.workerUid < 1)
+            throw new TypeError("invalid broker frame");
+        const base = { kind: "completed", requestId: id(input.requestId), turnId: id(input.turnId), text: text(input.text, 262_144), workerPid: input.workerPid, workerUid: input.workerUid, workerStartTime: id(input.workerStartTime) };
+        return expected === VERSION ? { version: VERSION, ...base, ...parseEngineBrokerTurnAccounting(input, "completed") } : { version: V1, ...base };
+    }
+    // `mcpCalls` is the broker's own observation of the worker's tool calls
+    // (`engineBrokerMcpCallLog.ts`), additive in v2 and never part of a v1
+    // record, which predates the instrument entirely.
+    if (expected === V1 && input.mcpCalls !== undefined)
+        throw new TypeError("invalid broker frame");
+    const fields = ["version", "kind", "requestId", "turnId", "code", ...accounting, ...(input.diagnostic === undefined ? [] : ["diagnostic"]), ...(input.mcpCalls === undefined ? [] : ["mcpCalls"])];
+    exact(input, fields);
+    const codes = expected === VERSION ? ENGINE_BROKER_FAILURE_CODES : ENGINE_BROKER_FAILURE_CODES.filter((code) => code !== "limit_exceeded");
+    if (!codes.includes(input.code))
+        throw new TypeError("invalid broker frame");
+    let diagnostic;
+    if (input.diagnostic !== undefined) {
+        const value = record(input.diagnostic);
+        const fields = ["status", "stage", "failureClass", "profileApplied", "exitCode", "termSignal", "workerPid", "workerUid", "startTicks"];
+        exact(value, value.reason === undefined ? fields : [...fields, "reason"]);
+        if (value.reason !== undefined && (typeof value.reason !== "string" || value.reason.length === 0 || Buffer.byteLength(value.reason, "utf8") > ENGINE_BROKER_MAX_DIAGNOSTIC_REASON_BYTES || /[\u0000-\u001f\u007f]/u.test(value.reason)))
+            throw new TypeError("invalid broker frame");
+        const status = ["prelaunch_failed", "worker_failed", "output_failed", "cancelled"], stage = ["peer", "request", "registration", "executable", "exec", "wait", "output", "attestation"], failureClass = ["peer", "protocol", "registration", "executable", "exec", "wait", "output_limit", "cancelled", "profile_missing", "profile_invalid"];
+        if (!status.includes(value.status) || !stage.includes(value.stage) || !failureClass.includes(value.failureClass) || typeof value.profileApplied !== "boolean" || ![value.exitCode, value.termSignal, value.workerPid, value.workerUid].every(Number.isSafeInteger) || typeof value.startTicks !== "string" || !/^(0|[1-9][0-9]*)$/u.test(value.startTicks) || !closedDiagnostic(value))
+            throw new TypeError("invalid broker frame");
+        diagnostic = value;
+    }
+    const base = { kind: "failed", requestId: id(input.requestId), turnId: id(input.turnId), code: input.code, ...(diagnostic ? { diagnostic } : {}) };
+    if (expected === V1)
+        return { version: V1, ...base };
+    const accountingValue = parseEngineBrokerTurnAccounting(input, "failed");
+    if ((input.code === "limit_exceeded") !== (accountingValue.limitReason !== "none"))
+        throw new TypeError("invalid broker frame");
+    const mcpCalls = input.mcpCalls === undefined ? undefined : parseMcpCallObservation(input.mcpCalls);
+    return { version: VERSION, ...base, ...(mcpCalls === undefined ? {} : { mcpCalls }), ...accountingValue };
+}
+/**
+ * Names and timings, bounded, and internally consistent: a report can never
+ * claim more answered calls than started ones, nor more outstanding ones than
+ * started minus answered. Every count is its own measurement, so a missing
+ * field is refused rather than defaulted — a zero the broker did not measure
+ * would read exactly like one it did.
+ */
+function parseMcpCallObservation(value) {
+    const input = record(value);
+    // `tunnels` is optional for one reason only: a turn sealed before the GET
+    // tunnel was observed carries no such member, and its record must still
+    // replay. Absence there means "the instrument did not exist", never zero.
+    exact(input, ["started", "answered", "undecoded", "outstanding", ...(input.tunnels === undefined ? [] : ["tunnels"]), ...(input.refusals === undefined ? [] : ["refusals"])]);
+    const started = input.started, answered = input.answered, undecoded = input.undecoded;
+    if (![started, answered, undecoded].every((count) => Number.isSafeInteger(count) && count >= 0))
+        throw new TypeError("invalid broker frame");
+    if (!Array.isArray(input.outstanding) || input.outstanding.length > ENGINE_BROKER_MCP_OUTSTANDING_MAX)
+        throw new TypeError("invalid broker frame");
+    const outstanding = input.outstanding.map((entry) => {
+        const call = record(entry);
+        exact(call, ["name", "outstandingMs"]);
+        if (typeof call.name !== "string" || !ENGINE_BROKER_MCP_CALL_NAME.test(call.name))
+            throw new TypeError("invalid broker frame");
+        if (!Number.isSafeInteger(call.outstandingMs) || call.outstandingMs < 0)
+            throw new TypeError("invalid broker frame");
+        return { name: call.name, outstandingMs: call.outstandingMs };
+    });
+    if (answered > started || outstanding.length > started - answered)
+        throw new TypeError("invalid broker frame");
+    const tunnels = input.tunnels === undefined ? undefined : parseMcpTunnelObservation(input.tunnels);
+    const refusals = input.refusals === undefined ? undefined : parseMcpRefusalObservation(input.refusals);
+    return { started: started, answered: answered, undecoded: undecoded, outstanding, ...(tunnels === undefined ? {} : { tunnels }), ...(refusals === undefined ? {} : { refusals }) };
+}
+/**
+ * The refused requests, by reason class: one count per closed reason, all of
+ * them required once the member is present. Optional for the same single
+ * reason `tunnels` is — a turn sealed before the facade counted its refusals
+ * must still replay — so its absence means "not measured" and never zero, and
+ * a partial member is refused rather than zero-filled.
+ */
+function parseMcpRefusalObservation(value) {
+    const input = record(value);
+    exact(input, ENGINE_BROKER_MCP_REFUSAL_REASONS);
+    for (const reason of ENGINE_BROKER_MCP_REFUSAL_REASONS) {
+        if (!Number.isSafeInteger(input[reason]) || input[reason] < 0)
+            throw new TypeError("invalid broker frame");
+    }
+    return Object.fromEntries(ENGINE_BROKER_MCP_REFUSAL_REASONS.map((reason) => [reason, input[reason]]));
+}
+/**
+ * The GET SSE tunnels, under the call observation's rules: counts and elapsed
+ * milliseconds, bounded, and internally consistent. A tunnel cannot close
+ * before it opened, cannot deliver without having opened, and no more can be
+ * reported open than `opened - closed` — a report claiming otherwise is a
+ * frame, not a measurement.
+ */
+function parseMcpTunnelObservation(value) {
+    const input = record(value);
+    exact(input, ["opened", "closed", "delivered", "open"]);
+    const opened = input.opened, closed = input.closed, delivered = input.delivered;
+    if (![opened, closed, delivered].every((count) => Number.isSafeInteger(count) && count >= 0))
+        throw new TypeError("invalid broker frame");
+    if (closed > opened || delivered > opened)
+        throw new TypeError("invalid broker frame");
+    if (!Array.isArray(input.open) || input.open.length > ENGINE_BROKER_MCP_TUNNEL_MAX || input.open.length > opened - closed)
+        throw new TypeError("invalid broker frame");
+    const open = input.open.map((entry) => {
+        const tunnel = record(entry);
+        exact(tunnel, ["openMs", "delivered"]);
+        if (!Number.isSafeInteger(tunnel.openMs) || tunnel.openMs < 0 || typeof tunnel.delivered !== "boolean")
+            throw new TypeError("invalid broker frame");
+        return { openMs: tunnel.openMs, delivered: tunnel.delivered };
+    });
+    return { opened: opened, closed: closed, delivered: delivered, open };
+}
+function closedDiagnostic(value) {
+    if (value.profileApplied !== false || value.workerPid < 0 || value.workerUid < 0)
+        return false;
+    // Only a worker that ran and wrote something can have said why it failed:
+    // no prelaunch failure and no attestation refusal carries worker words.
+    if (value.reason !== undefined && !((value.status === "worker_failed" && value.stage === "wait") || value.status === "output_failed" || value.status === "cancelled"))
+        return false;
+    const noWorker = value.workerPid === 0 && value.workerUid === 0 && value.startTicks === "0";
+    const worker = value.workerPid > 0 && value.workerUid >= 2200 && value.startTicks !== "0";
+    if (value.status === "prelaunch_failed")
+        return noWorker && { peer: "peer", request: "protocol", registration: "registration", executable: "executable", exec: "exec" }[value.stage] === value.failureClass;
+    if (value.status === "worker_failed" && value.stage === "attestation")
+        return worker && (value.failureClass === "profile_missing" || value.failureClass === "profile_invalid");
+    if (value.status === "worker_failed")
+        return worker && value.stage === "wait" && (value.failureClass === "exec" || value.failureClass === "wait");
+    if (value.status === "output_failed")
+        return worker && value.stage === "output" && value.failureClass === "output_limit";
+    return value.status === "cancelled" && worker && value.stage === "wait" && value.failureClass === "cancelled";
+}
+export function encodeEngineBrokerFrame(value) {
+    const body = Buffer.from(JSON.stringify(value), "utf8");
+    if (body.length > ENGINE_BROKER_MAX_FRAME_BYTES)
+        throw new TypeError("invalid broker frame");
+    const frame = Buffer.allocUnsafe(body.length + 4);
+    frame.writeUInt32BE(body.length);
+    body.copy(frame, 4);
+    return frame;
+}
+export class EngineBrokerFrameDecoder {
+    buffered = Buffer.alloc(0);
+    push(chunk) {
+        this.buffered = Buffer.concat([this.buffered, chunk]);
+        const values = [];
+        while (this.buffered.length >= 4) {
+            const length = this.buffered.readUInt32BE(0);
+            if (length === 0 || length > ENGINE_BROKER_MAX_FRAME_BYTES)
+                throw new TypeError("invalid broker frame");
+            if (this.buffered.length < length + 4)
+                break;
+            const body = this.buffered.subarray(4, length + 4);
+            this.buffered = this.buffered.subarray(length + 4);
+            try {
+                values.push(JSON.parse(body.toString("utf8")));
+            }
+            catch {
+                throw new TypeError("invalid broker frame");
+            }
+        }
+        return values;
+    }
+    finish() { if (this.buffered.length !== 0)
+        throw new TypeError("incomplete broker frame"); }
+}

package/dist/runtime/engineBrokerSealLedger.d.ts

@@ -0,0 +1,70 @@
+import type { EngineBrokerTerminalResponse } from "./engineBrokerProtocol.js";
+/**
+ * The operator-visible half of a sealed terminal turn, as a durable row.
+ *
+ * The seal itself already carries everything an operator needs to read a turn
+ * that stopped acting — the failure code, the worker's own redacted last words,
+ * and `engineBrokerMcpCallLog.ts`'s observation of the tool call the worker was
+ * blocked on. All of it travels in the control-protocol terminal response, and
+ * that response is the one artifact a *hung* turn never produces: the client is
+ * gone before the broker answers, the turn registry record lives in the
+ * broker's own `0700` turn store, and a training slot's control root is tmpfs
+ * that dies with the container. Six live runs reproduced the same signature and
+ * none of them could read the instrument built for it.
+ *
+ * What does survive a slot is the broker's ledger directory: Paideia already
+ * recovers `usage.jsonl` and `requests.jsonl` from it on the failure path. So
+ * this is a third stream beside those two, written by the broker — still the
+ * single sealed usage writer — from the sealed response and nothing else, at
+ * the moment that response is sealed.
+ *
+ * Its rules are the two ledgers' rules:
+ *
+ * - **Numbers, names, timings and closed vocabularies only.** The failure code,
+ *   the accounting, the diagnostic's closed `status`/`stage`/`failure_class`
+ *   and its already-redacted, already-bounded, control-character-free `reason`
+ *   (`engineBrokerNativeClient.ts` produced it; nothing here re-derives it),
+ *   plus tool-call names, GET-tunnel counts and elapsed milliseconds. Never a
+ *   prompt, a body, a
+ *   reply, a bearer, a capability or a session id — none of which the terminal
+ *   response carries in the first place.
+ * - **Absence stays absence.** `mcp` is written only when the facade actually
+ *   observed the turn, `diagnostic` only when the sealed response carried one,
+ *   and `code` only for a failure. A turn that called no tool publishes
+ *   `started: 0`, which is a measurement; a turn the facade never registered
+ *   publishes no `mcp` member at all, which is not.
+ * - **It can never fail a turn.** The row is rendered from an
+ *   already-validated frame and appended through `recordLedgerLines`, which
+ *   swallows every I/O fault.
+ *
+ * A separate stream and a separate `v`, for `turnRequestLedger.ts`'s reason:
+ * Spawnfile's reader pins `noopolis.daimon.turn-usage.v1` and drops any other
+ * `v` outright, and Paideia's request reader refuses a row it cannot type. A
+ * row in a new file is invisible to both.
+ */
+export declare const TURN_SEAL_LEDGER_VERSION: "noopolis.daimon.turn-seal.v1";
+/** Default location: beside `usage.jsonl` and `requests.jsonl`, no new mount. */
+export declare const TURN_SEAL_LEDGER: {
+    readonly version: "noopolis.daimon.turn-seal.v1";
+    readonly directoryPath: "/var/lib/spawnfile/daimon/usage";
+    readonly filePath: "/var/lib/spawnfile/daimon/usage/turns.jsonl";
+    readonly rotatedFilePath: "/var/lib/spawnfile/daimon/usage/turns.jsonl.1";
+    readonly fileMode: 416;
+};
+/** A rendered seal line is bounded by its own contents: a 768-byte reason, 16 bounded names and 8 tunnel timings. */
+export declare const TURN_SEAL_MAX_LINE_BYTES = 8192;
+export type BrokerTurnSealEntry = Readonly<{
+    agent: string;
+    wake: string;
+    at: string;
+}>;
+/**
+ * One newline-terminated row for one sealed terminal turn.
+ *
+ * Every member is copied from the terminal response the protocol already
+ * validated, so this projection cannot widen what the response admits; it is an
+ * allow-list rather than a spread, so a future additive member of the response
+ * does not silently become a ledger field.
+ */
+export declare const renderBrokerTurnSealLine: (terminal: EngineBrokerTerminalResponse, entry: BrokerTurnSealEntry) => string;
+//# sourceMappingURL=engineBrokerSealLedger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engineBrokerSealLedger.d.ts","sourceRoot":"","sources":["../../src/runtime/engineBrokerSealLedger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,wBAAwB,EAAG,8BAAuC,CAAC;AAEhF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,qHAAqH;AACrH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAIxF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GAAI,UAAU,4BAA4B,EAAE,OAAO,mBAAmB,KAAG,MAyDxG,CAAC"}

package/dist/runtime/engineBrokerSealLedger.js

@@ -0,0 +1,123 @@
+import { ENGINE_BROKER_MCP_CALL_NAME, ENGINE_BROKER_MCP_OUTSTANDING_MAX, ENGINE_BROKER_MCP_REFUSAL_REASONS, ENGINE_BROKER_MCP_TUNNEL_MAX } from "./engineBrokerMcpCallLog.js";
+import { TURN_USAGE_LEDGER, TURN_USAGE_MAX_IDENTIFIER_CHARS } from "./turnUsageLedger.js";
+/**
+ * The operator-visible half of a sealed terminal turn, as a durable row.
+ *
+ * The seal itself already carries everything an operator needs to read a turn
+ * that stopped acting — the failure code, the worker's own redacted last words,
+ * and `engineBrokerMcpCallLog.ts`'s observation of the tool call the worker was
+ * blocked on. All of it travels in the control-protocol terminal response, and
+ * that response is the one artifact a *hung* turn never produces: the client is
+ * gone before the broker answers, the turn registry record lives in the
+ * broker's own `0700` turn store, and a training slot's control root is tmpfs
+ * that dies with the container. Six live runs reproduced the same signature and
+ * none of them could read the instrument built for it.
+ *
+ * What does survive a slot is the broker's ledger directory: Paideia already
+ * recovers `usage.jsonl` and `requests.jsonl` from it on the failure path. So
+ * this is a third stream beside those two, written by the broker — still the
+ * single sealed usage writer — from the sealed response and nothing else, at
+ * the moment that response is sealed.
+ *
+ * Its rules are the two ledgers' rules:
+ *
+ * - **Numbers, names, timings and closed vocabularies only.** The failure code,
+ *   the accounting, the diagnostic's closed `status`/`stage`/`failure_class`
+ *   and its already-redacted, already-bounded, control-character-free `reason`
+ *   (`engineBrokerNativeClient.ts` produced it; nothing here re-derives it),
+ *   plus tool-call names, GET-tunnel counts and elapsed milliseconds. Never a
+ *   prompt, a body, a
+ *   reply, a bearer, a capability or a session id — none of which the terminal
+ *   response carries in the first place.
+ * - **Absence stays absence.** `mcp` is written only when the facade actually
+ *   observed the turn, `diagnostic` only when the sealed response carried one,
+ *   and `code` only for a failure. A turn that called no tool publishes
+ *   `started: 0`, which is a measurement; a turn the facade never registered
+ *   publishes no `mcp` member at all, which is not.
+ * - **It can never fail a turn.** The row is rendered from an
+ *   already-validated frame and appended through `recordLedgerLines`, which
+ *   swallows every I/O fault.
+ *
+ * A separate stream and a separate `v`, for `turnRequestLedger.ts`'s reason:
+ * Spawnfile's reader pins `noopolis.daimon.turn-usage.v1` and drops any other
+ * `v` outright, and Paideia's request reader refuses a row it cannot type. A
+ * row in a new file is invisible to both.
+ */
+export const TURN_SEAL_LEDGER_VERSION = "noopolis.daimon.turn-seal.v1";
+/** Default location: beside `usage.jsonl` and `requests.jsonl`, no new mount. */
+export const TURN_SEAL_LEDGER = {
+    version: TURN_SEAL_LEDGER_VERSION,
+    directoryPath: TURN_USAGE_LEDGER.directoryPath,
+    filePath: `${TURN_USAGE_LEDGER.directoryPath}/turns.jsonl`,
+    rotatedFilePath: `${TURN_USAGE_LEDGER.directoryPath}/turns.jsonl.1`,
+    fileMode: TURN_USAGE_LEDGER.fileMode
+};
+/** A rendered seal line is bounded by its own contents: a 768-byte reason, 16 bounded names and 8 tunnel timings. */
+export const TURN_SEAL_MAX_LINE_BYTES = 8_192;
+const bounded = (value) => [...value].slice(0, TURN_USAGE_MAX_IDENTIFIER_CHARS).join("");
+/**
+ * One newline-terminated row for one sealed terminal turn.
+ *
+ * Every member is copied from the terminal response the protocol already
+ * validated, so this projection cannot widen what the response admits; it is an
+ * allow-list rather than a spread, so a future additive member of the response
+ * does not silently become a ledger field.
+ */
+export const renderBrokerTurnSealLine = (terminal, entry) => `${JSON.stringify({
+    v: TURN_SEAL_LEDGER_VERSION,
+    agent: bounded(entry.agent),
+    wake: bounded(entry.wake),
+    engine: "grok",
+    at: entry.at,
+    turn: terminal.turnId,
+    outcome: terminal.outcome,
+    requests: terminal.requests,
+    model: terminal.model,
+    limit_reason: terminal.limitReason,
+    ...(terminal.kind === "failed" ? { code: terminal.code } : {}),
+    ...(terminal.kind === "failed" && terminal.diagnostic !== undefined
+        ? {
+            diagnostic: {
+                status: terminal.diagnostic.status,
+                stage: terminal.diagnostic.stage,
+                failure_class: terminal.diagnostic.failureClass,
+                exit_code: terminal.diagnostic.exitCode,
+                term_signal: terminal.diagnostic.termSignal,
+                ...(terminal.diagnostic.reason === undefined ? {} : { reason: terminal.diagnostic.reason })
+            }
+        }
+        : {}),
+    ...(terminal.kind === "failed" && terminal.mcpCalls !== undefined
+        ? {
+            mcp: {
+                started: terminal.mcpCalls.started,
+                answered: terminal.mcpCalls.answered,
+                undecoded: terminal.mcpCalls.undecoded,
+                outstanding: terminal.mcpCalls.outstanding
+                    .slice(0, ENGINE_BROKER_MCP_OUTSTANDING_MAX)
+                    .map((call) => ({ name: ENGINE_BROKER_MCP_CALL_NAME.test(call.name) ? call.name : "<invalid>", outstanding_ms: call.outstandingMs })),
+                // Every request the facade refused before it could relay it, by reason
+                // class. Without it a turn whose capability was spent seals as
+                // `answered == started, outstanding: []`, which is what a healthy turn
+                // seals as.
+                ...(terminal.mcpCalls.refusals === undefined
+                    ? {}
+                    : { refusals: Object.fromEntries(ENGINE_BROKER_MCP_REFUSAL_REASONS.map((reason) => [reason, terminal.mcpCalls.refusals[reason]])) }),
+                // The session's standalone GET tunnel, absent for a turn sealed before
+                // the facade observed that channel at all.
+                ...(terminal.mcpCalls.tunnels === undefined
+                    ? {}
+                    : {
+                        tunnels: {
+                            opened: terminal.mcpCalls.tunnels.opened,
+                            closed: terminal.mcpCalls.tunnels.closed,
+                            delivered: terminal.mcpCalls.tunnels.delivered,
+                            open: terminal.mcpCalls.tunnels.open
+                                .slice(0, ENGINE_BROKER_MCP_TUNNEL_MAX)
+                                .map((tunnel) => ({ open_ms: tunnel.openMs, delivered: tunnel.delivered }))
+                        }
+                    })
+            }
+        }
+        : {})
+})}\n`;

package/dist/runtime/engineBrokerService.d.ts

@@ -0,0 +1,37 @@
+import type { EngineBrokerTurnAccounting, EngineBrokerTurnLimitOverrides } from "./engineBrokerTurnAccounting.js";
+import { type GrokInferenceGrantIssued, type GrokInferenceGrantRequest } from "./grokInferenceGrants.js";
+export interface EngineBrokerServiceEngine {
+    turn(agentId: string, wakeId: string, prompt: string, mcpEndpoint: string, signal?: AbortSignal, limits?: EngineBrokerTurnLimitOverrides): Promise<Readonly<{
+        text: string;
+        workerPid: number;
+        workerUid: number;
+        workerStartTime: string;
+    }> & EngineBrokerTurnAccounting>;
+    readiness(): Readonly<{
+        providerProxyPort: number;
+        mcpFacadePort: number;
+        registrations: number;
+        credentialStale: boolean;
+        realmLease: boolean;
+        workerIsolation: boolean;
+    }>;
+    close(): Promise<void>;
+    /** Evaluator inference grants; an engine without them refuses every grant request as `unavailable`. Refusals throw {@link GrokInferenceGrantRefused}. */
+    requestInferenceGrant?(request: GrokInferenceGrantRequest): GrokInferenceGrantIssued;
+    releaseInferenceGrant?(grantId: string): boolean;
+}
+export declare function startEngineBrokerService(broker: EngineBrokerServiceEngine, socketPath?: string): Promise<{
+    close: () => Promise<void>;
+    health: () => {
+        activeTurns: number;
+        socketPath: string;
+    };
+}>;
+export declare function startEngineBrokerServiceWithIdentity(broker: EngineBrokerServiceEngine, socketPath: string, expectedUid: number): Promise<{
+    close: () => Promise<void>;
+    health: () => {
+        activeTurns: number;
+        socketPath: string;
+    };
+}>;
+//# sourceMappingURL=engineBrokerService.d.ts.map