@celestea/agent-loop 2.7.1

package/dist/retention.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Tool-result retention (W855) — bound what ONE step may keep inline, and make
+ * every omitted byte retrievable.
+
+ * B6 (W855) split the two halves of a result:
+ *   - the session LOG stores the ORIGINAL value (`retainToolResult().logged`);
+ *   - the MODEL/SSE face is the bounded head/tail window + locator notice
+ *     (`retainToolResult().face`), rendered by the shared core primitives so a
+ *     replay of the same log reproduces the live model context byte for byte.
+
+ * Contract discipline (mirrors dsh-output-retention / dsh-spill):
+ *   - an omission means THE BUDGET kept something out. An upstream that
+ *     returned an incomplete body keeps its own domain field and is never
+ *     described as "truncated" here;
+ *   - the notice names the omitted amount EXACTLY and always carries a
+ *     retrieval instruction (the spill locator);
+ *   - cutting never returns broken UTF-8: head/tail are cut on code-point
+ *     boundaries;
+ *   - a spill that fails is BEST-EFFORT: the inline text is kept and the tool
+ *     call still succeeds (never turned into an error).
+
+ * The policy is session-scoped and lives in the Context under
+ * [RETENTION_SERVICE]; the agent loop reads it once per turn. The persistence
+ * half (where the bytes go) belongs to the host, NOT this L1 package.
+ */
+import { type ToolOutput } from "@celestea/core";
+/** Context service token: the retention policy of THIS session. */
+export declare const RETENTION_SERVICE = "celestea.agent-loop.ToolResultRetention";
+/**
+ * Tools whose results are NEVER rewritten by retention (W855 #8b).
+ *
+ * `read_file` is how the model retrieves a spilled locator; rewriting a read
+ * result into another "read_file <locator>" notice would invite a
+ * read -> spill -> read loop (`dsh-spill-policy` skips the same tool). The
+ * skipped result does NOT debit the step budget: those bytes are outside the
+ * retention budget by policy. W846: `read_file` now paginates with
+ * `offset`/`limit`, but each page is still bounded by the tool's 256 KiB
+ * budget, so the skip stays correct — a page stays inline up to that cap and
+ * the model advances with `nextOffset` instead of a retention locator.
+ */
+export declare const RETENTION_SKIP_TOOLS: ReadonlySet<string>;
+/** A persisted full-text tool result. */
+export interface SpillRef {
+    /** Where the full text lives (a path the model can read back). */
+    locator: string;
+    /** Exact byte size of the persisted text. */
+    bytes: number;
+    /** A concrete instruction for getting the text back. */
+    retrievalHint: string;
+}
+export interface ToolResultRetention {
+    /** A single result whose model-visible text exceeds this is retained. */
+    singleResultBytes: number;
+    /** Cumulative model-visible bytes one step may keep inline. */
+    stepResultBytes: number;
+    /** Head window kept inline when a result is retained. */
+    previewHeadBytes: number;
+    /** Tail window kept inline when a result is retained. */
+    previewTailBytes: number;
+    /** Persist the full text; null = best-effort failure (keep it inline). */
+    spill(text: string, meta: {
+        callId: string;
+    }): Promise<SpillRef | null>;
+}
+/** Default single-result threshold: 64 KiB (~16k tokens). */
+export declare const DEFAULT_SINGLE_RESULT_BYTES: number;
+/** Default per-step cumulative threshold: 128 KiB (~32k tokens). */
+export declare const DEFAULT_STEP_RESULT_BYTES: number;
+/** Default inline head window: 4 KiB. */
+export declare const DEFAULT_PREVIEW_HEAD_BYTES: number;
+/** Default inline tail window: 1 KiB. */
+export declare const DEFAULT_PREVIEW_TAIL_BYTES = 1024;
+/** Mutable per-step budget cursor (one per dispatchToolCalls call). */
+export interface StepRetention {
+    consumedBytes: number;
+}
+export declare function newStepRetention(): StepRetention;
+export { cutPrefixCodePoints, cutSuffixCodePoints, retainHeadTail } from "@celestea/core";
+export type { RetainedText } from "@celestea/core";
+/** The text retention measures and persists: a string value stays RAW (so the
+ * spill file is readable), anything else is the model-visible JSON. */
+export declare function retentionText(output: ToolOutput): string;
+/** The two surfaces of one tool result: what the log keeps vs what the model sees. */
+export interface ToolResultFaces {
+    /** The log row: the ORIGINAL value, plus the optional surface descriptor. */
+    logged: ToolOutput;
+    /** The model/SSE face: `value`/`render` replaced by the rendered surface. */
+    face: ToolOutput;
+}
+/** Apply a tool-authored surface (or none) to the face; the log keeps the original. */
+export declare function faceToolOutput(output: ToolOutput): ToolResultFaces;
+/**
+ * Apply retention to ONE tool output, returning BOTH surfaces.
+ *
+ * A result is retained when it exceeds the single-result threshold OR when it
+ * would push this step past the cumulative threshold. On ANY spill failure the
+ * ORIGINAL is kept inline (fail-soft).
+ */
+export declare function retainToolResult(output: ToolOutput, policy: ToolResultRetention, step: StepRetention, toolName?: string | null): Promise<ToolResultFaces>;
+/**
+ * Back-compat wrapper: the FACE only (what the model/SSE sees). Callers that
+ * must also persist the ORIGINAL use [retainToolResult].
+ */
+export declare function retainToolOutput(output: ToolOutput, policy: ToolResultRetention, step: StepRetention, toolName?: string | null): Promise<ToolOutput>;

