basalt-ui 1.10.0 → 1.11.0

package/src/agent/parts.test.ts

@@ -1,15 +1,16 @@
 /**
- * parseAgentPart / isStartPart — the runtime narrowing guard over the AgentPart wire format.
+ * parseAgentPart / isStartPart / isToolCallSettled — the runtime narrowing guard over the
+ * AgentPart wire format, post-1.11.0 part identity + the seven-state ToolCallPart union.
  *
- * Scope: the parser AS IT EXISTS TODAY (B1) — no required `id`/`toolCallId`, no `AgentPartDraft`,
- * no seven-state ToolCallPart union; those are 1.10.0 part-identity work landing on top of this
- * currently-untested parser (see the sibling `ai-sdk-transport.test.ts`'s scope note for the same
- * cutoff). Every AgentPart variant below is validated against parts.ts:87's `parseAgentPart` and
- * parts.ts:134's `isStartPart` as they read right now.
+ * Every AgentPart variant below is validated against parts.ts's `parseAgentPart`, `isStartPart`,
+ * and `isToolCallSettled` as they read right now: `id` is required on every variant, and `tool`
+ * parts are validated against the seven-state discriminated union mirroring AI SDK v7's
+ * `UIToolInvocation` (see parts.ts's ToolCallPart doc for the ground-truth corrections against the
+ * design spec).
  */
 import { describe, expect, test } from 'bun:test'
