@open-mercato/ai-assistant 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/src/modules/ai_assistant/__integration__/TC-AI-PLAYGROUND-004-playground.spec.ts

@@ -0,0 +1,333 @@
+import { test, expect } from '@playwright/test';
+import { login } from '@open-mercato/core/modules/core/__integration__/helpers/auth';
+
+/**
+ * TC-AI-PLAYGROUND-004: AI Playground page smoke (Step 4.4 / Phase 2 WS-B).
+ *
+ * Covers the first user-facing embedding of `<AiChat>` in the backoffice. The
+ * route is guarded by `ai_assistant.settings.manage`; superadmin always holds
+ * it. The agent registry may be empty in CI (generated file depends on
+ * module authors registering agents), so the spec handles BOTH branches:
+ *   - populated registry: assert the agent picker, debug toggle, and chat
+ *     surface render;
+ *   - empty registry: assert the `EmptyState` copy renders instead.
+ *
+ * The chat SSE response is stubbed via Playwright's route interception so the
+ * test never has to hit a live LLM provider. The object-mode run-object route
+ * is also stubbed to assert wiring without invoking a real model.
+ */
+test.describe('TC-AI-PLAYGROUND-004: AI Playground', () => {
+  const playgroundPath = '/backend/config/ai-assistant/playground';
+
+  test('playground renders agent picker or empty state for superadmin', async ({ page }) => {
+    await login(page, 'superadmin');
+
+    // Stub the agents list so the test behavior is deterministic regardless of
+    // what the generated registry holds at run-time.
+    await page.route('**/api/ai_assistant/ai/agents', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          agents: [
+            {
+              id: 'customers.assistant',
+              moduleId: 'customers',
+              label: 'Customers assistant',
+              description: 'Answers questions about customer records.',
+              executionMode: 'chat',
+              mutationPolicy: 'read-only',
+              allowedTools: ['customers.list_people'],
+              requiredFeatures: [],
+              acceptedMediaTypes: [],
+              hasOutputSchema: false,
+            },
+            {
+              id: 'catalog.extract',
+              moduleId: 'catalog',
+              label: 'Catalog extractor',
+              description: 'Extracts structured product metadata.',
+              executionMode: 'object',
+              mutationPolicy: 'read-only',
+              allowedTools: [],
+              requiredFeatures: [],
+              acceptedMediaTypes: [],
+              hasOutputSchema: true,
+            },
+          ],
+          total: 2,
+        }),
+      });
+    });
+
+    // Stub the chat SSE so the composer has something to "succeed" against.
+    await page.route('**/api/ai_assistant/ai/chat**', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'text/event-stream',
+        body: 'ok from stubbed SSE\n',
+      });
+    });
+
+    // Stub the run-object dispatcher so the object-mode tab has a deterministic response.
+    await page.route('**/api/ai_assistant/ai/run-object', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          object: { title: 'Stubbed title' },
+          finishReason: 'stop',
+          usage: { inputTokens: 1, outputTokens: 2 },
+        }),
+      });
+    });
+
+    await page.goto(playgroundPath, { waitUntil: 'domcontentloaded' });
+
+    const container = page.locator('[data-ai-playground]');
+    const empty = page.getByText(/No AI agents are registered/i).first();
+    const loadError = page.locator('[data-ai-playground-error]');
+
+    // Wait until the page has stabilized (either container, empty state, or a load error).
+    await expect(container.or(empty).or(loadError)).toBeVisible({ timeout: 15_000 });
+
+    if (await container.isVisible().catch(() => false)) {
+      const picker = page.locator('[data-ai-playground-agent-picker]');
+      await expect(picker).toBeVisible();
+      // Two stubbed agents should surface.
+      const optionCount = await picker.locator('option').count();
+      expect(optionCount).toBeGreaterThanOrEqual(2);
+
+      const debugToggle = page.locator('[data-ai-playground-debug-toggle]');
+      await expect(debugToggle).toBeVisible();
+
+      const composer = page.locator('#ai-chat-composer');
+      await expect(composer).toBeVisible();
+      await composer.fill('Hello from Playwright');
+      await expect(composer).toHaveValue('Hello from Playwright');
+
+      // Step 4.6: toggling the debug panel should reveal the three collapsible
+      // sections (tool map / prompt sections / last request), each addressable
+      // by its `data-ai-chat-debug-section` attribute.
+      const debugPanel = page.locator('[data-ai-chat-debug="true"]');
+      const initiallyVisible = await debugPanel.isVisible().catch(() => false);
+      if (!initiallyVisible) {
+        await debugToggle.click();
+      }
+      await expect(debugPanel).toBeVisible({ timeout: 5_000 });
+      await expect(
+        page.locator('[data-ai-chat-debug-section="tools"]'),
+      ).toBeVisible();
+      await expect(
+        page.locator('[data-ai-chat-debug-section="promptSections"]'),
+      ).toBeVisible();
+      await expect(
+        page.locator('[data-ai-chat-debug-section="lastRequest"]'),
+      ).toBeVisible();
+    } else if (await empty.isVisible().catch(() => false)) {
+      // Empty branch: agent registry is empty in this environment.
+      await expect(empty).toBeVisible();
+    } else {
+      // Fatal load error branch — still acceptable evidence that the guard fired.
+      await expect(loadError).toBeVisible();
+    }
+  });
+
+  test('picker lists all three Phase 2 agents and chat-mode selection disables object-mode tab', async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    await login(page, 'superadmin');
+
+    // Hit the live registry for this scenario — Phase 2 agents are all
+    // chat-mode so we can assert the "not supported" alert on the object
+    // tab without stubbing.
+    await page.goto(playgroundPath, { waitUntil: 'domcontentloaded' });
+
+    const container = page.locator('[data-ai-playground]');
+    await expect(container).toBeVisible({ timeout: 60_000 });
+
+    const picker = page.locator('[data-ai-playground-agent-picker]');
+    await expect(picker).toBeVisible();
+
+    // The three Phase 2 agents must be present.
+    await expect(
+      picker.locator('option[value="customers.account_assistant"]'),
+    ).toHaveCount(1);
+    await expect(
+      picker.locator('option[value="catalog.catalog_assistant"]'),
+    ).toHaveCount(1);
+    await expect(
+      picker.locator('option[value="catalog.merchandising_assistant"]'),
+    ).toHaveCount(1);
+
+    // Switch to the object-mode tab — Phase 2 agents are all chat-mode, so
+    // the "not supported" info Alert should render with the documented
+    // `data-ai-playground-unsupported="object"` marker.
+    await page.getByRole('tab', { name: /object mode/i }).click();
+    await expect(
+      page.locator('[data-ai-playground-unsupported="object"]'),
+    ).toBeVisible();
+
+    // Flip back to chat tab; the `AiChat` region for the currently selected
+    // agent must render.
+    await page.getByRole('tab', { name: /^chat$/i }).click();
+    const chatRegion = page.locator('[data-ai-chat-agent]').first();
+    await expect(chatRegion).toBeVisible();
+  });
+
+  test('chat happy path — stubbed SSE response appears in the transcript', async ({ page }) => {
+    test.setTimeout(120_000);
+    await login(page, 'superadmin');
+
+    // Stub agents so the picker is deterministic.
+    await page.route('**/api/ai_assistant/ai/agents', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          agents: [
+            {
+              id: 'customers.account_assistant',
+              moduleId: 'customers',
+              label: 'Customers account assistant',
+              description: 'Stubbed agent for playground chat smoke.',
+              executionMode: 'chat',
+              mutationPolicy: 'read-only',
+              allowedTools: [],
+              requiredFeatures: [],
+              acceptedMediaTypes: [],
+              hasOutputSchema: false,
+            },
+          ],
+          total: 1,
+        }),
+      });
+    });
+
+    // Stub the SSE dispatcher with a canned text stream the AiChat reader
+    // consumes. The AiChat component writes streamed deltas into the
+    // transcript; we assert the text surfaces regardless of the exact
+    // stream dialect by filling in both a `data:` framed payload and a
+    // plain-text fallback.
+    const streamBody = [
+      'event: text',
+      'data: {"content":"stubbed-playground-reply"}',
+      '',
+      'event: done',
+      'data: {}',
+      '',
+    ].join('\n');
+    await page.route('**/api/ai_assistant/ai/chat**', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'text/event-stream',
+        body: streamBody,
+      });
+    });
+
+    await page.goto(playgroundPath, { waitUntil: 'domcontentloaded' });
+
+    const composer = page.locator('#ai-chat-composer');
+    await expect(composer).toBeVisible({ timeout: 60_000 });
+    await composer.fill('Say hi please');
+    await composer.press('Meta+Enter');
+    // On non-mac runners Meta+Enter is a no-op; try Control+Enter too.
+    await page.waitForTimeout(200);
+    if (!(await page.locator('[data-ai-chat-state="thinking"]').count())) {
+      await composer.press('Control+Enter');
+    }
+
+    // The composer should have been cleared on submit, proving the
+    // handler fired. The SSE stream body itself is driven by the agent
+    // runtime which may surface the text either verbatim or through a
+    // rendered message row — accept either signal.
+    await expect(async () => {
+      const cleared = (await composer.inputValue()) === '';
+      const rendered = await page.getByText(/stubbed-playground-reply/i).count();
+      const thinking = await page.locator('[data-ai-chat-state="thinking"]').count();
+      expect(cleared || rendered > 0 || thinking > 0).toBe(true);
+    }).toPass({ timeout: 10_000 });
+  });
+
+  test('mutation-preview-card renders inside the playground transcript when a pending action is emitted', async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    await login(page, 'superadmin');
+
+    // Deterministic agent registry — a mutation-capable chat agent.
+    await page.route('**/api/ai_assistant/ai/agents', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          agents: [
+            {
+              id: 'customers.account_assistant',
+              moduleId: 'customers',
+              label: 'Customers account assistant',
+              description: 'Mutation-capable agent for Phase 3 approval flow.',
+              executionMode: 'chat',
+              mutationPolicy: 'require-approval',
+              allowedTools: ['customers.update_person'],
+              requiredFeatures: [],
+              acceptedMediaTypes: [],
+              hasOutputSchema: false,
+            },
+          ],
+          total: 1,
+        }),
+      });
+    });
+
+    // Stub the polling endpoint with a pending row so the preview card
+    // resolves its state. The Playwright test never hits a real DB.
+    const pendingRow = {
+      pendingAction: {
+        id: 'pa-stub-001',
+        agentId: 'customers.account_assistant',
+        toolName: 'customers.update_person',
+        status: 'pending',
+        fieldDiff: [
+          { field: 'name', before: 'Alice', after: 'Alicia' },
+        ],
+        records: null,
+        failedRecords: null,
+        sideEffectsSummary: 'Rename Alice to Alicia.',
+        attachmentIds: [],
+        targetEntityType: 'customers.person',
+        targetRecordId: 'p-1',
+        recordVersion: '1',
+        executionResult: null,
+        createdAt: new Date().toISOString(),
+        expiresAt: new Date(Date.now() + 600_000).toISOString(),
+        resolvedAt: null,
+        resolvedByUserId: null,
+      },
+    };
+    await page.route('**/api/ai_assistant/ai/actions/pa-stub-001', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify(pendingRow),
+      });
+    });
+
+    // Navigate with the debug seed that instructs the playground to inject
+    // the `mutation-preview-card` UI part. This is the Step 5.10 stub path
+    // until the dispatcher surfaces UI parts through the streamed body.
+    await page.goto(
+      `${playgroundPath}?uiPart=mutation-preview-card&pendingActionId=pa-stub-001`,
+      { waitUntil: 'domcontentloaded' },
+    );
+
+    const container = page.locator('[data-ai-playground]');
+    await expect(container).toBeVisible({ timeout: 60_000 });
+
+    const previewCard = page.locator('[data-ai-mutation-preview]').first();
+    await expect(previewCard).toBeVisible({ timeout: 15_000 });
+    await expect(page.locator('[data-ai-mutation-preview-confirm]')).toBeVisible();
+    await expect(page.locator('[data-ai-mutation-preview-cancel]')).toBeVisible();
+  });
+});

