Translate ACP traffic into shared timeline events

src/main/acp/acp-background-task-timeline.ts

@@ -0,0 +1,57 @@
+import { BoundedMap } from '../../shared/bounded-map'
+import { backgroundTaskJournalBody } from '../../shared/native-chat-background-task-row'
+import type { NativeChatBackgroundTaskBlock } from '../../shared/native-chat-types'
+import {
+  boundInlineText,
+  DEFAULT_JOURNAL_PAYLOAD_LIMITS
+} from '../native-chat/agent-session-journal/journal-payload-bounds'
+import type {
+  ProviderTimelineEvent,
+  ProviderTimelineJoin
+} from '../native-chat/agent-session-timeline/provider-timeline-event'
+import type { AcpBackgroundTaskUpdate } from './acp-dialects/acp-dialect'
+
+/** Partial provider snapshots only; the assembler owns settlement and durable placement. A task
+ *  the bound evicted (128 others updated since) loses its earlier label, parent tool and output
+ *  file on its next update; its row keeps the turn it was placed in. */
+export class AcpBackgroundTaskTimeline {
+  private readonly snapshots = new BoundedMap<string, NativeChatBackgroundTaskBlock>({
+    maxEntries: 128,
+    maxBytes: 1024 * 1024,
+    sizeOf: (block, key) => Buffer.byteLength(key) + Buffer.byteLength(JSON.stringify(block))
+  })
+
+  constructor(private readonly toolTurn: (callId: string) => string | undefined) {}
+
+  translate(
+    updates: AcpBackgroundTaskUpdate[],
+    join: ProviderTimelineJoin
+  ): ProviderTimelineEvent[] {
+    return updates.map((update) => {
+      const { fallbackLabel, fallbackKind, ...fields } = update
+      const previous = this.snapshots.get(update.taskId)
+      const block: NativeChatBackgroundTaskBlock = {
+        type: 'background-task',
+        ...previous,
+        ...fields,
+        kind: update.kind ?? previous?.kind ?? fallbackKind ?? 'unknown',
+        label: update.label ?? previous?.label ?? fallbackLabel ?? update.taskId,
+        state: update.state
+      }
+      for (const key of ['label', 'summary', 'error', 'outputFile'] as const) {
+        const text = block[key]
+        if (text !== undefined) {
+          block[key] = boundInlineText(text, DEFAULT_JOURNAL_PAYLOAD_LIMITS).text
+        }
+      }
+      this.snapshots.set(block.taskId, block)
+      const turn = block.parentToolUseId ? this.toolTurn(block.parentToolUseId) : undefined
+      return {
+        type: 'item.update',
+        item: `background-task:${block.taskId}`,
+        body: backgroundTaskJournalBody(block),
+        join: { ...join, ...(turn === undefined ? {} : { turn }) }
+      }
+    })
+  }
+}

