Render standalone entity stream errors (#4547)

## Summary
- include standalone entity stream errors in the main timeline query
- render errors with their error code and message in the timeline UI
- keep existing run-attached error/fallback rendering unchanged

## Verification
- pnpm --dir packages/agents-server-ui typecheck
- pnpm --dir packages/agents-runtime test entity-timeline --run

Note: full packages/agents-runtime typecheck still fails on existing
unrelated missing exports in test/pg-sync-source.test.ts.

Author: KyleAMathews

.changeset/render-standalone-entity-errors.md

@@ -0,0 +1,6 @@
+---
+'@electric-ax/agents-runtime': patch
+'@electric-ax/agents-server-ui': patch
+---
+
+Render standalone entity stream errors in the timeline with their error code and message.

packages/agents-runtime/src/entity-timeline.ts

@@ -8,6 +8,7 @@ import {
   eq,
   gt,
   isNull,
+  isUndefined,
   like,
   localOnlyCollectionOptions,
   or,
@@ -281,6 +282,9 @@ export interface EntityTimelineRunRow {
 export type EntityTimelineInboxRow = IncludesInboxMessage
 export type EntityTimelineWakeRow = IncludesWakeMessage
 export type EntityTimelineSignalRow = IncludesSignal
+export type EntityTimelineErrorRow = EntityTimelineErrorItem & {
+  order: TimelineOrder
+}
 
 export type EntityTimelineQueryRow =
   | {
@@ -289,6 +293,7 @@ export type EntityTimelineQueryRow =
       run?: undefined
       wake?: undefined
       signal?: undefined
+      error?: undefined
       manifest?: undefined
     }
   | {
@@ -297,6 +302,7 @@ export type EntityTimelineQueryRow =
       run: EntityTimelineRunRow
       wake?: undefined
       signal?: undefined
+      error?: undefined
       manifest?: undefined
     }
   | {
@@ -305,6 +311,7 @@ export type EntityTimelineQueryRow =
       run?: undefined
       wake: EntityTimelineWakeRow
       signal?: undefined
+      error?: undefined
       manifest?: undefined
     }
   | {
@@ -313,6 +320,16 @@ export type EntityTimelineQueryRow =
       run?: undefined
       wake?: undefined
       signal: EntityTimelineSignalRow
+      error?: undefined
+      manifest?: undefined
+    }
+  | {
+      $key: string
+      inbox?: undefined
+      run?: undefined
+      wake?: undefined
+      signal?: undefined
+      error: EntityTimelineErrorRow
       manifest?: undefined
     }
   | {
@@ -321,6 +338,7 @@ export type EntityTimelineQueryRow =
       run?: undefined
       wake?: undefined
       signal?: undefined
+      error?: undefined
       manifest: ManifestEntry
     }
 
@@ -1356,6 +1374,17 @@ function buildEntityTimelineQuery(
       new_state: signal.new_state,
     }))
 
+  const errorSource = q
+    .from({ error: db.collections.errors })
+    .where(({ error }) => or(isNull(error.run_id), isUndefined(error.run_id)))
+    .select(({ error }) => ({
+      key: error.key,
+      order: coalesce(error._timeline_order, `~`),
+      error_code: error.error_code,
+      message: error.message,
+      run_id: error.run_id,
+    }))
+
   const runItemsSource = q
     .unionAll({
       text: db.collections.texts,
@@ -1490,30 +1519,41 @@ function buildEntityTimelineQuery(
       run: runSource,
       wake: wakeSource,
       signal: signalSource,
+      error: errorSource,
       manifest: db.collections.manifests,
     })
-    .orderBy(({ inbox, run, wake, signal, manifest }) =>
+    .orderBy(({ inbox, run, wake, signal, error, manifest }) =>
       coalesce(
         inbox.order,
         run.order,
         wake.order,
         signal.order,
+        error.order,
         manifest._timeline_order,
         `~`
       )
     )
-    .orderBy(({ inbox, run, wake, signal, manifest }) =>
+    .orderBy(({ inbox, run, wake, signal, error, manifest }) =>
       coalesce(
         caseWhen(inbox.key, `inbox`),
         caseWhen(run.key, `run`),
         caseWhen(wake.key, `wake`),
         caseWhen(signal.key, `signal`),
+        caseWhen(error.key, `error`),
         caseWhen(manifest.key, `manifest`),
         ``
       )
     )
-    .orderBy(({ inbox, run, wake, signal, manifest }) =>
-      coalesce(inbox.key, run.key, wake.key, signal.key, manifest.key, ``)
+    .orderBy(({ inbox, run, wake, signal, error, manifest }) =>
+      coalesce(
+        inbox.key,
+        run.key,
+        wake.key,
+        signal.key,
+        error.key,
+        manifest.key,
+        ``
+      )
     )
 }
 
@@ -1751,7 +1791,9 @@ export function createEntityErrorsQuery(
   return (q: InitialQueryBuilder) =>
     q
       .from({ errors: db.collections.errors })
-      .where(({ errors }) => isNull(errors.run_id))
+      .where(({ errors }) =>
+        or(isNull(errors.run_id), isUndefined(errors.run_id))
+      )
       .select(({ errors }) => ({
         key: errors.key,
         error_code: errors.error_code,

packages/agents-runtime/test/entity-timeline.test.ts

@@ -6,7 +6,9 @@ import {
 import {
   buildEntityTimelineData,
   compareTimelineOrders,
+  createEntityErrorsQuery,
   createEntityIncludesQuery,
+  createEntityTimelineQuery,
   getEntityState,
   normalizeEntityTimelineData,
 } from '../src/entity-timeline'
@@ -1659,6 +1661,39 @@ describe(`entity includes query`, () => {
       }
     }
 
+    it(`matches standalone errors when run_id is omitted`, async () => {
+      const { collections, sync } = createEntityCollections()
+      const errorsQuery = createLiveQueryCollection({
+        query: createEntityErrorsQuery({ collections } as any),
+        startSync: true,
+      })
+      const timelineQuery = createLiveQueryCollection({
+        query: createEntityTimelineQuery({ collections } as any),
+        startSync: true,
+      })
+      await Promise.all([errorsQuery.preload(), timelineQuery.preload()])
+
+      sync.errors.insert({
+        key: `err-omitted-run`,
+        error_code: `HANDLER_FAILED`,
+        message: `boom`,
+      })
+      await new Promise((r) => setTimeout(r, 50))
+
+      expect(getData(errorsQuery)).toMatchObject([
+        {
+          key: `err-omitted-run`,
+          error_code: `HANDLER_FAILED`,
+          message: `boom`,
+        },
+      ])
+      expect(getData(timelineQuery)[0]?.error).toMatchObject({
+        key: `err-omitted-run`,
+        error_code: `HANDLER_FAILED`,
+        message: `boom`,
+      })
+    })
+
     it(`reacts to changes in the top-level runs collection`, async () => {
       const { collections, sync } = createEntityCollections()
       const queryFn = createEntityIncludesQuery({ collections } as any)

packages/agents-server-ui/src/components/EntityTimeline.tsx

@@ -265,6 +265,7 @@ function timelineRowSearchText(
     })
   }
   if (row.signal) return signalSearchText(row.signal)
+  if (row.error) return `${row.error.error_code} ${row.error.message}`
   if (row.manifest) return manifestSearchText(row.manifest)
   return runSearchTextByKey.get(row.$key) ?? runSearchTextFromSnapshot(row.run)
 }
@@ -274,6 +275,7 @@ function timelineRowLabel(row: RenderTimelineRow): string {
   if (row.inbox) return `User message`
   if (row.wake) return `Wake`
   if (row.signal) return `Signal`
+  if (row.error) return `Error`
   if (row.manifest) return `Manifest item`
   return `Agent response`
 }
@@ -434,6 +436,23 @@ function SignalTimelineRow({
   )
 }
 
+function ErrorTimelineRow({
+  error,
+}: {
+  error: NonNullable<RenderTimelineRow[`error`]>
+}): React.ReactElement {
+  return (
+    <div className={styles.manifestRow}>
+      <InlineEventCard
+        icon={CircleStop}
+        title={error.error_code || `error`}
+        summary={error.message}
+        headerSurface
+      />
+    </div>
+  )
+}
+
 function signalSearchText(
   signal: NonNullable<RenderTimelineRow[`signal`]>
 ): string {
@@ -982,6 +1001,10 @@ const TimelineRow = memo(function TimelineRow({
     return <SignalTimelineRow signal={row.signal} />
   }
 
+  if (row.error) {
+    return <ErrorTimelineRow error={row.error} />
+  }
+
   if (row.manifest) {
     return (
       <ManifestTimelineRow