@noopolis/daimon 0.1.1 → 0.2.0

package/dist/pi/cliSession.js

@@ -0,0 +1,379 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createPiToolMcpServer } from "../mcp/toolServer.js";
+import { redactCredentialError, redactCredentialText } from "../core/credentialRedaction.js";
+import { asGrokAuthenticationRejected, classifyGrokAuthenticationDiagnostic, GrokSubscriptionAuthenticationRejectedError } from "../runtime/grokAuthenticationError.js";
+import { readChild } from "./cliChildOutput.js";
+import { cliChildEnvironment } from "./cliEnvironment.js";
+import { spawnEngine } from "./cliEngineSpawn.js";
+import { registerCliMcpServer, renderAgyMcpAddArgs, renderAgyMcpRemoveArgs } from "./cliMcpRegistration.js";
+import { registerGrokHomeMcpServer } from "./grokHomeMcpRegistration.js";
+import { decodeAgyHeadlessTurn } from "./agyHeadlessResult.js";
+import { createCliTurnMeter, decodeCodexTurn, failedTurnOutcome, publishTurnRequests, publishTurnUsage } from "./cliTurnMetering.js";
+import { decodeGrokHeadlessResult } from "./grokHeadlessResult.js";
+import { terminateChild } from "./cliProcess.js";
+import { ensureRuntimeHome, ensureRuntimeHomeDirectory } from "../runtime/runtimeHomeLayout.js";
+/**
+ * The per-wake tool-call bound for AGY, and the one place it is decided.
+ *
+ * Codex and Grok leave this `undefined` — their only bound is the wake
+ * deadline. AGY does not get that treatment, for a measured reason: its
+ * terminal usage frame is the *sum* over the turn's model steps, and each tool
+ * step resends the whole context. The live capture is 13,796 total tokens for a
+ * tool-free turn and 45,381 for a turn with a single call against an
+ * empty-schema tool — one call roughly triples the wake. An unbounded loop on
+ * the one engine whose subscription quota is currently the operator's only
+ * working credential is a cost hazard, not a capability.
+ *
+ * 16 is chosen so a realistic wake is never truncated (read a few declared MCP
+ * tools, then send one or two Moltnet messages) while the worst case is bounded
+ * at roughly a quarter-million tokens instead of "whatever fits in 180s". The
+ * bound degrades gracefully rather than failing the wake: exceeding it returns
+ * `McpToolTurnLimitError` to the model as a tool *error*, so the agent can still
+ * finish its turn and reply.
+ */
+export const AGY_MAX_TOOL_TURNS = 16;
+export { DAIMON_CODEX_WAKE_TIMEOUT_MS_ENV, DAIMON_CODEX_WAKE_TOKEN_CEILING_ENV, DAIMON_ENGINE_WAKE_TIMEOUT_MS_ENV, DAIMON_ENGINE_WAKE_TOKEN_CEILING_ENV, DEFAULT_CODEX_WAKE_TIMEOUT_MS, DEFAULT_CODEX_WAKE_TOKEN_CEILING, resolveCodexWakeTimeoutMs, resolveCodexWakeTokenCeiling, resolveEngineWakeLimitOverrides } from "./engineWakeLimits.js";
+export const prepareCliRuntimeHome = async (runtimeHomePath) => {
+    if (runtimeHomePath === undefined)
+        return;
+    await ensureRuntimeHome(runtimeHomePath);
+    await Promise.all([".config", ".local/share", ".local/state", ".cache", ".tmp"]
+        .map((relative) => ensureRuntimeHomeDirectory(runtimeHomePath, relative)));
+};
+const childSecretValues = (redactedNames) => redactedNames
+    .map((name) => process.env[name])
+    .filter((value) => typeof value === "string" && value.length > 0);
+const captureCleanup = async (current, action) => {
+    try {
+        await action();
+    }
+    catch (error) {
+        return current ?? error;
+    }
+    return current;
+};
+export { terminateChild } from "./cliProcess.js";
+export { CLI_ENGINE_MAX_DIAGNOSTIC_BYTES, CLI_ENGINE_MAX_OUTPUT_BYTES, readChild } from "./cliChildOutput.js";
+const startMcp = async (tools, maxToolTurns, wakeDeadline, onToolsMounted, onStarted) => {
+    onToolsMounted?.(tools);
+    const mcpServer = createPiToolMcpServer(tools, { maxToolTurns, wakeDeadline });
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+    const httpServer = createServer((request, response) => {
+        void transport.handleRequest(request, response);
+    });
+    let lifecycle = "starting";
+    let cancelled = false;
+    let endpoint = "";
+    let closePromise;
+    let settleStartup;
+    const startupSettled = new Promise((resolve) => { settleStartup = resolve; });
+    const close = () => closePromise ??= (async () => {
+        cancelled = true;
+        if (lifecycle !== "closed")
+            lifecycle = "closing";
+        // `listen()` begins synchronously but its callback is pending. Waiting for
+        // startup prevents dispose from returning while that callback can still bind.
+        await startupSettled;
+        await transport.close().catch(() => undefined);
+        await mcpServer.close().catch(() => undefined);
+        // `close` only stops accepting and then waits for every open connection,
+        // including the ones the transport has no record of and so cannot end (a
+        // socket opened before `initialize`, or a client pool's idle keep-alive
+        // socket, which relaying a turn through the broker MCP facade leaves
+        // behind). That wait is unbounded and sits on the wake's own completion
+        // path: measured, one such connection parked a finished broker turn with
+        // its result in hand and published nothing. By here this one wake's engine
+        // has returned, failed or been cancelled, so anything still connected is a
+        // leftover — see `AGENTS.md`, and the facade, which bounds itself the same
+        // way.
+        if (httpServer.listening)
+            await new Promise((resolve) => { httpServer.close(() => resolve()); httpServer.closeAllConnections(); });
+        lifecycle = "closed";
+    })();
+    const mount = { get endpoint() { return endpoint; }, close };
+    onStarted(mount);
+    let startupError;
+    try {
+        if (cancelled)
+            throw new Error("MCP startup was cancelled");
+        await mcpServer.connect(transport);
+        if (cancelled)
+            throw new Error("MCP startup was cancelled");
+        await new Promise((resolve, reject) => {
+            const onError = (error) => reject(error);
+            httpServer.once("error", onError);
+            httpServer.listen(0, "127.0.0.1", () => {
+                httpServer.off("error", onError);
+                // A disposer can run from a Server.prototype.listen interceptor before
+                // this callback. Never publish the server as live in that interleaving.
+                if (!cancelled)
+                    lifecycle = "listening";
+                resolve();
+            });
+        });
+        if (cancelled)
+            throw new Error("MCP startup was cancelled");
+        const address = httpServer.address();
+        if (address === null || typeof address === "string") {
+            throw new Error("MCP server did not receive an ephemeral port");
+        }
+        endpoint = `http://127.0.0.1:${address.port}/mcp`;
+        return mount;
+    }
+    catch (error) {
+        startupError = error;
+        throw error;
+    }
+    finally {
+        settleStartup();
+        if (cancelled || startupError !== undefined)
+            await close();
+    }
+};
+class CliSession {
+    options;
+    input;
+    listeners = new Set();
+    setupChildren = new Set();
+    disposed = false;
+    activeChild;
+    activeMount;
+    activeBrokerTurn;
+    mcpRegistration;
+    disposePromise;
+    wakeId;
+    constructor(options, input) {
+        this.options = options;
+        this.input = input;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    bindWake(event) {
+        this.wakeId = event?.id;
+    }
+    async prompt(text) {
+        if (this.disposed)
+            throw new Error("CLI session is disposed");
+        await prepareCliRuntimeHome(this.input.runtimeHomePath);
+        const deadline = this.options.timeoutMs === undefined ? undefined : Date.now() + this.options.timeoutMs;
+        const environmentSecretValues = childSecretValues([
+            ...(this.options.redactedEnvironmentNames ?? []),
+            ...(this.input.daimonSecretEnvironmentNames ?? [])
+        ]);
+        const stagedCredentialSecrets = await this.options.credentialSecretValues?.() ?? [];
+        const secretValues = [...environmentSecretValues, ...stagedCredentialSecrets];
+        let mount;
+        let registration;
+        let turnUsage;
+        // Kept beside the decoded turn so a wake that never reaches its decoder
+        // still owes the ledger the usage Codex already reported (`cliTurnMetering.ts`).
+        const meter = createCliTurnMeter();
+        // Codex's own `thread.started` frame, carried out of the stream so the
+        // wake's rollout can be found by identity rather than by recency.
+        let codexThreadId;
+        let instrumented = false;
+        const instrument = async () => {
+            if (instrumented)
+                return;
+            instrumented = true;
+            await publishTurnRequests(this.options.onCodexTurnRequests, codexThreadId);
+        };
+        let child;
+        let output;
+        let cleanupFailure;
+        let promptFailure;
+        try {
+            // Every CLI engine mounts the same tool surface. AGY used to be the one
+            // exception (`toolAccess: "none"`), which is exactly what made an AGY
+            // agent unable to reach Moltnet or a declared MCP server, and so unable
+            // to take part in an organization at all.
+            mount = await startMcp(this.input.customTools ?? [], this.options.maxToolTurns, deadline, this.options.onToolsMounted, (started) => {
+                this.activeMount = started;
+                if (this.disposed)
+                    void started.close();
+            });
+            this.ensureLive();
+            if (this.options.engine === "grok" && this.options.grokBrokerTurn !== undefined && mount !== undefined) {
+                const controller = new AbortController();
+                this.activeBrokerTurn = controller;
+                try {
+                    output = await this.options.grokBrokerTurn(`${this.options.identityPrompt ?? ""}${text}`, mount.endpoint, controller.signal);
+                }
+                finally {
+                    if (this.activeBrokerTurn === controller)
+                        this.activeBrokerTurn = undefined;
+                }
+            }
+            else {
+                if (this.options.engine === "grok" && mount !== undefined) {
+                    await this.options.verifyExecutable?.();
+                    registration = await registerGrokHomeMcpServer({
+                        engineHomePath: this.options.engineHomePath,
+                        endpoint: mount.endpoint,
+                        ...(this.options.verifyGrokSandbox !== undefined ? { verify: this.options.verifyGrokSandbox } : {})
+                    });
+                    this.mcpRegistration = registration;
+                }
+                else if (this.options.engine === "agy" && mount !== undefined) {
+                    await this.options.verifyExecutable?.();
+                    registration = await registerCliMcpServer({
+                        addArgs: renderAgyMcpAddArgs(this.options.commandArgs, mount.endpoint),
+                        removeArgs: renderAgyMcpRemoveArgs(this.options.commandArgs),
+                        command: this.options.command ?? this.options.engine,
+                        cwd: this.input.cwd,
+                        env: cliChildEnvironment([
+                            ...(this.options.redactedEnvironmentNames ?? []),
+                            ...(this.input.daimonSecretEnvironmentNames ?? [])
+                        ], this.input.runtimeHomePath, {
+                            ...(this.options.dbusSessionBusAddress !== undefined ? { dbusSessionBusAddress: this.options.dbusSessionBusAddress } : {}),
+                            engine: this.options.engine,
+                            executablePath: this.options.command,
+                            engineHomePath: this.options.engineHomePath
+                        }),
+                        onChild: (setupChild) => { this.setupChildren.add(setupChild); },
+                        onChildSettled: (setupChild) => this.setupChildren.delete(setupChild),
+                        secretValues
+                    });
+                    this.mcpRegistration = registration;
+                }
+                this.ensureLive();
+                await this.options.verifyRuntimePaths?.();
+                await this.options.verifyExecutable?.();
+                await this.options.verifyGrokSandbox?.();
+                child = spawnEngine(this.options, `${this.options.identityPrompt ?? ""}${text}`, this.input, mount?.endpoint, this.wakeId);
+                this.activeChild = child;
+                // Attach terminal listeners synchronously. A fast local sentinel may
+                // exit before an asynchronous post-spawn authority recheck completes.
+                const outputPromise = readChild(child, deadline === undefined ? undefined : Math.max(1, deadline - Date.now()), secretValues, {
+                    failureClassifier: this.options.engine === "grok" ? classifyGrokAuthenticationDiagnostic : undefined,
+                    retainNdjson: this.options.engine === "codex" ? "codex" : undefined,
+                    retainStdoutTail: this.options.engine === "grok",
+                    timeoutErrorMessage: this.options.engine === "codex" && this.options.timeoutMs !== undefined
+                        ? `Codex wake exceeded its ${this.options.timeoutMs}ms per-wake wall-clock bound`
+                        : undefined,
+                    codexTokenCeiling: this.options.engine === "codex" ? this.options.codexTokenCeiling : undefined,
+                    onCodexTurnCompleted: meter.observeCodexTurnCompleted,
+                    onCodexThreadStarted: (threadId) => { codexThreadId = threadId; }
+                });
+                void outputPromise.catch(() => undefined);
+                await this.options.verifyRuntimePaths?.();
+                await this.options.verifyExecutable?.();
+                const childOutput = await outputPromise;
+                if (this.options.engine === "grok")
+                    output = decodeGrokHeadlessResult(childOutput);
+                else if (this.options.engine === "codex") {
+                    const decoded = decodeCodexTurn(childOutput);
+                    output = decoded.text;
+                    turnUsage = decoded.usage;
+                }
+                else if (this.options.engine === "agy") {
+                    const decoded = decodeAgyHeadlessTurn(childOutput);
+                    output = decoded.text;
+                    turnUsage = decoded.usage;
+                }
+                else
+                    output = childOutput;
+            }
+        }
+        catch (error) {
+            promptFailure = error;
+        }
+        finally {
+            cleanupFailure = await captureCleanup(cleanupFailure, async () => { if (child !== undefined)
+                await terminateChild(child); });
+            if (this.activeChild === child)
+                this.activeChild = undefined;
+            let registrationClosed = registration === undefined;
+            cleanupFailure = await captureCleanup(cleanupFailure, async () => { await registration?.close(); registrationClosed = true; });
+            if (registrationClosed && this.mcpRegistration === registration)
+                this.mcpRegistration = undefined;
+            cleanupFailure = await captureCleanup(cleanupFailure, async () => { await mount?.close(); });
+            if (this.activeMount === mount)
+                this.activeMount = undefined;
+        }
+        const refreshedCredentialSecrets = await this.options.credentialSecretValues?.().catch(() => []) ?? [];
+        const finalSecrets = [...secretValues, ...refreshedCredentialSecrets];
+        // A wake that Codex reported usage for is metered whether or not it goes on
+        // to publish. Every throw below this point used to drop that spend on the
+        // floor, so a breached ceiling, an expired wall clock, a non-zero exit, or
+        // a turn judged unpublishable all cost money the ledger never saw.
+        const failure = promptFailure ?? cleanupFailure;
+        if (failure !== undefined) {
+            await publishTurnUsage(this.options.onTurnUsage, turnUsage ?? meter.reported(), failedTurnOutcome(failure));
+            // A wake that failed still made model requests and still paid for them,
+            // so its per-request shape is measured on exactly the paths its spend is.
+            await instrument();
+        }
+        if (promptFailure !== undefined) {
+            const authRejection = this.options.engine === "grok" ? asGrokAuthenticationRejected(promptFailure) : undefined;
+            if (authRejection !== undefined)
+                throw new GrokSubscriptionAuthenticationRejectedError(cleanupFailure === undefined ? undefined : redactCredentialError(cleanupFailure, finalSecrets));
+            if (cleanupFailure !== undefined)
+                throw redactCredentialError(cleanupFailure, finalSecrets);
+            throw redactCredentialError(promptFailure, finalSecrets);
+        }
+        if (cleanupFailure !== undefined) {
+            if (this.options.engine === "grok" && asGrokAuthenticationRejected(cleanupFailure) !== undefined) {
+                throw new GrokSubscriptionAuthenticationRejectedError();
+            }
+            throw redactCredentialError(cleanupFailure, finalSecrets);
+        }
+        if (output === undefined)
+            return;
+        output = redactCredentialText(output, finalSecrets, 64 * 1024);
+        for (const listener of this.listeners)
+            listener({
+                type: "turn_end",
+                message: {
+                    role: "assistant", content: [{ type: "text", text: output }], api: "openai-completions", provider: "openai", model: "cli",
+                    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+                    stopReason: "stop", timestamp: Date.now()
+                }, toolResults: []
+            });
+        // Meter only after the turn has published.
+        await publishTurnUsage(this.options.onTurnUsage, turnUsage ?? meter.reported(), { status: "completed" });
+        await instrument();
+    }
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+        this.disposePromise ??= this.quiesce();
+    }
+    async disposeAsync() {
+        this.dispose();
+        await this.disposePromise;
+    }
+    ensureLive() {
+        if (this.disposed)
+            throw new Error("CLI session is disposed");
+    }
+    async quiesce() {
+        let cleanupFailure;
+        cleanupFailure = await captureCleanup(cleanupFailure, async () => { if (this.activeChild !== undefined)
+            await terminateChild(this.activeChild); });
+        this.activeBrokerTurn?.abort();
+        cleanupFailure = await captureCleanup(cleanupFailure, () => Promise.all([...this.setupChildren].map((child) => terminateChild(child))).then(() => undefined));
+        cleanupFailure = await captureCleanup(cleanupFailure, async () => { await this.mcpRegistration?.close(); });
+        cleanupFailure = await captureCleanup(cleanupFailure, async () => { await this.activeMount?.close(); });
+        if (cleanupFailure !== undefined)
+            throw cleanupFailure;
+    }
+}
+export const createCliSessionFactory = (options) => async (input) => {
+    if (input.cwd === undefined)
+        throw new Error("CLI session cwd is required");
+    return {
+        session: new CliSession(options, {
+            cwd: input.cwd,
+            customTools: input.customTools,
+            daimonSecretEnvironmentNames: input.daimonSecretEnvironmentNames,
+            runtimeHomePath: input.runtimeHomePath
+        })
+    };
+};
+export { runEngine, runEngineDetailed } from "./cliEngineRun.js";
+export { renderAgyArgs, renderCodexArgs, spawnEngine } from "./cliEngineSpawn.js";

