basalt-ui 1.10.0 → 1.12.0

package/src/agent/merge.ts

@@ -0,0 +1,114 @@
+/**
+ * mergePart — identity-addressed accumulator over a part array.
+ *
+ * Appending a part whose `id` is already present in `parts` REWRITES that entry in place rather
+ * than pushing a duplicate — ordering stays stable (a rewritten part keeps its original position).
+ * `text`/`reasoning` splice the incoming delta into the existing text at `next.offset` (an
+ * undefined offset means "append at the tail", and an out-of-range one is clamped rather than
+ * honoured — see `spliceText` for the exact supported shapes); every other variant — including any
+ * `ForeignPart`, which is never text-like — replaces wholesale. A FIRST insertion of a text-like
+ * part goes through the same splice against an empty text, so an offset that claims a prefix this
+ * accumulator never saw is clamped and warned about there too — never honoured, never padded.
+ *
+ * The invariant this holds, and the reason `offset` exists at all: replaying a whole run from
+ * character 0 rebuilds the identical parts array it produced the first time — it cannot double
+ * it. Splicing a full-length delta at offset 0 overwrites the existing text in place (the
+ * trailing slice covers nothing once the incoming text's length matches what's already there),
+ * so a resumed/replayed stream converges instead of duplicating content.
+ *
+ * Constrained on `PartLike` (structural: `id` + `type`), NOT `AgentPart` — a widened, backward-
+ * compatible relaxation so `TranscriptPart` (`AgentPart | ForeignPart`, ./foreign) flows through
+ * the same accumulator a transport-streamed foreign part must pass through on its way from the
+ * transport into `useAgentThreadRuns`'s `runs` map. `AgentPart`'s closed union is untouched —
+ * only the constraint widens, never the union itself.
+ *
+ * @example
+ * let parts: AgentPart[] = []
+ * parts = mergePart(parts, { id: 'p1', type: 'text', text: 'Hel' })
+ * parts = mergePart(parts, { id: 'p1', type: 'text', text: 'lo' }) // splices at the tail
+ * // parts === [{ id: 'p1', type: 'text', text: 'Hello' }]
+ */
+import type { ReasoningPart, TextPart } from './parts'
+
+type TextLike = TextPart | ReasoningPart
+
+/** The structural bound `mergePart` (and the hooks that call it) actually need — an `AgentPart` or
+ * a `ForeignPart` both satisfy it, so this is the widened constraint, not a new closed union. */
+export type PartLike = { readonly id: string; readonly type: string }
+
+// Widened from `AgentPart['type']` to `string`: a plain type-predicate narrowing, so accepting a
+// wider input (any string, including a ForeignPart's) is safe — it still only returns true for the
+// two text-like literals, and a ForeignPart's type string always falls through it to the
+// wholesale-replace path below.
+function isTextLikeType(type: string): type is TextLike['type'] {
+  return type === 'text' || type === 'reasoning'
+}
+
+/**
+ * Splices `next`'s text into `existingText` at `next.offset`. Exactly two shapes are supported,
+ * and they are the only two any basalt transport emits (`diffPart` always sets
+ * `offset = prevText.length`; `diffChunkStream` restarts its accumulator per call):
+ *
+ * 1. **append at the end** — `offset` undefined, or equal to `existingText.length`;
+ * 2. **in-range replace** — `0 <= offset <= existingText.length`, overwriting the span the
+ *    incoming text covers (this is what makes an offset-0 full replay converge instead of double).
+ *
+ * An offset outside that range — negative, past the current length, or non-finite — is **clamped**
+ * into `[0, existingText.length]`, not honoured and not thrown on. A throw here would turn a
+ * transient wire anomaly into a permanently dead transcript; this is stream-reduction code on the
+ * render path. Each clamp is announced in dev.
+ *
+ * A FIRST insertion (no entry with this id yet) runs through here too, against an empty
+ * `existingText`: the stored text is the incoming text either way, but a nonzero offset — the wire
+ * claiming text this accumulator never saw — is clamped to 0 and announced like any other
+ * out-of-range value rather than passing silently. `mergePart` never invents the missing prefix.
+ *
+ * Note what is NOT special-cased: an out-of-order delta whose offset is still in range is an
+ * ordinary in-range replace, so it overwrites whatever already occupies that span. `mergePart`
+ * has no way to tell a stale delta from a deliberate rewrite, and inventing one would break the
+ * offset-0 replay convergence this whole mechanism exists for.
+ */
+function spliceText(existingText: string, next: TextLike): string {
+  const offset = clampOffset(next.offset ?? existingText.length, existingText.length)
+  return existingText.slice(0, offset) + next.text + existingText.slice(offset + next.text.length)
+}
+
+/** Clamps a wire offset into `[0, length]`, warning in dev when the raw value was out of range. */
+function clampOffset(offset: number, length: number): number {
+  // A non-finite offset would make every slice() return '' and blank the part outright — it is
+  // out of range like any other, and appending is the safe reading of "position unknown".
+  const clamped = Number.isFinite(offset) ? Math.min(Math.max(offset, 0), length) : length
+  if (clamped !== offset && process.env['NODE_ENV'] !== 'production') {
+    console.warn(
+      `[basalt] mergePart: text offset ${offset} out of range [0, ${length}] — clamped to ${clamped}`,
+    )
+  }
+  return clamped
+}
+
+export function mergePart<TPart extends PartLike>(parts: readonly TPart[], next: TPart): TPart[] {
+  const index = parts.findIndex((part) => part.id === next.id)
+  const existing = index === -1 ? undefined : (parts[index] as TPart)
+
+  // A first insertion of a text-like part is spliced too — against an empty existing text — so the
+  // offset contract is one path with one set of rules: same clamp, same dev warning, and the same
+  // stored result (`'' + next.text`) an unconditional append would have produced.
+  const spliceable =
+    isTextLikeType(next.type) && (existing === undefined || existing.type === next.type)
+
+  const merged: TPart = spliceable
+    ? ({
+        ...next,
+        text: spliceText(
+          existing === undefined ? '' : (existing as unknown as TextLike).text,
+          next as unknown as TextLike,
+        ),
+      } as TPart)
+    : next
+
+  if (existing === undefined) return [...parts, merged]
+
+  const out = parts.slice()
+  out[index] = merged
+  return out
+}

