@celestea/agent-loop 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# @celestea/agent-loop
+
+The `AgentLoop` implementation: turn/step driving, context-budget trimming,
+cooperative cancellation and the five real terminal states. Depends only on
+`@celestea/core`; every collaborator (`Llm`, `SessionLog`, `ToolRegistry`) is
+resolved from the `Context` at turn start, so this package never imports a
+provider, a storage backend or a tool implementation.
+
+Ports (1:1 against the legacy engine unless listed under **Divergences**):
+
+| TS module | Legacy source |
+|---|---|
+| `loop.ts` (`DefaultAgentLoop`, the step loop) | `crates/agent-loop/src/loop.rs` (`impl AgentLoop for DefaultAgentLoop`) |
+| `step.ts` (per-step verdict types + folds) | inline in `loop.rs` |
+| `seams.ts` (Context → Llm/SessionLog/ToolRegistry) | `loop.rs:204-213` |
+| `cancel.ts` (checkpoints, synthetic result text) | `loop.rs:177-200` (`cancel_set` / `wait_cancel`, W267 constant) |
+| `context-trim.ts` (`estimate_*`, `trim_context`) | `crates/agent-loop/src/context.rs` (W220) |
+| `usage.ts` (`UsageTracker`) | `loop.rs:49-89` (W220) |
+| `events.ts` (`LoopEvent` builders + `EventSink`) | `crates/agent-loop/src/events.rs` |
+| `thinking.ts` (W252 thinking-burst aggregation) | `loop.rs:165-171` (`flush_thinking`) |
+| `plugin.ts` (`AGENT_LOOP_SERVICE` registration) | `crates/runtime/src/compose.rs:208-220` |
+| `sse.ts` (`LoopEvent` → SSE frame) | `celestea_studio/src/main.rs:667-713` (`loop_event_to_json`) |
+
+## Public API (via `index.ts` only)
+
+- **Loop** — `DefaultAgentLoop` (implements core's `AgentLoop`), with
+  `runTurn(ctx, input)` for the seam and `runTurnOutcome(ctx, input)` for hosts
+  that want the terminal state back; `AgentLoopBindings` = `{ signal?, sink?,
+  usage? }`; read-only `agentConfig` / `usageTracker` accessors.
+- **Plugin** — `agentLoopPlugin(config, bindings?, name?)` provides a loop under
+  core's `AGENT_LOOP_SERVICE` token; `createAgentLoop(config, bindings?)` builds
+  one without a Context. Mounting order is patch semantics: a later mount wins.
+- **Cancellation** — `CANCELLED_BEFORE_EXECUTION`, `raceAbort(signal, work)`,
+  `isAborted(signal)`, `closeIterator(iter)`, `errorMessage(err)`, `RaceResult`.
+- **Context budget** — `trimContext(messages, systemTokens, windowTokens,
+  threshold, keepRecent)` → `{ messages, outcome }`, `estimateTokens`,
+  `estimateMessageTokens`, `estimateMessagesTokens`, `trimmedMarkerMessage`,
+  `TrimOutcome`, `TrimResult`, `TRIMMED_MARKER_PREFIX`.
+- **Usage** — `UsageTracker` (`record` / `latest` / `total`) and
+  `createUsageTracker()`.
+- **Events** — `EventSink`, `toolCallEvent`, `toolResultEvent`, `doneEvent`,
+  `turnEndEvent`, `decisionLabel`.
+- **SSE** — `loopEventToSse(event)` → `{ event, payload }` (`SseFrame`).
+
+## Turn semantics (the five terminal states)
+
+One turn = `turn_start` + `user_message`, then up to `max_steps` model steps,
+then **exactly one** `turn_end`, written to the log and emitted to the sink from
+a single exit point. `max_steps === 0` means unlimited (W220). The terminal
+state is one of:
+
+| state | when |
+|---|---|
+| `completed` | the model answered without tool calls |
+| `cancelled` | the `AbortSignal` fired at any checkpoint |
+| `error{kind}` | `generate` failed before the stream, or `stream` failed mid-flight |
+| `step_limit` | the step budget ran out without a final answer — **never** `completed` |
+| `interrupted` | the stream ended without a terminal frame (torn/EOF) |
+
+A partial answer is never flushed as a reply, and `runTurn` only rejects with
+`AgentError` when the Context is missing a driver seam (`missing LlmService in
+context` / `missing SessionLog service in context` / `missing ToolRegistryService
+in context`) — terminal states always ride the log.
+
+Log ordering contracts (same as the legacy engine):
+
+- all `tool_call` rows of a step precede every `tool_result` row of that step;
+- results are appended in the model's call order even when dispatched in
+  parallel batches of `max_parallel_tool_calls` (clamped to ≥ 1);
+- thinking bursts are persisted **before** the reply / tool calls they precede;
+- derived history comes from `SessionLog.deriveMessages()` only — the loop never
+  keeps a second copy of the conversation. Tool-call merging is `session`'s job.
+
+## Cancellation
+
+Cooperative over an `AbortSignal`, re-checked at every await checkpoint:
+before generating, while consuming the stream (each `next()`), and while a tool
+batch is in flight. On a mid-dispatch cancel, every call of the step that has no
+real result yet gets a synthesized `tool_result` with
+`error = "cancelled before execution"` (W267), appended after the real results
+and before `turn_end`, in model order — the log stays protocol-valid (no
+dangling assistant `tool_calls`), and the sink receives the paired event.
+
+`raceAbort` never rejects: a rejected `work` returns `{ outcome: "failed" }`, so
+the loop keeps its state contract instead of leaking a seam exception. The
+abandoned provider stream is closed via `closeIterator`.
+
+## Thinking aggregation (W252) and deferred Done
+
+Streamed reasoning deltas are concatenated and flushed as **one**
+`thinking_delta` row per contiguous burst (boundaries: text / done / failed /
+interrupted / stream end / cancel); the live `thinking` event is still emitted
+per delta. The `done` event is **deferred until the stream truly ends**, so
+trailing reasoning that providers send after the finish frame still lands above
+the reply on the wire.
+
+## Usage
+
+Bind a `UsageTracker` and every `usage` stream event is recorded: `latest()` is
+the most recent response, `total()` the cumulative sum (detached copies, `Copy`
+semantics). Without a tracker, `usage` events are consumed and ignored.
+
+## Extension points
+
+```ts
+import { Context, mountPlugins, SESSION_LOG_SERVICE, TOOL_REGISTRY_SERVICE, LLM_SERVICE } from "@celestea/core";
+import { agentLoopPlugin, defaultAgentConfig, createUsageTracker } from "@celestea/agent-loop";
+
+const usage = createUsageTracker();
+const ctx = Context.root();
+// …mount the llm / session / tools plugins first (they provide the seams)…
+mountPlugins(ctx, [agentLoopPlugin(defaultAgentConfig({ max_steps: 32 }), { usage, signal: abort.signal, sink })]);
+```
+
+- **Another provider / storage / tool set** — mount a different plugin; this
+  package needs no change (no `if (provider === …)` anywhere).
+- **Another event transport** — pass your own `EventSink`; without one, events
+  are dropped (the host owns rendering).
+- **Another cancellation source** — pass any `AbortSignal` (HTTP request, CLI
+  ctrl-c, a worker watchdog); one controller can abort exactly one turn.
+- **Another trimming policy** — `trimContext` is a pure function; call it
+  directly or replace the call site in `buildRequest`.
+
+## Divergences from the legacy engine (deliberate, all documented in code)
+
+1. **Cancel signal**: `AbortSignal` owned by the caller instead of a
+   `tokio::sync::watch::Receiver` built by the loop.
+2. **No legacy stdout printer**: a missing sink drops events instead of printing
+   `text` / `[thinking] …` (product code must not write to stdout —
+   ARCHITECTURE.md §6.3).
+3. **`max_steps = 0` is unlimited** here (W220 semantics); the studio's
+   `MIN_STEPS = 4096` clamp belongs to the host, not the loop.
+4. **Trim marker text** is a single-spaced sentence; the legacy literal carried
+   the source indentation as runs of spaces. Contract-relevant part
+   (`[context-trimmed]`, counts, token estimate) is identical.
+5. **Torn stream after a `done` frame** ends the turn (with the stream's terminal
+   state) instead of dispatching that step's tool calls under a sticky error
+   outcome — a protocol-violating input that must not look successful.
+6. **Seam violation on dispatch**: a registry that throws is contained as a
+   `tool_result` error (the legacy loop would unwind), so the turn still reaches
+   a terminal state; a batch that somehow rejects is reported as `AgentError`.
+
+### P0 placeholder cleanup
+
+The P0 skeleton of this package exported `outcomePhase` / `outcomeError`
+(duplicates of `core`'s, now imported from there), plus `MIN_STEPS`,
+`STATUS_TICK_MS` and `createCancelSignal` — host-side loop scaffolding. All of
+them moved out in P1b: the five-state vocabulary lives in `core`, cancellation
+is an `AbortSignal` owned by the caller, and the studio's step clamp belongs to
+`apps/studio`. `loopEventToSse` kept its signature and now lives in `sse.ts`.
+
+## Tests
+
+`pnpm vitest run packages/agent-loop` — 56 cases across 7 files, all against
+fake `Llm` / `SessionLog` / `ToolRegistry` seam doubles (no network, no disk):
+`context-trim.test.ts` (estimate + trim matrix), `usage.test.ts`,
+`loop.test.ts` (stepping, five terminal states, TurnEnd uniqueness, deferred
+Done, thinking aggregation, unique turn ids), `loop-tools.test.ts` (dispatch
+order, batch concurrency, request building/trimming, usage), `cancel.test.ts`
+(before the turn / mid-stream / mid-dispatch + W267 synthesis),
+`events.test.ts` (builders + SSE mapping), `plugin.test.ts` (service token).
+
+## File layout
+
+```
+src/index.ts          public API (module map + re-exports)
+src/loop.ts           DefaultAgentLoop: turn bookkeeping + step loop
+src/step.ts           StepResult / GenerateResult / StreamOutcome + folds
+src/seams.ts          Context -> Llm / SessionLog / ToolRegistry, safe dispatch
+src/cancel.ts         AbortSignal checkpoints + W267 constant
+src/context-trim.ts   token estimate + trim_context
+src/usage.ts          UsageTracker
+src/events.ts         LoopEvent builders + EventSink
+src/thinking.ts       thinking-burst buffer (W252)
+src/plugin.ts         AGENT_LOOP_SERVICE registration
+src/sse.ts            LoopEvent -> SSE frame (contracts/sse-events.json)
+src/fakes.test-util.ts  seam doubles + turn harness for the tests
+```
+
+Size policy: every file ≤ 400 lines (max 292), every function ≤ 80 lines, no
+`ARCH_EXCEPTIONS` entry. `pnpm check` (typecheck + lint + lint:arch + test) is
+the gate.

package/dist/cancel.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cooperative cancellation — the AbortSignal counterpart of the legacy loop's
+ * `watch::Receiver<bool>` checkpoints (`cancel_set` / `wait_cancel`).
+ *
+ * The legacy loop awaited every interruptible step inside a `tokio::select!`
+ * against a cancellation future; the TS port races the same checkpoints against
+ * an [AbortSignal]. The differences are deliberate and documented in README.md:
+ *   - the signal is owned by the CALLER (host HTTP route / CLI), not built by
+ *     the loop, so one controller can abort a whole turn and be reused by the
+ *     next one;
+ *   - `raceAbort` never rejects: a rejected `work` is reported as
+ *     `{ outcome: "failed" }`, so the loop can keep the five-state contract
+ *     instead of leaking a seam exception;
+ *   - abandoning in-flight work must not raise an unhandled rejection, so the
+ *     loser of every race gets a no-op catch attached.
+ */
+/** W267: canonical error text of a synthesized ToolResult for a call that
+ * never ran because the turn was cancelled mid-dispatch. Shared by the session
+ * append and the emitted event so both sides carry the exact same string. */
+export declare const CANCELLED_BEFORE_EXECUTION = "cancelled before execution";
+/** Why an in-flight promise stopped being awaited. */
+export type RaceResult<T> = {
+    outcome: "ok";
+    value: T;
+} | {
+    outcome: "aborted";
+} | {
+    outcome: "failed";
+    error: unknown;
+};
+/** True when cancellation was already signalled (a synchronous checkpoint). */
+export declare function isAborted(signal: AbortSignal | undefined): boolean;
+/**
+ * Await `work`, but give up as soon as `signal` aborts. Re-checks the current
+ * value first, so it is safe to call at every checkpoint of a turn.
+ */
+export declare function raceAbort<T>(signal: AbortSignal | undefined, work: Promise<T>): Promise<RaceResult<T>>;
+/**
+ * Best-effort close of an async iterator abandoned on cancellation: releases
+ * the provider stream (and its socket) instead of leaving it suspended. A
+ * close failure is irrelevant to the turn, which is already terminal.
+ */
+export declare function closeIterator<T>(iter: AsyncIterator<T>): void;
+/** The message of a thrown value, for seam errors that arrive as `unknown`. */
+export declare function errorMessage(error: unknown): string;

package/dist/cancel.js

@@ -0,0 +1,71 @@
+/**
+ * Cooperative cancellation — the AbortSignal counterpart of the legacy loop's
+ * `watch::Receiver<bool>` checkpoints (`cancel_set` / `wait_cancel`).
+ *
+ * The legacy loop awaited every interruptible step inside a `tokio::select!`
+ * against a cancellation future; the TS port races the same checkpoints against
+ * an [AbortSignal]. The differences are deliberate and documented in README.md:
+ *   - the signal is owned by the CALLER (host HTTP route / CLI), not built by
+ *     the loop, so one controller can abort a whole turn and be reused by the
+ *     next one;
+ *   - `raceAbort` never rejects: a rejected `work` is reported as
+ *     `{ outcome: "failed" }`, so the loop can keep the five-state contract
+ *     instead of leaking a seam exception;
+ *   - abandoning in-flight work must not raise an unhandled rejection, so the
+ *     loser of every race gets a no-op catch attached.
+ */
+/** W267: canonical error text of a synthesized ToolResult for a call that
+ * never ran because the turn was cancelled mid-dispatch. Shared by the session
+ * append and the emitted event so both sides carry the exact same string. */
+export const CANCELLED_BEFORE_EXECUTION = "cancelled before execution";
+function ignore() {
+    // Deliberate no-op: the loser of a race only needs its rejection consumed.
+}
+function settled(work) {
+    return work.then((value) => ({ outcome: "ok", value }), (error) => ({ outcome: "failed", error }));
+}
+/** True when cancellation was already signalled (a synchronous checkpoint). */
+export function isAborted(signal) {
+    return signal !== undefined && signal.aborted;
+}
+/**
+ * Await `work`, but give up as soon as `signal` aborts. Re-checks the current
+ * value first, so it is safe to call at every checkpoint of a turn.
+ */
+export function raceAbort(signal, work) {
+    if (signal === undefined)
+        return settled(work);
+    if (signal.aborted) {
+        void work.catch(ignore);
+        return Promise.resolve({ outcome: "aborted" });
+    }
+    return new Promise((resolve) => {
+        const onAbort = () => {
+            void work.catch(ignore);
+            resolve({ outcome: "aborted" });
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        void work.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve({ outcome: "ok", value });
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve({ outcome: "failed", error });
+        });
+    });
+}
+/**
+ * Best-effort close of an async iterator abandoned on cancellation: releases
+ * the provider stream (and its socket) instead of leaving it suspended. A
+ * close failure is irrelevant to the turn, which is already terminal.
+ */
+export function closeIterator(iter) {
+    const close = iter.return;
+    if (close === undefined)
+        return;
+    void Promise.resolve(close.call(iter)).catch(ignore);
+}
+/** The message of a thrown value, for seam errors that arrive as `unknown`. */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/context-trim.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Context-budget utilities for the agent loop — port of
+ * `crates/agent-loop/src/context.rs` (W220).
+ *
+ * Token estimation operates on the model-facing messages only and decides
+ * *when* to trim; it is deliberately approximate (UTF-8 bytes / 4) and never
+ * used to bill or to report usage. Real numbers come from the provider
+ * (`core.Usage`) and are handled by [UsageTracker].
+ *
+ * W762: the trim pass is O(n). It used to score EVERY candidate cut with
+ * `estimateMessagesTokens(rest.slice(candidate))` — an O(n) estimate plus an
+ * array allocation per candidate, i.e. O(n²) time and O(n) allocations for one
+ * pass, which the statusline paid on every tick once a session went over budget
+ * (measured: 5k messages ≈ 0.8 s, 10k-event session ≈ 1.0 s per tick). The pass
+ * now pre-computes suffix token sums once (`suffix[i] = Σ_{j>=i} tokens`) and
+ * scores each candidate in O(1); `removedTokens` is a suffix difference instead
+ * of a second full estimate. `pickCut` / `safeCutPositions` are unchanged, so
+ * the chosen cut is bit-for-bit the same as before.
+ *
+ * Contract notes (all mirrored by unit tests, same as the legacy module):
+ *   - `contextWindowTokens === 0` disables trimming entirely;
+ *   - over budget, the `contextKeepRecent` most-recent messages survive, plus
+ *     every `system` message (always kept, always first);
+ *   - removal is marked with ONE short system message so the model knows;
+ *   - every cut lands on a system/user boundary, so an assistant tool-call
+ *     group is never split and the history never starts with an orphan tool
+ *     message.
+ */
+import { type Message } from "@celestea/core";
+/** W804: fixed overhead of one image block in the estimate. */
+export declare const IMAGE_BASE_TOKENS = 85;
+/** W804: coarse area divisor used to estimate an image block's token cost. */
+export declare const IMAGE_PIXEL_DIVISOR = 750;
+/** Marker text prefix (contract: consumers key off `[context-trimmed]`). */
+export declare const TRIMMED_MARKER_PREFIX = "[context-trimmed]";
+/** Estimate the token count of a text fragment (UTF-8 bytes / 4, rounded up). */
+export declare function estimateTokens(text: string): number;
+/** Estimate the token count of one message (content + structural overhead). */
+export declare function estimateMessageTokens(msg: Message): number;
+/**
+ * W804: coarse token estimate of one image block (fixed overhead + area term).
+ * It is deliberately approximate, exactly like [estimateTokens]: it decides WHEN
+ * to trim, never what the provider bills.
+ */
+export declare function estimateImageTokens(width: number, height: number): number;
+/**
+ * W889: the per-message estimator is INJECTABLE so a caller (test, diagnostic)
+ * can count how many times the trim pass estimates — the deterministic stand-in
+ * for the old wall-clock "linear-ish" guard. The default is the real estimator,
+ * so production behaviour is unchanged.
+ */
+export type MessageEstimator = (msg: Message) => number;
+/**
+ * Run `fn` with an injected estimator, restoring the previous one afterwards.
+ * Scoped (not a bare setter) so a counter can never leak into another test.
+ */
+export declare function withMessageEstimator<T>(estimate: MessageEstimator, fn: () => T): T;
+/** Estimate the total token count of a message list (estimator injectable). */
+export declare function estimateMessagesTokens(messages: readonly Message[], estimate?: MessageEstimator): number;
+/** The outcome of one trim pass over the derived history (`TrimOutcome`). */
+export interface TrimOutcome {
+    /** How many messages were removed (0 = nothing trimmed). */
+    removedMessages: number;
+    /** Estimated tokens of the removed messages. */
+    removedTokens: number;
+    /** True when the history was actually trimmed this pass. */
+    trimmed: boolean;
+}
+/** The trimmed history plus what the pass did. */
+export interface TrimResult {
+    messages: Message[];
+    outcome: TrimOutcome;
+}
+/**
+ * Mark the removal of earlier messages with one short system message, so the
+ * model knows older context was dropped instead of silently missing it.
+ */
+export declare function trimmedMarkerMessage(removedMessages: number, removedTokens: number): Message;
+/**
+ * Trim an over-budget message history to fit the context window (W220 v1).
+ *
+ * `systemTokens` is the estimated size of the outside system prompt
+ * (`ModelRequest.system`): it is never trimmed but counts into the budget.
+ */
+export declare function trimContext(messages: readonly Message[], systemTokens: number, contextWindowTokens: number, threshold: number, keepRecent: number): TrimResult;

package/dist/context-trim.js

@@ -0,0 +1,219 @@
+/**
+ * Context-budget utilities for the agent loop — port of
+ * `crates/agent-loop/src/context.rs` (W220).
+ *
+ * Token estimation operates on the model-facing messages only and decides
+ * *when* to trim; it is deliberately approximate (UTF-8 bytes / 4) and never
+ * used to bill or to report usage. Real numbers come from the provider
+ * (`core.Usage`) and are handled by [UsageTracker].
+ *
+ * W762: the trim pass is O(n). It used to score EVERY candidate cut with
+ * `estimateMessagesTokens(rest.slice(candidate))` — an O(n) estimate plus an
+ * array allocation per candidate, i.e. O(n²) time and O(n) allocations for one
+ * pass, which the statusline paid on every tick once a session went over budget
+ * (measured: 5k messages ≈ 0.8 s, 10k-event session ≈ 1.0 s per tick). The pass
+ * now pre-computes suffix token sums once (`suffix[i] = Σ_{j>=i} tokens`) and
+ * scores each candidate in O(1); `removedTokens` is a suffix difference instead
+ * of a second full estimate. `pickCut` / `safeCutPositions` are unchanged, so
+ * the chosen cut is bit-for-bit the same as before.
+ *
+ * Contract notes (all mirrored by unit tests, same as the legacy module):
+ *   - `contextWindowTokens === 0` disables trimming entirely;
+ *   - over budget, the `contextKeepRecent` most-recent messages survive, plus
+ *     every `system` message (always kept, always first);
+ *   - removal is marked with ONE short system message so the model knows;
+ *   - every cut lands on a system/user boundary, so an assistant tool-call
+ *     group is never split and the history never starts with an orphan tool
+ *     message.
+ */
+import { isImageContent, isTextContent, isToolCallContent, serdeJsonString, systemMessage, } from "@celestea/core";
+/** Per-message structural overhead (role + framing) in the estimate. */
+const MESSAGE_OVERHEAD_TOKENS = 4;
+/** Per-tool-call structural overhead in the estimate. */
+const TOOL_CALL_OVERHEAD_TOKENS = 10;
+/** W804: fixed overhead of one image block in the estimate. */
+export const IMAGE_BASE_TOKENS = 85;
+/** W804: coarse area divisor used to estimate an image block's token cost. */
+export const IMAGE_PIXEL_DIVISOR = 750;
+/** Marker text prefix (contract: consumers key off `[context-trimmed]`). */
+export const TRIMMED_MARKER_PREFIX = "[context-trimmed]";
+/** Estimate the token count of a text fragment (UTF-8 bytes / 4, rounded up). */
+export function estimateTokens(text) {
+    const bytes = Buffer.byteLength(text, "utf8");
+    return Math.ceil(bytes / 4);
+}
+/** Estimate the token count of one message (content + structural overhead). */
+export function estimateMessageTokens(msg) {
+    let total = MESSAGE_OVERHEAD_TOKENS;
+    for (const content of msg.content) {
+        if (isTextContent(content))
+            total += estimateTokens(content.content);
+        else if (isToolCallContent(content)) {
+            const call = content.content;
+            total += TOOL_CALL_OVERHEAD_TOKENS + estimateTokens(call.name) + estimateTokens(serdeJsonString(call.args));
+        }
+        else if (isImageContent(content)) {
+            // W804 (R8): an image block MUST contribute tokens, otherwise the trim
+            // systematically under-counts and can send an over-window request. P0 has
+            // no decoder here, so the estimate is fixed overhead + a coarse area term.
+            total += estimateImageTokens(content.content.width, content.content.height);
+        }
+    }
+    if (msg.tool_call_id !== null)
+        total += estimateTokens(msg.tool_call_id);
+    return total;
+}
+/**
+ * W804: coarse token estimate of one image block (fixed overhead + area term).
+ * It is deliberately approximate, exactly like [estimateTokens]: it decides WHEN
+ * to trim, never what the provider bills.
+ */
+export function estimateImageTokens(width, height) {
+    const w = Number.isFinite(width) && width > 0 ? width : 0;
+    const h = Number.isFinite(height) && height > 0 ? height : 0;
+    return IMAGE_BASE_TOKENS + Math.ceil((w * h) / IMAGE_PIXEL_DIVISOR);
+}
+/**
+ * W889: the estimator the trim pass uses. Injectable via [withMessageEstimator]
+ * so a caller can COUNT estimates (the deterministic complexity guard).
+ */
+let activeEstimator = estimateMessageTokens;
+/**
+ * Run `fn` with an injected estimator, restoring the previous one afterwards.
+ * Scoped (not a bare setter) so a counter can never leak into another test.
+ */
+export function withMessageEstimator(estimate, fn) {
+    const previous = activeEstimator;
+    activeEstimator = estimate;
+    try {
+        return fn();
+    }
+    finally {
+        activeEstimator = previous;
+    }
+}
+/** Estimate the total token count of a message list (estimator injectable). */
+export function estimateMessagesTokens(messages, estimate = estimateMessageTokens) {
+    let total = 0;
+    for (const msg of messages)
+        total += estimate(msg);
+    return total;
+}
+const NOT_TRIMMED = { removedMessages: 0, removedTokens: 0, trimmed: false };
+/**
+ * Mark the removal of earlier messages with one short system message, so the
+ * model knows older context was dropped instead of silently missing it.
+ */
+export function trimmedMarkerMessage(removedMessages, removedTokens) {
+    return systemMessage(`${TRIMMED_MARKER_PREFIX} Earlier conversation was trimmed to fit the context budget: ` +
+        `${removedMessages} message(s) ~${removedTokens} tokens removed. Continue from the recent ` +
+        "messages below; ask the user to restate any earlier detail you need.");
+}
+function isCutBoundary(role) {
+    return role === "system" || role === "user";
+}
+/** Indices of `rest` where a protocol-safe suffix may start. */
+function safeCutPositions(rest) {
+    const cuts = [];
+    for (let i = 0; i < rest.length; i++) {
+        const role = rest[i]?.role;
+        if (role !== undefined && isCutBoundary(role))
+            cuts.push(i);
+    }
+    return cuts;
+}
+/**
+ * Pick the cut index: prefer keeping exactly `keepRecent` messages, trim
+ * further when that suffix is still over budget (keep the most that fits), and
+ * fall back to the last safe boundary when nothing fits.
+ */
+function pickCut(cuts, keepRecent, fits) {
+    const withinKeep = cuts.find((c) => c >= keepRecent);
+    const fitsBudget = cuts.find((c) => fits(c));
+    if (withinKeep !== undefined && fitsBudget !== undefined)
+        return withinKeep >= fitsBudget ? withinKeep : fitsBudget;
+    if (withinKeep !== undefined)
+        return withinKeep;
+    if (fitsBudget !== undefined)
+        return fitsBudget;
+    return cuts[cuts.length - 1] ?? 0;
+}
+/**
+ * Trim an over-budget message history to fit the context window (W220 v1).
+ *
+ * `systemTokens` is the estimated size of the outside system prompt
+ * (`ModelRequest.system`): it is never trimmed but counts into the budget.
+ */
+export function trimContext(messages, systemTokens, contextWindowTokens, threshold, keepRecent) {
+    if (contextWindowTokens === 0)
+        return { messages: [...messages], outcome: NOT_TRIMMED };
+    const budget = Math.max(1, Math.floor(contextWindowTokens * Math.min(Math.max(threshold, 0), 1)));
+    // Unchanged fast path: one O(n) estimate, no split, no suffix (the common case
+    // of a session inside its budget must not pay for the trim machinery).
+    if (systemTokens + estimateMessagesTokens(messages, activeEstimator) <= budget) {
+        return { messages: [...messages], outcome: NOT_TRIMMED };
+    }
+    const split = splitHistory(messages, activeEstimator);
+    const systems = split.systems;
+    const rest = split.rest;
+    if (rest.length === 0)
+        return { messages: [...systems], outcome: NOT_TRIMMED };
+    const cuts = safeCutPositions(rest);
+    // No safe boundary: refuse to risk breaking the tool-call protocol.
+    if (cuts.length === 0)
+        return { messages: [...systems, ...rest], outcome: NOT_TRIMMED };
+    // W762: one O(n) pass, then every `fits(candidate)` is an O(1) array read.
+    const suffix = suffixTokenSums(split.restTokens);
+    const keep = Math.max(1, keepRecent);
+    // W813 P2-trimContext: the predicate must score the request the cut ACTUALLY
+    // produces, not just its non-system suffix. Two parts always travel next to
+    // that suffix and both used to be dropped from the budget:
+    //   - every history system message: kept and prepended unconditionally;
+    //   - the one trim marker: inserted unconditionally whenever anything is cut.
+    // The marker carries this candidate's own removed message/token counts, so it
+    // is scored exactly (a few characters, still O(1)); the suffix stays a read.
+    const fixedTokens = systemTokens + estimateMessagesTokens(systems, activeEstimator);
+    const cut = pickCut(cuts, Math.max(0, rest.length - keep), (candidate) => {
+        const candidateRemovedTokens = (suffix[0] ?? 0) - (suffix[candidate] ?? 0);
+        const markerTokens = activeEstimator(trimmedMarkerMessage(candidate, candidateRemovedTokens));
+        return fixedTokens + markerTokens + (suffix[candidate] ?? 0) <= budget;
+    });
+    // `suffix[0] - suffix[cut]` IS `estimateMessagesTokens(rest.slice(0, cut))`:
+    // both are the sum of the same per-message estimates (W762).
+    const removedTokens = (suffix[0] ?? 0) - (suffix[cut] ?? 0);
+    const outcome = { removedMessages: cut, removedTokens, trimmed: cut > 0 };
+    if (!outcome.trimmed)
+        return { messages: [...systems, ...rest], outcome: NOT_TRIMMED };
+    return {
+        messages: [...systems, trimmedMarkerMessage(outcome.removedMessages, outcome.removedTokens), ...rest.slice(cut)],
+        outcome,
+    };
+}
+/** Split the history in ONE pass, estimating each non-system message once. */
+function splitHistory(messages, estimate) {
+    const systems = [];
+    const rest = [];
+    const restTokens = [];
+    for (const msg of messages) {
+        if (msg.role === "system")
+            systems.push(msg);
+        else {
+            rest.push(msg);
+            restTokens.push(estimate(msg));
+        }
+    }
+    return { systems, rest, restTokens };
+}
+/**
+ * W762: suffix token sums — `suffix[i]` is the estimated size of `tokens[i..]`,
+ * with `suffix[tokens.length] === 0`. Token counts are non-negative, so the sum
+ * is non-increasing in `i`: "does this cut fit?" is monotone, and scoring a
+ * candidate costs one array read instead of a full re-estimate.
+ */
+function suffixTokenSums(tokens) {
+    const suffix = new Array(tokens.length + 1).fill(0);
+    for (let i = tokens.length - 1; i >= 0; i -= 1) {
+        suffix[i] = (suffix[i + 1] ?? 0) + (tokens[i] ?? 0);
+    }
+    return suffix;
+}

package/dist/events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Turn-level event plumbing — port of `crates/agent-loop/src/events.rs`.
+ *
+ * A running turn delivers every [LoopEvent] it produces to an injected
+ * [EventSink], in log order: the LLM stream deltas (text / thinking / done)
+ * plus the tool lifecycle (tool_call + the FULL ToolOutput of every result) so
+ * a rich UI can draw tool cards without scraping the session log.
+ *
+ * P0-A: every started turn emits exactly ONE terminal
+ * `{ kind: "turn_end" }` carrying the real terminal state — consumers map it
+ * onto their "done"/status envelope, so cancelled / error / step-limit /
+ * interrupted turns can never be mistaken for completed ones.
+ *
+ * The builders below are the only place where core values become events, so
+ * the log and the event stream can never drift apart.
+ */
+import { type LoopEvent, type Message, type ToolCall, type ToolDecision, type ToolOutput, type TurnOutcome } from "@celestea/core";
+/** A sink receives every LoopEvent of a turn, in log order. */
+export type EventSink = (event: LoopEvent) => void;
+/** `Some(ToolDecision::Allow)` -> `"allow"`: the flat label of the SSE payload. */
+export declare function decisionLabel(decision: ToolDecision | null): "allow" | "deny" | "ask" | null;
+export declare function toolCallEvent(call: ToolCall): LoopEvent;
+/** The full ToolOutput rides the event: value, authored render, error, verdict. */
+export declare function toolResultEvent(output: ToolOutput): LoopEvent;
+/** The authoritative assistant reply of one model step (not terminal). */
+export declare function doneEvent(message: Message): LoopEvent;
+/** The single terminal verdict of the turn. */
+export declare function turnEndEvent(outcome: TurnOutcome): LoopEvent;