@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/loop/builder/index.ts

@@ -0,0 +1,346 @@
+import { err, ok, type Result } from "neverthrow";
+
+import type { AutonomousRequest, LlmBackend } from "../../backends/index.ts";
+import type { Outcome } from "../../conversation/index.ts";
+import { flow, llm, reporter as currentReporter } from "../../flow/index.ts";
+import { backendFailed, type BackendTag, type RuntimeError, type Usage } from "../../model/index.ts";
+import type { Observation } from "../context/index.ts";
+import { executeLoop, type LoopExecutionAction, type LoopExecutionStepResult } from "../execution.ts";
+import { analyzeGraph, type Edge } from "../graph/index.ts";
+import { measure as manifestMeasure, type TaskManifest } from "../state/index.ts";
+import { enforceTerminationContract, type TerminationContractError } from "../termination-contract.ts";
+import type {
+  ConfidenceState,
+  GatesState,
+  LoopBuilder,
+  LoopGuards,
+  LoopOutcome,
+  LoopRunError,
+  LoopRunOptions,
+  LoopVariant,
+  TerminationPreset,
+} from "./types.ts";
+
+export * from "./types.ts";
+
+// The loop() builder lowers a declarative loop onto flow() + loop execution
+// (spec loop-builder / flow-runtime, design D1+D3). Effect lives in src/loop/engine;
+// this surface never touches it, so the single-cycle case reads like a guarded `while`.
+
+/** One body node: a deterministic `.step()` transform or the single `.reason()` LLM verb. */
+interface StepItem<S> {
+  readonly kind: "step";
+  readonly name: string;
+  readonly body: (state: S) => Promise<S> | S;
+}
+interface ReasonItem {
+  readonly kind: "reason";
+  readonly tag: BackendTag;
+  /** Resolved lazily so `llm()` reads the flow context established by `.run()`. */
+  readonly run: () => Promise<Outcome>;
+}
+type BodyItem<S> = StepItem<S> | ReasonItem;
+
+interface Probe<S> {
+  readonly state: S;
+  readonly measure: number;
+}
+
+interface BodyResult<S> {
+  readonly state: S;
+  readonly usage?: Usage;
+  readonly observations: readonly Observation[];
+}
+
+/** A constant cycle action: the fingerprint guard is disabled, so its identity never matters. */
+const CYCLE_ACTION: LoopExecutionAction = { identity: "loop-cycle", inputs: null };
+
+class LoopBuilderImpl<S> implements LoopBuilder<S> {
+  private readonly items: BodyItem<S>[] = [];
+  private measureFn: ((state: S) => Promise<number> | number) | undefined;
+  private termination: TerminationPreset<S> | LoopVariant<S> | undefined;
+  private readonly guards: { maxIterations?: number; wallClockMs?: number; tokenBudget?: number } = {};
+
+  constructor(private readonly name: string) {}
+
+  reason<B extends BackendTag, Output = unknown>(
+    backend: LlmBackend<B>,
+    request: AutonomousRequest<Output, B>
+  ): LoopBuilder<S> {
+    this.items.push({
+      kind: "reason",
+      tag: backend.tag,
+      run: () => llm().autonomous(backend, request).awaitResult(),
+    });
+    return this;
+  }
+
+  step(name: string, body: (state: S) => Promise<S> | S): LoopBuilder<S> {
+    this.items.push({ kind: "step", name, body });
+    return this;
+  }
+
+  measure(fn: (state: S) => Promise<number> | number): LoopBuilder<S> {
+    this.measureFn = fn;
+    return this;
+  }
+
+  until(termination: TerminationPreset<S> | LoopVariant<S>): LoopBuilder<S> {
+    this.termination = termination;
+    return this;
+  }
+
+  guard(opts: LoopGuards): LoopBuilder<S> {
+    if (opts.maxIterations !== undefined) this.guards.maxIterations = opts.maxIterations;
+    if (opts.wallClockMs !== undefined) this.guards.wallClockMs = opts.wallClockMs;
+    if (opts.tokenBudget !== undefined) this.guards.tokenBudget = opts.tokenBudget;
+    return this;
+  }
+
+  async run(initial?: S, options: LoopRunOptions = {}): Promise<Result<LoopOutcome<S>, LoopRunError>> {
+    // 1. Termination by construction (design D3): reject an unguarded back-edge before running.
+    const contract = this.enforceContract();
+    if (contract.isErr()) {
+      return err(contract.error);
+    }
+
+    const variant = this.resolveVariant();
+    const guards = this.resolveGuards();
+
+    // 2. Lower onto flow() + loop execution; accessors/test overrides resolve from this context.
+    return await flow<Result<LoopOutcome<S>, LoopRunError>>(options.args ?? [], options.overrides ?? {})(async () => {
+      let current = initial as S;
+      let cycle = 0;
+
+      const summary = await executeLoop<Probe<S>>({
+        evaluate: async () => ok({ state: current, measure: await variant(current, cycle) }),
+        converged: (probe) => probe.measure <= 0,
+        nextAction: (probe) => (probe.measure <= 0 ? undefined : CYCLE_ACTION),
+        execute: async () => {
+          const body = await this.runBody(current);
+          if (body.isErr()) {
+            return err(body.error);
+          }
+          current = body.value.state;
+          cycle += 1;
+          // Post-cycle measure from the SAME variant the loop converges on, so the emitted
+          // progress stream cannot drift from the termination variant (spec execution-observability).
+          const measure = await variant(current, cycle);
+          const stepResult: LoopExecutionStepResult = {
+            ...(body.value.usage === undefined ? {} : { usage: body.value.usage }),
+            observations: body.value.observations,
+            measure,
+            ...(measure <= 0 ? { stopReason: "converged" } : {}),
+          };
+          return ok(stepResult);
+        },
+        fingerprint: false,
+        maxIterations: guards.maxIterations ?? 10,
+        ...(guards.wallClockMs === undefined ? {} : { wallClockMs: guards.wallClockMs }),
+        ...(guards.tokenBudget === undefined ? {} : { tokenBudget: guards.tokenBudget }),
+        ...(options.context === undefined ? {} : { context: options.context }),
+        onCycle: (progress) => {
+          currentReporter().emit({
+            type: "cycle_progress",
+            iteration: progress.iteration,
+            ...(progress.measure === undefined ? {} : { measure: progress.measure }),
+            ...(progress.usage === undefined ? {} : { usage: progress.usage }),
+            ...(progress.contextPressure === undefined ? {} : { contextPressure: progress.contextPressure }),
+          });
+          if (options.onCycle !== undefined && progress.measure !== undefined) {
+            options.onCycle({
+              iteration: progress.iteration,
+              measure: progress.measure,
+              ...(progress.usage === undefined ? {} : { usage: progress.usage }),
+              ...(progress.contextPressure === undefined ? {} : { contextPressure: progress.contextPressure }),
+            });
+          }
+        },
+      });
+
+      if (summary.isErr()) {
+        return err(summary.error);
+      }
+      const value = summary.value;
+      return ok({
+        state: value.lastEvaluation.state,
+        stopReason: value.stop,
+        iterations: value.iterations,
+      });
+    });
+  }
+
+  /** Run the cycle body once, threading state through `.step()`s and folding `.reason()` usage. */
+  private async runBody(state: S): Promise<Result<BodyResult<S>, RuntimeError>> {
+    let current = state;
+    let usage: Usage | undefined;
+    const observations: Observation[] = [];
+    for (const item of this.items) {
+      if (item.kind === "step") {
+        current = await item.body(current);
+        observations.push({ id: item.name, content: stringifyObservation(current) });
+        continue;
+      }
+      const outcome = await item.run();
+      if (outcome.type === "failed") {
+        return err(outcome.error);
+      }
+      if (outcome.type === "cancelled") {
+        return err(backendFailed(item.tag, "reason verb cancelled before completion"));
+      }
+      const reported = outcome.result.usage;
+      if (reported !== undefined) {
+        usage = usage === undefined ? reported : addUsage(usage, reported);
+      }
+      observations.push({ id: `reason:${item.tag}`, content: stringifyObservation(outcome.result.output) });
+    }
+    return ok(usage === undefined ? { state: current, observations } : { state: current, usage, observations });
+  }
+
+  /** The loop has a variant iff a custom measure or a termination (preset/variant) was supplied. */
+  private hasVariant(): boolean {
+    return this.measureFn !== undefined || this.termination !== undefined;
+  }
+
+  /** Normalize the variant to one async measure; priority: `.measure()` > `.until()`. */
+  private resolveVariant(): (state: S, cycle: number) => Promise<number> {
+    const measureFn = this.measureFn;
+    if (measureFn !== undefined) {
+      return (state) => Promise.resolve(measureFn(state));
+    }
+    const termination = this.termination;
+    if (termination !== undefined) {
+      if (isPreset(termination)) {
+        const preset = termination;
+        return (state, cycle) => Promise.resolve(preset.measure(state, cycle));
+      }
+      const variant = termination;
+      return (state) => Promise.resolve(variant.measure(state));
+    }
+    // Unreachable after the contract check; an unguarded loop rests on its ceiling.
+    return () => Promise.resolve(Number.POSITIVE_INFINITY);
+  }
+
+  /** Explicit `.guard()` values win; a preset's default seatbelts fill the rest (design D3). */
+  private resolveGuards(): LoopGuards {
+    const termination = this.termination;
+    const presetGuards = termination !== undefined && isPreset(termination) ? termination.guards : undefined;
+    const maxIterations = this.guards.maxIterations ?? presetGuards?.maxIterations;
+    const wallClockMs = this.guards.wallClockMs ?? presetGuards?.wallClockMs;
+    const tokenBudget = this.guards.tokenBudget ?? presetGuards?.tokenBudget;
+    return {
+      ...(maxIterations === undefined ? {} : { maxIterations }),
+      ...(wallClockMs === undefined ? {} : { wallClockMs }),
+      ...(tokenBudget === undefined ? {} : { tokenBudget }),
+    };
+  }
+
+  /** Build the cyclic graph (one declared back-edge) and enforce termination by construction. */
+  private enforceContract(): Result<void, TerminationContractError> {
+    const ids = this.nodeIds();
+    const first = ids.at(0);
+    const last = ids.at(-1);
+    if (first === undefined || last === undefined) {
+      return ok(undefined); // no body ⇒ no cycle to guard
+    }
+    const edges: Edge[] = [];
+    for (let i = 0; i + 1 < ids.length; i += 1) {
+      const from = ids[i];
+      const to = ids[i + 1];
+      if (from !== undefined && to !== undefined) {
+        edges.push({ from, to });
+      }
+    }
+    const backEdge: Edge = { from: last, to: first };
+    const report = analyzeGraph({
+      nodes: ids,
+      edges: [...edges, backEdge],
+      declaredBackEdges: [backEdge],
+    });
+    const guarded = this.hasVariant();
+    return enforceTerminationContract(report, () => guarded);
+  }
+
+  /** Unique, loop-namespaced node ids in authored order (so contract errors name the loop). */
+  private nodeIds(): string[] {
+    const used = new Set<string>();
+    const ids: string[] = [];
+    for (const item of this.items) {
+      const base = `${this.name}:${item.kind === "reason" ? "reason" : item.name}`;
+      let id = base;
+      let suffix = 1;
+      while (used.has(id)) {
+        id = `${base}#${String(suffix)}`;
+        suffix += 1;
+      }
+      used.add(id);
+      ids.push(id);
+    }
+    return ids;
+  }
+}
+
+function isPreset<S>(termination: TerminationPreset<S> | LoopVariant<S>): termination is TerminationPreset<S> {
+  return "kind" in termination;
+}
+
+function addUsage(a: Usage, b: Usage): Usage {
+  const reasoning = (a.reasoning ?? 0) + (b.reasoning ?? 0);
+  const base = { input: a.input + b.input, output: a.output + b.output };
+  return reasoning > 0 ? { ...base, reasoning } : base;
+}
+
+function stringifyObservation(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Entry point for the declarative loop builder (task 5.1). */
+export function loop<S = unknown>(name: string): LoopBuilder<S> {
+  return new LoopBuilderImpl<S>(name);
+}
+
+// Preset termination archetypes (design D3 / task 5.2). Each bundles a loop variant whose
+// measure floors at 0; choosing one satisfies the termination contract with no author math.
+
+/** TDD / compiler loop: drive failing tests/gates to zero. */
+export function untilGatesGreen(): TerminationPreset<GatesState> {
+  return { kind: "untilGatesGreen", measure: (state) => Math.max(0, state.failingGates) };
+}
+
+/** The "Ralph" case: drive the manifest's pending-task count to zero (variant from L05 projection). */
+export function untilManifestComplete(): TerminationPreset<TaskManifest> {
+  return { kind: "untilManifestComplete", measure: (state) => manifestMeasure(state) };
+}
+
+/** Today's review/fix loop: drive the open-issue count to zero. */
+export function untilNoIssues(): TerminationPreset<readonly unknown[]> {
+  return { kind: "untilNoIssues", measure: (state) => state.length };
+}
+
+/** Confidence loop: drive `1 − confidence` to the threshold floor. */
+export function untilConfident(threshold: number): TerminationPreset<ConfidenceState> {
+  return { kind: "untilConfident", measure: (state) => Math.max(0, threshold - state.confidence) };
+}
+
+/** Bounded-count escape hatch: the variant is the remaining iterations; converges after `n`. */
+export function times(n: number): TerminationPreset {
+  const ceiling = Math.max(0, Math.floor(n));
+  return {
+    kind: "times",
+    measure: (_state, cycle) => Math.max(0, ceiling - cycle),
+    guards: { maxIterations: ceiling },
+  };
+}
+
+// Opt-in fan-out / fan-in combinators (spec loop-builder; design D9; tasks 6.1-6.4). They live
+// in ./fanout.ts (Effect-free, building on the engine's plain `runBoundedBranches` seam) and are
+// surfaced here so the loop authoring module exposes them; omitting them leaves the single-cycle
+// loop() surface above unchanged.
+export * from "../fanout.ts";

package/src/loop/builder/types.ts

@@ -0,0 +1,131 @@
+import type { Result } from "neverthrow";
+
+import type { AutonomousRequest, LlmBackend } from "../../backends/index.ts";
+import type { FlowOverrides } from "../../flow/index.ts";
+import type { BackendTag, RuntimeError, Usage } from "../../model/index.ts";
+import type { LoopExecutionContextOptions, LoopContextPressure } from "../execution.ts";
+import type { TerminationContractError } from "../termination-contract.ts";
+
+// Declarative loop() builder — the Effect-free authoring front door (spec loop-builder).
+// Lowers to flow() + loop execution. No Effect type may appear
+// here (design D2 facade gate). The single-cycle case reads like a guarded `while`: no
+// graph, fan-out, Effect, queue, or conversation symbol surfaces in authored source.
+
+/** Surfaced from the internal contract module so callers can discriminate a build failure. */
+export type { TerminationContractError } from "../termination-contract.ts";
+
+/**
+ * A loop variant (design D3): a measure bounded below — floor `0` by convention — that the
+ * loop drives toward zero. `.measure(fn)` supplies one directly; presets bundle one.
+ */
+export interface LoopVariant<S = unknown> {
+  /** Current measure; the loop converges when this reaches `0`. */
+  measure(state: S): Promise<number> | number;
+}
+
+export type PresetKind =
+  | "untilGatesGreen"
+  | "untilManifestComplete"
+  | "untilNoIssues"
+  | "untilConfident"
+  | "times";
+
+/**
+ * A preset termination archetype (design D3). Choosing one satisfies the termination contract
+ * without the author authoring variant math. The bundled `measure` is the loop variant (floor
+ * `0`); `cycle` is the completed-iteration count, needed by count-based presets like `times`.
+ * `guards` are sane default seatbelts the preset contributes; an explicit `.guard()` overrides.
+ */
+export interface TerminationPreset<S = unknown> {
+  readonly kind: PresetKind;
+  readonly measure: (state: S, cycle: number) => number;
+  readonly guards?: LoopGuards;
+}
+
+/** Fan-in join policies — all four ship in v1 (design D9). Wired by L07 `fanIn`. */
+export type JoinPolicy = "barrier" | "race" | "quorum" | "reduce";
+
+/** Seatbelt guards layered under the variant (design D3): ceiling, wall-clock, token budget. */
+export interface LoopGuards {
+  readonly maxIterations?: number;
+  readonly wallClockMs?: number;
+  readonly tokenBudget?: number;
+}
+
+/** Discriminated stop reason; extends the fixLoop stops with `budget-exhausted`/`cancelled` (design D3). */
+export type LoopStopReason =
+  | "converged"
+  | "unfixable"
+  | "stuck"
+  | "timeout"
+  | "ceiling"
+  | "budget-exhausted"
+  | "cancelled";
+
+/** Outcome of a completed loop run. */
+export interface LoopOutcome<S = unknown> {
+  readonly state: S;
+  readonly stopReason: LoopStopReason;
+  readonly iterations: number;
+}
+
+/**
+ * Per-cycle observability report emitted after each completed cycle when `onCycle` is set. The
+ * `measure` comes from the loop variant (the L05 manifest projection), so a record fed straight to
+ * `WorkflowMonitor.recordCycle` stays consistent with the termination variant (spec
+ * execution-observability). `usage` omitted ⇒ the backend reported none this cycle.
+ */
+export interface LoopCycleReport {
+  readonly iteration: number;
+  readonly measure: number;
+  readonly usage?: Usage;
+  readonly contextPressure?: LoopContextPressure;
+}
+
+/** Flow setup supplied to a run; `overrides` is how tests inject fake accessors (flow-runtime spec). */
+export interface LoopRunOptions {
+  readonly args?: readonly string[];
+  readonly overrides?: FlowOverrides;
+  readonly context?: LoopExecutionContextOptions;
+  /** Optional observability hook; receives a {@link LoopCycleReport} after each completed cycle. */
+  readonly onCycle?: (cycle: LoopCycleReport) => void;
+}
+
+/** A `.run()` fails either at build (unguarded back-edge) or at runtime (a step/reason error). */
+export type LoopRunError = RuntimeError | TerminationContractError;
+
+/**
+ * Chainable loop builder. The single-cycle case reads like a guarded `while` and needs no
+ * graph/fan-out/Effect knowledge. `.reason()` is the single LLM verb; `.step()` is a
+ * deterministic transform; `.measure()`/`.until()` set the termination variant; `.guard()`
+ * adds seatbelts. `.run()` lowers to `flow()` + loop execution.
+ */
+export interface LoopBuilder<S = unknown> {
+  /** The single LLM verb. Drives a backend autonomously each cycle; hides the conversation. */
+  reason<B extends BackendTag, Output = unknown>(
+    backend: LlmBackend<B>,
+    request: AutonomousRequest<Output, B>
+  ): LoopBuilder<S>;
+  /** A deterministic step that transforms the threaded loop state. */
+  step(name: string, body: (state: S) => Promise<S> | S): LoopBuilder<S>;
+  /** Power-user variant override (design D3); takes precedence over a preset. */
+  measure(fn: (state: S) => Promise<number> | number): LoopBuilder<S>;
+  /** Set the termination variant from a preset archetype or a custom variant. */
+  until(termination: TerminationPreset<S> | LoopVariant<S>): LoopBuilder<S>;
+  /** Layer seatbelt guards under the variant. */
+  guard(opts: LoopGuards): LoopBuilder<S>;
+  /** Build (enforcing the termination contract) then run; returns the outcome and a stop reason. */
+  run(initial?: S, options?: LoopRunOptions): Promise<Result<LoopOutcome<S>, LoopRunError>>;
+}
+
+/** State projection read by the `untilGatesGreen` preset. */
+export interface GatesState {
+  /** Failing tests/gates remaining; the loop converges as this reaches `0`. */
+  readonly failingGates: number;
+}
+
+/** State projection read by the `untilConfident` preset. */
+export interface ConfidenceState {
+  /** Confidence in `[0, 1]`; the loop converges once it reaches the threshold. */
+  readonly confidence: number;
+}

package/src/loop/context/compaction.ts

@@ -0,0 +1,175 @@
+import type { CompactionConfig } from "./types.ts";
+
+// Aggressive-default staged context compaction (design D10; task 7.1). Once managed context is
+// enabled, compaction runs by TOKEN PRESSURE — the "small windows = smart agents" principle: a
+// tight working window forces sharper agent behaviour and cheaper turns. As pressure rises past the
+// small working window, the same observation history is compacted in escalating stages, IN ORDER:
+//
+//   mask      → keep every observation record but drop its body to a short stub (cheapest, lowest
+//               information loss): the agent still sees that the step happened.
+//   prune     → discard the oldest stubs that no longer fit, keeping the newest history that does.
+//   summarize → when even pruning would discard most of the record (wholesale loss), collapse the
+//               whole history span into a single bounded summary observation instead of dropping it.
+//
+// Each stage is reached only when the previous one cannot bring the context back within the window,
+// so the stages applied report the pressure tier. `compact` is a pure transform (no I/O); large
+// individual outputs are kept out of context separately by the offload path (see ./offload.ts), so
+// by the time observations reach here each one is already bounded.
+
+/** ~4 chars per token — the same crude estimate used across the loop module (cf. fanout budgets). */
+const CHARS_PER_TOKEN = 4;
+/** The stub a masked observation's body collapses to; its own token cost is the mask floor. */
+const MASK_PLACEHOLDER = "⟦masked⟧";
+/** Bounded size of the single observation produced by the summarize stage. */
+const SUMMARY_TOKEN_CAP = 48;
+const SUMMARY_CHAR_CAP = SUMMARY_TOKEN_CAP * CHARS_PER_TOKEN;
+/** If fitting the window would force pruning more than this fraction of history, summarize instead. */
+const PRUNE_TO_SUMMARIZE_FRACTION = 0.5;
+
+/** Token cost of one masked stub — the irreducible floor of the mask stage. */
+const MASK_TOKENS = estimateTokens(MASK_PLACEHOLDER);
+
+/**
+ * Aggressive defaults applied once managed context is enabled (design D10): a small working window
+ * and an aggressive offload threshold. Authors MAY raise these, but enabled context gets tight
+ * defaults out of the box.
+ */
+export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
+  workingWindowTokens: 2000,
+  offloadThresholdChars: 8000,
+};
+
+/** The escalating compaction stages, lowest pressure first. */
+export type CompactionStage = "mask" | "prune" | "summarize";
+
+/** One unit of loop context — a tool/step observation the agent may later read. */
+export interface Observation {
+  /** Stable identifier, preserved through masking so the record of the step survives. */
+  readonly id: string;
+  /** The observation body; what masking and summarization compress. */
+  readonly content: string;
+  /** Pinned observations (goal, manifest) are never compacted. */
+  readonly pinned?: boolean;
+  /** Precise token cost; defaults to a ~4-chars-per-token estimate of `content`. */
+  readonly tokens?: number;
+}
+
+export interface CompactionResult {
+  /** The compacted context: pinned, then the compacted history span, then the verbatim recent tail. */
+  readonly observations: readonly Observation[];
+  /** Stages applied, in order — empty when there was no pressure, up to all three under heavy load. */
+  readonly stagesApplied: readonly CompactionStage[];
+  readonly tokensBefore: number;
+  readonly tokensAfter: number;
+}
+
+/** Crude token estimate from character length; shared so masking/summary budgets stay consistent. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+function tokensOf(observation: Observation): number {
+  return observation.tokens ?? estimateTokens(observation.content);
+}
+
+function totalTokens(observations: readonly Observation[]): number {
+  return observations.reduce((sum, observation) => sum + tokensOf(observation), 0);
+}
+
+/**
+ * Compact `observations` to fit the small working window, escalating mask → prune → summarize only
+ * as far as the token pressure requires. Pure: returns a new context plus the stages it applied. The
+ * result is kept within `config.workingWindowTokens` except when a single un-offloaded recent
+ * observation alone exceeds the window — offload oversized outputs (see ./offload.ts) to avoid that.
+ */
+export function compact(
+  observations: readonly Observation[],
+  config: CompactionConfig = DEFAULT_COMPACTION_CONFIG,
+): CompactionResult {
+  const window = config.workingWindowTokens;
+  const tokensBefore = totalTokens(observations);
+  if (tokensBefore <= window) {
+    // No pressure — nothing is touched.
+    return { observations: [...observations], stagesApplied: [], tokensBefore, tokensAfter: tokensBefore };
+  }
+
+  const { pinned, recent, history } = partition(observations, window);
+  const fixedTokens = totalTokens(pinned) + totalTokens(recent); // pinned + recent tail are never compacted
+
+  // Stage 1 — MASK every history observation's body down to a stub.
+  const masked = history.map(maskObservation);
+  if (fixedTokens + totalTokens(masked) <= window) {
+    return assemble(pinned, masked, recent, ["mask"], tokensBefore);
+  }
+
+  // Stage 2 — PRUNE the oldest stubs that no longer fit, keeping the newest that do — UNLESS that
+  // would discard most of the history, which is wholesale loss better handled by summarization.
+  const room = Math.max(0, window - fixedTokens);
+  const keepCount = Math.min(masked.length, Math.floor(room / MASK_TOKENS));
+  const dropCount = masked.length - keepCount;
+  if (dropCount <= masked.length * PRUNE_TO_SUMMARIZE_FRACTION) {
+    const pruned = masked.slice(masked.length - keepCount); // keep the newest survivors
+    return assemble(pinned, pruned, recent, ["mask", "prune"], tokensBefore);
+  }
+
+  // Stage 3 — SUMMARIZE the whole history span into one bounded observation, preserving its gist
+  // rather than dropping the majority of it. Guaranteed to fit: the recent tail reserves room for it.
+  const summary = summarizeObservations(history);
+  return assemble(pinned, [summary], recent, ["mask", "prune", "summarize"], tokensBefore);
+}
+
+/**
+ * Split observations into the never-compacted pinned set, the verbatim recent tail that fills the
+ * working window (newest first, reserving room for a terminal summary), and the older history span.
+ * At least the single newest non-pinned observation is always kept verbatim.
+ */
+function partition(
+  observations: readonly Observation[],
+  window: number,
+): { pinned: Observation[]; recent: Observation[]; history: Observation[] } {
+  const pinned = observations.filter((observation) => observation.pinned === true);
+  const flow = observations.filter((observation) => observation.pinned !== true); // chronological, oldest→newest
+  const recentBudget = Math.max(0, window - totalTokens(pinned) - SUMMARY_TOKEN_CAP);
+
+  const recent: Observation[] = [];
+  let used = 0;
+  for (let i = flow.length - 1; i >= 0; i--) {
+    const observation = flow[i];
+    if (observation === undefined) {
+      continue;
+    }
+    const cost = tokensOf(observation);
+    if (recent.length > 0 && used + cost > recentBudget) {
+      break; // always keep the newest observation; stop once the tail would overflow the budget
+    }
+    recent.unshift(observation);
+    used += cost;
+  }
+
+  const history = flow.slice(0, flow.length - recent.length);
+  return { pinned, recent, history };
+}
+
+/** Drop an observation's body to a stub while preserving its identity (the step still happened). */
+function maskObservation(observation: Observation): Observation {
+  return { id: observation.id, content: MASK_PLACEHOLDER };
+}
+
+/** Collapse a history span into one bounded summary observation that names what it replaced. */
+function summarizeObservations(history: readonly Observation[]): Observation {
+  const ids = history.map((observation) => observation.id).join(", ");
+  const full = `⟦summary of ${String(history.length)} earlier observations: ${ids}⟧`;
+  const content = full.length > SUMMARY_CHAR_CAP ? `${full.slice(0, SUMMARY_CHAR_CAP - 1)}…` : full;
+  return { id: "compaction-summary", content };
+}
+
+function assemble(
+  pinned: readonly Observation[],
+  historyReplacement: readonly Observation[],
+  recent: readonly Observation[],
+  stagesApplied: readonly CompactionStage[],
+  tokensBefore: number,
+): CompactionResult {
+  const observations = [...pinned, ...historyReplacement, ...recent];
+  return { observations, stagesApplied, tokensBefore, tokensAfter: totalTokens(observations) };
+}

package/src/loop/context/index.ts

@@ -0,0 +1,3 @@
+export * from "./types.ts";
+export * from "./compaction.ts";
+export * from "./offload.ts";