package/src/agent/part-list.test.tsx

@@ -0,0 +1,112 @@
+/**
+ * PartList's headless default tool-call renderer — a failed/denied call must stay visible.
+ *
+ * Regression coverage: after the seven-state ToolCallPart split, `output-error` carries no
+ * `output` field, so the old `part.state === 'output-available'`-only body left a failed call
+ * rendering as name+input and nothing else — the failure was silently invisible. Same gap for
+ * `output-denied`, indistinguishable from a still-pending call.
+ *
+ * Plus the `settled` flag's forwarding contract — the field that lets a text renderer drop out of
+ * streaming mode once the message it belongs to has finished.
+ */
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, test } from 'bun:test'
+import { PartList } from './part-list'
+import type { AgentPart, ToolCallPart } from './parts'
+
+afterEach(cleanup)
+
+const BASE = { id: 'p1', type: 'tool' as const, toolCallId: 'c1', toolName: 'search' }
+
+describe('DefaultToolCall — terminal states stay visible', () => {
+  test('output-error renders the errorText', () => {
+    const part: ToolCallPart = { ...BASE, state: 'output-error', errorText: 'boom' }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText('boom')).not.toBeNull()
+  })
+
+  test('output-error with no validated input falls back to rendering rawInput', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-error',
+      errorText: 'boom',
+      rawInput: { q: 'x' },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText(/"q": "x"/)).not.toBeNull()
+  })
+
+  test('output-error with validated input present does not also render rawInput', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-error',
+      errorText: 'boom',
+      input: { q: 'x' },
+      rawInput: { q: 'stale' },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.queryByText(/stale/)).toBeNull()
+  })
+
+  test('output-denied is visibly denied, not indistinguishable from a pending call', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-denied',
+      input: { q: 'x' },
+      approval: { id: 'a1', approved: false, reason: 'too risky' },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText(/Denied/)).not.toBeNull()
+    expect(screen.getByText(/too risky/)).not.toBeNull()
+  })
+
+  test('output-denied with no reason still renders a visible denial', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-denied',
+      input: { q: 'x' },
+      approval: { id: 'a1', approved: false },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText('Denied')).not.toBeNull()
+  })
+
+  test('output-available is unaffected — still renders output, no error/denied line', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-available',
+      input: { q: 'x' },
+      output: { hits: 3 },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText(/"hits": 3/)).not.toBeNull()
+    expect(screen.queryByText(/Denied/)).toBeNull()
+  })
+})
+
+describe('settled — forwarded to every renderer', () => {
+  const TEXT: AgentPart = { id: 't1', type: 'text', text: 'hello' }
+
+  function settledProbe() {
+    const seen: boolean[] = []
+    const components = {
+      text: ({ settled }: { settled: boolean }) => {
+        seen.push(settled)
+        return <div data-testid="probe">{String(settled)}</div>
+      },
+    }
+    return { seen, components }
+  }
+
+  test('defaults to true — a caller that knows nothing about a run renders a finished list', () => {
+    const { seen, components } = settledProbe()
+    render(<PartList parts={[TEXT]} components={components} />)
+    expect(seen).toEqual([true])
+  })
+
+  test('an explicit settled={false} reaches the renderer', () => {
+    const { seen, components } = settledProbe()
+    render(<PartList parts={[TEXT]} components={components} settled={false} />)
+    expect(seen).toEqual([false])
+  })
+})

