indusagi-coding-agent 0.1.58 → 0.1.60

package/dist/types/transcript-export/theme-bridge.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ThemeBridge — the color service behind the HTML transcript export.
+ *
+ * Everything the publisher needs to turn an {@link ExportTheme} token bag into
+ * concrete page colors lives here: parsing CSS colors into {@link Rgb}, measuring
+ * a color's WCAG relative luminance through a precomputed lookup table, deciding
+ * whether the theme reads {@link ThemeMode} light or dark, deriving lighter/darker
+ * surface variants from a base, and projecting the whole theme to the CSS custom
+ * properties the page shell consumes.
+ *
+ * Two facts are interface-dictated and kept faithful:
+ *   - The WCAG relative-luminance formula — linearize each sRGB channel with the
+ *     gamma piecewise curve, then weight `0.2126 R + 0.7152 G + 0.0722 B`. The
+ *     per-channel linearization is precomputed once into {@link buildLuminanceLut}
+ *     (a {@link LuminanceLut}) so a luminance read is three table lookups plus a
+ *     weighted sum, never a `pow` per pixel.
+ *   - Readable foreground selection — given a background, pick the foreground
+ *     (from the theme's own ink choices) whose contrast against that background is
+ *     the larger, so text on any derived surface stays legible.
+ *
+ * Every default color the bridge falls back to is this rebuild's own
+ * {@link FALLBACK_EXPORT_THEME} (a deep-slate palette), never a legacy export's
+ * magic constant.
+ */
+import { type ExportTheme, type LuminanceLut, type Rgb, type ThemeBridge, type ThemeMode } from "../briefing/contract";
+/**
+ * Build the 256-entry sRGB→linear lookup table the WCAG relative-luminance
+ * formula needs for each channel.
+ *
+ * For a channel value `v` in `0–255`, normalize to `s = v / 255`, then apply the
+ * standard gamma-expansion: `s ≤ 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ^
+ * 2.4`. The table holds the linearized value at each integer channel so a
+ * luminance read avoids the per-call `pow`. The math is the published standard's;
+ * the table is this module's.
+ */
+export declare function buildLuminanceLut(): Float64Array;
+/**
+ * Parse a CSS color string into its {@link Rgb} channels. Recognizes `#rgb`,
+ * `#rrggbb` (and their alpha-bearing `#rgba` / `#rrggbbaa` forms, alpha dropped)
+ * and the functional `rgb(r, g, b)` / `rgba(r, g, b, a)` notations. Any
+ * unrecognized input resolves to `null`, which the bridge treats as "fall back to
+ * the theme default" rather than throwing.
+ *
+ * @param color a CSS color string
+ */
+export declare function parseColor(color: string): Rgb | null;
+/** Render an {@link Rgb} back to a `#rrggbb` CSS string. */
+export declare function formatColor(rgb: Rgb): string;
+/**
+ * The concrete {@link ThemeBridge}. Holds a resolved {@link ExportTheme} and a
+ * {@link LuminanceLut}, and serves every color query the publisher makes against
+ * them. Pure with respect to its inputs — construction resolves the theme once and
+ * the methods only read.
+ */
+export declare class DefaultThemeBridge implements ThemeBridge {
+    readonly theme: ExportTheme;
+    private readonly lut;
+    /**
+     * @param theme an {@link ExportTheme} to serve; defaults to the rebuild's own
+     *   {@link FALLBACK_EXPORT_THEME}.
+     * @param lut   the luminance lookup table to read; defaults to the shared
+     *   module-level table.
+     */
+    constructor(theme?: ExportTheme, lut?: LuminanceLut);
+    /** The WCAG relative luminance (0–1) of a CSS color; unparseable input reads 0. */
+    luminance(color: string): number;
+    /** Whether the theme's page surface reads light or dark. */
+    mode(): ThemeMode;
+    /**
+     * Derive a surface variant from a base color. The `amount` is a signed lightness
+     * delta in channel space; the sign is honored directly so a caller can lighten
+     * (`+`) or darken (`−`) explicitly. When `amount` is `0` the base is returned
+     * formatted but unchanged. Unparseable bases fall through to the theme's card
+     * surface so a derivation never yields an empty string.
+     *
+     * @param base   the base CSS color to adjust
+     * @param amount signed lightness delta (positive lightens, negative darkens)
+     */
+    deriveSurface(base: string, amount: number): string;
+    /**
+     * Pick the more readable of the theme's two ink colors for a given background by
+     * comparing each ink's WCAG contrast against it and returning the higher. This
+     * is the bridge's own readable-foreground chooser — used when text sits on a
+     * derived surface whose lightness is not known ahead of time.
+     *
+     * @param background the surface the text will sit on
+     */
+    readableInk(background: string): string;
+    /** Project the theme to its CSS custom properties, keyed by token name. */
+    toCssVars(): Readonly<Record<string, string>>;
+}
+/**
+ * Build a {@link ThemeBridge} over an optional {@link ExportTheme}. The convenience
+ * factory the publisher calls; omitting the theme yields a bridge over the
+ * rebuild's own fallback palette.
+ *
+ * @param theme an export palette to serve, or undefined for the fallback
+ */
+export declare function createThemeBridge(theme?: ExportTheme): ThemeBridge;

package/dist/types/transcript-export/transcript-export.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Transcript-export subsystem — Phase 9 behavioral tests.
+ *
+ * Three concerns, exercised purely (no disk, no network):
+ *   1. {@link paintSgr} — the table-driven SGR machine turns an ANSI string
+ *      (bold + red foreground + a 256-color index) into HTML spans carrying this
+ *      page's own `sgr-*` classes and resolved colors, and a reset returns the
+ *      text to a bare (span-less) run.
+ *   2. {@link DefaultThemeBridge} — picks a readable foreground for a dark and a
+ *      light background through the WCAG luminance LUT, and never resolves to a
+ *      forbidden upstream color (#343541 / rgb(24,24,30)).
+ *   3. {@link publishTranscript} — renders a small transcript to a self-contained
+ *      HTML string carrying the new token/class names, the marked-rendered
+ *      markdown, and none of the upstream magic colors.
+ */
+export {};

package/dist/types/window-budget/budget/estimate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Token estimation — the heuristic "meter stick" for the window-budget
+ * subsystem.
+ *
+ * Before we can decide whether the transcript is over budget (gate.ts) or where
+ * to slice it (slice.ts), we need a cheap, deterministic estimate of how many
+ * tokens each {@link AgentMessage} occupies. We do *not* call a tokenizer; we
+ * walk the serialized content and apply a small, transparent weighting model.
+ *
+ * Design notes (clean-room, deliberately distinct from any chars/4 + flat-image
+ * baseline):
+ *   - The estimate is computed over a *serialization* of each message's
+ *     payload, not over a JSON blob of the whole object — structural framing
+ *     (braces, quotes, field names) is accounted for with small per-block adds
+ *     rather than being measured character-for-character.
+ *   - Constants below are this module's OWN tunables (a fractional
+ *     bytes-per-token divisor plus per-block framing adds and a flat image
+ *     cost). They are intentionally not the legacy fingerprint values.
+ *   - The estimator is conservative (rounds up, adds framing) so the gate fires
+ *     a little early rather than a little late — overflowing the window is worse
+ *     than condensing one turn sooner than strictly necessary.
+ */
+import type { AgentMessage } from "../contract.js";
+/**
+ * Estimate the token cost of one message in isolation. Exposed so the slice
+ * planner can build a prefix-sum without re-deriving the per-message weight.
+ *
+ * Cost = `ceil(serialized_chars / CHARS_PER_TOKEN)` + framing tokens +
+ * `images * IMAGE_TOKENS`. Always `>= 0` and biased high (conservative).
+ */
+export declare function estimateMessageTokens(message: AgentMessage): number;
+/**
+ * Estimate the total token cost of a transcript: the sum of every message's
+ * {@link estimateMessageTokens}. This is a pure heuristic — the gate prefers a
+ * provider-anchored figure when one exists, and only falls back to this.
+ */
+export declare function estimateTokens(messages: AgentMessage[]): number;
+/**
+ * Build a FORWARD prefix-sum array of per-message token estimates.
+ *
+ * Returns an array of length `messages.length + 1` where `result[i]` is the
+ * total estimated tokens of `messages[0 .. i)` (so `result[0] === 0` and
+ * `result[messages.length] === estimateTokens(messages)`). This monotonically
+ * non-decreasing array is exactly what {@link planSlice} binary-searches to find
+ * the cut boundary in O(log n).
+ */
+export declare function prefixTokens(messages: AgentMessage[]): number[];

package/dist/types/window-budget/budget/gate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Budget gate — the trigger predicate for the window-budget subsystem.
+ *
+ * {@link isOverBudget} answers the single question "is the transcript large
+ * enough that we should condense before the next turn?" by comparing a token
+ * estimate against a window-relative threshold derived from the model's
+ * `contextWindow` and the caller-supplied {@link BudgetPolicy}.
+ *
+ * The threshold is computed as:
+ *
+ *     limit = (contextWindow - reserveTokens?) * triggerRatio
+ *
+ * i.e. optional fixed headroom is carved off the window first, then the
+ * remaining capacity is scaled by the window-relative trigger ratio. This keeps
+ * the trigger free of baked-in token counts — `triggerRatio` lives in `(0, 1]`
+ * and `reserveTokens` is an optional config value, never a fingerprint constant.
+ */
+import type { AgentMessage, BudgetPolicy, Model } from "../contract.js";
+import type { Api } from "indusagi/ai";
+/**
+ * Compute the absolute token limit at which condensing should fire for a given
+ * model and policy. Exposed for callers that want the number itself (e.g. to
+ * display headroom) rather than just the boolean.
+ *
+ * `reserveTokens` (when present) is subtracted from the window before the ratio
+ * is applied; the result is floored at `0` so a misconfigured reserve larger
+ * than the window can never yield a negative limit.
+ */
+export declare function budgetLimit(model: Model<Api>, policy: BudgetPolicy): number;
+/**
+ * Decide whether the transcript is over budget for the given model and policy.
+ *
+ * Uses the heuristic {@link estimateTokens} over the serialized transcript and
+ * compares it to {@link budgetLimit}. Returns `true` once the estimate strictly
+ * exceeds the limit — the signal the conductor uses to kick off a condense.
+ */
+export declare function isOverBudget(messages: AgentMessage[], model: Model<Api>, policy: BudgetPolicy): boolean;

package/dist/types/window-budget/budget/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Window-budget / budget — pure budget math.
+ *
+ * The arithmetic core of the window-budget subsystem, free of I/O, prompts, and
+ * model calls:
+ *   - {@link estimateTokens} / {@link estimateMessageTokens} / {@link prefixTokens}
+ *     — heuristic token measurement and the forward cumulative-token array.
+ *   - {@link isOverBudget} / {@link budgetLimit} — the window-relative trigger.
+ *   - {@link planSlice} — forward prefix-sum + binary-search cut planning that
+ *     never splits a tool_call from its tool_result.
+ */
+export { estimateMessageTokens, estimateTokens, prefixTokens } from "./estimate.js";
+export { budgetLimit, isOverBudget } from "./gate.js";
+export { planSlice } from "./slice.js";

package/dist/types/window-budget/budget/slice.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Slice planner — decides *where* to cut the transcript when it is over budget.
+ *
+ * {@link planSlice} partitions a transcript into a `dropped` prefix (older
+ * messages destined for a summary) and a `kept` suffix (the verbatim recent
+ * tail), choosing the boundary so the tail holds roughly `policy.keepRecent`
+ * tokens. It does this with a FORWARD prefix-sum + BINARY SEARCH (not a backward
+ * accumulate-and-snap):
+ *
+ *   1. Build the cumulative-token array `prefix` (forward, monotonic).
+ *   2. The total is `prefix[n]`; we want the tail to be ~`keepRecent` tokens, so
+ *      the *ideal* cut sits at the first index `i` whose suffix
+ *      `prefix[n] - prefix[i]` has fallen to `<= keepRecent`. Equivalently, the
+ *      first `i` with `prefix[i] >= prefix[n] - keepRecent`. That predicate is
+ *      monotonic in `i`, so we BINARY-SEARCH the lower bound of the threshold
+ *      `prefix[n] - keepRecent` over `prefix`.
+ *   3. Snap the resulting index FORWARD to the nearest *legal* boundary so we
+ *      never land between a tool_call and its matching tool_result. A boundary
+ *      is legal iff the message it lands on is not a `toolResult` (a tool result
+ *      always belongs with the assistant turn that issued the call, so the tail
+ *      may never begin with one).
+ *
+ * If the whole transcript already fits within `keepRecent`, or snapping forward
+ * consumes everything, the cut is `0` (nothing condensable — keep it all).
+ */
+import type { AgentMessage, BudgetPolicy, CondensePlan } from "../contract.js";
+/**
+ * Plan the condense slice for a transcript under a {@link BudgetPolicy}.
+ *
+ * Chooses the cut via forward prefix-sum + binary search for the boundary that
+ * keeps ~`policy.keepRecent` recent tokens, then snaps that boundary forward to
+ * a legal point (never between a tool_call and its tool_result).
+ *
+ * @returns a {@link CondensePlan} with the chosen `cut`, the `kept` tail
+ *          (`messages.slice(cut)`) and the `dropped` head (`messages.slice(0, cut)`).
+ *          `cut === 0` when nothing is condensable.
+ */
+export declare function planSlice(messages: AgentMessage[], policy: BudgetPolicy): CondensePlan;

package/dist/types/window-budget/condenser.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Window-budget — the condenser factory (the conductor-consumable seam).
+ *
+ * {@link createCondenser} ties the three pure pieces together into a single
+ * function the conductor can drop into its auto-compaction hook:
+ *
+ *   1. **Gate**   — {@link isOverBudget} asks "is this transcript large enough to
+ *      condense?" against the bound model's window and the {@link BudgetPolicy}.
+ *   2. **Slice**  — {@link planSlice} splits the transcript into a `dropped` head
+ *      (older turns to fold away) and a verbatim `kept` tail, never cutting
+ *      between a `toolCall` and its `toolResult`.
+ *   3. **Condense** — {@link summarize} turns the dropped head into one synthetic
+ *      digest message (scope `"session"`), via the injectable model completer.
+ *
+ * The returned value is a {@link Condenser} — structurally a conductor
+ * `CondenseFn` `(messages) => AgentMessage[] | Promise<AgentMessage[]>`:
+ *   - When over budget it returns `[summaryMessage, ...kept]` (a strictly smaller
+ *     transcript: one digest in place of the dropped prefix, plus the recent tail).
+ *   - Otherwise it returns the input list unchanged (the no-op identity the
+ *     conductor expects when nothing needs doing).
+ *
+ * It is **network-free-testable**: with no `model` bound the gate cannot measure a
+ * window, so the condenser is an identity transform; inject a {@link CompleteFn}
+ * stub (and a `model`) to drive the summary path with no real API call.
+ *
+ * Branch-archival is *not* a second engine — {@link condenseScope} forwards to the
+ * shared {@link summarize} core pinned to scope `"branch"`. {@link condense} is the
+ * matching session-scope entrypoint. Both are re-exported here so callers can
+ * summarize a slice directly without building a full {@link Condenser}.
+ */
+import type { AgentMessage, CondenserDeps, Condenser, Summary } from "./contract.js";
+import { condenseScope, type SummarizeDeps } from "./summarize/index.js";
+/**
+ * Build a {@link Condenser} from a {@link CondenserDeps} bundle. The result plugs
+ * straight into the conductor's `CondenseFn` seam.
+ *
+ * Behavior of the returned condenser, given a transcript `messages`:
+ *   - If no `model` is bound (so the window is unknown), or the transcript is
+ *     **not** over budget, return `messages` **unchanged**.
+ *   - Otherwise {@link planSlice} the transcript; if there is nothing to drop
+ *     (`cut === 0`) return it unchanged; else {@link summarize} the dropped head
+ *     (scope `"session"`) and return `[summary.message, ...plan.kept]`.
+ *
+ * All dependencies are optional, so `createCondenser()` yields a working,
+ * network-free condenser (a no-op until a model and policy are supplied).
+ */
+export declare function createCondenser(deps?: CondenserDeps): Condenser;
+/**
+ * Session-scope summarization: fold a slice of dropped messages into one digest
+ * for the active session. A thin wrapper over the shared {@link summarize} core
+ * pinned to scope `"session"` (the default), so callers don't pass the flag.
+ */
+export declare function condense(messages: AgentMessage[], deps?: Omit<SummarizeDeps, "scope">): Promise<Summary>;
+/**
+ * Branch-scope summarization: archive an abandoned branch into one digest. Folds
+ * branch-summarization into the same machinery behind the scope flag — re-exported
+ * from the summarize subsystem so this module is the single condenser entrypoint.
+ */
+export { condenseScope };

package/dist/types/window-budget/contract.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Window-budget contract — the FROZEN type surface of the context-window
+ * budgeting subsystem (Phase 3, subsystem 05).
+ *
+ * A long-running coding session accrues messages — user turns, assistant turns,
+ * tool calls and their results — until the transcript approaches the model's
+ * context window. This subsystem keeps the session usable by *condensing* older
+ * history into a single structured summary message while keeping a verbatim
+ * tail of the most-recent turns. It answers three questions:
+ *
+ *   1. **Budget**  — *when* are we over budget? A {@link BudgetPolicy} carries
+ *      config-sourced thresholds (no magic literals); {@link isOverBudget}
+ *      decides from a real {@link TokenEstimate}.
+ *   2. **Slice**   — *where* do we cut? {@link planSlice} computes a
+ *      {@link CondensePlan} via a forward prefix-sum + binary search over a
+ *      cumulative-token array, never splitting a tool_call from its tool_result.
+ *   3. **Condense** — *how* do we compress the dropped portion? A
+ *      {@link Condenser} flattens the dropped messages, asks an injectable model
+ *      completer for a structured {@link Summary}, and returns the rebuilt
+ *      transcript (summary + kept tail).
+ *
+ * This file declares *only* shapes plus the function-type seams — no behavior,
+ * no I/O, no prompt strings. Every later window-budget module (the meter, the
+ * slice planner, the condenser, the branch archivist, the prompt templates, and
+ * the public barrel) is written against the names declared here.
+ *
+ * Design stance:
+ *   - Thresholds are **configuration, not constants**. {@link BudgetPolicy}
+ *     fields are supplied by the caller; this module bakes in no fixed token
+ *     fingerprints. Defaults, if any, live in the implementation and are
+ *     computed relative to the model's own context window.
+ *   - Branch-summarization is **not a separate engine**. It collapses into the
+ *     condenser behind a {@link CondenseScope} flag (`"session" | "branch"`),
+ *     so there is one prompt-assembly path, one token estimator, one slicer.
+ *   - The model completer is **injectable** ({@link CompleteFn}, default the
+ *     framework's `completeSimple`) so the condenser runs in tests with no
+ *     network.
+ *   - The produced condenser is **conductor-consumable**: a {@link Condenser}
+ *     is structurally a conductor `CondenseFn`
+ *     (`(messages: AgentMessage[]) => AgentMessage[] | Promise<AgentMessage[]>`),
+ *     so a {@link CondenserDeps}-built condenser plugs straight into the
+ *     conductor's auto-compaction seam.
+ *
+ * Framework anchors (all from the `indusagi` package — the sibling rebuilt
+ * framework this app targets):
+ *   - `AgentMessage`                          ← `indusagi/agent`
+ *   - `Model`, `Usage`, `completeSimple` (and its `Api`/`AssistantMessage`/
+ *     `Context`/`SimpleStreamOptions`/`StreamLogger` shapes) ← `indusagi/ai`
+ *
+ * This module never re-declares these; it composes them.
+ */
+import type { AgentMessage } from "indusagi/agent";
+import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions, StreamLogger, Usage } from "indusagi/ai";
+/** Re-exported framework vocabulary window-budget consumers routinely need. */
+export type { AgentMessage, Model, Usage };
+/**
+ * The config-sourced thresholds that govern when and how the transcript is
+ * condensed. Every field is a *number the caller supplies* — there are no magic
+ * token literals baked into this contract. An implementation may
+ * provide defaults, but they are configuration values, not protected constants,
+ * and deliberately differ from the legacy fingerprints.
+ */
+export interface BudgetPolicy {
+    /**
+     * Fraction of the model's `contextWindow` at which condensing is triggered,
+     * in `(0, 1]`. The meter is "over budget" once the estimated context tokens
+     * cross `contextWindow * triggerRatio`. Expressing the trigger as a ratio
+     * (rather than an absolute reserve) keeps it window-relative and free of
+     * baked-in token counts.
+     */
+    readonly triggerRatio: number;
+    /**
+     * How much of the recent transcript to keep verbatim, measured in estimated
+     * tokens. The slice planner preserves a tail of at least this many tokens
+     * (snapped to a legal boundary) and condenses everything before it.
+     */
+    readonly keepRecent: number;
+    /**
+     * Optional token headroom to subtract from the window before the trigger is
+     * evaluated — a safety margin so a condense fires *before* the very next turn
+     * would overflow. When omitted, only {@link triggerRatio} governs the trigger.
+     */
+    readonly reserveTokens?: number;
+}
+/**
+ * The outcome of measuring a transcript against a model's window. Anchors on the
+ * provider's authoritative `usage` count when available (`anchored: true`) and
+ * falls back to a rough char/role estimate otherwise; either way `contextTokens`
+ * is the figure {@link isOverBudget} compares to `contextWindow`.
+ */
+export interface TokenEstimate {
+    /** Best estimate of tokens currently occupying the context window. */
+    readonly contextTokens: number;
+    /** The model's total context window, in tokens (`Model.contextWindow`). */
+    readonly contextWindow: number;
+    /**
+     * `true` when {@link contextTokens} is anchored on a real provider `usage`
+     * figure (only trailing, post-usage messages are estimated); `false` when the
+     * whole figure is a heuristic estimate.
+     */
+    readonly anchored: boolean;
+}
+/**
+ * The pre-computed result of {@link planSlice}: the chosen cut index and the
+ * resulting partition of the transcript.
+ *
+ * The cut is found by a *forward* prefix-sum + binary search: build a cumulative
+ * estimated-token array over the messages, binary-search for the boundary index
+ * nearest `total - keepRecent`, then nudge to the closest *legal* boundary —
+ * never landing between a `toolCall` and its `toolResult`.
+ *
+ * Invariants:
+ *   - `kept.length + dropped.length === messages.length`
+ *   - `dropped` is the prefix `messages[0 .. cut)` (the older slice to condense)
+ *   - `kept`    is the suffix `messages[cut ..]` (the verbatim recent tail)
+ *   - `cut` is `0` when nothing is condensable (everything kept).
+ */
+export interface CondensePlan {
+    /** Index of the legal cut boundary: `dropped = messages.slice(0, cut)`. */
+    readonly cut: number;
+    /** The verbatim recent tail preserved as-is (`messages.slice(cut)`). */
+    readonly kept: AgentMessage[];
+    /** The older slice to be folded into a {@link Summary} (`messages.slice(0, cut)`). */
+    readonly dropped: AgentMessage[];
+}
+/**
+ * Which kind of condensing run this is — the flag that collapses
+ * branch-summarization into the single condenser path:
+ *   - `"session"` — condense the *active* transcript in place (the trigger /
+ *     overflow path); keeps a recent tail, summarizes the head.
+ *   - `"branch"`  — archive an *abandoned* branch into one summary message so its
+ *     context isn't lost on tree navigation; no verbatim tail is retained.
+ */
+export type CondenseScope = "session" | "branch";
+/**
+ * The structured result of summarizing a slice of dropped messages: a single
+ * synthetic {@link AgentMessage} that stands in for the messages it covers.
+ */
+export interface Summary {
+    /** The synthetic summary message to splice into the rebuilt transcript. */
+    readonly message: AgentMessage;
+    /** How many source messages this summary replaces. */
+    readonly coveredCount: number;
+}
+/**
+ * The injectable model-completion function. Structurally identical to the
+ * framework's `completeSimple`, so the real `completeSimple` is the drop-in
+ * default and a test can pass a no-network stub of the same shape. The
+ * condenser uses this single call to turn flattened transcript text into a
+ * {@link Summary}.
+ */
+export type CompleteFn = <TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions, logger?: StreamLogger) => Promise<AssistantMessage>;
+/**
+ * A condenser: takes the active branch's messages and returns the rebuilt
+ * transcript (condensed head + verbatim tail, or the input unchanged when there
+ * is nothing to do).
+ *
+ * This type is **structurally compatible with the conductor's `CondenseFn`**
+ * (`(messages: AgentMessage[]) => AgentMessage[] | Promise<AgentMessage[]>`), so
+ * the result of the condenser factory plugs directly into the conductor's
+ * auto-compaction seam with no adapter.
+ */
+export type Condenser = (messages: AgentMessage[]) => AgentMessage[] | Promise<AgentMessage[]>;
+/**
+ * Dependencies for building a {@link Condenser}. All fields are optional so a
+ * bare `createCondenser()` yields a working, network-free-testable condenser:
+ *   - `complete` defaults to the framework's `completeSimple`.
+ *   - `policy` defaults to the implementation's config-sourced thresholds.
+ *   - `model` is the summarization model; when omitted the condenser may fall
+ *     back to a no-op (return input unchanged) rather than guess a model.
+ */
+export interface CondenserDeps {
+    /**
+     * The injectable model completer (default: framework `completeSimple`). Inject
+     * a stub of {@link CompleteFn} shape to run the condenser with no network.
+     */
+    readonly complete?: CompleteFn;
+    /** The model used to write the summary. When omitted, condensing is a no-op. */
+    readonly model?: Model<Api>;
+    /** The config-sourced budget thresholds (default: implementation defaults). */
+    readonly policy?: BudgetPolicy;
+}

