@noopolis/daimon 0.1.1 → 0.2.0

package/dist/observability/controlCausal.js

@@ -0,0 +1,107 @@
+import { emitCausalEvent, resolveRunId } from "./causalEvents.js";
+/**
+ * Control-wake causal emitters for root's two wake-acceptance surfaces
+ * (`src/runtime/pi/appControlSource.ts`, root repo, out of scope here):
+ * the operator-only control endpoint and the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`). Both stamp `control.wake.accepted` —
+ * enforcement point #3 in `specs/CAUSAL.md` §"Enforcement points" — but with
+ * different `principal_id` authorities, per the B62 fix (Option B): the
+ * operator endpoint stamps `operator:<name>` (`emitControlWakeAccepted`),
+ * the delivery endpoint stamps the fixed `system:moltnet` authority
+ * (`emitDeliveryWakeAccepted`), never a caller-supplied `from`/agent field.
+ * `control.wake.denied` (`emitControlWakeDenied`) stays operator-only: the
+ * delivery endpoint has no bearer-token deny path to stamp. Root's generated
+ * app calls these directly; this file has no knowledge of HTTP, tokens, or
+ * the request shape, only the causal envelope contract.
+ */
+export const CONTROL_WAKE_ACCEPTED_TYPE = "control.wake.accepted";
+export const CONTROL_WAKE_DENIED_TYPE = "control.wake.denied";
+/**
+ * Principal grammar per `specs/CAUSAL.md` §3 (`^(agent|operator|system):.+`):
+ * an authenticated operator identity, e.g. `operator:control`. Callers must
+ * pass the identity behind the verified bearer token, never a value read
+ * from the request body or model output.
+ */
+export const operatorPrincipalId = (operatorName) => `operator:${operatorName}`;
+/**
+ * Fixed principal for wakes accepted through the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`): the delivering authority itself, never an
+ * identity derived from a caller-supplied `from`/agent field on the request.
+ */
+export const DELIVERY_PRINCIPAL_ID = "system:moltnet";
+/** Deterministic, non-model-derived event id for a control wake acceptance. */
+export const controlWakeAcceptedEventId = (requestId) => `daimon:${requestId}:control.wake.accepted`;
+/** Deterministic, non-model-derived event id for a control wake denial. */
+export const controlWakeDeniedEventId = (requestId) => `daimon:${requestId}:control.wake.denied`;
+/**
+ * Deterministic, non-model-derived event id for a Moltnet-delivered wake
+ * acceptance. Distinct from `controlWakeAcceptedEventId` (own `.delivery.`
+ * segment) so the two paths never collide even if a future caller reused a
+ * `requestId` across both endpoints for the same target.
+ */
+export const deliveryWakeAcceptedEventId = (requestId) => `daimon:${requestId}:delivery.wake.accepted`;
+/**
+ * Stamps `control.wake.accepted` once root's operator-control endpoint has
+ * verified the bearer token and is about to wake `targetAgentId`.
+ * `principal_id` is always `operator:<operatorName>` (the authenticated
+ * operator behind the verified token), never derived from the request body.
+ * `run_id` defaults to `resolveRunId()` like every other daimon emitter.
+ */
+export const emitControlWakeAccepted = (input) => emitCausalEvent({
+    agentId: input.targetAgentId,
+    causeEventIds: input.causeEventIds ?? [],
+    eventId: controlWakeAcceptedEventId(input.requestId),
+    payload: {
+        target_agent_id: input.targetAgentId,
+        wake_kind: input.wakeKind
+    },
+    principalId: operatorPrincipalId(input.operatorName),
+    runId: input.runId ?? resolveRunId(),
+    runtimeHomePath: input.runtimeHomePath,
+    type: CONTROL_WAKE_ACCEPTED_TYPE
+});
+/**
+ * Stamps `control.wake.accepted` once root's Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`) is about to wake `targetAgentId` on behalf
+ * of an inter-agent message. `principal_id` is always the fixed
+ * `DELIVERY_PRINCIPAL_ID` (`system:moltnet`) — the delivering authority —
+ * never derived from a caller-supplied `from`/agent field, and never
+ * `operator:<name>` (that principal is reserved for the operator-only
+ * control endpoint; see `emitControlWakeAccepted`). `run_id` defaults to
+ * `resolveRunId()` like every other daimon emitter.
+ */
+export const emitDeliveryWakeAccepted = (input) => emitCausalEvent({
+    agentId: input.targetAgentId,
+    causeEventIds: input.causeEventIds ?? [],
+    eventId: deliveryWakeAcceptedEventId(input.requestId),
+    payload: {
+        delivered_by: "moltnet",
+        target_agent_id: input.targetAgentId,
+        wake_kind: input.wakeKind
+    },
+    principalId: DELIVERY_PRINCIPAL_ID,
+    runId: input.runId ?? resolveRunId(),
+    runtimeHomePath: input.runtimeHomePath,
+    type: CONTROL_WAKE_ACCEPTED_TYPE
+});
+/**
+ * Stamps `control.wake.denied` when root's operator-control endpoint rejects
+ * a wake request over a missing or invalid bearer token. Deny paths must
+ * never drop silently (see `specs/CAUSAL.md` enforcement point #3 / T5):
+ * every 401 the endpoint returns should carry exactly one of these. As with
+ * `emitControlWakeAccepted`, `principal_id` is always the authenticated
+ * operator identity, never a value read from the request.
+ */
+export const emitControlWakeDenied = (input) => emitCausalEvent({
+    agentId: input.targetAgentId,
+    causeEventIds: input.causeEventIds ?? [],
+    eventId: controlWakeDeniedEventId(input.requestId),
+    payload: {
+        reason: input.reason,
+        target_agent_id: input.targetAgentId
+    },
+    principalId: operatorPrincipalId(input.operatorName),
+    runId: input.runId ?? resolveRunId(),
+    runtimeHomePath: input.runtimeHomePath,
+    type: CONTROL_WAKE_DENIED_TYPE
+});

