@inceptionstack/roundhouse 0.5.29 → 0.5.30

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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

package/package.json

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

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

@@ -505,6 +505,104 @@ describe('softResetSessionFile', () => {
     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];
@@ -549,4 +647,46 @@ describe('isContextOverflowError', () => {
     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,44 +246,65 @@ 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 = kept.map(e => JSON.stringify(e)).join('\n') + '\n';
+  const newContent = repaired.map(e => JSON.stringify(e)).join('\n') + '\n';
   atomicWrite(path, newContent);
 
-  return {
-    repaired: true,
-    droppedEntryIds: Array.from(entriesToDrop),
-    droppedToolCallIds: validation.orphanedToolCallIds,
-    droppedToolResultIds: validation.orphanedToolResultIds,
-    backupPath,
-    totalEntries: entries.length,
-  };
+  return { ...report, backupPath };
 }
 
 // ── Soft reset (recovery from already-overflowed sessions) ──────────────
@@ -323,12 +344,19 @@ export interface SoftResetReport {
 
 /**
  * Find a safe cut index in the entries array. Walk backwards from the end
- * looking for user message entries; the cut sits *just before* the Nth
- * most-recent user message we encounter. Returns the index of the first
- * entry to KEEP (i.e. all entries[0..cutIdx) are dropped).
+ * 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).
  *
- * If we can't find enough user messages, returns 1 to keep everything except
- * the session header (which we preserve separately).
+ * 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[],
@@ -337,24 +365,32 @@ function findSoftResetCutIndex(
 ): { 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 += JSON.stringify(e).length + 1; // +1 for newline
+    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). Stop once we'd exceed the cap.
+    // (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: i + 1, reason: `byte-cap-${bytesAccumulated}b` };
+      return { cutIdx: lastUserIdx, reason: `byte-cap-${bytesAccumulated}b` };
     }
   }
-  // Not enough user turns in the file — keep everything except header.
-  // (Header is always at index 0 and is preserved by the writer separately.)
+  // 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' };
 }
 
@@ -418,24 +454,27 @@ export function softResetSessionFile(
   }
   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 = trimmed.map(e => JSON.stringify(e)).join('\n') + '\n';
+  const newContent = repaired.entries.map(e => JSON.stringify(e)).join('\n') + '\n';
   atomicWrite(path, newContent);
 
-  // The cut may have orphaned tool pairs (e.g. toolResult kept but its
-  // toolCall is now in the dropped section). Run repair to clean those up.
-  const postRepair = repairSessionFile(path);
-
-  const bytesAfter = readFileSync(path).length;
+  const bytesAfter = Buffer.byteLength(newContent, 'utf8');
   return {
     reset: true,
     reason,
     entriesBefore: entries.length,
-    entriesAfter: trimmed.length - postRepair.droppedEntryIds.length,
+    entriesAfter: repaired.entries.length,
     bytesBefore,
     bytesAfter,
     backupPath,
-    postRepair,
+    postRepair: repaired.report,
   };
 }
 
@@ -447,10 +486,14 @@ export function softResetSessionFile(
  *
  * 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 msg = (err as { message?: string }).message ?? String(err);
   const patterns = [
     /prompt is too long/i,
     /tokens?\s*[>>]\s*\d+\s*maximum/i,
@@ -458,7 +501,35 @@ export function isContextOverflowError(err: unknown): boolean {
     /context length exceeded/i,
     /maximum context length/i,
   ];
-  return patterns.some(p => p.test(msg));
+
+  // 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;
 }
 
 /**