@noopolis/daimon 0.1.2 → 0.2.0

package/dist/pi/agyHeadlessResult.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Token accounting for one AGY turn, as the engine itself reported it.
+ *
+ * Same shape and the same discipline as {@link import("./grokHeadlessResult.js").GrokTurnUsage},
+ * but AGY's envelope is *not* Grok's. Field provenance is the terminal frame of
+ * `agy --print … --output-format stream-json`:
+ *
+ *     {"event":"result","result":{ "status":"SUCCESS", "response":"…",
+ *       "num_turns":1,
+ *       "usage":{"input_tokens":…, "output_tokens":…,
+ *                "thinking_tokens":…, "cache_read_tokens":…, "total_tokens":…}}}
+ *
+ * Differences from Grok that this decoder exists to get right:
+ *
+ * - the prompt-side cache bucket is `cache_read_tokens`, **not**
+ *   `cache_read_input_tokens`;
+ * - there is no `cache_creation_input_tokens` bucket at all, so `cacheWrite` is
+ *   structurally absent and recorded as `0` — absent, not measured-as-zero;
+ * - there is no `total_cost_usd`, so `notionalUsd` is `0` for the same reason;
+ * - `thinking_tokens` has no Grok equivalent and is a **subset** of
+ *   `output_tokens`, not a disjoint bucket. The captured plain turn is
+ *   `input 13,722 + output 74 = 13,796 = total_tokens` with
+ *   `thinking_tokens: 73`, so adding it would double-count reasoning tokens.
+ *   It is therefore read only to be ignored;
+ * - AGY supplies its own `total_tokens`, which is cross-checked rather than
+ *   trusted (see {@link decodeAgyTurnUsage});
+ * - `status: "SUCCESS"` replaces Grok's `subtype`/`is_error` pair.
+ *
+ * The terminal frame's `usage` is the sum over the turn's model steps, not the
+ * last step's: the captured tool turn sums three `step_update` frames
+ * (14,579 + 15,079 + 15,279 input) into `input_tokens: 44,937`. Reading a
+ * `step_update` would under-report every tool-using wake.
+ */
+export type AgyTurnUsage = Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+    calls: number;
+    notionalUsd: number;
+    complete: boolean;
+}>;
+export type AgyHeadlessTurn = Readonly<{
+    text: string;
+    usage?: AgyTurnUsage;
+}>;
+/**
+ * Decode AGY's `stream-json` NDJSON without treating a progress frame as a
+ * reply, and extract the turn's own token accounting from the same frame.
+ *
+ * Frames before the terminal one are `{"event":"init"|"step_update", …}`.
+ * Unrecognized `event` values are skipped rather than rejected: AGY owns this
+ * stream and a frame kind added later must not fail a turn that published.
+ * The terminal `result` frame must be the last line, exactly as with Grok.
+ */
+export declare const decodeAgyHeadlessTurn: (output: string) => AgyHeadlessTurn;
+/** Text-only view of {@link decodeAgyHeadlessTurn}, for callers that do not meter. */
+export declare const decodeAgyHeadlessResult: (output: string) => string;
+//# sourceMappingURL=agyHeadlessResult.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agyHeadlessResult.d.ts","sourceRoot":"","sources":["../../src/pi/agyHeadlessResult.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,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,eAAe,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;AAqD/E;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,KAAG,eAkBtD,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,GAAI,QAAQ,MAAM,KAAG,MAA4C,CAAC"}

package/dist/pi/agyHeadlessResult.js

