Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
32.7 KB
Raw Blame
/**
 * PressureContextManager and InLoopContextManager - ContextManager implementations.
 *
 * Phase 6: Context window pressure management for the tool-use loop.
 *
 * PressureContextManager uses tiered compaction based on token usage:
 *   < 80%:  passthrough (no compaction)
 *   80-85%: MoveToWorkspace — archive old turns to daily log, keep 8
 *   85-95%: Summarize — LLM-summarize old turns to daily log, keep 5
 *   > 95%:  Truncate — emergency drop, keep 3 (no LLM call)
 *
 * InLoopContextManager is a simpler version with a single threshold.
 */
import { Counter, Histogram } from 'prom-client'
import { logger } from '../../logger'
import type { Workspace } from '../../workspace/service'
import {
  applyAlignedCut,
  estimateTokens,
  measureCompactionRatio,
  splitTurns,
  turnIndexToMessageIndex,
} from '../conversation/compaction'
import { parseStructuredSummary } from '../conversation/structuredSummaryParser'
import { ContextManageOptions, ContextManager, LlmPort } from '../interfaces'
import type { AgentEventEmitter } from '../interfaces'
import { validateToolLinkages } from '../orchestration/toolUseLoop'
import { bpeTokenEstimate } from '../tokenizer/bpeEstimate'
import { heuristicCount, heuristicCountTools } from '../tokenizer/heuristic'
import { tokenizerDryrunDelta, tokenizerDryrunTierMismatchTotal } from '../tokenizer/metrics'
import type { TokenCounter } from '../tokenizer/tokenCounter'
import { ChatMessage, CompactionState, Conversation, ToolDefinition } from '../types'
import { type PrePruneOptions, clerumPrePruneSavingsTokensTotal, prePrune } from './prePrune'
import { buildStructuredSummaryPrompt } from './structuredSummaryTemplate'

// ─── T1.4 Prometheus instruments ────────────────────────────────────────────
//
// Co-located with the manager (same pattern as `tokenizer/metrics.ts`'s
// `tokenizerFallbackTotal`). The `skipped:pending_approval` outcome is emitted
// by `runToolUseLoop` (P.3 §4.1 — single source of truth); the manager only
// emits `ok` and `thrashing`. The histogram is observed once per *actual*
// compaction (i.e. not on passthrough, defensive-skip or thrash backoff).

// `none` is the sentinel for the `skipped:pending_approval` outcome which is
// emitted by `runToolUseLoop` before any tier is chosen (P.3 §4.1).
export type CompactionTier = 'move_to_workspace' | 'summarize' | 'truncate' | 'none'
export type CompactionOutcome = 'ok' | 'thrashing' | 'skipped:pending_approval'

export const clerumCompactionTotal = new Counter({
  name: 'clerum_compaction_total',
  help: 'Compaction attempts by tier and outcome.',
  labelNames: ['tier', 'outcome'] as const,
})

export const clerumCompactionRatio = new Histogram({
  name: 'clerum_compaction_ratio',
  help: 'post/pre token ratio per compaction attempt (lower is more effective).',
  buckets: [0.1, 0.25, 0.5, 0.7, 0.8, 0.9, 0.95, 1.0],
})

// ─── T1.1 — Structured summary parse outcome counter ────────────────────────
//
// Tracked only when `CLERUM_COMPACTION_STRUCTURED_SUMMARY=true` AND the
// summarize tier ran. Labels mirror `ParseStatus` so the bake-week dashboards
// can flag "≥ 80% ok" before flipping the default in prod.
export const clerumCompactionStructuredParseTotal = new Counter({
  name: 'clerum_compaction_structured_parse_total',
  help: 'Structured summary parse outcomes per Summarize tier invocation.',
  labelNames: ['outcome'] as const,
})