src/main/acp/acp-context-usage.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+import type { AgentSessionContextUsage } from '../../shared/agent-session-context-usage'
+import type {
+  ProviderTimelineEvent,
+  ProviderTimelineJoin
+} from '../native-chat/agent-session-timeline/provider-timeline-event'
+import type { AcpDialect } from './acp-dialects/acp-dialect'
+import type { SessionUpdate, UsageUpdate } from './generated/acp-protocol.generated'
+
+export class AcpContextTimeline {
+  private window?: { tokens: number; capturedAt: number }
+
+  models(
+    models: unknown,
+    at: number,
+    dialect: AcpDialect,
+    join: ProviderTimelineJoin
+  ): ProviderTimelineEvent[] {
+    const tokens = dialect.contextWindow?.(models)
+    return tokens === undefined ? [] : this.update({ window: { tokens, capturedAt: at } }, join)
+  }
+
+  update(usage: AgentSessionContextUsage, join: ProviderTimelineJoin): ProviderTimelineEvent[] {
+    this.window = usage.window ?? this.window
+    return [
+      {
+        type: 'context.usage',
+        usage: { ...usage, ...(this.window ? { window: this.window } : {}) },
+        join
+      }
+    ]
+  }
+
+  /** Replayed history is dropped except what it says about the context window. */
+  history(
+    update: SessionUpdate | undefined,
+    usage: AgentSessionContextUsage | undefined,
+    at: number,
+    join: ProviderTimelineJoin
+  ): ProviderTimelineEvent[] {
+    const events = usage ? this.update(usage, join) : []
+    if (update?.sessionUpdate === 'usage_update') {
+      events.push({ type: 'context.usage', usage: acpWindowUsage(update, at), join })
+    }
+    return events
+  }
+}
+
+export function acpWindowUsage(update: UsageUpdate, at: number): AgentSessionContextUsage {
+  return {
+    window: { tokens: update.size, capturedAt: at },
+    used: {
+      kind: 'estimate',
+      capturedAt: at,
+      usage: {
+        inputTokens: update.used,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        outputTokens: 0
+      }
+    }
+  }
+}
+
+export const acpNotificationEnvelopeSchema = z.looseObject({
+  sessionId: z.string(),
+  update: z.looseObject({ sessionUpdate: z.string() }),
+  _meta: z.looseObject({ isReplay: z.boolean().optional() }).nullish()
+})

src/main/acp/acp-dialects/acp-dialect.ts

@@ -0,0 +1,54 @@
+import type { AgentSessionContextUsage } from '../../../shared/agent-session-context-usage'
+import type { AgentJournalToolCallItem } from '../../../shared/agent-session-journal-types'
+import type { AgentSessionPromptResponse } from '../../../shared/agent-session-question-answer'
+import type { NativeChatBackgroundTaskBlock } from '../../../shared/native-chat-types'
+import type { ProviderTimelineRequestBody } from '../../native-chat/agent-session-timeline/provider-timeline-event'
+import type { AcpAgentError } from '../acp-errors'
+import type { ToolCallUpdate } from '../generated/acp-protocol.generated'
+
+export type AcpRequestPresentation = {
+  body: ProviderTimelineRequestBody
+  reply(response: AgentSessionPromptResponse | null): unknown
+}
+
+export type AcpBackgroundTaskUpdate = Pick<NativeChatBackgroundTaskBlock, 'taskId' | 'state'> &
+  Partial<Omit<NativeChatBackgroundTaskBlock, 'type' | 'taskId' | 'state'>> & {
+    /** Used only until a provider description is known. */
+    fallbackLabel?: string
+    /** Used only until a frame names the task's kind. */
+    fallbackKind?: NativeChatBackgroundTaskBlock['kind']
+  }
+
+export type AcpDialectNotification =
+  | { disposition: 'ignore' }
+  | {
+      disposition: 'map'
+      turn?: string
+      replay?: boolean
+      at?: number
+      started?: boolean
+      end?: { stopReason: string; durationMs?: number; failureDetail?: string }
+      /** The provider's own words for why `turn` failed, sent apart from its end. */
+      failureDetail?: string
+      usage?: AgentSessionContextUsage
+      backgroundTasks?: AcpBackgroundTaskUpdate[]
+    }
+
+/** Hooks interpret extensions; lifecycle and row identity stay shared. */
+export type AcpDialect = {
+  injectedPromptIdentity?: true
+  toolName?(update: ToolCallUpdate): string | undefined
+  toolBackgroundTasks?(
+    update: ToolCallUpdate,
+    tool: AgentJournalToolCallItem
+  ): AcpBackgroundTaskUpdate[]
+  notification?(method: string, params: unknown, at: number): AcpDialectNotification | undefined
+  contextWindow?(models: unknown): number | undefined
+  request?(method: string, params: unknown): AcpRequestPresentation | undefined
+  /** The provider's words in a `session/prompt` error answer, when its message is generic. */
+  promptErrorDetail?(error: AcpAgentError): string | undefined
+  /** The row for a failed turn the provider gave no words for. */
+  failedTurnText?(stopReason: string): string
+}
+
+export const GENERIC_ACP_DIALECT: AcpDialect = {}