package/dist/pi/cliTurnMetering.d.ts

@@ -0,0 +1,60 @@
+import type { AgyTurnUsage } from "./agyHeadlessResult.js";
+import { type CodexHeadlessTurn, type CodexTurnUsage } from "./codexHeadlessResult.js";
+import type { TurnUsageOutcome } from "../runtime/turnUsageLedger.js";
+/**
+ * What one CLI turn owes the usage ledger, and the rules for when it owes
+ * nothing.
+ *
+ * A wake that fails spends exactly the money a wake that publishes spends, so
+ * the engine's reported usage is metered on both paths and the row's outcome
+ * says which. A Codex wake that breached its per-wake token ceiling used to
+ * record nothing at all: the tokens it burned survived only as a number
+ * interpolated into the error message, and a timeout, a killed child, or a
+ * non-zero exit lost the figure entirely.
+ *
+ * The counterweight is that a number is never invented. A zero-filled row is
+ * byte-identical to a real zero and would silently poison every aggregate
+ * computed over the ledger, so "the engine reported nothing" stays absent.
+ */
+export type CliTurnMeter = Readonly<{
+    /** Wire this to `readChild`'s `onCodexTurnCompleted`. */
+    observeCodexTurnCompleted: (usage: CodexTurnUsage | undefined) => void;
+    /**
+     * The usage Codex reported mid-stream, for a wake that never reached its
+     * decoder.
+     *
+     * Trustworthy only under `decodeCodexHeadlessTurn`'s own rule: exactly one
+     * `turn.completed` frame. Codex may omit, repeat, or follow that frame with
+     * another, and two completions leave no defensible answer for which one the
+     * wake actually spent — so this declines rather than guessing, and no frame
+     * at all means nothing was reported and nothing is written.
+     */
+    reported: () => CodexTurnUsage | undefined;
+}>;
+export declare const createCliTurnMeter: () => CliTurnMeter;
+/**
+ * A turn Codex reported usage for but that the decoder refuses to publish is
+ * still a turn that spent tokens. Tagging the rejection is what lets the
+ * ledger row name why the wake failed instead of matching on message prose.
+ */
+export declare const decodeCodexTurn: (output: string) => CodexHeadlessTurn;
+/** The failed row's marker, named by the bound that actually fired. */
+export declare const failedTurnOutcome: (failure: unknown) => TurnUsageOutcome;
+/**
+ * Advisory: metering never fails, delays, or rewrites the wake it describes —
+ * the same ordering rule the Grok engine broker states in
+ * `finishBrokerTurnWithUsage`.
+ */
+export declare const publishTurnUsage: (sink: ((usage: AgyTurnUsage | CodexTurnUsage, outcome: TurnUsageOutcome) => Promise<void>) | undefined, usage: AgyTurnUsage | CodexTurnUsage | undefined, outcome: TurnUsageOutcome) => Promise<void>;
+/**
+ * Advisory per-request instrumentation, under the same ordering rule as
+ * {@link publishTurnUsage}: it never fails, delays, or rewrites the wake it
+ * describes.
+ *
+ * No thread id means Codex never announced one — an engine that is not Codex,
+ * a child killed before its first frame, or a future stream that renamed the
+ * event. Nothing is written in that case, because the alternative is guessing
+ * which rollout on disk belongs to this wake.
+ */
+export declare const publishTurnRequests: (sink: ((threadId: string) => Promise<void>) | undefined, threadId: string | undefined) => Promise<void>;
+//# sourceMappingURL=cliTurnMetering.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliTurnMetering.d.ts","sourceRoot":"","sources":["../../src/pi/cliTurnMetering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAA2B,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAChH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,yDAAyD;IACzD,yBAAyB,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;IACvE;;;;;;;;;OASG;IACH,QAAQ,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;CAC5C,CAAC,CAAC;AAEH,eAAO,MAAM,kBAAkB,QAAO,YAUrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,iBAGhD,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,GAAI,SAAS,OAAO,KAAG,gBACwB,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACtG,OAAO,YAAY,GAAG,cAAc,GAAG,SAAS,EAChD,SAAS,gBAAgB,KACxB,OAAO,CAAC,IAAI,CAGd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACvD,UAAU,MAAM,GAAG,SAAS,KAC3B,OAAO,CAAC,IAAI,CAGd,CAAC"}