package/dist/retention.js

@@ -0,0 +1,134 @@
+/**
+ * Tool-result retention (W855) — bound what ONE step may keep inline, and make
+ * every omitted byte retrievable.
+
+ * B6 (W855) split the two halves of a result:
+ *   - the session LOG stores the ORIGINAL value (`retainToolResult().logged`);
+ *   - the MODEL/SSE face is the bounded head/tail window + locator notice
+ *     (`retainToolResult().face`), rendered by the shared core primitives so a
+ *     replay of the same log reproduces the live model context byte for byte.
+
+ * Contract discipline (mirrors dsh-output-retention / dsh-spill):
+ *   - an omission means THE BUDGET kept something out. An upstream that
+ *     returned an incomplete body keeps its own domain field and is never
+ *     described as "truncated" here;
+ *   - the notice names the omitted amount EXACTLY and always carries a
+ *     retrieval instruction (the spill locator);
+ *   - cutting never returns broken UTF-8: head/tail are cut on code-point
+ *     boundaries;
+ *   - a spill that fails is BEST-EFFORT: the inline text is kept and the tool
+ *     call still succeeds (never turned into an error).
+
+ * The policy is session-scoped and lives in the Context under
+ * [RETENTION_SERVICE]; the agent loop reads it once per turn. The persistence
+ * half (where the bytes go) belongs to the host, NOT this L1 package.
+ */
+import { renderOmittedText, retainHeadTail, toolSurfaceText, toolSurfaceValue } from "@celestea/core";
+/** Context service token: the retention policy of THIS session. */
+export const RETENTION_SERVICE = "celestea.agent-loop.ToolResultRetention";
+/**
+ * Tools whose results are NEVER rewritten by retention (W855 #8b).
+ *
+ * `read_file` is how the model retrieves a spilled locator; rewriting a read
+ * result into another "read_file <locator>" notice would invite a
+ * read -> spill -> read loop (`dsh-spill-policy` skips the same tool). The
+ * skipped result does NOT debit the step budget: those bytes are outside the
+ * retention budget by policy. W846: `read_file` now paginates with
+ * `offset`/`limit`, but each page is still bounded by the tool's 256 KiB
+ * budget, so the skip stays correct — a page stays inline up to that cap and
+ * the model advances with `nextOffset` instead of a retention locator.
+ */
+export const RETENTION_SKIP_TOOLS = new Set(["read_file"]);
+/** Default single-result threshold: 64 KiB (~16k tokens). */
+export const DEFAULT_SINGLE_RESULT_BYTES = 64 * 1024;
+/** Default per-step cumulative threshold: 128 KiB (~32k tokens). */
+export const DEFAULT_STEP_RESULT_BYTES = 128 * 1024;
+/** Default inline head window: 4 KiB. */
+export const DEFAULT_PREVIEW_HEAD_BYTES = 4 * 1024;
+/** Default inline tail window: 1 KiB. */
+export const DEFAULT_PREVIEW_TAIL_BYTES = 1024;
+export function newStepRetention() {
+    return { consumedBytes: 0 };
+}
+// W855 (B6): the pure cut/render primitives live in core so the projection can
+// render the face without importing this L1 policy layer. Re-exported here so
+// the package keeps its stable import path.
+export { cutPrefixCodePoints, cutSuffixCodePoints, retainHeadTail } from "@celestea/core";
+/** The text retention measures and persists: a string value stays RAW (so the
+ * spill file is readable), anything else is the model-visible JSON. */
+export function retentionText(output) {
+    if (typeof output.error === "string" && output.error.length > 0)
+        return "Error: " + output.error;
+    return typeof output.value === "string" ? output.value : toolSurfaceText(output.value, undefined);
+}
+/** Apply a tool-authored surface (or none) to the face; the log keeps the original. */
+export function faceToolOutput(output) {
+    if (output.surface === undefined)
+        return { logged: output, face: output };
+    const face = toolSurfaceValue(output.value, output.surface); // RAW (SSE/UI) face
+    return { logged: output, face: { ...output, value: face, render: typeof face === "string" ? face : output.render } };
+}
+/**
+ * Apply retention to ONE tool output, returning BOTH surfaces.
+ *
+ * A result is retained when it exceeds the single-result threshold OR when it
+ * would push this step past the cumulative threshold. On ANY spill failure the
+ * ORIGINAL is kept inline (fail-soft).
+ */
+export async function retainToolResult(output, policy, step, toolName = null) {
+    const text = retentionText(output);
+    const bytes = Buffer.byteLength(text, "utf8");
+    // W855 #8b: a read tool's result IS the retrieval path, not a payload to
+    // spill; skipping it prevents read -> spill -> read (and does not debit the
+    // step budget — see RETENTION_SKIP_TOOLS).
+    if (toolName !== null && RETENTION_SKIP_TOOLS.has(toolName))
+        return faceToolOutput(output);
+    // W855 decision (architect, 2026-09-18): ONLY a successful STRING result is
+    // rewritten. An object result's value shape is part of the tool contract
+    // (consumers branch on typeof value === "object"), so this layer NEVER
+    // changes its type; shrinking a large object is the tool's own decision
+    // (deferred). Error results are messages, not payloads, and pass through too.
+    // Non-string results still count toward the step budget.
+    if (output.error !== null || typeof output.value !== "string") {
+        step.consumedBytes += bytes;
+        return faceToolOutput(output);
+    }
+    const overSingle = bytes > policy.singleResultBytes;
+    const overStep = step.consumedBytes + bytes > policy.stepResultBytes;
+    if (!overSingle && !overStep) {
+        step.consumedBytes += bytes;
+        return faceToolOutput(output);
+    }
+    let ref = null;
+    try {
+        ref = await policy.spill(text, { callId: output.call_id });
+    }
+    catch {
+        ref = null;
+    }
+    if (ref === null) {
+        // Best-effort: the tool call stays successful and keeps its full result.
+        step.consumedBytes += bytes;
+        return faceToolOutput(output);
+    }
+    const window = retainHeadTail(text, policy.previewHeadBytes, policy.previewTailBytes);
+    const surface = {
+        kind: "omitted",
+        omitted_bytes: window.omittedBytes,
+        total_bytes: window.totalBytes,
+        locator: ref.locator,
+        retrieval_hint: ref.retrievalHint,
+        head_bytes: policy.previewHeadBytes,
+        tail_bytes: policy.previewTailBytes,
+    };
+    const face = renderOmittedText(text, surface);
+    step.consumedBytes += Buffer.byteLength(face, "utf8");
+    return { logged: { ...output, surface }, face: { ...output, value: face, render: face, surface } };
+}
+/**
+ * Back-compat wrapper: the FACE only (what the model/SSE sees). Callers that
+ * must also persist the ORIGINAL use [retainToolResult].
+ */
+export async function retainToolOutput(output, policy, step, toolName = null) {
+    return (await retainToolResult(output, policy, step, toolName)).face;
+}

