@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/grokEngineBroker.d.ts

@@ -0,0 +1,48 @@
+import type { EngineBrokerServiceRegistration } from "./engineBrokerServiceConfig.js";
+import type { EngineBrokerTurnLimitOverrides } from "./engineBrokerTurnAccounting.js";
+import { type GrokEngineBrokerTurnResult } from "./grokEngineBrokerTurn.js";
+import { type GrokInferenceGrantRequest } from "./grokInferenceGrants.js";
+export { EngineBrokerTurnFailure, type GrokEngineBrokerTurnResult } from "./grokEngineBrokerTurn.js";
+export { finishBrokerTurnWithUsage } from "./grokEngineBrokerMetering.js";
+export type GrokEngineBrokerRegistration = EngineBrokerServiceRegistration;
+export type GrokEngineBroker = Awaited<ReturnType<typeof startGrokEngineBroker>>;
+/**
+ * The Grok engine broker: one credential realm, one provider proxy, one MCP
+ * facade, and the root-provisioned registrations. Each registration declares
+ * its own model/effort (whose worker config bytes are attested), usage ledger,
+ * and turn limits (`engineBrokerServiceConfig.ts`).
+ *
+ * With an `inferenceLedgerPath` the broker also issues evaluator inference
+ * grants (`grokInferenceGrants.ts`) over the same credential authority and
+ * proxy; their rows go only to that ledger. A stale realm refuses a grant as
+ * `auth_stale`, exactly as it fails subject turns.
+ */
+export declare function startGrokEngineBroker(options: Readonly<{
+    grokCommand: string;
+    nativeClient: string;
+    credentialHome: string;
+    turnStore: string;
+    registrations: readonly GrokEngineBrokerRegistration[];
+    inferenceLedgerPath?: string;
+}>): Promise<{
+    turn(agentId: string, wakeId: string, prompt: string, mcpEndpoint: string, signal?: AbortSignal, limits?: EngineBrokerTurnLimitOverrides): Promise<GrokEngineBrokerTurnResult>;
+    requestInferenceGrant(request: GrokInferenceGrantRequest): Readonly<{
+        grantId: string;
+        token: string;
+        purpose: import("./inferenceUsageLedger.js").GrokInferencePurpose;
+        policy: import("./grokBrokerModelPolicy.js").GrokBrokerModelPolicy;
+        expiresAt: number;
+        limits: import("./engineBrokerTurnAccounting.js").EngineBrokerTurnLimits;
+    }>;
+    releaseInferenceGrant(grantId: string): boolean;
+    close(): Promise<void>;
+    readiness: () => {
+        providerProxyPort: number;
+        mcpFacadePort: number;
+        registrations: number;
+        credentialStale: boolean;
+        realmLease: boolean;
+        workerIsolation: boolean;
+    };
+}>;
+//# sourceMappingURL=grokEngineBroker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokEngineBroker.d.ts","sourceRoot":"","sources":["../../src/runtime/grokEngineBroker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AAOtF,OAAO,EAA2B,KAAK,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAErG,OAAO,EAAgE,KAAK,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAExI,OAAO,EAAE,uBAAuB,EAAE,KAAK,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACrG,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,MAAM,MAAM,4BAA4B,GAAG,+BAA+B,CAAC;AAC3E,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC;AAEjF;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,QAAQ,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;kBAYrN,MAAM,UAAU,MAAM,UAAU,MAAM,eAAe,MAAM,WAAW,WAAW,WAAW,8BAA8B,GAAG,OAAO,CAAC,0BAA0B,CAAC;mCAOrJ,yBAAyB;;;;;;;;mCAKzB,MAAM,GAAG,OAAO;aAIhC,OAAO,CAAC,IAAI,CAAC;;;;;;;;;GAG/B"}

package/dist/runtime/grokEngineBroker.js

