@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/grokEngineBrokerTurn.js

@@ -0,0 +1,165 @@
+import { createHash, randomUUID } from "node:crypto";
+import { decodeGrokHeadlessTurn } from "../pi/grokHeadlessResult.js";
+import { decodeGrokStreamUsage } from "../pi/grokStreamUsage.js";
+import { ENGINE_BROKER_VERSION } from "./engineBrokerProtocol.js";
+import { lowerEngineBrokerTurnLimits, mapGrokReportedModel } from "./engineBrokerTurnAccounting.js";
+import { NativeBrokerTurnFailure } from "./engineBrokerNativeClient.js";
+import { engineBrokerRequestLedgerPathFor, engineBrokerSealLedgerPathFor } from "./engineBrokerServiceConfig.js";
+import { ensureBrokerTurnLedgered } from "./grokEngineBrokerLedger.js";
+import { finishBrokerTurnWithUsage } from "./grokEngineBrokerMetering.js";
+import { GrokBrokerTurnMeter } from "./grokBrokerTurnMeter.js";
+import { GrokWorkerAttestationFailure } from "./grokWorkerAttestation.js";
+export class EngineBrokerTurnFailure extends Error {
+    code;
+    diagnostic;
+    accounting;
+    mcpCalls;
+    constructor(code, diagnostic, accounting, mcpCalls) {
+        super("engine broker turn failed");
+        this.code = code;
+        this.diagnostic = diagnostic;
+        this.accounting = accounting;
+        this.mcpCalls = mcpCalls;
+    }
+}
+const limitReasonFor = { tokens: "token_ceiling", requests: "request_ceiling", timeout: "wake_timeout" };
+const usageOf = (usage) => ({ input: usage.input, cacheRead: usage.cacheRead, cacheWrite: usage.cacheWrite, output: usage.output, total: usage.total });
+/**
+ * One brokered Grok turn under its declared limits.
+ *
+ * The limits are the registration's, lowered (never raised) by the wake. The
+ * proxy meter refuses model requests past `maxRequests`, past the elapsed
+ * deadline, or once the upstream-reported running total reached `maxTokens`,
+ * and a tripped limit aborts the worker through the same cancel/kill path a
+ * client cancellation uses. A wall-clock timer trips `timeout` for a worker
+ * that is mid-request.
+ *
+ * Every terminal path — completed, failed, limit, cancelled — is sealed and
+ * metered through {@link finishBrokerTurnWithUsage}; a replayed turn returns its
+ * sealed accounting before any of this runs and never meters again.
+ */
+export async function runGrokEngineBrokerTurn(deps, registration, wakeId, prompt, mcpEndpoint, signal, overrides) {
+    const { agentId } = registration, declared = registration.model.model;
+    let limits;
+    try {
+        limits = lowerEngineBrokerTurnLimits(registration.limits, overrides);
+    }
+    catch {
+        throw new EngineBrokerTurnFailure("invalid_request", undefined, { outcome: "failed", usage: null, model: declared, requests: 0, limitReason: "none" });
+    }
+    const turnId = createHash("sha256").update(`${agentId}\0${wakeId}`).digest("hex");
+    const request = { version: ENGINE_BROKER_VERSION, kind: "start_turn", requestId: randomUUID(), turnId, agentId, wakeId, prompt, mcpEndpoint, ...(overrides === undefined ? {} : { limits: overrides }) };
+    const begun = await deps.turns.begin(request, declared);
+    const metering = { usageLedgerPath: registration.usageLedgerPath, requestLedgerPath: engineBrokerRequestLedgerPathFor(registration.usageLedgerPath), sealLedgerPath: engineBrokerSealLedgerPathFor(registration.usageLedgerPath), agentId, wakeId };
+    if (begun !== "start") {
+        await ensureBrokerTurnLedgered(begun.ledger, turnId, metering);
+        return replay(begun.replay);
+    }
+    const controller = new AbortController();
+    const meter = new GrokBrokerTurnMeter(limits, () => controller.abort());
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted)
+        controller.abort();
+    const timer = setTimeout(() => meter.trip("timeout"), limits.timeoutMs);
+    timer.unref?.();
+    let nativeDiagnostic, attested = false, output, rejected = false, sealed;
+    try {
+        const isolationGuard = await deps.prepareIsolation(registration);
+        deps.proxy.registerIsolationGuard(turnId, isolationGuard);
+        deps.proxy.registerTurn(turnId, { policy: registration.model, meter });
+        const providerCapability = deps.proxy.capabilities.issue(agentId, turnId), mcpCapability = deps.mcp.register(agentId, turnId, mcpEndpoint);
+        const result = await deps.runNative({ slot: registration.slot, requestId: request.requestId, turnId, agentId, wakeId, prompt, providerCapability, mcpCapability }, controller.signal);
+        nativeDiagnostic = result.diagnostic;
+        output = result.text;
+        if (result.workerUid !== registration.workerUid)
+            throw new Error("engine broker worker identity mismatch");
+        await isolationGuard();
+        attested = true;
+        rejected = true;
+        const decoded = decodeGrokHeadlessTurn(result.text), stream = decodeGrokStreamUsage(result.text);
+        if (stream.reportedModels.some((reported) => mapGrokReportedModel(reported, declared) === undefined))
+            throw new Error("engine broker reported an undeclared model");
+        rejected = false;
+        const snapshot = meter.snapshot();
+        if (snapshot.limitReason !== "none")
+            throw new Error("engine broker turn limit reached");
+        const usage = decoded.usage === undefined ? streamOrMeterUsage(stream, snapshot) : usageOf(decoded.usage);
+        const accounting = { outcome: "completed", usage, model: declared, requests: requestCount(stream, snapshot), limitReason: "none" };
+        const completed = { version: request.version, kind: "completed", requestId: request.requestId, turnId, text: decoded.text, workerPid: result.workerPid, workerUid: result.workerUid, workerStartTime: result.startTicks.toString(), ...accounting };
+        const result_ = { text: completed.text, workerPid: completed.workerPid, workerUid: completed.workerUid, workerStartTime: completed.workerStartTime, ...accounting };
+        await finishBrokerTurnWithUsage(deps.turns, request, completed, metering, { notionalUsd: decoded.usage?.notionalUsd ?? 0, complete: decoded.usage?.complete ?? false, estimatedRequests: snapshot.estimatedRequests, requests: requestRows(stream, snapshot), ...(stream.sessionId === undefined ? {} : { session: stream.sessionId }) }, () => { sealed = result_; });
+        return result_;
+    }
+    catch (error) {
+        // Once the completed record is published it is the durable truth: anything
+        // failing after that (metering) must neither re-seal the turn as failed nor
+        // append a second row.
+        if (sealed !== undefined)
+            return sealed;
+        const snapshot = meter.snapshot();
+        const code = snapshot.limitReason !== "none" ? "limit_exceeded" : deps.credentialStale() ? "auth_stale" : controller.signal.aborted ? "cancelled" : "engine_failed";
+        const diagnostic = error instanceof NativeBrokerTurnFailure ? error.diagnostic : nativeDiagnostic && !attested ? { ...nativeDiagnostic, status: "worker_failed", stage: "attestation", failureClass: error instanceof GrokWorkerAttestationFailure ? error.failureClass : "profile_invalid", profileApplied: false } : undefined;
+        const stream = output === undefined ? undefined : decodeGrokStreamUsage(output);
+        const accounting = { outcome: "failed", usage: streamOrMeterUsage(stream, snapshot), model: declared, requests: requestCount(stream, snapshot), limitReason: snapshot.limitReason };
+        // Read before the `finally` revokes this turn's MCP registration, and
+        // swallowed like every other instrument here: it must never be the reason
+        // a turn reports something other than why it failed.
+        let mcpCalls;
+        try {
+            mcpCalls = deps.mcp.observe?.(turnId);
+        }
+        catch {
+            mcpCalls = undefined;
+        }
+        const failed = { version: request.version, kind: "failed", requestId: request.requestId, turnId, code, ...(diagnostic ? { diagnostic } : {}), ...(mcpCalls === undefined ? {} : { mcpCalls }), ...accounting };
+        const reason = snapshot.limitReason !== "none" ? limitReasonFor[snapshot.limitReason] : rejected ? "turn_rejected" : "unknown";
+        await finishBrokerTurnWithUsage(deps.turns, request, failed, metering, { notionalUsd: 0, complete: false, reason, estimatedRequests: snapshot.estimatedRequests, requests: requestRows(stream, snapshot), ...(stream?.sessionId === undefined ? {} : { session: stream.sessionId }) });
+        throw new EngineBrokerTurnFailure(code, diagnostic, accounting, mcpCalls);
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        meter.abortInFlight();
+        deps.proxy.revokeTurn(turnId);
+        deps.proxy.revokeIsolationGuard(turnId);
+        deps.proxy.capabilities.revoke(turnId);
+        deps.mcp.revoke(turnId);
+    }
+}
+function replay(response) {
+    const accounting = { outcome: response.outcome, usage: response.usage, model: response.model, requests: response.requests, limitReason: response.limitReason };
+    if (response.kind === "completed")
+        return { text: response.text, workerPid: response.workerPid, workerUid: response.workerUid, workerStartTime: response.workerStartTime, ...accounting, outcome: "completed" };
+    const code = response.code === "turn_conflict" || response.code === "unavailable" ? "engine_failed" : response.code;
+    throw new EngineBrokerTurnFailure(code, response.diagnostic, accounting, response.mcpCalls);
+}
+/** The proxy saw every forwarded request; the stream is the fallback when no request crossed this proxy. */
+const requestCount = (stream, snapshot) => snapshot.requests > 0 ? snapshot.requests : stream?.requests.length ?? 0;
+/** Best partial usage: the worker's own per-request frames when any arrived, else what upstream reported to the proxy. */
+function streamOrMeterUsage(stream, snapshot) {
+    if (stream !== undefined && stream.requests.length > 0) {
+        const sum = (pick) => stream.requests.reduce((total, value) => total + pick(value), 0);
+        return { input: sum((value) => value.input), cacheRead: sum((value) => value.cacheRead), cacheWrite: sum((value) => value.cacheWrite), output: sum((value) => value.output), total: sum((value) => value.total) };
+    }
+    return snapshot.usage;
+}
+/** Per-request rows: stream usage with the proxy's own observation when both describe the same requests, else the proxy's measured requests. */
+function requestRows(stream, snapshot) {
+    if (stream !== undefined && stream.requests.length > 0) {
+        const timed = snapshot.timings.length === stream.requests.length;
+        return stream.requests.map((value, index) => ({ ...value, usageSource: "stream", ...(timed ? observed(snapshot.timings[index]) : {}) }));
+    }
+    return snapshot.timings.flatMap((timing, index) => timing.usage === undefined ? [] : [{ index, ...usageOf(timing.usage), usageSource: timing.estimated === true ? "estimated" : "upstream", ...observed(timing) }]);
+}
+/**
+ * What only the proxy saw of one request: its clock, and the tool-call names the
+ * response carried. Both are attached on the stream path only when the two
+ * descriptions are request-for-request aligned, because an unaligned index would
+ * credit one request's attempt to another.
+ */
+const observed = (timing) => ({
+    startedAt: timing.startedAt,
+    ...(timing.endedAt === undefined ? {} : { endedAt: timing.endedAt }),
+    ...(timing.toolCalls === undefined ? {} : { toolCalls: timing.toolCalls })
+});