export interface PressureContextManagerOptions {
  /**
   * P.2 dry-run mode. When true (the default during the bake-week), the
   * manager uses the legacy heuristic to decide the tier and ALSO computes
   * the real counter value for observability. When false, the real counter
   * drives the decision. See `.specs/mcp-hermes/implementation-plans/P2-tokenizer.md`.
   */
  dryRun?: boolean
  /**
   * T1.4 — Anti-thrash thresholds. Two consecutive compactions whose
   * `post/pre` token ratio exceeds `ineffectiveRatio` trip a backoff: the
   * manager stops attempting compaction for the rest of the task and lets
   * the agent-level budgets terminate the loop.
   *
   * Defaults: `ineffectiveRatio=0.9`, `ineffectiveMaxRun=2`.
   */
  ineffectiveRatio?: number
  ineffectiveMaxRun?: number
  /**
   * T1.4 — Optional event emitter for the one-shot `compaction:thrashing`
   * activity event. When omitted, the event is dropped silently and only the
   * Prometheus counter records the outcome (useful for unit tests).
   */
  events?: AgentEventEmitter
  /**
   * T1.4 — Optional task id stamped onto the thrashing event so the activity
   * hub can correlate the event with the originating task.
   */
  taskId?: string
  /**
   * T1.2 — Master flag for the deterministic pre-prune. Default `false`.
   * When `true`, `manage()` runs the four-pass pre-prune after the pressure
   * threshold is crossed but before any tier is selected; if pre-prune alone
   * brings pressure back under 80%, the manager returns the pruned set
   * without invoking the tier.
   */
  prePruneEnabled?: boolean
  /**
   * T1.2 — Per-pass toggles + budgets. Defaults documented in
   * `DEFAULT_PRE_PRUNE_OPTIONS`. Only consulted when `prePruneEnabled === true`.
   */
  prePruneOptions?: PrePruneOptions
  /**
   * T1.1 — Structured summary template. When `true`, the `Summarize` tier
   * sends the section-anchored prompt (defensive preamble + Active Task +
   * Memory Writes) and parses the LLM output via `parseStructuredSummary`.
   * When `false` (the default during rollout), behaves bit-for-bit like the
   * pre-T1.1 free-form summarizer. See `structuredSummaryTemplate.ts`.
   */
  structuredSummaryEnabled?: boolean

  /**
   * T2.2 — invalidation hook fired AFTER a real compaction (any tier that
   * archived turns). The manager has no direct dependency on `PromptCache`;
   * the wiring side (`TaskExecutor.buildLoopConfig`) passes a closure that
   * captures the cache + sessionKey so the manager stays free of LLM-adapter
   * concerns.
   */
  onCompactionEffective?: (info: { conversationId: string; tier: CompactionTier }) => void

  /**
   * #731 — the provider's bound on the number of request messages, taken from
   * its attempt contract (`LIMITS.maxMessages`). When set, pressure is the
   * larger of the token ratio and `messages.length / maxMessages`, so a long
   * history of small turns is compacted before the contract refuses it on
   * count alone. Omitted for providers without such a bound.
   */
  maxMessages?: number
}

/**
 * The pressure at which compaction starts. Below it `manage()` passes the
 * history through untouched; `taskExecutor` scales it by the context window to
 * gate history compaction at rehydration (#731).
 */
export const COMPACTION_PRESSURE_THRESHOLD = 0.8

/**
 * The token count behind `PressureContextManager`'s tier decision. Without a
 * counter, or in the dry run, the byte heuristic decides; otherwise the
 * counter does. `taskExecutor` measures the rehydrated history with this same
 * function, so a history the manager passes through is never compacted at
 * rehydration (#739).
 *
 * The `lastObservedInputTokens` shortcut (Hermes `update_from_response`) is
 * intentionally NOT applied: the manager calls this once per loop iteration,
 * so the per-decision count is affordable, and skipping `count()` would risk
 * under-counting messages added since the last response. T2.2 (prompt cache)
 * revisits this with a per-iteration shape diff.
 */
export async function tierDecisionTokens(
  messages: ChatMessage[],
  tools: ToolDefinition[],
  tokenCounter: TokenCounter | undefined,
  dryRun: boolean
): Promise<number> {
  if (!tokenCounter || dryRun) return estimateTokens(messages) + heuristicCountTools(tools)
  return tokenCounter.count(messages, tools)
}

/** Measure the complete emitted tool message with the larger applicable estimate. */
export function toolMessageBudgetTokens(
  message: ChatMessage,
  tokenCounter: TokenCounter | undefined,
  dryRun: boolean
): number {
  const applicable =
    !tokenCounter || dryRun ? heuristicCount([message]) : tokenCounter.countSync([message])
  const bpe =
    bpeTokenEstimate(message.content ?? '') +
    bpeTokenEstimate(message.name ?? '') +
    bpeTokenEstimate(message.tool_call_id ?? '') +
    6
  return Math.max(applicable, bpe)
}

