@xelauvas/xela-cli 0.3.1 → 0.4.0

package/src/services/compact/reactiveCompact.ts

@@ -0,0 +1,251 @@
+import { feature } from 'bun:bundle'
+import type { QuerySource } from '../../constants/querySource.js'
+import type { AssistantMessage, Message } from '../../types/message.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import type { CacheSafeParams } from '../../utils/forkedAgent.js'
+import type { CompactionResult } from './compact.js'
+
+// This module is loaded with require() from the query loop, so it must not
+// statically import the compaction/hook graph (it reaches ripgrep.ts, which
+// cannot be loaded as CJS). Everything heavy is imported when first used.
+async function deps() {
+  const [compact, hooks, errors, errorsUtil, log, sessionMemory, warning, micro, cleanup] =
+    await Promise.all([
+      import('./compact.js'),
+      import('../../utils/hooks.js'),
+      import('../api/errors.js'),
+      import('../../utils/errors.js'),
+      import('../../utils/log.js'),
+      import('../SessionMemory/sessionMemoryUtils.js'),
+      import('./compactWarningState.js'),
+      import('./microCompact.js'),
+      import('./postCompactCleanup.js'),
+    ])
+  return { compact, hooks, errors, errorsUtil, log, sessionMemory, warning, micro, cleanup }
+}
+
+const PROMPT_TOO_LONG_PREFIX = 'Prompt is too long'
+
+function isPromptTooLongMessage(msg: AssistantMessage): boolean {
+  if (!msg.isApiErrorMessage) return false
+  const content = msg.message.content
+  return (
+    Array.isArray(content) &&
+    content.some(b => b.type === 'text' && b.text.startsWith(PROMPT_TOO_LONG_PREFIX))
+  )
+}
+
+function isMediaSizeErrorMessage(msg: AssistantMessage): boolean {
+  const raw = msg.errorDetails
+  if (msg.isApiErrorMessage !== true || typeof raw !== 'string') return false
+  return (
+    (raw.includes('image exceeds') && raw.includes('maximum')) ||
+    (raw.includes('image dimensions exceed') && raw.includes('many-image')) ||
+    /maximum of \d+ PDF pages/.test(raw)
+  )
+}
+
+/**
+ * Reactive compaction: instead of (or in addition to) compacting ahead of a
+ * threshold, recover when the API actually rejects a request as too long.
+ * The query loop withholds the prompt-too-long / media-size error from the
+ * stream, calls `tryReactiveCompact`, and retries the turn on the compacted
+ * conversation. `/compact` can also be routed through this path
+ * (`isReactiveOnlyMode`).
+ */
+
+export type ReactiveCompactOutcome =
+  | { ok: true; result: CompactionResult }
+  | {
+      ok: false
+      reason:
+        | 'too_few_groups'
+        | 'aborted'
+        | 'exhausted'
+        | 'error'
+        | 'media_unstrippable'
+    }
+
+export function isReactiveCompactEnabled(): boolean {
+  if (!feature('REACTIVE_COMPACT')) return false
+  if (isEnvTruthy(process.env.DISABLE_COMPACT)) return false
+  if (isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_REACTIVE_COMPACT)) return false
+  return true
+}
+
+/**
+ * When set, /compact summarizes through the reactive path (no microcompact
+ * pre-pass, auto-compact threshold ignored). Off by default.
+ */
+export function isReactiveOnlyMode(): boolean {
+  return (
+    isReactiveCompactEnabled() &&
+    isEnvTruthy(process.env.CLAUDE_CODE_REACTIVE_COMPACT_ONLY)
+  )
+}
+
+/**
+ * Should this streamed message be held back from the caller so the loop can
+ * try compaction first? Only prompt-too-long API errors qualify.
+ */
+export function isWithheldPromptTooLong(
+  msg: Message | { type: string } | undefined,
+): msg is AssistantMessage {
+  if (!isReactiveCompactEnabled()) return false
+  if (!msg || msg.type !== 'assistant') return false
+  const m = msg as AssistantMessage
+  return m.isApiErrorMessage === true && isPromptTooLongMessage(m)
+}
+
+/** Image / PDF / many-image rejections that stripping media can fix. */
+export function isWithheldMediaSizeError(
+  msg: Message | { type: string } | undefined,
+): msg is AssistantMessage {
+  if (!isReactiveCompactEnabled()) return false
+  if (!msg || msg.type !== 'assistant') return false
+  return isMediaSizeErrorMessage(msg as AssistantMessage)
+}
+
+function hasMediaBlocks(messages: Message[]): boolean {
+  return messages.some(
+    m =>
+      m.type === 'user' &&
+      Array.isArray(m.message.content) &&
+      m.message.content.some(
+        b =>
+          b.type === 'image' ||
+          (b.type === 'document' &&
+            typeof (b as { source?: { type?: string } }).source?.type === 'string'),
+      ),
+  )
+}
+
+function conversationGroups(messages: Message[]): number {
+  // A "group" is one user→assistant exchange; compaction needs at least two
+  // so that a summary carries any information the tail does not.
+  return messages.filter(m => m.type === 'user' && !('isMeta' in m && m.isMeta)).length
+}
+
+/**
+ * Summarize `messages` in response to a rejected request. For media errors
+ * the images/PDFs are replaced with placeholders first so the summary request
+ * itself is not rejected for the same reason. compactConversation already
+ * handles a summary request that is itself too long (head truncation retry)
+ * and runs the PostCompact hooks.
+ */
+export async function reactiveCompactOnPromptTooLong(
+  messages: Message[],
+  cacheSafeParams: CacheSafeParams,
+  options: {
+    customInstructions?: string
+    trigger: 'manual' | 'auto'
+    mediaError?: boolean
+  },
+): Promise<ReactiveCompactOutcome> {
+  const { compact, errorsUtil, log } = await deps()
+  const context = cacheSafeParams.toolUseContext
+  const signal = context.abortController.signal
+  if (conversationGroups(messages) < 2) {
+    return { ok: false, reason: 'too_few_groups' }
+  }
+  let input = messages
+  if (options.mediaError) {
+    if (!hasMediaBlocks(messages)) {
+      return { ok: false, reason: 'media_unstrippable' }
+    }
+    input = compact.stripImagesFromMessages(messages)
+  }
+  try {
+    const result = await compact.compactConversation(
+      input,
+      context,
+      { ...cacheSafeParams, forkContextMessages: input },
+      true,
+      options.customInstructions,
+      options.trigger === 'auto',
+    )
+    return { ok: true, result }
+  } catch (error) {
+    if (signal.aborted) return { ok: false, reason: 'aborted' }
+    if (errorsUtil.hasExactErrorMessage(error, compact.ERROR_MESSAGE_NOT_ENOUGH_MESSAGES)) {
+      return { ok: false, reason: 'too_few_groups' }
+    }
+    const text = error instanceof Error ? error.message : String(error)
+    if (/prompt is too long/i.test(text)) {
+      return { ok: false, reason: 'exhausted' }
+    }
+    log.logError(error as Error)
+    return { ok: false, reason: 'error' }
+  }
+}
+
+/**
+ * Entry point used by the query loop after a withheld 413 / media error.
+ * Returns the compaction result to retry with, or null when recovery must
+ * not run (already tried this turn, aborted, or we are inside a compaction
+ * request ourselves) or failed.
+ */
+export async function tryReactiveCompact(params: {
+  hasAttempted: boolean
+  querySource: QuerySource
+  aborted: boolean
+  messages: Message[]
+  cacheSafeParams: CacheSafeParams
+}): Promise<CompactionResult | null> {
+  const { hasAttempted, querySource, aborted, messages, cacheSafeParams } =
+    params
+  if (!isReactiveCompactEnabled()) return null
+  if (hasAttempted || aborted) return null
+  if (querySource === 'compact' || querySource === 'session_memory') return null
+
+  const lastMessage = messages.at(-1)
+  const mediaError =
+    lastMessage?.type === 'assistant' &&
+    isMediaSizeErrorMessage(lastMessage as AssistantMessage)
+  // The rejected attempt's error message (if the caller left it in) carries
+  // nothing worth summarizing.
+  const toCompact =
+    lastMessage?.type === 'assistant' &&
+    (lastMessage as AssistantMessage).isApiErrorMessage
+      ? messages.slice(0, -1)
+      : messages
+
+  const { compact, hooks, log, sessionMemory, warning, micro, cleanup } = await deps()
+  const context = cacheSafeParams.toolUseContext
+  const signal = context.abortController.signal
+  context.onCompactProgress?.({ type: 'hooks_start', hookType: 'pre_compact' })
+  let customInstructions: string | undefined
+  try {
+    const hookResult = await hooks.executePreCompactHooks(
+      { trigger: 'auto', customInstructions: null },
+      signal,
+    )
+    customInstructions = compact.mergeHookInstructions(
+      undefined,
+      hookResult.newCustomInstructions,
+    )
+  } catch (error) {
+    log.logError(error as Error)
+  }
+
+  logForDebugging(
+    `[reactiveCompact] ${mediaError ? 'media-size' : 'prompt-too-long'} recovery on ${toCompact.length} messages (${querySource})`,
+  )
+  const outcome = await reactiveCompactOnPromptTooLong(
+    toCompact,
+    cacheSafeParams,
+    { customInstructions, trigger: 'auto', mediaError },
+  )
+  if (!outcome.ok) {
+    logForDebugging(`[reactiveCompact] gave up: ${outcome.reason}`)
+    context.onCompactProgress?.({ type: 'compact_end' })
+    return null
+  }
+
+  sessionMemory.setLastSummarizedMessageId(undefined)
+  cleanup.runPostCompactCleanup(querySource)
+  warning.suppressCompactWarning()
+  micro.resetMicrocompactState()
+  return outcome.result
+}

