@tangle-network/starter-foundry 0.7.2 → 0.13.0

package/registry/families/agent-debug-ui-ts/files/src/components/ChatPair.tsx

@@ -0,0 +1,69 @@
+import { useMemo } from 'react'
+import type { NormalizedEvent } from '../lib/event-types'
+
+interface ChatPairProps {
+  userPrompt: string
+  events: NormalizedEvent[]
+  // When false, hide the streaming spinner (used during replay).
+  isStreaming: boolean
+}
+
+interface AccumulatedText {
+  text: string
+  reasoning: string
+  finalText?: string
+}
+
+// Walks the event log and reconstructs the assistant response state at the
+// far end of the buffer. Streaming `delta`s are already accumulated in
+// part.text by sandbox-stream's normalizer, so we just take the latest
+// snapshot per part type.
+export function accumulateAssistantText(events: NormalizedEvent[]): AccumulatedText {
+  let text = ''
+  let reasoning = ''
+  let finalText: string | undefined
+  for (const evt of events) {
+    const e = evt.event
+    if (e.type === 'message.part.updated') {
+      const data = e.data as { part: { type: string; text: string } }
+      if (data.part.type === 'text') text = data.part.text
+      else if (data.part.type === 'reasoning') reasoning = data.part.text
+    } else if (e.type === 'result') {
+      const data = e.data as { finalText?: string }
+      if (data.finalText) finalText = data.finalText
+    }
+  }
+  return { text, reasoning, finalText }
+}
+
+export function ChatPair({ userPrompt, events, isStreaming }: ChatPairProps) {
+  const acc = useMemo(() => accumulateAssistantText(events), [events])
+  const displayText = acc.finalText ?? acc.text
+
+  return (
+    <div className='chat-pair'>
+      <article className='chat-pair__msg chat-pair__msg--user'>
+        <header>You</header>
+        <pre>{userPrompt || '(no prompt yet)'}</pre>
+      </article>
+      <article className='chat-pair__msg chat-pair__msg--assistant'>
+        <header>
+          Agent
+          {isStreaming ? (
+            <span className='chat-pair__streaming'> streaming…</span>
+          ) : null}
+          {acc.finalText ? (
+            <span className='chat-pair__locked'> final</span>
+          ) : null}
+        </header>
+        {acc.reasoning ? (
+          <details className='chat-pair__reasoning'>
+            <summary>reasoning ({acc.reasoning.length} chars)</summary>
+            <pre>{acc.reasoning}</pre>
+          </details>
+        ) : null}
+        <pre>{displayText || (isStreaming ? '…' : '(no response yet)')}</pre>
+      </article>
+    </div>
+  )
+}

package/registry/families/agent-debug-ui-ts/files/src/components/EventInspector.tsx

