@noopolis/daimon 0.1.2 → 0.2.0

package/dist/pi/engineWakeLimits.js

@@ -0,0 +1,55 @@
+/**
+ * Per-wake engine bounds, and the one place they are decided.
+ *
+ * `maxToolTurns` mediates only daimon-MCP tool calls; Codex's own shell
+ * (`exec_command`) is never routed through that gate, so a single Codex turn
+ * previously had no ceiling at all — one production wake ran 23:32→23:42
+ * (unbounded wall clock) making 51 shell calls. Codex's `--json` stream
+ * reports token usage exactly once, on `turn.completed` — there is no
+ * incremental total to watch mid-turn (verified against a live multi-tool-call
+ * turn: `item.completed` fires once per tool call, but usage is reported only
+ * on the single terminal `turn.completed`) — so the token ceiling is the best
+ * bound obtainable from that wire shape: it converts an over-budget turn into
+ * an explicit, killed, named failure instead of a silent success, and the
+ * wall-clock timeout is what actually interrupts a runaway turn in progress.
+ *
+ * The names are engine-neutral: `DAIMON_ENGINE_WAKE_TIMEOUT_MS` and
+ * `DAIMON_ENGINE_WAKE_TOKEN_CEILING` bound Codex locally and are passed to the
+ * Grok broker as the wake's *lowering* limits (the broker refuses a value above
+ * its registration). The `DAIMON_CODEX_*` names remain aliases; setting both
+ * names of one bound to different values is refused rather than guessed.
+ */
+export const DEFAULT_CODEX_WAKE_TIMEOUT_MS = 240_000;
+export const DEFAULT_CODEX_WAKE_TOKEN_CEILING = 300_000;
+export const DAIMON_ENGINE_WAKE_TIMEOUT_MS_ENV = "DAIMON_ENGINE_WAKE_TIMEOUT_MS";
+export const DAIMON_ENGINE_WAKE_TOKEN_CEILING_ENV = "DAIMON_ENGINE_WAKE_TOKEN_CEILING";
+export const DAIMON_CODEX_WAKE_TIMEOUT_MS_ENV = "DAIMON_CODEX_WAKE_TIMEOUT_MS";
+export const DAIMON_CODEX_WAKE_TOKEN_CEILING_ENV = "DAIMON_CODEX_WAKE_TOKEN_CEILING";
+const positiveInteger = (value, name) => {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return parsed;
+};
+const declared = (environment, neutral, alias) => {
+    const primary = environment[neutral], legacy = environment[alias];
+    const value = primary === undefined ? undefined : positiveInteger(primary, neutral);
+    const aliased = legacy === undefined ? undefined : positiveInteger(legacy, alias);
+    if (value !== undefined && aliased !== undefined && value !== aliased)
+        throw new Error(`${neutral} and ${alias} disagree; set one`);
+    return value ?? aliased;
+};
+export const resolveCodexWakeTimeoutMs = (environment = process.env) => declared(environment, DAIMON_ENGINE_WAKE_TIMEOUT_MS_ENV, DAIMON_CODEX_WAKE_TIMEOUT_MS_ENV) ?? DEFAULT_CODEX_WAKE_TIMEOUT_MS;
+export const resolveCodexWakeTokenCeiling = (environment = process.env) => declared(environment, DAIMON_ENGINE_WAKE_TOKEN_CEILING_ENV, DAIMON_CODEX_WAKE_TOKEN_CEILING_ENV) ?? DEFAULT_CODEX_WAKE_TOKEN_CEILING;
+/**
+ * The limits a wake asks a broker to lower to: only the bounds the operator
+ * actually set, never the Codex defaults (a broker registration's declared
+ * limits already are the defaults there).
+ */
+export const resolveEngineWakeLimitOverrides = (environment = process.env) => {
+    const timeoutMs = declared(environment, DAIMON_ENGINE_WAKE_TIMEOUT_MS_ENV, DAIMON_CODEX_WAKE_TIMEOUT_MS_ENV);
+    const maxTokens = declared(environment, DAIMON_ENGINE_WAKE_TOKEN_CEILING_ENV, DAIMON_CODEX_WAKE_TOKEN_CEILING_ENV);
+    if (timeoutMs === undefined && maxTokens === undefined)
+        return undefined;
+    return { ...(timeoutMs === undefined ? {} : { timeoutMs }), ...(maxTokens === undefined ? {} : { maxTokens }) };
+};