package/dist/runtime/grokInferenceClientConfig.d.ts

@@ -0,0 +1,41 @@
+import { type GrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+/** The evaluator CLI's only model id: Paideia passes `--model daimon-inference-grok`, never a catalog id. */
+export declare const GROK_INFERENCE_CLIENT_MODEL_ID: "daimon-inference-grok";
+/** The environment variable the evaluator CLI reads its grant token from. */
+export declare const GROK_INFERENCE_GRANT_ENV: "DAIMON_INFERENCE_GRANT";
+export type GrokInferenceClientConfigInput = Readonly<{
+    baseUrl: string;
+    model: GrokBrokerModelPolicy["model"];
+    reasoningEffort: GrokBrokerModelPolicy["reasoningEffort"];
+    envKey: string;
+}>;
+/**
+ * `config.toml` bytes for an evaluator Grok CLI (Paideia judge or optimizer,
+ * uid 2000) that reaches the broker proxy through an inference grant.
+ *
+ * Paideia writes it into a private `GROK_HOME` (`0700`, uid 2000) and sets the
+ * grant token in `envKey`; the CLI never holds the broker credential. Grok
+ * 1.0.34 ignores `[auth_provider.*]` helpers for a custom model, so the token
+ * travels through `env_key` exactly as the worker's turn capability does.
+ *
+ * It mirrors the worker renderer's lean settings: every bundled skill
+ * disabled, workflows off, the per-call `session_title` request pointed at a
+ * hidden model with a placeholder key the proxy refuses before any credential
+ * read or upstream call, and the declared effort as the model's single
+ * effort. There is no MCP server. `max_retries = 0`: with the default, a
+ * refused request (HTTP 503) is retried with backoff past a 45 s bound
+ * (live stub capture), so a gate refusal would hang the judge until its own
+ * timeout; with it the CLI fails in ~0.35 s and the caller's routed retry
+ * policy decides. HTTP 401 is never retried either way. `baseUrl` is the `baseUrl` of the grant (the
+ * loopback provider proxy); the manifest pins the sha256 for the production
+ * proxy URL and {@link GROK_INFERENCE_GRANT_ENV}.
+ *
+ * Paideia must also accept the init frame this produces: `apiKeySource` is
+ * `"user"` (not `"oauth"`), with `tools: []` and `mcp_servers: []` (live
+ * stub capture with the Paideia judge argv).
+ */
+export declare function renderGrokInferenceClientConfig(input: GrokInferenceClientConfigInput): string;
+export declare const grokInferenceClientConfigSha256: (input: GrokInferenceClientConfigInput) => string;
+/** The production bytes for a declared model/effort: the grant's proxy URL and the canonical env key. */
+export declare const renderProductionGrokInferenceClientConfig: (policy: GrokBrokerModelPolicy) => string;
+//# sourceMappingURL=grokInferenceClientConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokInferenceClientConfig.d.ts","sourceRoot":"","sources":["../../src/runtime/grokInferenceClientConfig.ts"],"names":[],"mappings":"AAIA,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAIpG,6GAA6G;AAC7G,eAAO,MAAM,8BAA8B,yBAAe,CAAC;AAC3D,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,0BAAc,CAAC;AAEpD,MAAM,MAAM,8BAA8B,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAAC,eAAe,EAAE,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7L;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,8BAA8B,GAAG,MAAM,CAe7F;AAED,eAAO,MAAM,+BAA+B,GAAI,OAAO,8BAA8B,KAAG,MACL,CAAC;AAEpF,yGAAyG;AACzG,eAAO,MAAM,yCAAyC,GAAI,QAAQ,qBAAqB,KAAG,MACmF,CAAC"}

package/dist/runtime/grokInferenceClientConfig.js

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+import { GROK_INFERENCE_PROXY_BASE_URL } from "./engineBrokerInferenceProtocol.js";
+import { parseGrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+import { GROK_SESSION_TITLE_SINK_KEY, GROK_SESSION_TITLE_SINK_MODEL_ID, renderGrokLeanBaseConfig } from "./grokBrokerWorkerConfig.js";
+const SPEC = GROK_ENGINE_BROKER.inferenceGrants.client;
+/** The evaluator CLI's only model id: Paideia passes `--model daimon-inference-grok`, never a catalog id. */
+export const GROK_INFERENCE_CLIENT_MODEL_ID = SPEC.modelId;
+/** The environment variable the evaluator CLI reads its grant token from. */
+export const GROK_INFERENCE_GRANT_ENV = SPEC.envKey;
+/**
+ * `config.toml` bytes for an evaluator Grok CLI (Paideia judge or optimizer,
+ * uid 2000) that reaches the broker proxy through an inference grant.
+ *
+ * Paideia writes it into a private `GROK_HOME` (`0700`, uid 2000) and sets the
+ * grant token in `envKey`; the CLI never holds the broker credential. Grok
+ * 1.0.34 ignores `[auth_provider.*]` helpers for a custom model, so the token
+ * travels through `env_key` exactly as the worker's turn capability does.
+ *
+ * It mirrors the worker renderer's lean settings: every bundled skill
+ * disabled, workflows off, the per-call `session_title` request pointed at a
+ * hidden model with a placeholder key the proxy refuses before any credential
+ * read or upstream call, and the declared effort as the model's single
+ * effort. There is no MCP server. `max_retries = 0`: with the default, a
+ * refused request (HTTP 503) is retried with backoff past a 45 s bound
+ * (live stub capture), so a gate refusal would hang the judge until its own
+ * timeout; with it the CLI fails in ~0.35 s and the caller's routed retry
+ * policy decides. HTTP 401 is never retried either way. `baseUrl` is the `baseUrl` of the grant (the
+ * loopback provider proxy); the manifest pins the sha256 for the production
+ * proxy URL and {@link GROK_INFERENCE_GRANT_ENV}.
+ *
+ * Paideia must also accept the init frame this produces: `apiKeySource` is
+ * `"user"` (not `"oauth"`), with `tools: []` and `mcp_servers: []` (live
+ * stub capture with the Paideia judge argv).
+ */
+export function renderGrokInferenceClientConfig(input) {
+    let declared;
+    try {
+        declared = parseGrokBrokerModelPolicy({ model: input.model, reasoningEffort: input.reasoningEffort });
+    }
+    catch {
+        throw new TypeError("invalid Grok inference client configuration");
+    }
+    if (declared.model !== input.model || declared.reasoningEffort !== input.reasoningEffort)
+        throw new TypeError("invalid Grok inference client configuration");
+    if (typeof input.baseUrl !== "string" || !/^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})\/v1$/u.test(input.baseUrl) || Number(input.baseUrl.slice(17, -3)) > 65_535)
+        throw new TypeError("invalid Grok inference client configuration");
+    if (typeof input.envKey !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/u.test(input.envKey))
+        throw new TypeError("invalid Grok inference client configuration");
+    const label = `${declared.reasoningEffort[0].toUpperCase()}${declared.reasoningEffort.slice(1)}`;
+    return [
+        renderGrokLeanBaseConfig(),
+        "[models]", `default = "${GROK_INFERENCE_CLIENT_MODEL_ID}"`, `default_reasoning_effort = "${declared.reasoningEffort}"`, `session_summary = "${GROK_SESSION_TITLE_SINK_MODEL_ID}"`, "",
+        `[model.${GROK_SESSION_TITLE_SINK_MODEL_ID}]`, 'model = "disabled"', `base_url = "${input.baseUrl}"`, `api_key = "${GROK_SESSION_TITLE_SINK_KEY}"`, "max_retries = 0", "hidden = true", "",
+        `[model.${GROK_INFERENCE_CLIENT_MODEL_ID}]`, `model = "${declared.model}"`, `base_url = "${input.baseUrl}"`, `env_key = "${input.envKey}"`,
+        'api_backend = "chat_completions"', "context_window = 131072", "supports_backend_search = false", "max_retries = 0", "",
+        `[[model.${GROK_INFERENCE_CLIENT_MODEL_ID}.reasoning_efforts]]`, `value = "${declared.reasoningEffort}"`, `label = "${label}"`, "default = true", ""
+    ].join("\n");
+}
+export const grokInferenceClientConfigSha256 = (input) => createHash("sha256").update(renderGrokInferenceClientConfig(input)).digest("hex");
+/** The production bytes for a declared model/effort: the grant's proxy URL and the canonical env key. */
+export const renderProductionGrokInferenceClientConfig = (policy) => renderGrokInferenceClientConfig({ baseUrl: GROK_INFERENCE_PROXY_BASE_URL, model: policy.model, reasoningEffort: policy.reasoningEffort, envKey: GROK_INFERENCE_GRANT_ENV });