package/dist/types/window-budget/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Window-budget — public barrel.
+ *
+ * The context-window budgeting subsystem: token measurement, slice planning,
+ * and transcript condensing (with branch-archival collapsed in behind a scope
+ * flag). Re-exports the frozen contract types plus the live functions: the
+ * budget math (estimateTokens / isOverBudget / planSlice), the summarization core
+ * (summarize / condenseScope), and the conductor-consumable condenser factory
+ * (createCondenser / condense).
+ */
+export type { AgentMessage, BudgetPolicy, CompleteFn, CondensePlan, Condenser, CondenserDeps, CondenseScope, Model, Summary, TokenEstimate, Usage, } from "./contract.js";
+export { budgetLimit, estimateMessageTokens, estimateTokens, isOverBudget, planSlice, prefixTokens, } from "./budget/index.js";
+export { buildSummaryPrompt, CONDENSER_BRIEF, flattenTranscript, summarize, } from "./summarize/index.js";
+export type { SummarizeDeps } from "./summarize/index.js";
+export { condense, condenseScope, createCondenser } from "./condenser.js";

package/dist/types/window-budget/summarize/condense.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Window-budget — model-driven summarization.
+ *
+ * {@link summarize} is the single condensing primitive: given the dropped prefix
+ * of a transcript and a {@link SummarizeDeps} bundle, it flattens those messages,
+ * asks the injectable model completer to write a structured digest, and returns a
+ * synthetic {@link Summary} message that stands in for the slice it covers.
+ *
+ * Both condensing scopes flow through this one function:
+ *   - `"session"` — the active-session checkpoint (head condensed, tail kept by
+ *     the caller).
+ *   - `"branch"`  — an abandoned branch archived into one message.
+ * The only difference is the scope flag forwarded into {@link buildSummaryPrompt}
+ * (which selects the framing line). {@link condenseScope} is the thin
+ * branch-archival entrypoint that pins `scope: "branch"`.
+ *
+ * The completer is injectable ({@link SummarizeDeps.complete}, default the
+ * framework's `completeSimple`) so tests run with no network — pass a stub that
+ * returns a canned {@link AssistantMessage}. When no `model` is supplied there is
+ * nothing to call, so {@link summarize} degrades to a deterministic local digest
+ * rather than guessing a model — keeping it usable in a bare/offline build.
+ */
+import type { AgentMessage, CompleteFn, CondenseScope, Model, Summary } from "../contract.js";
+import { flattenTranscript } from "./prompt.js";
+/**
+ * What {@link summarize} needs. Every field is optional so the function is
+ * network-free-testable: omit `model` for a local fallback digest, or inject a
+ * `complete` stub for a scripted model response.
+ */
+export interface SummarizeDeps {
+    /** Injectable completer (default: framework `completeSimple`). */
+    readonly complete?: CompleteFn;
+    /** The summarization model. When omitted, a deterministic local digest is used. */
+    readonly model?: Model<Model<string>["api"]>;
+    /** Which kind of condense this is; defaults to `"session"`. */
+    readonly scope?: CondenseScope;
+    /** An earlier digest to refresh/extend (iterative-refresh / branch carry-in). */
+    readonly priorDigest?: string;
+    /** Cancellation signal forwarded to the completer. */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional cap on the digest size, in tokens, forwarded to the completer's
+     * `maxTokens`. A modest ceiling keeps the summary itself from eating the
+     * window. When omitted the model's own default applies.
+     */
+    readonly maxTokens?: number;
+}
+/**
+ * Summarize a slice of dropped messages into a single synthetic {@link Summary}.
+ *
+ * One code path for both scopes — `deps.scope` (default `"session"`) only changes
+ * the prompt framing. With a `model` bound it calls `deps.complete`
+ * (default `completeSimple`) once with {@link CONDENSER_BRIEF} as the system
+ * prompt and {@link buildSummaryPrompt} as the user turn; otherwise it returns a
+ * deterministic local digest. Never throws on an empty model reply — it falls
+ * back to the local digest so a {@link Summary} is always produced.
+ *
+ * @returns a {@link Summary} whose `message` replaces the `coveredCount` source
+ *          messages it summarizes.
+ */
+export declare function summarize(messages: AgentMessage[], deps?: SummarizeDeps): Promise<Summary>;
+/**
+ * Branch-archival entrypoint: condense an abandoned branch into one summary
+ * message. A thin wrapper that pins `scope: "branch"` and delegates to
+ * {@link summarize} — the branch case is the same machinery, not a separate
+ * engine.
+ */
+export declare function condenseScope(messages: AgentMessage[], deps?: Omit<SummarizeDeps, "scope">): Promise<Summary>;
+/** Re-export the flattener so callers can preview what the model will receive. */
+export { flattenTranscript };

package/dist/types/window-budget/summarize/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Window-budget — summarization subsystem barrel.
+ *
+ * Model-driven condensing of the dropped transcript prefix into one synthetic
+ * summary message, with re-authored prompts (new section names + a new tag
+ * vocabulary). Branch-archival folds in behind the scope flag — `condenseScope`
+ * is the branch entrypoint over the same `summarize` core.
+ */
+export { buildSummaryPrompt, CONDENSER_BRIEF, flattenTranscript, } from "./prompt.js";
+export { condenseScope, summarize } from "./condense.js";
+export type { SummarizeDeps } from "./condense.js";
+export type { AgentMessage, CompleteFn, CondenseScope, Model, Summary, } from "../contract.js";

package/dist/types/window-budget/summarize/prompt.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Window-budget — summarization prompt assembly (re-authored).
+ *
+ * When the transcript crosses budget, the older head is *condensed* into one
+ * synthetic message. This module turns the dropped slice of {@link AgentMessage}s
+ * into the single text payload handed to the model completer. Two pieces ship
+ * here:
+ *
+ *   1. {@link CONDENSER_BRIEF} — the system-prompt brief that frames the model as
+ *      a *recorder*, not a continuation of the chat: read the transcript as data
+ *      and emit only the structured digest.
+ *   2. {@link buildSummaryPrompt} — flattens the dropped messages into a tagged
+ *      block and appends the section template the model fills in.
+ *
+ * OWN VOCABULARY (an original prompt design):
+ *   - Section headings are `# Objective / # Guardrails /
+ *     # Status (Shipped / Active / Stuck) / # Rationale / # Plan / # Carryover`.
+ *   - The transcript is wrapped in `<scrollback>…</scrollback>` and a prior digest
+ *     (the branch-archival / iterative-refresh path) in
+ *     `<carried-digest>…</carried-digest>`.
+ *   - Per-message lines use `» role:` markers (`» you`, `» agent`,
+ *     `» agent.plan`, `» agent.call`, `» tool`).
+ *
+ * No token math, no model calls, no I/O here — only string assembly. The scope
+ * flag selects the framing line (active-session checkpoint vs abandoned-branch
+ * archive); everything else is one code path.
+ */
+import type { AgentMessage, CondenseScope } from "../contract.js";
+/**
+ * The system-prompt brief for the condenser model. Frames the request as a
+ * record-keeping task — the model must NOT answer, continue, or act on the
+ * conversation; it only transcribes it into the fixed section layout. Re-authored
+ * wording; shares no sentences with the legacy `SUMMARIZATION_SYSTEM_PROMPT`.
+ */
+export declare const CONDENSER_BRIEF: string;
+/**
+ * Flatten a list of messages into a single `\n`-joined block of `» role:` lines.
+ * Exported so the condenser can reuse it for diagnostics/tests.
+ */
+export declare function flattenTranscript(messages: AgentMessage[]): string;
+/**
+ * Build the full summarization prompt for a slice of dropped messages.
+ *
+ * The result is one string: the scope framing, the flattened transcript wrapped
+ * in `<scrollback>`, an optional carried digest wrapped in `<carried-digest>`
+ * (the iterative-refresh / branch-archival input), and the section template the
+ * model fills in. Pass this as the user turn to the injectable completer; pair it
+ * with {@link CONDENSER_BRIEF} as the system prompt.
+ *
+ * @param messages  the dropped prefix to summarize
+ * @param scope     `"session"` (active checkpoint) or `"branch"` (archive)
+ * @param priorDigest  an optional earlier digest to refresh/extend, threaded in
+ *                      under `<carried-digest>` so the model merges rather than
+ *                      re-derives. Omit for a first-pass condense.
+ */
+export declare function buildSummaryPrompt(messages: AgentMessage[], scope: CondenseScope, priorDigest?: string): string;