package/src/agent/part-list.tsx

@@ -19,7 +19,9 @@
  * <PartList
  *   parts={parts}
  *   components={{
- *     text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown>,
+ *     text: ({ part, settled }) => (
+ *       <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *     ),
  *   }}
  * />
  */
@@ -38,37 +40,48 @@ import type {
 
 // ── Per-type renderer signatures ──────────────────────────────────────────────
 
-export type TextPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'text' }>
+/**
+ * The per-renderer argument. `settled` is `false` only while the message these parts belong to is
+ * still streaming — it converges this map toward the `PartRenderContext` a foreign renderer
+ * already receives (`./foreign`), rather than adding a third shape. Additive and
+ * source-compatible: an existing `({ part }) => …` renderer simply ignores it.
+ *
+ * Settlement is MONOTONE — a message that has settled never un-settles.
+ */
+type PartRenderArgs<TPart> = {
+  part: TPart
   index: number
-}) => JSX.Element | null
+  settled: boolean
+}
 
-export type ReasoningPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'reasoning' }>
-  index: number
-}) => JSX.Element | null
+export type TextPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'text' }>>,
+) => JSX.Element | null
 
-export type ToolCallPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'tool' }>
-  index: number
-}) => JSX.Element | null
+export type ReasoningPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'reasoning' }>>,
+) => JSX.Element | null
 
-export type SourcePartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'source' }>
-  index: number
-}) => JSX.Element | null
+export type ToolCallPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'tool' }>>,
+) => JSX.Element | null
 
