@inceptionstack/roundhouse 0.5.21 → 0.5.25

package/src/agents/shared/message-validator.ts

@@ -0,0 +1,200 @@
+/**
+ * message-validator.ts — Validates and repairs agent message history
+ *
+ * Detects orphaned toolCall/toolResult blocks that corrupt message history:
+ * - orphaned toolResults (result without matching call)
+ * - orphaned toolCalls (call with no matching result, e.g., aborted tool execution)
+ *
+ * ⚠️  STATUS: Draft pending integration decision per Codex review.
+ * Codex recommends stream-time tool lifecycle tracking (in gateway/streaming.ts)
+ * over batch history validation for Pi/Kiro adapters.
+ * This module is designed for future raw-history providers.
+ */
+
+import type {
+  Message,
+  AssistantMessage,
+  ToolCall,
+  ToolResultMessage,
+} from '@earendil-works/pi-ai';
+
+// Re-export Message so tests/consumers can import it from this module
+// (required under isolatedModules when tests do `import { type Message } from './message-validator'`)
+export type { Message } from '@earendil-works/pi-ai';
+
+export interface ValidationResult {
+  isValid: boolean;
+  orphanedToolCallIds: string[];
+  orphanedToolResultIds: string[];
+  orphanedCount: number;
+}
+
+/**
+ * Validates that all toolCall/toolResult pairs are complete:
+ * - Every toolResult has a matching toolCall earlier in history
+ * - Every toolCall has a matching toolResult later in history (in order)
+ *
+ * Returns both orphaned toolCalls (calls with no result) and orphaned toolResults
+ * (results with no matching call).
+ */
+export function validateToolPairing(messages: Message[]): ValidationResult {
+  const toolCallIds = new Set<string>();
+  const toolCallIndexes = new Map<string, number>(); // toolCallId -> msgIndex
+  const toolResultIds = new Set<string>();
+  const orphanedCalls: string[] = [];
+  const orphanedResults: string[] = [];
+
+  // First pass: collect all tool call IDs and their positions
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg.role === 'assistant' && msg.content) {
+      for (const block of msg.content) {
+        if ((block as ToolCall).type === 'toolCall' && (block as ToolCall).id) {
+          const callId = (block as ToolCall).id;
+          // Duplicate toolCall IDs would be a pi-ai invariant violation upstream;
+          // keep first-occurrence semantics (set().add ignores dups; Map.set overwrites
+          // with last-seen index — guard to preserve earliest position for ordering checks).
+          if (!toolCallIndexes.has(callId)) {
+            toolCallIndexes.set(callId, i);
+          }
+          toolCallIds.add(callId);
+        }
+      }
+    }
+  }
+
+  // Second pass: check all toolResult messages have matching toolCall earlier
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg.role === 'toolResult') {
+      const resultMsg = msg as ToolResultMessage;
+      toolResultIds.add(resultMsg.toolCallId);
+
+      if (!toolCallIds.has(resultMsg.toolCallId)) {
+        orphanedResults.push(resultMsg.toolCallId);
+      } else {
+        // Verify the toolCall appears before this toolResult
+        const callIdx = toolCallIndexes.get(resultMsg.toolCallId);
+        if (callIdx !== undefined && callIdx >= i) {
+          // Call appears after result (invalid order)
+          orphanedResults.push(resultMsg.toolCallId);
+        }
+      }
+    }
+  }
+
+  // Third pass: check all toolCalls have matching toolResult later
+  for (const [callId, callIdx] of toolCallIndexes.entries()) {
+    if (!toolResultIds.has(callId)) {
+      // toolCall has no matching toolResult (e.g., execution aborted)
+      orphanedCalls.push(callId);
+    } else {
+      // Verify toolResult appears after this toolCall
+      let resultFound = false;
+      for (let i = callIdx + 1; i < messages.length; i++) {
+        if (messages[i].role === 'toolResult' &&
+            (messages[i] as ToolResultMessage).toolCallId === callId) {
+          resultFound = true;
+          break;
+        }
+      }
+      if (!resultFound) {
+        orphanedCalls.push(callId);
+      }
+    }
+  }
+
+  const allOrphaned = orphanedCalls.concat(orphanedResults);
+  return {
+    isValid: allOrphaned.length === 0,
+    orphanedToolCallIds: orphanedCalls,
+    orphanedToolResultIds: orphanedResults,
+    orphanedCount: allOrphaned.length,
+  };
+}
+
+/**
+ * Strips orphaned toolResults and toolCalls from message history.
+ * Returns repaired array or original if no orphans found.
+ *
+ * - Removes toolResult messages with orphaned IDs
+ * - Removes toolCall blocks from assistant messages with orphaned IDs
+ * - Strips entire assistant message if it becomes empty after removing toolCalls
+ */
+export function stripOrphanedResults(messages: Message[]): Message[] {
+  const { orphanedToolCallIds, orphanedToolResultIds } = validateToolPairing(messages);
+  const idsToRemove = new Set([...orphanedToolCallIds, ...orphanedToolResultIds]);
+
+  if (idsToRemove.size === 0) {
+    return messages;
+  }
+
+  const result: Message[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === 'toolResult') {
+      const resultMsg = msg as ToolResultMessage;
+      // Skip orphaned toolResult messages
+      if (!idsToRemove.has(resultMsg.toolCallId)) {
+        result.push(msg);
+      }
+    } else if (msg.role === 'assistant') {
+      const assistantMsg = msg as AssistantMessage;
+      // Filter out orphaned toolCall blocks
+      const cleanedContent = assistantMsg.content.filter(block => {
+        if ((block as ToolCall).type === 'toolCall') {
+          return !idsToRemove.has((block as ToolCall).id);
+        }
+        return true; // Keep text, thinking, images
+      });
+
+      // Only keep assistant message if it has remaining content
+      if (cleanedContent.length > 0) {
+        result.push({
+          ...assistantMsg,
+          content: cleanedContent,
+        });
+      }
+    } else {
+      result.push(msg);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validates and repairs message history in one call.
+ * Returns cleaned messages and a report if any repairs were made.
+ */
+export interface RepairResult {
+  messages: Message[];
+  wasRepaired: boolean;
+  strippedCount: number;
+  strippedCallIds: string[];
+  strippedResultIds: string[];
+}
+
+export function validateAndRepair(messages: Message[]): RepairResult {
+  const validation = validateToolPairing(messages);
+
+  if (validation.isValid) {
+    return {
+      messages,
+      wasRepaired: false,
+      strippedCount: 0,
+      strippedCallIds: [],
+      strippedResultIds: [],
+    };
+  }
+
+  const cleaned = stripOrphanedResults(messages);
+
+  return {
+    messages: cleaned,
+    wasRepaired: true,
+    strippedCount: validation.orphanedCount,
+    strippedCallIds: validation.orphanedToolCallIds,
+    strippedResultIds: validation.orphanedToolResultIds,
+  };
+}

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

@@ -0,0 +1,378 @@
+/**
+ * session-repair.test.ts — Tests for file-level session repair.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  parseSessionFile,
+  inspectSessionFile,
+  repairSessionFile,
+  isToolPairingError,
+} from './session-repair';
+
+// ---------- fixtures ----------
+
+const HEADER = {
+  type: 'session',
+  version: 3,
+  id: 'sess-1',
+  timestamp: '2026-05-01T00:00:00Z',
+  cwd: '/x',
+};
+
+const MODEL_CHANGE = {
+  type: 'model_change',
+  id: 'mc-1',
+  parentId: null,
+  timestamp: '2026-05-01T00:00:01Z',
+  provider: 'amazon-bedrock',
+  modelId: 'us.anthropic.claude-opus-4-7',
+};
+
+function userMsg(id: string, parentId: string | null, text: string) {
+  return {
+    type: 'message',
+    id,
+    parentId,
+    timestamp: '2026-05-01T00:00:02Z',
+    message: { role: 'user', content: [{ type: 'text', text }], timestamp: 1 },
+  };
+}
+
+function assistantToolCall(id: string, parentId: string | null, toolCallId: string, toolName = 'bash') {
+  return {
+    type: 'message',
+    id,
+    parentId,
+    timestamp: '2026-05-01T00:00:03Z',
+    message: {
+      role: 'assistant',
+      content: [{ type: 'toolCall', id: toolCallId, name: toolName, arguments: {} }],
+      api: 'bedrock-converse-stream',
+      provider: 'amazon-bedrock',
+      model: 'claude-opus',
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+      stopReason: 'toolUse',
+      timestamp: 2,
+    },
+  };
+}
+
+function assistantTextAndToolCall(id: string, parentId: string | null, toolCallId: string, text: string) {
+  return {
+    type: 'message',
+    id,
+    parentId,
+    timestamp: '2026-05-01T00:00:03Z',
+    message: {
+      role: 'assistant',
+      content: [
+        { type: 'text', text },
+        { type: 'toolCall', id: toolCallId, name: 'bash', arguments: {} },
+      ],
+      api: 'bedrock-converse-stream',
+      provider: 'amazon-bedrock',
+      model: 'claude-opus',
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+      stopReason: 'toolUse',
+      timestamp: 2,
+    },
+  };
+}
+
+function toolResult(id: string, parentId: string, toolCallId: string, text = 'ok') {
+  return {
+    type: 'message',
+    id,
+    parentId,
+    timestamp: '2026-05-01T00:00:04Z',
+    message: {
+      role: 'toolResult',
+      toolCallId,
+      toolName: 'bash',
+      content: [{ type: 'text', text }],
+      isError: false,
+      timestamp: 3,
+    },
+  };
+}
+
+function writeJsonl(path: string, entries: object[]): void {
+  writeFileSync(path, entries.map(e => JSON.stringify(e)).join('\n') + '\n');
+}
+
+// ---------- helpers ----------
+
+let tmpFiles: string[] = [];
+function tmpJsonl(entries: object[]): string {
+  const p = join(tmpdir(), `session-repair-test-${Date.now()}-${Math.random().toString(36).slice(2)}.jsonl`);
+  writeJsonl(p, entries);
+  tmpFiles.push(p);
+  return p;
+}
+
+afterEach(() => {
+  for (const f of tmpFiles) {
+    if (existsSync(f)) try { unlinkSync(f); } catch { /* ignore */ }
+    // clean up any .bak-* files the repair created next to f
+    try {
+      const dir = f.substring(0, f.lastIndexOf('/'));
+      const name = f.substring(f.lastIndexOf('/') + 1);
+      for (const sibling of readdirSync(dir)) {
+        if (sibling.startsWith(`${name}.bak-`) || sibling.startsWith(`${name}.tmp-`)) {
+          try { unlinkSync(join(dir, sibling)); } catch { /* ignore */ }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  tmpFiles = [];
+});
+
+// ---------- tests ----------
+
+describe('session-repair', () => {
+  describe('parseSessionFile', () => {
+    it('parses a valid JSONL session', () => {
+      const path = tmpJsonl([HEADER, MODEL_CHANGE, userMsg('u1', 'mc-1', 'hi')]);
+      const entries = parseSessionFile(path);
+      expect(entries.length).toBe(3);
+      expect(entries[0].type).toBe('session');
+      expect(entries[2].message).toBeDefined();
+    });
+
+    it('tolerates trailing blank lines', () => {
+      const path = tmpJsonl([HEADER]);
+      writeFileSync(path, JSON.stringify(HEADER) + '\n\n\n');
+      expect(parseSessionFile(path).length).toBe(1);
+    });
+
+    it('throws on malformed JSON with line number', () => {
+      const path = join(tmpdir(), `bad-${Date.now()}.jsonl`);
+      writeFileSync(path, JSON.stringify(HEADER) + '\n{not json\n');
+      tmpFiles.push(path);
+      expect(() => parseSessionFile(path)).toThrow(/line 2/);
+    });
+  });
+
+  describe('inspectSessionFile', () => {
+    it('reports clean session as no orphans', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        assistantToolCall('a1', 'u1', 'call-1'),
+        toolResult('r1', 'a1', 'call-1'),
+      ]);
+      const rep = inspectSessionFile(path);
+      expect(rep.hasOrphans).toBe(false);
+      expect(rep.totalMessages).toBe(3);
+    });
+
+    it('detects orphaned toolCall (no result)', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        assistantToolCall('a1', 'u1', 'call-1'),
+        // no toolResult — simulates crashed mid-tool
+      ]);
+      const rep = inspectSessionFile(path);
+      expect(rep.hasOrphans).toBe(true);
+      expect(rep.orphanedToolCallIds).toEqual(['call-1']);
+      expect(rep.orphanedToolResultIds).toEqual([]);
+    });
+
+    it('detects orphaned toolResult (no matching call)', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        toolResult('r1', 'u1', 'call-ghost'),
+      ]);
+      const rep = inspectSessionFile(path);
+      expect(rep.hasOrphans).toBe(true);
+      expect(rep.orphanedToolResultIds).toEqual(['call-ghost']);
+    });
+  });
+
+  describe('repairSessionFile', () => {
+    it('is a no-op on clean sessions (returns repaired:false, writes no backup)', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        assistantToolCall('a1', 'u1', 'call-1'),
+        toolResult('r1', 'a1', 'call-1'),
+      ]);
+      const rep = repairSessionFile(path);
+      expect(rep.repaired).toBe(false);
+      expect(rep.backupPath).toBeUndefined();
+    });
+
+    it('drops orphaned toolCall-only assistant entry and preserves tree', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        assistantToolCall('a1', 'u1', 'call-1'),  // orphan - no result
+        userMsg('u2', 'a1', 'next question'),      // child of dropped entry
+      ]);
+      const rep = repairSessionFile(path);
+      expect(rep.repaired).toBe(true);
+      expect(rep.droppedEntryIds).toContain('a1');
+      expect(rep.droppedToolCallIds).toEqual(['call-1']);
+      expect(rep.backupPath).toBeDefined();
+
+      // Verify tree reparenting: u2's parentId should now be u1 (not a1)
+      const repaired = parseSessionFile(path);
+      const u2 = repaired.find(e => e.id === 'u2');
+      expect(u2?.parentId).toBe('u1');
+      // a1 gone
+      expect(repaired.find(e => e.id === 'a1')).toBeUndefined();
+    });
+
+    it('drops orphaned toolResult entry only, keeps its siblings', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        toolResult('r-ghost', 'u1', 'call-ghost'),
+        userMsg('u2', 'r-ghost', 'next'),
+      ]);
+      const rep = repairSessionFile(path);
+      expect(rep.repaired).toBe(true);
+      expect(rep.droppedEntryIds).toEqual(['r-ghost']);
+      expect(rep.droppedToolResultIds).toEqual(['call-ghost']);
+
+      const repaired = parseSessionFile(path);
+      const u2 = repaired.find(e => e.id === 'u2');
+      expect(u2?.parentId).toBe('u1'); // reparented
+    });
+
+    it('keeps assistant entry but strips orphan toolCall block when text coexists', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        assistantTextAndToolCall('a1', 'u1', 'call-1', 'thinking out loud'),
+        // no toolResult for call-1 → orphan, but entry has text too, so KEEP entry + strip block
+      ]);
+      const rep = repairSessionFile(path);
+      expect(rep.repaired).toBe(true);
+      expect(rep.droppedEntryIds).not.toContain('a1'); // entry preserved
+      expect(rep.droppedToolCallIds).toEqual(['call-1']);
+
+      const repaired = parseSessionFile(path);
+      const a1 = repaired.find(e => e.id === 'a1');
+      expect(a1).toBeDefined();
+      const content = (a1!.message as { content: Array<{ type: string }> }).content;
+      expect(content.length).toBe(1);
+      expect(content[0].type).toBe('text');
+    });
+
+    it('writes backup file before mutation', () => {
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        assistantToolCall('a1', 'u1', 'call-1'),
+      ]);
+      const before = readFileSync(path, 'utf8');
+      const rep = repairSessionFile(path);
+      expect(rep.backupPath).toBeDefined();
+      expect(existsSync(rep.backupPath!)).toBe(true);
+      expect(readFileSync(rep.backupPath!, 'utf8')).toBe(before);
+    });
+
+    it('throws on missing file', () => {
+      expect(() => repairSessionFile('/nonexistent/path.jsonl')).toThrow(/not found/);
+    });
+  });
+
+  describe('isToolPairingError', () => {
+    it('matches Bedrock tool_use without tool_result', () => {
+      const err = new Error('messages.3: `tool_use` ids were found without `tool_result` blocks immediately after');
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
+    it('matches Anthropic toolUse without toolResult', () => {
+      const err = new Error('toolUse id abc123 without matching toolResult');
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
+    it('matches nested ValidationException', () => {
+      const err = Object.assign(new Error('Request failed with status 400'), {
+        name: 'ValidationException',
+        $metadata: { httpStatusCode: 400 },
+        cause: { message: 'messages.0: unmatched tool_use block' },
+      });
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
+    it('does not match unrelated 400s', () => {
+      const err = new Error('Invalid model ID');
+      expect(isToolPairingError(err)).toBe(false);
+    });
+
+    it('does not match generic messages containing "400" (F5 tightening)', () => {
+      // Before the fix, any message containing "400" triggered a JSON.stringify
+      // deep search. After fix, we require ValidationException name OR
+      // $metadata.httpStatusCode === 400.
+      const err = new Error('queued 400 tasks for retry');
+      expect(isToolPairingError(err)).toBe(false);
+    });
+
+    it('uses $metadata.httpStatusCode to gate deep search (F5)', () => {
+      const err = Object.assign(new Error('Bad request'), {
+        $metadata: { httpStatusCode: 400 },
+        cause: { message: 'tool_use without tool_result in messages.5' },
+      });
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
+    it('handles null/undefined safely', () => {
+      expect(isToolPairingError(null)).toBe(false);
+      expect(isToolPairingError(undefined)).toBe(false);
+    });
+  });
+
+  describe('repairSessionFile — tree edge cases', () => {
+    it('survives a self-parenting cycle when reparenting a kept child (F3)', () => {
+      // Malformed file: orphan assistant entry a1 self-parents (cycle),
+      // AND a kept entry u2 points at a1 — forcing reparentDroppedEntries
+      // to resolve an ancestor through the cycle. Without the visited guard,
+      // this stack-overflows.
+      const entries: object[] = [
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        { ...assistantToolCall('a1', 'a1', 'call-1') }, // self-parent orphan
+        userMsg('u2', 'a1', 'next'), // kept child pointing into the cycle
+      ];
+      const path = tmpJsonl(entries);
+      const rep = repairSessionFile(path);
+      expect(rep.repaired).toBe(true);
+      expect(rep.droppedEntryIds).toContain('a1');
+      // With the cycle, resolveAncestor bails to null — u2 becomes a root.
+      const repaired = parseSessionFile(path);
+      const u2 = repaired.find(e => e.id === 'u2');
+      expect(u2).toBeDefined();
+      expect(u2?.parentId).toBeNull();
+    });
+
+    it('survives a 2-node parentId loop when reparenting a kept child (F3)', () => {
+      // a1 <-> a2 form a cycle, both orphan toolCalls.
+      // u3 is a kept child pointing into the cycle — forces traversal.
+      const a1 = assistantToolCall('a1', 'a2', 'call-1');
+      const a2 = assistantToolCall('a2', 'a1', 'call-2');
+      const path = tmpJsonl([
+        HEADER, MODEL_CHANGE,
+        userMsg('u1', 'mc-1', 'hi'),
+        a1, a2,
+        userMsg('u3', 'a2', 'next'), // kept child into the cycle
+      ]);
+      const rep = repairSessionFile(path);
+      expect(rep.repaired).toBe(true);
+      expect(rep.droppedEntryIds.sort()).toEqual(['a1', 'a2']);
+      // u3 gets reparented to null (cycle bail) rather than crashing.
+      const repaired = parseSessionFile(path);
+      const u3 = repaired.find(e => e.id === 'u3');
+      expect(u3).toBeDefined();
+      expect(u3?.parentId).toBeNull();
+    });
+  });
+});