package/src/modules/ai_assistant/__integration__/TC-INT-AI-TOOLS.spec.ts

@@ -0,0 +1,135 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { expect, test } from '@playwright/test'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+/**
+ * TC-INT-AI-TOOLS: Smoke-test every AI tool registered via `defineAiTool`.
+ *
+ * Strategy: shells out to `yarn mercato ai_assistant test-tools --json` which
+ * runs the in-process tool runner (`packages/ai-assistant/.../lib/tool-test-runner.ts`).
+ * The runner iterates every entry in `apps/mercato/.mercato/generated/ai-tools.generated.ts`,
+ * invokes each handler with a small fixture input against a super-admin
+ * context, and returns a structured report. Mutation tools are exercised
+ * through `prepareMutation` only — the test asserts a pending-action envelope
+ * is returned and never confirms the action.
+ *
+ * No HTTP endpoint is added; the runner is CLI-only and never exposed.
+ */
+
+interface ToolTestRecord {
+  module: string
+  tool: string
+  isMutation: boolean
+  status: 'pass' | 'fail' | 'skip'
+  durationMs: number
+  reason?: string
+}
+
+interface ToolTestReport {
+  tenantId: string | null
+  organizationId: string | null
+  total: number
+  passed: number
+  failed: number
+  skipped: number
+  records: ToolTestRecord[]
+}
+
+const REPORT_BEGIN = '---TOOL_TEST_REPORT_BEGIN---'
+const REPORT_END = '---TOOL_TEST_REPORT_END---'
+
+function findRepoRoot(): string {
+  return path.resolve(__dirname, '..', '..', '..', '..', '..', '..')
+}
+
+function findAppRoot(): string {
+  const testAppRoot = process.env.OM_TEST_APP_ROOT
+  if (testAppRoot && testAppRoot.length > 0) {
+    return testAppRoot
+  }
+
+  // The CLI loads its env from apps/mercato/.env (DB connection, JWT secret,
+  // encryption fallback). Spawning from there makes the bootstrap reach a
+  // ready state instead of bailing on the MFA-secret precondition.
+  return path.join(findRepoRoot(), 'apps', 'mercato')
+}
+
+function runToolTestsCli(): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((resolveCmd, rejectCmd) => {
+    const cwd = findAppRoot()
+    const child = spawn(
+      'yarn',
+      ['mercato', 'ai_assistant', 'test-tools', '--json'],
+      {
+        cwd,
+        env: { ...process.env, FORCE_COLOR: '0', NODE_NO_WARNINGS: '1' },
+        shell: false,
+      },
+    )
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString()
+    })
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString()
+    })
+    child.on('error', (err) => rejectCmd(err))
+    child.on('close', (code) => {
+      resolveCmd({ stdout, stderr, code: code ?? -1 })
+    })
+  })
+}
+
+function parseReport(stdout: string): ToolTestReport {
+  const beginIdx = stdout.indexOf(REPORT_BEGIN)
+  const endIdx = stdout.indexOf(REPORT_END)
+  if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
+    throw new Error(
+      `Could not find report markers in CLI output. stdout (first 500 chars):\n${stdout.slice(0, 500)}`,
+    )
+  }
+  const payload = stdout.slice(beginIdx + REPORT_BEGIN.length, endIdx).trim()
+  return JSON.parse(payload) as ToolTestReport
+}
+
+test.describe('TC-INT-AI-TOOLS: Every AI tool returns the expected shape', () => {
+  test('all registered tools either pass or skip with a reason; none fail', async () => {
+    test.slow()
+    const { stdout, stderr, code } = await runToolTestsCli()
+    if (code !== 0 && stdout.indexOf(REPORT_BEGIN) === -1) {
+      throw new Error(
+        `tool-test CLI failed (exit ${code}) before producing a report.\nstderr:\n${stderr.slice(0, 2000)}\nstdout:\n${stdout.slice(0, 1000)}`,
+      )
+    }
+    const report = parseReport(stdout)
+
+    // Surface a compact summary in the test log for triage.
+    const failures = report.records.filter((r) => r.status === 'fail')
+    const skips = report.records.filter((r) => r.status === 'skip')
+    if (failures.length > 0) {
+      console.log(
+        `[TC-INT-AI-TOOLS] Failures (${failures.length}):\n${failures
+          .map((r) => `  - ${r.tool}: ${r.reason ?? '<no reason>'}`)
+          .join('\n')}`,
+      )
+    }
+    if (skips.length > 0) {
+      console.log(
+        `[TC-INT-AI-TOOLS] Skips (${skips.length}): ${skips
+          .map((r) => `${r.tool} (${r.reason ?? 'skipped'})`)
+          .join(', ')}`,
+      )
+    }
+    console.log(
+      `[TC-INT-AI-TOOLS] Result: total=${report.total} pass=${report.passed} fail=${report.failed} skip=${report.skipped}`,
+    )
+
+    expect(failures, `Expected zero failing AI tools, got ${failures.length}`).toEqual([])
+    expect(report.passed, 'At least one tool must run successfully').toBeGreaterThan(0)
+  })
+})