package/dist/observability/emitCausalFixture.d.ts

@@ -0,0 +1,25 @@
+import { type CausalEvent } from "./causalEvents.js";
+export interface CausalFixtureResult {
+    events: [CausalEvent, CausalEvent];
+    jsonlPath: string;
+}
+export interface RunCausalFixtureOptions {
+    /** Overrides the scratch runtime home; defaults to a fixed `.runtime/` path keyed on `spoof`. */
+    runtimeHomePath?: string;
+    /**
+     * Adversarial mode: the fixture's "wake text" (standing in for untrusted
+     * model/request input) embeds a forged identity claim, but the emitted
+     * `principal_id` on both events must remain the authenticated
+     * `agent:<agentId>` regardless — never the claimed identity. Mirrors the
+     * spoof invariant already covered live in `piHarnessCausal.test.ts`
+     * ("model output cannot set principal_id...").
+     */
+    spoof?: boolean;
+}
+/**
+ * Runs the fixture and returns the two stamped events plus the jsonl path,
+ * without touching `process.stdout`/`process.exitCode` — the CLI entry
+ * point below wraps this for `npm run emit-causal-fixture`.
+ */
+export declare const runCausalFixture: (options?: RunCausalFixtureOptions) => Promise<CausalFixtureResult>;
+//# sourceMappingURL=emitCausalFixture.d.ts.map

package/dist/observability/emitCausalFixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitCausalFixture.d.ts","sourceRoot":"","sources":["../../src/observability/emitCausalFixture.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4E,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0B/H,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAU,UAAS,uBAA4B,KAAG,OAAO,CAAC,mBAAmB,CA0DzG,CAAC"}

package/dist/observability/emitCausalFixture.js