package/dist/seams.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Driver-seam resolution for one turn.
+ *
+ * The loop never imports an implementation: it resolves the three seams the
+ * legacy `run_turn` resolved from the shared `Context` — `Llm` (how to generate),
+ * `SessionLog` (where the single source of truth lives) and `ToolRegistry`
+ * (how to dispatch tool calls) — and fails loudly when the composition root
+ * forgot one. Same three services, same order, as `crates/agent-loop/src/loop.rs`.
+ */
+import { type Context, type Llm, type SessionLog, type ToolCall, type ToolInput, type ToolOutput, type ToolRegistry } from "@celestea/core";
+/** The three seams a turn resolves from the Context. */
+export interface Seams {
+    llm: Llm;
+    session: SessionLog;
+    registry: ToolRegistry;
+}
+/** Resolve the driver seams; a missing service is a wiring bug, not a state. */
+export declare function resolveSeams(ctx: Context): Seams;
+export declare function toToolInput(call: ToolCall): ToolInput;
+/**
+ * Dispatch one call, containing a seam violation: `ToolRegistry.dispatch`
+ * captures tool errors in `ToolOutput.error` and must not throw, so an escaping
+ * exception would otherwise leave the turn without a terminal state. The
+ * legacy loop could rely on `?`-free unwrapping; TS keeps the same totality
+ * explicitly.
+ */
+export declare function dispatchCall(registry: ToolRegistry, input: ToolInput): Promise<ToolOutput>;

