@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/grokBrokerProjection.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { canonicalJson } from "../contracts/canonicalJson.js";
+import { DAIMON_GROK_SYSTEM_PROMPT } from "../contracts/grokWorkerContract.js";
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+import { grokSandboxProtectedPaths } from "./engineDispatcher.js";
+import { parseEngineBrokerServiceConfig } from "./engineBrokerServiceConfig.js";
+import { parseEngineBrokerTurnLimits } from "./engineBrokerTurnAccounting.js";
+import { grokBrokerWorkerConfigSha256 } from "./grokBrokerWorkerConfig.js";
+import { GROK_WORKER_SANDBOX_PROFILE, grokWorkerEventsPathFor, renderGrokWorkerSandboxProfile, grokWorkerSandboxProfileSha256 } from "./grokWorkerSandboxProfile.js";
+import { parseOrganizationRuntimeConfig } from "./organizationRuntime.js";
+export const GROK_BROKER_PROJECTION_VERSION = GROK_ENGINE_BROKER.projectionVersion;
+/**
+ * Resolve the public Grok broker projection for one agent.
+ *
+ * Paths are taken as given, never resolved: the caller (Spawnfile provisioning)
+ * must supply canonical, non-symlink paths — the fixed tmpfs/workspace roots it
+ * creates — and its provisioning must verify they are not symlinks before a
+ * slot is used; the broker's own attestation re-checks the worker home at
+ * every turn.
+ *
+ * Deterministic and I/O-free on purpose: its digest
+ * ({@link grokBrokerProjectionSha256}) is what the slot preflight receipt
+ * binds, so the supervisor that writes the receipt and the evaluator that reads
+ * it must compute byte-equal projections from the same inputs.
+ *
+ * The agent must be a Grok agent that *declares* its model and reasoning
+ * effort; nothing is defaulted. The deny list is Daimon's own protected set for
+ * this agent (realm, bootstrap, peers, and the mask covering the acceptance
+ * store) plus the caller's evaluator paths, sorted and deduplicated exactly as
+ * the profile renderer does. A supplied `profileSha256` that differs is
+ * refused.
+ */
+export function resolveOrganizationGrokBrokerProjection(config, agentId, options) {
+    const parsed = parseOrganizationRuntimeConfig(config);
+    const agent = parsed.agents.find((entry) => entry.id === agentId);
+    if (agent === undefined || agent.engine.kind !== "grok")
+        throw new Error("Grok broker projection requires a known Grok agent");
+    if (agent.engine.model === undefined || agent.engine.reasoningEffort === undefined)
+        throw new Error("Grok broker projection requires a declared model and reasoning effort");
+    for (const [label, value] of [["workerHomePath", options.workerHomePath], ["acceptanceStorePath", options.acceptanceStorePath]]) {
+        if (!path.posix.isAbsolute(value) || path.posix.normalize(value) !== value || value === "/" || value.endsWith("/"))
+            throw new Error(`Grok broker projection requires a canonical absolute ${label}`);
+    }
+    if (!/^[a-f0-9]{64}$/u.test(options.seccompProfileSha256))
+        throw new Error("Grok broker projection requires a seccomp profile sha256");
+    const model = agent.engine.model, reasoningEffort = agent.engine.reasoningEffort;
+    const denyPaths = [...new Set([...grokSandboxProtectedPaths(agent.id, parsed.agents, [options.acceptanceStorePath]), ...(options.denyPaths ?? [])])].sort();
+    renderGrokWorkerSandboxProfile(denyPaths);
+    const profileSha256 = grokWorkerSandboxProfileSha256(denyPaths);
+    if (options.profileSha256 !== undefined && options.profileSha256 !== profileSha256)
+        throw new Error("Grok broker projection profile digest mismatch");
+    const workerConfigSha256 = grokBrokerWorkerConfigSha256({ model, reasoningEffort });
+    if (workerConfigSha256 !== GROK_ENGINE_BROKER.worker.configSha256[model][reasoningEffort])
+        throw new Error("Grok broker projection worker config drifted from the manifest");
+    if (createHash("sha256").update(DAIMON_GROK_SYSTEM_PROMPT).digest("hex") !== GROK_ENGINE_BROKER.worker.systemPromptSha256)
+        throw new Error("Grok broker projection system prompt drifted from the manifest");
+    const artifact = GROK_ENGINE_BROKER.grokCliArtifacts[options.architecture];
+    if (artifact === undefined)
+        throw new Error("Grok broker projection requires a pinned architecture");
+    const profilePath = path.posix.join(options.workerHomePath, ".grok", "sandbox.toml");
+    const projection = {
+        version: GROK_BROKER_PROJECTION_VERSION, agentId, workspacePath: agent.workspacePath, runtimeHomePath: agent.runtimeHomePath,
+        workerUid: options.workerUid, slot: options.slot, profilePath, profileSha256, denyPaths, workerConfigSha256,
+        systemPromptSha256: GROK_ENGINE_BROKER.worker.systemPromptSha256, grokCliVersion: GROK_ENGINE_BROKER.grokCliVersion, grokExecutableSha256: artifact.sha256,
+        nativeAbiVersion: GROK_ENGINE_BROKER.nativeAbiVersion, model, reasoningEffort, limits: parseEngineBrokerTurnLimits(options.limits), usageLedgerPath: options.usageLedgerPath, seccompProfileSha256: options.seccompProfileSha256,
+        attestation: { platform: "linux/landlock", enforced: true, restrictNetwork: true, profileName: GROK_WORKER_SANDBOX_PROFILE, sandboxRuntime: "bubblewrap", eventsPath: grokWorkerEventsPathFor(profilePath) }
+    };
+    // The registration this projection implies must itself be a valid v2 service.json entry.
+    grokBrokerServiceRegistrationFor(projection);
+    return projection;
+}
+/** sha256 over the projection's canonical JSON; what a slot preflight receipt binds. */
+export const grokBrokerProjectionSha256 = (projection) => createHash("sha256").update(canonicalJson(projection)).digest("hex");
+/** The `service.json` v2 registration a deployment provisions for this projection, validated by the broker's own parser. */
+export function grokBrokerServiceRegistrationFor(projection) {
+    const registration = {
+        agentId: projection.agentId, slot: projection.slot, workerUid: projection.workerUid, workspace: projection.workspacePath,
+        profilePath: projection.profilePath, eventsPath: projection.attestation.eventsPath, profileSha256: projection.profileSha256,
+        usageLedgerPath: projection.usageLedgerPath, limits: projection.limits, model: { id: projection.model, reasoningEffort: projection.reasoningEffort }
+    };
+    parseEngineBrokerServiceConfig({ version: "noopolis.daimon.engine-broker-service.v2", credentialHome: GROK_ENGINE_BROKER.credentialHomePath, turnStore: GROK_ENGINE_BROKER.turnStorePath, registrations: [registration] });
+    return registration;
+}
+/**
+ * Refuses a provisioned registration that does not describe this projection:
+ * any differing member — a weaker profile digest, another model, raised
+ * limits, a different ledger — is a mismatch, never a merge.
+ */
+export function verifyGrokBrokerRegistrationMatchesProjection(registration, projection) {
+    const expected = parseEngineBrokerServiceConfig({ version: "noopolis.daimon.engine-broker-service.v2", credentialHome: GROK_ENGINE_BROKER.credentialHomePath, turnStore: GROK_ENGINE_BROKER.turnStorePath, registrations: [grokBrokerServiceRegistrationFor(projection)] }).registrations[0];
+    if (canonicalJson(expected) !== canonicalJson(registration))
+        throw new Error("Grok broker registration does not match its projection");
+}