@@ -0,0 +1,95 @@
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const invalidResult = (detail) => new Error(`AGY CLI returned no publishable terminal response: ${detail}`);
+/**
+ * The three token buckets AGY emits on `result.usage`. All three 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_tokens"];
+const tokenCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+/**
+ * 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` follows exactly the honesty rule the Grok decoder states: AGY's
+ * envelope has no marker for incomplete or absent usage either, so an all-zero
+ * block reads as "unknown", not "free". It cannot catch a *partially*
+ * zero-filled turn, so every count this decoder produces is a lower bound.
+ *
+ * AGY additionally reports its own `total_tokens`. Neither side is trusted
+ * blindly: the derived sum `input + cacheRead + output` is compared against it,
+ * `total` is the larger of the two so a reconciliation failure can never
+ * under-report, and any disagreement clears `complete` so the record is
+ * rendered as an incomplete turn rather than a verified count. A `total_tokens`
+ * that is not a non-negative safe integer rejects the block outright, because
+ * an unreadable total is a total that cannot be reconciled.
+ */
+const decodeAgyTurnUsage = (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] = counts;
+    const reported = usage.total_tokens === undefined ? undefined : tokenCount(usage.total_tokens);
+    if (usage.total_tokens !== undefined && reported === undefined)
+        return undefined;
+    const derived = input + cacheRead + output;
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite: 0,
+        total: reported === undefined ? derived : Math.max(derived, reported),
+        calls: tokenCount(result.num_turns) ?? 0,
+        notionalUsd: 0,
+        complete: derived > 0 && (reported === undefined || reported === derived)
+    };
+};
+/**
+ * Decode AGY's `stream-json` NDJSON without treating a progress frame as a
+ * reply, and extract the turn's own token accounting from the same frame.
+ *
+ * Frames before the terminal one are `{"event":"init"|"step_update", …}`.
+ * Unrecognized `event` values are skipped rather than rejected: AGY owns this
+ * stream and a frame kind added later must not fail a turn that published.
+ * The terminal `result` frame must be the last line, exactly as with Grok.
+ */
+export const decodeAgyHeadlessTurn = (output) => {
+    const lines = output.split(/\r?\n/).filter((line) => line.length > 0);
+    if (lines.length === 0)
+        throw invalidResult("empty stream");
+    let result;
+    for (const [index, line] of lines.entries()) {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            throw invalidResult("invalid JSON");
+        }
+        if (!isRecord(frame) || typeof frame.event !== "string")
+            throw invalidResult("invalid event");
+        if (frame.event !== "result")
+            continue;
+        if (index !== lines.length - 1)
+            throw invalidResult("non-terminal result");
+        if (!isRecord(frame.result))
+            throw invalidResult("invalid result event");
+        result = frame.result;
+    }
+    if (result === undefined)
+        throw invalidResult("no result frame");
+    if (result.status !== "SUCCESS")
+        throw invalidResult("unsuccessful result");
+    if (typeof result.response !== "string" || result.response.trim().length === 0)
+        throw invalidResult("empty response");
+    const usage = decodeAgyTurnUsage(result);
+    return usage === undefined ? { text: result.response.trim() } : { text: result.response.trim(), usage };
+};
+/** Text-only view of {@link decodeAgyHeadlessTurn}, for callers that do not meter. */
+export const decodeAgyHeadlessResult = (output) => decodeAgyHeadlessTurn(output).text;

package/dist/pi/cliChildOutput.d.ts