@@ -0,0 +1,36 @@
+import type { NormalizedEvent } from '../lib/event-types'
+
+interface EventInspectorProps {
+  event?: NormalizedEvent
+}
+
+export function EventInspector({ event }: EventInspectorProps) {
+  if (!event) {
+    return (
+      <div className='event-inspector event-inspector--empty'>
+        <p>Click an event or tool call to inspect its full payload.</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className='event-inspector'>
+      <header className='event-inspector__header'>
+        <span>Event #{event.eventIdx}</span>
+        <span className='event-inspector__type'>{event.event.type}</span>
+        <span className='event-inspector__elapsed'>+{event.elapsedMs}ms</span>
+      </header>
+      <pre className='event-inspector__json'>
+        {JSON.stringify(event.event, jsonReplacer, 2)}
+      </pre>
+    </div>
+  )
+}
+
+// Truncate huge text bodies so a 200-KB tool result doesn't blow up the DOM.
+function jsonReplacer(_key: string, value: unknown): unknown {
+  if (typeof value === 'string' && value.length > 4000) {
+    return `${value.slice(0, 4000)}… [truncated ${value.length - 4000} chars]`
+  }
+  return value
+}

package/registry/families/agent-debug-ui-ts/files/src/components/EventStream.tsx

@@ -0,0 +1,122 @@
+import { useEffect, useRef } from 'react'
+import type { NormalizedEvent } from '../lib/event-types'
+
+interface EventStreamProps {
+  events: NormalizedEvent[]
+  // Bound the rendered window — agent runs can emit thousands of events.
+  // Fits the "~50 most recent" requirement and keeps DOM cheap.
+  windowSize?: number
+  selectedIdx?: number
+  onSelect?: (idx: number) => void
+  autoScroll?: boolean
+}
+
+const TYPE_COLORS: Record<string, string> = {
+  'message.part.updated': '#7dd3fc', // sky-300
+  status: '#fcd34d', // amber-300
+  'model-processing': '#c4b5fd', // violet-300
+  result: '#86efac', // green-300
+  'trace.id': '#94a3b8', // slate-400
+  error: '#fca5a5', // red-300
+}
+
+function formatElapsed(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  return `${(ms / 1000).toFixed(2)}s`
+}
+
+function summarizeEvent(evt: NormalizedEvent): string {
+  const e = evt.event
+  switch (e.type) {
+    case 'message.part.updated': {
+      const data = e.data as { part: { type: string; text: string } }
+      const preview = data.part.text.slice(-60).replace(/\s+/g, ' ')
+      return `${data.part.type} • "${preview}"`
+    }
+    case 'status': {
+      const data = e.data as { status: string; detail?: string }
+      return data.detail ? `${data.status} — ${data.detail}` : data.status
+    }
+    case 'model-processing': {
+      const data = e.data as { phase: string; elapsedMs?: number }
+      return data.elapsedMs !== undefined
+        ? `${data.phase} (${formatElapsed(data.elapsedMs)})`
+        : data.phase
+    }
+    case 'result': {
+      const data = e.data as { tokenUsage?: { inputTokens: number; outputTokens: number } }
+      if (!data.tokenUsage) return 'result'
+      return `result • in=${data.tokenUsage.inputTokens} out=${data.tokenUsage.outputTokens}`
+    }
+    case 'trace.id': {
+      const data = e.data as { traceId: string }
+      return data.traceId
+    }
+    case 'error': {
+      const data = e.data as { message: string }
+      return data.message
+    }
+    default:
+      return JSON.stringify(e.data ?? {}).slice(0, 80)
+  }
+}
+
+export function EventStream({
+  events,
+  windowSize = 50,
+  selectedIdx,
+  onSelect,
+  autoScroll = true,
+}: EventStreamProps) {
+  const tailRef = useRef<HTMLDivElement | null>(null)
+  const visible = events.slice(-windowSize)
+
+  useEffect(() => {
+    if (!autoScroll) return
+    tailRef.current?.scrollIntoView({ behavior: 'smooth', block: 'end' })
+  }, [events.length, autoScroll])
+
+  if (events.length === 0) {
+    return (
+      <div className='event-stream event-stream--empty'>
+        <p>No events yet. Send a prompt to start a run.</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className='event-stream'>
+      <header className='event-stream__header'>
+        <span>Events ({events.length})</span>
+        {events.length > windowSize ? (
+          <span className='event-stream__overflow'>
+            showing last {windowSize}
+          </span>
+        ) : null}
+      </header>
+      <ol className='event-stream__list'>
+        {visible.map((evt) => {
+          const isSelected = evt.eventIdx === selectedIdx
+          const color = TYPE_COLORS[evt.event.type] ?? '#cbd5e1'
+          return (
+            <li
+              key={evt.eventIdx}
+              className={
+                'event-stream__row' + (isSelected ? ' event-stream__row--selected' : '')
+              }
+              onClick={() => onSelect?.(evt.eventIdx)}
+            >
+              <span className='event-stream__idx'>#{evt.eventIdx}</span>
+              <span className='event-stream__elapsed'>{formatElapsed(evt.elapsedMs)}</span>
+              <span className='event-stream__type' style={{ color }}>
+                {evt.event.type}
+              </span>
+              <span className='event-stream__summary'>{summarizeEvent(evt)}</span>
+            </li>
+          )
+        })}
+        <div ref={tailRef} />
+      </ol>
+    </div>
+  )
+}

package/registry/families/agent-debug-ui-ts/files/src/components/ReplayScrubber.tsx

@@ -0,0 +1,59 @@
+import type { NormalizedEvent } from '../lib/event-types'
+
+interface ReplayScrubberProps {
+  events: NormalizedEvent[]
+  // 1-based count of events to show. Range: [0, events.length].
+  // 0 = nothing yet, events.length = full run.
+  cursor: number
+  onCursorChange: (cursor: number) => void
+  isLive: boolean
+  onToggleLive: () => void
+}
+
+export function ReplayScrubber({
+  events,
+  cursor,
+  onCursorChange,
+  isLive,
+  onToggleLive,
+}: ReplayScrubberProps) {
+  const max = events.length
+  const totalElapsedMs = max > 0 ? events[max - 1]!.elapsedMs : 0
+  const cursorElapsed =
+    cursor === 0 ? 0 : events[Math.min(cursor, max) - 1]?.elapsedMs ?? 0
+
+  return (
+    <div className='replay-scrubber'>
+      <button
+        type='button'
+        className={
+          'replay-scrubber__btn' +
+          (isLive ? ' replay-scrubber__btn--live' : '')
+        }
+        onClick={onToggleLive}
+        disabled={max === 0}
+      >
+        {isLive ? '▶ Live' : '⏸ Replay'}
+      </button>
+      <input
+        className='replay-scrubber__range'
+        type='range'
+        min={0}
+        max={max}
+        step={1}
+        value={Math.min(cursor, max)}
+        disabled={max === 0}
+        onChange={(e) => {
+          const next = Number(e.target.value)
+          // Switching off live the moment the user scrubs — otherwise
+          // incoming events would yank the cursor away.
+          if (isLive) onToggleLive()
+          onCursorChange(next)
+        }}
+      />
+      <span className='replay-scrubber__readout'>
+        {cursor}/{max} events · {cursorElapsed}ms / {totalElapsedMs}ms
+      </span>
+    </div>
+  )
+}

package/registry/families/agent-debug-ui-ts/files/src/components/ToolCallTimeline.tsx

@@ -0,0 +1,136 @@
+import { useMemo } from 'react'
+import type { MessagePart, NormalizedEvent } from '../lib/event-types'
+import { extractToolPart } from '../lib/event-types'
+
+interface ToolCallTimelineProps {
+  events: NormalizedEvent[]
+  selectedToolCallId?: string
+  onSelect?: (toolCallId: string, eventIdx: number) => void
+}
+
+interface ToolCallSpan {
+  toolCallId: string
+  toolName: string
+  firstSeenIdx: number
+  firstSeenAt: number
+  lastSeenAt: number
+  state: MessagePart['state']
+  args: unknown
+  result: unknown
+}
+
+// Walk the event log, fold every tool part by toolCallId. Each span
+// captures its first/last appearance + final state — exactly what you
+// want for a horizontal duration bar.
+export function aggregateToolCalls(events: NormalizedEvent[]): ToolCallSpan[] {
+  const byId = new Map<string, ToolCallSpan>()
+  // Synthetic id counter for tool parts that arrive without a toolCallId
+  // — rare, but we still want to surface them rather than collapse them
+  // all under a single "anon" key.
+  let anonCounter = 0
+  for (const evt of events) {
+    const part = extractToolPart(evt.event)
+    if (!part) continue
+    const id = part.toolCallId ?? `anon:${anonCounter++}`
+    const existing = byId.get(id)
+    if (!existing) {
+      byId.set(id, {
+        toolCallId: id,
+        toolName: part.toolName ?? '<unknown-tool>',
+        firstSeenIdx: evt.eventIdx,
+        firstSeenAt: evt.receivedAt,
+        lastSeenAt: evt.receivedAt,
+        state: part.state ?? 'pending',
+        args: part.args,
+        result: part.result,
+      })
+    } else {
+      existing.lastSeenAt = evt.receivedAt
+      // Latest update wins — args are usually fixed but tool runtimes can
+      // re-emit refined argument shapes.
+      if (part.toolName) existing.toolName = part.toolName
+      if (part.state) existing.state = part.state
+      if (part.args !== undefined) existing.args = part.args
+      if (part.result !== undefined) existing.result = part.result
+    }
+  }
+  return [...byId.values()].sort((a, b) => a.firstSeenIdx - b.firstSeenIdx)
+}
+
+const STATE_COLORS: Record<NonNullable<MessagePart['state']>, string> = {
+  pending: '#94a3b8',
+  running: '#7dd3fc',
+  completed: '#86efac',
+  failed: '#fca5a5',
+}
+
+export function ToolCallTimeline({
+  events,
+  selectedToolCallId,
+  onSelect,
+}: ToolCallTimelineProps) {
+  const spans = useMemo(() => aggregateToolCalls(events), [events])
+  const totalSpan = useMemo(() => {
+    if (spans.length === 0) return 0
+    const min = spans[0]!.firstSeenAt
+    const max = Math.max(...spans.map((s) => s.lastSeenAt))
+    return Math.max(1, max - min)
+  }, [spans])
+  const origin = spans[0]?.firstSeenAt ?? 0
+
+  if (spans.length === 0) {
+    return (
+      <div className='tool-timeline tool-timeline--empty'>
+        <p>No tool calls yet.</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className='tool-timeline'>
+      <header className='tool-timeline__header'>
+        Tool calls ({spans.length})
+      </header>
+      <ol className='tool-timeline__list'>
+        {spans.map((span) => {
+          const offsetPct = ((span.firstSeenAt - origin) / totalSpan) * 100
+          const widthPct = Math.max(
+            2,
+            ((span.lastSeenAt - span.firstSeenAt) / totalSpan) * 100,
+          )
+          const color = STATE_COLORS[span.state ?? 'pending']
+          const isSelected = span.toolCallId === selectedToolCallId
+          const durationMs = span.lastSeenAt - span.firstSeenAt
+          return (
+            <li
+              key={span.toolCallId}
+              className={
+                'tool-timeline__row' +
+                (isSelected ? ' tool-timeline__row--selected' : '')
+              }
+              onClick={() => onSelect?.(span.toolCallId, span.firstSeenIdx)}
+            >
+              <div className='tool-timeline__label'>
+                <strong>{span.toolName}</strong>
+                <span className='tool-timeline__state' style={{ color }}>
+                  {span.state ?? 'pending'}
+                </span>
+                <span className='tool-timeline__duration'>{durationMs}ms</span>
+              </div>
+              <div className='tool-timeline__track'>
+                <div
+                  className='tool-timeline__bar'
+                  style={{
+                    left: `${offsetPct}%`,
+                    width: `${widthPct}%`,
+                    background: color,
+                  }}
+                />
+              </div>
+            </li>
+          )
+        })}
+      </ol>
+    </div>
+  )
+}

package/registry/families/agent-debug-ui-ts/files/src/lib/event-types.ts

@@ -0,0 +1,115 @@
+// SSE event contract from @tangle-network/sandbox `streamPrompt()`.
+// Source of truth: products/sandbox/sdk/INTEGRATION.md "SSE Event Contract" table
+// + products/sandbox/sdk/src/sandbox.ts streamPrompt() implementation.
+//
+// We reproduce the public shape locally rather than re-export the SDK's
+// `SandboxEvent` because:
+//   1. The SDK's union is wider (includes internal `execution.started`,
+//      `done`, replay markers) than what UI consumers should react to.
+//   2. We need a discriminated narrow that React components can switch on.
+//   3. Keeps the debugger usable against any adapter that speaks the
+//      documented contract — not just the canonical SDK.
+
+export type PartType = 'text' | 'reasoning' | 'tool'
+
+export interface MessagePart {
+  type: PartType
+  text: string
+  // Tool parts carry structured execution state on top of the text body.
+  // Keep loose — different runtimes attach different metadata shapes.
+  toolName?: string
+  toolCallId?: string
+  args?: unknown
+  result?: unknown
+  state?: 'pending' | 'running' | 'completed' | 'failed'
+}
+
+export type SandboxEvent =
+  | {
+      type: 'message.part.updated'
+      data: {
+        part: MessagePart
+        // When `delta` is present, append to the existing part text.
+        // When absent, `part.text` is the cumulative value.
+        delta?: string
+      }
+    }
+  | {
+      type: 'status'
+      data: {
+        // Documented values: 'generating_response' | 'processing' | 'completed' | 'failed'
+        // — kept open as `string` so adapters can extend.
+        status: string
+        detail?: string
+      }
+    }
+  | {
+      type: 'model-processing'
+      data: {
+        // Documented phases: 'thinking' | 'generating' | 'tool-result'
+        phase: string
+        elapsedMs?: number
+      }
+    }
+  | {
+      type: 'result'
+      data: {
+        finalText?: string
+        tokenUsage?: {
+          inputTokens: number
+          outputTokens: number
+          reasoningTokens?: number
+        }
+      }
+    }
+  | { type: 'trace.id'; data: { traceId: string } }
+  | { type: 'error'; data: { message: string } }
+
+// Anything the SDK yields that we don't model explicitly (execution.started,
+// done, custom adapter events) flows through here so the debugger can still
+// surface it in the raw event stream view.
+export interface UnknownSandboxEvent {
+  type: string
+  data?: unknown
+}
+
+export type AnySandboxEvent = SandboxEvent | UnknownSandboxEvent
+
+// A NormalizedEvent is what UI components consume — adds wall-clock + index
+// + pre-accumulated part text so React doesn't re-derive on every render.
+export interface NormalizedEvent {
+  // 0-based monotonic index in the run.
+  eventIdx: number
+  // Wall-clock ms since epoch when the SSE frame was received.
+  receivedAt: number
+  // Elapsed ms since the first event in this run.
+  elapsedMs: number
+  // The raw event payload, narrowed where we recognise the type.
+  event: AnySandboxEvent
+}
+
+export function isKnownSandboxEvent(
+  event: AnySandboxEvent,
+): event is SandboxEvent {
+  switch (event.type) {
+    case 'message.part.updated':
+    case 'status':
+    case 'model-processing':
+    case 'result':
+    case 'trace.id':
+    case 'error':
+      return true
+    default:
+      return false
+  }
+}
+
+// Pulls a tool part out of a message.part.updated event, if applicable.
+export function extractToolPart(
+  event: AnySandboxEvent,
+): MessagePart | undefined {
+  if (event.type !== 'message.part.updated') return undefined
+  const data = (event as Extract<SandboxEvent, { type: 'message.part.updated' }>).data
+  if (data.part.type !== 'tool') return undefined
+  return data.part
+}

package/registry/families/agent-debug-ui-ts/files/src/lib/sandbox-stream.ts

@@ -0,0 +1,133 @@
+// Wraps `Sandbox.streamPrompt()` into a normalized AsyncIterable that:
+//   1. Adds a wall-clock timestamp + monotonic index to every event.
+//   2. Pre-accumulates streaming `delta`s into part text so consumers
+//      never have to track per-part state themselves.
+//   3. Surfaces unknown event types unchanged so the debugger never
+//      silently drops frames it doesn't recognise.
+//
+// Consumers iterate with `for await (const evt of streamRun(...))`.
+
+import { connectSandbox, type Sandbox } from '@tangle-network/sandbox'
+import {
+  type AnySandboxEvent,
+  type MessagePart,
+  type NormalizedEvent,
+  type SandboxEvent,
+} from './event-types'
+
+export interface StreamRunArgs {
+  baseUrl: string
+  apiKey: string
+  sandboxId: string
+  prompt: string
+  signal?: AbortSignal
+  // Optional — pass through to streamPrompt's PromptOptions.
+  sessionId?: string
+}
+
+// Internal: per-run accumulator for streaming text parts. Keyed by
+// (toolCallId | partType + index) — we use the part's own identity when
+// available, falling back to type+ordinal so concurrent text parts don't
+// collide. The SDK's actual key strategy is opaque, so we reconstruct.
+type PartKey = string
+
+function partKey(part: MessagePart, fallbackIdx: number): PartKey {
+  if (part.toolCallId) return `tool:${part.toolCallId}`
+  return `${part.type}:${fallbackIdx}`
+}
+
+export async function* streamRun(
+  args: StreamRunArgs,
+): AsyncIterable<NormalizedEvent> {
+  const sandbox: Sandbox = await connectSandbox({
+    baseUrl: args.baseUrl,
+    apiKey: args.apiKey,
+    id: args.sandboxId,
+  })
+
+  yield* normalizeEventStream(
+    sandbox.streamPrompt(args.prompt, {
+      signal: args.signal,
+      sessionId: args.sessionId,
+    }),
+  )
+}
+
+// Exposed separately so tests + alternative transports (replay from disk,
+// websocket bridges, mock streams) can normalize without a real Sandbox.
+export async function* normalizeEventStream(
+  raw: AsyncIterable<AnySandboxEvent>,
+): AsyncIterable<NormalizedEvent> {
+  let eventIdx = 0
+  let firstAt: number | undefined
+  const partAccum = new Map<PartKey, MessagePart>()
+  let textPartCount = 0
+  let reasoningPartCount = 0
+
+  for await (const event of raw) {
+    const receivedAt = Date.now()
+    if (firstAt === undefined) firstAt = receivedAt
+
+    let normalized: AnySandboxEvent = event
+
+    if (event.type === 'message.part.updated') {
+      const data = (event as Extract<SandboxEvent, { type: 'message.part.updated' }>).data
+      const incoming = data.part
+      const fallbackIdx =
+        incoming.type === 'text'
+          ? textPartCount
+          : incoming.type === 'reasoning'
+            ? reasoningPartCount
+            : 0
+      const key = partKey(incoming, fallbackIdx)
+      const prior = partAccum.get(key)
+
+      // First time we see this part: register it and bump the per-type
+      // ordinal so subsequent same-type parts don't collide.
+      if (!prior) {
+        if (incoming.type === 'text') textPartCount++
+        else if (incoming.type === 'reasoning') reasoningPartCount++
+      }
+
+      const accumulatedText =
+        data.delta !== undefined
+          ? (prior?.text ?? '') + data.delta
+          : incoming.text
+
+      const merged: MessagePart = {
+        ...incoming,
+        text: accumulatedText,
+      }
+      partAccum.set(key, merged)
+
+      normalized = {
+        type: 'message.part.updated',
+        data: {
+          part: merged,
+          // `delta` preserved so consumers can distinguish "fresh chunk" vs
+          // "snapshot" if they care; the part.text is already cumulative.
+          ...(data.delta !== undefined ? { delta: data.delta } : {}),
+        },
+      }
+    }
+
+    yield {
+      eventIdx,
+      receivedAt,
+      elapsedMs: receivedAt - firstAt,
+      event: normalized,
+    }
+
+    eventIdx++
+  }
+}
+
+// Helper: collect a finished run into an array. Useful for tests + the
+// step-through replay scrubber, which needs random access to the buffer.
+export async function collectRun(
+  iter: AsyncIterable<NormalizedEvent>,
+): Promise<NormalizedEvent[]> {
+  const out: NormalizedEvent[] = []
+  for await (const evt of iter) out.push(evt)
+  return out
+}

package/registry/families/agent-debug-ui-ts/files/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { App } from './App'
+import './styles.css'
+
+const container = document.getElementById('root')
+if (!container) throw new Error('#root mount point missing from index.html')
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)