package/dist/seams.js

@@ -0,0 +1,42 @@
+/**
+ * Driver-seam resolution for one turn.
+ *
+ * The loop never imports an implementation: it resolves the three seams the
+ * legacy `run_turn` resolved from the shared `Context` — `Llm` (how to generate),
+ * `SessionLog` (where the single source of truth lives) and `ToolRegistry`
+ * (how to dispatch tool calls) — and fails loudly when the composition root
+ * forgot one. Same three services, same order, as `crates/agent-loop/src/loop.rs`.
+ */
+import { AgentError, LLM_SERVICE, SESSION_LOG_SERVICE, TOOL_REGISTRY_SERVICE, } from "@celestea/core";
+import { errorMessage } from "./cancel.js";
+/** Resolve the driver seams; a missing service is a wiring bug, not a state. */
+export function resolveSeams(ctx) {
+    const llm = ctx.get(LLM_SERVICE);
+    if (llm === undefined)
+        throw new AgentError("missing LlmService in context");
+    const session = ctx.get(SESSION_LOG_SERVICE);
+    if (session === undefined)
+        throw new AgentError("missing SessionLog service in context");
+    const registry = ctx.get(TOOL_REGISTRY_SERVICE);
+    if (registry === undefined)
+        throw new AgentError("missing ToolRegistryService in context");
+    return { llm, session, registry };
+}
+export function toToolInput(call) {
+    return { call_id: call.id, name: call.name, args: call.args };
+}
+/**
+ * Dispatch one call, containing a seam violation: `ToolRegistry.dispatch`
+ * captures tool errors in `ToolOutput.error` and must not throw, so an escaping
+ * exception would otherwise leave the turn without a terminal state. The
+ * legacy loop could rely on `?`-free unwrapping; TS keeps the same totality
+ * explicitly.
+ */
+export async function dispatchCall(registry, input) {
+    try {
+        return await registry.dispatch(input);
+    }
+    catch (error) {
+        return { call_id: input.call_id, value: null, render: null, error: errorMessage(error), decision: null };
+    }
+}

package/dist/sse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * LoopEvent -> (SSE event name, payload) — the exact mapping of
+ * `celestea_studio/src/main.rs:667-713` (`loop_event_to_json`).
+ *
+ * Kept in this package because it is contract, not transport: the frozen
+ * `contracts/sse-events.json` table is checked against it, and the host
+ * (`apps/studio`) only publishes the resulting frames. Phase/error labels come
+ * from `core` (`outcomePhase` / `outcomeError`), so the agent loop never keeps
+ * a second copy of that vocabulary.
+ */
+import { type LoopEvent, type SseEventName } from "@celestea/core";
+export interface SseFrame {
+    event: SseEventName;
+    payload: Record<string, unknown>;
+}
+/** LoopEvent -> (SSE event name, payload) exactly as `loop_event_to_json`. */
+export declare function loopEventToSse(ev: LoopEvent): SseFrame;

package/dist/sse.js