src/main/acp/acp-dialects/grok-background-tasks.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod'
+import type { AgentJournalToolCallItem } from '../../../shared/agent-session-journal-types'
+import {
+  isSettledBackgroundTaskState,
+  normalizeBackgroundTaskKind
+} from '../../../shared/native-chat-background-task-row'
+import type { NativeChatBackgroundTaskBlock } from '../../../shared/native-chat-types'
+import type { ToolCallUpdate } from '../generated/acp-protocol.generated'
+import type { AcpBackgroundTaskUpdate, AcpDialectNotification } from './acp-dialect'
+
+const taskSchema = z.object({
+  task_id: z.string().min(1),
+  command: z.string().optional(),
+  description: z.string().nullish(),
+  monitor_description: z.string().nullish(),
+  display_command: z.string().nullish(),
+  output_file: z.string().optional(),
+  summary: z.string().optional(),
+  error: z.string().optional(),
+  output: z.string().optional(),
+  kind: z.string().optional(),
+  task_type: z.string().optional(),
+  exit_code: z.number().int().nullish(),
+  signal: z.union([z.string(), z.number()]).nullish(),
+  explicitly_killed: z.boolean().optional()
+})
+const backgroundedSchema = taskSchema.extend({
+  sessionUpdate: z.literal('task_backgrounded'),
+  tool_call_id: z.string().optional()
+})
+const completedSchema = z.object({
+  sessionUpdate: z.literal('task_completed'),
+  task_snapshot: taskSchema
+})
+const startedOutputSchema = taskSchema.extend({ type: z.literal('BackgroundTaskStarted') })
+const taskResultSchema = taskSchema.extend({
+  status: z.string().optional(),
+  outcome: z.string().optional()
+})
+const resultOutputSchema = z.object({
+  type: z.enum(['TaskOutput', 'KillTask']),
+  Result: taskResultSchema.optional(),
+  MultiResult: z.object({ results: z.array(taskResultSchema) }).optional()
+})
+type GrokTask = z.infer<typeof taskSchema>
+/** Grok's output reads name a monitor only by this command prefix. */
+const MONITOR_COMMAND = /^\[monitor[:\]]/
+
+function completedState(task: GrokTask): NativeChatBackgroundTaskBlock['state'] {
+  return task.explicitly_killed
+    ? 'idle'
+    : task.signal != null || task.error?.trim() || (task.exit_code != null && task.exit_code !== 0)
+      ? 'blocked'
+      : 'done'
+}
+
+function resultState(
+  task: z.infer<typeof taskResultSchema>
+): NativeChatBackgroundTaskBlock['state'] | undefined {
+  if (task.explicitly_killed || ['killed', 'stopped', 'cancelled'].includes(task.status ?? '')) {
+    return 'idle'
+  }
+  if (task.error?.trim() || ['failed', 'error'].includes(task.status ?? '')) {
+    return 'blocked'
+  }
+  if (
+    task.exit_code != null ||
+    task.signal != null ||
+    ['completed', 'success', 'succeeded'].includes(task.status ?? '')
+  ) {
+    return completedState(task)
+  }
+  return ['pending', 'running'].includes(task.status ?? '') ? 'working' : undefined
+}
+
+function snapshot(
+  task: GrokTask,
+  state: NativeChatBackgroundTaskBlock['state']
+): AcpBackgroundTaskUpdate {
+  const kind = task.kind ?? task.task_type
+  const monitor =
+    kind === 'monitor' ||
+    task.monitor_description != null ||
+    MONITOR_COMMAND.test(task.command ?? '')
+  const label = task.monitor_description?.trim() || task.description?.trim()
+  const fallbackLabel = task.display_command?.trim() || task.command?.trim()
+  const settled = isSettledBackgroundTaskState(state)
+  return {
+    taskId: task.task_id,
+    state,
+    ...(monitor
+      ? { kind: 'monitor' as const }
+      : kind !== undefined
+        ? {
+            kind:
+              kind === 'bash' || kind === 'shell' || task.command !== undefined
+                ? ('command' as const)
+                : normalizeBackgroundTaskKind(kind)
+          }
+        : task.command !== undefined
+          ? { fallbackKind: 'command' as const }
+          : {}),
+    ...(label ? { label } : fallbackLabel ? { fallbackLabel } : {}),
+    ...(task.output_file === undefined ? {} : { outputFile: task.output_file }),
+    // A running task's summary is Grok's "Background task <id> started", not the task's result.
+    ...(settled ? { summary: task.summary ?? '' } : {}),
+    ...(task.error === undefined && !settled ? {} : { error: task.error ?? '' })
+  }
+}
+
+const taskInputSchema = z.object({
+  description: z.string().optional(),
+  command: z.string().optional(),
+  task_id: z.string().trim().min(1).optional(),
+  task_ids: z.array(z.string().trim().min(1)).optional()
+})
+
+export function grokToolBackgroundTasks(
+  update: ToolCallUpdate,
+  tool: AgentJournalToolCallItem
+): AcpBackgroundTaskUpdate[] {
+  const result = resultOutputSchema.safeParse(update.rawOutput)
+  if (result.success) {
+    const tasks =
+      result.data.MultiResult?.results ?? (result.data.Result ? [result.data.Result] : [])
+    return tasks.flatMap((task) => {
+      if (result.data.type === 'KillTask') {
+        return update.status === 'completed' && task.outcome === 'killed'
+          ? [snapshot(task, 'idle')]
+          : []
+      }
+      const state = resultState(task)
+      return state && !task.command?.startsWith('[subagent:') ? [snapshot(task, state)] : []
+    })
+  }
+  const input = taskInputSchema.safeParse(tool.input)
+  if (tool.name === 'kill_command_or_subagent' && update.status === 'completed' && input.success) {
+    // Inference: a successful kill call settles its named tasks without a completion notice.
+    return [
+      ...new Set([
+        ...(input.data.task_ids ?? []),
+        ...(input.data.task_id ? [input.data.task_id] : [])
+      ])
+    ].map((taskId) => ({ taskId, state: 'idle', summary: '', error: '' }))
+  }
+  const parsed = startedOutputSchema.safeParse(update.rawOutput)
+  return parsed.success
+    ? [
+        {
+          ...snapshot({ ...(input.success ? input.data : {}), ...parsed.data }, 'working'),
+          parentToolUseId: update.toolCallId
+        }
+      ]
+    : []
+}
+
+export function grokBackgroundTaskNotification(
+  canonicalMethod: string,
+  params: unknown
+): AcpDialectNotification | undefined {
+  if (!['x.ai/task_backgrounded', 'x.ai/task_completed'].includes(canonicalMethod)) {
+    return undefined
+  }
+  const parsed = z
+    .object({ sessionId: z.string(), update: z.union([backgroundedSchema, completedSchema]) })
+    .safeParse(params)
+  if (!parsed.success) {
+    return { disposition: 'ignore' }
+  }
+  const update = parsed.data.update
+  if (update.sessionUpdate === 'task_backgrounded') {
+    return {
+      disposition: 'map',
+      backgroundTasks: [
+        {
+          ...snapshot(update, update.monitor_description != null ? 'monitoring' : 'working'),
+          ...(update.tool_call_id === undefined ? {} : { parentToolUseId: update.tool_call_id })
+        }
+      ]
+    }
+  }
+  const task = update.task_snapshot
+  return { disposition: 'map', backgroundTasks: [snapshot(task, completedState(task))] }
+}