package/dist/pi/grokHeadlessResult.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Token accounting for one turn, as the engine itself reported it.
+ *
+ * These are subscription-backed CLIs, so nothing here is billed: the counts are
+ * real quota consumption and `notionalUsd` is what the same turn would have cost
+ * at metered API rates. Kept away from anything named `cost` so a later reader
+ * cannot mistake it for a charge.
+ *
+ * Field provenance is the `streaming-messages-json` terminal `result` frame,
+ * which production hardcodes (`grokBrokerWorkerConfig.ts`). Its `result.usage`
+ * is the Messages API `message.usage` shape with three *disjoint* prompt-side
+ * buckets, so the full turn cost is
+ * `input_tokens + cache_read_input_tokens + cache_creation_input_tokens + output_tokens`.
+ */
+export type GrokTurnUsage = Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+    calls: number;
+    notionalUsd: number;
+    complete: boolean;
+}>;
+export type GrokHeadlessTurn = Readonly<{
+    text: string;
+    usage?: GrokTurnUsage;
+}>;
+/**
+ * Decode Grok's terminal message stream without treating progress messages as a
+ * reply, and extract the turn's own token accounting from the same frame.
+ */
+export declare const decodeGrokHeadlessTurn: (output: string) => GrokHeadlessTurn;
+/** Text-only view of {@link decodeGrokHeadlessTurn}, for callers that do not meter. */
+export declare const decodeGrokHeadlessResult: (output: string) => string;
+//# sourceMappingURL=grokHeadlessResult.d.ts.map

package/dist/pi/grokHeadlessResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grokHeadlessResult.d.ts","sourceRoot":"","sources":["../../src/pi/grokHeadlessResult.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC,CAAC;AA8DjF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,KAAG,gBA+BvD,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,wBAAwB,GAAI,QAAQ,MAAM,KAAG,MAA6C,CAAC"}

package/dist/pi/grokHeadlessResult.js