/**
 * The messages a pressure count measures: the loop's messages, preceded by the
 * system prompt as the one system message it becomes on the wire (R9-14). The
 * prompt is counted only; it never enters the history the manager returns.
 */
function withSystemPrompt(
  messages: ChatMessage[],
  systemPrompt: string | undefined
): ChatMessage[] {
  if (systemPrompt === undefined) return messages
  return [{ role: 'system', content: systemPrompt }, ...messages]
}

type PressureTier = 'passthrough' | 'workspace' | 'summarize' | 'truncate'

function tierFor(pressure: number): PressureTier {
  if (pressure < COMPACTION_PRESSURE_THRESHOLD) return 'passthrough'
  if (pressure < 0.85) return 'workspace'
  if (pressure < 0.95) return 'summarize'
  return 'truncate'
}

/**
 * T1.4 — translate a numeric pressure into the Counter `tier` label. Distinct
 * from `tierFor`/`PressureTier` because the metric uses snake-case labels
 * matching the activity-hub vocabulary (`move_to_workspace` vs. `workspace`).
 */
function tierLabel(pressure: number): CompactionTier {
  if (pressure >= 0.95) return 'truncate'
  if (pressure >= 0.85) return 'summarize'
  return 'move_to_workspace'
}

/**
 * T1.4 — lazily attach a fresh `CompactionState` to the conversation. Mutates
 * the input so subsequent calls within the same task share the counter.
 */
function ensureCompactionState(conv: Conversation): CompactionState {
  if (!conv.compactionState) {
    conv.compactionState = {
      lastRatio: 1.0,
      ineffectiveCount: 0,
      stoppedForTask: false,
    }
  }
  return conv.compactionState
}

/**
 * Format turns as readable markdown for workspace archival.
 */
function formatTurnsAsMarkdown(turns: ChatMessage[][]): string {
  const lines: string[] = []
  for (const turn of turns) {
    for (const msg of turn) {
      if (msg.role === 'user') {
        lines.push(`**User:** ${msg.content}`)
      } else if (msg.role === 'assistant') {
        const text = msg.content || '(tool call)'
        lines.push(`**Assistant:** ${text}`)
      } else if (msg.role === 'tool') {
        const snippet = msg.content.length > 200 ? msg.content.slice(0, 200) + '…' : msg.content
        lines.push(`**Tool (${msg.name || 'unknown'}):** ${snippet}`)
      }
    }
    lines.push('') // blank line between turns
  }
  return lines.join('\n')
}

const SUMMARIZE_PROMPT =
  'Summarize the following conversation concisely. Focus on:\n' +
  '- Key decisions made\n' +
  '- Important information exchanged\n' +
  '- Actions taken\n' +
  '- Outcomes achieved\n' +
  'Be brief but capture all important details. Use bullet points.'

/**
 * Tier-based context compaction with workspace archival and LLM summarization.
 *
 * Dependencies are optional — when not provided, all tiers fall back to
 * simple truncation (original Phase 6 behavior).
 */
export class PressureContextManager implements ContextManager {
  private readonly maxTokens: number
  private readonly workspace?: Workspace
  private readonly llmPort?: LlmPort
  private readonly tokenCounter?: TokenCounter
  private readonly dryRun: boolean
  private readonly ineffectiveRatio: number
  private readonly ineffectiveMaxRun: number
  private readonly events?: AgentEventEmitter
  private readonly taskId?: string
  private readonly prePruneEnabled: boolean
  private readonly prePruneOptions?: PrePruneOptions
  private readonly structuredSummaryEnabled: boolean
  private readonly onCompactionEffective?: (info: {
    conversationId: string
    tier: CompactionTier
  }) => void
  private readonly maxMessages?: number
  /**
   * T1.1 — Previous structured summary text. Persists across compactions
   * within the same task so the next call sends `### Previous Summary` and
   * asks for a DELTA UPDATE instead of a full re-summary (avoids summary
   * drift). Reset on task termination; not persisted across pod restarts in
   * T1.1 (T2.1 SQLite store will persist it).
   */
  private _previousSummary: string | null = null