@@ -0,0 +1,67 @@
+import type { ChildProcess } from "node:child_process";
+import type { TurnUsageFailureReason } from "../runtime/turnUsageLedger.js";
+import { type CodexTurnUsage } from "./codexHeadlessResult.js";
+/** Maximum assistant reply bytes retained from stdout. */
+export declare const CLI_ENGINE_MAX_OUTPUT_BYTES: number;
+/** Diagnostic bytes retained from stderr for a failed child: its head and its tail together. */
+export declare const CLI_ENGINE_MAX_DIAGNOSTIC_BYTES = 768;
+export declare const tagCliChildFailure: <T>(error: T, reason: TurnUsageFailureReason) => T;
+export declare const cliChildFailureReason: (error: unknown) => TurnUsageFailureReason | undefined;
+/**
+ * One bounded window over a failed child's own output: its head AND its tail,
+ * with an explicit marker naming the bytes elided between them.
+ *
+ * A pure tail is the wrong end for the process this exists for. A worker that
+ * dies early prints its error first and then echoes its own input, so the tail
+ * is the echo: one live brokered turn reported 512 bytes of its own prompt
+ * read back, with the actual error already off the front and discarded. Both
+ * ends cost the same window, and the marker is the one oversized tool results
+ * already use (`toolResultSpill.ts`), so a reader meets one shape everywhere.
+ *
+ * The marker is paid for out of the same budget — it is sized against the
+ * largest count it could carry — so the result never exceeds `maxBytes`, and
+ * output that fits is returned byte-identical with no marker at all.
+ */
+export declare const boundedDiagnosticWindow: (value: string, maxBytes: number) => string;
+export declare const readChild: (child: ChildProcess, timeoutMs: number | undefined, secretValues: readonly string[], options?: Readonly<{
+    failureClassifier?: (diagnostic: string) => Error | undefined;
+    retainNdjson?: "codex";
+    retainStdoutTail?: boolean;
+    /** Overrides the generic wall-clock-timeout message so the caller can name which bound was hit. */
+    timeoutErrorMessage?: string;
+    /**
+     * Per-wake token ceiling for a Codex turn (`retainNdjson: "codex"` only).
+     * Codex's `--json` stream reports usage exactly once, on `turn.completed`
+     * — there is no incremental total to watch mid-turn — so this is
+     * enforced at the earliest and only moment the crossing is observable:
+     * the instant that frame is parsed off the stream. Crossing it kills the
+     * child immediately (rather than letting an over-budget turn resolve as
+     * a normal success) and fails the wake with a bound-named error.
+     */
+    codexTokenCeiling?: number;
+    /**
+     * Called once per parsed `turn.completed` frame (`retainNdjson: "codex"`
+     * only), with that frame's decoded usage — or `undefined` when the usage
+     * block is absent or malformed, which is never substituted with zeros.
+     *
+     * This is the only point at which a wake that is about to be killed — by
+     * the ceiling, by the wall clock, or by a non-zero exit — can still hand
+     * over what Codex reported it spent. Every path downstream of here either
+     * rejects or discards the stream, which is how a breached wake's usage
+     * used to survive only inside an error message.
+     */
+    onCodexTurnCompleted?: (usage: CodexTurnUsage | undefined) => void;
+    /**
+     * Called with the thread id from Codex's `thread.started` frame
+     * (`retainNdjson: "codex"` only), the first line of every `codex exec
+     * --json` stream — verified live against codex-cli 0.153.4:
+     * `{"type":"thread.started","thread_id":"01a076d3-…"}`.
+     *
+     * That id is the only key that ties this wake to the rollout Codex writes
+     * under `$CODEX_HOME/sessions/**`, where the per-model-request accounting
+     * lives. The frame stays out of the retained stream: the decoder's
+     * vocabulary and the retained-output budget are unchanged by reading it.
+     */
+    onCodexThreadStarted?: (threadId: string) => void;
+}>) => Promise<string>;
+//# sourceMappingURL=cliChildOutput.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliChildOutput.d.ts","sourceRoot":"","sources":["../../src/pi/cliChildOutput.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAGrF,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,QAAY,CAAC;AACrD,gGAAgG;AAChG,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAanD,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,QAAQ,sBAAsB,KAAG,CAOhF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,OAAO,OAAO,KAAG,sBAAsB,GAAG,SAGjE,CAAC;AAMhB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,MAQzE,CAAC;AAUF,eAAO,MAAM,SAAS,GACpB,OAAO,YAAY,EACnB,WAAW,MAAM,GAAG,SAAS,EAC7B,cAAc,SAAS,MAAM,EAAE,EAC/B,UAAS,QAAQ,CAAC;IAChB,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,KAAK,GAAG,SAAS,CAAC;IAC9D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mGAAmG;IACnG,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;IACnE;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD,CAAM,KACN,OAAO,CAAC,MAAM,CAmLf,CAAC"}

package/dist/pi/cliChildOutput.js

