feat(agents): Add session comments to agent timelines

.changeset/session-comments.md

@@ -0,0 +1,7 @@
+---
+"@electric-ax/agents-runtime": patch
+"@electric-ax/agents-server": patch
+"@electric-ax/agents-server-ui": patch
+---
+
+Add session comments to agent timelines, including synced comment events, server comment writes, reply targets, comments-only timeline display, and timeline controls for showing or hiding comments.

packages/agents-runtime/src/client.ts

@@ -4,6 +4,7 @@ export {
   compareTimelineOrders,
   buildEntityTimelineData,
   createPendingTimelineOrder,
+  TIMELINE_ORDER_FALLBACK,
   createEntityErrorsQuery,
   createEntityIncludesQuery,
   createEntityTimelineQuery,
@@ -44,6 +45,9 @@ export type {
   AttachmentStatus,
   AttachmentSubject,
   AttachmentSubjectType,
+  Comment,
+  CommentSnapshot,
+  CommentTarget,
   Manifest,
   ManifestAttachmentEntry,
 } from './entity-schema'
@@ -64,6 +68,7 @@ export type {
 export type {
   EntityTimelineContentItem,
   EntityTimelineData,
+  EntityTimelineCommentRow,
   EntityTimelineInboxMode,
   EntityTimelineQueryOptions,
   EntityTimelineQueryRow,

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

@@ -203,6 +203,43 @@ type MessageReceivedValue = {
   processed_at?: string
   cancelled_at?: string
 }
+type CommentTargetCollectionValue =
+  | `inbox`
+  | `run`
+  | `text`
+  | `tool_call`
+  | `wake`
+  | `signal`
+  | `manifest`
+type CommentTargetValue =
+  | {
+      kind: `comment`
+      key: string
+    }
+  | {
+      kind: `timeline`
+      collection: CommentTargetCollectionValue
+      key: string
+      run_id?: string
+    }
+type CommentSnapshotValue = {
+  label: string
+  text?: string
+  from?: string
+  timestamp?: string
+  collection?: string
+}
+type CommentValue = {
+  key?: string
+  body: string
+  from_principal: string
+  timestamp: string
+  reply_to?: CommentTargetValue
+  target_snapshot?: CommentSnapshotValue
+  edited_at?: string
+  deleted_at?: string
+  deleted_by?: string
+}
 type WakeEntryValue = {
   key?: string
   timestamp: string
@@ -552,6 +589,54 @@ function createMessageReceivedSchema(): Schema<MessageReceivedValue> {
   })
 }
 
+function createCommentTargetSchema(): Schema<CommentTargetValue> {
+  return z.union([
+    z.object({
+      kind: z.literal(`comment`),
+      key: z.string(),
+    }),
+    z.object({
+      kind: z.literal(`timeline`),
+      collection: z.enum([
+        `inbox`,
+        `run`,
+        `text`,
+        `tool_call`,
+        `wake`,
+        `signal`,
+        `manifest`,
+      ]),
+      key: z.string(),
+      run_id: z.string().optional(),
+    }),
+  ])
+}
+
+function createCommentSnapshotSchema(): Schema<CommentSnapshotValue> {
+  return z.object({
+    label: z.string(),
+    text: z.string().optional(),
+    from: z.string().optional(),
+    timestamp: z.string().optional(),
+    collection: z.string().optional(),
+  })
+}
+
+function createCommentSchema(): Schema<CommentValue> {
+  return z.object({
+    key: z.string().optional(),
+    ...timelineOrderField,
+    body: z.string(),
+    from_principal: z.string(),
+    timestamp: z.string(),
+    reply_to: createCommentTargetSchema().optional(),
+    target_snapshot: createCommentSnapshotSchema().optional(),
+    edited_at: z.string().optional(),
+    deleted_at: z.string().optional(),
+    deleted_by: z.string().optional(),
+  })
+}
+
 function createWakeSchema(): Schema<WakeEntryValue> {
   return z.object({
     key: z.string().optional(),
@@ -851,6 +936,9 @@ export type ToolCall = SequencedPersistedRow<ToolCallValue>
 export type Reasoning = SequencedPersistedRow<ReasoningValue>
 export type ErrorEvent = SequencedPersistedRow<ErrorEventValue>
 export type MessageReceived = SequencedPersistedRow<MessageReceivedValue>
+export type CommentTarget = CommentTargetValue
+export type CommentSnapshot = CommentSnapshotValue
+export type Comment = SequencedPersistedRow<CommentValue>
 export type WakeEntry = SequencedPersistedRow<WakeEntryValue>
 export type EntityCreated = SequencedPersistedRow<EntityCreatedValue>
 export type EntityStopped = SequencedPersistedRow<EntityStoppedValue>
@@ -941,6 +1029,7 @@ export const ENTITY_COLLECTIONS = {
   reasoning: `reasoning`,
   errors: `errors`,
   inbox: `inbox`,
+  comments: `comments`,
   wakes: `wakes`,
   entityCreated: `entityCreated`,
   entityStopped: `entityStopped`,
@@ -966,6 +1055,7 @@ export const BUILT_IN_EVENT_SCHEMAS = {
   error: createErrorEventSchema() as unknown as BuiltInEntitySchema<ErrorEvent>,
   inbox:
     createMessageReceivedSchema() as unknown as BuiltInEntitySchema<MessageReceived>,
+  comment: createCommentSchema() as unknown as BuiltInEntitySchema<Comment>,
   wake: createWakeSchema() as unknown as BuiltInEntitySchema<WakeEntry>,
   entity_created:
     createEntityCreatedSchema() as unknown as BuiltInEntitySchema<EntityCreated>,
@@ -1000,6 +1090,7 @@ type EntityCollectionsDefinition = {
   reasoning: CollectionDefinition<Reasoning>
   errors: CollectionDefinition<ErrorEvent>
   inbox: CollectionDefinition<MessageReceived>
+  comments: CollectionDefinition<Comment>
   wakes: CollectionDefinition<WakeEntry>
   entityCreated: CollectionDefinition<EntityCreated>
   entityStopped: CollectionDefinition<EntityStopped>
@@ -1060,6 +1151,11 @@ export const builtInCollections: EntityCollectionsDefinition = {
     type: `inbox`,
     primaryKey: `key`,
   },
+  comments: {
+    schema: BUILT_IN_EVENT_SCHEMAS.comment as StandardSchemaV1<Comment>,
+    type: `comment`,
+    primaryKey: `key`,
+  },
   wakes: {
     schema: BUILT_IN_EVENT_SCHEMAS.wake as StandardSchemaV1<WakeEntry>,
     type: `wake`,