@celestea/runtime 2.7.1

package/dist/tokens.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Well-known service tokens the runtime owns.
+ *
+ * `core` freezes the seam tokens (`SESSION_LOG_SERVICE`, `LLM_SERVICE`,
+ * `TOOL_REGISTRY_SERVICE`, `AGENT_LOOP_SERVICE`, `EVENT_BUS_SERVICE`). The
+ * runtime adds the tokens that only exist because it drives turns: the
+ * per-turn abort signal, the per-turn frame sink, and the two accounting
+ * services. They follow the same convention (a stable namespaced string), so a
+ * Context-aware `AgentLoop` implementation can resolve them without importing
+ * this package (which would be an L1 -> L2 jump, ARCHITECTURE.md §1.3 D3).
+ */
+/** Per-turn `AbortSignal` (cooperative cancellation), provided on the turn scope. */
+export declare const TURN_ABORT_SERVICE = "celestea.runtime.TurnAbort";
+/** Per-turn frame sink: `(frame: TurnFrame) => void` (SSE-shaped, in log order). */
+export declare const TURN_SINK_SERVICE = "celestea.runtime.TurnSink";
+/** Shared usage accounting (`UsageAccounting`): latest + cumulative. */
+export declare const USAGE_TRACKER_SERVICE = "celestea.runtime.UsageTracker";
+/** Shared statusline tracker (`StatusTracker`): steps + delta rate. */
+export declare const STATUS_TRACKER_SERVICE = "celestea.runtime.StatusTracker";
+/** The host (coordinator) conversation id: registry / mailbox queue key. */
+export declare const HOST_SESSION_ID = "cli-main";
+/** Default directory the worker receipt protocol writes `results/<wid>-<short>.md` into. */
+export declare const RESULTS_DIR = "results";
+/** W218: context window used for the estimated ratio (contract display default). */
+export declare const CONTEXT_WINDOW_FALLBACK = 1000000;

package/dist/tokens.js

@@ -0,0 +1,25 @@
+/**
+ * Well-known service tokens the runtime owns.
+ *
+ * `core` freezes the seam tokens (`SESSION_LOG_SERVICE`, `LLM_SERVICE`,
+ * `TOOL_REGISTRY_SERVICE`, `AGENT_LOOP_SERVICE`, `EVENT_BUS_SERVICE`). The
+ * runtime adds the tokens that only exist because it drives turns: the
+ * per-turn abort signal, the per-turn frame sink, and the two accounting
+ * services. They follow the same convention (a stable namespaced string), so a
+ * Context-aware `AgentLoop` implementation can resolve them without importing
+ * this package (which would be an L1 -> L2 jump, ARCHITECTURE.md §1.3 D3).
+ */
+/** Per-turn `AbortSignal` (cooperative cancellation), provided on the turn scope. */
+export const TURN_ABORT_SERVICE = "celestea.runtime.TurnAbort";
+/** Per-turn frame sink: `(frame: TurnFrame) => void` (SSE-shaped, in log order). */
+export const TURN_SINK_SERVICE = "celestea.runtime.TurnSink";
+/** Shared usage accounting (`UsageAccounting`): latest + cumulative. */
+export const USAGE_TRACKER_SERVICE = "celestea.runtime.UsageTracker";
+/** Shared statusline tracker (`StatusTracker`): steps + delta rate. */
+export const STATUS_TRACKER_SERVICE = "celestea.runtime.StatusTracker";
+/** The host (coordinator) conversation id: registry / mailbox queue key. */
+export const HOST_SESSION_ID = "cli-main";
+/** Default directory the worker receipt protocol writes `results/<wid>-<short>.md` into. */
+export const RESULTS_DIR = "results";
+/** W218: context window used for the estimated ratio (contract display default). */
+export const CONTEXT_WINDOW_FALLBACK = 1_000_000;

package/dist/turn-runner.d.ts