@@ -0,0 +1,269 @@
+import { redactCredentialText } from "../core/credentialRedaction.js";
+import { headUtf8, tailUtf8 } from "../runtime/toolResultSpill.js";
+import { decodeCodexTurnUsage } from "./codexHeadlessResult.js";
+import { terminateChild, trackCliChild } from "./cliProcess.js";
+/** Maximum assistant reply bytes retained from stdout. */
+export const CLI_ENGINE_MAX_OUTPUT_BYTES = 64 * 1024;
+/** Diagnostic bytes retained from stderr for a failed child: its head and its tail together. */
+export const CLI_ENGINE_MAX_DIAGNOSTIC_BYTES = 768;
+const CLI_ENGINE_FAILURE_SCAN_CHARS = 256;
+/**
+ * Which bound or condition failed a wake, carried on the error object itself.
+ *
+ * The caller needs this to label the usage row a failed wake still owes the
+ * ledger, and matching on the message text would make that label depend on
+ * prose. The tag is a non-enumerable symbol property, so it never widens the
+ * error's serialized form and never reaches a diagnostic string.
+ */
+const CLI_CHILD_FAILURE_REASON = Symbol("daimon.cliChildFailureReason");
+export const tagCliChildFailure = (error, reason) => {
+    if (!(error instanceof Error))
+        return error;
+    // Labelling a failure must never become a second failure: a frozen or sealed
+    // error simply goes untagged and its row reads `unknown`.
+    try {
+        Object.defineProperty(error, CLI_CHILD_FAILURE_REASON, { configurable: true, enumerable: false, value: reason, writable: true });
+    }
+    catch { /* the reason is advisory; the failure it describes is not */ }
+    return error;
+};
+export const cliChildFailureReason = (error) => error instanceof Error
+    ? error[CLI_CHILD_FAILURE_REASON]
+    : undefined;
+const redactChildOutput = (value, secretValues) => {
+    return redactCredentialText(value, secretValues, CLI_ENGINE_MAX_OUTPUT_BYTES);
+};
+/**
+ * One bounded window over a failed child's own output: its head AND its tail,
+ * with an explicit marker naming the bytes elided between them.
+ *
+ * A pure tail is the wrong end for the process this exists for. A worker that
+ * dies early prints its error first and then echoes its own input, so the tail
+ * is the echo: one live brokered turn reported 512 bytes of its own prompt
+ * read back, with the actual error already off the front and discarded. Both
+ * ends cost the same window, and the marker is the one oversized tool results
+ * already use (`toolResultSpill.ts`), so a reader meets one shape everywhere.
+ *
+ * The marker is paid for out of the same budget — it is sized against the
+ * largest count it could carry — so the result never exceeds `maxBytes`, and
+ * output that fits is returned byte-identical with no marker at all.
+ */
+export const boundedDiagnosticWindow = (value, maxBytes) => {
+    const total = Buffer.byteLength(value, "utf8");
+    if (total <= maxBytes)
+        return value;
+    const budget = Math.max(0, maxBytes - Buffer.byteLength(elisionMarker(total), "utf8"));
+    const head = headUtf8(value, Math.floor(budget / 2));
+    const tail = tailUtf8(value, budget - Buffer.byteLength(head, "utf8"));
+    const elided = total - Buffer.byteLength(head, "utf8") - Buffer.byteLength(tail, "utf8");
+    return `${head}${elisionMarker(elided)}${tail}`;
+};
+const elisionMarker = (elided) => `[… ${elided} bytes elided …]`;
+const childDiagnostic = (stdout, stderr, secretValues) => {
+    const output = stderr.trim().length > 0 ? stderr : stdout;
+    const redacted = redactCredentialText(output, secretValues, Number.MAX_SAFE_INTEGER).trim();
+    const bounded = boundedDiagnosticWindow(redacted, CLI_ENGINE_MAX_DIAGNOSTIC_BYTES).trim();
+    return bounded.length > 0 ? `: ${bounded}` : "";
+};
+export const readChild = (child, timeoutMs, secretValues, options = {}) => new Promise((resolve, reject) => {
+    trackCliChild(child);
+    const stdout = [];
+    let stdoutTail = Buffer.alloc(0);
+    let droppingStdoutLine = false;
+    // Both ends of stderr, retained as it streams: the head frozen once it is
+    // full, the tail sliding. A single sliding tail dropped the head at capture
+    // time, which is where the cause of an early death lives — no later window
+    // can recover what was never kept.
+    let stderrHead = Buffer.alloc(0);
+    let stderrTail = Buffer.alloc(0);
+    let stderrBytes = 0;
+    let stdoutBytes = 0;
+    let stdoutRemainder = Buffer.alloc(0);
+    let droppingNdjsonLine = false;
+    let ndjsonCalls = 0;
+    let settled = false;
+    let cleanupStarted = false;
+    let classifiedFailure;
+    let failureScanTail = "";
+    /**
+     * Each retained end carries its reported share PLUS one whole secret, which
+     * is the invariant that keeps exact redaction exact: a secret that reaches
+     * the reported window can extend at most its own length past that window's
+     * cut, so retaining that much more on each side means the redactor always
+     * sees the secret whole. Halving one shared budget instead broke it — a
+     * 2000-byte secret was cut in the middle and its tail fragment
+     * (`…qqq-secret-end`) reached the diagnostic verbatim.
+     */
+    const stderrSecretAllowance = Math.max(0, ...secretValues.map((secret) => Buffer.byteLength(secret, "utf8")));
+    const stderrHeadBytes = Math.floor(CLI_ENGINE_MAX_DIAGNOSTIC_BYTES / 2) + stderrSecretAllowance;
+    const stderrTailBytes = CLI_ENGINE_MAX_DIAGNOSTIC_BYTES - Math.floor(CLI_ENGINE_MAX_DIAGNOSTIC_BYTES / 2) + stderrSecretAllowance;
+    const settle = (action) => {
+        if (settled)
+            return;
+        settled = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        action();
+    };
+    const abort = (error) => {
+        if (cleanupStarted)
+            return;
+        cleanupStarted = true;
+        void terminateChild(child).then(() => settle(() => reject(error)), (cleanupError) => settle(() => reject(cleanupError instanceof Error ? cleanupError : error)));
+    };
+    const classifyFailure = (chunk) => {
+        if (classifiedFailure !== undefined || options.failureClassifier === undefined)
+            return;
+        const diagnostic = `${failureScanTail}${chunk.toString("utf8")}`;
+        classifiedFailure = options.failureClassifier(diagnostic);
+        failureScanTail = diagnostic.slice(-CLI_ENGINE_FAILURE_SCAN_CHARS);
+    };
+    const retainStdout = (chunk) => {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        classifyFailure(value);
+        if (options.retainNdjson !== undefined) {
+            let incoming = value;
+            if (droppingNdjsonLine) {
+                const newline = incoming.indexOf(0x0a);
+                if (newline < 0)
+                    return;
+                droppingNdjsonLine = false;
+                incoming = incoming.subarray(newline + 1);
+            }
+            stdoutRemainder = Buffer.concat([stdoutRemainder, incoming]);
+            let newline;
+            while ((newline = stdoutRemainder.indexOf(0x0a)) >= 0) {
+                const line = stdoutRemainder.subarray(0, newline).toString("utf8");
+                stdoutRemainder = Buffer.from(stdoutRemainder.subarray(newline + 1));
+                let frame;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+                        frame = parsed;
+                }
+                catch { /* decoder reports malformed retained protocol lines */ }
+                if (frame === undefined) {
+                    stdout.push(Buffer.from(`${line}\n`));
+                    continue;
+                }
+                if (frame.type === "thread.started" && typeof frame.thread_id === "string") {
+                    options.onCodexThreadStarted?.(frame.thread_id);
+                    continue;
+                }
+                const item = typeof frame.item === "object" && frame.item !== null && !Array.isArray(frame.item) ? frame.item : undefined;
+                if (frame.type === "item.completed" && (item?.type === "command_execution" || item?.type === "mcp_tool_call")) {
+                    ndjsonCalls += 1;
+                    stdout.push(Buffer.from(`${JSON.stringify({ type: frame.type, item: { type: item.type } })}\n`));
+                }
+                else if ((frame.type === "item.completed" && item?.type === "agent_message") || frame.type === "turn.completed" || frame.type === "turn.failed") {
+                    if (frame.type === "turn.completed") {
+                        // Decode and publish first, kill second: the ceiling breach is the
+                        // one path guaranteed to destroy this stream, so the accounting
+                        // has to leave the reader before the child does.
+                        const usage = decodeCodexTurnUsage(frame, ndjsonCalls);
+                        options.onCodexTurnCompleted?.(usage);
+                        if (options.codexTokenCeiling !== undefined && usage !== undefined && usage.total >= options.codexTokenCeiling) {
+                            abort(tagCliChildFailure(new Error(`Codex wake exceeded its ${options.codexTokenCeiling}-token per-wake ceiling (turn usage ${usage.total} tokens)`), "token_ceiling"));
+                            return;
+                        }
+                    }
+                    stdout.push(Buffer.from(`${line}\n`));
+                }
+                stdoutBytes = stdout.reduce((total, part) => total + part.length, 0);
+                if (stdoutBytes > CLI_ENGINE_MAX_OUTPUT_BYTES) {
+                    abort(tagCliChildFailure(new Error(`CLI engine output exceeded ${CLI_ENGINE_MAX_OUTPUT_BYTES} bytes`), "output_limit"));
+                    return;
+                }
+            }
+            if (stdoutRemainder.length > CLI_ENGINE_MAX_OUTPUT_BYTES) {
+                const prefix = stdoutRemainder.subarray(0, Math.min(stdoutRemainder.length, 4096)).toString("utf8");
+                if (/"type"\s*:\s*"item\.completed"/u.test(prefix)
+                    && !/"type"\s*:\s*"agent_message"/u.test(prefix)) {
+                    const toolType = prefix.match(/"type"\s*:\s*"(command_execution|mcp_tool_call)"/u)?.[1];
+                    if (toolType !== undefined) {
+                        ndjsonCalls += 1;
+                        stdout.push(Buffer.from(`${JSON.stringify({ type: "item.completed", item: { type: toolType } })}\n`));
+                    }
+                    stdoutRemainder = Buffer.alloc(0);
+                    droppingNdjsonLine = true;
+                }
+                else
+                    abort(tagCliChildFailure(new Error(`CLI engine output exceeded ${CLI_ENGINE_MAX_OUTPUT_BYTES} bytes`), "output_limit"));
+            }
+            return;
+        }
+        if (options.retainStdoutTail === true) {
+            let remainder = value;
+            if (droppingStdoutLine) {
+                const newline = remainder.indexOf(0x0a);
+                if (newline < 0)
+                    return;
+                droppingStdoutLine = false;
+                remainder = remainder.subarray(newline + 1);
+            }
+            const combined = Buffer.concat([stdoutTail, remainder]);
+            if (combined.length <= CLI_ENGINE_MAX_OUTPUT_BYTES) {
+                stdoutTail = combined;
+                return;
+            }
+            const overflow = combined.length - CLI_ENGINE_MAX_OUTPUT_BYTES;
+            if (combined[overflow - 1] === 0x0a) {
+                stdoutTail = Buffer.from(combined.subarray(overflow));
+                return;
+            }
+            const newline = combined.indexOf(0x0a, overflow);
+            stdoutTail = newline < 0 ? Buffer.alloc(0) : Buffer.from(combined.subarray(newline + 1));
+            droppingStdoutLine = newline < 0;
+            return;
+        }
+        stdoutBytes += value.length;
+        if (stdoutBytes > CLI_ENGINE_MAX_OUTPUT_BYTES) {
+            abort(tagCliChildFailure(new Error(`CLI engine output exceeded ${CLI_ENGINE_MAX_OUTPUT_BYTES} bytes`), "output_limit"));
+            return;
+        }
+        stdout.push(value);
+    };
+    const retainStderrWindow = (chunk) => {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        classifyFailure(value);
+        stderrBytes += value.length;
+        if (stderrHead.length < stderrHeadBytes)
+            stderrHead = Buffer.concat([stderrHead, value.subarray(0, stderrHeadBytes - stderrHead.length)]);
+        if (value.length >= stderrTailBytes) {
+            stderrTail = Buffer.from(value.subarray(value.length - stderrTailBytes));
+            return;
+        }
+        const overflow = stderrTail.length + value.length - stderrTailBytes;
+        stderrTail = Buffer.concat([overflow > 0 ? stderrTail.subarray(overflow) : stderrTail, value]);
+    };
+    /**
+     * The retained stderr, reassembled exactly.
+     *
+     * Nothing was elided while the whole output fitted the budget, and then the
+     * two ends overlap: they tile the stream, so dropping the overlap from the
+     * tail rebuilds it byte-identically. Above the budget the ends are joined by
+     * the marker, which names how many bytes never reached this process at all.
+     */
+    const retainedStderr = () => {
+        const elided = stderrBytes - stderrHead.length - stderrTail.length;
+        if (elided <= 0)
+            return Buffer.concat([stderrHead, stderrTail.subarray(stderrHead.length + stderrTail.length - stderrBytes)]).toString("utf8");
+        return `${stderrHead.toString("utf8")}${elisionMarker(elided)}${stderrTail.toString("utf8")}`;
+    };
+    child.stdout?.on("data", retainStdout);
+    child.stderr?.on("data", retainStderrWindow);
+    const timer = timeoutMs === undefined ? undefined : setTimeout(() => abort(tagCliChildFailure(new Error(options.timeoutErrorMessage ?? "CLI engine timed out"), "wake_timeout")), timeoutMs);
+    child.once("error", abort);
+    child.once("close", (code, signal) => {
+        if (cleanupStarted)
+            return;
+        if (options.retainNdjson !== undefined && stdoutRemainder.length > 0)
+            stdout.push(stdoutRemainder);
+        const retainedStdout = options.retainStdoutTail === true ? stdoutTail : Buffer.concat(stdout);
+        if (code === 0) {
+            settle(() => resolve(redactChildOutput(retainedStdout.toString("utf8"), secretValues).trim()));
+            return;
+        }
+        settle(() => reject(tagCliChildFailure(classifiedFailure ?? new Error(`CLI engine exited ${code ?? signal}${childDiagnostic(retainedStdout.toString("utf8"), retainedStderr(), secretValues)}`), "engine_exit")));
+    });
+});

