@inceptionstack/roundhouse 0.5.30 → 0.5.32

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `@inceptionstack/roundhouse` are documented here.
 
+## [0.5.32] — 2026-05-14
+
+### Fixed
+- **Soft-reset progress: emit completion message, not just start.** Before, the user saw `♻️ Session overflowed — soft-resetting to recent turns...` and then silence — success/failure outcomes only went to stderr. Now the user always sees a follow-up:
+  - ✅ `Soft-reset complete (N → M entries). Durable memory will re-inject on next turn.` on success
+  - ⚠️ `Soft-reset no-op (<reason>). Will retry compact next turn.` when nothing to trim
+  - ❌ `Soft-reset failed: <msg>. Will retry next turn.` when recovery itself errors
+- 3 new tests verifying onProgress emissions for all three outcomes (`emergency_whenSoftResetSucceeds_emitsCompletionProgressMessage`, `..._emitsNoOpProgressMessage`, `..._emitsFailureProgressMessage`), plus 1 regression test (`..._doesNotMaskWithTypeError`) for non-Error throws inside the recovery catch. **540 tests passing.**
+
+## [0.5.31] — 2026-05-14
+
+### Internal
+- **Refactor: session-repair module split + DRY shared error-classifier helper.** Pure refactor, zero behavior change. Addresses 7 maintainability findings from the post-v0.5.30 review:
+  - Extracted `matchesErrorPatterns()` shared helper so `isContextOverflowError` and `isToolPairingError` no longer duplicate ~80% of their structure. Both classifiers now walk the `cause` chain (previously only the overflow classifier did — fixed divergent-change smell). Both share `looksLikeValidationError()` gating.
+  - Extracted `buildTrimmedEntries()` from `softResetSessionFile` and `attemptSoftResetRecovery()` from `flushMemoryThenCompact`. The lifecycle catch block is now ~25 lines of linear flow (classify → recover → log → persist) instead of ~60 lines with a nested try/catch.
+  - `MAX_CAUSE_CHAIN_DEPTH = 5` named constant.
+  - Split `src/agents/shared/session-repair.ts` (574 lines, two domains) into four focused files: `session-repair.ts` (81 lines, public surface), `session-soft-reset.ts`, `error-classifiers.ts`, `session-repair-internal.ts`. All public exports preserved via re-exports for backward compat.
+  - Introduced `SessionRepairResult` named type replacing anonymous `{entries, report}` shape (named to avoid collision with the existing `RepairResult` in `message-validator.ts`).
+- 2 new regression tests for `isToolPairingError`'s now-fixed cause-chain walking. **536 tests passing.**
+
 ## [0.5.30] — 2026-05-14
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.30",
+  "version": "0.5.32",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",

package/src/agents/pi/pi-adapter.ts