@@ -0,0 +1,41 @@
+/**
+ * LoopEvent -> (SSE event name, payload) — the exact mapping of
+ * `celestea_studio/src/main.rs:667-713` (`loop_event_to_json`).
+ *
+ * Kept in this package because it is contract, not transport: the frozen
+ * `contracts/sse-events.json` table is checked against it, and the host
+ * (`apps/studio`) only publishes the resulting frames. Phase/error labels come
+ * from `core` (`outcomePhase` / `outcomeError`), so the agent loop never keeps
+ * a second copy of that vocabulary.
+ */
+import { outcomeError, outcomePhase } from "@celestea/core";
+/** LoopEvent -> (SSE event name, payload) exactly as `loop_event_to_json`. */
+export function loopEventToSse(ev) {
+    switch (ev.kind) {
+        case "text":
+            return { event: "text", payload: { delta: ev.delta } };
+        case "thinking":
+            return { event: "thinking", payload: { delta: ev.delta } };
+        case "tool_call":
+            return { event: "tool", payload: { id: ev.id, name: ev.name, args: ev.args } };
+        case "tool_result":
+            // W855 (B6): `value` is the MODEL FACE, not the log's original — the loop
+            // builds the face from the retention surface before emitting. Replay derives
+            // the same face from the log (`session/src/replay.ts`).
+            return {
+                event: "tool_result",
+                payload: {
+                    id: ev.callId,
+                    ok: ev.ok,
+                    value: ev.value,
+                    render: ev.render,
+                    error: ev.error,
+                    decision: ev.decision,
+                },
+            };
+        case "turn_end":
+            return { event: "turn_end", payload: { outcome: outcomePhase(ev.outcome), error: outcomeError(ev.outcome) } };
+        case "done":
+            return { event: "done", payload: { text: ev.text, tool_calls: ev.tool_calls } };
+    }
+}

