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

package/src/modules/ai_assistant/ai-tools/__tests__/meta-pack.test.ts

@@ -3,7 +3,8 @@
  *
  * Covers `list_agents` empty-registry graceful case, RBAC filtering,
  * super-admin bypass, `describe_agent` not-found / forbidden / happy,
- * and the `output.schema` JSON-Schema fallback.
+ * `update_task_plan` sanitization, and the `output.schema` JSON-Schema
+ * fallback.
  */
 import { z } from 'zod'
 import type { AiAgentDefinition } from '../../lib/ai-agent-definition'
@@ -148,6 +149,7 @@ describe('meta.describe_agent', () => {
         readOnly: true,
         mutationPolicy: 'read-only',
         acceptedMediaTypes: ['image', 'pdf'],
+        taskPlan: { enabled: true },
         maxSteps: 6,
         output: { schemaName: 'MerchProposal', schema, mode: 'generate' },
         keywords: ['catalog', 'merch'],
@@ -159,9 +161,14 @@ describe('meta.describe_agent', () => {
     const agent = result.agent as Record<string, unknown>
     expect(agent.id).toBe('catalog.merch')
     expect(agent.executionMode).toBe('object')
-    expect(agent.allowedTools).toEqual(['search.hybrid_search', 'catalog.get_product_bundle'])
+    expect(agent.allowedTools).toEqual([
+      'search.hybrid_search',
+      'catalog.get_product_bundle',
+      'meta.update_task_plan',
+    ])
     expect(agent.readOnly).toBe(true)
     expect(agent.acceptedMediaTypes).toEqual(['image', 'pdf'])
+    expect(agent.taskPlan).toEqual({ enabled: true })
     const output = agent.output as Record<string, unknown>
     expect(output.schemaName).toBe('MerchProposal')
     expect(output.jsonSchema).toBeDefined()
@@ -206,10 +213,59 @@ describe('meta.describe_agent', () => {
   })
 })
 
+describe('meta.update_task_plan', () => {
+  const tool = findTool('meta.update_task_plan')
+
+  it('returns sanitized user-visible task labels', async () => {
+    const ctx = makeCtx()
+    const result = (await tool.handler(
+      {
+        tasks: [
+          {
+            id: ' step one ',
+            label: '  Search catalog products  ',
+            detail: '  Use product search  ',
+            toolName: 'catalog__search_products',
+          },
+        ],
+      },
+      ctx as any,
+    )) as Record<string, unknown>
+
+    expect(result.ok).toBe(true)
+    expect(result.accepted).toBe(1)
+    expect(result.tasks).toEqual([
+      {
+        id: 'step-one',
+        label: 'Search catalog products',
+        detail: 'Use product search',
+        toolName: 'catalog.search_products',
+      },
+    ])
+  })
+
+  it('rejects hidden-reasoning-like labels at schema validation', () => {
+    expect(() =>
+      tool.inputSchema.parse({
+        tasks: [
+          {
+            label: '<thinking>First I will inspect private chain of thought</thinking>',
+          },
+        ],
+      }),
+    ).toThrow(/private reasoning|Task-plan labels/i)
+  })
+
+  it('does not expose mutation capability', () => {
+    expect(tool.isMutation).not.toBe(true)
+    expect(tool.requiredFeatures).toEqual(['ai_assistant.view'])
+  })
+})
+
 describe('meta-pack tool surface', () => {
-  it('exports the two read-only meta tools', () => {
+  it('exports the read-only meta tools', () => {
     const names = metaAiTools.map((tool) => tool.name)
-    expect(names).toEqual(['meta.list_agents', 'meta.describe_agent'])
+    expect(names).toEqual(['meta.list_agents', 'meta.describe_agent', 'meta.update_task_plan'])
     for (const tool of metaAiTools) {
       expect(tool.isMutation).not.toBe(true)
       expect(tool.requiredFeatures).toEqual(['ai_assistant.view'])

package/src/modules/ai_assistant/ai-tools/meta-pack.ts

@@ -12,7 +12,15 @@ import type { AiAgentDefinition } from '../lib/ai-agent-definition'
 import { listAgents, getAgent } from '../lib/agent-registry'
 import { hasRequiredFeatures } from '../lib/auth'
 import { defineAiTool } from '../lib/ai-tool-definition'
-import type { AiToolDefinition } from '../lib/types'
+import {
+  TASK_PLAN_DETAIL_MAX_CHARS,
+  TASK_PLAN_ID_MAX_CHARS,
+  TASK_PLAN_LABEL_MAX_CHARS,
+  TASK_PLAN_MAX_TASKS,
+  TASK_PLAN_TOOL_NAME_MAX_CHARS,
+  looksLikeHiddenReasoning,
+  sanitizeAgentTaskPlanInput,
+} from '../lib/task-plan-labels'
 
 function summarizeAgent(agent: AiAgentDefinition): Record<string, unknown> {
   return {
@@ -30,6 +38,7 @@ function summarizeAgent(agent: AiAgentDefinition): Record<string, unknown> {
     domain: agent.domain ?? null,
     keywords: agent.keywords ?? [],
     suggestions: agent.suggestions ?? [],
+    taskPlan: agent.taskPlan ?? { enabled: false },
     dataCapabilities: agent.dataCapabilities ?? null,
     hasOutputSchema: Boolean(agent.output),
     hasPageContextResolver: typeof agent.resolvePageContext === 'function',
@@ -135,6 +144,74 @@ const describeAgentTool = defineAiTool({
   },
 })
 
-export const metaAiTools: AiToolDefinition<any, any>[] = [listAgentsTool, describeAgentTool]
+const visibleTaskLabel = z
+  .string()
+  .min(1)
+  .max(TASK_PLAN_LABEL_MAX_CHARS)
+  .superRefine((value, ctx) => {
+    if (!looksLikeHiddenReasoning(value)) return
+    ctx.addIssue({
+      code: 'custom',
+      message: 'Task-plan labels are user-visible UI copy and must not include private reasoning.',
+    })
+  })
+
+const visibleTaskDetail = z
+  .string()
+  .max(TASK_PLAN_DETAIL_MAX_CHARS)
+  .optional()
+  .superRefine((value, ctx) => {
+    if (!value || !looksLikeHiddenReasoning(value)) return
+    ctx.addIssue({
+      code: 'custom',
+      message: 'Task-plan details must not include private reasoning.',
+    })
+  })
+
+const updateTaskPlanInput = z.object({
+  tasks: z
+    .array(
+      z.object({
+        id: z.string().min(1).max(TASK_PLAN_ID_MAX_CHARS).optional(),
+        label: visibleTaskLabel.describe('Concise user-visible step label. Do not include private reasoning.'),
+        detail: visibleTaskDetail.describe('Optional short visible detail, not private reasoning.'),
+        toolName: z
+          .string()
+          .min(1)
+          .max(TASK_PLAN_TOOL_NAME_MAX_CHARS)
+          .optional()
+          .describe('Optional whitelisted tool name that this planned step maps to.'),
+      }),
+    )
+    .min(1)
+    .max(TASK_PLAN_MAX_TASKS),
+})
+
+const updateTaskPlanTool = defineAiTool({
+  name: 'meta.update_task_plan',
+  displayName: 'Update task plan',
+  description:
+    'Set the concise user-visible task plan for this assistant turn before calling domain tools. Labels are progress UI, not hidden reasoning.',
+  inputSchema: updateTaskPlanInput,
+  requiredFeatures: ['ai_assistant.view'],
+  tags: ['read', 'meta', 'task-plan'],
+  isMutation: false,
+  handler: async (rawInput) => {
+    const input = updateTaskPlanInput.parse(rawInput)
+    const sanitized = sanitizeAgentTaskPlanInput(input)
+    return {
+      ok: sanitized.tasks.length > 0,
+      tasks: sanitized.tasks,
+      accepted: sanitized.tasks.length,
+      dropped: input.tasks.length - sanitized.tasks.length,
+    }
+  },
+})
+
+export const metaAiTools = [
+  listAgentsTool,
+  describeAgentTool,
+  updateTaskPlanTool,
+]
 
 export default metaAiTools

package/src/modules/ai_assistant/api/ai/agents/route.ts

@@ -4,7 +4,7 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
-import { listAgents, loadAgentRegistry } from '../../../lib/agent-registry'
+import { isAgentTaskPlanEnabled, listAgents, loadAgentRegistry } from '../../../lib/agent-registry'
 import { hasRequiredFeatures } from '../../../lib/auth'
 import { toolRegistry } from '../../../lib/tool-registry'
 import type { AiToolDefinition } from '../../../lib/types'
@@ -90,6 +90,7 @@ export async function GET(req: NextRequest) {
         mutationPolicy: agent.mutationPolicy ?? 'read-only',
         readOnly: Boolean(agent.readOnly),
         maxSteps: agent.maxSteps ?? null,
+        taskPlan: { enabled: isAgentTaskPlanEnabled(agent) },
         allowedTools: agent.allowedTools,
         tools,
         requiredFeatures: agent.requiredFeatures ?? [],

package/src/modules/ai_assistant/backend/config/ai-assistant/agents/AiAgentSettingsPageClient.tsx

@@ -75,6 +75,7 @@ type AgentSettings = {
   mutationPolicy: string
   readOnly: boolean
   maxSteps: number | null
+  taskPlan?: { enabled?: boolean }
   allowedTools: string[]
   tools: AgentTool[]
   requiredFeatures: string[]

package/src/modules/ai_assistant/i18n/de.json

@@ -146,7 +146,7 @@
   "ai_assistant.allowlist.save.success": "Liste gespeichert.",
   "ai_assistant.allowlist.subtitle": "Schränke Anbieter und Modelle ein, die für diesen Mandanten verwendet werden dürfen. Die ENV-Liste ist die äußere Beschränkung — die Mandantenauswahl engt sie weiter ein.",
   "ai_assistant.allowlist.title": "Anbieter- & Modell-Allowlist",
-  "ai_assistant.chat.agentTasksTitle": "Agent-Aufgaben",
+  "ai_assistant.chat.agentTasksTitle": "Tool-Aufrufe",
   "ai_assistant.chat.assistantRoleLabel": "Assistent",
   "ai_assistant.chat.attachFile": "Attach file",
   "ai_assistant.chat.betaChip": "beta",
@@ -257,6 +257,12 @@
   "ai_assistant.chat.tabs.noSessions": "Keine Sitzungen",
   "ai_assistant.chat.tabs.recentSessions": "Letzte Sitzungen",
   "ai_assistant.chat.tabs.rename": "Umbenennen",
+  "ai_assistant.chat.taskDone": "fertig",
+  "ai_assistant.chat.taskFailed": "fehlgeschlagen",
+  "ai_assistant.chat.taskPending": "ausstehend",
+  "ai_assistant.chat.taskPlanTitle": "Plan",
+  "ai_assistant.chat.taskRunning": "läuft…",
+  "ai_assistant.chat.taskSkipped": "übersprungen",
   "ai_assistant.chat.thinking": "Denkt nach...",
   "ai_assistant.chat.toolDone": "done",
   "ai_assistant.chat.toolError": "failed",

package/src/modules/ai_assistant/i18n/en.json

@@ -146,7 +146,7 @@
   "ai_assistant.allowlist.save.success": "Allowlist saved.",
   "ai_assistant.allowlist.subtitle": "Limit which providers and models the runtime, settings, and chat picker may use for this tenant. The env allowlist is the outer constraint — tenant picks narrow it further.",
   "ai_assistant.allowlist.title": "AI provider & model allowlist",
-  "ai_assistant.chat.agentTasksTitle": "Agent tasks",
+  "ai_assistant.chat.agentTasksTitle": "Tool calls",
   "ai_assistant.chat.assistantRoleLabel": "Assistant",
   "ai_assistant.chat.attachFile": "Attach file",
   "ai_assistant.chat.betaChip": "beta",
@@ -257,6 +257,12 @@
   "ai_assistant.chat.tabs.noSessions": "No sessions",
   "ai_assistant.chat.tabs.recentSessions": "Recent sessions",
   "ai_assistant.chat.tabs.rename": "Rename",
+  "ai_assistant.chat.taskDone": "done",
+  "ai_assistant.chat.taskFailed": "failed",
+  "ai_assistant.chat.taskPending": "pending",
+  "ai_assistant.chat.taskPlanTitle": "Plan",
+  "ai_assistant.chat.taskRunning": "running…",
+  "ai_assistant.chat.taskSkipped": "skipped",
   "ai_assistant.chat.thinking": "Thinking...",
   "ai_assistant.chat.toolDone": "done",
   "ai_assistant.chat.toolError": "failed",

package/src/modules/ai_assistant/i18n/es.json

@@ -146,7 +146,7 @@
   "ai_assistant.allowlist.save.success": "Lista guardada.",
   "ai_assistant.allowlist.subtitle": "Limita los proveedores y modelos que el runtime, los ajustes y el selector de chat pueden usar para este inquilino. La lista ENV es la restricción externa — las elecciones del inquilino la reducen.",
   "ai_assistant.allowlist.title": "Lista de proveedores y modelos AI",
-  "ai_assistant.chat.agentTasksTitle": "Tareas del agente",
+  "ai_assistant.chat.agentTasksTitle": "Llamadas a herramientas",
   "ai_assistant.chat.assistantRoleLabel": "Asistente",
   "ai_assistant.chat.attachFile": "Attach file",
   "ai_assistant.chat.betaChip": "beta",
@@ -257,6 +257,12 @@
   "ai_assistant.chat.tabs.noSessions": "Sin sesiones",
   "ai_assistant.chat.tabs.recentSessions": "Sesiones recientes",
   "ai_assistant.chat.tabs.rename": "Renombrar",
+  "ai_assistant.chat.taskDone": "hecho",
+  "ai_assistant.chat.taskFailed": "fallido",
+  "ai_assistant.chat.taskPending": "pendiente",
+  "ai_assistant.chat.taskPlanTitle": "Plan",
+  "ai_assistant.chat.taskRunning": "en curso…",
+  "ai_assistant.chat.taskSkipped": "omitido",
   "ai_assistant.chat.thinking": "Pensando...",
   "ai_assistant.chat.toolDone": "done",
   "ai_assistant.chat.toolError": "failed",

package/src/modules/ai_assistant/i18n/pl.json

@@ -146,7 +146,7 @@
   "ai_assistant.allowlist.save.success": "Lista zapisana.",
   "ai_assistant.allowlist.subtitle": "Ogranicz dostawców i modele dostępne dla tego najemcy. Lista ENV jest zewnętrznym ograniczeniem — wybory najemcy je zawężają.",
   "ai_assistant.allowlist.title": "Lista dozwolonych dostawców i modeli AI",
-  "ai_assistant.chat.agentTasksTitle": "Zadania agenta",
+  "ai_assistant.chat.agentTasksTitle": "Wywołania narzędzi",
   "ai_assistant.chat.assistantRoleLabel": "Asystent",
   "ai_assistant.chat.attachFile": "Attach file",
   "ai_assistant.chat.betaChip": "beta",
@@ -257,6 +257,12 @@
   "ai_assistant.chat.tabs.noSessions": "Brak sesji",
   "ai_assistant.chat.tabs.recentSessions": "Ostatnie sesje",
   "ai_assistant.chat.tabs.rename": "Zmień nazwę",
+  "ai_assistant.chat.taskDone": "ukończono",
+  "ai_assistant.chat.taskFailed": "niepowodzenie",
+  "ai_assistant.chat.taskPending": "oczekuje",
+  "ai_assistant.chat.taskPlanTitle": "Plan",
+  "ai_assistant.chat.taskRunning": "w toku…",
+  "ai_assistant.chat.taskSkipped": "pominięto",
   "ai_assistant.chat.thinking": "Myślenie...",
   "ai_assistant.chat.toolDone": "done",
   "ai_assistant.chat.toolError": "failed",

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

@@ -187,6 +187,66 @@ describe('agent-registry', () => {
     })
   })
 
+  it('adds the internal task-plan tool only when taskPlan is enabled', () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'customers.account_assistant',
+        moduleId: 'customers',
+        allowedTools: ['customers.list_people'],
+        taskPlan: { enabled: true },
+      }),
+      makeAgent({
+        id: 'catalog.catalog_assistant',
+        moduleId: 'catalog',
+        allowedTools: ['catalog.list_products', 'meta.update_task_plan'],
+      }),
+    ])
+
+    expect(getAgent('customers.account_assistant')).toMatchObject({
+      taskPlan: { enabled: true },
+      allowedTools: ['customers.list_people', 'meta.update_task_plan'],
+    })
+    const catalogAgent = getAgent('catalog.catalog_assistant')
+    expect(catalogAgent?.taskPlan).toBeUndefined()
+    expect(catalogAgent?.allowedTools).toEqual(['catalog.list_products'])
+  })
+
+  it('lets extensions opt an existing agent in or out of visible task planning', () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.catalog_assistant',
+        moduleId: 'catalog',
+        allowedTools: ['catalog.list_products'],
+      }),
+      makeAgent({
+        id: 'customers.account_assistant',
+        moduleId: 'customers',
+        allowedTools: ['customers.list_people'],
+        taskPlan: { enabled: true },
+      }),
+    ])
+
+    applyAgentExtensionEntriesForTests([
+      {
+        targetAgentId: 'catalog.catalog_assistant',
+        taskPlan: { enabled: true },
+      },
+      {
+        targetAgentId: 'customers.account_assistant',
+        taskPlan: { enabled: false },
+      },
+    ])
+
+    expect(getAgent('catalog.catalog_assistant')).toMatchObject({
+      taskPlan: { enabled: true },
+      allowedTools: ['catalog.list_products', 'meta.update_task_plan'],
+    })
+    expect(getAgent('customers.account_assistant')).toMatchObject({
+      taskPlan: { enabled: false },
+      allowedTools: ['customers.list_people'],
+    })
+  })
+
   it('resetAgentRegistryForTests clears the cache so a subsequent seed sees fresh fixtures', () => {
     seedAgentRegistryForTests([
       makeAgent({ id: 'catalog.merchandiser', moduleId: 'catalog' }),

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

@@ -71,6 +71,7 @@ describe('defineAiAgentExtension', () => {
       replaceAllowedTools: ['catalog.list_products'],
       deleteAllowedTools: ['catalog.old_tool'],
       appendAllowedTools: ['example.catalog_stats'],
+      taskPlan: { enabled: true },
       replaceSystemPrompt: 'Replacement prompt.',
       appendSystemPrompt: 'Use example.catalog_stats for app-level catalog metrics.',
       replaceSuggestions: [
@@ -86,6 +87,7 @@ describe('defineAiAgentExtension', () => {
     expect(extension.replaceAllowedTools).toEqual(['catalog.list_products'])
     expect(extension.deleteAllowedTools).toEqual(['catalog.old_tool'])
     expect(extension.appendAllowedTools).toEqual(['example.catalog_stats'])
+    expect(extension.taskPlan).toEqual({ enabled: true })
     expect(extension.replaceSystemPrompt).toBe('Replacement prompt.')
     expect(extension.deleteSuggestions).toEqual(['Old prompt'])
     expect(extension.appendSuggestions).toEqual([
@@ -128,6 +130,7 @@ describe('defineAiAgent', () => {
       defaultModel: 'gpt-4o',
       acceptedMediaTypes: ['image', 'pdf', 'file'],
       requiredFeatures: ['catalog.products.view'],
+      taskPlan: { enabled: true },
       uiParts: ['mutation-preview-card'],
       readOnly: true,
       mutationPolicy: 'read-only',
@@ -163,6 +166,7 @@ describe('defineAiAgent', () => {
     expect(agent.domain).toBe('catalog')
     expect(agent.acceptedMediaTypes).toEqual(['image', 'pdf', 'file'])
     expect(agent.requiredFeatures).toEqual(['catalog.products.view'])
+    expect(agent.taskPlan).toEqual({ enabled: true })
     expect(agent.uiParts).toEqual(['mutation-preview-card'])
     expect(agent.readOnly).toBe(true)
     expect(agent.defaultModel).toBe('gpt-4o')

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

@@ -267,6 +267,49 @@ describe('prepareMutation', () => {
     expect(pendingAction.organizationId).toBe('org-alpha')
   })
 
+  it('uses resolver-provided after snapshots and display labels for operator previews', async () => {
+    const em = mockEm()
+    const container = makeContainer(em)
+    const tool = makeTool({
+      name: 'customers.update_deal_stage',
+      isMutation: true,
+      loadBeforeRecord: async () => ({
+        recordId: 'deal-1',
+        entityType: 'customers.deal',
+        recordVersion: 'v-1',
+        before: { pipelineStageId: 'stage-old' },
+        after: { pipelineStageId: 'stage-new' },
+        display: {
+          fieldLabels: { pipelineStageId: 'Pipeline stage' },
+          before: { pipelineStageId: 'Offering' },
+          after: { pipelineStageId: 'Lost' },
+        },
+      }),
+    })
+    const agent = makeAgent({ id: 'customers.deal_analyzer' })
+
+    const { uiPart, pendingAction } = await prepareMutation(
+      {
+        agent,
+        tool,
+        toolCallArgs: { dealId: 'deal-1', toPipelineStageId: 'stage-new' },
+      },
+      { ...baseCtx, container },
+    )
+
+    expect(uiPart.props.fieldDiff).toEqual([
+      {
+        field: 'pipelineStageId',
+        fieldLabel: 'Pipeline stage',
+        before: 'stage-old',
+        after: 'stage-new',
+        beforeDisplay: 'Offering',
+        afterDisplay: 'Lost',
+      },
+    ])
+    expect(pendingAction.fieldDiff).toEqual(uiPart.props.fieldDiff)
+  })
+
   it('batch happy path: populates records[] with per-record diffs (fieldDiff stays []) when isBulk=true', async () => {
     const em = mockEm()
     const container = makeContainer(em)