package/dist/runtime/grokInferenceGrants.d.ts

@@ -0,0 +1,77 @@
+import type { EngineBrokerInferenceFailureCode } from "./engineBrokerInferenceProtocol.js";
+import type { EngineBrokerTurnLimits, EngineBrokerTurnUsage } from "./engineBrokerTurnAccounting.js";
+import { type GrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+import { GrokBrokerTurnMeter } from "./grokBrokerTurnMeter.js";
+import { type GrokInferencePurpose, type InferenceUsageEntry } from "./inferenceUsageLedger.js";
+/** One live evaluator grant as the proxy sees it. */
+export type GrokInferenceGrant = Readonly<{
+    grantId: string;
+    purpose: GrokInferencePurpose;
+    policy: GrokBrokerModelPolicy;
+    expiresAt: number;
+    meter: GrokBrokerTurnMeter;
+}>;
+export type GrokInferenceGrantIssued = Readonly<{
+    grantId: string;
+    token: string;
+    purpose: GrokInferencePurpose;
+    policy: GrokBrokerModelPolicy;
+    expiresAt: number;
+    limits: EngineBrokerTurnLimits;
+}>;
+export type GrokInferenceGrantRequest = Readonly<{
+    model: unknown;
+    reasoningEffort: unknown;
+    purpose: unknown;
+}>;
+export declare class GrokInferenceGrantRefused extends Error {
+    readonly code: EngineBrokerInferenceFailureCode;
+    constructor(code: EngineBrokerInferenceFailureCode);
+}
+export type GrokInferenceGrantsOptions = Readonly<{
+    now?: () => number;
+    /** Test seam: a fixed grant id proves grants never share a key space with turn capabilities. */
+    grantId?: () => string;
+    onSettled?: (entry: InferenceUsageEntry) => void;
+    ttlMs?: number;
+    maxLiveGrants?: number;
+}>;
+/**
+ * Evaluator inference grants: a distinct kind beside subject turn capabilities.
+ *
+ * Grants live in their own map keyed by a random grant id; turn capabilities
+ * (`engineBrokerCapabilities.ts`) are keyed by turn id and never consulted
+ * here, and grant tokens carry `inference_` so the proxy routes a bearer to
+ * exactly one of the two lookups. A grant has no worker isolation guard (it is
+ * issued only to the organization uid, the trusted evaluator side), but it
+ * carries the same spend gate as a subject turn: a {@link GrokBrokerTurnMeter}
+ * with one request in flight, the request ceiling, the between-requests token
+ * ceiling and the estimate for a response without usage. Its lifetime is the
+ * meter's time limit: past `expiresAt` it is gone from the map, and a request
+ * still in flight at expiry is aborted.
+ *
+ * At most `maxLiveGrants` grants exist at once; a caller frees a slot early
+ * with {@link release}. Nothing here is durable — a broker restart drops every
+ * grant, and callers request a new one.
+ */
+export declare class GrokInferenceGrants {
+    private readonly options;
+    private readonly grants;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxLive;
+    constructor(options?: GrokInferenceGrantsOptions);
+    issue(request: GrokInferenceGrantRequest): GrokInferenceGrantIssued;
+    /** The live, unexpired grant a bearer names, or `undefined`. Never counts a request. */
+    authorize(token: string): GrokInferenceGrant | undefined;
+    /** Records one admitted request's end on the grant's meter and emits its ledger row. */
+    settle(grant: GrokInferenceGrant, index: number, usage: EngineBrokerTurnUsage | undefined, requestBytes: number): void;
+    /** Revokes a grant and aborts its in-flight request. Returns whether it was live. */
+    release(grantId: string): boolean;
+    live(): number;
+    close(): void;
+    private prune;
+}
+/** The broker's grants: every settled request is appended to the evaluator inference ledger and nowhere else. */
+export declare const createLedgeredGrokInferenceGrants: (inferenceLedgerPath: string) => GrokInferenceGrants;
+//# sourceMappingURL=grokInferenceGrants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokInferenceGrants.d.ts","sourceRoot":"","sources":["../../src/runtime/grokInferenceGrants.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AAC3F,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACrG,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAiD,KAAK,oBAAoB,EAAE,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAI/I,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;AAC5K,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,CAAC,CAAC;AACrM,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEjH,qBAAa,yBAA0B,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,gCAAgC;gBAAtC,IAAI,EAAE,gCAAgC;CAC5D;AAGD,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,mBAAmB;IAKlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBACJ,OAAO,GAAE,0BAA+B;IAOrE,KAAK,CAAC,OAAO,EAAE,yBAAyB,GAAG,wBAAwB;IAiBnE,wFAAwF;IACxF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAQxD,wFAAwF;IACxF,MAAM,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAStH,qFAAqF;IACrF,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAOjC,IAAI,IAAI,MAAM;IAEd,KAAK,IAAI,IAAI;IAEb,OAAO,CAAC,KAAK;CAId;AAED,iHAAiH;AACjH,eAAO,MAAM,iCAAiC,GAAI,qBAAqB,MAAM,KAAG,mBAC+B,CAAC"}

package/dist/runtime/grokInferenceGrants.js

@@ -0,0 +1,116 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+import { parseGrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+import { GrokBrokerTurnMeter } from "./grokBrokerTurnMeter.js";
+import { GROK_INFERENCE_PURPOSES, recordInferenceUsage } from "./inferenceUsageLedger.js";
+const SPEC = GROK_ENGINE_BROKER.inferenceGrants;
+export class GrokInferenceGrantRefused extends Error {
+    code;
+    constructor(code) {
+        super(`inference grant refused (${code})`);
+        this.code = code;
+    }
+}
+/**
+ * Evaluator inference grants: a distinct kind beside subject turn capabilities.
+ *
+ * Grants live in their own map keyed by a random grant id; turn capabilities
+ * (`engineBrokerCapabilities.ts`) are keyed by turn id and never consulted
+ * here, and grant tokens carry `inference_` so the proxy routes a bearer to
+ * exactly one of the two lookups. A grant has no worker isolation guard (it is
+ * issued only to the organization uid, the trusted evaluator side), but it
+ * carries the same spend gate as a subject turn: a {@link GrokBrokerTurnMeter}
+ * with one request in flight, the request ceiling, the between-requests token
+ * ceiling and the estimate for a response without usage. Its lifetime is the
+ * meter's time limit: past `expiresAt` it is gone from the map, and a request
+ * still in flight at expiry is aborted.
+ *
+ * At most `maxLiveGrants` grants exist at once; a caller frees a slot early
+ * with {@link release}. Nothing here is durable — a broker restart drops every
+ * grant, and callers request a new one.
+ */
+export class GrokInferenceGrants {
+    options;
+    grants = new Map();
+    now;
+    ttlMs;
+    maxLive;
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.ttlMs = options.ttlMs ?? SPEC.ttlMs;
+        this.maxLive = options.maxLiveGrants ?? SPEC.maxLiveGrants;
+        if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs < 1 || this.ttlMs > SPEC.ttlMs || !Number.isSafeInteger(this.maxLive) || this.maxLive < 1 || this.maxLive > SPEC.maxLiveGrants)
+            throw new TypeError("invalid inference grant policy");
+    }
+    issue(request) {
+        let policy;
+        try {
+            policy = parseGrokBrokerModelPolicy({ model: request.model, reasoningEffort: request.reasoningEffort });
+        }
+        catch {
+            throw new GrokInferenceGrantRefused("invalid_request");
+        }
+        // Nothing is defaulted: the model parser fills an absent member, a grant must name both.
+        if (request.model !== policy.model || request.reasoningEffort !== policy.reasoningEffort || !GROK_INFERENCE_PURPOSES.includes(request.purpose))
+            throw new GrokInferenceGrantRefused("invalid_request");
+        this.prune();
+        if (this.grants.size >= this.maxLive)
+            throw new GrokInferenceGrantRefused("grant_limit");
+        const grantId = this.options.grantId?.() ?? randomBytes(16).toString("hex");
+        if (!/^[a-f0-9]{32}$/u.test(grantId) || this.grants.has(grantId))
+            throw new GrokInferenceGrantRefused("grant_limit");
+        const limits = Object.freeze({ maxRequests: SPEC.limits.maxRequests, maxTokens: SPEC.limits.maxTokens, timeoutMs: this.ttlMs });
+        const token = `${SPEC.tokenPrefix}${randomBytes(32).toString("base64url")}`;
+        const grant = Object.freeze({ grantId, purpose: request.purpose, policy, expiresAt: this.now() + this.ttlMs, meter: new GrokBrokerTurnMeter(limits, () => undefined, this.now) });
+        const timer = setTimeout(() => this.release(grantId), this.ttlMs);
+        timer.unref?.();
+        this.grants.set(grantId, { grant, digest: digest(token), timer });
+        return Object.freeze({ grantId, token, purpose: grant.purpose, policy, expiresAt: grant.expiresAt, limits });
+    }
+    /** The live, unexpired grant a bearer names, or `undefined`. Never counts a request. */
+    authorize(token) {
+        if (!token.startsWith(SPEC.tokenPrefix))
+            return undefined;
+        this.prune();
+        const candidate = digest(token);
+        for (const entry of this.grants.values())
+            if (timingSafeEqual(entry.digest, candidate))
+                return entry.grant;
+        return undefined;
+    }
+    /** Records one admitted request's end on the grant's meter and emits its ledger row. */
+    settle(grant, index, usage, requestBytes) {
+        const before = grant.meter.snapshot().timings[index];
+        if (before === undefined || before.endedAt !== undefined)
+            return;
+        grant.meter.settle(index, usage, requestBytes);
+        const timing = grant.meter.snapshot().timings[index];
+        if (timing?.usage === undefined || timing.endedAt === undefined)
+            return;
+        this.options.onSettled?.({ grant: grant.grantId, purpose: grant.purpose, model: grant.policy.model, request: index, usage: timing.usage, usageSource: timing.estimated === true ? "estimated" : "upstream", startedAt: timing.startedAt, endedAt: timing.endedAt });
+    }
+    /** Revokes a grant and aborts its in-flight request. Returns whether it was live. */
+    release(grantId) {
+        const entry = this.grants.get(grantId);
+        if (entry === undefined)
+            return false;
+        clearTimeout(entry.timer);
+        entry.grant.meter.trip("timeout");
+        entry.digest.fill(0);
+        this.grants.delete(grantId);
+        return true;
+    }
+    live() { this.prune(); return this.grants.size; }
+    close() { for (const grantId of [...this.grants.keys()])
+        this.release(grantId); }
+    prune() {
+        const now = this.now();
+        for (const [grantId, entry] of this.grants)
+            if (entry.grant.expiresAt <= now)
+                this.release(grantId);
+    }
+}
+/** The broker's grants: every settled request is appended to the evaluator inference ledger and nowhere else. */
+export const createLedgeredGrokInferenceGrants = (inferenceLedgerPath) => new GrokInferenceGrants({ onSettled: (entry) => { void recordInferenceUsage(inferenceLedgerPath, entry); } });
+const digest = (value) => createHash("sha256").update(value).digest();

