@open-mercato/ai-assistant 0.6.2-develop.3406.1.2b403f40da → 0.6.2-develop.3446.1.bd060c6017

package/src/modules/ai_assistant/lib/__tests__/task-plan-stream.test.ts

@@ -0,0 +1,375 @@
+/**
+ * Tests for the server-side task-plan SSE injector
+ * (`packages/ai-assistant/src/modules/ai_assistant/lib/task-plan-stream.ts`).
+ *
+ * Covers spec `.ai/specs/2026-05-13-ai-chat-visible-task-plan.md`
+ * acceptance criteria:
+ *   - runtime-derived labels from tool lifecycle chunks
+ *   - agent-authored labels via the safe `meta.update_task_plan` tool
+ *   - additive `data-agent-task-plan` snapshot + `data-agent-task-update` deltas
+ *   - terminal-state ordering safeguard (done/failed/skipped wins over running)
+ *   - non-tool chunks are passed through unchanged
+ */
+
+// Node 18+ ships TextEncoder/TextDecoder/ReadableStream/Response globally,
+// so no jsdom-style polyfills are required for this test. The
+// `task-plan-stream` module relies on the same standard web stream APIs.
+
+import {
+  TaskPlanAccumulator,
+  deriveTaskLabel,
+  injectTaskPlanIntoStream,
+} from '../task-plan-stream'
+
+function chunk(type: string, extras: Record<string, unknown> = {}): { type: string } & Record<string, unknown> {
+  return { type, ...extras }
+}
+
+function parseInjected(line: string): Record<string, unknown> {
+  return JSON.parse(line.replace('data: ', '').trim()) as Record<string, unknown>
+}
+
+describe('deriveTaskLabel', () => {
+  it('humanizes the last tool segment with module prefix', () => {
+    expect(deriveTaskLabel('customers__list_people')).toBe('Customers · List people')
+  })
+
+  it('falls back to a generic label when name is missing', () => {
+    expect(deriveTaskLabel(undefined)).toBe('Tool call')
+    expect(deriveTaskLabel('')).toBe('Tool call')
+  })
+
+  it('handles unprefixed tool names', () => {
+    expect(deriveTaskLabel('search')).toBe('Search')
+  })
+
+  it('caps very long names at 80 chars', () => {
+    const huge = `module__${'segment_'.repeat(40)}end`
+    const label = deriveTaskLabel(huge)
+    expect(label.length).toBeLessThanOrEqual(80)
+  })
+})
+
+describe('TaskPlanAccumulator', () => {
+  it('emits an initial snapshot then patches via updates', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    const first = acc.handleToolChunk(
+      chunk('tool-input-start', { toolCallId: 'call-1', toolName: 'customers__list_people' }),
+    )
+    expect(first).toHaveLength(1)
+    const firstParsed = JSON.parse(first[0]!.replace('data: ', '').trim())
+    expect(firstParsed).toMatchObject({
+      type: 'data-agent-task-plan',
+      planId: 'turn_test',
+      tasks: [
+        {
+          id: 'call-1',
+          label: 'Customers · List people',
+          state: 'running',
+          source: 'runtime',
+          toolCallId: 'call-1',
+        },
+      ],
+    })
+
+    const finishing = acc.handleToolChunk(
+      chunk('tool-output-available', { toolCallId: 'call-1' }),
+    )
+    expect(finishing).toHaveLength(1)
+    const finishParsed = JSON.parse(finishing[0]!.replace('data: ', '').trim())
+    expect(finishParsed).toMatchObject({
+      type: 'data-agent-task-update',
+      planId: 'turn_test',
+      task: { id: 'call-1', state: 'done' },
+    })
+  })
+
+  it('emits task-update for a second tool that arrives after the snapshot', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    acc.handleToolChunk(chunk('tool-input-start', { toolCallId: 'call-1', toolName: 'a__first' }))
+    const secondStart = acc.handleToolChunk(
+      chunk('tool-input-start', { toolCallId: 'call-2', toolName: 'b__second' }),
+    )
+    expect(secondStart).toHaveLength(1)
+    const parsed = JSON.parse(secondStart[0]!.replace('data: ', '').trim())
+    expect(parsed.type).toBe('data-agent-task-update')
+    expect(parsed.task).toMatchObject({ id: 'call-2', state: 'running' })
+  })
+
+  it('keeps terminal state when a later running event arrives out of order', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    acc.handleToolChunk(chunk('tool-input-start', { toolCallId: 'call-1', toolName: 'a__first' }))
+    acc.handleToolChunk(chunk('tool-output-available', { toolCallId: 'call-1' }))
+    const stale = acc.handleToolChunk(
+      chunk('tool-input-available', { toolCallId: 'call-1', toolName: 'a__first', input: {} }),
+    )
+    const parsed = JSON.parse(stale[0]!.replace('data: ', '').trim())
+    // Stream-ordering safeguard: terminal `done` wins over a late `running`.
+    expect(parsed.task.state).toBe('done')
+  })
+
+  it('marks tool errors as failed', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    acc.handleToolChunk(chunk('tool-input-start', { toolCallId: 'call-1', toolName: 'a__first' }))
+    const fail = acc.handleToolChunk(
+      chunk('tool-output-error', { toolCallId: 'call-1', errorText: 'boom' }),
+    )
+    const parsed = JSON.parse(fail[0]!.replace('data: ', '').trim())
+    expect(parsed.task.state).toBe('failed')
+  })
+
+  it('ignores chunks without a toolCallId', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    expect(acc.handleToolChunk(chunk('tool-input-start'))).toEqual([])
+    expect(acc.handleToolChunk(chunk('text-delta', { delta: 'hi' }))).toEqual([])
+  })
+
+  it('emits a safe agent-authored plan from meta.update_task_plan input', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    const emitted = acc.handleToolChunk(
+      chunk('tool-input-available', {
+        toolCallId: 'plan-call',
+        toolName: 'meta__update_task_plan',
+        input: {
+          tasks: [
+            {
+              id: 'find-products',
+              label: 'Find matching products',
+              detail: 'Catalog search',
+              toolName: 'catalog.search_products',
+            },
+            {
+              label: 'Summarize useful matches',
+            },
+          ],
+        },
+      }),
+    )
+    expect(emitted).toHaveLength(1)
+    const parsed = parseInjected(emitted[0]!)
+    expect(parsed).toMatchObject({
+      type: 'data-agent-task-plan',
+      planId: 'turn_test',
+      tasks: [
+        {
+          id: 'find-products',
+          label: 'Find matching products',
+          detail: 'Catalog search',
+          state: 'pending',
+          source: 'agent',
+        },
+        {
+          id: 'agent-plan-2',
+          label: 'Summarize useful matches',
+          state: 'pending',
+          source: 'agent',
+        },
+      ],
+    })
+  })
+
+  it('drops hidden-reasoning-like agent task labels', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    const emitted = acc.handleToolChunk(
+      chunk('tool-input-available', {
+        toolCallId: 'plan-call',
+        toolName: 'meta.update_task_plan',
+        input: {
+          tasks: [
+            {
+              id: 'bad',
+              label: '<thinking>inspect tenant data</thinking>',
+            },
+          ],
+        },
+      }),
+    )
+    expect(emitted).toEqual([])
+  })
+
+  it('updates an agent-authored step when the mapped tool runs and finishes', () => {
+    const acc = new TaskPlanAccumulator('turn_test')
+    acc.handleToolChunk(
+      chunk('tool-input-available', {
+        toolCallId: 'plan-call',
+        toolName: 'meta__update_task_plan',
+        input: {
+          tasks: [
+            {
+              id: 'catalog-search',
+              label: 'Search the catalog',
+              toolName: 'catalog.search_products',
+            },
+          ],
+        },
+      }),
+    )
+    const running = acc.handleToolChunk(
+      chunk('tool-input-start', {
+        toolCallId: 'call-1',
+        toolName: 'catalog__search_products',
+      }),
+    )
+    expect(parseInjected(running[0]!)).toMatchObject({
+      type: 'data-agent-task-update',
+      task: {
+        id: 'catalog-search',
+        label: 'Search the catalog',
+        state: 'running',
+        source: 'agent',
+        toolCallId: 'call-1',
+      },
+    })
+
+    const done = acc.handleToolChunk(chunk('tool-output-available', { toolCallId: 'call-1' }))
+    expect(parseInjected(done[0]!)).toMatchObject({
+      type: 'data-agent-task-update',
+      task: {
+        id: 'catalog-search',
+        label: 'Search the catalog',
+        state: 'done',
+        source: 'agent',
+        toolCallId: 'call-1',
+      },
+    })
+  })
+})
+
+function buildSseResponse(events: Array<Record<string, unknown>>): Response {
+  const encoder = new TextEncoder()
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const raw = events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join('')
+      controller.enqueue(encoder.encode(raw))
+      controller.close()
+    },
+  })
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'x-vercel-ai-ui-message-stream': 'v1',
+    },
+  })
+}
+
+async function readEvents(response: Response): Promise<Array<Record<string, unknown>>> {
+  const reader = response.body!.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  const events: Array<Record<string, unknown>> = []
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+    for (;;) {
+      const boundary = buffer.indexOf('\n\n')
+      if (boundary === -1) break
+      const block = buffer.slice(0, boundary)
+      buffer = buffer.slice(boundary + 2)
+      const dataLine = block.split('\n').find((line) => line.startsWith('data: '))
+      if (!dataLine) continue
+      const payload = dataLine.slice('data: '.length)
+      if (payload === '[DONE]') continue
+      try {
+        events.push(JSON.parse(payload))
+      } catch {
+        // ignore malformed
+      }
+    }
+  }
+  return events
+}
+
+describe('injectTaskPlanIntoStream', () => {
+  it('passes through original chunks while injecting task-plan events', async () => {
+    const base = buildSseResponse([
+      { type: 'tool-input-start', toolCallId: 'call-1', toolName: 'catalog__search_products' },
+      { type: 'tool-input-available', toolCallId: 'call-1', toolName: 'catalog__search_products', input: { q: 'shoe' } },
+      { type: 'tool-output-available', toolCallId: 'call-1', output: { count: 3 } },
+      { type: 'text-delta', id: 'text-1', delta: 'Done.' },
+    ])
+    const wrapped = injectTaskPlanIntoStream(base, 'turn_42')
+    const events = await readEvents(wrapped)
+    const planEvent = events.find((e) => e.type === 'data-agent-task-plan')
+    expect(planEvent).toMatchObject({ planId: 'turn_42' })
+    // Snapshot should appear before the first tool-input-start passthrough.
+    const planIndex = events.findIndex((e) => e.type === 'data-agent-task-plan')
+    const startIndex = events.findIndex((e) => e.type === 'tool-input-start')
+    expect(planIndex).toBeLessThan(startIndex)
+    // A `done` update should be emitted after the tool-output-available.
+    const outputIndex = events.findIndex((e) => e.type === 'tool-output-available')
+    const doneUpdateIndex = events.findIndex(
+      (e) =>
+        e.type === 'data-agent-task-update' &&
+        (e.task as { state?: string } | undefined)?.state === 'done',
+    )
+    expect(doneUpdateIndex).toBeGreaterThan(outputIndex)
+    // Text-delta is forwarded unchanged.
+    const textEvent = events.find((e) => e.type === 'text-delta')
+    expect(textEvent).toMatchObject({ delta: 'Done.' })
+  })
+
+  it('injects an agent-authored plan before the meta tool input passthrough', async () => {
+    const base = buildSseResponse([
+      { type: 'tool-input-start', toolCallId: 'plan-call', toolName: 'meta__update_task_plan' },
+      {
+        type: 'tool-input-available',
+        toolCallId: 'plan-call',
+        toolName: 'meta__update_task_plan',
+        input: {
+          tasks: [
+            {
+              id: 'search-step',
+              label: 'Search matching products',
+              toolName: 'catalog.search_products',
+            },
+          ],
+        },
+      },
+      { type: 'tool-output-available', toolCallId: 'plan-call', output: { ok: true } },
+      { type: 'tool-input-start', toolCallId: 'call-1', toolName: 'catalog__search_products' },
+    ])
+    const wrapped = injectTaskPlanIntoStream(base, 'turn_agent')
+    const events = await readEvents(wrapped)
+    const planIndex = events.findIndex((e) => e.type === 'data-agent-task-plan')
+    const metaInputIndex = events.findIndex(
+      (e) => e.type === 'tool-input-available' && e.toolCallId === 'plan-call',
+    )
+    const domainStartIndex = events.findIndex(
+      (e) => e.type === 'tool-input-start' && e.toolCallId === 'call-1',
+    )
+    expect(planIndex).toBeGreaterThan(-1)
+    expect(planIndex).toBeLessThan(metaInputIndex)
+    expect(planIndex).toBeLessThan(domainStartIndex)
+    expect(events[planIndex]).toMatchObject({
+      tasks: [{ id: 'search-step', label: 'Search matching products', source: 'agent' }],
+    })
+    expect(
+      events.some(
+        (e) =>
+          (e.type === 'data-agent-task-update' || e.type === 'data-agent-task-plan') &&
+          JSON.stringify(e).includes('plan-call'),
+      ),
+    ).toBe(false)
+  })
+
+  it('does not inject anything when there are no tool events', async () => {
+    const base = buildSseResponse([
+      { type: 'text-delta', id: 'text-1', delta: 'Hello.' },
+      { type: 'reasoning-start' },
+      { type: 'reasoning-delta', delta: '...' },
+      { type: 'reasoning-end' },
+    ])
+    const wrapped = injectTaskPlanIntoStream(base, 'turn_43')
+    const events = await readEvents(wrapped)
+    expect(events.some((e) => e.type === 'data-agent-task-plan')).toBe(false)
+    expect(events.some((e) => e.type === 'data-agent-task-update')).toBe(false)
+    expect(events.map((e) => e.type)).toEqual([
+      'text-delta',
+      'reasoning-start',
+      'reasoning-delta',
+      'reasoning-end',
+    ])
+  })
+})