package/dist/pi/cliEngineRun.d.ts

@@ -0,0 +1,16 @@
+import { type CliEngineKind } from "./cliSession.js";
+export interface EngineRunResult {
+    readonly durationMs: number;
+    readonly outputChars: number;
+    readonly promptChars: number;
+    readonly text: string;
+}
+export declare const runEngineDetailed: (engine: CliEngineKind, prompt: string, paths: {
+    readonly workspacePath: string;
+    readonly runtimeHomePath?: string;
+}) => Promise<EngineRunResult>;
+export declare const runEngine: (engine: CliEngineKind, prompt: string, paths: {
+    readonly workspacePath: string;
+    readonly runtimeHomePath?: string;
+}) => Promise<string>;
+//# sourceMappingURL=cliEngineRun.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliEngineRun.d.ts","sourceRoot":"","sources":["../../src/pi/cliEngineRun.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+C,KAAK,aAAa,EAAyB,MAAM,iBAAiB,CAAC;AAEzH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,aAAa,EACrB,QAAQ,MAAM,EACd,OAAO;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3E,OAAO,CAAC,eAAe,CAsBzB,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,QAAQ,aAAa,EACrB,QAAQ,MAAM,EACd,OAAO;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3E,OAAO,CAAC,MAAM,CAA0D,CAAC"}