@@ -28,7 +28,9 @@ import {
 
 import type { AgentAdapter, AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent, MessageContext } from "../../types";
 import { formatMessage, extractCustomMessage, customContentToText } from "./message-format";
-import { isToolPairingError, repairSessionFile, softResetSessionFile, type SoftResetReport } from "../shared/session-repair";
+import { isToolPairingError } from "../shared/error-classifiers";
+import { repairSessionFile } from "../shared/session-repair";
+import { softResetSessionFile, type SoftResetReport } from "../shared/session-soft-reset";
 import { SESSIONS_DIR } from "../../config";
 import { DEBUG_STREAM, threadIdToDir } from "../../util";
 

package/src/agents/shared/error-classifiers.ts

@@ -0,0 +1,71 @@
+export const MAX_CAUSE_CHAIN_DEPTH = 5;
+
+interface ErrorPatternMatchOptions {
+  stringifyGate?: (err: unknown) => boolean;
+}
+
+/**
+ * Stringify-search gate: only walk serialized error fields when the error
+ * looks like a 4xx / Bedrock ValidationException. Avoids false-positives
+ * from unrelated 5xx noise that happens to contain trigger phrases.
+ */
+function looksLikeValidationError(err: unknown): boolean {
+  const name = (err as { name?: string }).name ?? '';
+  const httpStatus =
+    (err as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;
+  return name === 'ValidationException' || httpStatus === 400;
+}
+
+export function matchesErrorPatterns(
+  err: unknown,
+  patterns: RegExp[],
+  options: ErrorPatternMatchOptions = {},
+): boolean {
+  if (!err) return false;
+
+  const matches = (value: unknown): boolean => {
+    const message = (value as { message?: string }).message ?? String(value);
+    return patterns.some(pattern => pattern.test(message));
+  };
+
+  if (matches(err)) return true;
+
+  let current: unknown = (err as { cause?: unknown }).cause;
+  for (let depth = 0; depth < MAX_CAUSE_CHAIN_DEPTH && current; depth++) {
+    if (matches(current)) return true;
+    current = (current as { cause?: unknown }).cause;
+  }
+
+  if (!options.stringifyGate?.(err)) {
+    return false;
+  }
+
+  try {
+    const serialized = JSON.stringify(err);
+    return patterns.some(pattern => pattern.test(serialized));
+  } catch {
+    return false;
+  }
+}
+
+export function isContextOverflowError(err: unknown): boolean {
+  const patterns = [
+    /prompt is too long/i,
+    /tokens?\s*[>>]\s*\d+\s*maximum/i,
+    /input is too long/i,
+    /context length exceeded/i,
+    /maximum context length/i,
+  ];
+  return matchesErrorPatterns(err, patterns, { stringifyGate: looksLikeValidationError });
+}
+
+export function isToolPairingError(err: unknown): boolean {
+  const patterns = [
+    /tool_use.*without.*tool_result/i,
+    /tool_result.*without.*tool_use/i,
+    /toolUse.*without.*toolResult/i,
+    /unmatched.*tool.?use/i,
+    /orphan.*tool/i,
+  ];
+  return matchesErrorPatterns(err, patterns, { stringifyGate: looksLikeValidationError });
+}

package/src/agents/shared/session-repair-internal.ts

@@ -0,0 +1,239 @@
+import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { validateToolPairing } from './message-validator';
+import type { Message, ToolCall, AssistantMessage, ToolResultMessage } from '@earendil-works/pi-ai';
+
+/** Minimal structural type for a pi-ai session file entry (we only touch message entries). */
+export interface SessionFileEntry {
+  type: string;
+  id?: string;
+  parentId?: string | null;
+  message?: Message;
+  // other fields preserved as-is
+  [key: string]: unknown;
+}
+
+export interface SessionRepairReport {
+  repaired: boolean;
+  droppedEntryIds: string[];
+  droppedToolCallIds: string[];
+  droppedToolResultIds: string[];
+  backupPath?: string;
+  totalEntries: number;
+}
+
+export interface SessionRepairResult {
+  entries: SessionFileEntry[];
+  report: SessionRepairReport;
+}
+
+/** Parse a .jsonl session file. Tolerant of trailing blank lines. Throws on malformed JSON. */
+export function parseSessionFile(path: string): SessionFileEntry[] {
+  const raw = readFileSync(path, 'utf8');
+  const lines = raw.split('\n');
+  const entries: SessionFileEntry[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line) as SessionFileEntry);
+    } catch (err) {
+      throw new Error(`Session file parse error at line ${i + 1}: ${(err as Error).message}`);
+    }
+  }
+  return entries;
+}
+
+/**
+ * Extract `Message[]` from file entries in the order they appear.
+ * Only includes entries of type "message" (skips session header, model_change, etc).
+ */
+function extractMessages(entries: SessionFileEntry[]): { messages: Message[]; entryIndex: number[] } {
+  const messages: Message[] = [];
+  const entryIndex: number[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.type === 'message' && entry.message) {
+      messages.push(entry.message);
+      entryIndex.push(i);
+    }
+  }
+  return { messages, entryIndex };
+}
+
+/**
+ * Re-parent children of dropped entries to preserve tree validity.
+ * If entry X is dropped and entry Y has parentId=X, set Y.parentId = X.parentId.
+ */
+function reparentDroppedEntries(
+  entries: SessionFileEntry[],
+  droppedEntryIds: Set<string>
+): SessionFileEntry[] {
+  const entryById = new Map<string, SessionFileEntry>();
+  for (const entry of entries) {
+    if (entry.id) entryById.set(entry.id, entry);
+  }
+
+  const remap = new Map<string, string | null>();
+  const resolveAncestor = (id: string, visited: Set<string> = new Set()): string | null => {
+    if (remap.has(id)) return remap.get(id)!;
+    if (!droppedEntryIds.has(id)) return id;
+    if (visited.has(id)) {
+      remap.set(id, null);
+      return null;
+    }
+    visited.add(id);
+    const entry = entryById.get(id);
+    const parent = entry?.parentId ?? null;
+    const resolved = parent === null ? null : resolveAncestor(parent, visited);
+    remap.set(id, resolved);
+    return resolved;
+  };
+
+  const kept: SessionFileEntry[] = [];
+  for (const entry of entries) {
+    if (entry.id && droppedEntryIds.has(entry.id)) continue;
+    if (entry.parentId && droppedEntryIds.has(entry.parentId)) {
+      kept.push({ ...entry, parentId: resolveAncestor(entry.parentId) });
+    } else {
+      kept.push(entry);
+    }
+  }
+  return kept;
+}
+
+/**
+ * Compute the set of entry IDs to drop based on orphaned tool IDs.
+ *
+ * - Orphaned toolResult message → drop the whole entry
+ * - Orphaned toolCall inside an assistant message → drop the entry only if the
+ *   toolCall was the *only* content block (otherwise keep the entry with the
+ *   block stripped; handled separately in applyEntryEdits)
+ */
+function findEntriesToDrop(
+  entries: SessionFileEntry[],
+  orphanedToolCallIds: Set<string>,
+  orphanedToolResultIds: Set<string>
+): { entriesToDrop: Set<string>; entriesToEdit: Map<string, string[]> } {
+  const entriesToDrop = new Set<string>();
+  const entriesToEdit = new Map<string, string[]>();
+
+  for (const entry of entries) {
+    if (entry.type !== 'message' || !entry.message || !entry.id) continue;
+    const message = entry.message;
+
+    if (message.role === 'toolResult') {
+      const toolResult = message as ToolResultMessage;
+      if (orphanedToolResultIds.has(toolResult.toolCallId)) {
+        entriesToDrop.add(entry.id);
+      }
+      continue;
+    }
+
+    if (message.role === 'assistant') {
+      const assistantMessage = message as AssistantMessage;
+      const orphanCallIds: string[] = [];
+      let hasNonOrphanContent = false;
+      for (const block of assistantMessage.content) {
+        if ((block as ToolCall).type === 'toolCall') {
+          const callId = (block as ToolCall).id;
+          if (orphanedToolCallIds.has(callId)) {
+            orphanCallIds.push(callId);
+          } else {
+            hasNonOrphanContent = true;
+          }
+        } else {
+          hasNonOrphanContent = true;
+        }
+      }
+      if (orphanCallIds.length === 0) continue;
+      if (hasNonOrphanContent) {
+        entriesToEdit.set(entry.id, orphanCallIds);
+      } else {
+        entriesToDrop.add(entry.id);
+      }
+    }
+  }
+
+  return { entriesToDrop, entriesToEdit };
+}
+
+/** Apply in-place edits to assistant entries: strip orphaned toolCall blocks. */
+function applyEntryEdits(
+  entries: SessionFileEntry[],
+  entriesToEdit: Map<string, string[]>
+): SessionFileEntry[] {
+  if (entriesToEdit.size === 0) return entries;
+  return entries.map(entry => {
+    if (!entry.id || !entriesToEdit.has(entry.id)) return entry;
+    const orphanIds = new Set(entriesToEdit.get(entry.id)!);
+    const message = entry.message as AssistantMessage;
+    const cleanedContent = message.content.filter(block => {
+      if ((block as ToolCall).type === 'toolCall') {
+        return !orphanIds.has((block as ToolCall).id);
+      }
+      return true;
+    });
+    return { ...entry, message: { ...message, content: cleanedContent } };
+  });
+}
+
+/** Atomic write: tmp file + rename. Preserves partial-failure safety. */
+export function atomicWrite(path: string, content: string): void {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, content, { encoding: 'utf8' });
+  renameSync(tmp, path);
+}
+
+/** Back up the original file before mutation. Returns the backup path. */
+export function backupFile(path: string): string {
+  const ts = Date.now();
+  const backupPath = join(dirname(path), `${basename(path)}.bak-${ts}`);
+  copyFileSync(path, backupPath);
+  return backupPath;
+}
+
+/**
+ * Pure in-memory tool-pairing repair. Takes entries, returns repaired entries
+ * + a report. Does not touch the filesystem.
+ */
+export function repairEntriesInMemory(entries: SessionFileEntry[]): SessionRepairResult {
+  const { messages } = extractMessages(entries);
+  const validation = validateToolPairing(messages);
+
+  if (validation.isValid) {
+    return {
+      entries,
+      report: {
+        repaired: false,
+        droppedEntryIds: [],
+        droppedToolCallIds: [],
+        droppedToolResultIds: [],
+        totalEntries: entries.length,
+      },
+    };
+  }
+
+  const orphanedCalls = new Set(validation.orphanedToolCallIds);
+  const orphanedResults = new Set(validation.orphanedToolResultIds);
+  const { entriesToDrop, entriesToEdit } = findEntriesToDrop(entries, orphanedCalls, orphanedResults);
+  const edited = applyEntryEdits(entries, entriesToEdit);
+  const kept = reparentDroppedEntries(edited, entriesToDrop);
+
+  return {
+    entries: kept,
+    report: {
+      repaired: true,
+      droppedEntryIds: Array.from(entriesToDrop),
+      droppedToolCallIds: validation.orphanedToolCallIds,
+      droppedToolResultIds: validation.orphanedToolResultIds,
+      totalEntries: entries.length,
+    },
+  };
+}
+
+export function assertSessionFileExists(path: string): void {
+  if (!existsSync(path)) {
+    throw new Error(`Session file not found: ${path}`);
+  }
+}

package/src/agents/shared/session-repair.test.ts

@@ -10,10 +10,9 @@ import {
   parseSessionFile,
   inspectSessionFile,
   repairSessionFile,
-  isToolPairingError,
-  softResetSessionFile,
-  isContextOverflowError,
 } from './session-repair';
+import { isToolPairingError, isContextOverflowError } from './error-classifiers';
+import { softResetSessionFile } from './session-soft-reset';
 
 // ---------- fixtures ----------
 
@@ -306,6 +305,24 @@ describe('session-repair', () => {
       expect(isToolPairingError(err)).toBe(true);
     });
 
+    it('matches wrapped Bedrock ValidationException through cause chain', () => {
+      const err = new Error('session resume failed', {
+        cause: Object.assign(new Error('Request failed with status 400'), {
+          name: 'ValidationException',
+          $metadata: { httpStatusCode: 400 },
+          cause: { message: 'messages.3: `tool_use` ids were found without `tool_result` blocks immediately after' },
+        }),
+      });
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
+    it('matches wrapped tool pairing text from a nested cause without stringify fallback', () => {
+      const err = new Error('session resume failed', {
+        cause: new Error('toolUse id abc123 without matching toolResult'),
+      });
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
     it('does not match unrelated 400s', () => {
       const err = new Error('Invalid model ID');
       expect(isToolPairingError(err)).toBe(false);

package/src/agents/shared/session-repair.ts

@@ -1,216 +1,33 @@
 /**
- * session-repair.ts — File-level session repair for corrupted pi-ai session files.
- *
- * Pi-ai persists sessions as JSONL at ~/.roundhouse/sessions/<thread>/<id>.jsonl.
- * Each line is a `FileEntry` in a tree (parentId links). Message entries wrap
- * pi-ai `Message` objects (role: user | assistant | toolResult).
- *
- * Corruption scenarios (mid-session):
- *   - Tool execution aborted → toolCall entry written, toolResult never lands
- *   - Process crash between tool completion and result persist
- *   - Manual Ctrl-C mid-tool
- *
- * On next resume, pi-ai loads these entries → sends history to the model →
- * model rejects with "toolUse without toolResult" (Bedrock/Anthropic 400).
- *
- * This module detects and repairs orphaned tool pairs at the file level,
- * preserving the parentId tree by re-parenting children of dropped entries.
- *
- * Delegates tool-pairing logic to message-validator.ts.
- */
-
-import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync } from 'node:fs';
-import { dirname, basename, join } from 'node:path';
-import { validateToolPairing } from './message-validator.js';
-import type { Message, ToolCall, AssistantMessage, ToolResultMessage } from '@earendil-works/pi-ai';
-
-/** Minimal structural type for a pi-ai session file entry (we only touch message entries). */
-interface SessionFileEntry {
-  type: string;
-  id?: string;
-  parentId?: string | null;
-  message?: Message;
-  // other fields preserved as-is
-  [key: string]: unknown;
-}
-
-export interface SessionRepairReport {
-  repaired: boolean;
-  droppedEntryIds: string[];
-  droppedToolCallIds: string[];
-  droppedToolResultIds: string[];
-  backupPath?: string;
-  totalEntries: number;
-}
-
-/** Parse a .jsonl session file. Tolerant of trailing blank lines. Throws on malformed JSON. */
-export function parseSessionFile(path: string): SessionFileEntry[] {
-  const raw = readFileSync(path, 'utf8');
-  const lines = raw.split('\n');
-  const entries: SessionFileEntry[] = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (!line.trim()) continue;
-    try {
-      entries.push(JSON.parse(line) as SessionFileEntry);
-    } catch (err) {
-      throw new Error(`Session file parse error at line ${i + 1}: ${(err as Error).message}`);
-    }
-  }
-  return entries;
-}
-
-/**
- * Extract `Message[]` from file entries in the order they appear.
- * Only includes entries of type "message" (skips session header, model_change, etc).
- */
-function extractMessages(entries: SessionFileEntry[]): { messages: Message[]; entryIndex: number[] } {
-  const messages: Message[] = [];
-  const entryIndex: number[] = []; // parallel array: messages[i] came from entries[entryIndex[i]]
-  for (let i = 0; i < entries.length; i++) {
-    const e = entries[i];
-    if (e.type === 'message' && e.message) {
-      messages.push(e.message);
-      entryIndex.push(i);
-    }
-  }
-  return { messages, entryIndex };
-}
-
-/**
- * Re-parent children of dropped entries to preserve tree validity.
- * If entry X is dropped and entry Y has parentId=X, set Y.parentId = X.parentId.
- */
-function reparentDroppedEntries(
-  entries: SessionFileEntry[],
-  droppedEntryIds: Set<string>
-): SessionFileEntry[] {
-  // Build a map: droppedId → nearest non-dropped ancestor (walk up the tree)
-  const entryById = new Map<string, SessionFileEntry>();
-  for (const e of entries) {
-    if (e.id) entryById.set(e.id, e);
-  }
-
-  const remap = new Map<string, string | null>();
-  const resolveAncestor = (id: string, visited: Set<string> = new Set()): string | null => {
-    if (remap.has(id)) return remap.get(id)!;
-    if (!droppedEntryIds.has(id)) return id;
-    if (visited.has(id)) {
-      // Cycle in parentId chain (self-parent or loop) — bail with null rather than
-      // blow the stack. Should never happen in a well-formed session file.
-      remap.set(id, null);
-      return null;
-    }
-    visited.add(id);
-    const e = entryById.get(id);
-    const parent = e?.parentId ?? null;
-    const resolved = parent === null ? null : resolveAncestor(parent, visited);
-    remap.set(id, resolved);
-    return resolved;
-  };
-
-  const kept: SessionFileEntry[] = [];
-  for (const e of entries) {
-    if (e.id && droppedEntryIds.has(e.id)) continue;
-    if (e.parentId && droppedEntryIds.has(e.parentId)) {
-      kept.push({ ...e, parentId: resolveAncestor(e.parentId) });
-    } else {
-      kept.push(e);
-    }
-  }
-  return kept;
-}
-
-/**
- * Compute the set of entry IDs to drop based on orphaned tool IDs.
- *
- * - Orphaned toolResult message → drop the whole entry
- * - Orphaned toolCall inside an assistant message → drop the entry only if the
- *   toolCall was the *only* content block (otherwise keep the entry with the
- *   block stripped; handled separately in applyEntryEdits)
+ * session-repair.ts — File-level repair for orphaned toolCall/toolResult pairs.
  */
-function findEntriesToDrop(
-  entries: SessionFileEntry[],
-  orphanedToolCallIds: Set<string>,
-  orphanedToolResultIds: Set<string>
-): { entriesToDrop: Set<string>; entriesToEdit: Map<string, string[]> } {
-  const entriesToDrop = new Set<string>();
-  const entriesToEdit = new Map<string, string[]>(); // entryId → toolCallIds to strip
-
-  for (const e of entries) {
-    if (e.type !== 'message' || !e.message || !e.id) continue;
-    const msg = e.message;
-
-    if (msg.role === 'toolResult') {
-      const tr = msg as ToolResultMessage;
-      if (orphanedToolResultIds.has(tr.toolCallId)) {
-        entriesToDrop.add(e.id);
-      }
-      continue;
-    }
 
-    if (msg.role === 'assistant') {
-      const am = msg as AssistantMessage;
-      const orphanCallIds: string[] = [];
-      let hasNonOrphanContent = false;
-      for (const block of am.content) {
-        if ((block as ToolCall).type === 'toolCall') {
-          const callId = (block as ToolCall).id;
-          if (orphanedToolCallIds.has(callId)) {
-            orphanCallIds.push(callId);
-          } else {
-            hasNonOrphanContent = true;
-          }
-        } else {
-          hasNonOrphanContent = true;
-        }
-      }
-      if (orphanCallIds.length === 0) continue;
-      if (hasNonOrphanContent) {
-        entriesToEdit.set(e.id, orphanCallIds);
-      } else {
-        entriesToDrop.add(e.id);
-      }
-    }
-  }
-
-  return { entriesToDrop, entriesToEdit };
-}
-
-/** Apply in-place edits to assistant entries: strip orphaned toolCall blocks. */
-function applyEntryEdits(
-  entries: SessionFileEntry[],
-  entriesToEdit: Map<string, string[]>
-): SessionFileEntry[] {
-  if (entriesToEdit.size === 0) return entries;
-  return entries.map(e => {
-    if (!e.id || !entriesToEdit.has(e.id)) return e;
-    const orphanIds = new Set(entriesToEdit.get(e.id)!);
-    const msg = e.message as AssistantMessage;
-    const cleanedContent = msg.content.filter(block => {
-      if ((block as ToolCall).type === 'toolCall') {
-        return !orphanIds.has((block as ToolCall).id);
-      }
-      return true;
-    });
-    return { ...e, message: { ...msg, content: cleanedContent } };
-  });
-}
-
-/** Atomic write: tmp file + rename. Preserves partial-failure safety. */
-function atomicWrite(path: string, content: string): void {
-  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmp, content, { encoding: 'utf8' });
-  renameSync(tmp, path);
-}
-
-/** Back up the original file before mutation. Returns the backup path. */
-function backupFile(path: string): string {
-  const ts = Date.now();
-  const backupPath = join(dirname(path), `${basename(path)}.bak-${ts}`);
-  copyFileSync(path, backupPath);
-  return backupPath;
-}
+import { validateToolPairing } from './message-validator';
+import {
+  assertSessionFileExists,
+  atomicWrite,
+  backupFile,
+  parseSessionFile,
+  repairEntriesInMemory,
+} from './session-repair-internal';
+
+export { parseSessionFile } from './session-repair-internal';
+export type {
+  SessionRepairResult,
+  SessionFileEntry,
+  SessionRepairReport,
+} from './session-repair-internal';
+export {
+  MAX_CAUSE_CHAIN_DEPTH,
+  isContextOverflowError,
+  isToolPairingError,
+  matchesErrorPatterns,
+} from './error-classifiers';
+export {
+  softResetSessionFile,
+  type SoftResetOptions,
+  type SoftResetReport,
+} from './session-soft-reset';
 
 /**
  * Validate a session file for orphaned tool pairs without modifying it.
@@ -224,7 +41,9 @@ export function inspectSessionFile(path: string): {
   totalMessages: number;
 } {
   const entries = parseSessionFile(path);
-  const { messages } = extractMessages(entries);
+  const messages = entries
+    .filter(entry => entry.type === 'message' && entry.message)
+    .map(entry => entry.message!);
   const validation = validateToolPairing(messages);
   return {
     hasOrphans: !validation.isValid,
@@ -246,54 +65,8 @@ export function inspectSessionFile(path: string): {
  *
  * @returns report describing what was repaired
  */
-/**
- * Pure in-memory tool-pairing repair. Takes entries, returns repaired entries
- * + a report. Does not touch the filesystem. Used directly by
- * `softResetSessionFile` so trim + repair land as a single atomic write, and
- * via a thin wrapper by `repairSessionFile` for on-disk repair.
- */
-function repairEntriesInMemory(entries: SessionFileEntry[]): {
-  entries: SessionFileEntry[];
-  report: SessionRepairReport;
-} {
-  const { messages } = extractMessages(entries);
-  const validation = validateToolPairing(messages);
-
-  if (validation.isValid) {
-    return {
-      entries,
-      report: {
-        repaired: false,
-        droppedEntryIds: [],
-        droppedToolCallIds: [],
-        droppedToolResultIds: [],
-        totalEntries: entries.length,
-      },
-    };
-  }
-
-  const orphanedCalls = new Set(validation.orphanedToolCallIds);
-  const orphanedResults = new Set(validation.orphanedToolResultIds);
-  const { entriesToDrop, entriesToEdit } = findEntriesToDrop(entries, orphanedCalls, orphanedResults);
-  const edited = applyEntryEdits(entries, entriesToEdit);
-  const kept = reparentDroppedEntries(edited, entriesToDrop);
-
-  return {
-    entries: kept,
-    report: {
-      repaired: true,
-      droppedEntryIds: Array.from(entriesToDrop),
-      droppedToolCallIds: validation.orphanedToolCallIds,
-      droppedToolResultIds: validation.orphanedToolResultIds,
-      totalEntries: entries.length,
-    },
-  };
-}
-
-export function repairSessionFile(path: string): SessionRepairReport {
-  if (!existsSync(path)) {
-    throw new Error(`Session file not found: ${path}`);
-  }
+export function repairSessionFile(path: string) {
+  assertSessionFileExists(path);
 
   const entries = parseSessionFile(path);
   const { entries: repaired, report } = repairEntriesInMemory(entries);
@@ -301,274 +74,8 @@ export function repairSessionFile(path: string): SessionRepairReport {
   if (!report.repaired) return report;
 
   const backupPath = backupFile(path);
-  const newContent = repaired.map(e => JSON.stringify(e)).join('\n') + '\n';
+  const newContent = repaired.map(entry => JSON.stringify(entry)).join('\n') + '\n';
   atomicWrite(path, newContent);
 
   return { ...report, backupPath };
 }
-
-// ── Soft reset (recovery from already-overflowed sessions) ──────────────
-
-/**
- * When a session has grown past the model's context window, normal compact
- * cannot recover — the summarizer prompt itself overflows. Soft reset trims
- * the session jsonl on disk to its most-recent N user turns, drops everything
- * older, and re-runs the tool-pairing repair so what's left is internally
- * consistent.
- *
- * Trade-off: loses fidelity for older turns. The roundhouse memory layer
- * (MEMORY.md, daily front-page) re-injects on the next turn, so the agent
- * still has its durable context — just not the verbatim message history.
- *
- * Conservative defaults aim for ~30–40% of a 200k window so the next compact
- * has ample room to summarize.
- */
-export interface SoftResetOptions {
-  /** Keep at most this many user turns from the tail (default: 8). */
-  keepRecentUserTurns?: number;
-  /** Hard cap on jsonl bytes after trim (default: 250_000 ≈ 60–80k tokens). */
-  maxBytes?: number;
-}
-
-export interface SoftResetReport {
-  reset: boolean;
-  reason: string;
-  entriesBefore: number;
-  entriesAfter: number;
-  bytesBefore: number;
-  bytesAfter: number;
-  backupPath?: string;
-  /** Tool-pairing repair report on the trimmed file (orphans created by the cut). */
-  postRepair?: SessionRepairReport;
-}
-
-/**
- * Find a safe cut index in the entries array. Walk backwards from the end
- * looking for user message entries; the cut sits *at* the Nth most-recent
- * user message we encounter (so the kept tail starts on a user turn).
- * Returns the index of the first entry to KEEP (i.e. all entries[0..cutIdx)
- * are dropped).
- *
- * Byte-cap path: if we exceed the byte budget before reaching N user turns,
- * we still snap the cut to the most-recent user-message boundary we've seen.
- * That guarantees the kept tail always starts with a user message — never an
- * orphaned assistant reply or toolResult whose user prompt was dropped.
- *
- * If we can't find ANY user messages, returns entries.length (drop everything
- * but header) so the caller produces a header-only no-op session rather than
- * a malformed tail.
- */
-function findSoftResetCutIndex(
-  entries: SessionFileEntry[],
-  keepRecentUserTurns: number,
-  maxBytes: number,
-): { cutIdx: number; reason: string } {
-  let userTurnsSeen = 0;
-  let bytesAccumulated = 0;
-  /** Most recent user-message index we've walked through, or -1 if none yet. */
-  let lastUserIdx = -1;
-  // Scan tail-to-head, stop when we've collected enough user turns OR exceeded byte budget.
-  for (let i = entries.length - 1; i >= 0; i--) {
-    const e = entries[i];
-    bytesAccumulated += Buffer.byteLength(JSON.stringify(e), 'utf8') + 1; // +1 for newline
-    if (e.type === 'message' && e.message?.role === 'user') {
-      userTurnsSeen++;
-      lastUserIdx = i;
-      if (userTurnsSeen >= keepRecentUserTurns) {
-        return { cutIdx: i, reason: `kept-${userTurnsSeen}-user-turns` };
-      }
-    }
-    // Byte cap is a safety net for sessions where a single turn is enormous
-    // (e.g. one turn dumped a 200k file). When we hit it we MUST snap the cut
-    // to the most recent user-message boundary — otherwise the kept tail could
-    // start mid-turn (assistant/toolResult with no user prompt above it), and
-    // tool-pairing repair won't fix that.
-    if (bytesAccumulated > maxBytes && userTurnsSeen > 0) {
-      return { cutIdx: lastUserIdx, reason: `byte-cap-${bytesAccumulated}b` };
-    }
-  }
-  // Fewer user turns than target — treat as no-op. Soft-reset is recovery
-  // from overflow; if the session has fewer turns than our target it isn't
-  // overflowed and we shouldn't mutate it. Returning 1 means "keep everything
-  // after the header", which the caller's `cutIdx <= 1` gate maps to reset:false.
-  return { cutIdx: 1, reason: 'fewer-turns-than-target' };
-}
-
-/**
- * Soft-reset a pi-ai session jsonl: keep the most-recent N user turns + their
- * surrounding messages, drop everything older. Always preserves the session
- * header (entries[0]). Re-parents the first kept entry to null so the tree
- * remains valid. Re-runs tool-pairing repair on the trimmed file because
- * the cut likely orphaned some toolCall/toolResult pairs.
- *
- * Atomic + backup: same safety pattern as repairSessionFile.
- *
- * @returns report describing what was reset, or `{reset:false}` if nothing to do.
- */
-export function softResetSessionFile(
-  path: string,
-  options: SoftResetOptions = {},
-): SoftResetReport {
-  if (!existsSync(path)) {
-    throw new Error(`Session file not found: ${path}`);
-  }
-
-  const keepRecentUserTurns = options.keepRecentUserTurns ?? 8;
-  const maxBytes = options.maxBytes ?? 250_000;
-
-  const entries = parseSessionFile(path);
-  const bytesBefore = readFileSync(path).length;
-
-  // Need at least header + a couple of messages to be worth resetting.
-  if (entries.length < 4) {
-    return {
-      reset: false,
-      reason: 'session-too-small',
-      entriesBefore: entries.length,
-      entriesAfter: entries.length,
-      bytesBefore,
-      bytesAfter: bytesBefore,
-    };
-  }
-
-  const { cutIdx, reason } = findSoftResetCutIndex(entries, keepRecentUserTurns, maxBytes);
-
-  // No-op if cut is already at the start (nothing to drop besides header).
-  if (cutIdx <= 1) {
-    return {
-      reset: false,
-      reason: `cut-at-start (${reason})`,
-      entriesBefore: entries.length,
-      entriesAfter: entries.length,
-      bytesBefore,
-      bytesAfter: bytesBefore,
-    };
-  }
-
-  // Build trimmed entries: header + tail.
-  // Re-parent the first kept tail entry to null so the tree root is intact.
-  const header = entries[0];
-  const tail = entries.slice(cutIdx);
-  if (tail.length > 0 && tail[0].parentId !== undefined) {
-    tail[0] = { ...tail[0], parentId: null };
-  }
-  const trimmed = [header, ...tail];
-
-  // Run tool-pair repair *in memory* on the trimmed entries before writing,
-  // so the on-disk update is a single atomic backup + atomic rename. Doing
-  // disk-write → repairSessionFile() (another disk-write) would mean a crash
-  // between the two leaves a partially-processed file AND a backup of the
-  // already-trimmed file rather than the true original.
-  const repaired = repairEntriesInMemory(trimmed);
-
-  const backupPath = backupFile(path);
-  const newContent = repaired.entries.map(e => JSON.stringify(e)).join('\n') + '\n';
-  atomicWrite(path, newContent);
-
-  const bytesAfter = Buffer.byteLength(newContent, 'utf8');
-  return {
-    reset: true,
-    reason,
-    entriesBefore: entries.length,
-    entriesAfter: repaired.entries.length,
-    bytesBefore,
-    bytesAfter,
-    backupPath,
-    postRepair: repaired.report,
-  };
-}
-
-// ── Error classifiers ────────────────────────────────────────────────────
-
-/**
- * Detect whether an error from pi-ai / the model provider indicates the
- * session has grown past the model's context window (input > max).
- *
- * Triggers soft-reset recovery in the memory lifecycle. Intentionally narrow:
- * only matches the well-known overflow phrasings, not generic 4xx errors.
- *
- * Mirrors `isToolPairingError`'s nested-error handling: provider SDKs commonly
- * wrap the useful text under `cause.message` or in serialized fields on
- * Bedrock ValidationException. Stringify-search is gated on a 4xx / validation
- * shape so we don't false-positive on noisy unrelated errors.
- */
-export function isContextOverflowError(err: unknown): boolean {
-  if (!err) return false;
-  const patterns = [
-    /prompt is too long/i,
-    /tokens?\s*[>>]\s*\d+\s*maximum/i,
-    /input is too long/i,
-    /context length exceeded/i,
-    /maximum context length/i,
-  ];
-
-  // 1. Top-level message.
-  const msg = (err as { message?: string }).message ?? String(err);
-  if (patterns.some(p => p.test(msg))) return true;
-
-  // 2. Walk the cause chain (a few hops — don't loop forever on circular).
-  let cur: unknown = (err as { cause?: unknown }).cause;
-  for (let hop = 0; hop < 5 && cur; hop++) {
-    const causeMsg = (cur as { message?: string }).message ?? String(cur);
-    if (patterns.some(p => p.test(causeMsg))) return true;
-    cur = (cur as { cause?: unknown }).cause;
-  }
-
-  // 3. Bedrock ValidationException sometimes carries the overflow text in
-  // nested SDK fields. Only stringify-search when the error LOOKS like a 4xx
-  // validation error — mirrors the gating in isToolPairingError.
-  const name = (err as { name?: string }).name ?? '';
-  const httpStatus =
-    (err as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;
-  if (name === 'ValidationException' || httpStatus === 400) {
-    try {
-      const full = JSON.stringify(err);
-      if (patterns.some(p => p.test(full))) return true;
-    } catch {
-      /* circular structure — give up */
-    }
-  }
-
-  return false;
-}
-
-/**
- * Detect whether an error from pi-ai / the model provider indicates a
- * tool-pairing mismatch that can be recovered by session repair.
- *
- * Matches Bedrock Converse and Anthropic error shapes. Intentionally narrow —
- * we don't want to repair on unrelated 400s.
- */
-export function isToolPairingError(err: unknown): boolean {
-  if (!err) return false;
-  const msg = (err as { message?: string }).message ?? String(err);
-  const name = (err as { name?: string }).name ?? '';
-
-  // Bedrock Converse: "messages.N: `tool_use` ids were found without `tool_result` blocks..."
-  // Anthropic direct: similar phrasing
-  const patterns = [
-    /tool_use.*without.*tool_result/i,
-    /tool_result.*without.*tool_use/i,
-    /toolUse.*without.*toolResult/i,
-    /unmatched.*tool.?use/i,
-    /orphan.*tool/i,
-  ];
-
-  if (patterns.some(p => p.test(msg))) return true;
-
-  // Bedrock ValidationException may carry the pairing text in nested fields
-  // (e.g. err.cause.message, $metadata). Only stringify-search when the error
-  // *looks* like a Bedrock validation error — avoid noisy matches on unrelated
-  // messages that happen to contain '400'.
-  const httpStatus =
-    (err as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;
-  if (name === 'ValidationException' || httpStatus === 400) {
-    try {
-      const full = JSON.stringify(err);
-      if (patterns.some(p => p.test(full))) return true;
-    } catch {
-      /* circular structure — give up */
-    }
-  }
-  return false;
-}

package/src/agents/shared/session-soft-reset.ts

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import {
+  assertSessionFileExists,
+  atomicWrite,
+  backupFile,
+  parseSessionFile,
+  repairEntriesInMemory,
+  type SessionFileEntry,
+  type SessionRepairReport,
+} from './session-repair-internal';
+
+export interface SoftResetOptions {
+  /** Keep at most this many user turns from the tail (default: 8). */
+  keepRecentUserTurns?: number;
+  /** Hard cap on jsonl bytes after trim (default: 250_000 ≈ 60–80k tokens). */
+  maxBytes?: number;
+}
+
+export interface SoftResetReport {
+  reset: boolean;
+  reason: string;
+  entriesBefore: number;
+  entriesAfter: number;
+  bytesBefore: number;
+  bytesAfter: number;
+  backupPath?: string;
+  /** Tool-pairing repair report on the trimmed file (orphans created by the cut). */
+  postRepair?: SessionRepairReport;
+}
+
+function findSoftResetCutIndex(
+  entries: SessionFileEntry[],
+  keepRecentUserTurns: number,
+  maxBytes: number,
+): { cutIdx: number; reason: string } {
+  let userTurnsSeen = 0;
+  let bytesAccumulated = 0;
+  let lastUserIdx = -1;
+
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    bytesAccumulated += Buffer.byteLength(JSON.stringify(entry), 'utf8') + 1;
+    if (entry.type === 'message' && entry.message?.role === 'user') {
+      userTurnsSeen++;
+      lastUserIdx = i;
+      if (userTurnsSeen >= keepRecentUserTurns) {
+        return { cutIdx: i, reason: `kept-${userTurnsSeen}-user-turns` };
+      }
+    }
+    if (bytesAccumulated > maxBytes && userTurnsSeen > 0) {
+      return { cutIdx: lastUserIdx, reason: `byte-cap-${bytesAccumulated}b` };
+    }
+  }
+
+  return { cutIdx: 1, reason: 'fewer-turns-than-target' };
+}
+
+function buildTrimmedEntries(entries: SessionFileEntry[], cutIdx: number): SessionFileEntry[] {
+  const header = entries[0];
+  const tail = entries.slice(cutIdx);
+  if (tail.length > 0 && tail[0].parentId !== undefined) {
+    tail[0] = { ...tail[0], parentId: null };
+  }
+  return [header, ...tail];
+}
+
+export function softResetSessionFile(
+  path: string,
+  options: SoftResetOptions = {},
+): SoftResetReport {
+  assertSessionFileExists(path);
+
+  const keepRecentUserTurns = options.keepRecentUserTurns ?? 8;
+  const maxBytes = options.maxBytes ?? 250_000;
+
+  const entries = parseSessionFile(path);
+  const bytesBefore = readFileSync(path).length;
+
+  if (entries.length < 4) {
+    return {
+      reset: false,
+      reason: 'session-too-small',
+      entriesBefore: entries.length,
+      entriesAfter: entries.length,
+      bytesBefore,
+      bytesAfter: bytesBefore,
+    };
+  }
+
+  const { cutIdx, reason } = findSoftResetCutIndex(entries, keepRecentUserTurns, maxBytes);
+  if (cutIdx <= 1) {
+    return {
+      reset: false,
+      reason: `cut-at-start (${reason})`,
+      entriesBefore: entries.length,
+      entriesAfter: entries.length,
+      bytesBefore,
+      bytesAfter: bytesBefore,
+    };
+  }
+
+  const trimmed = buildTrimmedEntries(entries, cutIdx);
+  const repaired = repairEntriesInMemory(trimmed);
+
+  const backupPath = backupFile(path);
+  const newContent = repaired.entries.map(entry => JSON.stringify(entry)).join('\n') + '\n';
+  atomicWrite(path, newContent);
+
+  const bytesAfter = Buffer.byteLength(newContent, 'utf8');
+  return {
+    reset: true,
+    reason,
+    entriesBefore: entries.length,
+    entriesAfter: repaired.entries.length,
+    bytesBefore,
+    bytesAfter,
+    backupPath,
+    postRepair: repaired.report,
+  };
+}

package/src/memory/lifecycle.ts

@@ -16,7 +16,7 @@ import { shouldInjectMemory, classifyContextPressure, isSoftFlushOnCooldown } fr
 import { buildMemoryInjection, injectMemoryIntoMessage } from "./inject";
 import { buildFlushPrompt } from "./prompts";
 import { bootstrapMemoryFiles } from "./bootstrap";
-import { isContextOverflowError } from "../agents/shared/session-repair";
+import { isContextOverflowError } from "../agents/shared/error-classifiers";
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -51,6 +51,41 @@ function appendCompactLog(entry: CompactLogEntry): void {
     .catch((err) => console.warn(`[memory] timing log write failed:`, (err as Error).message));
 }
 
+async function attemptSoftResetRecovery(
+  err: unknown,
+  threadId: string,
+  agent: AgentAdapter,
+  onProgress?: (step: string) => void | Promise<void>,
+): Promise<{ attempted: boolean; succeeded: boolean }> {
+  if (!isContextOverflowError(err) || !agent.softReset) {
+    return { attempted: false, succeeded: false };
+  }
+
+  try {
+    await onProgress?.("♻️ Session overflowed — soft-resetting to recent turns...");
+    const report = await agent.softReset(threadId);
+    if (report?.reset) {
+      console.warn(`[memory] soft-reset recovered ${threadId} from overflow`);
+      const { entriesBefore, entriesAfter } = (report as { entriesBefore?: number; entriesAfter?: number });
+      const detail = typeof entriesBefore === "number" && typeof entriesAfter === "number"
+        ? ` (${entriesBefore} → ${entriesAfter} entries)`
+        : "";
+      await onProgress?.(`✅ Soft-reset complete${detail}. Durable memory will re-inject on next turn.`);
+      return { attempted: true, succeeded: true };
+    }
+
+    const reason = (report as { reason?: string } | null)?.reason ?? "unknown";
+    console.warn(`[memory] soft-reset returned no-op for ${threadId} (${reason})`);
+    await onProgress?.(`⚠️ Soft-reset no-op (${reason}). Will retry compact next turn.`);
+    return { attempted: true, succeeded: false };
+  } catch (resetErr) {
+    const msg = resetErr instanceof Error ? resetErr.message : String(resetErr);
+    console.error(`[memory] soft-reset failed for ${threadId}:`, msg);
+    await onProgress?.(`❌ Soft-reset failed: ${msg.slice(0, 200)}. Will retry next turn.`);
+    return { attempted: true, succeeded: false };
+  }
+}
+
 // ── Memory mode detection ────────────────────────────
 
 /**
@@ -360,34 +395,7 @@ export async function flushMemoryThenCompact(
   } catch (err) {
     const errMsg = (err as Error).message;
     console.error(`[memory] flush+compact failed for ${threadId}:`, errMsg);
-
-    // Recovery path: when the session has grown past the model's context
-    // window, the summarizer prompt itself overflows and compact() throws
-    // "prompt is too long". Threshold tuning prevents *new* sessions from
-    // hitting this, but does nothing for sessions already past the line.
-    // Trim the on-disk session jsonl to its most recent N user turns and
-    // mark the next turn for a fresh memory injection. We do NOT retry
-    // compact inline — that would extend the thread lock for another long
-    // operation. The trimmed session is small enough that the next user
-    // turn proceeds normally; any soft pressure from injected memory will
-    // trigger a regular compact later.
-    let softResetAttempted = false;
-    let softResetSucceeded = false;
-    if (isContextOverflowError(err) && agent.softReset) {
-      softResetAttempted = true;
-      try {
-        await onProgress?.("♻️ Session overflowed — soft-resetting to recent turns...");
-        const report = await agent.softReset(threadId);
-        if (report?.reset) {
-          softResetSucceeded = true;
-          console.warn(`[memory] soft-reset recovered ${threadId} from overflow`);
-        } else {
-          console.warn(`[memory] soft-reset returned no-op for ${threadId} (${(report as { reason?: string } | null)?.reason ?? "unknown"})`);
-        }
-      } catch (resetErr) {
-        console.error(`[memory] soft-reset failed for ${threadId}:`, (resetErr as Error).message);
-      }
-    }
+    const recovery = await attemptSoftResetRecovery(err, threadId, agent, onProgress);
 
     appendCompactLog({
       threadId,
@@ -401,13 +409,13 @@ export async function flushMemoryThenCompact(
       totalMs: Date.now() - t0,
       model: flushModel ?? "default",
       status: "failed",
-      error: (softResetAttempted
-        ? `${softResetSucceeded ? "soft-reset-recovered" : "soft-reset-failed"}: ${errMsg}`
+      error: (recovery.attempted
+        ? `${recovery.succeeded ? "soft-reset-recovered" : "soft-reset-failed"}: ${errMsg}`
         : errMsg).slice(0, 500),
     });
 
     try {
-      if (softResetSucceeded) {
+      if (recovery.succeeded) {
         // Soft reset cleared the overflow. Mark the next turn for memory
         // re-injection so the agent has its durable context, and clear the
         // pendingCompact flag — there's nothing left to compact now.