@noopolis/daimon 0.1.2 → 0.2.1

package/dist/runtime/grokBrokerRunBudget.d.ts

@@ -0,0 +1,20 @@
+export declare class GrokBrokerRunLimit extends Error {
+    constructor();
+}
+/** One broker realm lease owns this journal. Reserve durably BEFORE forwarding;
+ * failed calls and credential retries consume capacity, never refund it.
+ * Slot recycle must never remove this run-level file.
+ */
+export declare class GrokBrokerRunBudget {
+    readonly maximum: number;
+    private readonly file;
+    private used;
+    private tail;
+    private failed;
+    private closed;
+    private constructor();
+    static open(maximum: number, file: string): Promise<GrokBrokerRunBudget>;
+    reserve(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=grokBrokerRunBudget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerRunBudget.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerRunBudget.ts"],"names":[],"mappings":"AAIA,qBAAa,kBAAmB,SAAQ,KAAK;;CAE5C;AAED;;;GAGG;AACH,qBAAa,mBAAmB;IAIV,QAAQ,CAAC,OAAO,EAAE,MAAM;IAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAU,OAAO,CAAC,IAAI;IAHzF,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO;WAEM,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAc9E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBlB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/runtime/grokBrokerRunBudget.js

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+export class GrokBrokerRunLimit extends Error {
+    constructor() { super("run_request_limit"); }
+}
+/** One broker realm lease owns this journal. Reserve durably BEFORE forwarding;
+ * failed calls and credential retries consume capacity, never refund it.
+ * Slot recycle must never remove this run-level file.
+ */
+export class GrokBrokerRunBudget {
+    maximum;
+    file;
+    used;
+    tail = Promise.resolve();
+    failed = false;
+    closed = false;
+    constructor(maximum, file, used) {
+        this.maximum = maximum;
+        this.file = file;
+        this.used = used;
+    }
+    static async open(maximum, file) {
+        if (!Number.isSafeInteger(maximum) || maximum < 1)
+            throw new TypeError("invalid run request cap");
+        await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+        let used = 0;
+        try {
+            const state = JSON.parse(await readFile(file, "utf8"));
+            if (state.schema !== "daimon.run-requests.v1" || state.maximum !== maximum ||
+                !Number.isSafeInteger(state.used) || state.used < 0 || state.used > maximum ||
+                Object.keys(state).length !== 3)
+                throw new Error("invalid run request checkpoint");
+            used = state.used;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        return new GrokBrokerRunBudget(maximum, file, used);
+    }
+    reserve() {
+        if (this.closed)
+            return Promise.reject(new Error("run request budget closed"));
+        const reservation = this.tail.then(async () => {
+            if (this.failed)
+                throw new Error("run request checkpoint unavailable");
+            if (this.used >= this.maximum)
+                throw new GrokBrokerRunLimit();
+            this.used += 1;
+            const temporary = `${this.file}.${randomUUID()}.tmp`;
+            try {
+                const handle = await open(temporary, "wx", 0o600);
+                try {
+                    await handle.writeFile(JSON.stringify({ schema: "daimon.run-requests.v1", maximum: this.maximum, used: this.used }));
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await rename(temporary, this.file);
+                const directory = await open(path.dirname(this.file), "r");
+                try {
+                    await directory.sync();
+                }
+                finally {
+                    await directory.close();
+                }
+            }
+            catch (error) {
+                this.failed = true;
+                throw error;
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        });
+        this.tail = reservation.catch(() => undefined);
+        return reservation;
+    }
+    async close() {
+        this.closed = true;
+        await this.tail;
+    }
+}

package/dist/runtime/grokBrokerSlot.d.ts

@@ -0,0 +1,6 @@
+import { type GrokWorkerConfigVariant } from "../contracts/grokBrokerTaskClock.js";
+/** Canonical path in both broker and worker views; never a caller-selected file. */
+export declare function brokerTaskClockFileFor(slot: number): string;
+/** The pinned strict base exposes /run; its deny mounts must hide every peer clock. */
+export declare function assertBrokerTaskClockIsolation(variant: GrokWorkerConfigVariant, slot: number, slots: readonly number[], denyPaths: readonly string[]): void;
+//# sourceMappingURL=grokBrokerSlot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerSlot.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerSlot.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAE3G,oFAAoF;AACpF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GACrG,IAAI,CAUN"}

package/dist/runtime/grokBrokerSlot.js

@@ -0,0 +1,21 @@
+import { GROK_BROKER_TASK_CLOCK } from "../contracts/grokBrokerTaskClock.js";
+/** Canonical path in both broker and worker views; never a caller-selected file. */
+export function brokerTaskClockFileFor(slot) {
+    if (!Number.isSafeInteger(slot) || slot < 0)
+        throw new TypeError("invalid broker slot");
+    return `${GROK_BROKER_TASK_CLOCK.rootDirectoryPath}/slot-${slot}/faketime`;
+}
+/** The pinned strict base exposes /run; its deny mounts must hide every peer clock. */
+export function assertBrokerTaskClockIsolation(variant, slot, slots, denyPaths) {
+    if (variant !== "clocked")
+        return;
+    const own = brokerTaskClockFileFor(slot);
+    const covers = (denied, file) => file === denied || file.startsWith(`${denied}/`);
+    if (denyPaths.some((denied) => covers(denied, own)))
+        throw new Error("own broker task clock is denied");
+    for (const peer of slots) {
+        if (peer !== slot && !denyPaths.some((denied) => covers(denied, brokerTaskClockFileFor(peer).slice(0, -"/faketime".length)))) {
+            throw new Error("sibling broker task clock is not denied");
+        }
+    }
+}

package/dist/runtime/grokBrokerTaskClock.d.ts

@@ -0,0 +1,32 @@
+import { type Stats } from "node:fs";
+import { type GrokWorkerConfigVariant } from "../contracts/grokBrokerTaskClock.js";
+import type { GrokBrokerProviderClockObservation } from "./grokBrokerProviderClock.js";
+import { type GrokWorkerConfigPins } from "./grokWorkerHomeAttestation.js";
+/** Internal filesystem seam; tests wrap real handles to observe both fsyncs. */
+export type BrokerTaskClockFs = Pick<typeof import("node:fs/promises"), "lstat" | "open" | "rename" | "unlink">;
+export type BrokerShellClock = "task" | "real" | "gap";
+export type BrokerShellClockObservation = Readonly<{
+    shellClock?: BrokerShellClock;
+}>;
+export type BrokerClockObservation = BrokerShellClockObservation & Readonly<{
+    providerClock?: GrokBrokerProviderClockObservation;
+}>;
+export declare function brokerClockObservation(shellClock?: BrokerShellClock, providerClock?: GrokBrokerProviderClockObservation): BrokerClockObservation;
+/** Relative seconds only: never a date, speed, loader path or arbitrary environment. */
+export declare function parseBrokerProcessClock(value: unknown): string;
+/** Daimon remains the offset owner; the broker uses its pinned library, not ambient preload. */
+export declare function brokerProcessClock(): string | undefined;
+/** Discovery only; selected slots still require full attestation before reconciliation. */
+export declare function needsBrokerTaskClockReconciliation(profilePath: string, pins: GrokWorkerConfigPins, file?: string): Promise<boolean>;
+/** Pure provisioning seam: only the broker can replace entries; every worker can read. */
+export declare function assertBrokerTaskClockDirectory(entry: Pick<Stats, "uid" | "mode" | "isDirectory">, brokerUid?: number): void;
+/**
+ * Root provisions a non-symlink broker-owned directory. Rename publishes a
+ * complete value before launch; binding the DIRECTORY (not the old file inode)
+ * into the worker view keeps subsequent turns visible. No native ABI changes.
+ * Paths/uid below are internal test seams, never control or service inputs.
+ */
+export declare function writeBrokerTaskClock(value: string | undefined, file?: string, brokerUid?: number, fs?: BrokerTaskClockFs): Promise<void>;
+/** Unknown config is never called clocked: this runs only after byte attestation. */
+export declare function prepareBrokerTaskClock(variant: GrokWorkerConfigVariant, value: string | undefined, write?: typeof writeBrokerTaskClock): Promise<BrokerShellClock>;
+//# sourceMappingURL=grokBrokerTaskClock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerTaskClock.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerTaskClock.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhD,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAE3G,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,8BAA8B,CAAC;AACvF,OAAO,EAA+B,KAAK,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAExG,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAGhH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AACvD,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IAAE,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAAC;AACtF,MAAM,MAAM,sBAAsB,GAAG,2BAA2B,GAAG,QAAQ,CAAC;IAC1E,aAAa,CAAC,EAAE,kCAAkC,CAAC;CACpD,CAAC,CAAC;AAEH,wBAAgB,sBAAsB,CACpC,UAAU,CAAC,EAAE,gBAAgB,EAAE,aAAa,CAAC,EAAE,kCAAkC,GAChF,sBAAsB,CAKxB;AAED,wFAAwF;AACxF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG9D;AAED,gGAAgG;AAChG,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAIvD;AAED,2FAA2F;AAC3F,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAC/C,IAAI,GAAE,MAAkC,GACvC,OAAO,CAAC,OAAO,CAAC,CAmBlB;AAED,0FAA0F;AAC1F,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,aAAa,CAAC,EAAE,SAAS,GAAE,MAAwC,GAAG,IAAI,CAI5J;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,GAAE,MAAkC,EACxC,SAAS,GAAE,MAAwC,EACnD,EAAE,GAAE,iBAA2B,GAC9B,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED,qFAAqF;AACrF,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,GAAE,OAAO,oBAA2C,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAS9L"}

package/dist/runtime/grokBrokerTaskClock.js

@@ -0,0 +1,120 @@
+import { brokerTaskClockFileFor } from "./grokBrokerSlot.js";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { GROK_BROKER_TASK_CLOCK } from "../contracts/grokBrokerTaskClock.js";
+import { readTaskClock, taskClockChildEnvironment } from "./taskClock.js";
+import { assertGrokWorkerConfigBytes } from "./grokWorkerHomeAttestation.js";
+const clockFs = { lstat, open, rename, unlink };
+export function brokerClockObservation(shellClock, providerClock) {
+    return {
+        ...(shellClock === undefined ? {} : { shellClock }),
+        ...(providerClock === undefined ? {} : { providerClock })
+    };
+}
+/** Relative seconds only: never a date, speed, loader path or arbitrary environment. */
+export function parseBrokerProcessClock(value) {
+    if (typeof value !== "string" || !/^[+-](?:0|[1-9][0-9]{0,12})(?:\.[0-9]{3})?$/u.test(value))
+        throw new TypeError("invalid broker process clock");
+    return value;
+}
+/** Daimon remains the offset owner; the broker uses its pinned library, not ambient preload. */
+export function brokerProcessClock() {
+    const clock = readTaskClock();
+    clock?.now();
+    return taskClockChildEnvironment({}, clock, { LD_PRELOAD: GROK_BROKER_TASK_CLOCK.preloadPath }).FAKETIME;
+}
+/** Discovery only; selected slots still require full attestation before reconciliation. */
+export async function needsBrokerTaskClockReconciliation(profilePath, pins, file = brokerTaskClockFileFor(0)) {
+    try {
+        // Even an unsafe directory entry must reach the fail-closed reconciliation.
+        await lstat(path.dirname(file));
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    let handle;
+    try {
+        handle = await open(path.join(path.dirname(profilePath), "config.toml"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const entry = await handle.stat();
+        if (!entry.isFile() || entry.size > 65_536)
+            return false;
+        return assertGrokWorkerConfigBytes(await handle.readFile(), pins) === "clocked";
+    }
+    catch {
+        // Missing or invalid unclocked provisioning is a per-turn attestation failure.
+        return false;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/** Pure provisioning seam: only the broker can replace entries; every worker can read. */
+export function assertBrokerTaskClockDirectory(entry, brokerUid = GROK_BROKER_TASK_CLOCK.ownerUid) {
+    if (!entry.isDirectory() || entry.uid !== brokerUid || (entry.mode & 0o7777) !== GROK_BROKER_TASK_CLOCK.directoryMode) {
+        throw new Error("unsafe Grok broker task clock directory");
+    }
+}
+/**
+ * Root provisions a non-symlink broker-owned directory. Rename publishes a
+ * complete value before launch; binding the DIRECTORY (not the old file inode)
+ * into the worker view keeps subsequent turns visible. No native ABI changes.
+ * Paths/uid below are internal test seams, never control or service inputs.
+ */
+export async function writeBrokerTaskClock(value, file = brokerTaskClockFileFor(0), brokerUid = GROK_BROKER_TASK_CLOCK.ownerUid, fs = clockFs) {
+    const seconds = value === undefined ? "+0" : parseBrokerProcessClock(value);
+    const directory = path.dirname(file);
+    const before = await fs.lstat(directory);
+    assertBrokerTaskClockDirectory(before, brokerUid);
+    const parent = await fs.open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    const temporary = path.join(directory, `.faketime-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+        const pinned = await parent.stat();
+        const verify = async () => {
+            const current = await fs.lstat(directory);
+            assertBrokerTaskClockDirectory(current, brokerUid);
+            if (current.dev !== pinned.dev || current.ino !== pinned.ino || before.dev !== pinned.dev || before.ino !== pinned.ino)
+                throw new Error("Grok broker task clock directory changed");
+        };
+        await verify();
+        const handle = await fs.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, GROK_BROKER_TASK_CLOCK.fileMode);
+        created = true;
+        try {
+            const entry = await handle.stat();
+            if (entry.uid !== brokerUid || !entry.isFile() || entry.nlink !== 1)
+                throw new Error("unsafe Grok broker task clock file");
+            await handle.chmod(GROK_BROKER_TASK_CLOCK.fileMode); // restrictive broker umask must not hide the file from the worker
+            await handle.writeFile(`${seconds}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await verify();
+        await fs.rename(temporary, file);
+        created = false;
+        await parent.sync();
+    }
+    finally {
+        if (created)
+            await fs.unlink(temporary).catch(() => undefined);
+        await parent.close();
+    }
+}
+/** Unknown config is never called clocked: this runs only after byte attestation. */
+export async function prepareBrokerTaskClock(variant, value, write = writeBrokerTaskClock) {
+    if (value !== undefined)
+        parseBrokerProcessClock(value);
+    if (variant === "clocked") {
+        await write(value);
+        return value === undefined ? "real" : "task";
+    }
+    if (value === undefined)
+        return "real";
+    console.warn("daimon: task clock coverage gap engine=grok: attested broker worker config is unclocked; native tools remain on real time; wake allowed");
+    return "gap";
+}

package/dist/runtime/grokBrokerTurnMeter.d.ts

@@ -0,0 +1,180 @@
+import { type EngineBrokerLimitReason, type EngineBrokerTurnLimits, type EngineBrokerTurnUsage } from "./engineBrokerTurnAccounting.js";
+/**
+ * `estimated` marks a request whose response carried no valid usage and was
+ * charged {@link estimateGrokRequestUsage}. `toolCalls` are the tool-call names
+ * that request's response carried, names only ({@link parseGrokResponseToolNames});
+ * absent means the response could not be decoded, `[]` that it called nothing.
+ */
+export type GrokBrokerRequestTiming = Readonly<{
+    startedAt: string;
+    endedAt?: string;
+    usage?: EngineBrokerTurnUsage;
+    estimated?: true;
+    toolCalls?: readonly string[];
+}>;
+export type GrokBrokerTurnMeterSnapshot = Readonly<{
+    requests: number;
+    tokens: number;
+    limitReason: EngineBrokerLimitReason;
+    usage: EngineBrokerTurnUsage | null;
+    estimatedRequests: number;
+    timings: readonly GrokBrokerRequestTiming[];
+}>;
+/** The model's last answer when it called no tool: the turn's final reply, as the proxy saw it, and when it settled. */
+export type GrokBrokerFinalReply = Readonly<{
+    index: number;
+    text: string;
+    at: number;
+}>;
+/**
+ * The weight a cached prompt read carries against the token ceiling.
+ *
+ * The ceiling exists to bound spend, and a cached read is billed at a quarter
+ * of a fresh input token (xAI's published cached-input rate for the Grok 4
+ * family). Counting it at full weight made the ceiling a context-size limit
+ * instead: a writing or composing turn re-reads its whole conversation on
+ * every request, 85–90% of it from cache, and production turns died at a
+ * 1.1M "ceiling" having spent about a third of that. Fresh input, output and
+ * reasoning still count in full; the sealed usage and ledgers are unchanged
+ * and keep every cached token at its raw count.
+ */
+export declare const GROK_CACHED_INPUT_TOKEN_WEIGHT = 0.25;
+/** What one request's usage costs against `maxTokens`: everything at full weight except cached reads. */
+export declare const grokCeilingTokens: (usage: EngineBrokerTurnUsage) => number;
+/**
+ * The proxy's per-turn spend gate.
+ *
+ * Every forwarded model request of one turn passes through {@link admit}
+ * *before* a bearer is attached, so the checks are hard for requests and
+ * elapsed time and between-requests for tokens:
+ *
+ * - `maxRequests`: request `maxRequests + 1` is refused; upstream never sees it.
+ * - `timeoutMs`: a request arriving after the deadline is refused (the broker's
+ *   own timer additionally kills a worker that is mid-request).
+ * - `maxTokens`: checked against the running total of upstream-reported usage
+ *   of the requests already answered. A request is admitted while that total is
+ *   still below the ceiling, so the overshoot is bounded by exactly one
+ *   request's usage — the last admitted one. Cached prompt reads count at
+ *   {@link GROK_CACHED_INPUT_TOKEN_WEIGHT} ({@link grokCeilingTokens}); an
+ *   uncached replay (P0 observed one at +55%) is fresh input and counts in full.
+ *
+ * The first limit that fires is sticky: every later request is refused with
+ * the same reason, and `onLimit` runs once.
+ *
+ * The token bound is only a bound if no request can be admitted on a total
+ * that an in-flight request has not yet reported into. So a turn has at most
+ * ONE upstream request in flight: a second request arriving before the first
+ * settled is refused (`busy`, HTTP 429) without being counted or tripping a
+ * limit. Grok's headless loop is sequential — every live capture (P1
+ * live-round1, P2 live) shows each request ending before the next starts — so
+ * this refuses only a worker that is not behaving like Grok. Tripping a limit
+ * (including the broker's timer) aborts that in-flight upstream call through
+ * its own `AbortSignal` rather than letting it run to completion.
+ */
+export declare class GrokBrokerTurnMeter {
+    readonly limits: EngineBrokerTurnLimits;
+    private readonly onLimit;
+    private readonly now;
+    private readonly startedAt;
+    private readonly timings;
+    private tokens;
+    private reason;
+    private inFlight;
+    private final;
+    private activityAt;
+    constructor(limits: EngineBrokerTurnLimits, onLimit?: (reason: Exclude<EngineBrokerLimitReason, "none">) => void, now?: () => number);
+    /** Returns the request index and its upstream abort signal when admitted, the limit that refused it, or `busy` while another request is in flight. */
+    admit(): Readonly<{
+        index: number;
+        signal: AbortSignal;
+    } | {
+        refused: Exclude<EngineBrokerLimitReason, "none">;
+    } | {
+        busy: true;
+    }>;
+    /**
+     * Records one admitted request's end, its usage, and the tool-call names its
+     * response carried. A response without valid usage (absent, malformed,
+     * implausible, or a failed/aborted call) is charged a conservative estimate
+     * from the request body size, so a missing `usage` can never silently disable
+     * the token ceiling. `toolCalls` is observation only: it never affects
+     * admission, the running total, or any limit.
+     *
+     * `finalReply` is the answer text of a response that called no tool and
+     * stopped ({@link parseGrokFinalReply}). It is recorded only when the same
+     * response decoded to zero tool calls, and only for the request still the
+     * latest: it is what lets the broker end a turn whose worker has finished but
+     * not exited, and report finished work whose stdout the launcher refused.
+     */
+    settle(index: number, usage: EngineBrokerTurnUsage | undefined, requestBytes: number, toolCalls?: readonly string[], finalReply?: string): void;
+    /** The turn's final reply, while no later request has been admitted. */
+    finalReply(): GrokBrokerFinalReply | undefined;
+    /** Whether a model request is in flight right now. */
+    busy(): boolean;
+    /** When a model request last started or settled (the meter's construction before any). */
+    lastActivityAt(): number;
+    /** Trips a limit from outside the request path (the broker's wall-clock timer). */
+    trip(reason: Exclude<EngineBrokerLimitReason, "none">): void;
+    /** Aborts the in-flight upstream call, if any (limit trip, or the broker ending the turn). */
+    abortInFlight(): void;
+    snapshot(): GrokBrokerTurnMeterSnapshot;
+}
+/** The charge for a request without valid usage: `ceil(bodyBytes / 2)` input plus a fixed output allowance. */
+export declare const estimateGrokRequestUsage: (requestBytes: number) => EngineBrokerTurnUsage;
+/**
+ * Upstream-reported usage of one chat-completions response, or `undefined`.
+ *
+ * The proxy buffers the whole upstream body, so the last `usage` object of an
+ * SSE stream (`stream_options.include_usage`) or of a JSON body is available
+ * before the body is returned to the worker. OpenAI-shaped `prompt_tokens`
+ * include cached tokens; they are split into disjoint buckets here, and any
+ * reasoning tokens reported outside `completion_tokens` (visible as
+ * `total_tokens` above prompt + completion) are folded into `output` so the
+ * total invariant holds. A malformed block, or one whose total exceeds
+ * `GROK_ENGINE_BROKER.turnLimits.requestUsageMaxTokens`, is invalid: never
+ * zero-filled and never added — the meter charges an estimate instead.
+ */
+export declare function parseGrokUpstreamUsage(body: Uint8Array, contentType: string | undefined): EngineBrokerTurnUsage | undefined;
+/** At most this many names per request row; a longer list ends in {@link GROK_TOOL_CALL_TRUNCATED}. */
+export declare const GROK_REQUEST_TOOL_CALLS_MAX = 16;
+/** A `name` that is not a plain short identifier is counted, never passed through. */
+export declare const GROK_TOOL_CALL_INVALID = "<invalid>";
+export declare const GROK_TOOL_CALL_TRUNCATED = "<truncated>";
+/**
+ * The tool-call NAMES one upstream response carried, and nothing else.
+ *
+ * Two live turns could not answer "did the model ever try `use_tool` or
+ * `search_tool`", because the per-request rows recorded timings and tokens but
+ * never an attempt. This is that answer, under four rules:
+ *
+ * - names only. No arguments, no message content, no tokens, no header. A
+ *   `name` that is not a plain short identifier is recorded as
+ *   {@link GROK_TOOL_CALL_INVALID} rather than passing provider bytes through;
+ * - bounded. At most {@link GROK_REQUEST_TOOL_CALLS_MAX} entries, the last being
+ *   {@link GROK_TOOL_CALL_TRUNCATED} when the response carried more, so a
+ *   pathological response cannot write an unbounded row;
+ * - absence stays absence. A decoded response that called nothing returns `[]`;
+ *   a response that could not be decoded returns `undefined` and the row records
+ *   no field at all;
+ * - one streaming call names itself in one delta and streams its arguments in
+ *   the rest, so a repeat of the same `(choice, call)` index is that same call,
+ *   not a second attempt.
+ */
+export declare function parseGrokResponseToolNames(body: Uint8Array, contentType: string | undefined): readonly string[] | undefined;
+/** The most of a final reply the broker reports; the rest is cut at a marker that says how much. */
+export declare const GROK_FINAL_REPLY_MAX_BYTES: number;
+/**
+ * The answer text of a response that *stopped*: every `delta.content` of a
+ * streamed response (or the `message.content` of a JSON one) in order, when
+ * some choice finished with `finish_reason: "stop"` and none with anything else.
+ *
+ * `undefined` means the response is not known to be final — undecodable, no
+ * finish reason, or one that asks for a tool. The caller additionally requires
+ * the same body to have decoded to zero tool calls. The text is bounded by
+ * {@link boundGrokFinalReply}, so a runaway answer can never make the turn's
+ * own report the thing that fails it.
+ */
+export declare function parseGrokFinalReply(body: Uint8Array, contentType: string | undefined): string | undefined;
+/** `text` whole when it fits {@link GROK_FINAL_REPLY_MAX_BYTES}, else its head and a marker naming what was cut — never a failure. */
+export declare function boundGrokFinalReply(text: string, maxBytes?: number): string;
+//# sourceMappingURL=grokBrokerTurnMeter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerTurnMeter.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerTurnMeter.ts"],"names":[],"mappings":"AACA,OAAO,EAA4B,KAAK,uBAAuB,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAElK;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC;AACxK,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,uBAAuB,CAAC;IAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAA;CAAE,CAAC,CAAC;AAC5O,wHAAwH;AACxH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEzF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAC;AACnD,yGAAyG;AACzG,eAAO,MAAM,iBAAiB,GAAI,OAAO,qBAAqB,KAAG,MAC4B,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,mBAAmB;IAQlB,QAAQ,CAAC,MAAM,EAAE,sBAAsB;IAAE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAgF,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPjL,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiI;IACzJ,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,QAAQ,CAA6D;IAC7E,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,UAAU,CAAS;gBACN,MAAM,EAAE,sBAAsB,EAAmB,OAAO,GAAE,CAAC,MAAM,EAAE,OAAO,CAAC,uBAAuB,EAAE,MAAM,CAAC,KAAK,IAAsB,EAAmB,GAAG,GAAE,MAAM,MAAiB;IAK1M,sJAAsJ;IACtJ,KAAK,IAAI,QAAQ,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC;IAgBlI;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAa/I,wEAAwE;IACxE,UAAU,IAAI,oBAAoB,GAAG,SAAS;IAC9C,sDAAsD;IACtD,IAAI,IAAI,OAAO;IACf,0FAA0F;IAC1F,cAAc,IAAI,MAAM;IAExB,mFAAmF;IACnF,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,uBAAuB,EAAE,MAAM,CAAC,GAAG,IAAI;IAO5D,8FAA8F;IAC9F,aAAa,IAAI,IAAI;IAErB,QAAQ,IAAI,2BAA2B;CAIxC;AAID,+GAA+G;AAC/G,eAAO,MAAM,wBAAwB,GAAI,cAAc,MAAM,KAAG,qBAG/D,CAAC;AAMF;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,qBAAqB,GAAG,SAAS,CAU3H;AA0BD,uGAAuG;AACvG,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAClD,eAAO,MAAM,wBAAwB,gBAAgB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CA2B3H;AAED,oGAAoG;AACpG,eAAO,MAAM,0BAA0B,QAAY,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAkBzG;AAED,sIAAsI;AACtI,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAA6B,GAAG,MAAM,CAQ/F"}