-import { isStartPart, parseAgentPart } from './parts'
-import type { AgentPart } from './parts'
+import { isStartPart, isToolCallSettled, parseAgentPart } from './parts'
+import type { AgentPart, ToolCallPart } from './parts'
 
 /** JSON round-trip a value through JSON.stringify → JSON.parse, mirroring wire transport. */
 function roundTrip(value: unknown): unknown {
@@ -19,13 +20,14 @@ function roundTrip(value: unknown): unknown {
 describe('parseAgentPart', () => {
   describe('start', () => {
     test('parses a minimal start part (no resumeToken)', () => {
-      const raw = { type: 'start', runId: 'run-1' }
-      expect(parseAgentPart(raw)).toEqual({ type: 'start', runId: 'run-1' })
+      const raw = { id: 'p1', type: 'start', runId: 'run-1' }
+      expect(parseAgentPart(raw)).toEqual({ id: 'p1', type: 'start', runId: 'run-1' })
     })
 
     test('parses a start part with resumeToken', () => {
-      const raw = { type: 'start', runId: 'run-1', resumeToken: 'tok-1' }
+      const raw = { id: 'p1', type: 'start', runId: 'run-1', resumeToken: 'tok-1' }
       expect(parseAgentPart(raw)).toEqual({
+        id: 'p1',
         type: 'start',
         runId: 'run-1',
         resumeToken: 'tok-1',
@@ -33,120 +35,397 @@ describe('parseAgentPart', () => {
     })
 
     test('drops a non-string resumeToken rather than passing it through', () => {
-      const raw = { type: 'start', runId: 'run-1', resumeToken: 42 }
-      expect(parseAgentPart(raw)).toEqual({ type: 'start', runId: 'run-1' })
+      const raw = { id: 'p1', type: 'start', runId: 'run-1', resumeToken: 42 }
+      expect(parseAgentPart(raw)).toEqual({ id: 'p1', type: 'start', runId: 'run-1' })
     })
 
     test('rejects a missing runId', () => {
-      expect(parseAgentPart({ type: 'start' })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'start' })).toBeNull()
     })
 
     test('rejects a non-string runId', () => {
-      expect(parseAgentPart({ type: 'start', runId: 42 })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'start', runId: 42 })).toBeNull()
+    })
+
+    test('rejects a missing id', () => {
+      expect(parseAgentPart({ type: 'start', runId: 'run-1' })).toBeNull()
     })
 
     test('round-trips through JSON', () => {
-      const part: AgentPart = { type: 'start', runId: 'run-1', resumeToken: 'tok-1' }
+      const part: AgentPart = { id: 'p1', type: 'start', runId: 'run-1', resumeToken: 'tok-1' }
       expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
   })
 
   describe('text', () => {
     test('parses a text part', () => {
-      expect(parseAgentPart({ type: 'text', text: 'hello' })).toEqual({
+      expect(parseAgentPart({ id: 'p1', type: 'text', text: 'hello' })).toEqual({
+        id: 'p1',
         type: 'text',
         text: 'hello',
       })
     })
 
+    test('parses a text part with offset', () => {
+      const raw = { id: 'p1', type: 'text', text: 'llo', offset: 2 }
+      expect(parseAgentPart(raw)).toEqual({ id: 'p1', type: 'text', text: 'llo', offset: 2 })
+    })
+
     test('rejects a missing text field', () => {
-      expect(parseAgentPart({ type: 'text' })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'text' })).toBeNull()
     })
 
     test('rejects a non-string text field', () => {
-      expect(parseAgentPart({ type: 'text', text: 1 })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'text', text: 1 })).toBeNull()
+    })
+
+    test('rejects a missing id', () => {
+      expect(parseAgentPart({ type: 'text', text: 'hello' })).toBeNull()
     })
 
     test('round-trips through JSON', () => {
-      const part: AgentPart = { type: 'text', text: 'hello' }
+      const part: AgentPart = { id: 'p1', type: 'text', text: 'hello', offset: 0 }
       expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
   })
 
   describe('reasoning', () => {
     test('parses a reasoning part', () => {
-      expect(parseAgentPart({ type: 'reasoning', text: 'thinking...' })).toEqual({
+      expect(parseAgentPart({ id: 'p1', type: 'reasoning', text: 'thinking...' })).toEqual({
+        id: 'p1',
         type: 'reasoning',
         text: 'thinking...',
       })
     })
 
     test('rejects a missing text field', () => {
-      expect(parseAgentPart({ type: 'reasoning' })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'reasoning' })).toBeNull()
     })
 
     test('round-trips through JSON', () => {
-      const part: AgentPart = { type: 'reasoning', text: 'thinking...' }
+      const part: AgentPart = { id: 'p1', type: 'reasoning', text: 'thinking...' }
       expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
   })
 
   describe('tool', () => {
-    test('parses a minimal tool part (input only, no output/toolCallId)', () => {
-      const raw = { type: 'tool', toolName: 'search', input: { q: 'x' } }
-      expect(parseAgentPart(raw)).toEqual({
+    test('rejects a missing toolCallId', () => {
+      const raw = {
+        id: 'p1',
         type: 'tool',
         toolName: 'search',
-        input: { q: 'x' },
-      })
+        state: 'input-available',
+        input: {},
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('rejects a missing toolName', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        state: 'input-available',
+        input: {},
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('rejects a missing state', () => {
+      const raw = { id: 'p1', type: 'tool', toolCallId: 'call-1', toolName: 'search', input: {} }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('rejects an unknown state', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'running',
+        input: {},
+      }
+      expect(parseAgentPart(raw)).toBeNull()
     })
 
-    test('parses a tool part with output and toolCallId', () => {
+    test('rejects the pre-1.11.0 flat shape (no `state` field at all)', () => {
       const raw = {
+        id: 'p1',
         type: 'tool',
         toolName: 'search',
+        toolCallId: 'call-1',
         input: { q: 'x' },
         output: { hits: 3 },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    // ── the seven states ────────────────────────────────────────────────────
+
+    test('input-streaming: parses with no input', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
         toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'input-streaming',
       }
       expect(parseAgentPart(raw)).toEqual({
+        id: 'p1',
         type: 'tool',
+        toolCallId: 'call-1',
         toolName: 'search',
+        state: 'input-streaming',
+      })
+    })
+
+    test('input-streaming: parses with a partial input', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'input-streaming',
         input: { q: 'x' },
-        output: { hits: 3 },
+      }
+      expect(parseAgentPart(raw)).toEqual({
+        id: 'p1',
+        type: 'tool',
         toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'input-streaming',
+        input: { q: 'x' },
       })
     })
 
-    test('rejects a missing toolName', () => {
-      expect(parseAgentPart({ type: 'tool', input: {} })).toBeNull()
+    test('input-available: requires input', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'input-available',
+      }
+      expect(parseAgentPart(raw)).toBeNull()
     })
 
-    test('rejects a non-string toolName', () => {
-      expect(parseAgentPart({ type: 'tool', toolName: 1, input: {} })).toBeNull()
+    test('input-available: round-trips', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'input-available',
+        input: { q: 'x' },
+      }
+      expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
 
-    test('rejects a missing input key entirely (undefined input is a valid value, absent key is not)', () => {
-      expect(parseAgentPart({ type: 'tool', toolName: 'search' })).toBeNull()
+    test('approval-requested: round-trips', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'approval-requested',
+        input: { q: 'x' },
+        approval: { id: 'appr-1' },
+      }
+      expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
 
-    test('accepts an explicit `input: undefined` (the key is present)', () => {
-      const raw = { type: 'tool', toolName: 'search', input: undefined }
-      expect(parseAgentPart(raw)).toEqual({ type: 'tool', toolName: 'search', input: undefined })
+    test('approval-requested: rejects a missing approval', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'approval-requested',
+        input: { q: 'x' },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
     })
 
-    test('drops a non-string toolCallId rather than passing it through', () => {
-      const raw = { type: 'tool', toolName: 'search', input: {}, toolCallId: 7 }
-      expect(parseAgentPart(raw)).toEqual({ type: 'tool', toolName: 'search', input: {} })
+    test('approval-requested: rejects an approval that already carries approved (a verdict, not a pending request)', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'approval-requested',
+        input: { q: 'x' },
+        approval: { id: 'appr-1', approved: true },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
     })
 
-    test('round-trips through JSON', () => {
-      const part: AgentPart = {
+    test('approval-requested: rejects an approval that already carries a reason', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'approval-requested',
+        input: { q: 'x' },
+        approval: { id: 'appr-1', reason: 'too risky' },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('approval-responded: round-trips with approved + reason', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'approval-responded',
+        input: { q: 'x' },
+        approval: { id: 'appr-1', approved: true, reason: 'looks safe' },
+      }
+      expect(parseAgentPart(roundTrip(part))).toEqual(part)
+    })
+
+    test('approval-responded: rejects a non-boolean approved', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'approval-responded',
+        input: { q: 'x' },
+        approval: { id: 'appr-1' },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('output-denied: round-trips (approved: false)', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
         type: 'tool',
+        toolCallId: 'call-1',
         toolName: 'search',
+        state: 'output-denied',
+        input: { q: 'x' },
+        approval: { id: 'appr-1', approved: false, reason: 'too risky' },
+      }
+      expect(parseAgentPart(roundTrip(part))).toEqual(part)
+    })
+
+    test('output-denied: rejects approved !== false', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-denied',
+        input: { q: 'x' },
+        approval: { id: 'appr-1', approved: true },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('output-available: round-trips with output + preliminary', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-available',
         input: { q: 'x' },
         output: { hits: 3 },
+        preliminary: true,
+      }
+      expect(parseAgentPart(roundTrip(part))).toEqual(part)
+    })
+
+    test('output-available: an optional approval carries through', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
+        type: 'tool',
         toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-available',
+        input: { q: 'x' },
+        output: { hits: 3 },
+        approval: { id: 'appr-1', approved: true },
+      }
+      expect(parseAgentPart(roundTrip(part))).toEqual(part)
+    })
+
+    test('output-available: rejects a missing output', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-available',
+        input: { q: 'x' },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('output-available: rejects approval.approved === false (a denial masquerading as output)', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-available',
+        input: { q: 'x' },
+        output: { hits: 3 },
+        approval: { id: 'appr-1', approved: false },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('output-error: uses errorText, not error, and round-trips with rawInput', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-error',
+        errorText: 'boom',
+        rawInput: '{"q": invalid json',
+      }
+      expect(parseAgentPart(roundTrip(part))).toEqual(part)
+    })
+
+    test('output-error: rejects a missing errorText', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-error',
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('output-error: rejects approval.approved === false (a denial masquerading as an error)', () => {
+      const raw = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-error',
+        errorText: 'boom',
+        approval: { id: 'appr-1', approved: false },
+      }
+      expect(parseAgentPart(raw)).toBeNull()
+    })
+
+    test('durationMs and providerExecuted carry through when present', () => {
+      const part: ToolCallPart = {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'output-available',
+        input: { q: 'x' },
+        output: { hits: 3 },
+        durationMs: 42,
+        providerExecuted: true,
       }
       expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
@@ -154,15 +433,17 @@ describe('parseAgentPart', () => {
 
   describe('source', () => {
     test('parses a minimal source part (no title)', () => {
-      expect(parseAgentPart({ type: 'source', url: 'https://example.com' })).toEqual({
+      expect(parseAgentPart({ id: 'p1', type: 'source', url: 'https://example.com' })).toEqual({
+        id: 'p1',
         type: 'source',
         url: 'https://example.com',
       })
     })
 
     test('parses a source part with title', () => {
-      const raw = { type: 'source', url: 'https://example.com', title: 'Example' }
+      const raw = { id: 'p1', type: 'source', url: 'https://example.com', title: 'Example' }
       expect(parseAgentPart(raw)).toEqual({
+        id: 'p1',
         type: 'source',
         url: 'https://example.com',
         title: 'Example',
@@ -170,38 +451,44 @@ describe('parseAgentPart', () => {
     })
 
     test('rejects a missing url', () => {
-      expect(parseAgentPart({ type: 'source' })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'source' })).toBeNull()
     })
 
     test('drops a non-string title rather than passing it through', () => {
-      const raw = { type: 'source', url: 'https://example.com', title: 7 }
-      expect(parseAgentPart(raw)).toEqual({ type: 'source', url: 'https://example.com' })
+      const raw = { id: 'p1', type: 'source', url: 'https://example.com', title: 7 }
+      expect(parseAgentPart(raw)).toEqual({ id: 'p1', type: 'source', url: 'https://example.com' })
     })
 
     test('round-trips through JSON', () => {
-      const part: AgentPart = { type: 'source', url: 'https://example.com', title: 'Example' }
+      const part: AgentPart = {
+        id: 'p1',
+        type: 'source',
+        url: 'https://example.com',
+        title: 'Example',
+      }
       expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
   })
 
   describe('error', () => {
     test('parses an error part', () => {
-      expect(parseAgentPart({ type: 'error', message: 'boom' })).toEqual({
+      expect(parseAgentPart({ id: 'p1', type: 'error', message: 'boom' })).toEqual({
+        id: 'p1',
         type: 'error',
         message: 'boom',
       })
     })
 
     test('rejects a missing message', () => {
-      expect(parseAgentPart({ type: 'error' })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'error' })).toBeNull()
     })
 
     test('rejects a non-string message', () => {
-      expect(parseAgentPart({ type: 'error', message: 500 })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'error', message: 500 })).toBeNull()
     })
 
     test('round-trips through JSON', () => {
-      const part: AgentPart = { type: 'error', message: 'boom' }
+      const part: AgentPart = { id: 'p1', type: 'error', message: 'boom' }
       expect(parseAgentPart(roundTrip(part))).toEqual(part)
     })
   })
@@ -225,26 +512,26 @@ describe('parseAgentPart', () => {
     })
 
     test('rejects an object with no type field', () => {
-      expect(parseAgentPart({ text: 'hello' })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', text: 'hello' })).toBeNull()
     })
 
     test('rejects an object with a non-string type field', () => {
-      expect(parseAgentPart({ type: 1 })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 1 })).toBeNull()
     })
 
     test('rejects an unknown type discriminant', () => {
-      expect(parseAgentPart({ type: 'unknown-variant', text: 'hi' })).toBeNull()
+      expect(parseAgentPart({ id: 'p1', type: 'unknown-variant', text: 'hi' })).toBeNull()
     })
   })
 })
 
 describe('isStartPart', () => {
   test('returns true for a StartPart', () => {
-    expect(isStartPart({ type: 'start', runId: 'run-1' })).toBe(true)
+    expect(isStartPart({ id: 'p1', type: 'start', runId: 'run-1' })).toBe(true)
   })
 
   test('returns false for a non-start AgentPart', () => {
-    expect(isStartPart({ type: 'text', text: 'hi' })).toBe(false)
+    expect(isStartPart({ id: 'p1', type: 'text', text: 'hi' })).toBe(false)
   })
 
   test('returns false for null', () => {
@@ -259,3 +546,58 @@ describe('isStartPart', () => {
     expect(isStartPart({ runId: 'run-1' })).toBe(false)
   })
 })
+
+describe('isToolCallSettled', () => {
+  const base = { id: 'p1', type: 'tool', toolCallId: 'call-1', toolName: 'search' } as const
+
+  test('false for input-streaming', () => {
+    expect(isToolCallSettled({ ...base, state: 'input-streaming' })).toBe(false)
+  })
+
+  test('false for input-available', () => {
+    expect(isToolCallSettled({ ...base, state: 'input-available', input: {} })).toBe(false)
+  })
+
+  test('false for approval-requested', () => {
+    expect(
+      isToolCallSettled({
+        ...base,
+        state: 'approval-requested',
+        input: {},
+        approval: { id: 'appr-1' },
+      }),
+    ).toBe(false)
+  })
+
+  test('false for approval-responded', () => {
+    expect(
+      isToolCallSettled({
+        ...base,
+        state: 'approval-responded',
+        input: {},
+        approval: { id: 'appr-1', approved: true },
+      }),
+    ).toBe(false)
+  })
+
+  test('true for output-available', () => {
+    expect(isToolCallSettled({ ...base, state: 'output-available', input: {}, output: {} })).toBe(
+      true,
+    )
+  })
+
+  test('true for output-error', () => {
+    expect(isToolCallSettled({ ...base, state: 'output-error', errorText: 'boom' })).toBe(true)
+  })
+
+  test('true for output-denied', () => {
+    expect(
+      isToolCallSettled({
+        ...base,
+        state: 'output-denied',
+        input: {},
+        approval: { id: 'appr-1', approved: false },
+      }),
+    ).toBe(true)
+  })
+})