@@ -0,0 +1,118 @@
+const PUBLISHABLE_STOP_REASONS = new Set(["end_turn", "stop_sequence"]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const invalidResult = (detail) => new Error(`Grok CLI returned no publishable terminal response: ${detail}`);
+/**
+ * The four disjoint token buckets grok emits on `result.usage`. All four must be
+ * present and be non-negative safe integers; a renamed, stringified, negative,
+ * or fractional field rejects the whole block rather than silently contributing
+ * a zero, because a zero bucket is byte-indistinguishable from a real one.
+ */
+const USAGE_TOKEN_FIELDS = ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+const tokenCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const nonNegativeAmount = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+/**
+ * Extract per-turn usage from the terminal `result` frame.
+ *
+ * Advisory: a malformed or absent usage block yields `undefined` rather than
+ * failing a turn that published correctly, and never throws.
+ *
+ * `complete` is a stated heuristic, not a wire-observable signal. grok's own
+ * embedded documentation for this stream says any bucket it cannot account for
+ * "falls back to `0`, because the Messages API schema has no marker for
+ * incomplete or absent usage", and instructs consumers to "read an all-zero
+ * `usage` here as 'unknown', not 'free'". That is exactly the rule below. It
+ * cannot catch a *partially* zero-filled turn, which sums to a plausible total
+ * and is stamped `complete: true` while under-counting — so every count this
+ * decoder produces is a lower bound.
+ */
+const decodeTurnUsage = (result) => {
+    if (!isRecord(result.usage))
+        return undefined;
+    const usage = result.usage;
+    const counts = USAGE_TOKEN_FIELDS.map((field) => tokenCount(usage[field]));
+    if (counts.some((count) => count === undefined))
+        return undefined;
+    const [input, output, cacheRead, cacheWrite] = counts;
+    const total = input + cacheRead + cacheWrite + output;
+    return { input, output, cacheRead, cacheWrite, total, calls: tokenCount(result.num_turns) ?? 0, notionalUsd: nonNegativeAmount(result.total_cost_usd), complete: total > 0 };
+};
+const decodeTerminalAssistant = (event) => {
+    if (event.type !== "assistant" || event.parent_tool_use_id !== null)
+        return undefined;
+    if (typeof event.session_id !== "string" || !isRecord(event.message))
+        throw invalidResult("invalid assistant event");
+    const message = event.message;
+    if (message.role !== "assistant" || typeof message.stop_reason !== "string" || !Array.isArray(message.content)) {
+        throw invalidResult("invalid assistant event");
+    }
+    if (!PUBLISHABLE_STOP_REASONS.has(message.stop_reason))
+        return { sessionId: event.session_id, stopReason: message.stop_reason, text: "" };
+    let text = "";
+    let textBlocks = 0;
+    for (const block of message.content) {
+        if (!isRecord(block) || typeof block.type !== "string")
+            throw invalidResult("invalid assistant content");
+        if (block.type === "thinking")
+            continue;
+        if (block.type !== "text" || typeof block.text !== "string")
+            throw invalidResult("invalid terminal content");
+        text += block.text;
+        textBlocks += 1;
+    }
+    if (textBlocks === 0 || text.trim().length === 0)
+        throw invalidResult("empty response");
+    return { sessionId: event.session_id, stopReason: message.stop_reason, text };
+};
+/**
+ * Decode Grok's terminal message stream without treating progress messages as a
+ * reply, and extract the turn's own token accounting from the same frame.
+ */
+export const decodeGrokHeadlessTurn = (output) => {
+    const lines = output.split(/\r?\n/).filter((line) => line.length > 0);
+    if (lines.length === 0)
+        throw invalidResult("empty stream");
+    let finalAssistant;
+    let result;
+    for (const [index, line] of lines.entries()) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            throw invalidResult("invalid JSON");
+        }
+        if (!isRecord(event) || typeof event.type !== "string")
+            throw invalidResult("invalid event");
+        if (event.type === "error") {
+            const rejection = asGrokAuthenticationRejected(JSON.stringify(event));
+            if (rejection !== undefined)
+                throw rejection;
+            throw invalidResult("engine error");
+        }
+        const assistant = decodeTerminalAssistant(event);
+        if (assistant !== undefined)
+            finalAssistant = assistant;
+        if (event.type === "result") {
+            if (index !== lines.length - 1)
+                throw invalidResult("non-terminal result");
+            result = event;
+        }
+    }
+    if (result === undefined || result.subtype !== "success" || result.is_error !== false)
+        throw invalidResult("unsuccessful result");
+    if (typeof result.stop_reason !== "string" || !PUBLISHABLE_STOP_REASONS.has(result.stop_reason))
+        throw invalidResult("non-terminal stop");
+    if ("errors" in result && (!Array.isArray(result.errors) || result.errors.length > 0))
+        throw invalidResult("engine error");
+    if (typeof result.result !== "string" || result.result.trim().length === 0)
+        throw invalidResult("empty response");
+    if (finalAssistant === undefined || finalAssistant.stopReason !== result.stop_reason ||
+        finalAssistant.sessionId !== result.session_id || finalAssistant.text !== result.result) {
+        throw invalidResult("terminal result mismatch");
+    }
+    const usage = decodeTurnUsage(result);
+    return usage === undefined ? { text: result.result.trim() } : { text: result.result.trim(), usage };
+};
+/** Text-only view of {@link decodeGrokHeadlessTurn}, for callers that do not meter. */
+export const decodeGrokHeadlessResult = (output) => decodeGrokHeadlessTurn(output).text;
+import { asGrokAuthenticationRejected } from "../runtime/grokAuthenticationError.js";

package/dist/pi/grokHomeMcpRegistration.d.ts