  /**
   * @param maxTokens     - Maximum context window size in tokens.
   * @param workspace     - WorkspaceService for archiving turns to daily log.
   * @param llmPort       - LlmPort for summarization (85-95% tier).
   * @param tokenCounter  - P.2 provider-aware counter. When provided, the
   *                        manager uses it (or the dry-run delta) instead of
   *                        the heuristic. When omitted, falls back to legacy.
   * @param options       - P.2 dry-run gating + T1.4 anti-thrash thresholds.
   */
  constructor(
    maxTokens: number = 100000,
    workspace?: Workspace,
    llmPort?: LlmPort,
    tokenCounter?: TokenCounter,
    options: PressureContextManagerOptions = {}
  ) {
    this.maxTokens = maxTokens
    this.workspace = workspace
    this.llmPort = llmPort
    this.tokenCounter = tokenCounter
    this.dryRun = options.dryRun ?? false
    this.ineffectiveRatio = options.ineffectiveRatio ?? 0.9
    this.ineffectiveMaxRun = options.ineffectiveMaxRun ?? 2
    this.events = options.events
    this.taskId = options.taskId
    this.prePruneEnabled = options.prePruneEnabled ?? false
    this.prePruneOptions = options.prePruneOptions
    this.structuredSummaryEnabled = options.structuredSummaryEnabled ?? false
    this.onCompactionEffective = options.onCompactionEffective
    this.maxMessages = options.maxMessages
  }

  /**
   * T1.1 — accessor for tests that need to assert state across calls.
   */
  getPreviousSummary(): string | null {
    return this._previousSummary
  }

  /**
   * T1.1 — invoked by `TaskExecutor.handleLoopResult` (or the manual compact
   * endpoint) when the task wraps up. Mirrors how `CompactionState` already
   * gets reset on terminal results in T1.4.
   */
  resetPreviousSummary(): void {
    this._previousSummary = null
  }