package/dist/runtime/grokInferenceProxy.d.ts

@@ -0,0 +1,29 @@
+import type { ServerResponse } from "node:http";
+import type { GrokBrokerCredentialAuthority, GrokBrokerUpstream } from "./grokBrokerProxy.js";
+import type { GrokInferenceGrants } from "./grokInferenceGrants.js";
+export type GrokInferenceProxyInput = Readonly<{
+    method: string;
+    pathname: string;
+    headers: Readonly<Record<string, string | undefined>>;
+    body: Buffer;
+    token: string;
+}>;
+/** HTTP 401 with a fixed code: the broker realm is stale, distinct from a generic 503 broker failure. */
+export declare const GROK_INFERENCE_AUTH_STALE_BODY = "{\"error\":\"auth_stale\"}";
+/**
+ * Serves one evaluator grant request; never throws.
+ *
+ * Order mirrors the subject path: the body is proven a grant-shaped request
+ * (declared model/effort, no tools) before the credential is read, the grant
+ * meter admits it before any upstream call, and exactly one ledger row is
+ * written once an admitted request settles. No worker isolation guard applies:
+ * grants are issued only to the organization uid.
+ *
+ * Stale realm: the grant shares the subject's credential authority, so a
+ * stale realm fails judges and subject turns alike (accepted shared fate). A
+ * grant request that finds the realm stale — before the upstream call or
+ * after a rejected refresh — is answered 401 `{"error":"auth_stale"}`, never
+ * the generic 503, so the evaluator can report it as a credential failure.
+ */
+export declare function serveGrokInferenceGrant(input: GrokInferenceProxyInput, response: ServerResponse, grants: GrokInferenceGrants, authority: GrokBrokerCredentialAuthority, upstream: GrokBrokerUpstream): Promise<void>;
+//# sourceMappingURL=grokInferenceProxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokInferenceProxy.d.ts","sourceRoot":"","sources":["../../src/runtime/grokInferenceProxy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EAAE,6BAA6B,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,MAAM,MAAM,uBAAuB,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,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEzK,yGAAyG;AACzG,eAAO,MAAM,8BAA8B,+BAA2B,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,uBAAuB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,mBAAmB,EAAE,SAAS,EAAE,6BAA6B,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiC1N"}