package/src/modules/ai_assistant/lib/agent-registry.ts

@@ -7,6 +7,7 @@ import {
   type AiAgentExtensionConfigEntry,
   type AiAgentOverrideConfigEntry,
 } from './ai-overrides'
+import { TASK_PLAN_TOOL_NAME } from './task-plan-labels'
 
 const agentsById = new Map<string, AiAgentDefinition>()
 let loaded = false
@@ -29,6 +30,11 @@ function isAiAgentExtension(value: unknown): value is AiAgentExtension {
     (!('replaceAllowedTools' in candidate) || isStringArray(candidate.replaceAllowedTools)) &&
     (!('deleteAllowedTools' in candidate) || isStringArray(candidate.deleteAllowedTools)) &&
     (!('appendAllowedTools' in candidate) || isStringArray(candidate.appendAllowedTools)) &&
+    (!('taskPlan' in candidate) ||
+      (candidate.taskPlan != null &&
+        typeof candidate.taskPlan === 'object' &&
+        (!('enabled' in candidate.taskPlan) ||
+          typeof (candidate.taskPlan as { enabled?: unknown }).enabled === 'boolean'))) &&
     (!('replaceSystemPrompt' in candidate) || typeof candidate.replaceSystemPrompt === 'string') &&
     (!('appendSystemPrompt' in candidate) || typeof candidate.appendSystemPrompt === 'string') &&
     (!('replaceSuggestions' in candidate) ||
@@ -58,6 +64,28 @@ function uniqueStrings(values: readonly string[]): string[] {
   return Array.from(new Set(values.filter((value) => typeof value === 'string' && value.length > 0)))
 }
 
+export function isAgentTaskPlanEnabled(agent: Pick<AiAgentDefinition, 'taskPlan'>): boolean {
+  return agent.taskPlan?.enabled === true
+}
+
+function normalizeTaskPlanTool(agent: AiAgentDefinition): AiAgentDefinition {
+  const enabled = isAgentTaskPlanEnabled(agent)
+  const withoutInternalTool = agent.allowedTools.filter((toolName) => toolName !== TASK_PLAN_TOOL_NAME)
+  const allowedTools = enabled
+    ? uniqueStrings([...withoutInternalTool, TASK_PLAN_TOOL_NAME])
+    : uniqueStrings(withoutInternalTool)
+  if (
+    allowedTools.length === agent.allowedTools.length &&
+    allowedTools.every((toolName, index) => toolName === agent.allowedTools[index])
+  ) {
+    return agent
+  }
+  return {
+    ...agent,
+    allowedTools,
+  }
+}
+
 function applyStringListPatch(
   current: readonly string[],
   patch: {
@@ -106,9 +134,10 @@ function applySuggestionPatch(
 }
 
 function validateAndNormalizeAgent(candidate: AiAgentDefinition): AiAgentDefinition {
+  const taskPlanNormalized = normalizeTaskPlanTool(candidate)
   const rawProvider = candidate.defaultProvider
   if (typeof rawProvider !== 'string' || rawProvider.trim().length === 0) {
-    return candidate
+    return taskPlanNormalized
   }
   const providerHint = rawProvider.trim()
   const registered = llmProviderRegistry.get(providerHint)
@@ -118,9 +147,9 @@ function validateAndNormalizeAgent(candidate: AiAgentDefinition): AiAgentDefinit
         `The agent will be registered with defaultProvider: undefined so the resolution chain still works. ` +
         `Built-in provider ids: anthropic, google, openai, deepinfra, groq, together, fireworks, azure, litellm, ollama.`,
     )
-    return { ...candidate, defaultProvider: undefined }
+    return { ...taskPlanNormalized, defaultProvider: undefined }
   }
-  return candidate
+  return taskPlanNormalized
 }
 
 function populateFromAgents(agents: unknown[]): void {
@@ -193,13 +222,14 @@ function applyExtensionsToRegistry(extensions: readonly AiAgentExtension[]): voi
     const replacementSystemPrompt = extension.replaceSystemPrompt?.trim()
     const appendSystemPrompt = extension.appendSystemPrompt?.trim()
     const systemPrompt = replacementSystemPrompt ?? agent.systemPrompt.trim()
-    agentsById.set(agent.id, {
+    const patchedAgent: AiAgentDefinition = {
       ...agent,
       allowedTools: applyStringListPatch(agent.allowedTools, {
         replace: extension.replaceAllowedTools,
         delete: extension.deleteAllowedTools,
         append: extension.appendAllowedTools,
       }),
+      taskPlan: extension.taskPlan !== undefined ? extension.taskPlan : agent.taskPlan,
       systemPrompt: appendSystemPrompt
         ? `${systemPrompt}\n\n${appendSystemPrompt}`
         : systemPrompt,
@@ -211,7 +241,8 @@ function applyExtensionsToRegistry(extensions: readonly AiAgentExtension[]): voi
           ...(extension.suggestions ?? []),
         ],
       }),
-    })
+    }
+    agentsById.set(agent.id, validateAndNormalizeAgent(patchedAgent))
   }
 }
 