  async manage(
    messages: ChatMessage[],
    conversation: Conversation,
    options?: ContextManageOptions
  ): Promise<ChatMessage[]> {
    // IronClaw invariant #1 (P.3 §4.1 + P.5 §5.3 hybrid guard):
    // primary defense is in `runToolUseLoop` via `LoopConfig.skipContextManager`
    // (emits `compaction:skipped` + owns the metric). This in-method check is
    // a SECOND LINE OF DEFENSE for callers that bypass the loop — e.g. the
    // `POST /v1/runtime/compact` endpoint (T1.1) or direct unit tests. Silent
    // passthrough on purpose: the loop is the metric owner. T1.4 also relies
    // on the early-return so `compactionState` is left untouched (the
    // defensive guard must not count against `ineffectiveCount`).
    if (conversation.pending_approval !== undefined) {
      return messages
    }

    // T1.1 — `forceTier: 'summarize'` bypasses the pressure-based dispatcher
    // entirely. Used by `POST /v1/runtime/compact` so an operator can request
    // a summary regardless of current token usage (focus topic, etc.). Pre-prune
    // and anti-thrash bookkeeping are skipped: a forced summarize is a
    // single-shot operator action, not part of the auto-compaction cadence.
    if (options?.forceTier === 'summarize') {
      const systemMsgs = messages.filter(m => m.role === 'system')
      const nonSystemMsgs = messages.filter(m => m.role !== 'system')
      const postMessages = await this.summarize(systemMsgs, nonSystemMsgs, 5, options?.focus)
      const ratio = measureCompactionRatio(messages, postMessages)
      clerumCompactionRatio.observe(ratio)
      clerumCompactionTotal.inc({ tier: 'summarize', outcome: 'ok' })
      this.onCompactionEffective?.({ conversationId: conversation.id, tier: 'summarize' })
      return postMessages
    }

    const tools = options?.tools ?? []
    const systemPrompt = options?.systemPrompt
    const pressure = await this.computePressure(messages, tools, systemPrompt)

    if (pressure < COMPACTION_PRESSURE_THRESHOLD) {
      return messages // Passthrough — does NOT touch compactionState (no attempt made).
    }

    // T1.2 — deterministic pre-prune BEFORE any tier runs. Operates on a
    // copy; if linkages break (e.g. a bug in a new pass) `validateToolLinkages`
    // hard-fails per P1-011 — no try/catch, the goldens must catch it. When
    // pre-prune alone brings pressure back under 80%, we return the pruned
    // set without invoking the tier (no LLM call, no workspace write).
    let working = messages
    if (this.prePruneEnabled) {
      const result = prePrune(messages, this.prePruneOptions, {
        inputTokens: pressure * this.maxTokens,
        contextWindowTokens: this.maxTokens,
      })
      working = result.messages
      if (result.passesApplied.length > 0) {
        validateToolLinkages(working)
        const savings = result.preTokens - result.postTokens
        if (savings > 0) {
          clerumPrePruneSavingsTokensTotal.inc(savings)
        }
        this.emitPrePruneEvent(conversation.id, result)
        const newPressure = await this.computePressure(working, tools, systemPrompt)
        if (newPressure < COMPACTION_PRESSURE_THRESHOLD) {
          return working // pre-prune alone was enough — skip the tier.
        }
      }
    }

    // T1.4 — lagged backoff transition. The 2nd consecutive ineffective
    // compaction does run (matches plan §8.1 case 3: `ineffectiveCount === 2`,
    // `stoppedForTask === false`). On the NEXT invocation the top-of-method
    // check sees the count, flips `stoppedForTask`, emits the one-shot event
    // and returns no-op (plan §8.1 case 4: "el backoff dispara recién en la
    // siguiente llamada"). The `!stoppedForTask` guard makes the event fire
    // exactly once per task.
    const state = ensureCompactionState(conversation)
    if (state.ineffectiveCount >= this.ineffectiveMaxRun) {
      if (!state.stoppedForTask) {
        state.stoppedForTask = true
        // The event goes to the bus, which only exists when `events` is wired;
        // this goes to the pod log, which is where an operator looks when a
        // conversation quietly stops being compacted. The turn proceeds
        // uncompacted from here, so the refusal that follows is expected (#731).
        // The conversation id stays out of the log line: on the email channel it
        // embeds the sender's address, and redaction matches keys, not values.
        logger.warn(
          {
            component: 'ContextManager',
            taskId: this.taskId,
            pressure,
            lastRatio: state.lastRatio,
            messageCount: working.length,
          },
          'Compaction backoff: history cannot be shrunk; proceeding uncompacted'
        )
        this.emitThrashingEvent(conversation.id, state.lastRatio, state.ineffectiveCount)
      }
      clerumCompactionTotal.inc({ tier: tierLabel(pressure), outcome: 'thrashing' })
      return working
    }

    // Always keep system message(s)
    const systemMsgs = working.filter(m => m.role === 'system')
    const nonSystemMsgs = working.filter(m => m.role !== 'system')

    let postMessages: ChatMessage[]
    let tier: CompactionTier
    if (pressure >= 0.95) {
      tier = 'truncate'
      postMessages = this.truncate(systemMsgs, nonSystemMsgs, 3)
    } else if (pressure >= 0.85) {
      tier = 'summarize'
      // Auto-compaction never carries a focus; the field is only meaningful
      // for `forceTier: 'summarize'`. Explicitly pass `undefined` so that a
      // caller who hands `{ focus }` without `forceTier` cannot accidentally
      // bias the automatic summary (the `forceTier === 'summarize'` branch
      // above is the only legitimate consumer of `options?.focus`).
      postMessages = await this.summarize(systemMsgs, nonSystemMsgs, 5, undefined)
    } else {
      tier = 'move_to_workspace'
      postMessages = await this.moveToWorkspace(systemMsgs, nonSystemMsgs, 8)
    }

    // T1.4 — measure effectiveness on the heuristic so trigger and measurement
    // share rounding. Histogram is observed for every *real* attempt.
    // Denominator is `working` (post pre-prune), not `messages`: pre-prune
    // already emitted its own savings event/metric, and using the original
    // input would let pre-prune deflate the ratio and mask an ineffective
    // tier — defeating the anti-thrash backoff.
    const ratio = measureCompactionRatio(working, postMessages)
    clerumCompactionRatio.observe(ratio)
    state.lastRatio = ratio

    if (ratio > this.ineffectiveRatio) {
      state.ineffectiveCount += 1
    } else {
      state.ineffectiveCount = 0
    }
    clerumCompactionTotal.inc({ tier, outcome: 'ok' })

    // T2.2 — fire the compaction-effective hook so prompt-cache callers can
    // invalidate the cached `parts` (the `stable` tier re-snapshots the daily
    // log on the next build). Only on `summarize` because that's the tier the
    // plan describes as "new session of the lineage" (§5.3a / §5.7); the
    // truncate / move_to_workspace tiers drop turns without changing the
    // session identity, so the cache stays valid.
    //
    // TODO(T2.2 round 2): `move_to_workspace` appends archived turns to the
    // daily log, which IS included in the semi-stable system-prompt tier.
    // `parts[1]` stays stale until the next task start re-snapshots the
    // daily log. The mismatch is bounded (move_to_workspace only fires in
    // pressure ∈ [0.8, 0.85) and the daily log refreshes at task start),
    // but it is not zero. Before expanding invalidations to this tier:
    // instrument prompt-cache hit-rate before/after, then decide whether
    // the extra invalidation pays for itself.
    if (tier === 'summarize') {
      this.onCompactionEffective?.({ conversationId: conversation.id, tier })
    }

    return postMessages
  }