@@ -0,0 +1,169 @@
+/**
+ * One turn, driven through the `AgentLoop` seam (`runtime/src/run.rs`).
+ *
+ * Responsibilities, in order:
+ *   1. **single concurrency slot** — a Runtime generation runs at most one turn;
+ *      a second `runTurn` while busy is a [TurnBusyError] (409), never a queue;
+ *   2. **receipt drain** — pending worker receipts are polled out of the host
+ *      mailbox and appended to the session log BEFORE the input, so a receipt is
+ *      real, model-visible history on the host's next turn (W232);
+ *   3. **stream mapping** — every `LoopEvent` the loop emits is fed to the
+ *      statusline tracker and mapped to one host frame, in log order;
+ *   4. **cancel propagation** — the caller's `AbortSignal` is linked to the
+ *      turn's own signal, which is (a) passed to the loop bindings and
+ *      (b) provided on the turn scope under `TURN_ABORT_SERVICE`;
+ *   5. **terminal state** — read back from the session log's own `turn_end`
+ *      (the log is the single source of truth), never invented by the runtime.
+ *   6. **usage ledger observation** (W728) — when a ledger is wired, the turn
+ *      boundary is announced to it (pure observation; it can never throw).
+ */
+import { type AgentConfig, type AgentLoop, type Context, type ImageRef, type InjectionSource, type PendingInjection, type SessionEvent, type SessionLog, type TurnOutcome } from "@celestea/core";
+import type { FrameMapper, LoopEventSink, TurnFrame } from "./frames.js";
+import type { TurnLedgerHooks } from "./ledger.js";
+import type { StatusTracker } from "./status.js";
+import type { UsageAccounting } from "./usage.js";
+/** Host-side frame consumer (SSE publisher, CLI renderer, test collector). */
+export type FrameSink = (frame: TurnFrame) => void;
+/**
+ * W888: one engine-owned turn-context row. The origin is what the transcript
+ * uses to label the injected block instead of showing it as a user bubble.
+ */
+export interface TurnContextRow {
+    readonly text: string;
+    readonly origin: "skill" | "memory";
+}
+export interface TurnOptions {
+    /** Caller cancellation (linked into the turn's own signal). */
+    signal?: AbortSignal;
+    /** Frame consumer for this turn; absent = frames are dropped. */
+    sink?: FrameSink;
+    /**
+     * W804: content-addressed image references for THIS turn's user message. The
+     * loop writes them onto the `user_message` row; bytes never enter the log.
+     */
+    attachments?: readonly ImageRef[];
+}
+/** Collaborators handed to a per-turn loop instance (`with_bindings`). */
+export interface LoopBindings {
+    config: AgentConfig;
+    signal: AbortSignal;
+    sink: LoopEventSink;
+    usage: UsageAccounting;
+    /** Mid-turn injection source (absent = nothing can be injected). */
+    injections?: InjectionSource;
+}
+/** Builds the per-turn `AgentLoop`; the host injects its concrete loop here. */
+export type LoopFactory = (bindings: LoopBindings) => AgentLoop;
+/** Anything waiting to be appended to the log (user text, receipt, relay). */
+export type PendingReceipt = PendingInjection;
+export interface TurnRunnerDeps {
+    ctx: Context;
+    /** Current session log (a rebind swaps the producer, so this is a getter). */
+    session: () => SessionLog;
+    status: StatusTracker;
+    usage: UsageAccounting;
+    agentConfig: AgentConfig;
+    frameMapper: FrameMapper;
+    /**
+     * Usage ledger hooks (W728 §3 P0): the turn boundary is only known HERE, and
+     * the ledger must not guess it from a counter. Observation only — the ledger
+     * swallows its own IO failures, so a turn cannot fail because of bookkeeping.
+     */
+    ledger?: TurnLedgerHooks;
+    /** Absent = the loop is resolved from `AGENT_LOOP_SERVICE` in the Context. */
+    loopFactory?: LoopFactory;
+    /**
+     * The TURN-START drain (`next-turn` lane + session mailbox): receipts precede
+     * the input (W232) and a follow-up queued while the session was idle is
+     * appended before it (W515 §1: `placement: "queued"`).
+     */
+    drainPending?: () => PendingReceipt[];
+    /**
+     * The STEP-BOUNDARY source handed to the loop (`next-step` lane + session
+     * mailbox). It carries `pending()` so the loop can refuse to close a turn
+     * while a steering message is still waiting (W515 §1 invariant).
+     */
+    injections?: InjectionSource;
+    /**
+     * W884: durable, ENGINE-OWNED turn context — the skill catalog (name +
+     * description only) and the F3 workspace MEMORY.md. Evaluated at EVERY turn
+     * start, before the receipts and the input, and appended as ordinary user-role
+     * history so it stays resident and participates in trimming/compaction like any
+     * other message. Returning `[]` costs nothing (a workspace with neither).
+     *
+     * W888: each row carries its own `origin` so the transcript can label an
+     * injected block ('skill' catalog vs 'memory') instead of showing it as a
+     * typed user bubble.
+     */
+    turnContext?: () => readonly TurnContextRow[];
+}
+export declare class TurnRunner {
+    private readonly deps;
+    private busy;
+    private controller;
+    private turnNo;
+    private released;
+    /** The in-flight turn promise, so shutdown can wait for it (P1-5, W836). */
+    private inFlight;
+    constructor(deps: TurnRunnerDeps);
+    get isBusy(): boolean;
+    /** The in-flight turn's signal, or null between turns. */
+    get currentSignal(): AbortSignal | null;
+    /** Turns started by this runner (diagnostics / tests). */
+    get turnCount(): number;
+    /** Cancel the in-flight turn; returns false when nothing was running. */
+    cancel(): boolean;
+    /** Shutdown hook: stop driving, but keep no other state. */
+    stop(): void;
+    runTurn(input: string | null, opts?: TurnOptions): Promise<TurnOutcome>;
+    /**
+     * P1-5 (W836): wait for the in-flight turn to settle. `stop()` only ABORTS it;
+     * a shutdown that claims a clean exit must first see the turn's own terminal
+     * write, or a crash inside that window strands the turn forever.
+     */
+    join(): Promise<void>;
+    private drive;
+    /** Feed the tracker, then map the event onto one host frame. */
+    private makeSink;
+    /** W263口径: a step per tool CALL; deltas feed the rate window. */
+    private observe;
+    /**
+     * The turn scope: the root context plus the per-turn services. A loop
+     * constructed from the Context (no factory) can resolve the signal and sink
+     * here without importing this package.
+     */
+    private turnScope;
+    private resolveLoop;
+    /**
+     * W884: append the engine-owned turn context (the skill catalog). Blank rows
+     * are dropped, so a provider that has nothing to say is free to return [""].
+     */
+    private injectTurnContext;
+    /** Turn-start drain: receipts and interjections land BEFORE the input. */
+    private injectReceipts;
+    /** The single drain function shared by turn start and the step boundary. */
+    private drainPending;
+}
+/** `[from W1] content` — the receipt attribution the host log shows verbatim. */
+export declare function formatReceipt(receipt: PendingReceipt): string;
+/**
+ * Link a caller signal into the turn's controller. Returns the cleanup that
+ * removes the listener again (P1-7, W836): `once:true` only removes it when the
+ * source DOES abort, so a host signal that outlives many turns would otherwise
+ * accumulate one listener per turn.
+ */
+export declare function linkAbort(source: AbortSignal, target: AbortController): () => void;
+/**
+ * The terminal state of the turn that started at `from`: the LAST `turn_end`
+ * appended after that index, with legacy rows (missing outcome) defaulting to
+ * `completed` exactly like the JSONL codec does.
+ */
+export declare function lastTurnEndOutcome(events: readonly SessionEvent[], from: number): TurnOutcome | null;
+/**
+ * Resolve the outcome of a finished turn:
+ *   1. a `turn_end` written by the loop wins — the log is the source of truth;
+ *   2. otherwise the turn never terminated: a thrown error propagates (a wiring
+ *      failure is not a terminal state), an aborted turn is `cancelled`, and a
+ *      silently-stopped turn is `interrupted` (a torn turn is never `completed`).
+ */
+export declare function resolveOutcome(events: readonly SessionEvent[], from: number, signal: AbortSignal, failure: unknown): TurnOutcome;

