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

package/src/ai/useAiChat.ts

@@ -20,6 +20,7 @@ export interface AiChatMessageFile {
 export interface AiChatToolCallSnapshot {
   id: string
   toolName: string
+  caption?: string
   state: 'pending' | 'complete' | 'error'
   input?: unknown
   output?: unknown
@@ -34,6 +35,25 @@ export interface AiChatMessageUiPart {
   key: string
 }
 
+/**
+ * Snapshot of a single task in the visible agent task plan
+ * (spec `.ai/specs/2026-05-13-ai-chat-visible-task-plan.md`). Tasks are
+ * streamed as additive `data-agent-task-plan` / `data-agent-task-update`
+ * SSE chunks and rendered above raw tool-call rows in `<AiChat>`.
+ *
+ * `source: 'runtime'` tasks are derived from tool lifecycle events by the
+ * agent runtime. `source: 'agent'` tasks are emitted through the reserved
+ * `meta.update_task_plan` helper and sanitized before they reach the client.
+ */
+export interface AiAgentTaskSnapshot {
+  id: string
+  label: string
+  state: 'pending' | 'running' | 'done' | 'failed' | 'skipped'
+  detail?: string
+  source: 'runtime' | 'agent'
+  toolCallId?: string
+}
+
 export interface AiChatMessage {
   id: string
   role: 'user' | 'assistant'
@@ -52,6 +72,12 @@ export interface AiChatMessage {
    * the UI-part registry never surfaces.
    */
   uiParts?: AiChatMessageUiPart[]
+  /**
+   * Client-local visible task plan derived from streamed
+   * `data-agent-task-plan` snapshots and `data-agent-task-update` deltas.
+   * Not persisted in any chat storage payload.
+   */
+  taskPlan?: AiAgentTaskSnapshot[]
 }
 
 export interface UseAiChatInput {
@@ -294,11 +320,78 @@ interface AssistantBuilderState {
   reasoning: string
   reasoningStreaming: boolean
   toolCalls: AiChatToolCallSnapshot[]
+  toolCallCaptions: Record<string, string>
+  internalToolCallIds: string[]
   uiParts: AiChatMessageUiPart[]
+  taskPlan: AiAgentTaskSnapshot[]
 }
 
 function createBuilder(): AssistantBuilderState {
-  return { text: '', reasoning: '', reasoningStreaming: false, toolCalls: [], uiParts: [] }
+  return {
+    text: '',
+    reasoning: '',
+    reasoningStreaming: false,
+    toolCalls: [],
+    toolCallCaptions: {},
+    internalToolCallIds: [],
+    uiParts: [],
+    taskPlan: [],
+  }
+}
+
+const VALID_TASK_STATES: ReadonlySet<AiAgentTaskSnapshot['state']> = new Set([
+  'pending',
+  'running',
+  'done',
+  'failed',
+  'skipped',
+])
+const VALID_TASK_SOURCES: ReadonlySet<AiAgentTaskSnapshot['source']> = new Set(['runtime', 'agent'])
+
+function coerceTaskSnapshot(raw: unknown): AiAgentTaskSnapshot | null {
+  if (!raw || typeof raw !== 'object') return null
+  const value = raw as Record<string, unknown>
+  const id = typeof value.id === 'string' ? value.id.trim() : ''
+  if (!id) return null
+  const label = typeof value.label === 'string' ? value.label : ''
+  if (!label) return null
+  const state = VALID_TASK_STATES.has(value.state as AiAgentTaskSnapshot['state'])
+    ? (value.state as AiAgentTaskSnapshot['state'])
+    : 'pending'
+  const source = VALID_TASK_SOURCES.has(value.source as AiAgentTaskSnapshot['source'])
+    ? (value.source as AiAgentTaskSnapshot['source'])
+    : 'runtime'
+  const detail = typeof value.detail === 'string' && value.detail.length > 0 ? value.detail : undefined
+  const toolCallId =
+    typeof value.toolCallId === 'string' && value.toolCallId.length > 0 ? value.toolCallId : undefined
+  return { id, label, state, source, detail, toolCallId }
+}
+
+const TERMINAL_TASK_STATES: ReadonlySet<AiAgentTaskSnapshot['state']> = new Set([
+  'done',
+  'failed',
+  'skipped',
+])
+
+function mergeTaskSnapshot(
+  current: AiAgentTaskSnapshot[],
+  incoming: AiAgentTaskSnapshot,
+): AiAgentTaskSnapshot[] {
+  const idx = current.findIndex((task) => task.id === incoming.id)
+  if (idx === -1) return [...current, incoming]
+  const prior = current[idx]
+  // Stream ordering safeguard: once a task reaches a terminal state we keep
+  // it terminal so a late "running" event cannot revert it (spec §Risks —
+  // "Stream ordering bugs cause stale statuses").
+  const nextState = TERMINAL_TASK_STATES.has(prior.state) ? prior.state : incoming.state
+  const merged: AiAgentTaskSnapshot = {
+    ...prior,
+    ...incoming,
+    state: nextState,
+  }
+  const next = current.slice()
+  next[idx] = merged
+  return next
 }
 
 /**
@@ -421,6 +514,7 @@ function updateToolCall(
     const next: AiChatToolCallSnapshot = {
       id,
       toolName: patch.toolName ?? 'tool',
+      caption: patch.caption ?? state.toolCallCaptions[id],
       state: patch.state ?? 'pending',
       input: patch.input,
       output: patch.output,
@@ -432,6 +526,7 @@ function updateToolCall(
   const merged: AiChatToolCallSnapshot = {
     ...current,
     toolName: patch.toolName ?? current.toolName,
+    caption: patch.caption ?? current.caption,
     state: patch.state ?? current.state,
     input: patch.input !== undefined ? patch.input : current.input,
     output: patch.output !== undefined ? patch.output : current.output,
@@ -442,11 +537,40 @@ function updateToolCall(
   return { ...state, toolCalls: nextCalls }
 }
 
+function updateToolCallCaption(
+  state: AssistantBuilderState,
+  toolCallId: string | undefined,
+  caption: string,
+): AssistantBuilderState {
+  if (!toolCallId || !caption) return state
+  const toolCallCaptions = { ...state.toolCallCaptions, [toolCallId]: caption }
+  const idx = state.toolCalls.findIndex((entry) => entry.id === toolCallId)
+  if (idx === -1) return { ...state, toolCallCaptions }
+  const nextCalls = state.toolCalls.slice()
+  nextCalls[idx] = { ...nextCalls[idx], caption }
+  return { ...state, toolCallCaptions, toolCalls: nextCalls }
+}
+
 function displayToolName(toolName: unknown): string | undefined {
   if (typeof toolName !== 'string') return undefined
   return toolName.replace(/__/g, '.')
 }
 
+function isInternalTaskPlanTool(toolName: unknown): boolean {
+  return displayToolName(toolName) === 'meta.update_task_plan'
+}
+
+function markInternalToolCall(state: AssistantBuilderState, toolCallId: unknown): AssistantBuilderState {
+  const id = String(toolCallId ?? '')
+  if (!id || state.internalToolCallIds.includes(id)) return state
+  return { ...state, internalToolCallIds: [...state.internalToolCallIds, id] }
+}
+
+function isInternalToolCallId(state: AssistantBuilderState, toolCallId: unknown): boolean {
+  const id = String(toolCallId ?? '')
+  return id.length > 0 && state.internalToolCallIds.includes(id)
+}
+
 function applyChunk(
   state: AssistantBuilderState,
   chunk: { type: string; [key: string]: unknown },
@@ -469,11 +593,13 @@ function applyChunk(
     case 'reasoning-end':
       return { ...state, reasoningStreaming: false }
     case 'tool-input-start':
+      if (isInternalTaskPlanTool(chunk.toolName)) return markInternalToolCall(state, chunk.toolCallId)
       return updateToolCall(state, String(chunk.toolCallId ?? ''), {
         toolName: displayToolName(chunk.toolName),
         state: 'pending',
       })
     case 'tool-input-available':
+      if (isInternalTaskPlanTool(chunk.toolName)) return markInternalToolCall(state, chunk.toolCallId)
       return updateToolCall(state, String(chunk.toolCallId ?? ''), {
         toolName: displayToolName(chunk.toolName),
         input: chunk.input,
@@ -481,6 +607,7 @@ function applyChunk(
       })
     case 'tool-output-available': {
       const toolCallId = String(chunk.toolCallId ?? '')
+      if (isInternalToolCallId(state, toolCallId)) return state
       const next = updateToolCall(state, toolCallId, {
         output: chunk.output,
         state: 'complete',
@@ -504,12 +631,14 @@ function applyChunk(
       return { ...next, uiParts: merged }
     }
     case 'tool-output-error':
+      if (isInternalToolCallId(state, chunk.toolCallId)) return state
       return updateToolCall(state, String(chunk.toolCallId ?? ''), {
         state: 'error',
         errorMessage:
           typeof chunk.errorText === 'string' ? chunk.errorText : 'Tool error',
       })
     case 'tool-input-error':
+      if (isInternalTaskPlanTool(chunk.toolName)) return markInternalToolCall(state, chunk.toolCallId)
       return updateToolCall(state, String(chunk.toolCallId ?? ''), {
         toolName: displayToolName(chunk.toolName),
         input: chunk.input,
@@ -517,6 +646,29 @@ function applyChunk(
         errorMessage:
           typeof chunk.errorText === 'string' ? chunk.errorText : 'Tool error',
       })
+    case 'data-agent-task-plan': {
+      // Initial / replacement plan snapshot. The agent runtime emits this
+      // when the first task in a turn becomes visible. Subsequent
+      // `data-agent-task-update` events patch individual tasks.
+      const rawTasks = Array.isArray(chunk.tasks) ? chunk.tasks : []
+      const coerced = rawTasks
+        .map(coerceTaskSnapshot)
+        .filter((task): task is AiAgentTaskSnapshot => task !== null)
+      if (coerced.length === 0) return state
+      return coerced.reduce(
+        (nextState, task) => updateToolCallCaption(nextState, task.toolCallId, task.label),
+        { ...state, taskPlan: coerced },
+      )
+    }
+    case 'data-agent-task-update': {
+      const incoming = coerceTaskSnapshot(chunk.task)
+      if (!incoming) return state
+      return updateToolCallCaption(
+        { ...state, taskPlan: mergeTaskSnapshot(state.taskPlan, incoming) },
+        incoming.toolCallId,
+        incoming.label,
+      )
+    }
     default:
       return state
   }
@@ -533,6 +685,7 @@ function mergeAssistantMessage(
     reasoningStreaming: state.reasoning ? state.reasoningStreaming : undefined,
     toolCalls: state.toolCalls.length > 0 ? state.toolCalls : undefined,
     uiParts: state.uiParts.length > 0 ? state.uiParts : undefined,
+    taskPlan: state.taskPlan.length > 0 ? state.taskPlan : undefined,
   }
 }
 

package/src/backend/DataTable.tsx

@@ -34,6 +34,7 @@ import { apiCall } from './utils/apiCall'
 import { raiseCrudError } from './utils/serverErrors'
 import { PerspectiveSidebar } from './PerspectiveSidebar'
 import { Popover, PopoverTrigger, PopoverContent } from '../primitives/popover'
+import { formatWithPublicDateFormat, normalizeDateFormatPattern } from '../primitives/date-format'
 import { cn } from '@open-mercato/shared/lib/utils'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { flash } from './FlashMessages'
@@ -1327,26 +1328,15 @@ export function DataTable<T>({
     return <RowActions items={injectedItems} />
   }, [injectedRowActions, rowActions, router, t])
 
-  // Date formatting setup
-  const DATE_FORMAT = (process.env.NEXT_PUBLIC_DATE_FORMAT || 'YYYY-MM-DD HH:mm') as string
-
-  const pad2 = (n: number) => (n < 10 ? `0${n}` : String(n))
-  const simpleFormat = (d: Date, fmt: string) => {
-    // Supports tokens: YYYY, MM, DD, HH, mm, ss
-    const YYYY = String(d.getFullYear())
-    const MM = pad2(d.getMonth() + 1)
-    const DD = pad2(d.getDate())
-    const HH = pad2(d.getHours())
-    const mm = pad2(d.getMinutes())
-    const ss = pad2(d.getSeconds())
-    return fmt
-      .replace(/YYYY/g, YYYY)
-      .replace(/MM/g, MM)
-      .replace(/DD/g, DD)
-      .replace(/HH/g, HH)
-      .replace(/mm/g, mm)
-      .replace(/ss/g, ss)
-  }
+  // Date formatting setup. The OM-prefixed env vars are the new public contract;
+  // NEXT_PUBLIC_DATE_FORMAT remains supported for existing apps.
+  const DATE_FORMAT = (
+    normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_TIME_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_TIME_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_FORMAT)
+    ?? 'yyyy-MM-dd HH:mm'
+  )
 
   const tryParseDate = (v: unknown): Date | null => {
     if (v == null) return null
@@ -2787,7 +2777,7 @@ export function DataTable<T>({
                       if (isDateCol) {
                         const raw = cell.getValue() as any
                         const d = tryParseDate(raw)
-                        content = d ? simpleFormat(d, DATE_FORMAT) : (raw as any)
+                        content = d ? (formatWithPublicDateFormat(d, DATE_FORMAT) ?? raw) : (raw as any)
                       } else {
                         content = flexRender(cell.column.columnDef.cell, cell.getContext())
                       }
@@ -2810,7 +2800,7 @@ export function DataTable<T>({
                         tooltipText = metaTooltipContent(row.original)
                       } else if (isDateCol && cellValue != null) {
                         const parsedDate = tryParseDate(cellValue)
-                        tooltipText = parsedDate ? simpleFormat(parsedDate, DATE_FORMAT) : String(cellValue)
+                        tooltipText = parsedDate ? (formatWithPublicDateFormat(parsedDate, DATE_FORMAT) ?? String(cellValue)) : String(cellValue)
                       } else {
                         tooltipText = cellValue != null ? String(cellValue) : undefined
                       }

package/src/primitives/__tests__/date-format.test.ts

@@ -0,0 +1,43 @@
+import {
+  deriveDateDisplayFormat,
+  formatWithPublicDateFormat,
+  normalizeDateFormatPattern,
+  resolvePublicDateFormat,
+  resolvePublicDateTimeFormat,
+} from '../date-format'
+
+const ORIGINAL_ENV = { ...process.env }
+
+afterEach(() => {
+  process.env = { ...ORIGINAL_ENV }
+})
+
+describe('date display format helpers', () => {
+  it('derives a system-style fallback from the locale family', () => {
+    expect(deriveDateDisplayFormat('en')).toBe('MMM d, yyyy')
+    expect(deriveDateDisplayFormat('pl')).toBe('d MMM yyyy')
+  })
+
+  it('normalizes legacy uppercase tokens for date-fns', () => {
+    expect(normalizeDateFormatPattern('YYYY-MM-DD HH:mm')).toBe('yyyy-MM-dd HH:mm')
+  })
+
+  it('treats system-like env values as unset', () => {
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'system'
+    expect(resolvePublicDateFormat('en')).toBe('MMM d, yyyy')
+  })
+
+  it('uses OM-prefixed env formats before legacy env formats', () => {
+    process.env.NEXT_PUBLIC_DATE_FORMAT = 'YYYY/MM/DD'
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'dd.MM.yyyy'
+    process.env.NEXT_PUBLIC_OM_DATE_TIME_FORMAT = 'dd.MM.yyyy HH:mm'
+
+    expect(resolvePublicDateFormat('en')).toBe('dd.MM.yyyy')
+    expect(resolvePublicDateTimeFormat('en')).toBe('dd.MM.yyyy HH:mm')
+  })
+
+  it('formats with normalized date-fns patterns', () => {
+    const value = formatWithPublicDateFormat(new Date(2026, 4, 9, 10, 30), 'yyyy-MM-dd HH:mm')
+    expect(value).toBe('2026-05-09 10:30')
+  })
+})

package/src/primitives/date-format.ts

@@ -0,0 +1,60 @@
+import { format as formatDateFns } from 'date-fns'
+import type { Locale } from 'date-fns'
+
+type LocaleLike = Locale | string | null | undefined
+
+const DAY_FIRST_LOCALE_CODES = new Set([
+  'pl', 'de', 'fr', 'es', 'it', 'pt', 'nl', 'ru', 'cs', 'sk', 'hu', 'ro',
+])
+
+const SYSTEM_FORMAT_VALUES = new Set(['auto', 'default', 'locale', 'system'])
+
+function getLocaleCode(locale?: LocaleLike): string {
+  if (!locale) return ''
+  if (typeof locale === 'string') return locale.split('-')[0]?.toLowerCase() ?? ''
+  return locale.code?.split('-')[0]?.toLowerCase() ?? ''
+}
+
+export function normalizeDateFormatPattern(value: string | null | undefined): string | null {
+  const trimmed = value?.trim()
+  if (!trimmed) return null
+  if (SYSTEM_FORMAT_VALUES.has(trimmed.toLowerCase())) return null
+  return trimmed
+    .replace(/YYYY/g, 'yyyy')
+    .replace(/YY/g, 'yy')
+    .replace(/DD/g, 'dd')
+}
+
+export function deriveDateDisplayFormat(locale?: LocaleLike): string {
+  const code = getLocaleCode(locale)
+  return code && DAY_FIRST_LOCALE_CODES.has(code) ? 'd MMM yyyy' : 'MMM d, yyyy'
+}
+
+export function resolvePublicDateFormat(locale?: LocaleLike, explicitFormat?: string | null): string {
+  return (
+    normalizeDateFormatPattern(explicitFormat)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_FORMAT)
+    ?? deriveDateDisplayFormat(locale)
+  )
+}
+
+export function resolvePublicDateTimeFormat(locale?: LocaleLike, explicitFormat?: string | null): string {
+  const dateFormat = deriveDateDisplayFormat(locale)
+  return (
+    normalizeDateFormatPattern(explicitFormat)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_TIME_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_TIME_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_FORMAT)
+    ?? `${dateFormat} HH:mm`
+  )
+}
+
+export function formatWithPublicDateFormat(date: Date, format: string, locale?: Locale): string | null {
+  try {
+    return formatDateFns(date, format, locale ? { locale } : undefined)
+  } catch {
+    return null
+  }
+}

package/src/primitives/date-picker.tsx

@@ -1,7 +1,6 @@
 "use client"
 
 import * as React from 'react'
-import { format } from 'date-fns'
 import type { Locale } from 'date-fns'
 import { CalendarIcon } from 'lucide-react'
 import { cn } from '@open-mercato/shared/lib/utils'
@@ -11,6 +10,7 @@ import { Calendar } from './calendar'
 import { Button } from './button'
 import { LinkButton } from './link-button'
 import { TimeInput } from '../backend/inputs/TimeInput'
+import { formatWithPublicDateFormat, resolvePublicDateFormat, resolvePublicDateTimeFormat } from './date-format'
 
 export type DatePickerFooter = 'apply-cancel' | 'today-clear' | 'none'
 
@@ -62,16 +62,6 @@ export type DatePickerProps = {
   'aria-describedby'?: string
 }
 
-const DAY_FIRST_LOCALE_CODES = new Set([
-  'pl', 'de', 'fr', 'es', 'it', 'pt', 'nl', 'ru', 'cs', 'sk', 'hu', 'ro',
-])
-
-function deriveDisplayFormat(locale: Locale | undefined, withTime: boolean): string {
-  const code = locale?.code?.split('-')[0]?.toLowerCase() ?? ''
-  const dateFmt = code && DAY_FIRST_LOCALE_CODES.has(code) ? 'd MMM yyyy' : 'MMM d, yyyy'
-  return withTime ? `${dateFmt} HH:mm` : dateFmt
-}
-
 function extractTime(date: Date): string {
   return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`
 }
@@ -129,7 +119,9 @@ export function DatePicker({
     if (open) setDraft(value ?? null)
   }, [open, value])
 
-  const resolvedFormat = displayFormat ?? deriveDisplayFormat(locale, withTime)
+  const resolvedFormat = withTime
+    ? resolvePublicDateTimeFormat(locale, displayFormat)
+    : resolvePublicDateFormat(locale, displayFormat)
   const placeholderText = placeholder ?? (
     withTime
       ? t('ui.dateTimePicker.placeholder', 'Pick date and time')
@@ -138,11 +130,7 @@ export function DatePicker({
 
   const formattedValue = React.useMemo(() => {
     if (!value) return null
-    try {
-      return format(value, resolvedFormat, locale ? { locale } : undefined)
-    } catch {
-      return null
-    }
+    return formatWithPublicDateFormat(value, resolvedFormat, locale)
   }, [value, resolvedFormat, locale])
 
   const handleDaySelect = React.useCallback(

package/src/primitives/date-range-picker.tsx

@@ -1,7 +1,6 @@
 "use client"
 
 import * as React from 'react'
-import { format } from 'date-fns'
 import type { Locale } from 'date-fns'
 import { CalendarIcon } from 'lucide-react'
 import { cn } from '@open-mercato/shared/lib/utils'
@@ -15,6 +14,7 @@ import {
   defaultDateRangePresets,
   type DateRangePresetItem,
 } from './date-picker-helpers'
+import { formatWithPublicDateFormat, resolvePublicDateFormat } from './date-format'
 
 export type { DateRangePresetItem } from './date-picker-helpers'
 
@@ -43,19 +43,9 @@ export type DateRangePickerProps = {
   'aria-describedby'?: string
 }
 
-const DAY_FIRST_LOCALE_CODES = new Set([
-  'pl', 'de', 'fr', 'es', 'it', 'pt', 'nl', 'ru', 'cs', 'sk', 'hu', 'ro',
-])
-
-function deriveDateFormat(locale?: Locale): string {
-  const code = locale?.code?.split('-')[0]?.toLowerCase() ?? ''
-  return code && DAY_FIRST_LOCALE_CODES.has(code) ? 'd MMM yyyy' : 'MMM d, yyyy'
-}
-
 function defaultFormatRange(range: DateRange, locale?: Locale): string {
-  const fmt = deriveDateFormat(locale)
-  const opts = locale ? { locale } : undefined
-  return `${format(range.start, fmt, opts)} – ${format(range.end, fmt, opts)}`
+  const fmt = resolvePublicDateFormat(locale)
+  return `${formatWithPublicDateFormat(range.start, fmt, locale) ?? ''} – ${formatWithPublicDateFormat(range.end, fmt, locale) ?? ''}`
 }
 
 function toRDPRange(range: DateRange | null | undefined): RDPRange | undefined {