  /**
   * T1.2 — emit `compaction:pre_prune_executed` whenever any pass mutated the
   * message array. Silent no-op when no emitter was wired (e.g. unit tests).
   */
  private emitPrePruneEvent(
    conversationId: string,
    result: { preTokens: number; postTokens: number; passesApplied: string[] }
  ): void {
    if (!this.events) return
    this.events.emit({
      type: 'compaction:pre_prune_executed',
      data: {
        taskId: this.taskId,
        conversationId,
        preTokens: result.preTokens,
        postTokens: result.postTokens,
        savingsTokens: result.preTokens - result.postTokens,
        savingsRatio: result.preTokens > 0 ? result.postTokens / result.preTokens : 1,
        passesApplied: result.passesApplied,
      },
      timestamp: new Date(),
    })
  }

  /**
   * T1.4 — emit the one-shot `compaction:thrashing` event on the core bus.
   * `eventWiring.ts` translates it into a `compaction.skipped`-style activity
   * record (warning severity). Silent no-op when no emitter was wired.
   */
  private emitThrashingEvent(
    conversationId: string,
    lastRatio: number,
    consecutiveCount: number
  ): void {
    if (!this.events) return
    this.events.emit({
      type: 'compaction:thrashing',
      data: {
        taskId: this.taskId,
        conversationId,
        lastRatio,
        consecutiveCount,
      },
      timestamp: new Date(),
    })
  }

  /**
   * Pressure is the larger of the token ratio and, when the provider's
   * contract bounds it, the message-count ratio (#731): the contract refuses
   * `messages.length > maxMessages` whatever the token count.
   */
  private async computePressure(
    messages: ChatMessage[],
    tools: ToolDefinition[],
    systemPrompt: string | undefined
  ): Promise<number> {
    const tokenPressure = await this.computeTokenPressure(messages, tools, systemPrompt)
    if (this.maxMessages === undefined) return tokenPressure
    return Math.max(tokenPressure, messages.length / this.maxMessages)
  }

  /**
   * Resolve the token pressure ratio from `tierDecisionTokens`. Three branches:
   *   - No counter: legacy heuristic (preserves pre-P.2 behavior bit-for-bit).
   *   - dryRun=true: the heuristic decides the tier; the counter's number is
   *     computed too, and the delta and any tier mismatch are emitted as
   *     metrics for the bake-week.
   *   - dryRun=false: the counter drives the decision directly.
   * Every branch counts `tools` and the system prompt with the messages: all
   * three travel in the request the provider caps (#731, R9-14).
   */
  private async computeTokenPressure(
    messages: ChatMessage[],
    tools: ToolDefinition[],
    systemPrompt: string | undefined
  ): Promise<number> {
    const counted = withSystemPrompt(messages, systemPrompt)
    const decided = await tierDecisionTokens(counted, tools, this.tokenCounter, this.dryRun)
    if (this.tokenCounter && this.dryRun) {
      await this.observeDryrunDelta(this.tokenCounter, counted, tools, decided)
    }
    return decided / this.maxTokens
  }