package/dist/pi/cliTurnMetering.js

@@ -0,0 +1,60 @@
+import { cliChildFailureReason, tagCliChildFailure } from "./cliChildOutput.js";
+import { decodeCodexHeadlessTurn } from "./codexHeadlessResult.js";
+export const createCliTurnMeter = () => {
+    let usage;
+    let completions = 0;
+    return {
+        observeCodexTurnCompleted: (reported) => {
+            completions += 1;
+            if (reported !== undefined)
+                usage = reported;
+        },
+        reported: () => (completions === 1 ? usage : undefined)
+    };
+};
+/**
+ * A turn Codex reported usage for but that the decoder refuses to publish is
+ * still a turn that spent tokens. Tagging the rejection is what lets the
+ * ledger row name why the wake failed instead of matching on message prose.
+ */
+export const decodeCodexTurn = (output) => {
+    try {
+        return decodeCodexHeadlessTurn(output);
+    }
+    catch (error) {
+        throw tagCliChildFailure(error, "turn_rejected");
+    }
+};
+/** The failed row's marker, named by the bound that actually fired. */
+export const failedTurnOutcome = (failure) => ({ status: "failed", reason: cliChildFailureReason(failure) ?? "unknown" });
+/**
+ * Advisory: metering never fails, delays, or rewrites the wake it describes —
+ * the same ordering rule the Grok engine broker states in
+ * `finishBrokerTurnWithUsage`.
+ */
+export const publishTurnUsage = async (sink, usage, outcome) => {
+    if (usage === undefined)
+        return;
+    try {
+        await sink?.(usage, outcome).catch(() => undefined);
+    }
+    catch { /* advisory */ }
+};
+/**
+ * Advisory per-request instrumentation, under the same ordering rule as
+ * {@link publishTurnUsage}: it never fails, delays, or rewrites the wake it
+ * describes.
+ *
+ * No thread id means Codex never announced one — an engine that is not Codex,
+ * a child killed before its first frame, or a future stream that renamed the
+ * event. Nothing is written in that case, because the alternative is guessing
+ * which rollout on disk belongs to this wake.
+ */
+export const publishTurnRequests = async (sink, threadId) => {
+    if (threadId === undefined)
+        return;
+    try {
+        await sink?.(threadId).catch(() => undefined);
+    }
+    catch { /* advisory */ }
+};