@@ -0,0 +1,114 @@
+import { DurableGrokBrokerCredentialAuthority } from "./grokBrokerCredentialAuthority.js";
+import { runNativeBrokerTurn } from "./engineBrokerNativeClient.js";
+import { EngineBrokerTurnRegistry } from "./engineBrokerTurnRegistry.js";
+import { startGrokBrokerProxy } from "./grokBrokerProxy.js";
+import { startEngineBrokerMcpFacade } from "./engineBrokerMcpFacade.js";
+import { acquireGrokBrokerRealmLease } from "./grokBrokerRealmLease.js";
+import { grokBrokerWorkerConfigSha256 } from "./grokBrokerWorkerConfig.js";
+import { parseGrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+import { runGrokEngineBrokerTurn } from "./grokEngineBrokerTurn.js";
+import { createGrokWorkerIsolationGuard, grokBrokerAttestationInput, prepareGrokWorkerAttestation } from "./grokWorkerAttestation.js";
+import { createLedgeredGrokInferenceGrants, GrokInferenceGrantRefused } from "./grokInferenceGrants.js";
+export { EngineBrokerTurnFailure } from "./grokEngineBrokerTurn.js";
+export { finishBrokerTurnWithUsage } from "./grokEngineBrokerMetering.js";
+/**
+ * The Grok engine broker: one credential realm, one provider proxy, one MCP
+ * facade, and the root-provisioned registrations. Each registration declares
+ * its own model/effort (whose worker config bytes are attested), usage ledger,
+ * and turn limits (`engineBrokerServiceConfig.ts`).
+ *
+ * With an `inferenceLedgerPath` the broker also issues evaluator inference
+ * grants (`grokInferenceGrants.ts`) over the same credential authority and
+ * proxy; their rows go only to that ledger. A stale realm refuses a grant as
+ * `auth_stale`, exactly as it fails subject turns.
+ */
+export async function startGrokEngineBroker(options) {
+    const registrations = new Map(options.registrations.map((entry) => [entry.agentId, { ...entry, model: parseGrokBrokerModelPolicy(entry.model) }]));
+    if (registrations.size !== options.registrations.length)
+        throw new Error("engine broker registration conflict");
+    const attestationFor = (registration) => grokBrokerAttestationInput(registration, [...registrations.values()], grokBrokerWorkerConfigSha256(registration.model));
+    const inferenceLedgerPath = options.inferenceLedgerPath;
+    const grants = inferenceLedgerPath === undefined ? undefined : createLedgeredGrokInferenceGrants(inferenceLedgerPath);
+    const lease = await acquireGrokBrokerRealmLease(options.credentialHome);
+    const authority = new DurableGrokBrokerCredentialAuthority(options.grokCommand, options.credentialHome);
+    try {
+        await authority.initialize();
+    }
+    catch (error) {
+        await lease.close();
+        throw error;
+    }
+    let proxy;
+    try {
+        proxy = await startGrokBrokerProxy(authority, undefined, undefined, undefined, grants);
+    }
+    catch (error) {
+        await lease.close();
+        throw error;
+    }
+    let mcp;
+    try {
+        mcp = await startEngineBrokerMcpFacade();
+        for (const registration of registrations.values())
+            await prepareGrokWorkerAttestation(attestationFor(registration));
+    }
+    catch (error) {
+        if (mcp)
+            await mcp.close().catch(() => undefined);
+        await proxy.close();
+        await lease.close();
+        throw error;
+    }
+    if (!mcp)
+        throw new Error("engine broker unavailable");
+    const turns = new EngineBrokerTurnRegistry(options.turnStore);
+    const active = new Map();
+    let closed = false;
+    const facade = mcp;
+    const deps = {
+        turns, proxy, mcp: facade, credentialStale: () => authority.isStale(),
+        prepareIsolation: async (registration) => { const attestation = attestationFor(registration); return createGrokWorkerIsolationGuard(attestation, await prepareGrokWorkerAttestation(attestation)); },
+        runNative: (input, signal) => runNativeBrokerTurn(options.nativeClient, input, signal)
+    };
+    return {
+        async turn(agentId, wakeId, prompt, mcpEndpoint, signal, limits) {
+            if (closed)
+                throw new Error("engine broker unavailable");
+            const registration = registrations.get(agentId);
+            if (registration === undefined)
+                throw new Error("engine broker unavailable");
+            const controller = new AbortController();
+            const onAbort = () => controller.abort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                controller.abort();
+            const key = `${agentId}\0${wakeId}`;
+            const done = runGrokEngineBrokerTurn(deps, registration, wakeId, prompt, mcpEndpoint, controller.signal, limits);
+            active.set(key, { controller, done: done.then(() => undefined, () => undefined) });
+            try {
+                return await done;
+            }
+            finally {
+                signal?.removeEventListener("abort", onAbort);
+                active.delete(key);
+            }
+        },
+        requestInferenceGrant(request) {
+            if (closed || grants === undefined)
+                throw new GrokInferenceGrantRefused("unavailable");
+            if (authority.isStale())
+                throw new GrokInferenceGrantRefused("auth_stale");
+            return grants.issue(request);
+        },
+        releaseInferenceGrant(grantId) {
+            if (grants === undefined)
+                throw new GrokInferenceGrantRefused("unavailable");
+            return grants.release(grantId);
+        },
+        async close() { if (closed)
+            return; closed = true; grants?.close(); const running = [...active.values()]; for (const entry of running)
+            entry.controller.abort(); await Promise.allSettled(running.map((entry) => entry.done)); const results = await Promise.allSettled([facade.close(), proxy.close(), lease.close()]); const failures = results.flatMap((entry) => entry.status === "rejected" ? [entry.reason] : []); if (failures.length)
+            throw new AggregateError(failures, "engine broker shutdown failed"); },
+        readiness: () => ({ providerProxyPort: proxy.port, mcpFacadePort: 43_124, registrations: registrations.size, credentialStale: authority.isStale(), realmLease: true, workerIsolation: true })
+    };
+}

package/dist/runtime/grokEngineBrokerLedger.d.ts

@@ -0,0 +1,52 @@
+import { type GrokTurnRequest } from "./turnRequestLedger.js";
+import { type TurnUsageFailureReason } from "./turnUsageLedger.js";
+import type { EngineBrokerTerminalResponse } from "./engineBrokerProtocol.js";
+/**
+ * The exact ledger bytes a terminal broker turn owes, sealed into its turn
+ * record *before* they are appended.
+ *
+ * The record is published first and the ledger appended second, so a crash in
+ * between used to leave a sealed turn whose spend never reached the ledger —
+ * and a replay never metered. Now a replay re-checks: if the ledger holds no
+ * row for this `turn`, it appends these same bytes (same `at`, same numbers).
+ * That is completing the original metering, not re-metering: a replay after a
+ * normal append finds the row and writes nothing, and readers dedupe on `turn`
+ * should two replays race.
+ */
+export type BrokerTurnLedgerLines = Readonly<{
+    usage: string | null;
+    requests: string;
+    seal?: string;
+}>;
+/** A v1 record, or a replay with no sealed bytes at all: nothing to append, including no seal. */
+export declare const EMPTY_BROKER_TURN_LEDGER: BrokerTurnLedgerLines;
+export type BrokerTurnLedgerDetail = Readonly<{
+    agentId: string;
+    wakeId: string;
+    notionalUsd: number;
+    complete: boolean;
+    reason?: TurnUsageFailureReason;
+    requests: readonly GrokTurnRequest[];
+    session?: string;
+    estimatedRequests: number;
+}>;
+export declare function renderBrokerTurnLedger(terminal: EngineBrokerTerminalResponse, detail: BrokerTurnLedgerDetail): BrokerTurnLedgerLines;
+/**
+ * Strict check of stored ledger bytes: exactly the turn's own rows,
+ * newline-terminated, bounded.
+ *
+ * `seal` is optional so a record sealed before this stream existed still
+ * replays; its absence means the turn owes no seal row, never that one was
+ * lost.
+ */
+export declare function parseBrokerTurnLedgerLines(value: unknown, turnId: string): BrokerTurnLedgerLines;
+export type BrokerTurnLedgerPaths = Readonly<{
+    usageLedgerPath: string;
+    requestLedgerPath: string;
+    sealLedgerPath: string;
+}>;
+/** Appends sealed lines on the first metering: no presence scan is needed, nothing was appended before the record existed. */
+export declare function appendBrokerTurnLedger(lines: BrokerTurnLedgerLines, paths: BrokerTurnLedgerPaths): Promise<void>;
+/** On replay: append each stream's sealed lines only when that stream (current file or its `.1`) holds no row for this turn. Never rejects. */
+export declare function ensureBrokerTurnLedgered(lines: BrokerTurnLedgerLines, turnId: string, paths: BrokerTurnLedgerPaths): Promise<void>;
+//# sourceMappingURL=grokEngineBrokerLedger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokEngineBrokerLedger.d.ts","sourceRoot":"","sources":["../../src/runtime/grokEngineBrokerLedger.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8E,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC1I,OAAO,EAAkD,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnH,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AACxG,kGAAkG;AAClG,eAAO,MAAM,wBAAwB,EAAE,qBAAoE,CAAC;AAE5G,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/O,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,4BAA4B,EAAE,MAAM,EAAE,sBAAsB,GAAG,qBAAqB,CAmBpI;AAKD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAqBhG;AAED,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7H,8HAA8H;AAC9H,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,qBAAqB,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtH;AAED,+IAA+I;AAC/I,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMxI"}

package/dist/runtime/grokEngineBrokerLedger.js

@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import { renderBrokerTurnSealLine, TURN_SEAL_LEDGER_VERSION, TURN_SEAL_MAX_LINE_BYTES } from "./engineBrokerSealLedger.js";
+import { recordLedgerLines, renderGrokTurnRequestLines, TURN_REQUEST_LEDGER_VERSION } from "./turnRequestLedger.js";
+import { renderTurnUsageLine, TURN_USAGE_LEDGER_VERSION } from "./turnUsageLedger.js";
+/** A v1 record, or a replay with no sealed bytes at all: nothing to append, including no seal. */
+export const EMPTY_BROKER_TURN_LEDGER = Object.freeze({ usage: null, requests: "" });
+export function renderBrokerTurnLedger(terminal, detail) {
+    const at = new Date().toISOString();
+    // The seal row is rendered for *every* terminal turn, including one whose
+    // usage is null. That is the whole point: a turn cancelled before any usage
+    // could be attributed is exactly the turn whose outstanding MCP call and
+    // redacted last words have no other route to the host.
+    const seal = renderBrokerTurnSealLine(terminal, { agent: detail.agentId, wake: detail.wakeId, at });
+    if (terminal.usage === null)
+        return { usage: null, requests: "", seal };
+    const { usage } = terminal;
+    return {
+        seal,
+        usage: renderTurnUsageLine({
+            agent: detail.agentId, wake: detail.wakeId, engine: "grok", at,
+            usage: { input: usage.input, output: usage.output, cacheRead: usage.cacheRead, cacheWrite: usage.cacheWrite, total: usage.total, calls: terminal.requests, notionalUsd: detail.notionalUsd, complete: detail.complete },
+            outcome: terminal.kind === "completed" ? { status: "completed" } : { status: "failed", reason: detail.reason ?? "unknown" },
+            turn: terminal.turnId, limitReason: terminal.limitReason, model: terminal.model, estimatedRequests: detail.estimatedRequests
+        }),
+        requests: renderGrokTurnRequestLines({ agent: detail.agentId, wake: detail.wakeId, turn: terminal.turnId, model: terminal.model, requests: detail.requests, requestCount: terminal.requests, at, ...(detail.session === undefined ? {} : { session: detail.session }) })
+    };
+}
+const MAX_USAGE_LINE_BYTES = 4_096, MAX_REQUEST_LINES_BYTES = 262_144;
+const rows = (text) => text.split("\n").filter((line) => line.length > 0).map((line) => { const value = JSON.parse(line); if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new Error(); return value; });
+/**
+ * Strict check of stored ledger bytes: exactly the turn's own rows,
+ * newline-terminated, bounded.
+ *
+ * `seal` is optional so a record sealed before this stream existed still
+ * replays; its absence means the turn owes no seal row, never that one was
+ * lost.
+ */
+export function parseBrokerTurnLedgerLines(value, turnId) {
+    const invalid = () => new Error("broker turn registry unavailable");
+    if (value === null || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, "usage") || !Object.hasOwn(value, "requests"))
+        throw invalid();
+    const sealed = Object.hasOwn(value, "seal");
+    if (Object.keys(value).length !== (sealed ? 3 : 2))
+        throw invalid();
+    const { usage, requests, seal } = value;
+    try {
+        if (usage !== null) {
+            if (typeof usage !== "string" || !usage.endsWith("\n") || Buffer.byteLength(usage) > MAX_USAGE_LINE_BYTES)
+                throw invalid();
+            const parsed = rows(usage);
+            if (parsed.length !== 1 || parsed[0].v !== TURN_USAGE_LEDGER_VERSION || parsed[0].turn !== turnId)
+                throw invalid();
+        }
+        if (typeof requests !== "string" || (requests.length > 0 && (usage === null || !requests.endsWith("\n"))) || Buffer.byteLength(requests) > MAX_REQUEST_LINES_BYTES)
+            throw invalid();
+        if (rows(requests).some((row) => row.v !== TURN_REQUEST_LEDGER_VERSION || row.turn !== turnId))
+            throw invalid();
+        if (sealed) {
+            if (typeof seal !== "string" || !seal.endsWith("\n") || Buffer.byteLength(seal) > TURN_SEAL_MAX_LINE_BYTES)
+                throw invalid();
+            const parsed = rows(seal);
+            if (parsed.length !== 1 || parsed[0].v !== TURN_SEAL_LEDGER_VERSION || parsed[0].turn !== turnId)
+                throw invalid();
+        }
+    }
+    catch {
+        throw invalid();
+    }
+    return { usage: usage, requests, ...(sealed ? { seal: seal } : {}) };
+}
+/** Appends sealed lines on the first metering: no presence scan is needed, nothing was appended before the record existed. */
+export async function appendBrokerTurnLedger(lines, paths) {
+    if (lines.usage !== null)
+        await recordLedgerLines(paths.usageLedgerPath, lines.usage);
+    await recordLedgerLines(paths.requestLedgerPath, lines.requests);
+    // Last, and never conditional on usage: a turn with no attributable spend is
+    // precisely the one whose seal row is its only account of itself.
+    if (lines.seal !== undefined)
+        await recordLedgerLines(paths.sealLedgerPath, lines.seal);
+}
+/** On replay: append each stream's sealed lines only when that stream (current file or its `.1`) holds no row for this turn. Never rejects. */
+export async function ensureBrokerTurnLedgered(lines, turnId, paths) {
+    try {
+        if (lines.usage !== null && !await ledgerHasTurn(paths.usageLedgerPath, turnId))
+            await recordLedgerLines(paths.usageLedgerPath, lines.usage);
+        if (lines.requests.length > 0 && !await ledgerHasTurn(paths.requestLedgerPath, turnId))
+            await recordLedgerLines(paths.requestLedgerPath, lines.requests);
+        if (lines.seal !== undefined && !await ledgerHasTurn(paths.sealLedgerPath, turnId))
+            await recordLedgerLines(paths.sealLedgerPath, lines.seal);
+    }
+    catch { /* advisory: a replay never fails on its ledger */ }
+}
+async function ledgerHasTurn(file, turnId) {
+    for (const candidate of [`${file}.1`, file]) {
+        let text;
+        try {
+            text = await readFile(candidate, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split("\n")) {
+            if (!line.includes(turnId))
+                continue;
+            try {
+                if (JSON.parse(line).turn === turnId)
+                    return true;
+            }
+            catch { /* a torn line is not this turn's row */ }
+        }
+    }
+    return false;
+}

package/dist/runtime/grokEngineBrokerMetering.d.ts

@@ -0,0 +1,51 @@
+import type { EngineBrokerRequest, EngineBrokerTerminalResponse } from "./engineBrokerProtocol.js";
+import type { EngineBrokerTurnRegistry } from "./engineBrokerTurnRegistry.js";
+import type { GrokTurnRequest } from "./turnRequestLedger.js";
+import type { TurnUsageFailureReason } from "./turnUsageLedger.js";
+export type BrokerTurnMetering = Readonly<{
+    usageLedgerPath: string;
+    requestLedgerPath: string;
+    /** Where the sealed response's operator-visible projection is appended (`engineBrokerSealLedger.ts`). */
+    sealLedgerPath: string;
+    agentId: string;
+    wakeId: string;
+}>;
+export type BrokerTurnMeteringDetail = Readonly<{
+    notionalUsd: number;
+    complete: boolean;
+    reason?: TurnUsageFailureReason;
+    requests: readonly GrokTurnRequest[];
+    session?: string;
+    estimatedRequests: number;
+}>;
+/**
+ * Seal a terminal turn, then meter it. The broker is the single writer.
+ *
+ * Order is load-bearing. The ledger bytes are rendered first and sealed into
+ * the durable terminal record together with its accounting
+ * (`grokEngineBrokerLedger.ts`); only after `turns.finish` published that
+ * record are the same bytes appended. A replayed turn returns before the
+ * broker's `try` block and never meters again — it only completes an append a
+ * crash interrupted (`ensureBrokerTurnLedgered`), and every row carries the
+ * turn id as `turn`, so a reader that sees one twice counts it once.
+ *
+ * Remaining window, documented rather than closed: a crash before the record's
+ * rename (while the turn is still `active`, including mid-turn) makes the next
+ * boot seal that turn `failed` with `usage: null`, so its spend is unmetered.
+ * Closing it needs the running proxy usage checkpointed into the active record
+ * on every request (an fsync'd rewrite per model request); not done here.
+ *
+ * Both terminal kinds meter: a failed turn spent real tokens, so its partial
+ * usage is written with `outcome: failed` and its closed `limitReason`. A turn
+ * with no usage at all (`usage: null`) writes no *usage* row — a zero row is
+ * byte-identical to a measured zero — but it still writes its seal row, which
+ * is a record of what the turn did rather than of what it spent.
+ *
+ * Appends never reject, so an append failure cannot escape into the caller's
+ * `catch` and rewrite a completed turn as failed; the caller also refuses to
+ * re-seal a turn this helper already sealed.
+ */
+export declare function finishBrokerTurnWithUsage(turns: EngineBrokerTurnRegistry, request: Extract<EngineBrokerRequest, {
+    kind: "start_turn";
+}>, terminal: EngineBrokerTerminalResponse, metering: BrokerTurnMetering, detail: BrokerTurnMeteringDetail, onSealed?: () => void): Promise<void>;
+//# sourceMappingURL=grokEngineBrokerMetering.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokEngineBrokerMetering.d.ts","sourceRoot":"","sources":["../../src/runtime/grokEngineBrokerMetering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACnG,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yGAAyG;IACzG,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEhN;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,wBAAwB,EAAE,OAAO,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,EAAE,QAAQ,EAAE,4BAA4B,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,wBAAwB,EAAE,QAAQ,GAAE,MAAM,IAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAK7S"}

package/dist/runtime/grokEngineBrokerMetering.js

@@ -0,0 +1,34 @@
+import { appendBrokerTurnLedger, renderBrokerTurnLedger } from "./grokEngineBrokerLedger.js";
+/**
+ * Seal a terminal turn, then meter it. The broker is the single writer.
+ *
+ * Order is load-bearing. The ledger bytes are rendered first and sealed into
+ * the durable terminal record together with its accounting
+ * (`grokEngineBrokerLedger.ts`); only after `turns.finish` published that
+ * record are the same bytes appended. A replayed turn returns before the
+ * broker's `try` block and never meters again — it only completes an append a
+ * crash interrupted (`ensureBrokerTurnLedgered`), and every row carries the
+ * turn id as `turn`, so a reader that sees one twice counts it once.
+ *
+ * Remaining window, documented rather than closed: a crash before the record's
+ * rename (while the turn is still `active`, including mid-turn) makes the next
+ * boot seal that turn `failed` with `usage: null`, so its spend is unmetered.
+ * Closing it needs the running proxy usage checkpointed into the active record
+ * on every request (an fsync'd rewrite per model request); not done here.
+ *
+ * Both terminal kinds meter: a failed turn spent real tokens, so its partial
+ * usage is written with `outcome: failed` and its closed `limitReason`. A turn
+ * with no usage at all (`usage: null`) writes no *usage* row — a zero row is
+ * byte-identical to a measured zero — but it still writes its seal row, which
+ * is a record of what the turn did rather than of what it spent.
+ *
+ * Appends never reject, so an append failure cannot escape into the caller's
+ * `catch` and rewrite a completed turn as failed; the caller also refuses to
+ * re-seal a turn this helper already sealed.
+ */
+export async function finishBrokerTurnWithUsage(turns, request, terminal, metering, detail, onSealed = () => undefined) {
+    const lines = renderBrokerTurnLedger(terminal, { ...detail, agentId: metering.agentId, wakeId: metering.wakeId });
+    await turns.finish(request, terminal, lines);
+    onSealed();
+    await appendBrokerTurnLedger(lines, metering);
+}

package/dist/runtime/grokEngineBrokerTurn.d.ts

@@ -0,0 +1,58 @@
+import { type EngineBrokerFailureCode } from "./engineBrokerProtocol.js";
+import type { EngineBrokerMcpCallObservation } from "./engineBrokerMcpCallLog.js";
+import { type EngineBrokerTurnAccounting, type EngineBrokerTurnLimitOverrides } from "./engineBrokerTurnAccounting.js";
+import { type NativeBrokerDiagnostic, type NativeBrokerTurn, type NativeBrokerTurnResult } from "./engineBrokerNativeClient.js";
+import type { EngineBrokerTurnRegistry } from "./engineBrokerTurnRegistry.js";
+import { type EngineBrokerServiceRegistration } from "./engineBrokerServiceConfig.js";
+import type { GrokBrokerProxyTurn } from "./grokBrokerProxy.js";
+export type GrokEngineBrokerTurnResult = Readonly<{
+    text: string;
+    workerPid: number;
+    workerUid: number;
+    workerStartTime: string;
+}> & EngineBrokerTurnAccounting;
+export declare class EngineBrokerTurnFailure extends Error {
+    readonly code: Exclude<EngineBrokerFailureCode, "turn_conflict" | "unavailable">;
+    readonly diagnostic?: NativeBrokerDiagnostic | undefined;
+    readonly accounting?: EngineBrokerTurnAccounting | undefined;
+    readonly mcpCalls?: EngineBrokerMcpCallObservation | undefined;
+    constructor(code: Exclude<EngineBrokerFailureCode, "turn_conflict" | "unavailable">, diagnostic?: NativeBrokerDiagnostic | undefined, accounting?: EngineBrokerTurnAccounting | undefined, mcpCalls?: EngineBrokerMcpCallObservation | undefined);
+}
+/** Everything one broker turn touches, injected so the accounting and limit paths run under test without a native launcher. */
+export type GrokEngineBrokerTurnDependencies = Readonly<{
+    turns: EngineBrokerTurnRegistry;
+    proxy: Readonly<{
+        capabilities: Readonly<{
+            issue(agentId: string, turnId: string): string;
+            revoke(turnId: string): void;
+        }>;
+        registerIsolationGuard(turnId: string, guard: () => Promise<void>): void;
+        revokeIsolationGuard(turnId: string): void;
+        registerTurn(turnId: string, turn: GrokBrokerProxyTurn): void;
+        revokeTurn(turnId: string): void;
+    }>;
+    mcp: Readonly<{
+        register(agentId: string, turnId: string, endpoint: string): string;
+        revoke(turnId: string): void;
+        observe?(turnId: string): EngineBrokerMcpCallObservation | undefined;
+    }>;
+    credentialStale(): boolean;
+    prepareIsolation(registration: EngineBrokerServiceRegistration): Promise<() => Promise<void>>;
+    runNative(input: NativeBrokerTurn, signal: AbortSignal): Promise<Readonly<NativeBrokerTurnResult>>;
+}>;
+/**
+ * One brokered Grok turn under its declared limits.
+ *
+ * The limits are the registration's, lowered (never raised) by the wake. The
+ * proxy meter refuses model requests past `maxRequests`, past the elapsed
+ * deadline, or once the upstream-reported running total reached `maxTokens`,
+ * and a tripped limit aborts the worker through the same cancel/kill path a
+ * client cancellation uses. A wall-clock timer trips `timeout` for a worker
+ * that is mid-request.
+ *
+ * Every terminal path — completed, failed, limit, cancelled — is sealed and
+ * metered through {@link finishBrokerTurnWithUsage}; a replayed turn returns its
+ * sealed accounting before any of this runs and never meters again.
+ */
+export declare function runGrokEngineBrokerTurn(deps: GrokEngineBrokerTurnDependencies, registration: EngineBrokerServiceRegistration, wakeId: string, prompt: string, mcpEndpoint: string, signal?: AbortSignal, overrides?: EngineBrokerTurnLimitOverrides): Promise<GrokEngineBrokerTurnResult>;
+//# sourceMappingURL=grokEngineBrokerTurn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokEngineBrokerTurn.d.ts","sourceRoot":"","sources":["../../src/runtime/grokEngineBrokerTurn.ts"],"names":[],"mappings":"AAIA,OAAO,EAAyB,KAAK,uBAAuB,EAAqC,MAAM,2BAA2B,CAAC;AACnI,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAqD,KAAK,0BAA0B,EAAE,KAAK,8BAA8B,EAA8B,MAAM,iCAAiC,CAAC;AACtM,OAAO,EAA2B,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACzJ,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,EAAmE,KAAK,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AAGvJ,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,0BAA0B,CAAC;AAChK,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,uBAAuB,EAAE,eAAe,GAAG,aAAa,CAAC;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,sBAAsB;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,0BAA0B;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,8BAA8B;gBAA3N,IAAI,EAAE,OAAO,CAAC,uBAAuB,EAAE,eAAe,GAAG,aAAa,CAAC,EAAW,UAAU,CAAC,EAAE,sBAAsB,YAAA,EAAW,UAAU,CAAC,EAAE,0BAA0B,YAAA,EAAW,QAAQ,CAAC,EAAE,8BAA8B,YAAA;CACjP;AAED,+HAA+H;AAC/H,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CAAC;IACtD,KAAK,EAAE,wBAAwB,CAAC;IAChC,KAAK,EAAE,QAAQ,CAAC;QAAE,YAAY,EAAE,QAAQ,CAAC;YAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;YAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAC,CAAC;QAAC,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAAC,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;QAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACrV,GAAG,EAAE,QAAQ,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,8BAA8B,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IAC3L,eAAe,IAAI,OAAO,CAAC;IAC3B,gBAAgB,CAAC,YAAY,EAAE,+BAA+B,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9F,SAAS,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC,CAAC;CACpG,CAAC,CAAC;AAKH;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,gCAAgC,EAAE,YAAY,EAAE,+BAA+B,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,8BAA8B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA2D/R"}