  /** Dry-run metrics: how far the counter's number is from the heuristic's. */
  private async observeDryrunDelta(
    tokenCounter: TokenCounter,
    messages: ChatMessage[],
    tools: ToolDefinition[],
    heuristic: number
  ): Promise<void> {
    let real: number
    try {
      real = await tokenCounter.count(messages, tools)
    } catch (err) {
      logger.warn({ component: 'ContextManager', err }, 'dryrun counter failed; using heuristic')
      return
    }
    const heuristicTier = tierFor(heuristic / this.maxTokens)
    const realTier = tierFor(real / this.maxTokens)
    const delta = heuristic > 0 ? real / heuristic : 0
    tokenizerDryrunDelta.observe(
      { provider: tokenCounter.providerName, tier_chosen: heuristicTier },
      delta
    )
    if (heuristicTier !== realTier) {
      tokenizerDryrunTierMismatchTotal.inc({ from: heuristicTier, to: realTier })
    }
  }

  /**
   * Compute the aligned cut + kept/archived split for a given keepRecent count.
   * Shared by all three tiers — every tier first picks the proposed cut by
   * turn count, then passes it through the T1.3 boundary aligner so the cut
   * never splits a tool-call pair and never archives the last user message.
   */
  private alignedSlice(
    systemMsgs: ChatMessage[],
    nonSystemMsgs: ChatMessage[],
    keepRecent: number
  ): { kept: ChatMessage[]; archived: ChatMessage[] } {
    const turns = splitTurns(nonSystemMsgs)
    const proposedCut = turnIndexToMessageIndex(turns, Math.max(0, turns.length - keepRecent))
    return applyAlignedCut(systemMsgs, nonSystemMsgs, proposedCut)
  }

  /**
   * Truncate: drop old turns, no archival. Used for emergency (>95%).
   */
  private truncate(
    systemMsgs: ChatMessage[],
    nonSystemMsgs: ChatMessage[],
    keepRecent: number
  ): ChatMessage[] {
    const { kept } = this.alignedSlice(systemMsgs, nonSystemMsgs, keepRecent)
    return kept
  }

  /**
   * MoveToWorkspace: format old turns as markdown, append to daily log,
   * then drop them. Falls back to truncate if no workspace available.
   */
  private async moveToWorkspace(
    systemMsgs: ChatMessage[],
    nonSystemMsgs: ChatMessage[],
    keepRecent: number
  ): Promise<ChatMessage[]> {
    const { kept, archived } = this.alignedSlice(systemMsgs, nonSystemMsgs, keepRecent)

    if (this.workspace && archived.length > 0) {
      const archivedTurns = splitTurns(archived)
      const markdown = formatTurnsAsMarkdown(archivedTurns)
      const header = `### Context Compacted (${archivedTurns.length} turns archived)\n\n`
      try {
        await this.workspace.appendDailyLog(header + markdown)
        logger.info(
          { component: 'ContextManager', archivedTurns: archivedTurns.length },
          'MoveToWorkspace: archived turns to daily log'
        )
      } catch (err) {
        logger.error(
          { component: 'ContextManager', err },
          'MoveToWorkspace: failed to archive turns'
        )
      }
    }

    return kept
  }

  /**
   * Summarize: call LLM to summarize old turns, write summary to daily log,
   * then drop old turns. Falls back to truncate if no LLM port available.
   *
   * T1.1 — when `structuredSummaryEnabled` is true the prompt switches to the
   * section-anchored template (`structuredSummaryTemplate.ts`) and the output
   * is run through `parseStructuredSummary`. If the LLM ignores the schema
   * the rawBody is persisted anyway and `_previousSummary` is updated for the
   * next delta attempt. `focus` is honoured only in the structured path; in
   * the legacy path it is silently ignored (auto-compaction never sets it).
   */
  private async summarize(
    systemMsgs: ChatMessage[],
    nonSystemMsgs: ChatMessage[],
    keepRecent: number,
    focus?: string
  ): Promise<ChatMessage[]> {
    const { kept, archived } = this.alignedSlice(systemMsgs, nonSystemMsgs, keepRecent)

    if (archived.length === 0) {
      return kept
    }

    // If no LLM port, fall back to MoveToWorkspace behavior
    if (!this.llmPort) {
      return this.moveToWorkspace(systemMsgs, nonSystemMsgs, keepRecent)
    }

    const archivedTurns = splitTurns(archived)
    const conversationText = formatTurnsAsMarkdown(archivedTurns)
    const useStructured = this.structuredSummaryEnabled
    const systemPrompt = useStructured
      ? buildStructuredSummaryPrompt({
          previousSummary: this._previousSummary,
          focus: focus ?? null,
          maxTokens: 1024,
        })
      : SUMMARIZE_PROMPT

    const summarizationMessages: ChatMessage[] = [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: conversationText },
    ]