@@ -0,0 +1,21 @@
+import type { CliMcpRegistration } from "./cliMcpRegistration.js";
+/**
+ * Per-wake MCP registration for the direct (non-broker) Grok CLI path.
+ *
+ * `grok mcp add --scope project` writes `<cwd>/.grok/config.toml`, which Grok
+ * 1.0.34 skips entirely in an untrusted workspace — and Daimon keeps every
+ * workspace untrusted so cwd `AGENTS.md` and project skills never load. The
+ * endpoint therefore goes into the agent's own Daimon-owned `GROK_HOME`
+ * config, rendered from the same lean base the broker worker uses
+ * (`renderGrokLeanBaseConfig`), and is removed again after the turn by
+ * rewriting the base alone.
+ *
+ * There is no fallback to the operator's `~/.grok`: without an explicit
+ * `engineHomePath` the session refuses, rather than editing a human's config.
+ */
+export declare function registerGrokHomeMcpServer(input: Readonly<{
+    engineHomePath: string | undefined;
+    endpoint: string;
+    verify?: () => Promise<void>;
+}>): Promise<CliMcpRegistration>;
+//# sourceMappingURL=grokHomeMcpRegistration.d.ts.map

package/dist/pi/grokHomeMcpRegistration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grokHomeMcpRegistration.d.ts","sourceRoot":"","sources":["../../src/pi/grokHomeMcpRegistration.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAE,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAepL"}