package/dist/pi/cliEngineRun.js

@@ -0,0 +1,27 @@
+import { AGY_MAX_TOOL_TURNS, createCliSessionFactory } from "./cliSession.js";
+export const runEngineDetailed = async (engine, prompt, paths) => {
+    const startedAt = Date.now();
+    const options = engine === "agy"
+        ? { engine, maxToolTurns: AGY_MAX_TOOL_TURNS, timeoutMs: 180_000 }
+        : { engine };
+    const { session } = await createCliSessionFactory(options)({
+        cwd: paths.workspacePath,
+        runtimeHomePath: paths.runtimeHomePath
+    });
+    let text = "";
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type !== "turn_end")
+            return;
+        if (!("content" in event.message))
+            return;
+        text = Array.isArray(event.message.content)
+            ? event.message.content.filter((entry) => entry.type === "text").map((entry) => entry.text).join("")
+            : event.message.content;
+    });
+    await session.prompt(prompt);
+    unsubscribe();
+    session.dispose();
+    await session.disposeAsync?.();
+    return { durationMs: Date.now() - startedAt, outputChars: text.length, promptChars: prompt.length, text };
+};
+export const runEngine = async (engine, prompt, paths) => (await runEngineDetailed(engine, prompt, paths)).text;

package/dist/pi/cliEngineSpawn.d.ts