package/dist/pi/codexFilesystemRules.d.ts

@@ -0,0 +1,3 @@
+/** Codex mounts deny roots read-only; a second deny below one cannot create parents. */
+export declare function codexFilesystemRules(protectedPaths: readonly string[], readablePaths: readonly string[], workspacePath?: string): Record<string, "read" | "deny">;
+//# sourceMappingURL=codexFilesystemRules.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codexFilesystemRules.d.ts","sourceRoot":"","sources":["../../src/pi/codexFilesystemRules.ts"],"names":[],"mappings":"AAIA,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,SAAS,MAAM,EAAE,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,aAAa,CAAC,EAAE,MAAM,GAC1F,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAqBjC"}

package/dist/pi/codexFilesystemRules.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+/** Codex mounts deny roots read-only; a second deny below one cannot create parents. */
+export function codexFilesystemRules(protectedPaths, readablePaths, workspacePath) {
+    const explicit = new Map();
+    // Agent roots are canonical, but shared acceptance paths may contain `..`
+    // or trailing separators. Compare the same absolute locations Codex uses.
+    for (const readablePath of readablePaths)
+        explicit.set(path.resolve(readablePath), "read");
+    for (const protectedPath of protectedPaths)
+        explicit.set(path.resolve(protectedPath), "deny");
+    const effective = new Map([
+        ...(workspacePath === undefined ? [] : [[path.resolve(workspacePath), "write"]]),
+        ...explicit
+    ]);
+    return Object.fromEntries([...explicit].filter(([target, permission]) => {
+        if (permission !== "deny")
+            return true;
+        let ancestor = path.dirname(target);
+        while (ancestor !== target) {
+            const inherited = effective.get(ancestor);
+            if (inherited !== undefined)
+                return inherited !== "deny";
+            target = ancestor;
+            ancestor = path.dirname(target);
+        }
+        return true;
+    }));
+}