@@ -0,0 +1,98 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { emitTurnInputSubmitted, emitTurnOutputCompleted, resolveRunId, sha256Hex } from "./causalEvents.js";
+/**
+ * Standalone fixture emitter, run via `npm run emit-causal-fixture`
+ * (or `npm run emit-causal-fixture:spoof` for the adversarial mode below).
+ *
+ * Stamps one synthetic `turn.input.submitted` -> `turn.output.completed`
+ * chain into a scratch runtime home under `.runtime/causal-fixture[-spoof]/`,
+ * using the same `causalEvents.ts` functions `turnCausal.ts` uses for real
+ * turns. This is a fixture, not a live engine run: no Pi session, no mneme
+ * recall.
+ *
+ * `principal_id` here is stamped as `agent:<agentId>` directly (rather than
+ * importing `turnCausal.ts`'s `agentPrincipalId` helper) because this file
+ * lives under `src/observability/`, which stays engine-neutral and must not
+ * import `src/pi/` implementation details (see this folder's `AGENTS.md`).
+ * The value is the same grammar (`specs/CAUSAL.md` §3) either way.
+ *
+ * Exact invocation contract for a future cross-repo conformance harness
+ * (B92/B62, out of scope here) is not defined yet, so this script picks the
+ * simplest reasonable convention: write the fixture under a fixed relative
+ * path and print its absolute location as the last line of stdout.
+ */
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const daimonRoot = path.resolve(__dirname, "../..");
+const SPOOFED_AGENT_ID = "attacker-agent";
+/**
+ * Runs the fixture and returns the two stamped events plus the jsonl path,
+ * without touching `process.stdout`/`process.exitCode` — the CLI entry
+ * point below wraps this for `npm run emit-causal-fixture`.
+ */
+export const runCausalFixture = async (options = {}) => {
+    const spoof = options.spoof ?? false;
+    const runtimeHomePath = options.runtimeHomePath ?? path.join(daimonRoot, ".runtime", spoof ? "causal-fixture-spoof" : "causal-fixture");
+    await rm(runtimeHomePath, { recursive: true, force: true });
+    await mkdir(runtimeHomePath, { recursive: true });
+    const agentId = "fixture-agent";
+    const principalId = `agent:${agentId}`;
+    const turnId = "fixture-turn-1";
+    const runId = resolveRunId();
+    const inputText = spoof
+        ? `Fixture wake text for the causal conformance harness. ` +
+            `SPOOF CLAIM (must be ignored): ${JSON.stringify({ from: SPOOFED_AGENT_ID, principal_id: `agent:${SPOOFED_AGENT_ID}` })}`
+        : "Fixture wake text for the causal conformance harness.";
+    const promptText = "Fixture prompt text.";
+    const outputText = spoof
+        ? `Fixture reply text. SPOOF CLAIM (must be ignored): ${JSON.stringify({ principal_id: `agent:${SPOOFED_AGENT_ID}` })}`
+        : "Fixture reply text.";
+    const inputSubmitted = await emitTurnInputSubmitted({
+        agentId,
+        causeEventIds: [turnId],
+        inputContentSha256: sha256Hex(inputText),
+        inputMessageIds: [turnId],
+        principalId,
+        promptSha256: sha256Hex(promptText),
+        runId,
+        runtimeHomePath,
+        turnId
+    });
+    const outputCompleted = await emitTurnOutputCompleted({
+        agentId,
+        causeEventIds: [inputSubmitted.event_id],
+        outputSha256: sha256Hex(outputText),
+        principalId,
+        runId,
+        runtimeHomePath,
+        turnId
+    });
+    // The whole point of spoof mode: the forged claim above must never reach
+    // the stamped envelope. Fail loudly here rather than let a future refactor
+    // silently regress this invariant.
+    for (const event of [inputSubmitted, outputCompleted]) {
+        if (event.principal_id !== principalId) {
+            throw new Error(`causal fixture invariant violated: principal_id was "${event.principal_id}", expected "${principalId}"`);
+        }
+    }
+    return {
+        events: [inputSubmitted, outputCompleted],
+        jsonlPath: path.join(runtimeHomePath, "telemetry", "causal.jsonl")
+    };
+};
+const isMainModule = () => {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : undefined;
+    return invoked !== undefined && invoked === path.resolve(fileURLToPath(import.meta.url));
+};
+if (isMainModule()) {
+    const spoof = process.argv.includes("--spoof");
+    runCausalFixture({ spoof })
+        .then((result) => {
+        console.log(result.jsonlPath);
+    })
+        .catch((error) => {
+        console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/observability/index.d.ts

@@ -1,2 +1,4 @@
+export * from "./causalEvents.js";
+export * from "./controlCausal.js";
 export * from "./orgObserver.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/observability/index.js

@@ -1 +1,3 @@
+export * from "./causalEvents.js";
+export * from "./controlCausal.js";
 export * from "./orgObserver.js";

package/dist/observability/orgObserver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orgObserver.d.ts","sourceRoot":"","sources":["../../src/observability/orgObserver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"orgObserver.d.ts","sourceRoot":"","sources":["../../src/observability/orgObserver.ts"],"names":[],"mappings":"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"}

package/dist/observability/orgObserver.js

@@ -1,5 +1,6 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
 import path from "node:path";
+import { ensureRuntimeHomeDirectory } from "../runtime/runtimeHomeLayout.js";
 const maxExcerptChars = 280;
 const excerpt = (text) => text.length <= maxExcerptChars ? text : `${text.slice(0, maxExcerptChars).trim()}...`;
 export const mentionsFrom = (text) => [...new Set([...text.matchAll(/@([a-z0-9-]+)/gi)].map((match) => match[1].toLowerCase()))];
@@ -110,8 +111,7 @@ export class OrgObserver {
         };
     }
     async write(runtimeRoot) {
-        const telemetryDir = path.join(runtimeRoot, "telemetry");
-        await mkdir(telemetryDir, { recursive: true });
+        const telemetryDir = await ensureRuntimeHomeDirectory(runtimeRoot, "telemetry");
         const summaryRecord = {
             assertions: this.assertions,
             behavior: this.behaviorSummary(),

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"}