package/dist/runtime/grokInferenceProxy.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { GrokBrokerProxyRefusal } from "./grokBrokerProxy.js";
+import { parseGrokUpstreamUsage } from "./grokBrokerTurnMeter.js";
+import { authorizeGrokInferenceProxyRequest } from "./grokInferenceProxyRequest.js";
+/** HTTP 401 with a fixed code: the broker realm is stale, distinct from a generic 503 broker failure. */
+export const GROK_INFERENCE_AUTH_STALE_BODY = '{"error":"auth_stale"}';
+/**
+ * Serves one evaluator grant request; never throws.
+ *
+ * Order mirrors the subject path: the body is proven a grant-shaped request
+ * (declared model/effort, no tools) before the credential is read, the grant
+ * meter admits it before any upstream call, and exactly one ledger row is
+ * written once an admitted request settles. No worker isolation guard applies:
+ * grants are issued only to the organization uid.
+ *
+ * Stale realm: the grant shares the subject's credential authority, so a
+ * stale realm fails judges and subject turns alike (accepted shared fate). A
+ * grant request that finds the realm stale — before the upstream call or
+ * after a rejected refresh — is answered 401 `{"error":"auth_stale"}`, never
+ * the generic 503, so the evaluator can report it as a credential failure.
+ */
+export async function serveGrokInferenceGrant(input, response, grants, authority, upstream) {
+    let settle;
+    try {
+        const grant = grants.authorize(input.token);
+        if (grant === undefined)
+            throw new GrokBrokerProxyRefusal("unknown_or_expired_grant");
+        let prepared;
+        try {
+            prepared = authorizeGrokInferenceProxyRequest(input, "pending", grant.policy);
+        }
+        catch {
+            throw new GrokBrokerProxyRefusal("request_body_rejected");
+        }
+        let token = await authority.accessToken(false);
+        const rejectedDigest = createHash("sha256").update(token).digest("hex");
+        prepared = withBearer(prepared, token);
+        token = "";
+        const admission = grant.meter.admit();
+        if ("refused" in admission)
+            return json(response, 429, JSON.stringify({ error: "grant limit reached", limit: admission.refused }));
+        if ("busy" in admission)
+            return json(response, 429, '{"error":"grant request in flight"}');
+        settle = (usage) => { settle = undefined; grants.settle(grant, admission.index, usage, input.body.byteLength); };
+        let result = await upstream(prepared, admission.signal);
+        if (result.status === 401) {
+            token = authority.refreshAfterRejection ? await authority.refreshAfterRejection(rejectedDigest) : await authority.accessToken(true);
+            const refreshedDigest = createHash("sha256").update(token).digest("hex");
+            prepared = withBearer(prepared, token);
+            token = "";
+            result = await upstream(prepared, admission.signal);
+            if (result.status === 401)
+                await authority.markRejected(refreshedDigest);
+        }
+        settle?.(parseGrokUpstreamUsage(result.body, result.headers["content-type"]));
+        json(response, result.status, result.body, result.headers["content-type"]);
+    }
+    catch (error) {
+        settle?.(undefined);
+        // Same rule as the subject path: a policy miss is non-retryable (400), because a
+        // retryable 503 makes the client re-send a request the broker will never accept,
+        // charging estimated usage for every attempt. 503 stays for transient faults only.
+        process.stderr.write(`[grok-proxy] inference refused: ${error instanceof GrokBrokerProxyRefusal ? error.reason : "broker_unavailable"}\n`);
+        if (authority.isStale?.() === true)
+            json(response, 401, GROK_INFERENCE_AUTH_STALE_BODY);
+        else if (error instanceof GrokBrokerProxyRefusal)
+            json(response, 400, JSON.stringify({ error: "broker refused this request", reason: error.reason }));
+        else
+            json(response, 503, '{"error":"broker unavailable"}');
+    }
+}
+const withBearer = (prepared, token) => {
+    if (!token || /[\r\n]/u.test(token))
+        throw new Error("broker credential authority unavailable");
+    return { ...prepared, headers: { ...prepared.headers, authorization: `Bearer ${token}` } };
+};
+function json(response, status, body, contentType = "application/json") {
+    if (response.headersSent)
+        return;
+    response.writeHead(status, { "content-type": contentType, "cache-control": "no-store" });
+    response.end(body);
+}