package/src/modules/ai_assistant/__tests__/events.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Unit coverage for the ai_assistant module event declarations (Step 5.11).
+ *
+ * Asserts:
+ * - All three FROZEN event IDs (`ai.action.confirmed` /
+ *   `ai.action.cancelled` / `ai.action.expired`) appear in
+ *   `eventsConfig.events` under `category: 'system'`.
+ * - The typed `emitAiAssistantEvent` helper hands declared events off to
+ *   the global event bus with the payload untouched.
+ * - Emitting an undeclared event id is rejected at the helper boundary
+ *   via `createModuleEvents`' strict-mode validation.
+ */
+import {
+  eventsConfig,
+  emitAiAssistantEvent,
+  type AiAssistantEventId,
+  type AiActionCancelledPayload,
+  type AiActionConfirmedPayload,
+  type AiActionExpiredPayload,
+} from '../events'
+import { setGlobalEventBus } from '@open-mercato/shared/modules/events'
+
+const FROZEN_EVENT_IDS: ReadonlyArray<AiAssistantEventId> = [
+  'ai.action.confirmed',
+  'ai.action.cancelled',
+  'ai.action.expired',
+]
+
+describe('ai_assistant events module', () => {
+  it('declares the three FROZEN pending-action events under moduleId=ai_assistant', () => {
+    expect(eventsConfig.moduleId).toBe('ai_assistant')
+    const declaredIds = eventsConfig.events.map((event) => event.id).sort()
+    expect(declaredIds).toEqual([...FROZEN_EVENT_IDS].sort())
+  })
+
+  it('every declared event has category=system and entity=ai_pending_action', () => {
+    for (const event of eventsConfig.events) {
+      expect(event.category).toBe('system')
+      expect(event.entity).toBe('ai_pending_action')
+      expect(event.module).toBe('ai_assistant')
+      expect(typeof event.label).toBe('string')
+      expect(event.label.length).toBeGreaterThan(0)
+    }
+  })
+
+  describe('emitAiAssistantEvent', () => {
+    const emitSpy = jest.fn().mockResolvedValue(undefined)
+    let consoleErrorSpy: jest.SpyInstance
+
+    beforeEach(() => {
+      emitSpy.mockClear()
+      setGlobalEventBus({ emit: (id, payload, opts) => emitSpy(id, payload, opts) })
+      consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    })
+
+    afterEach(() => {
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('forwards ai.action.confirmed payloads to the global bus verbatim', async () => {
+      const payload: AiActionConfirmedPayload = {
+        pendingActionId: 'pa_1',
+        agentId: 'catalog.merchandising_assistant',
+        toolName: 'catalog.update_product',
+        status: 'confirmed',
+        tenantId: 'tenant-1',
+        organizationId: 'org-1',
+        userId: 'user-1',
+        resolvedByUserId: 'user-1',
+        resolvedAt: '2026-04-18T10:05:00.000Z',
+        executionResult: { recordId: 'p-1', commandName: 'catalog.product.update' },
+      }
+      await emitAiAssistantEvent(
+        'ai.action.confirmed',
+        payload as unknown as Record<string, unknown>,
+        { persistent: true },
+      )
+      expect(emitSpy).toHaveBeenCalledTimes(1)
+      const [id, forwardedPayload, options] = emitSpy.mock.calls[0]
+      expect(id).toBe('ai.action.confirmed')
+      expect(forwardedPayload).toEqual(payload)
+      expect(options).toEqual({ persistent: true })
+    })
+
+    it('forwards ai.action.cancelled payloads to the global bus', async () => {
+      const payload: AiActionCancelledPayload = {
+        pendingActionId: 'pa_1',
+        agentId: 'catalog.merchandising_assistant',
+        toolName: 'catalog.update_product',
+        status: 'cancelled',
+        tenantId: 'tenant-1',
+        organizationId: 'org-1',
+        userId: 'user-1',
+        resolvedByUserId: 'user-1',
+        resolvedAt: '2026-04-18T10:05:00.000Z',
+        executionResult: {
+          error: { code: 'cancelled_by_user', message: 'Customer asked to abort' },
+        },
+        reason: 'Customer asked to abort',
+      }
+      await emitAiAssistantEvent(
+        'ai.action.cancelled',
+        payload as unknown as Record<string, unknown>,
+      )
+      expect(emitSpy).toHaveBeenCalledTimes(1)
+      expect(emitSpy.mock.calls[0][0]).toBe('ai.action.cancelled')
+      expect(emitSpy.mock.calls[0][1]).toEqual(payload)
+    })
+
+    it('forwards ai.action.expired payloads to the global bus', async () => {
+      const payload: AiActionExpiredPayload = {
+        pendingActionId: 'pa_1',
+        agentId: 'catalog.merchandising_assistant',
+        toolName: 'catalog.update_product',
+        status: 'expired',
+        tenantId: 'tenant-1',
+        organizationId: 'org-1',
+        userId: null,
+        resolvedByUserId: null,
+        resolvedAt: '2026-04-18T10:05:00.000Z',
+        expiresAt: '2026-04-18T10:00:00.000Z',
+        expiredAt: '2026-04-18T10:05:00.000Z',
+      }
+      await emitAiAssistantEvent(
+        'ai.action.expired',
+        payload as unknown as Record<string, unknown>,
+      )
+      expect(emitSpy).toHaveBeenCalledTimes(1)
+      expect(emitSpy.mock.calls[0][0]).toBe('ai.action.expired')
+      expect(emitSpy.mock.calls[0][1]).toEqual(payload)
+    })
+
+    it('logs an error and still forwards undeclared event ids (non-strict mode)', async () => {
+      await emitAiAssistantEvent(
+        // Deliberate cast: runtime test for undeclared-event path.
+        'ai.action.nope' as unknown as AiAssistantEventId,
+        { pendingActionId: 'pa_1' },
+      )
+      expect(consoleErrorSpy).toHaveBeenCalledTimes(1)
+      const [message] = consoleErrorSpy.mock.calls[0]
+      expect(message).toContain('ai_assistant')
+      expect(message).toContain('ai.action.nope')
+    })
+  })
+})