-export type ErrorPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'error' }>
-  index: number
-}) => JSX.Element | null
+export type SourcePartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'source' }>>,
+) => JSX.Element | null
+
+export type ErrorPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'error' }>>,
+) => JSX.Element | null
 
 /**
  * Partial map of per-type renderers. Any omitted key falls back to the headless default.
  *
  * @example
  * const renderers: Partial<AgentPartRenderers> = {
- *   text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown>,
+ *   text: ({ part, settled }) => (
+ *     <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *   ),
  * }
  */
 export type AgentPartRenderers<TPart extends AgentPart = AgentPart> = {
@@ -112,6 +125,12 @@ const CODE_BLOCK_STYLE = {
   overflowX: 'auto',
 } as const
 
+/** Terminal-state status line (tool-call error/denial) — plain text, no code-block chrome. */
+const STATUS_LINE_STYLE = {
+  marginTop: 'var(--vx-space-agent-part-gap-top)',
+  color: VX.status.bad,
+} as const
+
 function DefaultText({ part }: { part: TextPart; index: number }): JSX.Element {
   return (
     <div
@@ -151,11 +170,30 @@ function DefaultToolCall({ part }: { part: ToolCallPart; index: number }): JSX.E
       <pre className="basalt-agent-tool-input" style={CODE_BLOCK_STYLE}>
         {JSON.stringify(part.input, null, 2)}
       </pre>
-      {part.output !== undefined && (
+      {/* output-error's input never validated — rawInput is the only surviving record of what was
+          actually sent, so show it whenever there is no validated input to show instead. */}
+      {part.state === 'output-error' && part.input === undefined && part.rawInput !== undefined && (
+        <pre className="basalt-agent-tool-raw-input" style={CODE_BLOCK_STYLE}>
+          {JSON.stringify(part.rawInput, null, 2)}
+        </pre>
+      )}
+      {part.state === 'output-available' && (
         <pre className="basalt-agent-tool-output" style={CODE_BLOCK_STYLE}>
           {JSON.stringify(part.output, null, 2)}
         </pre>
       )}
+      {/* A failed or denied call must stay visible after the seven-state split — neither carries
+          an `output`, so without this the call renders as name+input and nothing else. */}
+      {part.state === 'output-error' && (
+        <div className="basalt-agent-tool-error" role="alert" style={STATUS_LINE_STYLE}>
+          {part.errorText}
+        </div>
+      )}
+      {part.state === 'output-denied' && (
+        <div className="basalt-agent-tool-denied" style={STATUS_LINE_STYLE}>
+          Denied{part.approval.reason !== undefined ? `: ${part.approval.reason}` : ''}
+        </div>
+      )}
     </div>
   )
 }
@@ -206,10 +244,17 @@ export type PartListProps<TPart extends AgentPart = AgentPart> = {
   readonly parts: TPart[]
   /**
    * Override individual part renderers. Omitted keys fall back to the headless defaults.
-   * Pass `{ text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown> }` to
-   * enable rich markdown rendering.
+   * Pass `{ text: ({ part, settled }) => <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown> }`
+   * to enable rich markdown rendering.
    */
   readonly components?: Partial<AgentPartRenderers<TPart>>
+  /**
+   * `false` while the message these parts belong to is still streaming — forwarded to every
+   * renderer so a text renderer can drop out of streaming mode (and a fenced mermaid/diagram can
+   * upgrade) once the turn finishes. Defaults to `true`: a caller that knows nothing about a run
+   * is rendering a finished list, and un-settled must be opted into by the thing that does know.
+   */
+  readonly settled?: boolean
 }
 
 /**
@@ -226,11 +271,19 @@ export type PartListProps<TPart extends AgentPart = AgentPart> = {
  * // With basalt's own Markdown for the text renderer:
  * import { PartList } from 'basalt-ui/agent'
  * import { Markdown } from 'basalt-ui/content'
- * <PartList parts={parts} components={{ text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown> }} />
+ * <PartList
+ *   parts={parts}
+ *   components={{
+ *     text: ({ part, settled }) => (
+ *       <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *     ),
+ *   }}
+ * />
  */
 export function PartList<TPart extends AgentPart = AgentPart>({
   parts,
   components,
+  settled = true,
 }: PartListProps<TPart>): JSX.Element {
   // Memoised to avoid rebuilding the renderer map on every streaming re-render (hot path).
   // Cast required because DEFAULT_RENDERERS is typed for the base AgentPart, not the generic TPart.
@@ -251,40 +304,60 @@ export function PartList<TPart extends AgentPart = AgentPart>({
           case 'text': {
             const Render = renderers.text
             return (
-              <Fragment key={index}>
-                <Render part={part as Extract<TPart, { type: 'text' }>} index={index} />
+              <Fragment key={part.id}>
+                <Render
+                  part={part as Extract<TPart, { type: 'text' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
           case 'reasoning': {
             const Render = renderers.reasoning
             return (
-              <Fragment key={index}>
-                <Render part={part as Extract<TPart, { type: 'reasoning' }>} index={index} />
+              <Fragment key={part.id}>
+                <Render
+                  part={part as Extract<TPart, { type: 'reasoning' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
           case 'tool': {
             const Render = renderers.tool
             return (
-              <Fragment key={index}>
-                <Render part={part as Extract<TPart, { type: 'tool' }>} index={index} />
+              <Fragment key={part.id}>
+                <Render
+                  part={part as Extract<TPart, { type: 'tool' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
           case 'source': {
             const Render = renderers.source
             return (
-              <Fragment key={index}>
-                <Render part={part as Extract<TPart, { type: 'source' }>} index={index} />
+              <Fragment key={part.id}>
+                <Render
+                  part={part as Extract<TPart, { type: 'source' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
           case 'error': {
             const Render = renderers.error
             return (
-              <Fragment key={index}>
-                <Render part={part as Extract<TPart, { type: 'error' }>} index={index} />
+              <Fragment key={part.id}>
+                <Render
+                  part={part as Extract<TPart, { type: 'error' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }