@inceptionstack/roundhouse 0.5.28 → 0.5.30

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `@inceptionstack/roundhouse` are documented here.
 
+## [0.5.30] — 2026-05-14
+
+### Fixed
+- **Soft-reset robustness fixes from codex review of v0.5.29:**
+  - **P1 — byte-cap could cut mid-turn.** When `findSoftResetCutIndex()` hit the byte budget before reaching `keepRecentUserTurns`, it returned `i + 1` which could land on an assistant reply or toolResult whose user prompt was about to be dropped. The kept tail then started mid-turn and tool-pairing repair didn't fix that (only orphans, not turn boundaries). Fixed: byte-cap path now snaps to the most-recent user-message boundary we've walked through.
+  - **P2 — byte cap measured in JS code units, not real bytes.** `JSON.stringify(e).length` counts UTF-16 code units; non-ASCII content (emoji, CJK) overshot the advertised 250k ceiling 2–3x. Now uses `Buffer.byteLength(..., 'utf8')` end-to-end so reported `bytesAfter` and the cap decision both reflect actual file bytes.
+  - **P2 — trim + repair was not atomic end-to-end.** Old flow wrote the trimmed file, then called `repairSessionFile()` which re-backed-up the *already-trimmed* file and rewrote it again. A crash between the two writes left a partial state and lost the true original. Refactored: extracted `repairEntriesInMemory()` so trim + tool-pair repair compose in memory and land as a single backup + atomic rename.
+  - **P2 — `isContextOverflowError()` only inspected top-level `.message`.** Wrapped provider errors (`err.cause.message`, Bedrock `ValidationException` carrying overflow text in nested SDK fields) fell through to re-arming `pendingCompact` instead of triggering recovery. Now mirrors `isToolPairingError()`'s nested handling: walks the `cause` chain (bounded, cycle-safe) and stringify-searches gated on a 4xx/`ValidationException` shape so we don't false-positive on unrelated 5xx noise.
+- 7 regression tests added (534 total passing): byte-cap user-boundary snap, UTF-8 byte accounting, single-atomic-write backup integrity, wrapped-cause classification, Bedrock validation classification, false-positive gating, circular-cause safety.
+
+## [0.5.29] — 2026-05-14
+
+### Added
+- **Soft-reset recovery for already-overflowed sessions.** When a session has grown past the model's context window, normal compact cannot recover — the summarizer prompt itself overflows and `compact()` throws `prompt is too long: N > max`. v0.5.28's threshold tuning prevents *new* sessions from hitting this; this release adds graceful recovery for sessions that already crossed the line. On context-overflow detection, the memory lifecycle calls a new `agent.softReset(threadId)` capability that trims the on-disk session jsonl to its most-recent N user turns (default 8, byte-capped at 250k), reloads the session, and queues a memory re-injection on the next turn. The agent loses verbatim message history for older turns but retains its durable context (MEMORY.md, daily front-page, soul.md). No more manual surgery on stuck sessions.
+- New module exports: `softResetSessionFile()` and `isContextOverflowError()` in `src/agents/shared/session-repair.ts`. New optional `softReset?(threadId)` method on `AgentAdapter` interface (no-op when not implemented — backward-compatible). PiAdapter implements it via the existing `reloadSession` path.
+- 20 new tests across `session-repair.test.ts` (file-level cut/preserve/repair semantics, error classifier) and `memory.test.ts` (lifecycle wiring — success/no-op/missing-capability/non-overflow-error/throws-during-recovery). 527 tests total.
+
 ## [0.5.28] — 2026-05-14
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.28",
+  "version": "0.5.30",
   "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,7 @@ import {
 
 import type { AgentAdapter, AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent, MessageContext } from "../../types";
 import { formatMessage, extractCustomMessage, customContentToText } from "./message-format";
-import { isToolPairingError, repairSessionFile } from "../shared/session-repair";
+import { isToolPairingError, repairSessionFile, softResetSessionFile, type SoftResetReport } from "../shared/session-repair";
 import { SESSIONS_DIR } from "../../config";
 import { DEBUG_STREAM, threadIdToDir } from "../../util";
 
@@ -662,6 +662,58 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
       });
     },
 
+    /**
+     * Soft-reset an overflowed session: trim the on-disk jsonl to its most
+     * recent N user turns, then reload the session in place. Used by the
+     * memory-lifecycle layer when compact fails with "prompt is too long"
+     * — the session has grown past the model's context window and the
+     * summarizer prompt itself can no longer fit.
+     *
+     * Returns the soft-reset report (or null if no session for threadId).
+     * Behavior:
+     *   - In-memory session: returns null (nothing to trim on disk).
+     *   - Already-trimmed session: report.reset === false, no reload.
+     *   - Otherwise: trims file, reloads session, returns report.
+     *
+     * On reload failure, the SessionEntry is dropped from the cache so the
+     * next prompt() recreates it cleanly.
+     */
+    async softReset(threadId: string): Promise<SoftResetReport | null> {
+      return enqueue(threadId, async () => {
+        const entry = sessions.get(threadId);
+        if (!entry) return null;
+        const sessionFile = entry.session.sessionFile;
+        if (!sessionFile) {
+          console.warn(`[pi-agent] softReset: ${threadId} has no on-disk session file, skipping`);
+          return null;
+        }
+
+        console.warn(`[pi-agent] softReset: trimming overflowed session ${sessionFile}`);
+        const report = softResetSessionFile(sessionFile);
+        if (!report.reset) {
+          console.log(`[pi-agent] softReset: nothing to trim (${report.reason})`);
+          return report;
+        }
+        console.warn(
+          `[pi-agent] softReset: ${report.entriesBefore} → ${report.entriesAfter} entries, ` +
+          `${report.bytesBefore} → ${report.bytesAfter} bytes (${report.reason}). Backup: ${report.backupPath}`
+        );
+
+        // Reload the session so pi-ai re-reads the trimmed file. Drop the
+        // cache entry on failure so the next prompt() recreates from scratch
+        // rather than running against the disposed session.
+        try {
+          const reloaded = await reloadSession(entry, sessionFile);
+          await entry.session.dispose();
+          entry.session = reloaded.session;
+        } catch (err) {
+          console.error(`[pi-agent] softReset reload failed for ${threadId}:`, (err as Error).message);
+          sessions.delete(threadId);
+        }
+        return report;
+      });
+    },
+
     async abort(threadId: string): Promise<void> {
       const entry = sessions.get(threadId);
       if (entry) {

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

@@ -11,6 +11,8 @@ import {
   inspectSessionFile,
   repairSessionFile,
   isToolPairingError,
+  softResetSessionFile,
+  isContextOverflowError,
 } from './session-repair';
 
 // ---------- fixtures ----------
@@ -376,3 +378,315 @@ describe('session-repair', () => {
     });
   });
 });
+
+// ============================================================
+// softResetSessionFile
+// ============================================================
+
+describe('softResetSessionFile', () => {
+  function userTurn(idPrefix: string, parentId: string | null) {
+    // A user turn = user msg + assistant text reply (no tool calls, so cuts
+    // are clean; tool-pairing edge cases are covered by repair tests).
+    return [
+      userMsg(`${idPrefix}u`, parentId, `text-${idPrefix}`),
+      {
+        type: 'message',
+        id: `${idPrefix}a`,
+        parentId: `${idPrefix}u`,
+        timestamp: '2026-05-01T00:00:04Z',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: `reply-${idPrefix}` }],
+          api: 'bedrock-converse-stream',
+          provider: 'amazon-bedrock',
+          model: 'claude',
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+          stopReason: 'endTurn',
+          timestamp: 4,
+        },
+      },
+    ];
+  }
+
+  it('softResetSessionFile_OnSessionWithMoreTurnsThanTarget_KeepsHeaderAndRecentTurns', () => {
+    // Arrange: 10 user turns, target keepRecentUserTurns=3.
+    const entries: object[] = [HEADER, MODEL_CHANGE];
+    let parent: string | null = 'mc-1';
+    for (let i = 1; i <= 10; i++) {
+      const turn = userTurn(`t${i}`, parent);
+      entries.push(...turn);
+      parent = `t${i}a`;
+    }
+    const path = tmpJsonl(entries);
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 3 });
+
+    // Assert: report indicates reset, file shrunk, header preserved, last 3 user msgs present.
+    expect(report.reset).toBe(true);
+    expect(report.entriesAfter).toBeLessThan(report.entriesBefore);
+    expect(report.bytesAfter).toBeLessThan(report.bytesBefore);
+    expect(report.backupPath).toBeDefined();
+    expect(existsSync(report.backupPath!)).toBe(true);
+
+    const trimmed = parseSessionFile(path);
+    // Header always preserved.
+    expect(trimmed[0].type).toBe('session');
+    // Last 3 user turns present.
+    const userIds = trimmed.filter(e => e.message?.role === 'user').map(e => e.id);
+    expect(userIds).toEqual(['t8u', 't9u', 't10u']);
+    // First kept entry's parentId reset to null (no dangling pointer).
+    const firstAfterHeader = trimmed[1];
+    expect(firstAfterHeader.parentId).toBeNull();
+  });
+
+  it('softResetSessionFile_OnSessionSmallerThanTarget_ReturnsResetFalseAndDoesNotMutate', () => {
+    // Arrange: 2 user turns, target keepRecentUserTurns=8.
+    const entries: object[] = [HEADER, MODEL_CHANGE, ...userTurn('a', 'mc-1'), ...userTurn('b', 'aa')];
+    const path = tmpJsonl(entries);
+    const before = readFileSync(path, 'utf8');
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 8 });
+
+    // Assert: no reset, file untouched, no backup.
+    expect(report.reset).toBe(false);
+    expect(report.backupPath).toBeUndefined();
+    expect(readFileSync(path, 'utf8')).toBe(before);
+  });
+
+  it('softResetSessionFile_OnTinySession_ReturnsResetFalseWithReason', () => {
+    // Arrange: only header.
+    const path = tmpJsonl([HEADER]);
+
+    // Act
+    const report = softResetSessionFile(path);
+
+    // Assert
+    expect(report.reset).toBe(false);
+    expect(report.reason).toContain('too-small');
+  });
+
+  it('softResetSessionFile_OnSessionWithOrphanedToolPairsAfterCut_AlsoRunsRepair', () => {
+    // Arrange: a session where the tail contains a toolResult whose toolCall
+    // sits in the older (dropped) section. After the cut the toolResult is
+    // orphaned — soft-reset must clean it up via the post-cut repair.
+    const oldToolCall = assistantToolCall('a-old', 'mc-1', 'call-X');
+    const orphanedResult = {
+      type: 'message',
+      id: 'tr-1',
+      parentId: 'a-old',
+      timestamp: '2026-05-01T00:00:05Z',
+      message: { role: 'toolResult', toolCallId: 'call-X', content: 'ok', timestamp: 5 },
+    };
+    const entries: object[] = [HEADER, MODEL_CHANGE, userMsg('u-old', 'mc-1', 'old'), oldToolCall];
+    let parent: string | null = 'a-old';
+    // Push 5 fresh turns so the cut leaves us in tail.
+    for (let i = 1; i <= 5; i++) {
+      entries.push(...userTurn(`f${i}`, parent));
+      parent = `f${i}a`;
+    }
+    // Insert the orphaned result mid-tail (kept by cut, but call is dropped).
+    entries.splice(6, 0, orphanedResult);
+    const path = tmpJsonl(entries);
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 3 });
+
+    // Assert: reset succeeded AND post-cut repair fired.
+    expect(report.reset).toBe(true);
+    expect(report.postRepair).toBeDefined();
+    // Final file is internally consistent (no orphans).
+    expect(inspectSessionFile(path).hasOrphans).toBe(false);
+  });
+
+  it('softResetSessionFile_OnNonexistentFile_Throws', () => {
+    // Arrange/Act/Assert: documents the precondition.
+    expect(() => softResetSessionFile('/nonexistent/path.jsonl')).toThrow(/not found/);
+  });
+
+  it('softResetSessionFile_ByteCapHit_SnapsToUserTurnBoundary_NeverStartsMidTurn', () => {
+    // Regression test for codex P1: byte-cap path used to return `i + 1`
+    // which could land mid-turn (assistant reply or toolResult with no user
+    // prompt above it). Fixed to snap to the most-recent user-message index.
+    // Arrange: many small turns, byte cap forces an early cut.
+    const entries: object[] = [HEADER, MODEL_CHANGE];
+    let parent: string | null = 'mc-1';
+    for (let i = 1; i <= 30; i++) {
+      entries.push(...userTurn(`t${i}`, parent));
+      parent = `t${i}a`;
+    }
+    const path = tmpJsonl(entries);
+
+    // Act: very tight byte budget so cap fires before keepRecentUserTurns reached.
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 100, maxBytes: 600 });
+
+    // Assert: reset happened AND first kept entry is a user message.
+    expect(report.reset).toBe(true);
+    const trimmed = parseSessionFile(path);
+    expect(trimmed[0].type).toBe('session');           // header preserved
+    expect(trimmed[1].message?.role).toBe('user');     // first kept = user turn
+    expect(trimmed[1].parentId).toBeNull();            // re-parented
+  });
+
+  it('softResetSessionFile_NonAsciiContent_ReportedBytesMatchActualFileBytes', () => {
+    // Regression test for codex P2: trim used JSON.stringify(e).length
+    // (UTF-16 code units) but reported bytesAfter from real file bytes.
+    // After fix, both use Buffer.byteLength(..., 'utf8').
+    // Arrange: turns containing multi-byte UTF-8 (each emoji = 4 bytes,
+    // length 2 in code units — 2x discrepancy).
+    const entries: object[] = [HEADER, MODEL_CHANGE];
+    const emojis = '🚀🔥🎉✨💡'.repeat(20); // ~100 bytes per turn
+    let parent: string | null = 'mc-1';
+    for (let i = 1; i <= 20; i++) {
+      entries.push(
+        userMsg(`t${i}u`, parent, `${emojis} text-${i}`),
+        {
+          type: 'message', id: `t${i}a`, parentId: `t${i}u`,
+          timestamp: '2026-05-01T00:00:04Z',
+          message: {
+            role: 'assistant',
+            content: [{ type: 'text', text: `${emojis} reply-${i}` }],
+            api: 'bedrock-converse-stream', provider: 'amazon-bedrock', model: 'claude',
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+            stopReason: 'endTurn', timestamp: 4,
+          },
+        },
+      );
+      parent = `t${i}a`;
+    }
+    const path = tmpJsonl(entries);
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 100, maxBytes: 2000 });
+
+    // Assert: reported bytesAfter matches actual file bytes (true UTF-8 size).
+    expect(report.reset).toBe(true);
+    const actualBytes = readFileSync(path).length;
+    expect(report.bytesAfter).toBe(actualBytes);
+    // And we honored the cap (allow some slack for snap-to-user-boundary).
+    expect(report.bytesAfter).toBeLessThan(4000);
+  });
+
+  it('softResetSessionFile_OnSingleAtomicWrite_OriginalBackupIsRecoverable', () => {
+    // Regression test for codex P2: previously trim wrote once, then
+    // repairSessionFile() wrote again with its OWN backup of the
+    // already-trimmed file. After fix, only one backup exists and it's
+    // the true original.
+    // Arrange: session with orphaned tool pair so post-cut repair fires.
+    const oldToolCall = assistantToolCall('a-old', 'mc-1', 'call-X');
+    const orphanedResult = {
+      type: 'message', id: 'tr-1', parentId: 'a-old',
+      timestamp: '2026-05-01T00:00:05Z',
+      message: { role: 'toolResult', toolCallId: 'call-X', content: 'ok', timestamp: 5 },
+    };
+    const entries: object[] = [HEADER, MODEL_CHANGE, userMsg('u-old', 'mc-1', 'old'), oldToolCall];
+    let parent: string | null = 'a-old';
+    for (let i = 1; i <= 5; i++) {
+      entries.push(...userTurn(`f${i}`, parent));
+      parent = `f${i}a`;
+    }
+    entries.splice(6, 0, orphanedResult);
+    const path = tmpJsonl(entries);
+    const originalBytes = readFileSync(path);
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 3 });
+
+    // Assert: backup contents = TRUE original (pre-trim, pre-repair),
+    // not an intermediate trimmed-but-unrepaired state.
+    expect(report.reset).toBe(true);
+    expect(report.backupPath).toBeDefined();
+    const backup = readFileSync(report.backupPath!);
+    expect(backup.equals(originalBytes)).toBe(true);
+    // Final on-disk file is internally consistent.
+    expect(inspectSessionFile(path).hasOrphans).toBe(false);
+  });
+
+  it('softResetSessionFile_BytesCapHonored_StopsCutAtCap', () => {
+    // Arrange: each turn is small but we set a tiny byte cap so we cut early.
+    const entries: object[] = [HEADER, MODEL_CHANGE];
+    let parent: string | null = 'mc-1';
+    for (let i = 1; i <= 20; i++) {
+      entries.push(...userTurn(`t${i}`, parent));
+      parent = `t${i}a`;
+    }
+    const path = tmpJsonl(entries);
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 100, maxBytes: 800 });
+
+    // Assert: reset triggered by byte cap (we asked for 100 turns we don't have,
+    // but byte cap kicks in first).
+    expect(report.reset).toBe(true);
+    expect(report.reason).toMatch(/byte-cap|fewer-turns/);
+    expect(report.bytesAfter).toBeLessThan(report.bytesBefore);
+  });
+});
+
+// ============================================================
+// isContextOverflowError
+// ============================================================
+
+describe('isContextOverflowError', () => {
+  it.each([
+    ['prompt is too long: 212776 tokens > 200000 maximum', true],
+    ['Validation error: input is too long', true],
+    ['context length exceeded for this model', true],
+    ['maximum context length reached', true],
+    ['tokens > 200000 maximum', true],
+    ['toolUse without toolResult', false], // pairing error — different recovery
+    ['random network failure', false],
+    ['', false],
+  ])('classifies %p as overflow=%p', (msg, expected) => {
+    expect(isContextOverflowError(new Error(msg))).toBe(expected);
+  });
+
+  it('returns false for null/undefined/non-Error inputs', () => {
+    expect(isContextOverflowError(null)).toBe(false);
+    expect(isContextOverflowError(undefined)).toBe(false);
+    expect(isContextOverflowError({})).toBe(false);
+  });
+
+  it('classifies overflow when text lives in err.cause.message (wrapped SDK error)', () => {
+    // Regression test for codex P2: wrapped provider errors used to fall
+    // through to re-arming pendingCompact. After fix, cause-chain is walked.
+    const inner = new Error('prompt is too long: 212776 tokens > 200000 maximum');
+    const outer = new Error('Summarization failed');
+    (outer as { cause?: unknown }).cause = inner;
+    expect(isContextOverflowError(outer)).toBe(true);
+  });
+
+  it('classifies overflow on Bedrock ValidationException with nested overflow text', () => {
+    // Regression test: Bedrock SDK can carry the useful text in nested
+    // $metadata or stringify-only fields. We only stringify-search when
+    // the error LOOKS like a 4xx validation (mirrors isToolPairingError).
+    const err = Object.assign(new Error('validation failed'), {
+      name: 'ValidationException',
+      $metadata: { httpStatusCode: 400 },
+      detail: { reason: 'prompt is too long' },
+    });
+    expect(isContextOverflowError(err)).toBe(true);
+  });
+
+  it('does NOT stringify-search arbitrary errors that contain overflow keywords', () => {
+    // Negative case: gating prevents false-positives on unrelated 5xx errors
+    // whose payload happens to contain trigger phrases.
+    const err = Object.assign(new Error('internal error'), {
+      name: 'InternalServerError',
+      $metadata: { httpStatusCode: 500 },
+      diagnostics: 'log line: prompt is too long check disabled',
+    });
+    expect(isContextOverflowError(err)).toBe(false);
+  });
+
+  it('does not loop forever on circular cause chains', () => {
+    // Safety: cause walk is bounded.
+    const a = new Error('outer');
+    const b = new Error('inner');
+    (a as { cause?: unknown }).cause = b;
+    (b as { cause?: unknown }).cause = a; // cycle
+    expect(() => isContextOverflowError(a)).not.toThrow();
+    expect(isContextOverflowError(a)).toBe(false);
+  });
+});

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

@@ -246,46 +246,292 @@ export function inspectSessionFile(path: string): {
  *
  * @returns report describing what was repaired
  */
-export function repairSessionFile(path: string): SessionRepairReport {
-  if (!existsSync(path)) {
-    throw new Error(`Session file not found: ${path}`);
-  }
-
-  const entries = parseSessionFile(path);
+/**
+ * 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 {
-      repaired: false,
-      droppedEntryIds: [],
-      droppedToolCallIds: [],
-      droppedToolResultIds: [],
-      totalEntries: entries.length,
+      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}`);
+  }
+
+  const entries = parseSessionFile(path);
+  const { entries: repaired, report } = repairEntriesInMemory(entries);
+
+  if (!report.repaired) return report;
+
+  const backupPath = backupFile(path);
+  const newContent = repaired.map(e => JSON.stringify(e)).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 = kept.map(e => JSON.stringify(e)).join('\n') + '\n';
+  const newContent = repaired.entries.map(e => JSON.stringify(e)).join('\n') + '\n';
   atomicWrite(path, newContent);
 
+  const bytesAfter = Buffer.byteLength(newContent, 'utf8');
   return {
-    repaired: true,
-    droppedEntryIds: Array.from(entriesToDrop),
-    droppedToolCallIds: validation.orphanedToolCallIds,
-    droppedToolResultIds: validation.orphanedToolResultIds,
+    reset: true,
+    reason,
+    entriesBefore: entries.length,
+    entriesAfter: repaired.entries.length,
+    bytesBefore,
+    bytesAfter,
     backupPath,
-    totalEntries: entries.length,
+    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.

package/src/memory/lifecycle.ts

@@ -16,6 +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 { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -359,6 +360,35 @@ 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);
+      }
+    }
+
     appendCompactLog({
       threadId,
       level,
@@ -371,11 +401,22 @@ export async function flushMemoryThenCompact(
       totalMs: Date.now() - t0,
       model: flushModel ?? "default",
       status: "failed",
-      error: errMsg.slice(0, 500),
+      error: (softResetAttempted
+        ? `${softResetSucceeded ? "soft-reset-recovered" : "soft-reset-failed"}: ${errMsg}`
+        : errMsg).slice(0, 500),
     });
-    // Mark pending so we retry on next turn. Reuse the state we already loaded.
+
     try {
-      stateBeforeCompact.pendingCompact = effectiveLevel;
+      if (softResetSucceeded) {
+        // 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.
+        stateBeforeCompact.forceInjectReason = "after-soft-reset";
+        stateBeforeCompact.pendingCompact = undefined;
+      } else {
+        // Re-arm pendingCompact so the next turn retries.
+        stateBeforeCompact.pendingCompact = effectiveLevel;
+      }
       await saveThreadMemoryState(threadId, stateBeforeCompact);
     } catch {}
     return null;

package/src/memory/types.ts

@@ -56,7 +56,7 @@ export interface ThreadMemoryState {
   /** Local date when memory was last injected (detects day boundary) */
   lastSeenLocalDate?: string;
   /** Force re-injection on next turn */
-  forceInjectReason?: "new-session" | "after-compact" | "manual";
+  forceInjectReason?: "new-session" | "after-compact" | "after-soft-reset" | "manual";
   /** When last compaction happened */
   lastCompactAt?: string;
   /** Pending compaction level (from interrupted flush) */

package/src/types.ts

@@ -122,6 +122,17 @@ export interface AgentAdapter {
   /** Compact with a specific model. */
   compactWithModel?(threadId: string, modelId: string): Promise<{ tokensBefore: number; tokensAfter: number | null } | null>;
 
+  /**
+   * Soft-reset an overflowed session by trimming on-disk history to the
+   * most-recent few turns. Called by memory lifecycle when compact() fails
+   * because the session itself is too large for the model's context window.
+   *
+   * Returns a report describing what was trimmed (shape is adapter-specific
+   * but always has `reset: boolean`), or null if not applicable.
+   * Adapters without on-disk sessions (in-memory only) should return null.
+   */
+  softReset?(threadId: string): Promise<{ reset: boolean } | null>;
+
   /** Abort the current agent run for a thread. */
   abort?(threadId: string): Promise<void>;