package/dist/runtime/grokBrokerProxy.d.ts

@@ -0,0 +1,55 @@
+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";
+/** One running turn as the proxy sees it: its declared model/effort and its spend gate. */
+export type GrokBrokerProxyTurn = Readonly<{
+    policy: GrokBrokerModelPolicy;
+    meter: GrokBrokerTurnMeter;
+}>;
+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): Promise<Readonly<{
+    port: number;
+    capabilities: EngineBrokerCapabilities;
+    registerIsolationGuard(turnId: string, guard: () => Promise<void>): void;
+    revokeIsolationGuard(turnId: string): void;
+    registerTurn(turnId: string, turn: GrokBrokerProxyTurn): void;
+    revokeTurn(turnId: string): void;
+    close(): 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":"AAKA,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,EAAsD,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGxH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,2FAA2F;AAC3F,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,qBAAqB,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;AAE1G,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,CAAC,SAAS,EAAE,6BAA6B,EAAE,QAAQ,GAAE,kBAAoC,EAAE,MAAM,GAAE,qBAAwD,EAAE,UAAU,SAAS,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,wBAAwB,CAAC;IAAC,sBAAsB,CAAC,MAAM,EAAC,MAAM,EAAC,KAAK,EAAC,MAAI,OAAO,CAAC,IAAI,CAAC,GAAE,IAAI,CAAC;IAAC,oBAAoB,CAAC,MAAM,EAAC,MAAM,GAAE,IAAI,CAAC;IAAC,YAAY,CAAC,MAAM,EAAC,MAAM,EAAC,IAAI,EAAC,mBAAmB,GAAE,IAAI,CAAC;IAAC,UAAU,CAAC,MAAM,EAAC,MAAM,GAAE,IAAI,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAAC,CAMtiB;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,262 @@
+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 { parseGrokResponseToolNames, parseGrokUpstreamUsage } from "./grokBrokerTurnMeter.js";
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+import { serveGrokInferenceGrant } from "./grokInferenceProxy.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) {
+    const declared = parseGrokBrokerModelPolicy(policy);
+    const capabilities = new EngineBrokerCapabilities();
+    const guards = new Map();
+    const turns = new Map();
+    const server = createServer((request, response) => { void serve(request, response, authority, upstream, capabilities, guards, turns, declared, grants); });
+    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 { port: address.port, 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 }); }, revokeTurn(turnId) { turns.delete(turnId); }, close: () => new Promise((resolve, reject) => { server.close((error) => error === undefined ? resolve() : reject(error)); /* `close` waits for every open connection, and a worker keeps its client pool's socket to this proxy open with nothing here accounting for it — so that wait has no bound. Ending them is this listener's to do, exactly as the MCP facade does. */ /* `close` waits for every open connection, and a worker keeps its client pool's socket to this proxy open with nothing here accounting for it — so that wait has no bound. Ending them is this listener's to do, exactly as the MCP facade does. */ server.closeAllConnections(); }) };
+}
+/**
+ * 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 {
+        const 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");
+        }
+        // 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) => { turn.meter.settle(admission.index, usage, body.byteLength, toolCalls); 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.
+        settle?.(usageOrEstimate(result.body, result.headers["content-type"]), toolCallsOrNothing(result.body, result.headers["content-type"]));
+        response.writeHead(result.status, { "content-type": result.headers["content-type"] ?? "application/json", "cache-control": "no-store" });
+        response.end(result.body);
+    }
+    catch (error) {
+        settle?.(undefined);
+        // 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;
+    }
+};
+/** 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/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,CAsBhO;AASD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAStD"}

package/dist/runtime/grokBrokerProxyRequest.js

@@ -0,0 +1,74 @@
+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(); 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");
+    // Forward what was validated, never the worker's bytes: JSON.parse keeps the
+    // last of duplicate keys, and an upstream that keeps the first would
+    // otherwise see a different `tools`/`model`/`reasoning_effort` than the 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 { spawn } from "node:child_process";
+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 { spawn } from "node:child_process";
+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);
+    }
+}