@noopolis/daimon 0.1.2 → 0.2.1

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":"AAEA,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,CAkC1N"}

package/dist/runtime/grokInferenceProxy.js

@@ -0,0 +1,85 @@
+import { GrokBrokerRunLimit } from "./grokBrokerRunBudget.js";
+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);
+        if (error instanceof GrokBrokerRunLimit)
+            return json(response, 429, '{"error":"run_request_limit"}');
+        // 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"}

package/dist/runtime/grokInferenceProxyRequest.js

@@ -0,0 +1,63 @@
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+import { parseGrokBrokerModelPolicy } from "./grokBrokerModelPolicy.js";
+const MAX_BODY = 2 * 1024 * 1024;
+const SPEC = GROK_ENGINE_BROKER.inferenceGrants;
+const BODY_MEMBERS = new Set(SPEC.bodyMembers);
+const ROLES = new Set(SPEC.messageRoles);
+const plain = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const rejected = () => new Error("inference grant request rejected");
+/**
+ * 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 function authorizeGrokInferenceProxyRequest(input, bearer, policy) {
+    const declared = parseGrokBrokerModelPolicy(policy);
+    if (input.method !== "POST" || input.pathname !== "/v1/chat/completions" || input.body.byteLength < 2 || input.body.byteLength > MAX_BODY)
+        throw 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 rejected();
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(input.body).toString("utf8"), (key, value) => { if (key === "__proto__")
+            throw new Error(); return value; });
+    }
+    catch {
+        throw rejected();
+    }
+    if (!plain(parsed) || Object.keys(parsed).some((key) => !BODY_MEMBERS.has(key)))
+        throw rejected();
+    if (parsed.model !== declared.model || parsed.reasoning_effort !== declared.reasoningEffort || parsed.stream !== true)
+        throw rejected();
+    if (!plain(parsed.stream_options) || Object.keys(parsed.stream_options).length !== 1 || parsed.stream_options.include_usage !== true)
+        throw rejected();
+    if (!Array.isArray(parsed.messages) || parsed.messages.length === 0 || !parsed.messages.every(plainMessage))
+        throw rejected();
+    if (parsed.response_format !== undefined && !jsonSchemaFormat(parsed.response_format))
+        throw rejected();
+    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)) };
+}
+const plainMessage = (message) => plain(message) && Object.keys(message).length === 2 && ROLES.has(message.role) && typeof message.content === "string";
+const jsonSchemaFormat = (value) => {
+    if (!plain(value) || Object.keys(value).length !== 2 || value.type !== "json_schema" || !plain(value.json_schema))
+        return false;
+    const schema = value.json_schema;
+    return Object.keys(schema).every((key) => key === "name" || key === "schema" || key === "strict") && typeof schema.name === "string" && plain(schema.schema) && (schema.strict === undefined || typeof schema.strict === "boolean");
+};

package/dist/runtime/grokSlotPreflightReceipt.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { type OrganizationGrokBrokerProjection } from "./grokBrokerProjection.js";
+export declare const GROK_SLOT_PREFLIGHT_VERSION: "noopolis.daimon.grok-slot-preflight.v2";
+/**
+ * One denied-path canary: the root supervisor ran a real sandboxed read of
+ * `path` as the slot's worker uid (a stub-model turn under the attested
+ * profile) and the read was denied. Only denials are representable — a
+ * supervisor that observed a readable path writes no receipt at all.
+ */
+export declare const grokSlotPreflightCanarySchema: z.ZodObject<{
+    path: z.ZodString;
+    method: z.ZodLiteral<"sandboxed-read">;
+    result: z.ZodLiteral<"denied">;
+}, z.core.$strict>;
+/**
+ * `noopolis.daimon.grok-slot-preflight.v2`: what the root slot supervisor (P5)
+ * writes after provisioning or recycling one broker slot, and what an
+ * evaluator (Paideia, P4) must hold before it runs a Grok subject turn in that
+ * slot. It binds the slot to one exact projection by digest, so any change to
+ * the model, limits, deny list, profile, worker config, or pinned executable
+ * invalidates it.
+ *
+ * The projection digest is identical across recycles of the same slot, so v1
+ * could not tell this recycle's receipt from an earlier one. v2 adds
+ * freshness: `generation` is the supervisor-owned per-slot counter, strictly
+ * increasing on every provision/recycle, and `nonce` echoes the 32 random
+ * bytes (hex) the evaluator passed in its recycle request. A v1 receipt is
+ * refused.
+ */
+export declare const grokSlotPreflightReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<"noopolis.daimon.grok-slot-preflight.v2">;
+    slot: z.ZodNumber;
+    worker_uid: z.ZodNumber;
+    generation: z.ZodNumber;
+    nonce: z.ZodString;
+    projection_sha256: z.ZodString;
+    sandbox_profile_sha256: z.ZodString;
+    seccomp_profile_sha256: z.ZodString;
+    sandbox_runtime: z.ZodLiteral<"bubblewrap">;
+    grok_executable_sha256: z.ZodString;
+    canaries: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        method: z.ZodLiteral<"sandboxed-read">;
+        result: z.ZodLiteral<"denied">;
+    }, z.core.$strict>>;
+    created_at: z.ZodString;
+}, z.core.$strict>;
+export type GrokSlotPreflightReceipt = z.infer<typeof grokSlotPreflightReceiptSchema>;
+/** Strict parse: unknown members, off-contract values, or duplicate canaries throw. */
+export declare function parseGrokSlotPreflightReceipt(value: unknown): GrokSlotPreflightReceipt;
+/**
+ * What the evaluator knows about *this* recycle: the nonce it sent, and the
+ * lowest generation it will accept — one above the last generation it
+ * accepted for the slot (1 for a slot it has never seen).
+ */
+export type GrokSlotPreflightFreshness = Readonly<{
+    expectedNonce: string;
+    minGeneration: number;
+}>;
+/**
+ * Parse a receipt and require that it proves *this* projection's slot: same
+ * digest, slot, worker uid, profile and executable, and a denied canary for
+ * exactly every projected deny path (no more, no fewer), under the projected
+ * seccomp profile and sandbox runtime — and that it is *this* recycle's
+ * receipt: the caller's nonce, at or above the caller's minimum generation.
+ * A receipt replayed from an earlier recycle fails on the nonce, and one
+ * whose generation went backwards fails on the generation.
+ */
+export declare function verifyGrokSlotPreflightReceipt(value: unknown, projection: OrganizationGrokBrokerProjection, freshness: GrokSlotPreflightFreshness): GrokSlotPreflightReceipt;
+//# sourceMappingURL=grokSlotPreflightReceipt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grokSlotPreflightReceipt.d.ts","sourceRoot":"","sources":["../../src/runtime/grokSlotPreflightReceipt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAA8B,KAAK,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAE9G,eAAO,MAAM,2BAA2B,0CAA0C,CAAC;AAMnF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B;;;;kBAIxC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;kBAqBzC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,uFAAuF;AACvF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAItF;AAED;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEpG;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,gCAAgC,EAAE,SAAS,EAAE,0BAA0B,GAAG,wBAAwB,CAgB5K"}