@open-mercato/ai-assistant 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/src/modules/ai_assistant/__integration__/TC-AI-SESSION-KEY-006-create-session-token.spec.ts

@@ -0,0 +1,95 @@
+import { test, expect, request as playwrightRequest } from '@playwright/test';
+import { randomUUID } from 'node:crypto';
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api';
+import {
+  createRoleFixture,
+  deleteRoleIfExists,
+  createUserFixture,
+  deleteUserIfExists,
+  setUserAclVisibility,
+} from '@open-mercato/core/helpers/integration/authFixtures';
+import { deleteUserAclInDb } from '@open-mercato/core/helpers/integration/dbFixtures';
+import { getTokenScope, readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures';
+
+/**
+ * TC-AI-SESSION-KEY-006 — Session key generation.
+ * Source: GitHub issue #2495.
+ *
+ * Surface under test:
+ *   - /api/ai_assistant/session-key   (POST)
+ *
+ * Contract notes verified against the route handler (the issue's guesses were wrong):
+ *   - the response body is EXACTLY `{ sessionToken, expiresAt }` — it does NOT
+ *     include userId / tenantId / organizationId.
+ *   - token format is `sess_` + 32 lowercase hex chars; TTL is 120 minutes.
+ *   - requires `ai_assistant.view`; unauthenticated -> 401; missing feature -> 403.
+ *
+ * NOTE: the returned `sess_...` token is consumed only as the MCP `_sessionToken`
+ * tool-call argument — it is NOT accepted by the Next.js HTTP auth resolver as a
+ * Bearer/header, so the issue's "use the token to call /tools" step is invalid
+ * and intentionally omitted here.
+ */
+
+const SESSION_KEY = '/api/ai_assistant/session-key';
+const SESSION_TOKEN_RE = /^sess_[0-9a-f]{32}$/;
+const TTL_MINUTES = 120;
+
+test.describe('TC-AI-SESSION-KEY-006: Session key generation', () => {
+  test('POST mints a unique sess_ token with a ~120 minute TTL', async ({ request }) => {
+    const adminToken = await getAuthToken(request, 'admin');
+
+    const first = await apiRequest(request, 'POST', SESSION_KEY, { token: adminToken, data: {} });
+    expect(first.status(), 'session-key POST returns 200').toBe(200);
+    const body = await readJsonSafe<{ sessionToken: string; expiresAt: string }>(first);
+    expect(body?.sessionToken).toMatch(SESSION_TOKEN_RE);
+
+    const now = Date.now();
+    const expiresAt = Date.parse(body!.expiresAt);
+    expect(Number.isNaN(expiresAt)).toBe(false);
+    // Allow generous slop for clock + request latency around the 120-minute TTL.
+    expect(expiresAt).toBeGreaterThan(now + (TTL_MINUTES - 5) * 60 * 1000);
+    expect(expiresAt).toBeLessThan(now + (TTL_MINUTES + 5) * 60 * 1000);
+
+    const second = await apiRequest(request, 'POST', SESSION_KEY, { token: adminToken, data: {} });
+    expect(second.status()).toBe(200);
+    const secondBody = await readJsonSafe<{ sessionToken: string }>(second);
+    expect(secondBody?.sessionToken).toMatch(SESSION_TOKEN_RE);
+    expect(secondBody?.sessionToken, 'each call mints a distinct token').not.toBe(body?.sessionToken);
+  });
+
+  test('auth gates: unauthenticated 401 and missing ai_assistant.view 403', async ({ request, baseURL }) => {
+    test.slow();
+    const adminToken = await getAuthToken(request, 'admin');
+    const { organizationId } = getTokenScope(adminToken);
+    const stamp = randomUUID().slice(0, 8);
+    const password = 'Secret123!';
+
+    const anon = await playwrightRequest.newContext({ baseURL });
+    try {
+      const res = await anon.fetch(SESSION_KEY, { method: 'POST', data: '{}' });
+      expect(res.status(), 'unauthenticated POST is 401').toBe(401);
+    } finally {
+      await anon.dispose();
+    }
+
+    let roleId: string | null = null;
+    let userId: string | null = null;
+    try {
+      roleId = await createRoleFixture(request, adminToken, { name: `IT Session Role ${stamp}` });
+      userId = await createUserFixture(request, adminToken, {
+        email: `it-session-${stamp}@example.com`,
+        password,
+        organizationId,
+        roles: [roleId],
+      });
+      await setUserAclVisibility(request, adminToken, { userId, features: [], organizations: null });
+      const viewlessToken = await getAuthToken(request, `it-session-${stamp}@example.com`, password);
+      const denied = await apiRequest(request, 'POST', SESSION_KEY, { token: viewlessToken, data: {} });
+      expect(denied.status(), 'caller without ai_assistant.view is 403').toBe(403);
+    } finally {
+      await deleteUserAclInDb(userId ?? '').catch(() => undefined);
+      await deleteUserIfExists(request, adminToken, userId);
+      await deleteRoleIfExists(request, adminToken, roleId);
+    }
+  });
+});

package/src/modules/ai_assistant/__integration__/TC-AI-SETTINGS-ALLOWLIST-003-put-delete-allowlist.spec.ts

@@ -0,0 +1,115 @@
+import { test, expect, request as playwrightRequest } from '@playwright/test';
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api';
+import { getTokenScope, readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures';
+import { deleteTenantAllowlistInDb } from './helpers/aiAssistantFixtures';
+
+/**
+ * TC-AI-SETTINGS-ALLOWLIST-003 — Tenant model allowlist (PUT/DELETE) + settings reflection.
+ * Source: GitHub issue #2495.
+ *
+ * Surfaces under test:
+ *   - /api/ai_assistant/settings/allowlist   (PUT, DELETE)
+ *   - /api/ai_assistant/settings             (GET — reflects the snapshot)
+ *
+ * Contract notes verified against the route handlers:
+ *   - PUT body fields are `allowedProviders` / `allowedModelsByProvider`
+ *     (NOT `providers` / `models`); success is 200 returning the saved snapshot.
+ *   - DELETE returns 200 `{ cleared: boolean }` and is idempotent
+ *     (`cleared: false` when no active row exists).
+ *   - GET /settings exposes `tenantAllowlist` (null when unset) + `effectiveAllowlist`.
+ *   - PUT/DELETE require `ai_assistant.settings.manage`.
+ *
+ * Out of scope (documented): the `provider_not_in_env_allowlist` 400 branch only
+ * fires when the APP process has `OM_AI_AVAILABLE_PROVIDERS` set to exclude the
+ * provider. The deterministic harness does not control the app's env, so that
+ * branch is covered by the module's unit tests; here we assert the env-agnostic
+ * Zod validation (wrong type -> 400 validation_error) instead.
+ */
+
+const ALLOWLIST = '/api/ai_assistant/settings/allowlist';
+const SETTINGS = '/api/ai_assistant/settings';
+
+interface TenantAllowlistSnapshot {
+  allowedProviders: string[] | null;
+  allowedModelsByProvider: Record<string, string[]>;
+}
+
+test.describe('TC-AI-SETTINGS-ALLOWLIST-003: Tenant model allowlist', () => {
+  test('PUT persists, GET reflects, DELETE clears + is idempotent', async ({ request }) => {
+    test.slow();
+    const adminToken = await getAuthToken(request, 'admin');
+    const { tenantId } = getTokenScope(adminToken);
+    try {
+      // Start from a known-clean state.
+      const reset = await apiRequest(request, 'DELETE', ALLOWLIST, { token: adminToken });
+      expect(reset.status()).toBe(200);
+
+      const settingsBefore = await apiRequest(request, 'GET', SETTINGS, { token: adminToken });
+      expect(settingsBefore.status()).toBe(200);
+      const before = await readJsonSafe<{ tenantAllowlist: TenantAllowlistSnapshot | null; effectiveAllowlist: unknown }>(
+        settingsBefore,
+      );
+      expect(before?.tenantAllowlist).toBeNull();
+      expect(before?.effectiveAllowlist).toBeTruthy();
+
+      const put = await apiRequest(request, 'PUT', ALLOWLIST, {
+        token: adminToken,
+        data: { allowedProviders: ['openai'], allowedModelsByProvider: { openai: ['gpt-5-mini'] } },
+      });
+      expect(put.status(), 'PUT allowlist returns 200').toBe(200);
+      const saved = await readJsonSafe<TenantAllowlistSnapshot>(put);
+      expect(saved?.allowedProviders).toContain('openai');
+      expect(saved?.allowedModelsByProvider?.openai).toContain('gpt-5-mini');
+
+      const settingsAfter = await apiRequest(request, 'GET', SETTINGS, { token: adminToken });
+      expect(settingsAfter.status()).toBe(200);
+      const after = await readJsonSafe<{ tenantAllowlist: TenantAllowlistSnapshot | null }>(settingsAfter);
+      expect(after?.tenantAllowlist?.allowedProviders).toContain('openai');
+
+      const del = await apiRequest(request, 'DELETE', ALLOWLIST, { token: adminToken });
+      expect(del.status()).toBe(200);
+      expect((await readJsonSafe<{ cleared: boolean }>(del))?.cleared).toBe(true);
+
+      const settingsCleared = await apiRequest(request, 'GET', SETTINGS, { token: adminToken });
+      const cleared = await readJsonSafe<{ tenantAllowlist: TenantAllowlistSnapshot | null }>(settingsCleared);
+      expect(cleared?.tenantAllowlist).toBeNull();
+
+      const delAgain = await apiRequest(request, 'DELETE', ALLOWLIST, { token: adminToken });
+      expect(delAgain.status()).toBe(200);
+      expect((await readJsonSafe<{ cleared: boolean }>(delAgain))?.cleared, 'DELETE is idempotent').toBe(false);
+    } finally {
+      await deleteTenantAllowlistInDb(tenantId).catch(() => undefined);
+    }
+  });
+
+  test('validation + RBAC gates: bad body 400, employee 403, unauthenticated 401', async ({ request, baseURL }) => {
+    const adminToken = await getAuthToken(request, 'admin');
+
+    const badType = await apiRequest(request, 'PUT', ALLOWLIST, {
+      token: adminToken,
+      data: { allowedProviders: 123 },
+    });
+    expect(badType.status()).toBe(400);
+    expect((await readJsonSafe<{ code?: string }>(badType))?.code).toBe('validation_error');
+
+    // Employee carries ai_assistant.view but NOT ai_assistant.settings.manage.
+    const employeeToken = await getAuthToken(request, 'employee');
+    const denied = await apiRequest(request, 'PUT', ALLOWLIST, {
+      token: employeeToken,
+      data: { allowedProviders: ['openai'] },
+    });
+    expect(denied.status(), 'employee lacks settings.manage -> 403').toBe(403);
+
+    const anon = await playwrightRequest.newContext({ baseURL });
+    try {
+      const res = await anon.fetch(ALLOWLIST, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        data: JSON.stringify({ allowedProviders: ['openai'] }),
+      });
+      expect(res.status(), 'unauthenticated PUT is 401').toBe(401);
+    } finally {
+      await anon.dispose();
+    }
+  });
+});

package/src/modules/ai_assistant/__integration__/TC-AI-TOKEN-USAGE-001-005.spec.ts

@@ -78,6 +78,8 @@ const STEP_EVENT = {
 };
 
 test.describe('TC-AI-TOKEN-USAGE-001–005: token usage stats page', () => {
+  test.describe.configure({ timeout: 120_000 });
+
   test('TC-AI-TOKEN-USAGE-001: usage page renders summary tiles for superadmin', async ({ page }) => {
     await login(page, 'superadmin');
 
@@ -97,7 +99,7 @@ test.describe('TC-AI-TOKEN-USAGE-001–005: token usage stats page', () => {
       });
     });
 
-    await page.goto(USAGE_PAGE, { waitUntil: 'domcontentloaded' });
+    await page.goto(USAGE_PAGE, { waitUntil: 'commit' });
 
     const summaryTile = page.locator('p.font-semibold.text-xl', { hasText: /^(1,000|500)$/ }).first();
     await expect(summaryTile).toBeVisible({ timeout: 15_000 });
@@ -130,7 +132,7 @@ test.describe('TC-AI-TOKEN-USAGE-001–005: token usage stats page', () => {
       (response) => response.url().includes('/api/ai_assistant/usage/sessions') && response.status() === 200,
       { timeout: 15_000 },
     );
-    await page.goto(USAGE_PAGE, { waitUntil: 'domcontentloaded' });
+    await page.goto(USAGE_PAGE, { waitUntil: 'commit' });
     await Promise.all([initialDailyRequest, initialSessionsRequest]);
 
     const fromInput = page.locator('#usage-from');
@@ -178,7 +180,7 @@ test.describe('TC-AI-TOKEN-USAGE-001–005: token usage stats page', () => {
       });
     });
 
-    await page.goto(USAGE_PAGE, { waitUntil: 'domcontentloaded' });
+    await page.goto(USAGE_PAGE, { waitUntil: 'commit' });
 
     const sessionCell = page.getByText('00000000').first();
     await expect(sessionCell).toBeVisible({ timeout: 15_000 });
@@ -216,7 +218,7 @@ test.describe('TC-AI-TOKEN-USAGE-001–005: token usage stats page', () => {
       });
     });
 