package/src/modules/ai_assistant/lib/agent-runtime.ts

@@ -57,9 +57,12 @@ import { AiAgentRuntimeOverrideRepository } from '../data/repositories/AiAgentRu
 import { AiTenantModelAllowlistRepository } from '../data/repositories/AiTenantModelAllowlistRepository'
 import type { TenantAllowlistSnapshot } from './model-allowlist'
 import { composeSystemPromptWithOverride } from './prompt-override-merge'
+import { isAgentTaskPlanEnabled } from './agent-registry'
 import { isKnownMutationPolicy } from './agent-policy'
 import type { AiAgentMutationPolicy } from './ai-agent-definition'
 import { recordTokenUsage } from './token-usage-recorder'
+import { injectTaskPlanIntoStream } from './task-plan-stream'
+import { TASK_PLAN_RUNTIME_PROMPT_SECTION } from './task-plan-labels'
 
 // Ensure built-in LLM providers are registered. Side-effect import; identical to
 // what `./ai-sdk.ts` consumers already rely on.
@@ -1416,6 +1419,11 @@ function appendRuntimeMutationPolicy(
   return `${systemPrompt}\n\n${block}`
 }
 
+function appendRuntimeTaskPlanPrompt(systemPrompt: string, agent: Pick<AiAgentDefinition, 'taskPlan'>): string {
+  if (!isAgentTaskPlanEnabled(agent)) return systemPrompt
+  return `${systemPrompt}\n\n${TASK_PLAN_RUNTIME_PROMPT_SECTION}`
+}
+
 /**
  * Server-side helper that runs an Open Mercato agent in chat mode via the
  * Vercel AI SDK and returns a streaming `Response` ready to be emitted from a
@@ -1482,7 +1490,7 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
     input.authContext.organizationId,
   )
   const systemPrompt = appendRuntimeMutationPolicy(
-    appendAttachmentSummary(baseSystemPrompt, resolvedAttachments),
+    appendRuntimeTaskPlanPrompt(appendAttachmentSummary(baseSystemPrompt, resolvedAttachments), agent),
     agent,
     mutationPolicyOverride,
   )
@@ -1615,6 +1623,13 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
     ...(builtToolLoopAgent !== undefined ? { toolLoopAgent: builtToolLoopAgent } : {}),
   }
 
+  // Phase 1 of `2026-05-13-ai-chat-visible-task-plan` — every chat-mode
+  // response stream is wrapped in a task-plan injector. The injector is
+  // additive and keyed by the per-turn `turnId` so old clients that ignore
+  // unknown chunks keep working; current clients render only agent-authored
+  // plan rows and leave raw lifecycle progress in the tool-call details.
+  const taskPlanId = `turn_${turnId}`
+
   if (input.generateText) {
     try {
       const callbackResult = await input.generateText(preparedOptions)
@@ -1625,10 +1640,11 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
           Connection: 'keep-alive',
         },
       })
+      const withTaskPlan = injectTaskPlanIntoStream(baseResponse, taskPlanId)
       if (input.emitLoopTrace) {
-        return appendLoopFinishToStream(baseResponse, preparedOptions.finalizeLoopTrace)
+        return appendLoopFinishToStream(withTaskPlan, preparedOptions.finalizeLoopTrace)
       }
-      return baseResponse
+      return withTaskPlan
     } finally {
       if (wallClockTimer !== undefined) clearTimeout(wallClockTimer)
     }
@@ -1654,10 +1670,11 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
         Connection: 'keep-alive',
       },
     })
+    const withTaskPlan = injectTaskPlanIntoStream(baseResponse, taskPlanId)
     if (input.emitLoopTrace) {
-      return appendLoopFinishToStream(baseResponse, preparedOptions.finalizeLoopTrace)
+      return appendLoopFinishToStream(withTaskPlan, preparedOptions.finalizeLoopTrace)
     }
-    return baseResponse
+    return withTaskPlan
   }
 
   // Default stream-text path (executionEngine === 'stream-text' or unset).
@@ -1688,10 +1705,11 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
       Connection: 'keep-alive',
     },
   })
+  const withTaskPlan = injectTaskPlanIntoStream(baseResponse, taskPlanId)
   if (input.emitLoopTrace) {
-    return appendLoopFinishToStream(baseResponse, preparedOptions.finalizeLoopTrace)
+    return appendLoopFinishToStream(withTaskPlan, preparedOptions.finalizeLoopTrace)
   }
-  return baseResponse
+  return withTaskPlan
 }
 
 /**
@@ -1914,7 +1932,7 @@ export async function runAiAgentObject<TSchema = unknown>(
     input.authContext.organizationId,
   )
   const systemPrompt = appendRuntimeMutationPolicy(
-    appendAttachmentSummary(baseSystemPrompt, resolvedAttachments),
+    appendRuntimeTaskPlanPrompt(appendAttachmentSummary(baseSystemPrompt, resolvedAttachments), agent),
     agent,
     mutationPolicyOverride,
   )

package/src/modules/ai_assistant/lib/ai-agent-definition.ts

@@ -275,6 +275,18 @@ export interface AiAgentSuggestion {
   prompt: string
 }
 
+export interface AiAgentTaskPlanConfig {
+  /**
+   * Enables the optional visible planning helper for this agent. When true,
+   * the runtime exposes `meta.update_task_plan` and injects prompt guidance
+   * telling the model to set a user-visible plan before domain tools.
+   *
+   * Defaults to false. CRM/customer agents enable this by default in core;
+   * other agents can opt in from their agent definition or extension config.
+   */
+  enabled?: boolean
+}
+
 export interface AiAgentDefinition {
   id: string
   moduleId: string
@@ -368,6 +380,7 @@ export interface AiAgentDefinition {
   allowRuntimeModelOverride?: boolean
   acceptedMediaTypes?: AiAgentAcceptedMediaType[]
   requiredFeatures?: string[]
+  taskPlan?: AiAgentTaskPlanConfig
   uiParts?: string[]
   readOnly?: boolean
   mutationPolicy?: AiAgentMutationPolicy
@@ -400,6 +413,7 @@ export interface AiAgentExtension {
   replaceAllowedTools?: string[]
   deleteAllowedTools?: string[]
   appendAllowedTools?: string[]
+  taskPlan?: AiAgentTaskPlanConfig
   replaceSystemPrompt?: string
   appendSystemPrompt?: string
   replaceSuggestions?: AiAgentSuggestion[]

package/src/modules/ai_assistant/lib/pending-action-types.ts

@@ -65,7 +65,7 @@ export type AiPendingActionRecordDiff = {
   recordId: string
   entityType: string
   label: string
-  fieldDiff: Array<{ field: string; before: unknown; after: unknown }>
+  fieldDiff: AiPendingActionFieldDiff[]
   recordVersion: string | null
   attachmentIds?: string[]
 }
@@ -81,8 +81,11 @@ export type AiPendingActionFailedRecord = {
 
 export type AiPendingActionFieldDiff = {
   field: string
+  fieldLabel?: string
   before: unknown
   after: unknown
+  beforeDisplay?: unknown
+  afterDisplay?: unknown
 }
 
 /**

package/src/modules/ai_assistant/lib/prepare-mutation.ts

@@ -5,6 +5,7 @@ import type { AiAgentDefinition, AiAgentMutationPolicy } from './ai-agent-defini
 import type { AiChatRequestContext, AiUiPart } from './attachment-bridge-types'
 import type {
   AiToolDefinition,
+  AiToolFieldDiffDisplayHints,
   AiToolLoadBeforeRecord,
   AiToolLoadBeforeSingleRecord,
   McpToolContext,
@@ -163,6 +164,7 @@ export function computeMutationIdempotencyKey(input: {
 function computeFieldDiff(
   before: Record<string, unknown>,
   after: Record<string, unknown>,
+  display?: AiToolFieldDiffDisplayHints,
 ): AiPendingActionFieldDiff[] {
   const diff: AiPendingActionFieldDiff[] = []
   const keys = new Set<string>([
@@ -173,7 +175,17 @@ function computeFieldDiff(
     const beforeValue = before ? before[field] : undefined
     const afterValue = after ? after[field] : undefined
     if (!Object.is(beforeValue, afterValue) && safeStringify(beforeValue) !== safeStringify(afterValue)) {
-      diff.push({ field, before: beforeValue, after: afterValue })
+      const fieldLabel = display?.fieldLabels?.[field]
+      const beforeDisplay = display?.before?.[field]
+      const afterDisplay = display?.after?.[field]
+      diff.push({
+        field,
+        ...(fieldLabel !== undefined ? { fieldLabel } : {}),
+        before: beforeValue,
+        after: afterValue,
+        ...(beforeDisplay !== undefined ? { beforeDisplay } : {}),
+        ...(afterDisplay !== undefined ? { afterDisplay } : {}),
+      })
     }
   }
   return diff
@@ -276,8 +288,8 @@ async function buildSingleRecordDiff(
       sideEffectsSummary: null,
     }
   }
-  const patch = extractPatchFromArgs(input.toolCallArgs)
-  const fieldDiff = computeFieldDiff(before.before, patch)
+  const patch = before.after ?? extractPatchFromArgs(input.toolCallArgs)
+  const fieldDiff = computeFieldDiff(before.before, patch, before.display)
   return {
     fieldDiff,
     targetEntityType: before.entityType,
@@ -320,12 +332,12 @@ async function buildBatchRecords(
     }
   }
   const diffs: AiPendingActionRecordDiff[] = rows.map((row) => {
-    const patch = matchBatchPatch(input.toolCallArgs, row.recordId)
+    const patch = row.after ?? matchBatchPatch(input.toolCallArgs, row.recordId)
     return {
       recordId: row.recordId,
       entityType: row.entityType,
       label: row.label,
-      fieldDiff: computeFieldDiff(row.before, patch),
+      fieldDiff: computeFieldDiff(row.before, patch, row.display),
       recordVersion: row.recordVersion ?? null,
     }
   })