package/dist/runtime/grokInferenceProxyRequest.d.ts

@@ -0,0 +1,23 @@
+import type { GrokBrokerProxyInput, GrokBrokerUpstreamRequest } from "./grokBrokerProxyRequest.js";
+import { type GrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+/**
+ * Authorizes one evaluator grant request body and rebuilds it for the provider.
+ *
+ * The accepted shape is exactly what Grok CLI 1.0.34 sends for a Paideia
+ * judge/optimizer call (`--tools read_file --disallowed-tools
+ * read_file,search_tool,use_tool --max-turns 1`, with and without
+ * `--system-prompt-override` and `--json-schema`; live stub capture):
+ *
+ * - `stream: true` with `stream_options: {include_usage: true}` — the CLI never
+ *   sends a non-streaming request, so none is accepted;
+ * - `model` and `reasoning_effort` equal to the grant's declaration;
+ * - `messages` of plain `{role, content}` string turns, roles system/user/assistant;
+ * - optional `response_format` `{type: "json_schema", json_schema: {name, schema, strict}}`;
+ * - no `tools` and no `tool_choice` member at all, not even an empty one. The
+ *   CLI's per-call `session_title` request carries both and is refused here.
+ *
+ * The client version must be the pinned CLI, and the forwarded body is the
+ * re-serialized parse, never the caller's bytes.
+ */
+export declare function authorizeGrokInferenceProxyRequest(input: Omit<GrokBrokerProxyInput, "agentId" | "turnId">, bearer: string, policy: GrokBrokerModelPolicy): GrokBrokerUpstreamRequest;
+//# sourceMappingURL=grokInferenceProxyRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokInferenceProxyRequest.d.ts","sourceRoot":"","sources":["../../src/runtime/grokInferenceProxyRequest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACnG,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAUpG;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,yBAAyB,CAcpL"}