-    await page.goto(USAGE_PAGE, { waitUntil: 'domcontentloaded' });
+    await page.goto(USAGE_PAGE, { waitUntil: 'commit' });
 
     const sessionCell = page.getByText('00000000').first();
     await expect(sessionCell).toBeVisible({ timeout: 15_000 });
@@ -233,7 +235,7 @@ test.describe('TC-AI-TOKEN-USAGE-001–005: token usage stats page', () => {
     const context = await browser.newContext();
     const page = await context.newPage();
     try {
-      await page.goto(USAGE_PAGE, { waitUntil: 'domcontentloaded' });
+      await page.goto(USAGE_PAGE, { waitUntil: 'commit' });
       await page.waitForURL(/\/login/, { timeout: 15_000 });
       expect(page.url()).toMatch(/\/login/);
     } finally {

package/src/modules/ai_assistant/__integration__/TC-AI-TOOLS-EXECUTE-007-direct-tool-execution.spec.ts

@@ -0,0 +1,97 @@
+import { test, expect, request as playwrightRequest } from '@playwright/test';
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api';
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures';
+
+/**
+ * TC-AI-TOOLS-EXECUTE-007 — Direct tool execution + tool listing.
+ * Source: GitHub issue #2495.
+ *
+ * Surfaces under test:
+ *   - /api/ai_assistant/tools          (GET)
+ *   - /api/ai_assistant/tools/execute   (POST)
+ *
+ * Contract notes verified against the route handlers (the issue's guesses were wrong):
+ *   - execute body fields are `toolName` + `args` (NOT `name` / `input`);
+ *     success is 200 `{ success: true, result }`.
+ *   - a missing `toolName` -> 400 `{ error: 'toolName is required' }`.
+ *   - an unknown tool -> 400 `{ success: false, error: 'Tool "<n>" not found' }`
+ *     (NOT a typed `code`; the errorCode only selects 400 vs 403 internally).
+ *   - both routes require `ai_assistant.view`; the per-tool `requiredFeatures` are
+ *     enforced separately inside the executor.
+ */
+
+const TOOLS = '/api/ai_assistant/tools';
+const EXECUTE = '/api/ai_assistant/tools/execute';
+
+interface ToolSummary {
+  name: string;
+  description: string;
+  inputSchema: { required?: unknown } & Record<string, unknown>;
+  module: string;
+}
+
+test.describe('TC-AI-TOOLS-EXECUTE-007: Direct tool execution', () => {
+  test('list tools, validate + reject unknown tools, and exercise a no-arg tool', async ({ request }) => {
+    test.slow();
+    const adminToken = await getAuthToken(request, 'admin');
+
+    const listRes = await apiRequest(request, 'GET', TOOLS, { token: adminToken });
+    expect(listRes.status()).toBe(200);
+    const list = await readJsonSafe<{ tools: ToolSummary[] }>(listRes);
+    expect(Array.isArray(list?.tools)).toBe(true);
+    expect((list?.tools.length ?? 0) > 0, 'at least one tool is visible to admin').toBe(true);
+    const sample = list!.tools[0];
+    expect(typeof sample.name).toBe('string');
+    expect(typeof sample.inputSchema).toBe('object');
+
+    // Missing toolName -> 400 with the route-level message.
+    const missing = await apiRequest(request, 'POST', EXECUTE, { token: adminToken, data: {} });
+    expect(missing.status()).toBe(400);
+    expect((await readJsonSafe<{ error?: string }>(missing))?.error).toBe('toolName is required');
+
+    // Unknown tool -> 400 { success: false, error: '... not found' }.
+    const unknown = await apiRequest(request, 'POST', EXECUTE, {
+      token: adminToken,
+      data: { toolName: 'does.not_exist_tool', args: {} },
+    });
+    expect(unknown.status()).toBe(400);
+    const unknownBody = await readJsonSafe<{ success?: boolean; error?: string }>(unknown);
+    expect(unknownBody?.success).toBe(false);
+    expect(unknownBody?.error ?? '').toContain('not found');
+
+    // Best-effort happy path: a tool whose input schema has no required fields can
+    // be invoked with empty args. The execute route runs the handler and returns
+    // 200 `{ success }`; assert the envelope only when such a tool is available.
+    const noArgTool = list!.tools.find((tool) => {
+      const required = tool.inputSchema?.required;
+      return !Array.isArray(required) || required.length === 0;
+    });
+    if (noArgTool) {
+      const exec = await apiRequest(request, 'POST', EXECUTE, {
+        token: adminToken,
+        data: { toolName: noArgTool.name, args: {} },
+      });
+      // A 200 from the execute route always carries `success: true` (only a
+      // thrown handler yields 400 `{ success: false }`), so assert the real
+      // value rather than mere presence. A no-arg tool that rejects empty input
+      // legitimately returns 400, which this guard intentionally tolerates.
+      if (exec.status() === 200) {
+        expect((await readJsonSafe<{ success?: boolean }>(exec))?.success).toBe(true);
+      }
+    }
+  });
+
+  test('unauthenticated execute is rejected with 401', async ({ baseURL }) => {
+    const anon = await playwrightRequest.newContext({ baseURL });
+    try {
+      const res = await anon.fetch(EXECUTE, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        data: JSON.stringify({ toolName: 'does.not_exist_tool', args: {} }),
+      });
+      expect(res.status()).toBe(401);
+    } finally {
+      await anon.dispose();
+    }
+  });
+});

package/src/modules/ai_assistant/__integration__/helpers/aiAssistantFixtures.ts

@@ -0,0 +1,198 @@
+import { readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { Client } from 'pg';
+
+/**
+ * Direct-Postgres fixtures for AI Assistant integration specs.
+ *
+ * Mirrors the sanctioned pattern in
+ * `@open-mercato/core/helpers/integration/dbFixtures` (raw SQL against
+ * `DATABASE_URL`) for the surfaces that have NO public create route:
+ *  - `ai_pending_actions`: a pending mutation approval is only ever born from
+ *    the internal `prepareMutation` path during a real LLM agent turn. Seeding
+ *    the row directly keeps confirm/cancel/GET coverage deterministic and
+ *    provider-free.
+ *  - prompt overrides: the `prompt-override` route exposes no DELETE, so
+ *    versioned rows must be swept via SQL after a test.
+ *
+ * The app server and this helper MUST share one `DATABASE_URL`, so specs using
+ * these helpers only run under the coherent app+DB harness
+ * (`yarn test:integration` / `:ephemeral`), never against an arbitrary dev
+ * server whose `DATABASE_URL` differs from `apps/mercato/.env`.
+ */
+
+function resolveAppRoot(): string {
+  const fromEnv = process.env.OM_TEST_APP_ROOT?.trim();
+  return fromEnv ? path.resolve(fromEnv) : path.resolve(process.cwd(), 'apps/mercato');
+}
+
+function readEnvValue(key: string): string | undefined {
+  if (process.env[key]) return process.env[key];
+  const candidatePaths = [
+    path.resolve(resolveAppRoot(), '.env'),
+    path.resolve(process.cwd(), 'apps/mercato/.env'),
+    path.resolve(process.cwd(), '.env'),
+  ];
+  for (const envPath of candidatePaths) {
+    try {
+      const content = readFileSync(envPath, 'utf-8');
+      const match = content.match(new RegExp(`^${key}=(.+)$`, 'm'));
+      if (match?.[1]) return match[1].trim();
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+function resolveDatabaseUrl(): string {
+  const url = readEnvValue('DATABASE_URL');
+  if (!url) throw new Error('[internal] DATABASE_URL is not configured for AI Assistant integration DB fixtures');
+  return url;
+}
+
+async function withClient<T>(run: (client: Client) => Promise<T>): Promise<T> {
+  const client = new Client({ connectionString: resolveDatabaseUrl() });
+  await client.connect();
+  try {
+    return await run(client);
+  } finally {
+    await client.end();
+  }
+}
+
+export type SeededPendingActionStatus =
+  | 'pending'
+  | 'confirmed'
+  | 'cancelled'
+  | 'expired'
+  | 'executing'
+  | 'failed';
+
+export interface SeedPendingActionInput {
+  tenantId: string;
+  organizationId?: string | null;
+  createdByUserId: string;
+  status?: SeededPendingActionStatus;
+  agentId?: string;
+  toolName?: string;
+  /** Minutes from now until expiry. Negative => the row is already expired. */
+  expiresInMinutes?: number;
+  normalizedInput?: Record<string, unknown>;
+  executionResult?: Record<string, unknown> | null;
+  idempotencyKey?: string;
+}
+
+export interface SeededPendingAction {
+  id: string;
+  idempotencyKey: string;
+}
+
+/**
+ * Inserts an `ai_pending_actions` row directly. Returns the new id so the test
+ * can act on it and clean it up. Defaults produce an actionable `pending` row
+ * with a future TTL; override `status`/`expiresInMinutes`/`executionResult` to
+ * cover the idempotency short-circuit and 409 error branches.
+ */
+export async function seedPendingActionInDb(input: SeedPendingActionInput): Promise<SeededPendingAction> {
+  const idempotencyKey = input.idempotencyKey ?? `it-pending-${randomUUID()}`;
+  const status = input.status ?? 'pending';
+  const expiresInMinutes = input.expiresInMinutes ?? 60;
+  const normalizedInput = JSON.stringify(input.normalizedInput ?? {});
+  const executionResult =
+    input.executionResult === undefined || input.executionResult === null
+      ? null
+      : JSON.stringify(input.executionResult);
+  return withClient(async (client) => {
+    const result = await client.query<{ id: string }>(
+      `insert into ai_pending_actions
+         (id, tenant_id, organization_id, agent_id, tool_name, normalized_input,
+          field_diff, attachment_ids, idempotency_key, created_by_user_id, status,
+          queue_mode, execution_result, created_at, expires_at)
+       values
+         (gen_random_uuid(), $1, $2, $3, $4, $5::jsonb,
+          '[]'::jsonb, '[]'::jsonb, $6, $7, $8,
+          'inline', $9::jsonb, now(), now() + make_interval(mins => $10::int))
+       returning id`,
+      [
+        input.tenantId,
+        input.organizationId ?? null,
+        input.agentId ?? 'it_agent.pending_fixture',
+        input.toolName ?? 'it_tool.noop',
+        normalizedInput,
+        idempotencyKey,
+        input.createdByUserId,
+        status,
+        executionResult,
+        expiresInMinutes,
+      ],
+    );
+    return { id: result.rows[0].id, idempotencyKey };
+  });
+}
+
+/** Hard-deletes a seeded pending action row (best-effort test cleanup). */
+export async function deletePendingActionInDb(id: string | null): Promise<void> {
+  if (!id) return;
+  await withClient(async (client) => {
+    await client.query('delete from ai_pending_actions where id = $1', [id]);
+  });
+}
+
+/**
+ * Sweeps every per-agent override row for a tenant across the three override
+ * tables. Required for `prompt-override` cleanup (no DELETE route) and used as a
+ * belt-and-braces teardown for mutation-policy / loop overrides.
+ */
+export async function deleteAgentOverridesInDb(input: { tenantId: string; agentId: string }): Promise<void> {
+  if (!input.tenantId || !input.agentId) return;
+  await withClient(async (client) => {
+    await client.query('delete from ai_agent_prompt_overrides where tenant_id = $1 and agent_id = $2', [
+      input.tenantId,
+      input.agentId,
+    ]);
+    await client.query('delete from ai_agent_mutation_policy_overrides where tenant_id = $1 and agent_id = $2', [
+      input.tenantId,
+      input.agentId,
+    ]);
+    await client.query('delete from ai_agent_runtime_overrides where tenant_id = $1 and agent_id = $2', [
+      input.tenantId,
+      input.agentId,
+    ]);
+  });
+}
+
+/** Hard-deletes any tenant model-allowlist rows (best-effort cleanup). */
+export async function deleteTenantAllowlistInDb(tenantId: string | null): Promise<void> {
+  if (!tenantId) return;
+  await withClient(async (client) => {
+    await client.query('delete from ai_tenant_model_allowlists where tenant_id = $1', [tenantId]);
+  });
+}
+
+/**
+ * Hard-deletes a conversation and its participant + message rows by the
+ * client-facing `conversation_id`. The DELETE route only soft-deletes, so this
+ * gives specs a true teardown for the rows they created.
+ */
+export async function deleteConversationCascadeInDb(input: {
+  tenantId: string;
+  conversationId: string;
+}): Promise<void> {
+  if (!input.tenantId || !input.conversationId) return;
+  await withClient(async (client) => {
+    await client.query('delete from ai_chat_messages where tenant_id = $1 and conversation_id = $2', [
+      input.tenantId,
+      input.conversationId,
+    ]);
+    await client.query(
+      'delete from ai_chat_conversation_participants where tenant_id = $1 and conversation_id = $2',
+      [input.tenantId, input.conversationId],
+    );
+    await client.query('delete from ai_chat_conversations where tenant_id = $1 and conversation_id = $2', [
+      input.tenantId,
+      input.conversationId,
+    ]);
+  });
+}

package/src/modules/ai_assistant/lib/__tests__/auth.test.ts

@@ -1,4 +1,5 @@
 import { extractApiKeyFromHeaders, hasRequiredFeatures } from '../auth'
+import { hasAllFeatures } from '@open-mercato/shared/lib/auth/featureMatch'
 
 describe('extractApiKeyFromHeaders', () => {
   describe('plain object headers', () => {
@@ -92,6 +93,32 @@ describe('hasRequiredFeatures', () => {
     ).toBe(false)
   })
 
+  it('grants a bare-segment requirement from a prefix wildcard (issue #2723)', () => {
+    expect(
+      hasRequiredFeatures(['entities'], ['entities.*'], false)
+    ).toBe(true)
+  })
+
+  it('matches the canonical matcher for bare-segment requirements with and without rbacService', () => {
+    const rbacService = {
+      hasAllFeatures: jest.fn((required: string[], granted: string[]) =>
+        hasAllFeatures(required, granted)
+      ),
+    }
+
+    const withService = hasRequiredFeatures(
+      ['entities'],
+      ['entities.*'],
+      false,
+      rbacService as any
+    )
+    const withoutService = hasRequiredFeatures(['entities'], ['entities.*'], false)
+
+    expect(withService).toBe(true)
+    expect(withoutService).toBe(true)
+    expect(withService).toBe(withoutService)
+  })
+
   it('requires all features (AND logic)', () => {
     expect(
       hasRequiredFeatures(