@lota-sdk/core 0.1.5

package/src/runtime/context-compaction.ts

@@ -0,0 +1,909 @@
+import { createHash, randomUUID } from 'node:crypto'
+
+import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+
+import { readString } from '../utils/string'
+import {
+  COMPACTION_CHUNK_MAX_CHARS,
+  CONTEXT_COMPACTION_INCLUDED_TOOL_NAMES,
+  CONTEXT_COMPACTION_INCLUDED_TOOL_PREFIXES,
+  CONTEXT_COMPACTION_THRESHOLD_RATIO,
+  CONTEXT_OUTPUT_RESERVE_TOKENS,
+  CONTEXT_SAFETY_MARGIN_TOKENS,
+  SUMMARY_ROLLUP_MAX_TOKENS,
+} from './context-compaction-constants'
+import {
+  StructuredCompactionOutputSchema,
+  WorkstreamStateDeltaSchema,
+  WORKSTREAM_STATE_MAX_ACTIVE_CONSTRAINTS,
+  WORKSTREAM_STATE_MAX_AGENT_CONTRIBUTIONS,
+  WORKSTREAM_STATE_MAX_ARTIFACTS,
+  WORKSTREAM_STATE_MAX_KEY_DECISIONS,
+  WORKSTREAM_STATE_MAX_OPEN_QUESTIONS,
+  WORKSTREAM_STATE_MAX_RISKS,
+  WORKSTREAM_STATE_MAX_TASKS,
+  WorkstreamStateSchema,
+  createEmptyWorkstreamState,
+  parseStructuredWorkstreamStateDelta,
+} from './workstream-state'
+import type { CompactionOutput, WorkstreamState, WorkstreamStateDelta } from './workstream-state'
+
+export interface ContextMessage {
+  role: 'system' | 'user' | 'assistant'
+  text: string
+  sourceMessageId: string
+}
+
+export interface CompactionAssessment {
+  estimatedTokens: number
+  threshold: number
+  shouldCompact: boolean
+}
+
+export interface CompactHistoryParams {
+  summaryText: string
+  liveMessages: ChatMessage[]
+  tailMessageCount: number
+  contextSize?: number
+  existingState: WorkstreamState
+}
+
+export interface CompactHistoryResult {
+  compacted: boolean
+  summaryText: string
+  lastCompactedMessageId?: string
+  compactedMessages: ChatMessage[]
+  compactedMessageCount: number
+  remainingMessageCount: number
+  estimatedTokens: number
+  inputChars: number
+  outputChars: number
+  state: WorkstreamState
+  stateDelta: WorkstreamStateDelta
+}
+
+export interface ContextCompactionRunnerParams {
+  previousSummary: string
+  existingState: WorkstreamState
+  chunk: ContextMessage[]
+  transcript: string
+}
+
+export interface ContextCompactionPromptParams {
+  previousSummary: string
+  existingState: WorkstreamState
+  transcript: string
+}
+
+export interface MemoryBlockCompactionPromptParams {
+  previousSummary: string
+  newEntriesText: string
+}
+
+export type ContextCompactionRunner = (params: ContextCompactionRunnerParams) => Promise<CompactionOutput>
+
+export interface CreateContextCompactionRuntimeOptions {
+  runCompacter: ContextCompactionRunner
+  now?: () => number
+  randomId?: () => string
+  thresholdRatio?: number
+  outputReserveTokens?: number
+  safetyMarginTokens?: number
+  compactionChunkMaxChars?: number
+  summaryRollupMaxTokens?: number
+  includedToolNames?: readonly string[]
+  includedToolPrefixes?: readonly string[]
+}
+
+const PROMPT_INJECTION_PATTERN =
+  /\b(ignore (all )?(previous|prior|system|developer)? instructions?|system prompt|developer prompt|tool override|jailbreak|role ?override|do not follow|bypass)\b/i
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 3)
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim()
+}
+
+function sanitizeStateText(value: string): string | null {
+  const normalized = normalizeWhitespace(value)
+  if (!normalized) return null
+  if (PROMPT_INJECTION_PATTERN.test(normalized)) return null
+  return normalized
+}
+
+function createStableId(prefix: string, ...parts: Array<string | number | undefined>): string {
+  const payload = parts
+    .map((part) => (part === undefined ? '' : String(part)))
+    .map((part) => normalizeWhitespace(part))
+    .join('|')
+  const hash = createHash('sha1').update(`${prefix}|${payload}`).digest('hex').slice(0, 20)
+  return `${prefix}_${hash}`
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null
+}
+
+function stringifyUnknown(value: unknown): string | null {
+  if (value === undefined) return null
+  if (typeof value === 'string') {
+    const normalized = value.trim()
+    return normalized.length > 0 ? normalized : null
+  }
+
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return null
+  }
+}
+
+function appendUnique(values: string[], nextValues: string[]): string[] {
+  const seen = new Set(values.map((value) => normalizeWhitespace(value).toLowerCase()))
+  const merged = [...values]
+
+  for (const value of nextValues) {
+    const normalized = normalizeWhitespace(value)
+    if (!normalized) continue
+    const key = normalized.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    merged.push(normalized)
+  }
+
+  return merged
+}
+
+function formatSummary(summaryText: string): string {
+  return `Compacted context summary:\n${summaryText.trim()}`
+}
+
+function normalizeSummary(summaryText: string): string {
+  return summaryText.trim()
+}
+
+function buildSyntheticSummaryPayload(
+  summaryText: string,
+): { role: 'system'; parts: Array<{ type: 'text'; text: string }> } | null {
+  const summary = normalizeSummary(summaryText)
+  if (!summary) return null
+  return { role: 'system', parts: [{ type: 'text', text: formatSummary(summary) }] }
+}
+
+function readIsCompacted(message: ChatMessage): boolean {
+  const metadata = message.metadata && typeof message.metadata === 'object' ? message.metadata : undefined
+  return metadata ? (metadata as Record<string, unknown>).isCompacted === true : false
+}
+
+function markMessageCompacted(message: ChatMessage, now: () => number): ChatMessage {
+  if (readIsCompacted(message)) return message
+
+  return {
+    ...message,
+    metadata:
+      message.metadata && typeof message.metadata === 'object'
+        ? { ...message.metadata, isCompacted: true }
+        : { createdAt: now(), isCompacted: true },
+  }
+}
+
+export function parseWorkstreamState(value: unknown): WorkstreamState {
+  const parsed = WorkstreamStateSchema.safeParse(value)
+  return parsed.success ? parsed.data : createEmptyWorkstreamState()
+}
+
+function pickDefined<T extends Record<string, unknown>, K extends keyof T>(
+  next: T,
+  base: T,
+  key: K,
+): Partial<Pick<T, K>> {
+  if (next[key] !== undefined) {
+    return { [key]: next[key] } as Partial<Pick<T, K>>
+  }
+  if (base[key] !== undefined) {
+    return { [key]: base[key] } as Partial<Pick<T, K>>
+  }
+  return {}
+}
+
+export function toStateFieldsUpdated(delta: WorkstreamStateDelta): string[] {
+  const fields: string[] = []
+  if (delta.currentPlan !== undefined) fields.push('currentPlan')
+  if ((delta.newDecisions?.length ?? 0) > 0) fields.push('keyDecisions')
+  if ((delta.resolvedQuestions?.length ?? 0) > 0 || (delta.newQuestions?.length ?? 0) > 0) fields.push('openQuestions')
+  if ((delta.newConstraints?.length ?? 0) > 0) fields.push('activeConstraints')
+  if ((delta.newRisks?.length ?? 0) > 0) fields.push('risks')
+  if ((delta.taskUpdates?.length ?? 0) > 0) fields.push('tasks')
+  if ((delta.artifacts?.length ?? 0) > 0) fields.push('artifacts')
+  if (delta.agentNote) fields.push('agentContributions')
+  if ((delta.conflicts?.length ?? 0) > 0) fields.push('conflicts')
+
+  if (
+    delta.approvedBy !== undefined ||
+    delta.approvedAt !== undefined ||
+    delta.approvalMessageId !== undefined ||
+    delta.approvalNote !== undefined
+  ) {
+    fields.push('approval')
+  }
+
+  return fields
+}
+
+function toCompactionTranscript(messages: ContextMessage[]): string {
+  return messages
+    .map((message, index) => {
+      const role = message.role.toUpperCase()
+      const content = message.text.trim() || '[no text]'
+      return `[${index + 1}] (id=${message.sourceMessageId}) ${role}: ${content}`
+    })
+    .join('\n\n')
+}
+
+function splitByCharBudget(messages: ContextMessage[], maxChars: number): ContextMessage[][] {
+  if (messages.length === 0) return []
+
+  const chunks: ContextMessage[][] = []
+  let current: ContextMessage[] = []
+  let currentChars = 0
+
+  for (const message of messages) {
+    const serialized = `${message.role}:${message.text}`
+    const nextChars = serialized.length
+
+    if (current.length > 0 && currentChars + nextChars > maxChars) {
+      chunks.push(current)
+      current = [message]
+      currentChars = nextChars
+      continue
+    }
+
+    current.push(message)
+    currentChars += nextChars
+  }
+
+  if (current.length > 0) chunks.push(current)
+  return chunks
+}
+
+function mergeDelta(base: WorkstreamStateDelta, next: WorkstreamStateDelta): WorkstreamStateDelta {
+  return {
+    ...(next.currentPlan !== undefined
+      ? { currentPlan: next.currentPlan }
+      : base.currentPlan !== undefined
+        ? { currentPlan: base.currentPlan }
+        : {}),
+    ...(appendUnique(base.newConstraints ?? [], next.newConstraints ?? []).length > 0
+      ? { newConstraints: appendUnique(base.newConstraints ?? [], next.newConstraints ?? []) }
+      : {}),
+    ...(appendUnique(base.newRisks ?? [], next.newRisks ?? []).length > 0
+      ? { newRisks: appendUnique(base.newRisks ?? [], next.newRisks ?? []) }
+      : {}),
+    ...(appendUnique(base.newQuestions ?? [], next.newQuestions ?? []).length > 0
+      ? { newQuestions: appendUnique(base.newQuestions ?? [], next.newQuestions ?? []) }
+      : {}),
+    ...(appendUnique(base.resolvedQuestions ?? [], next.resolvedQuestions ?? []).length > 0
+      ? { resolvedQuestions: appendUnique(base.resolvedQuestions ?? [], next.resolvedQuestions ?? []) }
+      : {}),
+    ...((base.newDecisions?.length ?? 0) + (next.newDecisions?.length ?? 0) > 0
+      ? { newDecisions: [...(base.newDecisions ?? []), ...(next.newDecisions ?? [])] }
+      : {}),
+    ...((base.taskUpdates?.length ?? 0) + (next.taskUpdates?.length ?? 0) > 0
+      ? { taskUpdates: [...(base.taskUpdates ?? []), ...(next.taskUpdates ?? [])] }
+      : {}),
+    ...((base.artifacts?.length ?? 0) + (next.artifacts?.length ?? 0) > 0
+      ? { artifacts: [...(base.artifacts ?? []), ...(next.artifacts ?? [])] }
+      : {}),
+    ...(next.agentNote ? { agentNote: next.agentNote } : base.agentNote ? { agentNote: base.agentNote } : {}),
+    ...((base.conflicts?.length ?? 0) + (next.conflicts?.length ?? 0) > 0
+      ? { conflicts: [...(base.conflicts ?? []), ...(next.conflicts ?? [])] }
+      : {}),
+    ...pickDefined(next, base, 'approvedBy'),
+    ...pickDefined(next, base, 'approvedAt'),
+    ...pickDefined(next, base, 'approvalMessageId'),
+    ...pickDefined(next, base, 'approvalNote'),
+  }
+}
+
+export function mergeStateDelta(
+  existingState: WorkstreamState,
+  delta: WorkstreamStateDelta,
+  now: () => number,
+): WorkstreamState {
+  const timestamp = now()
+  const state: WorkstreamState = {
+    ...existingState,
+    currentPlan: existingState.currentPlan ? { ...existingState.currentPlan } : null,
+    activeConstraints: [...existingState.activeConstraints],
+    keyDecisions: [...existingState.keyDecisions],
+    tasks: [...existingState.tasks],
+    openQuestions: [...existingState.openQuestions],
+    risks: [...existingState.risks],
+    artifacts: [...existingState.artifacts],
+    agentContributions: [...existingState.agentContributions],
+    lastUpdated: timestamp,
+  }
+
+  if (delta.currentPlan !== undefined) {
+    if (delta.currentPlan === null) {
+      state.currentPlan = null
+    } else {
+      const planText = sanitizeStateText(delta.currentPlan)
+      if (planText) {
+        const planId = createStableId('plan', planText)
+        const existingPlan = state.currentPlan && state.currentPlan.id === planId ? state.currentPlan : null
+        state.currentPlan = {
+          id: planId,
+          text: planText,
+          source: 'agent',
+          approved: existingPlan?.approved ?? false,
+          timestamp,
+          sourceMessageIds: existingPlan?.sourceMessageIds ?? [],
+        }
+      }
+    }
+  }
+
+  if (delta.newConstraints?.length) {
+    for (const rawConstraint of delta.newConstraints) {
+      const text = sanitizeStateText(rawConstraint)
+      if (!text) continue
+      const constraintId = createStableId('constraint', text)
+      const exists = state.activeConstraints.some((constraint) => constraint.id === constraintId)
+      if (exists) continue
+      state.activeConstraints.push({
+        id: constraintId,
+        text,
+        source: 'agent',
+        approved: false,
+        timestamp,
+        sourceMessageIds: [],
+      })
+    }
+  }
+
+  if (delta.newRisks?.length) {
+    state.risks = appendUnique(state.risks, delta.newRisks)
+  }
+
+  if (delta.resolvedQuestions?.length) {
+    const resolvedIds = new Set(
+      delta.resolvedQuestions
+        .map((question) => sanitizeStateText(question))
+        .filter((question): question is string => Boolean(question))
+        .map((question) => createStableId('question', question)),
+    )
+    state.openQuestions = state.openQuestions.filter((question) => !resolvedIds.has(question.id))
+  }
+
+  if (delta.newQuestions?.length) {
+    for (const rawQuestion of delta.newQuestions) {
+      const text = sanitizeStateText(rawQuestion)
+      if (!text) continue
+      const questionId = createStableId('question', text)
+      const exists = state.openQuestions.some((question) => question.id === questionId)
+      if (exists) continue
+      state.openQuestions.push({ id: questionId, text, source: 'agent', timestamp, sourceMessageIds: [] })
+    }
+  }
+
+  if (delta.newDecisions?.length) {
+    for (const decision of delta.newDecisions) {
+      const normalizedDecision = sanitizeStateText(decision.decision)
+      const normalizedRationale = sanitizeStateText(decision.rationale)
+      if (!normalizedDecision || !normalizedRationale) continue
+
+      const sourceIds = [...new Set(decision.sourceMessageIds.map((id) => normalizeWhitespace(id)).filter(Boolean))]
+      const decisionId = createStableId('decision', normalizedDecision, normalizedRationale, sourceIds.sort().join('|'))
+      const alreadyExists = state.keyDecisions.some((item) => item.id === decisionId)
+      if (alreadyExists) continue
+      state.keyDecisions.push({
+        id: decisionId,
+        decision: normalizedDecision,
+        rationale: normalizedRationale,
+        agent: normalizeWhitespace(decision.agent),
+        sourceMessageIds: sourceIds,
+        confidence: decision.confidence,
+        timestamp,
+      })
+    }
+  }
+
+  if (delta.taskUpdates?.length) {
+    for (const update of delta.taskUpdates) {
+      const title = sanitizeStateText(update.title)
+      if (!title) continue
+
+      const externalId = sanitizeStateText(update.externalId ?? '')
+      const owner = normalizeWhitespace(update.owner)
+      const taskId = externalId ? createStableId('task-external', externalId) : createStableId('task', title, owner)
+      const sourceMessageIds = [
+        ...new Set(update.sourceMessageIds.map((id) => normalizeWhitespace(id)).filter(Boolean)),
+      ]
+      const existingIndex = state.tasks.findIndex((task) => task.id === taskId)
+      const nextTask = {
+        id: taskId,
+        title,
+        status: update.status,
+        owner,
+        ...(externalId ? { externalId } : {}),
+        source: 'agent' as const,
+        sourceMessageIds,
+        timestamp,
+      }
+
+      if (existingIndex >= 0) {
+        const existingTask = state.tasks[existingIndex]
+        state.tasks[existingIndex] = {
+          ...nextTask,
+          sourceMessageIds: [...new Set([...existingTask.sourceMessageIds, ...sourceMessageIds])],
+        }
+      } else {
+        state.tasks.push(nextTask)
+      }
+    }
+  }
+
+  if (delta.artifacts?.length) {
+    for (const artifact of delta.artifacts) {
+      const name = sanitizeStateText(artifact.name)
+      const pointer = sanitizeStateText(artifact.pointer)
+      if (!name || !pointer) continue
+
+      const artifactId = createStableId('artifact', name, pointer)
+      const exists = state.artifacts.some((item) => item.id === artifactId)
+      if (exists) continue
+      state.artifacts.push({ id: artifactId, name, type: normalizeWhitespace(artifact.type), pointer, timestamp })
+    }
+  }
+
+  if (delta.agentNote) {
+    const agent = sanitizeStateText(delta.agentNote.agent)
+    const summary = sanitizeStateText(delta.agentNote.summary)
+    if (agent && summary) {
+      const noteId = createStableId('agent-note', agent, summary)
+      const exists = state.agentContributions.some((note) => note.id === noteId)
+      if (!exists) {
+        state.agentContributions.push({ id: noteId, agent, summary, timestamp })
+      }
+    }
+  }
+
+  if (delta.conflicts?.length) {
+    for (const conflict of delta.conflicts) {
+      const text = sanitizeStateText(`Conflict: ${conflict.recommendation}`)
+      if (!text) continue
+      const questionId = createStableId('question', text)
+      const exists = state.openQuestions.some((question) => question.id === questionId)
+      if (exists) continue
+      state.openQuestions.push({ id: questionId, text, source: 'agent', timestamp, sourceMessageIds: [] })
+    }
+  }
+
+  if (delta.approvedBy !== undefined) {
+    state.approvedBy = sanitizeStateText(delta.approvedBy) ?? undefined
+  }
+  if (delta.approvedAt !== undefined) {
+    state.approvedAt = delta.approvedAt
+  }
+  if (delta.approvalMessageId !== undefined) {
+    state.approvalMessageId = sanitizeStateText(delta.approvalMessageId) ?? undefined
+  }
+  if (delta.approvalNote !== undefined) {
+    state.approvalNote = sanitizeStateText(delta.approvalNote) ?? undefined
+  }
+
+  state.keyDecisions = state.keyDecisions.slice(-WORKSTREAM_STATE_MAX_KEY_DECISIONS)
+  state.activeConstraints = state.activeConstraints.slice(-WORKSTREAM_STATE_MAX_ACTIVE_CONSTRAINTS)
+  state.tasks = state.tasks.slice(-WORKSTREAM_STATE_MAX_TASKS)
+  state.openQuestions = state.openQuestions.slice(-WORKSTREAM_STATE_MAX_OPEN_QUESTIONS)
+  state.risks = state.risks.slice(-WORKSTREAM_STATE_MAX_RISKS)
+  state.artifacts = state.artifacts.slice(-WORKSTREAM_STATE_MAX_ARTIFACTS)
+  state.agentContributions = state.agentContributions.slice(-WORKSTREAM_STATE_MAX_AGENT_CONTRIBUTIONS)
+
+  return WorkstreamStateSchema.parse(state)
+}
+
+export interface ContextCompactionRuntime {
+  createSummaryMessage: (summaryText: string) => ChatMessage | null
+  prependSummaryMessage: (summaryText: string, liveMessages: ChatMessage[]) => ChatMessage[]
+  formatWorkstreamStateForPrompt: (state: WorkstreamState | null | undefined) => string | undefined
+  estimateThreshold: (contextSize?: number) => number
+  shouldCompactHistory: (params: {
+    summaryText: string
+    liveMessages: ChatMessage[]
+    contextSize?: number
+  }) => CompactionAssessment
+  compactHistory: (params: CompactHistoryParams) => Promise<CompactHistoryResult>
+}
+
+export function buildContextCompactionPrompt(params: ContextCompactionPromptParams): string {
+  return [
+    '<context-compaction-input>',
+    '<previous-summary>',
+    params.previousSummary.trim() || 'None',
+    '</previous-summary>',
+    '<existing-workstream-state>',
+    JSON.stringify(params.existingState),
+    '</existing-workstream-state>',
+    '<new-messages>',
+    params.transcript || 'None',
+    '</new-messages>',
+    '</context-compaction-input>',
+    '',
+    'Produce a concise replacement summary and a structured state delta.',
+    'Only include facts supported by the new messages.',
+    'Summary format is required and must use exactly these sections in order:',
+    'KEY FACTS:',
+    '- ...',
+    'CONVERSATION FLOW:',
+    '- ...',
+    'OPEN THREADS:',
+    '- ...',
+    'Return every stateDelta field. Use empty arrays for unchanged list fields, null for unchanged nullable fields, and currentPlan.action to signal unchanged, clear, or set.',
+  ].join('\n')
+}
+
+export function buildMemoryBlockCompactionPrompt(params: MemoryBlockCompactionPromptParams): string {
+  return [
+    '<memory-block-compaction>',
+    'Produce a compact replacement summary for the workstream memory block.',
+    'Preserve constraints, commitments, unresolved risks, and ownership.',
+    'Blend the previous summary with the new raw entries into one updated summary.',
+    'Return plain text only.',
+    '',
+    '<previous-summary>',
+    params.previousSummary.trim() || 'None',
+    '</previous-summary>',
+    '<new-entries>',
+    params.newEntriesText.trim() || 'None',
+    '</new-entries>',
+    '</memory-block-compaction>',
+  ].join('\n')
+}
+
+export function createContextCompactionRuntime(
+  options: CreateContextCompactionRuntimeOptions,
+): ContextCompactionRuntime {
+  const now = options.now ?? (() => Date.now())
+  const randomId = options.randomId ?? (() => randomUUID())
+  const thresholdRatio = options.thresholdRatio ?? CONTEXT_COMPACTION_THRESHOLD_RATIO
+  const outputReserveTokens = options.outputReserveTokens ?? CONTEXT_OUTPUT_RESERVE_TOKENS
+  const safetyMarginTokens = options.safetyMarginTokens ?? CONTEXT_SAFETY_MARGIN_TOKENS
+  const compactionChunkMaxChars = options.compactionChunkMaxChars ?? COMPACTION_CHUNK_MAX_CHARS
+  const summaryRollupMaxTokens = options.summaryRollupMaxTokens ?? SUMMARY_ROLLUP_MAX_TOKENS
+  const includedToolNames = new Set(options.includedToolNames ?? CONTEXT_COMPACTION_INCLUDED_TOOL_NAMES)
+  const includedToolPrefixes = options.includedToolPrefixes ?? CONTEXT_COMPACTION_INCLUDED_TOOL_PREFIXES
+
+  const shouldIncludeToolInCompaction = (toolName: string): boolean => {
+    if (includedToolNames.has(toolName)) return true
+    return includedToolPrefixes.some((prefix) => toolName.startsWith(prefix))
+  }
+
+  const toContextTextFromChatMessage = (message: ChatMessage): string => {
+    const chunks: string[] = []
+
+    for (const part of message.parts) {
+      const record = readRecord(part)
+      if (!record) continue
+
+      const type = readString(record.type)
+      if (type === 'text') {
+        const text = readString(record.text)
+        if (text) chunks.push(text)
+        continue
+      }
+
+      if (type?.startsWith('tool-')) {
+        const toolName = type.slice('tool-'.length) || 'unknown'
+        if (!shouldIncludeToolInCompaction(toolName)) continue
+        const state = readString(record.state)
+        const output = stringifyUnknown(record.output)
+        const input = stringifyUnknown(record.input)
+        const payload = output ?? input
+        if (payload) {
+          chunks.push(`[tool:${toolName}${state ? `:${state}` : ''}] ${payload}`)
+        }
+        continue
+      }
+
+      if (type?.startsWith('data-')) {
+        const dataPayload = stringifyUnknown(record.data)
+        if (dataPayload) {
+          chunks.push(`[${type}] ${dataPayload}`)
+        }
+      }
+    }
+
+    return chunks.join('\n').trim()
+  }
+
+  const toContextMessageFromChatMessage = (message: ChatMessage): ContextMessage => {
+    return { role: message.role, text: toContextTextFromChatMessage(message), sourceMessageId: message.id }
+  }
+
+  const formatWorkstreamStateForPrompt = (state: WorkstreamState | null | undefined): string | undefined => {
+    if (!state) return undefined
+
+    const approvedPlan =
+      state.currentPlan && state.currentPlan.approved ? sanitizeStateText(state.currentPlan.text) : null
+    const candidatePlan =
+      state.currentPlan && !state.currentPlan.approved ? sanitizeStateText(state.currentPlan.text) : null
+
+    const approvedConstraints = state.activeConstraints
+      .filter((constraint) => constraint.approved)
+      .map((constraint) => ({ ...constraint, text: sanitizeStateText(constraint.text) }))
+      .filter((constraint): constraint is typeof constraint & { text: string } => Boolean(constraint.text))
+
+    const candidateConstraints = state.activeConstraints
+      .filter((constraint) => !constraint.approved)
+      .map((constraint) => ({ ...constraint, text: sanitizeStateText(constraint.text) }))
+      .filter((constraint): constraint is typeof constraint & { text: string } => Boolean(constraint.text))
+
+    const openQuestions = state.openQuestions
+      .map((question) => ({ ...question, text: sanitizeStateText(question.text) }))
+      .filter((question): question is typeof question & { text: string } => Boolean(question.text))
+
+    const decisions = state.keyDecisions
+      .map((decision) => ({
+        ...decision,
+        decision: sanitizeStateText(decision.decision),
+        rationale: sanitizeStateText(decision.rationale),
+      }))
+      .filter((decision): decision is typeof decision & { decision: string; rationale: string } =>
+        Boolean(decision.decision && decision.rationale),
+      )
+
+    const tasks = state.tasks
+      .map((task) => ({ ...task, title: sanitizeStateText(task.title), owner: sanitizeStateText(task.owner) }))
+      .filter((task): task is typeof task & { title: string; owner: string } => Boolean(task.title && task.owner))
+
+    const artifacts = state.artifacts
+      .map((artifact) => ({
+        ...artifact,
+        name: sanitizeStateText(artifact.name),
+        pointer: sanitizeStateText(artifact.pointer),
+      }))
+      .filter((artifact): artifact is typeof artifact & { name: string; pointer: string } =>
+        Boolean(artifact.name && artifact.pointer),
+      )
+
+    const agentContributions = state.agentContributions
+      .map((note) => ({ ...note, summary: sanitizeStateText(note.summary) }))
+      .filter((note): note is typeof note & { summary: string } => Boolean(note.summary))
+
+    const payload = {
+      policy: { approvedConstraintsAreBinding: true, candidateStateIsAdvisoryOnly: true },
+      approved: {
+        currentPlan: approvedPlan ? { text: approvedPlan, source: state.currentPlan?.source } : null,
+        constraints: approvedConstraints.map((constraint) => ({
+          id: constraint.id,
+          text: constraint.text,
+          source: constraint.source,
+        })),
+      },
+      candidate: {
+        currentPlan: candidatePlan ? { text: candidatePlan, source: state.currentPlan?.source } : null,
+        constraints: candidateConstraints.map((constraint) => ({
+          id: constraint.id,
+          text: constraint.text,
+          source: constraint.source,
+        })),
+      },
+      decisions,
+      openQuestions,
+      risks: state.risks.map((risk) => sanitizeStateText(risk)).filter((risk): risk is string => Boolean(risk)),
+      tasks,
+      artifacts,
+      agentContributions,
+      advisory: {
+        approvedBy: state.approvedBy ?? null,
+        approvedAt: state.approvedAt ?? null,
+        approvalMessageId: state.approvalMessageId ?? null,
+        approvalNote: state.approvalNote ?? null,
+      },
+      lastUpdated: state.lastUpdated,
+    }
+
+    return ['<workstream-state>', JSON.stringify(payload, null, 2), '</workstream-state>'].join('\n')
+  }
+
+  const createSummaryMessage = (summaryText: string): ChatMessage | null => {
+    const summary = normalizeSummary(summaryText)
+    if (!summary) return null
+
+    return {
+      id: `summary-${randomId()}`,
+      role: 'system',
+      parts: [{ type: 'text', text: formatSummary(summary) }],
+      metadata: { createdAt: now() },
+    }
+  }
+
+  const prependSummaryMessage = (summaryText: string, liveMessages: ChatMessage[]): ChatMessage[] => {
+    const summaryMessage = createSummaryMessage(summaryText)
+    return summaryMessage ? [summaryMessage, ...liveMessages] : [...liveMessages]
+  }
+
+  const estimateThreshold = (contextSize = 256_000): number => {
+    const reservedOutput = Math.min(outputReserveTokens, Math.floor(contextSize * 0.35))
+    const safetyMargin = Math.min(safetyMarginTokens, Math.floor(contextSize * 0.1))
+    const reservedThreshold = contextSize - (reservedOutput + safetyMargin)
+    const ratioThreshold = Math.floor(contextSize * thresholdRatio)
+    return Math.max(1_000, Math.min(contextSize - 1, Math.min(reservedThreshold, ratioThreshold)))
+  }
+
+  const shouldCompactHistory = (params: {
+    summaryText: string
+    liveMessages: ChatMessage[]
+    contextSize?: number
+  }): CompactionAssessment => {
+    const threshold = estimateThreshold(params.contextSize)
+    const summaryPayload = buildSyntheticSummaryPayload(params.summaryText)
+    const promptPayload = JSON.stringify([...(summaryPayload ? [summaryPayload] : []), ...params.liveMessages])
+    const estimatedTokens = estimateTokens(promptPayload)
+    return { estimatedTokens, threshold, shouldCompact: estimatedTokens >= threshold }
+  }
+
+  const compactContextMessages = async (params: {
+    previousSummary: string
+    existingState: WorkstreamState
+    newMessages: ContextMessage[]
+  }): Promise<CompactionOutput> => {
+    const chunks = splitByCharBudget(params.newMessages, compactionChunkMaxChars)
+    let summary = normalizeSummary(params.previousSummary)
+    let delta: WorkstreamStateDelta = {}
+    let currentState = params.existingState
+
+    for (const chunk of chunks) {
+      const transcript = toCompactionTranscript(chunk)
+      const output = await options.runCompacter({
+        previousSummary: summary,
+        existingState: currentState,
+        chunk,
+        transcript,
+      })
+      summary = normalizeSummary(output.summary)
+      const parsedDelta = WorkstreamStateDeltaSchema.parse(output.stateDelta)
+      delta = mergeDelta(delta, parsedDelta)
+      currentState = mergeStateDelta(currentState, parsedDelta, now)
+    }
+
+    return { summary, stateDelta: delta }
+  }
+
+  const compactHistory = async (params: CompactHistoryParams): Promise<CompactHistoryResult> => {
+    let summaryText = normalizeSummary(params.summaryText)
+    let remainingMessages = [...params.liveMessages]
+    let state = params.existingState
+    let mergedDelta: WorkstreamStateDelta = {}
+    let compactedMessages: ChatMessage[] = []
+    let lastCompactedMessageId: string | undefined
+    const summaryPayload = buildSyntheticSummaryPayload(summaryText)
+    const initialPayload = JSON.stringify([...(summaryPayload ? [summaryPayload] : []), ...remainingMessages])
+    const inputChars = initialPayload.length
+
+    for (;;) {
+      const assessment = shouldCompactHistory({
+        summaryText,
+        liveMessages: remainingMessages,
+        contextSize: params.contextSize,
+      })
+
+      if (!assessment.shouldCompact) {
+        const summaryPayload = buildSyntheticSummaryPayload(summaryText)
+        const outputPayload = JSON.stringify([...(summaryPayload ? [summaryPayload] : []), ...remainingMessages])
+        return {
+          compacted: compactedMessages.length > 0,
+          summaryText,
+          ...(lastCompactedMessageId ? { lastCompactedMessageId } : {}),
+          compactedMessages,
+          compactedMessageCount: compactedMessages.length,
+          remainingMessageCount: remainingMessages.length,
+          estimatedTokens: assessment.estimatedTokens,
+          inputChars,
+          outputChars: outputPayload.length,
+          state,
+          stateDelta: mergedDelta,
+        }
+      }
+
+      const boundary = Math.max(0, remainingMessages.length - params.tailMessageCount)
+      if (boundary <= 0) {
+        const summaryPayload = buildSyntheticSummaryPayload(summaryText)
+        const outputPayload = JSON.stringify([...(summaryPayload ? [summaryPayload] : []), ...remainingMessages])
+        return {
+          compacted: compactedMessages.length > 0,
+          summaryText,
+          ...(lastCompactedMessageId ? { lastCompactedMessageId } : {}),
+          compactedMessages,
+          compactedMessageCount: compactedMessages.length,
+          remainingMessageCount: remainingMessages.length,
+          estimatedTokens: assessment.estimatedTokens,
+          inputChars,
+          outputChars: outputPayload.length,
+          state,
+          stateDelta: mergedDelta,
+        }
+      }
+
+      const candidatePrefix = remainingMessages.slice(0, boundary)
+      const messagesToCompact = candidatePrefix.filter((message) => !readIsCompacted(message))
+      const contextMessages = messagesToCompact.map(toContextMessageFromChatMessage)
+      const sourceText = toCompactionTranscript(contextMessages)
+
+      if (!normalizeWhitespace(sourceText)) {
+        const summaryPayload = buildSyntheticSummaryPayload(summaryText)
+        const outputPayload = JSON.stringify([...(summaryPayload ? [summaryPayload] : []), ...remainingMessages])
+        return {
+          compacted: compactedMessages.length > 0,
+          summaryText,
+          ...(lastCompactedMessageId ? { lastCompactedMessageId } : {}),
+          compactedMessages,
+          compactedMessageCount: compactedMessages.length,
+          remainingMessageCount: remainingMessages.length,
+          estimatedTokens: assessment.estimatedTokens,
+          inputChars,
+          outputChars: outputPayload.length,
+          state,
+          stateDelta: mergedDelta,
+        }
+      }
+
+      let compactionOutput = await compactContextMessages({
+        previousSummary: summaryText,
+        existingState: state,
+        newMessages: contextMessages,
+      })
+
+      let nextSummary = normalizeSummary(compactionOutput.summary)
+      let nextState = mergeStateDelta(state, compactionOutput.stateDelta, now)
+
+      if (estimateTokens(nextSummary) > summaryRollupMaxTokens) {
+        const rollupOutput = await compactContextMessages({
+          previousSummary: '',
+          existingState: nextState,
+          newMessages: [{ role: 'assistant', text: nextSummary, sourceMessageId: 'summary-rollup' }],
+        })
+        nextSummary = normalizeSummary(rollupOutput.summary)
+        nextState = mergeStateDelta(nextState, rollupOutput.stateDelta, now)
+        compactionOutput = rollupOutput
+      }
+
+      if (nextSummary.length >= sourceText.length) {
+        throw new Error('Compaction summary is not shorter than compacted source')
+      }
+
+      summaryText = nextSummary
+      state = nextState
+      mergedDelta = mergeDelta(mergedDelta, compactionOutput.stateDelta)
+      compactedMessages = [
+        ...compactedMessages,
+        ...candidatePrefix.map((message) => markMessageCompacted(message, now)),
+      ]
+      lastCompactedMessageId = candidatePrefix.at(-1)?.id ?? lastCompactedMessageId
+      remainingMessages = remainingMessages.slice(boundary)
+
+      if (remainingMessages.length <= params.tailMessageCount) {
+        continue
+      }
+    }
+  }
+
+  return {
+    createSummaryMessage,
+    prependSummaryMessage,
+    formatWorkstreamStateForPrompt,
+    estimateThreshold,
+    shouldCompactHistory,
+    compactHistory,
+  }
+}
+
+export function parseCompactionOutput(value: unknown): CompactionOutput {
+  const parsed = StructuredCompactionOutputSchema.parse(value)
+
+  return { summary: parsed.summary, stateDelta: parseStructuredWorkstreamStateDelta(parsed.stateDelta) }
+}