package/dist/pi/codexHeadlessResult.d.ts

@@ -0,0 +1,68 @@
+type JsonRecord = Readonly<Record<string, unknown>>;
+/**
+ * Token accounting for one Codex turn, from the terminal frame emitted by
+ * `codex exec --json`:
+ *
+ *     {"type":"turn.completed","usage":{"input_tokens":…,
+ *       "cached_input_tokens":…,"cache_write_input_tokens":…,
+ *       "output_tokens":…,"reasoning_output_tokens":…}}
+ *
+ * Codex's reconciled session total proves `cached_input_tokens` is a subset of
+ * `input_tokens`: total is `input + output`, unlike AGY's disjoint cache-read
+ * bucket. Adding cacheRead would over-count every cached turn. Likewise,
+ * `reasoning_output_tokens` is a subset of `output_tokens`; it is read only to
+ * validate that relationship, never added. Codex reports cache writes, but no
+ * cost, so `cacheWrite` is measured while `notionalUsd: 0` means absent, not
+ * free. `calls` counts completed command/MCP tools; Codex exposes no AGY-like
+ * model-step count, so this is explicitly a tool-call count.
+ */
+export type CodexTurnUsage = Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+    calls: number;
+    notionalUsd: number;
+    complete: boolean;
+}>;
+export type CodexHeadlessTurn = Readonly<{
+    text: string;
+    usage?: CodexTurnUsage;
+}>;
+/**
+ * Advisory usage decoding: an absent or malformed block is `undefined`, never
+ * a failed published turn and never a zero-filled record. Every field must be
+ * a non-negative safe integer because a substituted zero is byte-identical to
+ * a real zero. `complete` requires a non-zero derived total and valid subset
+ * relationships. As with AGY, every emitted count remains a lower bound.
+ */
+export declare const decodeCodexTurnUsage: (frame: JsonRecord, calls: number) => CodexTurnUsage | undefined;
+/**
+ * Decode Codex's NDJSON stream without mistaking tool/progress items for the
+ * reply. Unknown envelopes and item types are skipped because Codex owns the
+ * vocabulary and a future frame must not fail a turn that published.
+ * A Codex turn that spent subscription money and produced a reply must reach
+ * the organization: uncertainty about accounting degrades to `usage:
+ * undefined` and never discards publishable text. Unlike AGY's stricter
+ * envelope, Codex may omit, repeat, or follow `turn.completed` with another
+ * frame, so only exactly one completion frame supplies trustworthy usage.
+ *
+ * Success is decided from the terminal frame, not from whether a reply was
+ * published: `engineDispatcher.ts`'s runtime envelope tells every agent its
+ * terminal response is a private note to the runtime, not an outward
+ * message, and that it may "leave it empty". A `turn.completed` with no
+ * `agent_message` is therefore a sanctioned silent success — `text: ""`,
+ * never a thrown failure — and its usage still reaches the ledger exactly as
+ * a spoken turn's would; do not reinstate throwing on empty text, it would
+ * both misreport a clean turn as failed and drop its usage from the ledger
+ * silently. Only `turn.failed` with no reply already published, or a stream
+ * with neither terminal frame at all (a truncated or killed child), reject
+ * the turn; the latter gets its own detail string so a genuinely truncated
+ * stream is never confused with a legitimately silent one.
+ */
+export declare const decodeCodexHeadlessTurn: (output: string) => CodexHeadlessTurn;
+/** Text-only view of {@link decodeCodexHeadlessTurn}, for callers that do not meter. */
+export declare const decodeCodexHeadlessResult: (output: string) => string;
+export {};
+//# sourceMappingURL=codexHeadlessResult.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codexHeadlessResult.d.ts","sourceRoot":"","sources":["../../src/pi/codexHeadlessResult.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAQpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,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,iBAAiB,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,cAAc,CAAA;CAAE,CAAC,CAAC;AA0BnF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,UAAU,EAAE,OAAO,MAAM,KAAG,cAAc,GAAG,SAmBxF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,MAAM,KAAG,iBAiCxD,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAA8C,CAAC"}