package/dist/step.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-step bookkeeping types and the pure folds of one model step.
+ *
+ * Kept apart from the loop driver so the verdict vocabulary ("what did this
+ * step decide?") is readable on its own: a step can end the turn, ask for
+ * another step, be cancelled, or fail to start at all.
+ */
+import { type LlmStream, type Message, type StreamEvent, type ToolCall, type TurnOutcome } from "@celestea/core";
+/** Verdict of one model step, consumed by the step loop. */
+export type StepResult = 
+/** The turn is over (completed, or a torn stream after a done frame). */
+{
+    kind: "final";
+    outcome: TurnOutcome;
+}
+/** Tool calls were dispatched; step again. */
+ | {
+    kind: "continue";
+} | {
+    kind: "cancelled";
+};
+/** What starting one model response produced. */
+export type GenerateResult = {
+    kind: "ok";
+    stream: LlmStream;
+} | {
+    kind: "cancelled";
+} | {
+    kind: "failed";
+    outcome: TurnOutcome;
+};
+/** Everything the loop learned from one response stream. */
+export interface StreamOutcome {
+    assistantText: string;
+    toolCalls: ToolCall[];
+    sawDone: boolean;
+    doneMessage: Message | null;
+    cancelled: boolean;
+    terminal: TurnOutcome | null;
+}
+export declare function emptyStreamOutcome(): StreamOutcome;
+/** Fold the authoritative `done` message into the step accumulators. */
+export declare function absorbDone(out: StreamOutcome, message: Message): void;
+/** `failed` / `interrupted` are terminal: they decide the turn's state. */
+export declare function terminalFromStreamEvent(ev: StreamEvent): TurnOutcome;

package/dist/step.js

@@ -0,0 +1,22 @@
+/**
+ * Per-step bookkeeping types and the pure folds of one model step.
+ *
+ * Kept apart from the loop driver so the verdict vocabulary ("what did this
+ * step decide?") is readable on its own: a step can end the turn, ask for
+ * another step, be cancelled, or fail to start at all.
+ */
+import { messageTexts, messageToolCalls } from "@celestea/core";
+export function emptyStreamOutcome() {
+    return { assistantText: "", toolCalls: [], sawDone: false, doneMessage: null, cancelled: false, terminal: null };
+}
+/** Fold the authoritative `done` message into the step accumulators. */
+export function absorbDone(out, message) {
+    out.sawDone = true;
+    out.doneMessage = message;
+    out.assistantText += messageTexts(message).join("");
+    out.toolCalls.push(...messageToolCalls(message));
+}
+/** `failed` / `interrupted` are terminal: they decide the turn's state. */
+export function terminalFromStreamEvent(ev) {
+    return ev.kind === "failed" ? { error: { kind: ev.kindOf, message: ev.message } } : "interrupted";
+}

package/dist/thinking.d.ts

@@ -0,0 +1,23 @@
+/**
+ * W252: thinking-delta aggregation.
+ *
+ * The session log is the replay source of truth, but reasoning streams arrive
+ * token by token: one jsonl row per delta would explode the log. Consecutive
+ * `thinking` deltas are therefore concatenated into a buffer and flushed only
+ * at visible boundaries (text / done / failed / stream end / cancellation), so
+ * one contiguous reasoning burst becomes exactly ONE persisted
+ * `thinking_delta` row. The live `thinking` event is still emitted per delta —
+ * only persistence aggregates.
+ */
+import type { SessionLog } from "@celestea/core";
+export declare class ThinkingBuffer {
+    private readonly session;
+    private buffered;
+    constructor(session: SessionLog);
+    /** Concatenate one delta into the current burst. */
+    push(delta: string): void;
+    /** Persist the current burst as one row; a no-op for an empty buffer. */
+    flush(): void;
+    /** True when deltas are waiting to be persisted (diagnostics / tests). */
+    get pending(): boolean;
+}

package/dist/thinking.js

@@ -0,0 +1,34 @@
+/**
+ * W252: thinking-delta aggregation.
+ *
+ * The session log is the replay source of truth, but reasoning streams arrive
+ * token by token: one jsonl row per delta would explode the log. Consecutive
+ * `thinking` deltas are therefore concatenated into a buffer and flushed only
+ * at visible boundaries (text / done / failed / stream end / cancellation), so
+ * one contiguous reasoning burst becomes exactly ONE persisted
+ * `thinking_delta` row. The live `thinking` event is still emitted per delta —
+ * only persistence aggregates.
+ */
+export class ThinkingBuffer {
+    session;
+    buffered = "";
+    constructor(session) {
+        this.session = session;
+    }
+    /** Concatenate one delta into the current burst. */
+    push(delta) {
+        this.buffered += delta;
+    }
+    /** Persist the current burst as one row; a no-op for an empty buffer. */
+    flush() {
+        if (this.buffered === "")
+            return;
+        const text = this.buffered;
+        this.buffered = "";
+        this.session.append({ type: "thinking_delta", text });
+    }
+    /** True when deltas are waiting to be persisted (diagnostics / tests). */
+    get pending() {
+        return this.buffered !== "";
+    }
+}

package/dist/usage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * UsageTracker — port of the `UsageTracker` of
+ * `crates/agent-loop/src/loop.rs` (W220).
+ *
+ * The loop records the `usage` stream event of every LLM response; the host
+ * reads `latest()` (most recent response) and `total()` (cumulative) to expose
+ * the statusline and to drive future trimming decisions. Both accessors return
+ * copies, matching the engine's `Copy` semantics — a caller can never mutate the
+ * tracker's state through the returned value.
+ */
+import { type Usage } from "@celestea/core";
+export declare class UsageTracker {
+    private totalUsage;
+    private latestUsage;
+    /** Record one LLM response: adds to the cumulative total, becomes latest. */
+    record(usage: Usage): void;
+    /** The usage of the most recent LLM response (zeroed when none yet). */
+    latest(): Usage;
+    /** Cumulative usage across every recorded response. */
+    total(): Usage;
+}
+/** Factory form (`createXxx` convention, ARCHITECTURE.md §6.1). */
+export declare function createUsageTracker(): UsageTracker;

package/dist/usage.js

@@ -0,0 +1,32 @@
+/**
+ * UsageTracker — port of the `UsageTracker` of
+ * `crates/agent-loop/src/loop.rs` (W220).
+ *
+ * The loop records the `usage` stream event of every LLM response; the host
+ * reads `latest()` (most recent response) and `total()` (cumulative) to expose
+ * the statusline and to drive future trimming decisions. Both accessors return
+ * copies, matching the engine's `Copy` semantics — a caller can never mutate the
+ * tracker's state through the returned value.
+ */
+import { usageAdd, zeroUsage } from "@celestea/core";
+export class UsageTracker {
+    totalUsage = zeroUsage();
+    latestUsage = zeroUsage();
+    /** Record one LLM response: adds to the cumulative total, becomes latest. */
+    record(usage) {
+        this.totalUsage = usageAdd(this.totalUsage, usage);
+        this.latestUsage = usage;
+    }
+    /** The usage of the most recent LLM response (zeroed when none yet). */
+    latest() {
+        return { ...this.latestUsage };
+    }
+    /** Cumulative usage across every recorded response. */
+    total() {
+        return { ...this.totalUsage };
+    }
+}
+/** Factory form (`createXxx` convention, ARCHITECTURE.md §6.1). */
+export function createUsageTracker() {
+    return new UsageTracker();
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@celestea/agent-loop",
+  "version": "2.7.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@celestea/core": "2.7.1"
+  },
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}