package/src/services/compact/snipCompact.ts

@@ -0,0 +1,282 @@
+import { randomUUID } from 'crypto'
+import { feature } from 'bun:bundle'
+import { SNIP_TOOL_NAME } from '../../tools/SnipTool/prompt.js'
+import type { Message } from '../../types/message.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { deriveShortMessageId } from '../../utils/messages.js'
+import {
+  collectSnippedUuids,
+  isSnipBoundaryMessage,
+  projectSnippedView,
+  SNIP_BOUNDARY_SUBTYPE,
+  type SnipBoundaryMessage,
+} from './snipProjection.js'
+
+// Turns at the end of the conversation that a snip can never reach
+const PROTECTED_TAIL_USER_TURNS = 2
+// Growth (estimated tokens) between context-efficiency nudges
+const NUDGE_INTERVAL_TOKENS = 10_000
+// Below this total the conversation is small enough that nudging is noise
+const NUDGE_MIN_TOTAL_TOKENS = 30_000
+
+export const SNIP_NUDGE_TEXT =
+  `Context check: the conversation has grown. If earlier messages are no longer useful ` +
+  `(large tool output you already acted on, dead-end attempts, resolved sub-tasks), remove them with the ${SNIP_TOOL_NAME} tool: ` +
+  `pass the [id:...] tag of the first and last message of the range. Do this only when it clearly helps; never snip what you may still need.`
+
+export type SnipResult = {
+  messages: Message[]
+  tokensFreed: number
+  boundaryMessage?: SnipBoundaryMessage
+  executed: boolean
+}
+
+export function isSnipRuntimeEnabled(): boolean {
+  if (!feature('HISTORY_SNIP')) return false
+  return !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_SNIP)
+}
+
+/** Snip markers are not used by this implementation (the tool call itself is the marker). */
+export function isSnipMarkerMessage(_message: Message): boolean {
+  return false
+}
+
+export function estimateMessageTokens(message: Message): number {
+  const m = message as { message?: { content?: unknown }; content?: unknown }
+  const content = m.message?.content ?? m.content ?? ''
+  const text = typeof content === 'string' ? content : JSON.stringify(content)
+  return Math.ceil(text.length / 4) + 8
+}
+
+type SnipRequest = {
+  toolUseId: string
+  startId: string
+  endId: string
+  reason?: string
+  /** index of the assistant message that issued the Snip call */
+  callerIndex: number
+}
+
+function findSnipRequests(
+  messages: readonly Message[],
+  alreadyApplied: Set<string>,
+): SnipRequest[] {
+  const requests: SnipRequest[] = []
+  messages.forEach((m, index) => {
+    if (m.type !== 'assistant') return
+    const content = (m as { message: { content: unknown } }).message.content
+    if (!Array.isArray(content)) return
+    for (const block of content as Array<{
+      type: string
+      id?: string
+      name?: string
+      input?: { start_id?: string; end_id?: string; reason?: string }
+    }>) {
+      if (block.type !== 'tool_use' || block.name !== SNIP_TOOL_NAME || !block.id) continue
+      if (alreadyApplied.has(block.id)) continue
+      const start = block.input?.start_id?.trim()
+      const end = block.input?.end_id?.trim()
+      if (!start || !end) continue
+      requests.push({
+        toolUseId: block.id,
+        startId: start.replace(/^\[?id:/, '').replace(/\]$/, ''),
+        endId: end.replace(/^\[?id:/, '').replace(/\]$/, ''),
+        reason: block.input?.reason,
+        callerIndex: index,
+      })
+    }
+  })
+  return requests
+}
+
+function toolUseIdsOf(message: Message): string[] {
+  if (message.type !== 'assistant') return []
+  const content = (message as { message: { content: unknown } }).message.content
+  if (!Array.isArray(content)) return []
+  return (content as Array<{ type: string; id?: string }>)
+    .filter(b => b.type === 'tool_use' && b.id)
+    .map(b => b.id!)
+}
+
+function toolResultIdsOf(message: Message): string[] {
+  if (message.type !== 'user') return []
+  const content = (message as { message: { content: unknown } }).message.content
+  if (!Array.isArray(content)) return []
+  return (content as Array<{ type: string; tool_use_id?: string }>)
+    .filter(b => b.type === 'tool_result' && b.tool_use_id)
+    .map(b => b.tool_use_id!)
+}
+
+function isRealUserTurn(message: Message): boolean {
+  if (message.type !== 'user') return false
+  if ((message as { isMeta?: boolean }).isMeta) return false
+  return toolResultIdsOf(message).length === 0
+}
+
+/**
+ * Resolves one Snip request to the set of uuids to remove: the tagged range,
+ * closed over tool_use/tool_result pairs so the API never sees a half pair,
+ * and clipped before the protected tail.
+ */
+function resolveRange(
+  view: readonly Message[],
+  req: SnipRequest,
+): { uuids: Set<string>; error?: string } {
+  const indexById = new Map<string, number>()
+  view.forEach((m, i) => {
+    if (m.type === 'user' || m.type === 'assistant') {
+      indexById.set(deriveShortMessageId(m.uuid), i)
+    }
+  })
+  let start = indexById.get(req.startId)
+  let end = indexById.get(req.endId)
+  if (start === undefined || end === undefined) {
+    return { uuids: new Set(), error: `unknown message id ${start === undefined ? req.startId : req.endId}` }
+  }
+  if (start > end) [start, end] = [end, start]
+
+  // Protected tail: the last N real user turns and everything after them
+  let protectedFrom = view.length
+  let turns = 0
+  for (let i = view.length - 1; i >= 0; i--) {
+    if (isRealUserTurn(view[i]!)) {
+      turns++
+      if (turns === PROTECTED_TAIL_USER_TURNS) {
+        protectedFrom = i
+        break
+      }
+    }
+  }
+  // The Snip call itself (and its result) must survive, otherwise the model
+  // forgets it already snipped and repeats the request
+  protectedFrom = Math.min(protectedFrom, req.callerIndex)
+  if (end >= protectedFrom) end = protectedFrom - 1
+  if (end < start) return { uuids: new Set(), error: 'range is entirely inside the protected recent turns' }
+
+  const uuids = new Set<string>()
+  for (let i = start; i <= end; i++) uuids.add(view[i]!.uuid)
+
+  // Close over tool pairs
+  const useToUuid = new Map<string, string>()
+  const resultToUuid = new Map<string, string>()
+  for (const m of view) {
+    for (const id of toolUseIdsOf(m)) useToUuid.set(id, m.uuid)
+    for (const id of toolResultIdsOf(m)) resultToUuid.set(id, m.uuid)
+  }
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const m of view) {
+      if (!uuids.has(m.uuid)) continue
+      for (const id of toolUseIdsOf(m)) {
+        const r = resultToUuid.get(id)
+        if (r && !uuids.has(r)) { uuids.add(r); changed = true }
+      }
+      for (const id of toolResultIdsOf(m)) {
+        const u = useToUuid.get(id)
+        if (u && !uuids.has(u)) { uuids.add(u); changed = true }
+      }
+    }
+  }
+  // Pair closure must not reach into the protected tail
+  for (let i = protectedFrom; i < view.length; i++) uuids.delete(view[i]!.uuid)
+  return { uuids }
+}
+
+/**
+ * Applies pending Snip requests. Returns the model-facing message list plus
+ * (at most) one new boundary describing what was removed this time. With
+ * `force` the caller is replaying on its own store (QueryEngine) and wants
+ * the full projected list back even when nothing new was snipped.
+ */
+export function snipCompactIfNeeded(
+  messages: Message[],
+  options: { force?: boolean } = {},
+): SnipResult {
+  if (!isSnipRuntimeEnabled()) {
+    return { messages, tokensFreed: 0, executed: false }
+  }
+  const applied = new Set<string>()
+  for (const m of messages) {
+    if (isSnipBoundaryMessage(m)) for (const id of m.snipToolUseIds) applied.add(id)
+  }
+  const view = projectSnippedView(messages)
+  const requests = findSnipRequests(view, applied)
+  if (requests.length === 0) {
+    const projected = options.force ? view : messages
+    return { messages: projected, tokensFreed: 0, executed: options.force ? view.length !== messages.length : false }
+  }
+
+  const removed = new Set<string>()
+  const handled: string[] = []
+  const reasons: string[] = []
+  for (const req of requests) {
+    const { uuids, error } = resolveRange(view, req)
+    handled.push(req.toolUseId)
+    if (error) continue
+    for (const u of uuids) removed.add(u)
+    if (req.reason) reasons.push(req.reason)
+  }
+  if (removed.size === 0) {
+    // Nothing removable; still record the tool uses so they are not retried
+    const boundary = makeBoundary([], handled, 0, reasons[0])
+    return { messages: options.force ? [...view, boundary] : [...messages, boundary], tokensFreed: 0, boundaryMessage: boundary, executed: true }
+  }
+  let tokensFreed = 0
+  for (const m of view) if (removed.has(m.uuid)) tokensFreed += estimateMessageTokens(m)
+  const boundary = makeBoundary([...removed], handled, tokensFreed, reasons[0])
+  const base = options.force ? messages : messages
+  const next = projectSnippedView([...base, boundary])
+  return { messages: next, tokensFreed, boundaryMessage: boundary, executed: true }
+}
+
+function makeBoundary(
+  snippedUuids: string[],
+  snipToolUseIds: string[],
+  tokensFreed: number,
+  reason?: string,
+): SnipBoundaryMessage {
+  const n = snippedUuids.length
+  const content =
+    n === 0
+      ? 'Snip: nothing removed (range was inside the protected recent turns or unknown)'
+      : `Snipped ${n} ${n === 1 ? 'message' : 'messages'} (~${tokensFreed.toLocaleString()} tokens)${reason ? `: ${reason}` : ''}`
+  return {
+    type: 'system',
+    subtype: SNIP_BOUNDARY_SUBTYPE,
+    content,
+    isMeta: false,
+    timestamp: new Date().toISOString(),
+    uuid: randomUUID(),
+    level: 'info',
+    snippedUuids,
+    snipToolUseIds,
+    tokensFreed,
+    reason,
+  } as SnipBoundaryMessage
+}
+
+/**
+ * Nudge pacing: once the context grew by NUDGE_INTERVAL_TOKENS since the last
+ * nudge, snip boundary or compact boundary, remind the model the tool exists.
+ */
+export function shouldNudgeForSnips(messages: readonly Message[]): boolean {
+  if (!isSnipRuntimeEnabled()) return false
+  const snipped = collectSnippedUuids(messages)
+  let total = 0
+  let sinceAnchor = 0
+  for (const m of messages) {
+    if (snipped.has(m.uuid)) continue
+    const isAnchor =
+      isSnipBoundaryMessage(m) ||
+      (m.type === 'system' && (m as { subtype?: string }).subtype === 'compact_boundary') ||
+      (m.type === 'user' &&
+        (m as { isMeta?: boolean }).isMeta &&
+        JSON.stringify((m as { message: { content: unknown } }).message.content).includes(SNIP_NUDGE_TEXT.slice(0, 40)))
+    const t = estimateMessageTokens(m)
+    total += t
+    if (isAnchor) sinceAnchor = 0
+    else sinceAnchor += t
+  }
+  return total >= NUDGE_MIN_TOTAL_TOKENS && sinceAnchor >= NUDGE_INTERVAL_TOKENS
+}