package/dist/turn-runner.js

@@ -0,0 +1,242 @@
+/**
+ * One turn, driven through the `AgentLoop` seam (`runtime/src/run.rs`).
+ *
+ * Responsibilities, in order:
+ *   1. **single concurrency slot** — a Runtime generation runs at most one turn;
+ *      a second `runTurn` while busy is a [TurnBusyError] (409), never a queue;
+ *   2. **receipt drain** — pending worker receipts are polled out of the host
+ *      mailbox and appended to the session log BEFORE the input, so a receipt is
+ *      real, model-visible history on the host's next turn (W232);
+ *   3. **stream mapping** — every `LoopEvent` the loop emits is fed to the
+ *      statusline tracker and mapped to one host frame, in log order;
+ *   4. **cancel propagation** — the caller's `AbortSignal` is linked to the
+ *      turn's own signal, which is (a) passed to the loop bindings and
+ *      (b) provided on the turn scope under `TURN_ABORT_SERVICE`;
+ *   5. **terminal state** — read back from the session log's own `turn_end`
+ *      (the log is the single source of truth), never invented by the runtime.
+ *   6. **usage ledger observation** (W728) — when a ledger is wired, the turn
+ *      boundary is announced to it (pure observation; it can never throw).
+ */
+import { AGENT_LOOP_SERVICE, } from "@celestea/core";
+import { ComposeError, RuntimeReleasedError, TurnBusyError } from "./errors.js";
+import { TURN_ABORT_SERVICE, TURN_SINK_SERVICE, USAGE_TRACKER_SERVICE } from "./tokens.js";
+export class TurnRunner {
+    deps;
+    busy = false;
+    controller = null;
+    turnNo = 0;
+    released = false;
+    /** The in-flight turn promise, so shutdown can wait for it (P1-5, W836). */
+    inFlight = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get isBusy() {
+        return this.busy;
+    }
+    /** The in-flight turn's signal, or null between turns. */
+    get currentSignal() {
+        return this.controller?.signal ?? null;
+    }
+    /** Turns started by this runner (diagnostics / tests). */
+    get turnCount() {
+        return this.turnNo;
+    }
+    /** Cancel the in-flight turn; returns false when nothing was running. */
+    cancel() {
+        if (this.controller === null)
+            return false;
+        this.controller.abort();
+        return true;
+    }
+    /** Shutdown hook: stop driving, but keep no other state. */
+    stop() {
+        this.released = true;
+        this.cancel();
+    }
+    async runTurn(input, opts = {}) {
+        if (this.released)
+            throw new RuntimeReleasedError("the turn runner was stopped");
+        if (this.busy)
+            throw new TurnBusyError();
+        this.busy = true;
+        const controller = new AbortController();
+        const unlink = opts.signal === undefined ? null : linkAbort(opts.signal, controller);
+        this.controller = controller;
+        const run = this.drive(input, opts, controller.signal);
+        this.inFlight = run;
+        try {
+            return await run;
+        }
+        finally {
+            unlink?.();
+            this.controller = null;
+            this.busy = false;
+            this.inFlight = null;
+        }
+    }
+    /**
+     * P1-5 (W836): wait for the in-flight turn to settle. `stop()` only ABORTS it;
+     * a shutdown that claims a clean exit must first see the turn's own terminal
+     * write, or a crash inside that window strands the turn forever.
+     */
+    async join() {
+        const run = this.inFlight;
+        if (run === null)
+            return;
+        try {
+            await run;
+        }
+        catch {
+            // The starter observes the outcome; shutdown only needs the turn stopped.
+        }
+    }
+    async drive(input, opts, signal) {
+        this.turnNo += 1;
+        this.deps.status.beginTurn();
+        const sink = this.makeSink(opts.sink);
+        const scope = this.turnScope(signal, sink);
+        const log = this.deps.session();
+        // W884: the skill catalog is standing context, so it lands BEFORE the
+        // receipts (which are addressed messages and belong nearest the input).
+        this.injectTurnContext(log);
+        this.injectReceipts(log);
+        const start = log.events().length;
+        const loop = this.resolveLoop(signal, sink);
+        this.deps.ledger?.beginTurn(log);
+        let failure = null;
+        try {
+            await loop.runTurn(scope, input, opts.attachments);
+        }
+        catch (error) {
+            failure = error;
+        }
+        try {
+            const outcome = resolveOutcome(log.events(), start, signal, failure);
+            this.deps.ledger?.endTurn(outcome);
+            return outcome;
+        }
+        catch (error) {
+            // A wiring failure still closes the ledger's turn before it propagates:
+            // the usage already booked belongs to a turn that will have no total.
+            this.deps.ledger?.endTurn("interrupted");
+            throw error;
+        }
+    }
+    /** Feed the tracker, then map the event onto one host frame. */
+    makeSink(userSink) {
+        return (event) => {
+            this.observe(event);
+            userSink?.(this.deps.frameMapper(event));
+        };
+    }
+    /** W263口径: a step per tool CALL; deltas feed the rate window. */
+    observe(event) {
+        if (event.kind === "text")
+            this.deps.status.addChars(event.delta.length);
+        else if (event.kind === "thinking")
+            this.deps.status.addChars(event.delta.length);
+        else if (event.kind === "tool_call")
+            this.deps.status.addStep();
+    }
+    /**
+     * The turn scope: the root context plus the per-turn services. A loop
+     * constructed from the Context (no factory) can resolve the signal and sink
+     * here without importing this package.
+     */
+    turnScope(signal, sink) {
+        const scope = this.deps.ctx.scoped();
+        scope.provide(TURN_ABORT_SERVICE, signal);
+        scope.provide(TURN_SINK_SERVICE, sink);
+        scope.provide(USAGE_TRACKER_SERVICE, this.deps.usage);
+        return scope;
+    }
+    resolveLoop(signal, sink) {
+        const factory = this.deps.loopFactory;
+        if (factory !== undefined) {
+            const injections = this.deps.injections;
+            return factory({
+                config: this.deps.agentConfig,
+                signal,
+                sink,
+                usage: this.deps.usage,
+                ...(injections === undefined ? {} : { injections }),
+            });
+        }
+        const loop = this.deps.ctx.get(AGENT_LOOP_SERVICE);
+        if (loop === undefined) {
+            throw new ComposeError("no AgentLoop: pass a loopFactory or mount an agentLoopPlugin");
+        }
+        return loop;
+    }
+    /**
+     * W884: append the engine-owned turn context (the skill catalog). Blank rows
+     * are dropped, so a provider that has nothing to say is free to return [""].
+     */
+    injectTurnContext(log) {
+        for (const row of this.deps.turnContext?.() ?? []) {
+            if (row.text === "")
+                continue;
+            // W888: the origin travels with the row so the projection can label it.
+            log.append({ type: "user_message", text: row.text, origin: row.origin });
+        }
+    }
+    /** Turn-start drain: receipts and interjections land BEFORE the input. */
+    injectReceipts(log) {
+        for (const receipt of this.drainPending()) {
+            // W888: a worker receipt is NOT the human's voice.
+            log.append({ type: "user_message", text: formatReceipt(receipt), origin: "receipt" });
+        }
+    }
+    /** The single drain function shared by turn start and the step boundary. */
+    drainPending() {
+        return this.deps.drainPending?.() ?? [];
+    }
+}
+/** `[from W1] content` — the receipt attribution the host log shows verbatim. */
+export function formatReceipt(receipt) {
+    return receipt.from === "" ? receipt.text : `[from ${receipt.from}] ${receipt.text}`;
+}
+/**
+ * Link a caller signal into the turn's controller. Returns the cleanup that
+ * removes the listener again (P1-7, W836): `once:true` only removes it when the
+ * source DOES abort, so a host signal that outlives many turns would otherwise
+ * accumulate one listener per turn.
+ */
+export function linkAbort(source, target) {
+    if (source.aborted) {
+        target.abort();
+        return () => undefined;
+    }
+    const onAbort = () => target.abort();
+    source.addEventListener("abort", onAbort, { once: true });
+    return () => source.removeEventListener("abort", onAbort);
+}
+/**
+ * The terminal state of the turn that started at `from`: the LAST `turn_end`
+ * appended after that index, with legacy rows (missing outcome) defaulting to
+ * `completed` exactly like the JSONL codec does.
+ */
+export function lastTurnEndOutcome(events, from) {
+    for (let i = events.length - 1; i >= from; i--) {
+        const ev = events[i];
+        if (ev !== undefined && ev.type === "turn_end")
+            return ev.outcome ?? "completed";
+    }
+    return null;
+}
+/**
+ * Resolve the outcome of a finished turn:
+ *   1. a `turn_end` written by the loop wins — the log is the source of truth;
+ *   2. otherwise the turn never terminated: a thrown error propagates (a wiring
+ *      failure is not a terminal state), an aborted turn is `cancelled`, and a
+ *      silently-stopped turn is `interrupted` (a torn turn is never `completed`).
+ */
+export function resolveOutcome(events, from, signal, failure) {
+    const fromLog = lastTurnEndOutcome(events, from);
+    if (fromLog !== null)
+        return fromLog;
+    if (failure !== null && failure !== undefined)
+        throw failure;
+    return signal.aborted ? "cancelled" : "interrupted";
+}