package/dist/pi/grokHomeMcpRegistration.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { renderGrokLeanBaseConfig } from "../runtime/grokBrokerWorkerConfig.js";
+/**
+ * Per-wake MCP registration for the direct (non-broker) Grok CLI path.
+ *
+ * `grok mcp add --scope project` writes `<cwd>/.grok/config.toml`, which Grok
+ * 1.0.34 skips entirely in an untrusted workspace — and Daimon keeps every
+ * workspace untrusted so cwd `AGENTS.md` and project skills never load. The
+ * endpoint therefore goes into the agent's own Daimon-owned `GROK_HOME`
+ * config, rendered from the same lean base the broker worker uses
+ * (`renderGrokLeanBaseConfig`), and is removed again after the turn by
+ * rewriting the base alone.
+ *
+ * There is no fallback to the operator's `~/.grok`: without an explicit
+ * `engineHomePath` the session refuses, rather than editing a human's config.
+ */
+export async function registerGrokHomeMcpServer(input) {
+    const home = input.engineHomePath;
+    if (home === undefined || !path.isAbsolute(home)) {
+        throw new Error("Grok direct CLI sessions require a Daimon-owned GROK_HOME (engineHomePath): Grok 1.0.34 ignores project-scoped MCP servers in untrusted workspaces");
+    }
+    if (!/^http:\/\/127\.0\.0\.1:\d{1,5}\/[A-Za-z0-9/_-]*$/u.test(input.endpoint))
+        throw new Error("Grok MCP endpoint must be a loopback http URL");
+    await input.verify?.();
+    await writeConfig(home, `${renderGrokLeanBaseConfig()}[mcp_servers.daimon]\nurl = ${JSON.stringify(input.endpoint)}\n`);
+    let closePromise;
+    return {
+        close: () => closePromise ??= (async () => {
+            await input.verify?.();
+            await writeConfig(home, renderGrokLeanBaseConfig());
+        })()
+    };
+}
+async function writeConfig(home, text) {
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    const directory = await lstat(home);
+    if (!directory.isDirectory() || directory.isSymbolicLink())
+        throw new Error("Grok engine home is not a private directory");
+    const target = path.join(home, "config.toml");
+    const temporary = path.join(home, `.config.toml.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(text);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, target);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+    }
+}

package/dist/pi/grokSandbox.d.ts

@@ -0,0 +1,11 @@
+export declare const GROK_DAIMON_SANDBOX_PROFILE: "daimon-strict";
+export interface GrokSandboxAuthority {
+    readonly command: string;
+    readonly commandArgs?: readonly string[];
+    readonly cwd: string;
+    readonly engineHomePath: string;
+    readonly protectedPaths: readonly string[];
+    readonly runtimeHomePath: string;
+}
+export declare function prepareAndVerifyGrokSandbox(authority: GrokSandboxAuthority): Promise<void>;
+//# sourceMappingURL=grokSandbox.d.ts.map

package/dist/pi/grokSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grokSandbox.d.ts","sourceRoot":"","sources":["../../src/pi/grokSandbox.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,2BAA2B,iBAA8B,CAAC;AAOvE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,oBAAoB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/dist/pi/grokSandbox.js

@@ -0,0 +1,216 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { readChild } from "./cliChildOutput.js";
+import { cliChildEnvironment } from "./cliEnvironment.js";
+import { terminateChild, trackCliChild } from "./cliProcess.js";
+import { renderGrokSandboxArgs } from "./cliEngineSpawn.js";
+import { assertGrokWorkerDenyPathsPlaceable } from "../runtime/grokWorkerDenyPlacement.js";
+import { GROK_WORKER_SANDBOX_EVENTS_RELATIVE_PATH, GROK_WORKER_SANDBOX_PROFILE, renderGrokWorkerSandboxProfile } from "../runtime/grokWorkerSandboxProfile.js";
+export const GROK_DAIMON_SANDBOX_PROFILE = GROK_WORKER_SANDBOX_PROFILE;
+const SANDBOX_CONFIG = "sandbox.toml";
+/** Grok 1.0.34 logs sandbox events under `sessions/`; the root file stays empty. */
+const SANDBOX_EVENTS = GROK_WORKER_SANDBOX_EVENTS_RELATIVE_PATH;
+const MAX_EVENTS_BYTES = 16 * 1024 * 1024;
+const ROTATE_EVENTS_BYTES = 8 * 1024 * 1024;
+export async function prepareAndVerifyGrokSandbox(authority) {
+    const engineHome = await realpath(authority.engineHomePath);
+    const cwd = await realpath(authority.cwd);
+    await assertPrivateDirectory(engineHome);
+    const denied = [...new Set(await Promise.all(authority.protectedPaths.map((entry) => realpath(entry))))].sort();
+    if (denied.some((entry) => overlaps(entry, cwd) || overlaps(entry, engineHome))) {
+        throw unavailable();
+    }
+    // Grok 1.0.34 materializes every deny target inside bubblewrap as the uid it
+    // runs Grok under — here, this process's own — and refuses the whole profile
+    // if one cannot be resolved. Refusing now names the path; letting it through
+    // would kill every turn with a bare `bwrap: Can't create file at …`.
+    await assertGrokWorkerDenyPathsPlaceable(denied, { uid: process.getuid?.() ?? 0, gid: process.getgid?.() ?? 0 });
+    await writeProfile(engineHome, denied);
+    const beforeBytes = await eventFileSize(path.join(engineHome, SANDBOX_EVENTS));
+    const child = trackCliChild(spawn(authority.command, [
+        ...renderGrokSandboxArgs(authority.commandArgs, GROK_DAIMON_SANDBOX_PROFILE),
+        "--cwd", cwd,
+        "inspect"
+    ], {
+        cwd,
+        detached: process.platform !== "win32",
+        env: cliChildEnvironment([], authority.runtimeHomePath, {
+            engine: "grok",
+            engineHomePath: engineHome,
+            executablePath: authority.command
+        }),
+        stdio: ["ignore", "pipe", "pipe"]
+    }));
+    try {
+        await readChild(child, 10_000, []);
+    }
+    catch {
+        throw unavailable();
+    }
+    finally {
+        await terminateChild(child).catch(() => undefined);
+    }
+    await verifyEnforcementEvent(path.join(engineHome, SANDBOX_EVENTS), beforeBytes, cwd, denied);
+    await verifyProfile(engineHome, denied);
+}
+const profileText = (denied) => renderGrokWorkerSandboxProfile(denied);
+async function writeProfile(engineHome, denied) {
+    const target = path.join(engineHome, SANDBOX_CONFIG);
+    const temporary = path.join(engineHome, `.${SANDBOX_CONFIG}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow(), 0o600);
+        await handle.writeFile(profileText(denied));
+        await handle.chmod(0o600);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, target);
+        await syncDirectory(engineHome);
+        await verifyProfile(engineHome, denied);
+    }
+    catch {
+        throw unavailable();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function verifyProfile(engineHome, denied) {
+    const file = path.join(engineHome, SANDBOX_CONFIG);
+    let handle;
+    try {
+        const before = await lstat(file);
+        assertPrivateFile(before, 64 * 1024);
+        handle = await open(file, constants.O_RDONLY | noFollow());
+        const opened = await handle.stat();
+        assertPrivateFile(opened, 64 * 1024);
+        if (!sameIdentity(before, opened) || await handle.readFile("utf8") !== profileText(denied))
+            throw new Error("changed");
+        const after = await handle.stat();
+        if (!sameIdentity(opened, after))
+            throw new Error("changed");
+    }
+    catch {
+        throw unavailable();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function verifyEnforcementEvent(file, beforeBytes, cwd, denied) {
+    let handle;
+    try {
+        const before = await lstat(file);
+        assertPrivateFile(before, MAX_EVENTS_BYTES);
+        if (before.size <= beforeBytes)
+            throw new Error("missing event");
+        handle = await open(file, constants.O_RDONLY | noFollow());
+        const opened = await handle.stat();
+        if (!sameIdentity(before, opened))
+            throw new Error("changed");
+        const bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (!sameIdentity(opened, after))
+            throw new Error("changed");
+        const appended = bytes.subarray(beforeBytes).toString("utf8").trim().split("\n").filter(Boolean);
+        const event = JSON.parse(appended.at(-1) ?? "null");
+        const observedDenied = Array.isArray(event?.deny_paths)
+            ? event.deny_paths.filter((entry) => typeof entry === "string").sort()
+            : [];
+        if (event?.event_type !== "ProfileApplied" || event.profile !== GROK_DAIMON_SANDBOX_PROFILE
+            || event.enforced !== true || event.restrict_network !== true || event.workspace !== cwd
+            || !/^(?:linux\/landlock|macos\/seatbelt)$/u.test(String(event.platform ?? ""))
+            || JSON.stringify(observedDenied) !== JSON.stringify(denied))
+            throw new Error("not enforced");
+        bytes.fill(0);
+    }
+    catch {
+        throw unavailable();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function eventFileSize(file) {
+    try {
+        const entry = await lstat(file);
+        assertPrivateFile(entry, MAX_EVENTS_BYTES, true);
+        if (entry.size >= ROTATE_EVENTS_BYTES) {
+            await replaceWithEmptyPrivateFile(file);
+            return 0;
+        }
+        return Number(entry.size);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            await mkdir(path.dirname(file), { mode: 0o700, recursive: true });
+            const handle = await open(file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow(), 0o600);
+            try {
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await syncDirectory(path.dirname(file));
+            return 0;
+        }
+        throw unavailable();
+    }
+}
+async function replaceWithEmptyPrivateFile(file) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow(), 0o600);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, file);
+        await syncDirectory(path.dirname(file));
+        const entry = await lstat(file);
+        assertPrivateFile(entry, 0, true);
+    }
+    catch {
+        throw unavailable();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function assertPrivateDirectory(directory) {
+    try {
+        const entry = await lstat(directory);
+        if (!entry.isDirectory() || entry.isSymbolicLink() || entry.uid !== process.getuid?.()
+            || (Number(entry.mode) & 0o777) !== 0o700)
+            throw new Error("unsafe");
+    }
+    catch {
+        throw unavailable();
+    }
+}
+async function syncDirectory(directory) {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+const overlaps = (left, right) => left === right || left.startsWith(`${right}${path.sep}`) || right.startsWith(`${left}${path.sep}`);
+const sameIdentity = (left, right) => left.dev === right.dev && left.ino === right.ino && left.mode === right.mode
+    && left.nlink === right.nlink && left.size === right.size && left.uid === right.uid && left.mtimeMs === right.mtimeMs;
+const assertPrivateFile = (entry, maxBytes, allowEmpty = false) => {
+    if (!entry.isFile() || entry.isSymbolicLink() || entry.uid !== process.getuid?.()
+        || entry.nlink !== 1 || (Number(entry.mode) & 0o777) !== 0o600
+        || (!allowEmpty && entry.size < 1) || entry.size > maxBytes)
+        throw new Error("unsafe");
+};
+const noFollow = () => constants.O_NOFOLLOW ?? 0;
+const unavailable = () => new Error("Grok kernel sandbox enforcement is unavailable");

package/dist/pi/grokStreamUsage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-request token accounting read off a Grok `streaming-messages-json`
+ * stream.
+ *
+ * Grok 1.0.34 puts the usage of each model request on that request's
+ * top-level `assistant` frame (`message.usage`, the same four disjoint
+ * Messages API buckets as the terminal `result.usage`), before any tool result
+ * of that request, and the per-request frames sum exactly to the terminal
+ * result (P0 host matrix). That makes the stream usable in two places the
+ * terminal frame is not: a turn that failed before its `result` frame, and a
+ * per-request ledger row.
+ *
+ * Never throws, and never invents a number: a usage block that is present but
+ * does not decode discards *all* requests, because one fabricated zero is
+ * byte-identical to a measured one.
+ */
+export type GrokRequestUsage = Readonly<{
+    index: number;
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    total: number;
+}>;
+export type GrokStreamUsage = Readonly<{
+    requests: readonly GrokRequestUsage[];
+    sessionId?: string;
+    reportedModels: readonly string[];
+}>;
+export declare const decodeGrokStreamUsage: (output: string) => GrokStreamUsage;
+//# sourceMappingURL=grokStreamUsage.d.ts.map

package/dist/pi/grokStreamUsage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grokStreamUsage.d.ts","sourceRoot":"","sources":["../../src/pi/grokStreamUsage.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAChJ,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IAAE,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC;AAkBzI,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,KAAG,eAmBtD,CAAC"}

package/dist/pi/grokStreamUsage.js

@@ -0,0 +1,51 @@
+import { GROK_ENGINE_BROKER } from "../contracts/runtimeContractManifest.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const tokenCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/u;
+const MODEL_KEY = /^[a-z0-9][a-z0-9.-]{0,63}$/u;
+const decodeUsage = (usage) => {
+    if (!isRecord(usage))
+        return undefined;
+    const input = tokenCount(usage.input_tokens), output = tokenCount(usage.output_tokens), cacheRead = tokenCount(usage.cache_read_input_tokens), cacheWrite = tokenCount(usage.cache_creation_input_tokens);
+    if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined)
+        return undefined;
+    const total = input + cacheRead + cacheWrite + output;
+    // Beyond the model context window one request cannot have spent it: invalid, like a malformed block.
+    if (total > GROK_ENGINE_BROKER.turnLimits.requestUsageMaxTokens)
+        return undefined;
+    return { input, cacheRead, cacheWrite, output, total };
+};
+export const decodeGrokStreamUsage = (output) => {
+    const byMessage = new Map();
+    const reportedModels = new Set();
+    let sessionId, corrupt = false;
+    for (const line of output.split(/\r?\n/u)) {
+        if (line.trim().length === 0)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(event))
+            continue;
+        if (typeof event.session_id === "string" && SESSION_ID.test(event.session_id))
+            sessionId ??= event.session_id;
+        if (event.type === "result" && isRecord(event.modelUsage))
+            for (const key of Object.keys(event.modelUsage))
+                reportedModels.add(MODEL_KEY.test(key) ? key : "invalid");
+        if (event.type !== "assistant" || event.parent_tool_use_id !== null || !isRecord(event.message) || event.message.usage === undefined)
+            continue;
+        const decoded = decodeUsage(event.message.usage);
+        if (decoded === undefined || typeof event.message.id !== "string") {
+            corrupt = true;
+            continue;
+        }
+        // One request can surface as more than one frame of the same message; it is one request.
+        byMessage.set(event.message.id, decoded);
+    }
+    const requests = corrupt ? [] : [...byMessage.values()].map((usage, index) => Object.freeze({ index, ...usage }));
+    return { requests, ...(sessionId === undefined ? {} : { sessionId }), reportedModels: [...reportedModels].sort() };
+};

package/dist/pi/piAgentHandle.d.ts

@@ -6,7 +6,7 @@ import { persistPiTurnTrace, type PiTurnTraceModel } from "./turnTrace.js";
 import { type PiRawTrainingCaptureOptions, type PiRawTrainingCaptureRef } from "./rawTrainingCapture.js";
 import { type PiWorldToolContextRef } from "./worldNudge.js";
 import { type PiWorldTrajectoryIdentity } from "./worldTrajectory.js";
-import { type PiNativeSessionCreator, type PiSession, type PiSessionCreator, type PiSessionLike } from "./piAgentWakeSupport.js";
+import { type PiNativeSessionCreator, type PiSession, type PiSessionCreator, type PiSessionLike, type PiWakeEnvironmentContextRef } from "./piAgentWakeSupport.js";
 import { type MemoryRuntime } from "@noopolis/mneme";
 export type { PiSession, PiSessionLike, PiSessionCreator, PiNativeSessionCreator } from "./piAgentWakeSupport.js";
 export type WakeAcceptanceInput = {
@@ -28,6 +28,7 @@ export declare class PiAgentHandle implements AgentHandle {
     private readonly rawTrainingCaptureOptions?;
     private readonly worldTrajectoryIdentity?;
     private readonly piSessionForRawCapture?;
+    private readonly wakeEnvironmentContext?;
     private state;
     private lastWakeAt;
     private lastError;
@@ -35,8 +36,8 @@ export declare class PiAgentHandle implements AgentHandle {
     private readonly stampTurnInputSubmitted;
     private readonly stampTurnOutputCompleted;
     private readonly persistTrace;
-    constructor(id: string, session: PiSession, createSession: PiNativeSessionCreator, runtimeHomePath: string, traceModel: PiTurnTraceModel, memory?: MemoryRuntime, memoryToolContext?: PiMemoryToolContextRef, dependencies?: WakeAcceptanceInput, worldToolContext?: PiWorldToolContextRef, rawTrainingCaptureRef?: PiRawTrainingCaptureRef, rawTrainingCaptureOptions?: PiRawTrainingCaptureOptions, worldTrajectoryIdentity?: PiWorldTrajectoryIdentity, rawTrainingCaptureSession?: PiSession);
-    constructor(id: string, session: PiSessionLike, createSession: PiSessionCreator, runtimeHomePath: string, traceModel: PiTurnTraceModel, memory?: MemoryRuntime, memoryToolContext?: PiMemoryToolContextRef, dependencies?: WakeAcceptanceInput, worldToolContext?: PiWorldToolContextRef, rawTrainingCaptureRef?: never, rawTrainingCaptureOptions?: never, worldTrajectoryIdentity?: PiWorldTrajectoryIdentity, rawTrainingCaptureSession?: never);
+    constructor(id: string, session: PiSession, createSession: PiNativeSessionCreator, runtimeHomePath: string, traceModel: PiTurnTraceModel, memory?: MemoryRuntime, memoryToolContext?: PiMemoryToolContextRef, dependencies?: WakeAcceptanceInput, worldToolContext?: PiWorldToolContextRef, rawTrainingCaptureRef?: PiRawTrainingCaptureRef, rawTrainingCaptureOptions?: PiRawTrainingCaptureOptions, worldTrajectoryIdentity?: PiWorldTrajectoryIdentity, rawTrainingCaptureSession?: PiSession, wakeEnvironmentContext?: PiWakeEnvironmentContextRef);
+    constructor(id: string, session: PiSessionLike, createSession: PiSessionCreator, runtimeHomePath: string, traceModel: PiTurnTraceModel, memory?: MemoryRuntime, memoryToolContext?: PiMemoryToolContextRef, dependencies?: WakeAcceptanceInput, worldToolContext?: PiWorldToolContextRef, rawTrainingCaptureRef?: never, rawTrainingCaptureOptions?: never, worldTrajectoryIdentity?: PiWorldTrajectoryIdentity, rawTrainingCaptureSession?: never, wakeEnvironmentContext?: PiWakeEnvironmentContextRef);
     wake(event: WakeEvent): Promise<WakeResult>;
     private runWake;
     status(): AgentStatus;