@noopolis/daimon 0.1.2 → 0.2.1

package/dist/runtime/grokBrokerProxy.d.ts

@@ -0,0 +1,69 @@
+import { type GrokBrokerRunBudget } from "./grokBrokerRunBudget.js";
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { EngineBrokerCapabilities } from "./engineBrokerCapabilities.js";
+import { type GrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+import { authorizeGrokBrokerProxyRequest } from "./grokBrokerProxyRequest.js";
+import { type GrokBrokerTurnMeter } from "./grokBrokerTurnMeter.js";
+import type { GrokInferenceGrants } from "./grokInferenceGrants.js";
+import { type GrokBrokerProviderClock } from "./grokBrokerProviderClock.js";
+/** One running turn as the proxy sees it: its declared model/effort and its spend gate. */
+export type GrokBrokerProxyTurn = Readonly<{
+    policy: GrokBrokerModelPolicy;
+    meter: GrokBrokerTurnMeter;
+    clock?: GrokBrokerProviderClock;
+}>;
+export type GrokBrokerCredentialAuthority = Readonly<{
+    accessToken(forceRefresh: boolean): Promise<string>;
+    refreshAfterRejection?(rejectedTokenDigest: string): Promise<string>;
+    markRejected(rejectedTokenDigest?: string): Promise<void>;
+    isStale?(): boolean;
+}>;
+export type GrokBrokerUpstream = (request: ReturnType<typeof authorizeGrokBrokerProxyRequest>, signal?: AbortSignal) => Promise<Readonly<{
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    body: Uint8Array;
+}>>;
+/**
+ * `policy` is the fallback declared model/effort (closed list); a registered
+ * turn's own policy wins. A request whose turn has no registered meter is
+ * refused like one without an isolation guard: nothing is forwarded unmetered.
+ * `listenPort` exists for tests that must not contend for the production port.
+ *
+ * `grants` are evaluator inference grants (`grokInferenceGrants.ts`): a bearer
+ * carrying the grant prefix is looked up only there and served by
+ * `grokInferenceProxy.ts`; every other bearer is looked up only among turn
+ * capabilities. Without `grants` a prefixed bearer is simply refused.
+ */
+export declare function startGrokBrokerProxy(authority: GrokBrokerCredentialAuthority, upstream?: GrokBrokerUpstream, policy?: GrokBrokerModelPolicy, listenPort?: number, grants?: GrokInferenceGrants, runBudget?: GrokBrokerRunBudget): Promise<{
+    port: number;
+    close: () => Promise<void>;
+    capabilities: EngineBrokerCapabilities;
+    registerIsolationGuard(turnId: string, guard: () => Promise<void>): void;
+    revokeIsolationGuard(turnId: string): void;
+    registerTurn(turnId: string, turn: GrokBrokerProxyTurn): void;
+    revokeTurn(turnId: string): void;
+    serve: (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+}>;
+/** @internal The production request handler, usable without opening a socket. */
+export declare function createGrokBrokerProxyHandler(authority: GrokBrokerCredentialAuthority, upstream?: GrokBrokerUpstream, policy?: GrokBrokerModelPolicy, grants?: GrokInferenceGrants, runBudget?: GrokBrokerRunBudget): {
+    capabilities: EngineBrokerCapabilities;
+    registerIsolationGuard(turnId: string, guard: () => Promise<void>): void;
+    revokeIsolationGuard(turnId: string): void;
+    registerTurn(turnId: string, turn: GrokBrokerProxyTurn): void;
+    revokeTurn(turnId: string): void;
+    serve: (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+};
+/**
+ * A refusal the caller must not retry.
+ *
+ * Every internal refusal used to collapse into one bare 503. Grok treats 503 as
+ * transient and blind-retries the same request (observed: 14 retries, ~141k
+ * estimated tokens, then `exit 1`), so a policy miss burned a turn's budget and
+ * reported itself as an engine crash. Policy refusals now answer 400 with a
+ * reason, and only genuinely transient faults keep 503.
+ */
+export declare class GrokBrokerProxyRefusal extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+//# sourceMappingURL=grokBrokerProxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerProxy.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerProxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAExF,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAIpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAgE,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACtI,OAAO,EAAE,+BAA+B,EAAE,MAAM,6BAA6B,CAAC;AAE9E,OAAO,EAA2E,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG7I,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAkC,KAAK,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5G,2FAA2F;AAC3F,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,KAAK,CAAC,EAAE,uBAAuB,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IAAE,WAAW,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAAC,qBAAqB,CAAC,CAAC,mBAAmB,EAAC,MAAM,GAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAAC,YAAY,CAAC,mBAAmB,CAAC,EAAC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,CAAC,IAAI,OAAO,CAAA;CAAE,CAAC,CAAC;AACjQ,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,+BAA+B,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC,CAAC;AAE3N;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,6BAA6B,EAAE,QAAQ,GAAE,kBAAoC,EACxF,MAAM,GAAE,qBAAwD,EAAE,UAAU,SAAS,EACrF,MAAM,CAAC,EAAE,mBAAmB,EAAE,SAAS,CAAC,EAAE,mBAAmB;;;;mCAoC5B,MAAM,SAAS,MAAM,OAAO,CAAC,IAAI,CAAC;iCACpC,MAAM;yBACd,MAAM,QAAQ,mBAAmB;uBAMnC,MAAM;qBACR,eAAe,YAAY,cAAc;GA5B7D;AAED,iFAAiF;AACjF,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,6BAA6B,EAAE,QAAQ,GAAE,kBAAoC,EACxF,MAAM,GAAE,qBAAwD,EAAE,MAAM,CAAC,EAAE,mBAAmB,EAAE,SAAS,CAAC,EAAE,mBAAmB;;mCAc9F,MAAM,SAAS,MAAM,OAAO,CAAC,IAAI,CAAC;iCACpC,MAAM;yBACd,MAAM,QAAQ,mBAAmB;uBAMnC,MAAM;qBACR,eAAe,YAAY,cAAc;EAI7D;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CACpC"}

package/dist/runtime/grokBrokerProxy.js

@@ -0,0 +1,326 @@
+import { GrokBrokerRunLimit } from "./grokBrokerRunBudget.js";
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { redactCredentialText } from "../core/credentialRedaction.js";
+import { CLI_ENGINE_MAX_DIAGNOSTIC_BYTES } from "../pi/cliChildOutput.js";
+import { EngineBrokerCapabilities } from "./engineBrokerCapabilities.js";
+import { ENGINE_BROKER_AUTH_STALE } from "./engineBrokerProtocol.js";
+import { DEFAULT_GROK_BROKER_MODEL_POLICY, parseGrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+import { authorizeGrokBrokerProxyRequest } from "./grokBrokerProxyRequest.js";
+import { GROK_SESSION_TITLE_SINK_KEY } from "./grokBrokerWorkerConfig.js";
+import { parseGrokFinalReply, parseGrokResponseToolNames, parseGrokUpstreamUsage } from "./grokBrokerTurnMeter.js";
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+import { serveGrokInferenceGrant } from "./grokInferenceProxy.js";
+import { GrokBrokerProviderClockRefusal } from "./grokBrokerProviderClock.js";
+/**
+ * `policy` is the fallback declared model/effort (closed list); a registered
+ * turn's own policy wins. A request whose turn has no registered meter is
+ * refused like one without an isolation guard: nothing is forwarded unmetered.
+ * `listenPort` exists for tests that must not contend for the production port.
+ *
+ * `grants` are evaluator inference grants (`grokInferenceGrants.ts`): a bearer
+ * carrying the grant prefix is looked up only there and served by
+ * `grokInferenceProxy.ts`; every other bearer is looked up only among turn
+ * capabilities. Without `grants` a prefixed bearer is simply refused.
+ */
+export async function startGrokBrokerProxy(authority, upstream = defaultUpstream, policy = DEFAULT_GROK_BROKER_MODEL_POLICY, listenPort = 43_123, grants, runBudget) {
+    const handler = createGrokBrokerProxyHandler(authority, upstream, policy, grants, runBudget);
+    const server = createServer((request, response) => { void handler.serve(request, response); });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(listenPort, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+    });
+    const address = server.address();
+    return {
+        ...handler, port: address.port,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => error === undefined ? resolve() : reject(error));
+            // A worker's idle pooled socket otherwise leaves close() without a bound.
+            server.closeAllConnections();
+        })
+    };
+}
+/** @internal The production request handler, usable without opening a socket. */
+export function createGrokBrokerProxyHandler(authority, upstream = defaultUpstream, policy = DEFAULT_GROK_BROKER_MODEL_POLICY, grants, runBudget) {
+    const admittedUpstream = async (request, signal) => {
+        signal?.throwIfAborted();
+        await runBudget?.reserve();
+        signal?.throwIfAborted();
+        return upstream(request, signal);
+    };
+    const declared = parseGrokBrokerModelPolicy(policy);
+    const capabilities = new EngineBrokerCapabilities();
+    const guards = new Map();
+    const turns = new Map();
+    return {
+        capabilities,
+        registerIsolationGuard(turnId, guard) { guards.set(turnId, guard); },
+        revokeIsolationGuard(turnId) { guards.delete(turnId); },
+        registerTurn(turnId, turn) {
+            turns.set(turnId, {
+                policy: parseGrokBrokerModelPolicy(turn.policy), meter: turn.meter,
+                ...(turn.clock === undefined ? {} : { clock: turn.clock })
+            });
+        },
+        revokeTurn(turnId) { turns.delete(turnId); },
+        serve: (request, response) => serve(request, response, authority, admittedUpstream, capabilities, guards, turns, declared, grants)
+    };
+}
+/**
+ * A refusal the caller must not retry.
+ *
+ * Every internal refusal used to collapse into one bare 503. Grok treats 503 as
+ * transient and blind-retries the same request (observed: 14 retries, ~141k
+ * estimated tokens, then `exit 1`), so a policy miss burned a turn's budget and
+ * reported itself as an engine crash. Policy refusals now answer 400 with a
+ * reason, and only genuinely transient faults keep 503.
+ */
+export class GrokBrokerProxyRefusal extends Error {
+    reason;
+    constructor(reason) {
+        super(`grok broker proxy refused: ${reason}`);
+        this.reason = reason;
+    }
+}
+async function serve(request, response, authority, upstream, capabilities, guards, turns, fallback, grants) {
+    let settle;
+    let titleSink = false;
+    // Every credential this request holds, kept only for this request and only so
+    // that a fault's own words can be redacted against them exactly as the CLI
+    // child and launcher diagnostics are. Nothing reads them but {@link brokerFaultCause}.
+    const secrets = [];
+    try {
+        let body = await readBody(request);
+        const headers = Object.fromEntries(Object.entries(request.headers).map(([key, value]) => [key, Array.isArray(value) ? value[0] : value]));
+        titleSink = headers.authorization === `Bearer ${GROK_SESSION_TITLE_SINK_KEY}`;
+        const match = headers.authorization?.match(/^Bearer ([A-Za-z0-9_-]{40,})$/u);
+        if (match)
+            secrets.push(match[1]);
+        if (match && match[1].startsWith(GROK_ENGINE_BROKER.inferenceGrants.tokenPrefix)) {
+            if (!grants)
+                throw new GrokBrokerProxyRefusal("inference_grants_unavailable");
+            return await serveGrokInferenceGrant({ method: request.method ?? "", pathname: new URL(request.url ?? "/", "http://127.0.0.1").pathname, headers, body, token: match[1] }, response, grants, authority, upstream);
+        }
+        const scope = match ? capabilities.inspectToken(match[1]) : undefined;
+        if (!scope)
+            throw new GrokBrokerProxyRefusal("unknown_capability");
+        const guard = guards.get(scope.turnId), turn = turns.get(scope.turnId);
+        if (!guard || !turn)
+            throw new GrokBrokerProxyRefusal("no_active_turn");
+        try {
+            await guard();
+        }
+        catch (error) {
+            throw new GrokBrokerProxyRefusal("worker_isolation_unverified");
+        }
+        // Neutralize engine context before the existing body gate or bearer read.
+        // The clock belongs to this turn, never to the slot's installed variant.
+        try {
+            if (turn.clock !== undefined)
+                body = Buffer.from(turn.clock.rewrite(body));
+        }
+        catch (error) {
+            if (error instanceof GrokBrokerProviderClockRefusal)
+                throw new GrokBrokerProxyRefusal(error.reason);
+            throw error;
+        }
+        // A fenced realm is not a transient fault: the credential is gone until an
+        // operator re-logs in, and 503 made Grok blind-retry it (observed: fifteen
+        // retries over five minutes, $0 spent, nothing learned). Named, 400, and
+        // checked before the credential read, so the miss costs one round trip.
+        if (authority.isStale?.() === true)
+            throw new GrokBrokerProxyRefusal(ENGINE_BROKER_AUTH_STALE);
+        let token = await authority.accessToken(false);
+        secrets.push(token);
+        const rejectedDigest = createHash("sha256").update(token).digest("hex");
+        let prepared = authorizeRequestOrRefuse({ method: request.method ?? "", pathname: new URL(request.url ?? "/", "http://127.0.0.1").pathname, headers, body }, capabilities, token, turn.policy ?? fallback);
+        token = "";
+        // The spend gate runs after the body is proven a real lean worker request
+        // (a refused session-title body never counts) and before any upstream call.
+        const admission = turn.meter.admit();
+        if ("refused" in admission) {
+            response.writeHead(429, { "content-type": "application/json", "cache-control": "no-store" });
+            response.end(JSON.stringify({ error: "turn limit reached", limit: admission.refused }));
+            return;
+        }
+        if ("busy" in admission) {
+            response.writeHead(429, { "content-type": "application/json", "cache-control": "no-store" });
+            response.end('{"error":"turn request in flight"}');
+            return;
+        }
+        settle = (usage, toolCalls, finalReply) => { turn.meter.settle(admission.index, usage, body.byteLength, toolCalls, finalReply); settle = undefined; };
+        let result = await upstream(prepared, admission.signal);
+        if (result.status === 401) {
+            token = authority.refreshAfterRejection ? await authority.refreshAfterRejection(rejectedDigest) : await authority.accessToken(true);
+            secrets.push(token);
+            const refreshedDigest = createHash("sha256").update(token).digest("hex");
+            prepared = { ...prepared, headers: { ...prepared.headers, authorization: `Bearer ${token}` } };
+            token = "";
+            result = await upstream(prepared, admission.signal);
+            if (result.status === 401)
+                await authority.markRejected(refreshedDigest);
+        }
+        // Names only, bounded, and never a reason to fail the request: the response
+        // is already buffered here for its usage block, so what the model tried to
+        // call is in hand. A decoder fault records no attempt rather than a false
+        // empty one, and never disturbs the turn.
+        // A successful answer that called nothing and stopped is the turn's final
+        // reply: the broker ends a worker that finished but did not exit on it
+        // (`grokEngineBrokerTurnEnd.ts`), and reports it when the launcher refused
+        // the worker's stdout. Observation only, exactly like the tool names.
+        settle?.(usageOrEstimate(result.body, result.headers["content-type"]), toolCallsOrNothing(result.body, result.headers["content-type"]), result.status === 200 ? finalReplyOrNothing(result.body, result.headers["content-type"]) : undefined);
+        response.writeHead(result.status, { "content-type": result.headers["content-type"] ?? "application/json", "cache-control": "no-store" });
+        response.end(result.body);
+    }
+    catch (error) {
+        settle?.(undefined);
+        if (error instanceof GrokBrokerRunLimit) {
+            response.writeHead(429, { "content-type": "application/json", "cache-control": "no-store" });
+            response.end('{"error":"run_request_limit"}');
+            return;
+        }
+        // Name the refusal on the broker's own stderr (reason code only, never a body
+        // or a token) so a failing turn is diagnosable without a stub harness —
+        // except for the two requests every healthy turn makes anyway.
+        // The request that *discovers* the fence throws an ordinary error from the
+        // credential authority, so it is promoted to the same named refusal: one
+        // stale realm must not read as one transient fault plus fourteen retries.
+        const fenced = !(error instanceof GrokBrokerProxyRefusal) && authority.isStale?.() === true;
+        const refused = error instanceof GrokBrokerProxyRefusal || fenced;
+        const refusal = error instanceof GrokBrokerProxyRefusal ? error.reason : fenced ? ENGINE_BROKER_AUTH_STALE : "broker_unavailable";
+        // A named refusal is its own account; anything else used to reach the log as
+        // the bare word `broker_unavailable`, which names nothing — so it carries the
+        // fault's own class and message, and nothing else, beside it.
+        const named = refused ? refusal : `${refusal} (${brokerFaultCause(error, secrets)})`;
+        if (!titleSink && !expectedWorkerProbe(request))
+            process.stderr.write(`[grok-proxy] refused: ${named}\n`);
+        // Grok's own session-title call is refused by design, and keeps the transient
+        // 503 shape it has always had. Forcing 400 and 503 on it were both observed
+        // to end the turn `exit=0, result: success`, so the shape is kept because it
+        // is the one every live capture was taken with, not because a 4xx there ends
+        // Grok's session — it does not.
+        if (titleSink) {
+            response.writeHead(503, { "content-type": "application/json", "cache-control": "no-store" });
+            response.end('{"error":"broker unavailable"}');
+            return;
+        }
+        if (refused) {
+            response.writeHead(400, { "content-type": "application/json", "cache-control": "no-store" });
+            response.end(JSON.stringify({ error: "broker refused this request", reason: refusal }));
+            return;
+        }
+        response.writeHead(503, { "content-type": "application/json", "cache-control": "no-store" });
+        response.end('{"error":"broker unavailable"}');
+    }
+    finally {
+        secrets.length = 0;
+    }
+}
+/**
+ * A non-refusal fault, named on one bounded line.
+ *
+ * `broker_unavailable` on its own carries no diagnostic content at all, and it
+ * is answered 503, which Grok blind-retries: one live turn emitted it fifteen
+ * times over five minutes, spent $0 — so no upstream call ever succeeded — and
+ * died with no account of why. The error's own class and message are the whole
+ * of what is logged: never a request body, bearer, capability, session id or
+ * header. It is redacted exactly as the failed CLI child and the launcher's
+ * worker diagnostic are — `redactCredentialText` with this request's own
+ * capabilities as exact secrets and the same `CLI_ENGINE_MAX_DIAGNOSTIC_BYTES`
+ * bound — and flattened to one line, because it travels on a log line. Naming
+ * a fault must never be able to fail the response that reports it, so a value
+ * that cannot even be described degrades to a marker.
+ *
+ * One level of `cause` is named too, because the fault this exists for names
+ * nothing without it: every failed `fetch` to the provider is `TypeError:
+ * fetch failed`, and which fault it was — `ENOTFOUND`, `ECONNREFUSED`, a TLS
+ * refusal, an abort — is only in the cause. An errno error whose message is
+ * empty is named by its `code`.
+ */
+const brokerFaultCause = (error, secrets) => {
+    try {
+        const described = `${describeFault(error)}${error instanceof Error && error.cause !== undefined && error.cause !== null ? ` <- ${describeFault(error.cause)}` : ""}`;
+        const flattened = described.replace(/[\u0000-\u001f\u007f]+/gu, " ").replace(/\s+/gu, " ").trim();
+        const named = redactCredentialText(flattened, secrets, CLI_ENGINE_MAX_DIAGNOSTIC_BYTES).trim();
+        return named.length === 0 ? "unnamed" : named;
+    }
+    catch {
+        return "unnameable";
+    }
+};
+/** One value's class and words: an error's own, or the type of whatever else was thrown. */
+const describeFault = (error) => {
+    if (!(error instanceof Error))
+        return `${typeof error}: ${String(error)}`;
+    const code = error.code;
+    const words = error.message.length > 0 ? error.message : typeof code === "string" ? code : "(no message)";
+    return `${error.constructor?.name ?? error.name}: ${words}`;
+};
+/**
+ * The unauthenticated connectivity probe Grok sends before its own requests: a
+ * bare `GET /` with no Authorization header, which has no capability to look up
+ * and answers 400.
+ *
+ * It and the per-turn `session_title` POST are the only two requests a healthy
+ * turn makes that this proxy does not forward, and both used to print the same
+ * `refused: unknown_capability` line as a real policy miss — so every healthy
+ * turn read as two refusals and cost a live investigation. They answer exactly
+ * as before; they simply stop claiming a refusal on the broker's stderr, which
+ * is left for the misses that are actually worth reading.
+ */
+const expectedWorkerProbe = (request) => request.headers.authorization === undefined && (request.method ?? "") === "GET" &&
+    new URL(request.url ?? "/", "http://127.0.0.1").pathname === "/";
+/**
+ * Upstream-reported usage, or the documented conservative estimate.
+ *
+ * The decoder faulting must not fail the request that already cost real
+ * money: the upstream call succeeded, the worker is owed its answer, and a
+ * 503 here would throw away a paid response and have Grok buy it again. The
+ * `undefined` this returns is not "no usage" — `GrokBrokerTurnMeter.settle`
+ * charges it `ceil(bodyBytes/2) + 4096` and marks the row
+ * `usage_source: "estimated"`, so the token ceiling still counts it and no
+ * fabricated zero ever reaches a ledger.
+ */
+const usageOrEstimate = (body, contentType) => {
+    try {
+        return parseGrokUpstreamUsage(body, contentType);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Instrumentation must never fail a turn: a throwing decoder records nothing, exactly as an undecodable response does. */
+const toolCallsOrNothing = (body, contentType) => {
+    try {
+        return parseGrokResponseToolNames(body, contentType);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Instrumentation must never fail a turn: a throwing decoder reports no final reply. */
+const finalReplyOrNothing = (body, contentType) => {
+    try {
+        return parseGrokFinalReply(body, contentType);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The body gate, refused non-retryably: a rejected body is a policy miss, never a transient fault. */
+function authorizeRequestOrRefuse(...args) {
+    try {
+        return authorizeGrokBrokerProxyRequest(...args);
+    }
+    catch {
+        throw new GrokBrokerProxyRefusal("request_body_rejected");
+    }
+}
+async function readBody(request) { const chunks = []; let bytes = 0; for await (const chunk of request) {
+    const value = Buffer.from(chunk);
+    bytes += value.length;
+    if (bytes > 2 * 1024 * 1024)
+        throw new Error("too large");
+    chunks.push(value);
+} return Buffer.concat(chunks); }
+const defaultUpstream = async (request, signal) => { const result = await fetch(request.url, { method: "POST", headers: request.headers, body: Buffer.from(request.body), ...(signal === undefined ? {} : { signal }) }); return { status: result.status, headers: { "content-type": result.headers.get("content-type") ?? "application/json" }, body: new Uint8Array(await result.arrayBuffer()) }; };

package/dist/runtime/grokBrokerProxyJson.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Preserve ordinary JSON bytes, including whitespace and escaping. Ambiguous
+ * duplicate members still normalize to the validated values, as the spend gate
+ * requires: an upstream parser must never select a different model or tool set.
+ */
+export declare function parseGrokBrokerProxyJson(body: Uint8Array): {
+    value: Record<string, unknown>;
+    body: Uint8Array;
+};
+//# sourceMappingURL=grokBrokerProxyJson.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerProxyJson.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerProxyJson.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG;IAC1D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,UAAU,CAAC;CAClB,CAuBA"}

package/dist/runtime/grokBrokerProxyJson.js

@@ -0,0 +1,31 @@
+/**
+ * Preserve ordinary JSON bytes, including whitespace and escaping. Ambiguous
+ * duplicate members still normalize to the validated values, as the spend gate
+ * requires: an upstream parser must never select a different model or tool set.
+ */
+export function parseGrokBrokerProxyJson(body) {
+    const source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body);
+    let properties = 0;
+    const value = JSON.parse(source, (key, entry) => {
+        if (key === "__proto__")
+            throw new Error("broker proxy request rejected");
+        if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+            properties += Object.keys(entry).length;
+        }
+        return entry;
+    });
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("broker proxy request rejected");
+    }
+    // JSON.parse established the grammar. Match whole string tokens (including
+    // escaped quotes), so a colon inside message content cannot count as a key.
+    let sourceProperties = 0;
+    for (const token of source.matchAll(/"(?:[^"\\]|\\[\s\S])*"\s*(:)?/gu)) {
+        if (token[1] !== undefined)
+            sourceProperties++;
+    }
+    return {
+        value: value,
+        body: sourceProperties === properties ? body : Buffer.from(JSON.stringify(value))
+    };
+}

package/dist/runtime/grokBrokerProxyRequest.d.ts

@@ -0,0 +1,30 @@
+import type { EngineBrokerCapabilities } from "./engineBrokerCapabilities.js";
+import { type GrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+export type GrokBrokerProxyInput = Readonly<{
+    method: string;
+    pathname: string;
+    headers: Readonly<Record<string, string | undefined>>;
+    body: Uint8Array;
+    agentId?: string;
+    turnId?: string;
+}>;
+export type GrokBrokerUpstreamRequest = Readonly<{
+    url: "https://cli-chat-proxy.grok.com/v1/chat/completions";
+    headers: Readonly<Record<string, string>>;
+    body: Uint8Array;
+}>;
+/**
+ * Authorizes one worker request and rebuilds it for the provider.
+ *
+ * Everything that decides spend is checked here, before a bearer is attached
+ * and before any upstream call:
+ * - the client version is exactly the pinned Grok CLI (`GROK_ENGINE_BROKER.grokCliVersion`);
+ * - the body model and `reasoning_effort` are exactly the declared policy, and
+ *   the model override header follows that declaration instead of a constant;
+ * - the offered tool names are exactly the lean visible set. Grok 1.0.34 turns
+ *   an unmappable `--tools` entry into its full 19-tool set, and its per-turn
+ *   `session_title` request carries a single forced tool; both are refused.
+ */
+export declare function authorizeGrokBrokerProxyRequest(input: GrokBrokerProxyInput, capabilities: EngineBrokerCapabilities, bearer: string, policy?: GrokBrokerModelPolicy): GrokBrokerUpstreamRequest;
+export declare function exactLeanTools(tools: unknown): boolean;
+//# sourceMappingURL=grokBrokerProxyRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerProxyRequest.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerProxyRequest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,EAAgE,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGtI,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAC9L,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,qDAAqD,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AAE9K;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,qBAAwD,GAAG,yBAAyB,CAmChO;AASD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAStD"}

package/dist/runtime/grokBrokerProxyRequest.js

@@ -0,0 +1,85 @@
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+import { GROK_WORKER_VISIBLE_TOOLS } from "../contracts/grokWorkerContract.js";
+import { DEFAULT_GROK_BROKER_MODEL_POLICY, parseGrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+const MAX_BODY = 2 * 1024 * 1024;
+/**
+ * Authorizes one worker request and rebuilds it for the provider.
+ *
+ * Everything that decides spend is checked here, before a bearer is attached
+ * and before any upstream call:
+ * - the client version is exactly the pinned Grok CLI (`GROK_ENGINE_BROKER.grokCliVersion`);
+ * - the body model and `reasoning_effort` are exactly the declared policy, and
+ *   the model override header follows that declaration instead of a constant;
+ * - the offered tool names are exactly the lean visible set. Grok 1.0.34 turns
+ *   an unmappable `--tools` entry into its full 19-tool set, and its per-turn
+ *   `session_title` request carries a single forced tool; both are refused.
+ */
+export function authorizeGrokBrokerProxyRequest(input, capabilities, bearer, policy = DEFAULT_GROK_BROKER_MODEL_POLICY) {
+    const declared = parseGrokBrokerModelPolicy(policy);
+    if (input.method !== "POST" || input.pathname !== "/v1/chat/completions" || input.body.byteLength < 2 || input.body.byteLength > MAX_BODY)
+        throw new Error("broker proxy request rejected");
+    const authorization = input.headers.authorization;
+    const match = authorization?.match(/^Bearer ([A-Za-z0-9_-]{40,})$/u);
+    if (match === null || match === undefined)
+        throw new Error("broker proxy request rejected");
+    const scope = capabilities.authorizeToken(match[1]);
+    if (scope === undefined || (input.agentId !== undefined && scope.agentId !== input.agentId) || (input.turnId !== undefined && scope.turnId !== input.turnId))
+        throw new Error("broker proxy request rejected");
+    if (!bearer || /[\r\n]/u.test(bearer))
+        throw new Error("broker credential authority unavailable");
+    const clientVersion = input.headers["x-grok-client-version"];
+    if (clientVersion !== GROK_ENGINE_BROKER.grokCliVersion)
+        throw new Error("broker proxy request rejected");
+    let parsed;
+    // `__proto__` is refused at any depth: JSON.parse makes it an ordinary own
+    // member, but an upstream JavaScript parser may treat it as a prototype.
+    try {
+        parsed = JSON.parse(Buffer.from(input.body).toString("utf8"), (key, value) => {
+            if (key === "__proto__")
+                throw new Error("broker proxy request rejected");
+            return value;
+        });
+    }
+    catch {
+        throw new Error("broker proxy request rejected");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || parsed.stream !== true || !Array.isArray(parsed.messages))
+        throw new Error("broker proxy request rejected");
+    if (parsed.model !== declared.model || parsed.reasoning_effort !== declared.reasoningEffort)
+        throw new Error("broker proxy request rejected");
+    if (!exactLeanTools(parsed.tools))
+        throw new Error("broker proxy request rejected");
+    if (Object.keys(parsed).some((key) => !LEAN_BODY_MEMBERS.has(key)) || !validStreamOptions(parsed.stream_options))
+        throw new Error("broker proxy request rejected");
+    // Keep origin/main's production handling: UTF-8 replacement decoding, then
+    // serialize the validated object (including last-member-wins duplicates).
+    // Only a clocked turn takes the stricter date rewrite before this gate.
+    return {
+        url: "https://cli-chat-proxy.grok.com/v1/chat/completions",
+        headers: {
+            authorization: `Bearer ${bearer}`, "content-type": "application/json",
+            "x-xai-token-auth": "xai-grok-cli", "x-grok-model-override": declared.model,
+            "x-grok-client-version": clientVersion, "x-grok-client-identifier": "grok-shell"
+        },
+        body: Buffer.from(JSON.stringify(parsed))
+    };
+}
+/** Top-level members of a Grok 1.0.34 lean worker chat-completions body (live stub capture). */
+const LEAN_BODY_MEMBERS = new Set(["messages", "model", "reasoning_effort", "stream", "stream_options", "tools"]);
+/** Members of each lean tool `function` entry (live stub capture). */
+const LEAN_FUNCTION_MEMBERS = new Set(["description", "name", "parameters"]);
+const validStreamOptions = (value) => value === undefined
+    || (value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).every((key) => key === "include_usage") && typeof value.include_usage === "boolean");
+export function exactLeanTools(tools) {
+    if (!Array.isArray(tools) || tools.length !== GROK_WORKER_VISIBLE_TOOLS.length)
+        return false;
+    const names = tools.map((tool) => {
+        if (tool === null || typeof tool !== "object" || Array.isArray(tool) || tool.type !== "function" || Object.keys(tool).some((key) => key !== "type" && key !== "function"))
+            return undefined;
+        const fn = tool.function;
+        if (fn === null || typeof fn !== "object" || Array.isArray(fn) || Object.keys(fn).some((key) => !LEAN_FUNCTION_MEMBERS.has(key)))
+            return undefined;
+        return fn.name;
+    });
+    return JSON.stringify([...names].sort()) === JSON.stringify(GROK_WORKER_VISIBLE_TOOLS);
+}

package/dist/runtime/grokBrokerRealmLease.d.ts

@@ -0,0 +1,4 @@
+export declare function acquireGrokBrokerRealmLease(root: string, flock?: string): Promise<Readonly<{
+    close(): Promise<void>;
+}>>;
+//# sourceMappingURL=grokBrokerRealmLease.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerRealmLease.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerRealmLease.ts"],"names":[],"mappings":"AAMA,wBAAsB,2BAA2B,CAAC,IAAI,EAAC,MAAM,EAAC,KAAK,SAAQ,GAAE,OAAO,CAAC,QAAQ,CAAC;IAAC,KAAK,IAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAC,CAAC,CAAC,CAGtH"}

package/dist/runtime/grokBrokerRealmLease.js

@@ -0,0 +1,33 @@
+import { spawnRealTime as spawn } from "./taskClockProcess.js";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { terminateChild, trackCliChild } from "../pi/cliProcess.js";
+export async function acquireGrokBrokerRealmLease(root, flock = "flock") {
+    const handle = await open(path.join(root, ".daimon-broker-lease"), constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+    let child;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600)
+            throw new Error();
+        child = trackCliChild(spawn("/bin/sh", ["-c", '"$1" --exclusive --nonblock --conflict-exit-code 73 3 || exit 73; printf "ready\\n"; IFS= read -r _hold || :', "daimon-grok-broker-lease", flock], { detached: process.platform !== "win32", env: { PATH: process.env.PATH, LANG: "C", LC_ALL: "C", TZ: "UTC" }, stdio: ["pipe", "pipe", "ignore", handle.fd] }));
+        await ready(child);
+        let closed = false;
+        return { close: async () => { if (closed)
+                return; closed = true; const exited = new Promise((resolve) => { if (child.exitCode !== null || child.signalCode !== null)
+                return resolve(true); child.once("close", () => resolve(true)); setTimeout(() => resolve(false), 500); }); child.stdin?.end(); if (!await exited)
+                await terminateChild(child); } };
+    }
+    catch {
+        if (child)
+            await terminateChild(child).catch(() => undefined);
+        throw new Error("Grok broker realm is already in use or cannot be leased");
+    }
+    finally {
+        await handle.close();
+    }
+}
+function ready(child) { return new Promise((resolve, reject) => { const timer = setTimeout(() => reject(new Error()), 5000); const fail = () => { clearTimeout(timer); reject(new Error()); }; child.once("error", fail); child.once("close", fail); child.stdout?.once("data", (chunk) => { clearTimeout(timer); if (chunk.toString() === "ready\n")
+    resolve();
+else
+    reject(new Error()); }); }); }

package/dist/runtime/grokBrokerRefresh.d.ts

@@ -0,0 +1,2 @@
+export declare function refreshGrokBrokerCredential(command: string, grokHome: string, timeoutMs?: number): Promise<void>;
+//# sourceMappingURL=grokBrokerRefresh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokBrokerRefresh.d.ts","sourceRoot":"","sources":["../../src/runtime/grokBrokerRefresh.ts"],"names":[],"mappings":"AAIA,wBAAsB,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAKtH"}

package/dist/runtime/grokBrokerRefresh.js

@@ -0,0 +1,15 @@
+import { spawnRealTime as spawn } from "./taskClockProcess.js";
+import { readChild } from "../pi/cliChildOutput.js";
+import { terminateChild, trackCliChild } from "../pi/cliProcess.js";
+export async function refreshGrokBrokerCredential(command, grokHome, timeoutMs = 15_000) {
+    const child = trackCliChild(spawn(command, ["models"], { detached: process.platform !== "win32", env: { GROK_HOME: grokHome, HOME: grokHome, PATH: process.env.PATH, LANG: "C", LC_ALL: "C", TZ: "UTC" }, stdio: ["ignore", "pipe", "pipe"] }));
+    try {
+        await readChild(child, timeoutMs, []);
+    }
+    catch {
+        throw new Error("Grok broker credential refresh failed");
+    }
+    finally {
+        await terminateChild(child).catch(() => undefined);
+    }
+}