package/dist/usage.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Usage accounting — the `usage` half of the statusline (W220/W263).
+ *
+ * The `AgentLoop` records the provider's `usage` stream event for every LLM
+ * response; the host reads two views:
+ *   - `latest()` — the most recent response (the context-usage surface is the
+ *     REAL prompt size of that request: `usage_prompt_tokens`, estimated:false);
+ *   - `total()`  — cumulative across every response of this generation.
+ *
+ * Both accessors return copies, so a caller can never mutate tracked state
+ * (`Usage` is `Copy` in the legacy engine).
+ *
+ * The seam is structural (`UsageRecorder` / `UsageAccounting`), not a class
+ * identity: `packages/agent-loop` ships its own `UsageTracker` with the same
+ * three methods, and the composition root may pass that instance in — the
+ * runtime then observes the very same object the loop writes to, with no
+ * cross-package type dependency.
+ */
+import { type Usage, type UsageBlock } from "@celestea/core";
+/** Write side of the seam: what an agent loop needs. */
+export interface UsageRecorder {
+    record(usage: Usage): void;
+}
+/** Read side: what the statusline / host needs in addition. */
+export interface UsageAccounting extends UsageRecorder {
+    latest(): Usage;
+    total(): Usage;
+}
+/** In-memory latest + cumulative tracker (the runtime's default implementation). */
+export declare class UsageTracker implements UsageAccounting {
+    private latestUsage;
+    private totalUsage;
+    record(usage: Usage): void;
+    latest(): Usage;
+    total(): Usage;
+    /** New-turn / new-generation baseline (the tracker keeps no history). */
+    reset(): void;
+}
+/** Factory form (ARCHITECTURE.md §6.1 `createXxx` convention). */
+export declare function createUsageTracker(): UsageTracker;
+/**
+ * `cache_read / prompt_tokens`, clamped to [0,1] and rounded to 4 decimals;
+ * 0 when the denominator is 0 (no usage recorded yet). `cache_hit_ratio`.
+ */
+export declare function cacheHitRatioRounded(u: Usage): number;
+/** One usage block: raw counters plus the derived cache-hit ratio. */
+export declare function usageBlock(u: Usage): UsageBlock;
+/**
+ * The statusline `usage` field: latest block + the same shape under `total`.
+ *
+ * W755 GUARDRAIL — `total` is a BILLING-shaped sum, NOT an occupancy reading.
+ * Every step of a turn re-sends the whole prompt, so `total.prompt_tokens` is
+ * O(steps x prompt): the DSH host's own ledger shows the same shape (13.7M
+ * uncached input / 1.09G cache-read over one long session) and it is several
+ * orders of magnitude away from the context window. Context occupancy is
+ * `context_usage` and ONLY `context_usage`
+ * (`packages/runtime/src/status.ts::contextUsage`, which uses `latest()` plus
+ * the visible growth since that sample). Never divide `total.prompt_tokens`,
+ * `total.cache_read` or `total.total_tokens` by a context window, and never
+ * render a context meter from this block.
+ */
+export declare function usageStatus(u: UsageAccounting): UsageBlock & {
+    total: UsageBlock;
+};