@@ -0,0 +1,55 @@
+import { type ChildProcess } from "node:child_process";
+import type { CliEngineOptions, CliSessionInput } from "./cliSession.js";
+export declare const GROK_STRICT_SANDBOX_PROFILE = "strict";
+export declare const renderGrokSandboxArgs: (commandArgs: readonly string[] | undefined, profile: string) => string[];
+/**
+ * Codex's `--json` stream is unconditional: it is the only output shape that
+ * carries `turn.completed.usage`, and an unmetered Codex turn is one whose
+ * subscription cost is invisible. The guarded arguments make this Daimon's
+ * security and metering boundary rather than a caller-controlled format.
+ *
+ * `model`/`reasoningEffort` come from parsed, bounded organization-runtime
+ * config, but are rendered defensively anyway: each is emitted as a single
+ * `--flag=value` argv token (never a bare flag followed by a separate value
+ * token), so a value that itself looks like a flag (e.g. `--sandbox`) can
+ * never be parsed as a second, independent argument — the same shape already
+ * used below for `mcp_servers.daimon.url=`. Omitting both fields leaves Codex's
+ * model defaults unchanged.
+ *
+ * The per-wake MCP server is always enabled and required. Otherwise Codex can
+ * continue a normal turn with only built-in tools after MCP startup fails.
+ * Subscription apps and installed plugins are not caller-declared tools.
+ * Disable their discovery per invocation, including with strict config: the
+ * CLI's defaults can otherwise add them even when user config is ignored.
+ */
+export declare const renderCodexArgs: (options: Pick<CliEngineOptions, "commandArgs" | "model" | "reasoningEffort" | "codexSandbox" | "codexSandboxProtectedPaths" | "codexSandboxReadablePaths">, cwd: string, endpoint: string | undefined, sandbox?: string) => string[];
+export declare const renderCodexPermissionProfile: (profileName: string, protectedPaths: readonly string[], readablePaths?: readonly string[], workspacePath?: string) => string;
+/**
+ * AGY's headless invocation.
+ *
+ * `--output-format stream-json` is unconditional: it is the only shape that
+ * carries `result.usage`, and an AGY turn that is not metered is an AGY turn
+ * whose subscription cost is invisible (see `agyHeadlessResult.ts`).
+ *
+ * `--dangerously-skip-permissions` is required for tools to work at all. AGY's
+ * default headless permission mode is `request-review`, and there is no
+ * reviewer inside a container, so a tool call can never be approved without it;
+ * the live probe that proved AGY's MCP tool calling ran with exactly this flag
+ * and reported `permission_mode: always-proceed`. Every Daimon CLI agent mounts
+ * at least the protected bash tool (`piHarness.ts`), so there is no AGY wake
+ * for which this is unnecessary and no conditional worth forking behavior over.
+ *
+ * SECURITY: the flag also auto-approves AGY's own ~50 built-in tools —
+ * `run_command`, `write_to_file`, the browser tools — none of which Daimon
+ * mediates. Inside the container that is the exposure Codex already has
+ * (`--sandbox danger-full-access`), but unlike Grok there is no kernel-enforced
+ * per-agent profile confining it to this agent's own workspace and runtime
+ * home. `DAIMON_AGY_SANDBOX=1` opts into AGY's own terminal-restricting
+ * sandbox; it is off by default only because its interaction with the MCP
+ * transport could not be verified without spending the operator's subscription
+ * quota, and shipping an unverified default that silently disables every tool
+ * would be worse than shipping the exposure with this note on it.
+ */
+export declare const renderAgyArgs: (options: Pick<CliEngineOptions, "commandArgs" | "timeoutMs">, prompt: string, sandbox?: boolean) => string[];
+export declare const spawnEngine: (options: CliEngineOptions, prompt: string, input: CliSessionInput, endpoint: string | undefined, wakeId?: string) => ChildProcess;
+//# sourceMappingURL=cliEngineSpawn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliEngineSpawn.d.ts","sourceRoot":"","sources":["../../src/pi/cliEngineSpawn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEzE,eAAO,MAAM,2BAA2B,WAAW,CAAC;AAEpD,eAAO,MAAM,qBAAqB,GAChC,aAAa,SAAS,MAAM,EAAE,GAAG,SAAS,EAC1C,SAAS,MAAM,KACd,MAAM,EAAuE,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,IAAI,CAAC,gBAAgB,EAAE,aAAa,GAAG,OAAO,GAAG,iBAAiB,GAAG,cAAc,GAAG,4BAA4B,GAAG,2BAA2B,CAAC,EAC1J,KAAK,MAAM,EACX,UAAU,MAAM,GAAG,SAAS,EAC5B,UAAS,MAA+F,KACvG,MAAM,EAyBR,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,aAAa,MAAM,EACnB,gBAAgB,SAAS,MAAM,EAAE,EACjC,gBAAe,SAAS,MAAM,EAAO,EACrC,gBAAgB,MAAM,KACrB,MAUF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,IAAI,CAAC,gBAAgB,EAAE,aAAa,GAAG,WAAW,CAAC,EAC5D,QAAQ,MAAM,EACd,UAAS,OAAgD,KACxD,MAAM,EAOR,CAAC;AAEF,eAAO,MAAM,WAAW,GACtB,SAAS,gBAAgB,EACzB,QAAQ,MAAM,EACd,OAAO,eAAe,EACtB,UAAU,MAAM,GAAG,SAAS,EAC5B,SAAS,MAAM,KACd,YAyBF,CAAC"}