    let rawSummary: string
    try {
      const response = await this.llmPort.complete({
        messages: summarizationMessages,
        max_tokens: 1024,
        temperature: 0.3,
      })
      rawSummary = response.content
      logger.info(
        {
          component: 'ContextManager',
          archivedTurns: archivedTurns.length,
          summaryChars: rawSummary.length,
        },
        'Summarize: condensed turns'
      )
    } catch (err) {
      logger.error(
        { component: 'ContextManager', err },
        'Summarize: LLM call failed, falling back to MoveToWorkspace'
      )
      return this.moveToWorkspace(systemMsgs, nonSystemMsgs, keepRecent)
    }

    let summaryToPersist = rawSummary
    if (useStructured) {
      const parsed = parseStructuredSummary(rawSummary)
      clerumCompactionStructuredParseTotal.inc({ outcome: parsed.parseStatus })

      if (parsed.parseStatus === 'fallback') {
        logger.warn(
          { component: 'ContextManager' },
          'Summarize: LLM ignored structured schema, using raw output'
        )
      }
      // Plan §6.2 — if the Memory Writes header is present but contents were
      // rejected (paraphrased / unanchored), append a placeholder so the agent
      // re-reads MEMORY.md from disk on resume.
      const memoryHeaderSeen = /^##\s+Memory Writes/im.test(rawSummary)
      if (memoryHeaderSeen && parsed.memoryWrites === null) {
        summaryToPersist =
          rawSummary + '\n\n[memory writes section could not be parsed — review previous turn]\n'
      }
      // Always stash the rawBody for the next delta-patch — even on fallback,
      // the next iteration can at least diff against it.
      this._previousSummary = parsed.rawBody
    }

    // Write summary to workspace
    if (this.workspace) {
      const header = `### Context Summary (${archivedTurns.length} turns summarized)\n\n`
      try {
        await this.workspace.appendDailyLog(header + summaryToPersist)
      } catch (err) {
        logger.error({ component: 'ContextManager', err }, 'Summarize: failed to write summary')
      }
    }

    return kept
  }
}

/**
 * Simple single-threshold context manager for in-loop usage.
 * Passes through if under threshold, otherwise keeps last N turns.
 */
export class InLoopContextManager implements ContextManager {
  private readonly thresholdTokens: number
  private readonly maxTurns: number

  constructor(thresholdTokens: number = 80000, maxTurns: number = 5) {
    this.thresholdTokens = thresholdTokens
    this.maxTurns = maxTurns
  }

  manage(
    messages: ChatMessage[],
    conversation: Conversation,
    options?: ContextManageOptions
  ): ChatMessage[] {
    // IronClaw invariant #1 — same defensive guard as PressureContextManager.
    if (conversation.pending_approval !== undefined) {
      return messages
    }
    // The tool schemas and the system prompt travel with every request, so they
    // count against the threshold exactly as in PressureContextManager.computePressure.
    const estimated =
      estimateTokens(withSystemPrompt(messages, options?.systemPrompt)) +
      heuristicCountTools(options?.tools ?? [])

    if (estimated < this.thresholdTokens) {
      return messages // Passthrough
    }

    const systemMsgs = messages.filter(m => m.role === 'system')
    const nonSystemMsgs = messages.filter(m => m.role !== 'system')

    const turns = splitTurns(nonSystemMsgs)
    const proposedCut = turnIndexToMessageIndex(turns, Math.max(0, turns.length - this.maxTurns))
    const { kept } = applyAlignedCut(systemMsgs, nonSystemMsgs, proposedCut)
    return kept
  }
}