package/dist/usage.js

@@ -0,0 +1,88 @@
+/**
+ * Usage accounting — the `usage` half of the statusline (W220/W263).
+ *
+ * The `AgentLoop` records the provider's `usage` stream event for every LLM
+ * response; the host reads two views:
+ *   - `latest()` — the most recent response (the context-usage surface is the
+ *     REAL prompt size of that request: `usage_prompt_tokens`, estimated:false);
+ *   - `total()`  — cumulative across every response of this generation.
+ *
+ * Both accessors return copies, so a caller can never mutate tracked state
+ * (`Usage` is `Copy` in the legacy engine).
+ *
+ * The seam is structural (`UsageRecorder` / `UsageAccounting`), not a class
+ * identity: `packages/agent-loop` ships its own `UsageTracker` with the same
+ * three methods, and the composition root may pass that instance in — the
+ * runtime then observes the very same object the loop writes to, with no
+ * cross-package type dependency.
+ */
+import { usageAdd, zeroUsage } from "@celestea/core";
+/** In-memory latest + cumulative tracker (the runtime's default implementation). */
+export class UsageTracker {
+    latestUsage = zeroUsage();
+    totalUsage = zeroUsage();
+    record(usage) {
+        this.totalUsage = usageAdd(this.totalUsage, usage);
+        this.latestUsage = { ...usage };
+    }
+    latest() {
+        return { ...this.latestUsage };
+    }
+    total() {
+        return { ...this.totalUsage };
+    }
+    /** New-turn / new-generation baseline (the tracker keeps no history). */
+    reset() {
+        this.latestUsage = zeroUsage();
+        this.totalUsage = zeroUsage();
+    }
+}
+/** Factory form (ARCHITECTURE.md §6.1 `createXxx` convention). */
+export function createUsageTracker() {
+    return new UsageTracker();
+}
+/**
+ * `cache_read / prompt_tokens`, clamped to [0,1] and rounded to 4 decimals;
+ * 0 when the denominator is 0 (no usage recorded yet). `cache_hit_ratio`.
+ */
+export function cacheHitRatioRounded(u) {
+    if (u.prompt_tokens === 0)
+        return 0;
+    return round4(clamp01(u.cache_read / u.prompt_tokens));
+}
+/** One usage block: raw counters plus the derived cache-hit ratio. */
+export function usageBlock(u) {
+    return {
+        prompt_tokens: u.prompt_tokens,
+        completion_tokens: u.completion_tokens,
+        total_tokens: u.total_tokens,
+        cache_read: u.cache_read,
+        cache_hit_ratio: cacheHitRatioRounded(u),
+        reasoning_tokens: u.reasoning_tokens,
+    };
+}
+/**
+ * The statusline `usage` field: latest block + the same shape under `total`.
+ *
+ * W755 GUARDRAIL — `total` is a BILLING-shaped sum, NOT an occupancy reading.
+ * Every step of a turn re-sends the whole prompt, so `total.prompt_tokens` is
+ * O(steps x prompt): the DSH host's own ledger shows the same shape (13.7M
+ * uncached input / 1.09G cache-read over one long session) and it is several
+ * orders of magnitude away from the context window. Context occupancy is
+ * `context_usage` and ONLY `context_usage`
+ * (`packages/runtime/src/status.ts::contextUsage`, which uses `latest()` plus
+ * the visible growth since that sample). Never divide `total.prompt_tokens`,
+ * `total.cache_read` or `total.total_tokens` by a context window, and never
+ * render a context meter from this block.
+ */
+export function usageStatus(u) {
+    return { ...usageBlock(u.latest()), total: usageBlock(u.total()) };
+}
+function clamp01(v) {
+    if (!Number.isFinite(v) || v < 0)
+        return 0;
+    return v > 1 ? 1 : v;
+}
+function round4(v) {
+    return Math.round(v * 10_000) / 10_000;
+}