package/src/services/compact/snipProjection.ts

@@ -0,0 +1,50 @@
+import type { Message } from '../../types/message.js'
+
+export const SNIP_BOUNDARY_SUBTYPE = 'snip_boundary'
+
+/**
+ * Boundary left behind by a snip. It is a system message so the REPL shows
+ * it (SnipBoundaryMessage) and normalizeMessagesForAPI drops it; it carries
+ * the removed uuids so the projection needs no module state and survives a
+ * session restore (the boundary lives in the transcript).
+ */
+export type SnipBoundaryMessage = Message & {
+  type: 'system'
+  subtype: typeof SNIP_BOUNDARY_SUBTYPE
+  content: string
+  snippedUuids: string[]
+  snipToolUseIds: string[]
+  tokensFreed: number
+  reason?: string
+}
+
+export function isSnipBoundaryMessage(
+  message: Message | undefined | null,
+): message is SnipBoundaryMessage {
+  return (
+    !!message &&
+    message.type === 'system' &&
+    (message as { subtype?: string }).subtype === SNIP_BOUNDARY_SUBTYPE
+  )
+}
+
+/** All uuids removed by every boundary present in the list. */
+export function collectSnippedUuids(messages: readonly Message[]): Set<string> {
+  const snipped = new Set<string>()
+  for (const m of messages) {
+    if (isSnipBoundaryMessage(m)) {
+      for (const u of m.snippedUuids) snipped.add(u)
+    }
+  }
+  return snipped
+}
+
+/**
+ * The model-facing view: drops every message a boundary snipped. Cheap on
+ * the hot path when nothing was snipped (one pass, no allocation).
+ */
+export function projectSnippedView<T extends Message>(messages: T[]): T[] {
+  const snipped = collectSnippedUuids(messages)
+  if (snipped.size === 0) return messages
+  return messages.filter(m => !snipped.has(m.uuid))
+}