@open-mercato/ai-assistant 0.6.1-develop.3287.1.450f4ffb56 → 0.6.1-develop.3306.1.9ad9ff2526

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:ai-assistant] found 168 entry points
+[build:ai-assistant] found 180 entry points
 [build:ai-assistant] built successfully

package/AGENTS.md

@@ -103,7 +103,7 @@ APIs are automatically available via the Code Mode `search` tool (reads the Open
 Typed AI agents live in each module's root `ai-agents.ts`. The generator auto-discovers the file and aggregates it into `apps/mercato/.mercato/generated/ai-agents.generated.ts`. Reference implementations: `packages/core/src/modules/customers/ai-agents.ts` and `packages/core/src/modules/catalog/ai-agents.ts`.
 
 1. Create `<module>/ai-agents.ts` and export `aiAgents: AiAgentDefinition[]` (default export optional).
-2. Declare the agent with `defineAiAgent({ ... })` from `@open-mercato/ai-assistant`. Required fields: `id`, `moduleId`, `label`, `description`, `systemPrompt`, `allowedTools`. Useful optional fields: `executionMode` (`'chat'` — default — or `'object'`), `defaultProvider` (registered provider id the agent prefers — falls through transparently when unconfigured; Phase 1 of `2026-04-27-ai-agents-provider-model-baseurl-overrides`), `defaultModel` (plain model id or slash-qualified `<provider>/<model>` shorthand, e.g. `openai/gpt-5-mini`), `acceptedMediaTypes`, `requiredFeatures`, `uiParts`, `readOnly`, `mutationPolicy` (`'read-only'` | `'confirm-required'` | `'destructive-confirm-required'`), `maxSteps`, `output` (Zod schema for `'object'` mode), `resolvePageContext`, `keywords`, `suggestions`, `domain`, `dataCapabilities`.
+2. Declare the agent with `defineAiAgent({ ... })` from `@open-mercato/ai-assistant`. Required fields: `id`, `moduleId`, `label`, `description`, `systemPrompt`, `allowedTools`. Useful optional fields: `executionMode` (`'chat'` — default — or `'object'`), `executionEngine` (`'stream-text'` — default — or `'tool-loop-agent'`; see §"Loop controls and execution engines" below), `defaultProvider` (registered provider id the agent prefers; when paired with `defaultModel`, the pair fails closed if the provider is unconfigured; Phase 1 of `2026-04-27-ai-agents-provider-model-baseurl-overrides`), `defaultModel` (plain model id or slash-qualified `<provider>/<model>` shorthand, e.g. `openai/gpt-5-mini`), `acceptedMediaTypes`, `requiredFeatures`, `uiParts`, `readOnly`, `mutationPolicy` (`'read-only'` | `'confirm-required'` | `'destructive-confirm-required'`), `maxSteps`, `loop` (Phase 0–5 of spec `2026-04-28-ai-agents-agentic-loop-controls`), `output` (Zod schema for `'object'` mode), `resolvePageContext`, `keywords`, `suggestions`, `domain`, `dataCapabilities`.
 3. Add the feature(s) you list in `requiredFeatures` to the module's `acl.ts` and grant them in `setup.ts` `defaultRoleFeatures`.
 4. Put the agent's tool allowlist behind the narrowest set possible. Start from the general-purpose packs (`search.hybrid_search`, `search.get_record_context`, `attachments.list_record_attachments`, `attachments.read_attachment`, `meta.describe_agent`) and add your module's own `defineAiTool`-registered tools.
 5. For mutation-capable agents, keep `readOnly: true` + `mutationPolicy: 'read-only'` on the agent and light up writes only via the per-tenant mutation-policy override table (spec Phase 3 WS-C §5.4). The runtime filters out any `isMutation: true` tool when the override is still read-only.
@@ -336,7 +336,7 @@ Process-wide defaults (Phase 0 of spec
 
 | Variable | Purpose |
 |----------|---------|
-| `OM_AI_PROVIDER` | Optional. Names the registered provider id to prefer when multiple are configured. Falls through transparently when the named provider is registered-but-unconfigured. Built-in ids: `anthropic`, `google`, `openai`, `deepinfra`, `groq`, `together`, `fireworks`, `azure`, `litellm`, `ollama`, `openrouter`, `lm-studio`. The legacy `OPENCODE_PROVIDER` env is read as a backward-compatibility fallback. |
+| `OM_AI_PROVIDER` | Optional. Names the registered provider id to prefer when multiple are configured. Provider-only preferences can fall through when unconfigured; when paired with `OM_AI_MODEL`, the named provider must be configured. Built-in ids: `anthropic`, `google`, `openai`, `deepinfra`, `groq`, `together`, `fireworks`, `azure`, `litellm`, `ollama`, `openrouter`, `lm-studio`. The legacy `OPENCODE_PROVIDER` env is read as a backward-compatibility fallback. |
 | `OM_AI_MODEL` | Optional. Process-wide model id used when neither caller override, `OM_AI_<MODULE>_MODEL`, nor `agentDefaultModel` applies. Slash-qualified ids (e.g. `openai/gpt-5-mini`) consume the provider axis at the same step — DeepInfra ids that already contain slashes (`meta-llama/Llama-3.3-70B-Instruct-Turbo`) stay intact via the registry-membership guard. The legacy `OPENCODE_MODEL` env is read as a backward-compatibility fallback. |
 
 `OM_AI_*` are the canonical names; the legacy `OPENCODE_PROVIDER` / `OPENCODE_MODEL` envs stay bound to the OpenCode Code Mode stack and are also honored here as backward-compatibility fallbacks — see "Coexistence with OpenCode Code Mode" below.
@@ -346,7 +346,7 @@ Per-module overrides (Phase 1 of the same spec — agent-default provider + per-
 | Variable | Purpose |
 |----------|---------|
 | `OM_AI_<MODULE>_MODEL` | Optional. Per-module model override, uppercased from the agent's `moduleId`. Examples: `OM_AI_CATALOG_MODEL=claude-opus-4-20250514`, `OM_AI_INBOX_OPS_MODEL=gpt-4o`. The legacy `<MODULE>_AI_MODEL` form (e.g. `INBOX_OPS_AI_MODEL`) is read as a backward-compatibility fallback. Accepts a slash-qualified `<provider>/<model>` shorthand. |
-| `OM_AI_<MODULE>_PROVIDER` | Optional. Per-module provider override, uppercased from the agent's `moduleId`. Examples: `OM_AI_CATALOG_PROVIDER=openai`, `OM_AI_INBOX_OPS_PROVIDER=anthropic`. The legacy `<MODULE>_AI_PROVIDER` form (e.g. `INBOX_OPS_AI_PROVIDER`) is read as a backward-compatibility fallback. Falls through transparently when the named provider is registered-but-unconfigured. |
+| `OM_AI_<MODULE>_PROVIDER` | Optional. Per-module provider override, uppercased from the agent's `moduleId`. Examples: `OM_AI_CATALOG_PROVIDER=openai`, `OM_AI_INBOX_OPS_PROVIDER=anthropic`. The legacy `<MODULE>_AI_PROVIDER` form (e.g. `INBOX_OPS_AI_PROVIDER`) is read as a backward-compatibility fallback. Provider-only preferences can fall through when unconfigured; paired provider/model overrides fail closed. |
 
 All new callers MUST use `createModelFactory(container)` from `@open-mercato/ai-assistant/modules/ai_assistant/lib/model-factory` — never inline provider SDK calls (`createAnthropic`, `createOpenAI`, `createGoogleGenerativeAI`). The factory enforces the resolution order (caller override → `OM_AI_<MODULE>_MODEL` → `agentDefaultModel` → `OM_AI_MODEL` → provider default) and throws the documented `AiModelFactoryError` codes when misconfigured. See **Model Resolution** below.
 
@@ -466,9 +466,7 @@ packages/ai-assistant/
 │   │   │   ├── codemode-tools.ts       # Code Mode search + execute tools
 │   │   │   ├── sandbox.ts             # node:vm sandbox executor
 │   │   │   ├── truncate.ts            # Response size limiter
-│   │   │   ├── api-endpoint-index.ts   # OpenAPI endpoint indexing + raw spec cache
-│   │   │   ├── api-discovery-tools.ts  # (legacy, unused) old find_api/call_api
-│   │   │   ├── entity-graph-tools.ts   # (legacy, unused) old discover_schema
+│   │   │   ├── api-endpoint-index.ts   # OpenAPI endpoint parsing + raw spec cache for Code Mode
 │   │   │   ├── http-server.ts          # MCP HTTP server implementation
 │   │   │   ├── mcp-server.ts           # MCP stdio server implementation
 │   │   │   ├── tool-registry.ts        # Global tool registration
@@ -587,7 +585,7 @@ The provider axis is resolved through `llmProviderRegistry.resolveFirstConfigure
 7. Slash-prefix from `OM_AI_MODEL` (legacy `OPENCODE_MODEL`) (Phase 0).
 8. `OM_AI_PROVIDER` (legacy `OPENCODE_PROVIDER`) env (Phase 0).
 
-The named provider is preferred but the walk falls through transparently when it is registered-but-unconfigured.
+Provider-only preferences can fall through when the named provider is registered but unconfigured. Provider/model pairs are atomic: slash-qualified model ids and same-source provider/model settings fail closed when their provider is unconfigured, instead of sending a provider-specific model id to a different provider.
 
 The factory throws `AiModelFactoryError` with `code: 'no_provider_configured'`
 when the registry has no configured provider and `code: 'api_key_missing'`
@@ -889,21 +887,28 @@ normalizeCode(code: string): string   // Strip markdown fences, validate shape
 truncateResult(value, maxChars?): string  // Default 40K chars (~10K tokens)
 ```
 
-**Legacy files kept but unused**: `lib/api-discovery-tools.ts` (old find_api/call_api) and `lib/entity-graph-tools.ts` (old discover_schema) remain in the tree but are no longer imported.
-
 ## Rules for the API Endpoint Index
 
-Located in `lib/api-endpoint-index.ts`. Use the singleton pattern — never instantiate directly:
+Located in `lib/api-endpoint-index.ts`. The module exposes pure functions — never instantiate. The Code Mode `search` and `execute` tools consume `getRawOpenApiSpec()` / `loadRichOpenApiSpec()` and `getApiEndpoints()`; no other live consumer exists.
 
 ```typescript
-class ApiEndpointIndex {
-  static getInstance(): ApiEndpointIndex
-  searchEndpoints(query: string, options?: SearchOptions): EndpointMatch[]
-  getEndpoint(operationId: string): EndpointInfo | null
-  getEndpointByPath(method: string, path: string): EndpointInfo | null
-}
+// Endpoint parsing (cached per process)
+getApiEndpoints(): Promise<ApiEndpoint[]>
+getEndpointByOperationId(operationId: string): Promise<ApiEndpoint | null>
+clearEndpointCache(): void
+
+// Raw spec for Code Mode
+getRawOpenApiSpec(): Promise<OpenApiDocument | null>
+loadRichOpenApiSpec(): Promise<OpenApiDocument | null>
+setRawSpecCache(doc: OpenApiDocument): void
+clearRawSpecCache(): void
+
+// Helper for request body schema flattening
+simplifyRequestBodySchema(schema): { required, properties } | null
 ```
 
+The module deliberately **does not** call `searchService.bulkIndex(...)` on boot — it has no live reader, and on a large OpenAPI surface (~600 operations) the fan-out triggered the embedding storm fixed by #1876.
+
 ## Docker Configuration
 
 ### Rules for the OpenCode Container
@@ -1405,8 +1410,54 @@ if (tool.requiredFeatures?.length) {
 
 ---
 
+## Loop controls and execution engines
+
+Agents that need multi-step tool loops configure the `loop` block on `AiAgentDefinition` (spec `2026-04-28-ai-agents-agentic-loop-controls`). The `executionEngine` field selects the underlying SDK dispatch strategy:
+
+| Engine | `executionEngine` value | When to use |
+|--------|------------------------|-------------|
+| `streamText` | `'stream-text'` (default) | Full primitive coverage: `repairToolCall`, all loop controls. Use for all agents unless you specifically need the ToolLoopAgent class. |
+| `ToolLoopAgent` | `'tool-loop-agent'` | Closer to a semantic agent abstraction; receives upcoming SDK features (multi-agent handoff) first. Opt-in per agent. |
+
+**`repairToolCall` engine note**: the current SDK version ships `experimental_repairToolCall` on `ToolLoopAgentSettings`, so the primitive is technically reachable via `'tool-loop-agent'`. However, behaviour parity across SDK versions is not guaranteed — prefer `'stream-text'` when repair logic correctness is critical. See `loop.repairToolCall` JSDoc in `ai-agent-definition.ts` for the engine-specific caveat.
+
+**Security guarantee**: the mutation-approval contract (`buildWrapperPrepareStep` → `prepareMutation`) is enforced identically regardless of `executionEngine`. For `'tool-loop-agent'`, the wrapper-owned `prepareStep` is wired at `ToolLoopAgent` construction (NOT via `prepareCall`, which does not include `prepareStep` in its `Pick` list).
+
+---
+
 ## Changelog
 
+### 2026-05-13 - Remove dead `indexApiEndpoints` from MCP boot (#1876)
+
+**What changed**:
+- MCP HTTP / stdio / dev entry points no longer call `indexApiEndpoints(searchService)` at startup. The Code Mode rewrite (2026-02-22) deleted the only readers (`find_api` / `call_api` / `discover_schema`), so the call was indexing into fulltext + tokens + vector indexes that nothing queried. On large specs (≳200 ops + remote embedding latency) the search-service fan-out also burned an `OpenAI` embedding storm + pgvector load on every boot — Code Mode reads the OpenAPI document directly via `getRawOpenApiSpec()` / `loadRichOpenApiSpec()`, in-memory.
+- Deleted `lib/api-discovery-tools.ts`, `lib/entity-graph-tools.ts`, `lib/api-endpoint-index-config.ts` — all dead since the 2026-02-22 rewrite, kept only by the boot-time indexing call we removed.
+- Pruned `lib/api-endpoint-index.ts`: removed `indexApiEndpoints`, `searchEndpoints`, `searchEndpointsFallback`, `buildSearchableContent`, `lastIndexChecksum`, and the `API_ENDPOINT_ENTITY` deprecated alias. Kept `parseApiEndpoints` (private), `getApiEndpoints`, `getEndpointByOperationId`, `getRawOpenApiSpec`, `loadRichOpenApiSpec`, `setRawSpecCache`, `clearRawSpecCache`, `clearEndpointCache`, `simplifyRequestBodySchema` — those still serve Code Mode.
+
+**Files modified**:
+- `lib/http-server.ts`, `lib/mcp-server.ts`, `lib/mcp-dev-server.ts` — removed the `indexApiEndpoints` import + call
+- `lib/api-endpoint-index.ts` — pruned dead code
+
+**Files deleted**:
+- `lib/api-discovery-tools.ts`
+- `lib/entity-graph-tools.ts`
+- `lib/api-endpoint-index-config.ts`
+
+**Backward compatibility**: All removed symbols (`indexApiEndpoints`, `searchEndpoints`, `searchEndpointsFallback`, `endpointToIndexableRecord`, `API_ENDPOINT_ENTITY`, `API_ENDPOINT_SEARCH_CONFIG`, `apiEndpointEntityConfig`, `computeEndpointsChecksum`, `API_ENDPOINT_ENTITY_ID`, `GLOBAL_TENANT_ID` from `api-endpoint-index-config`) live inside the module's internal `lib/` path and are not part of the documented developer contract surface (see `BACKWARD_COMPATIBILITY.md`). They were already documented as legacy and unused.
+
+**Operator cleanup (optional)**: If a deployment previously booted MCP and accumulated rows in fulltext/vector/tokens under `entityId: 'ai_assistant:api_endpoint'` / `tenantId: '00000000-0000-0000-0000-000000000000'`, they are orphaned but inert — no live workflow reads them. Manual purge is purely cosmetic.
+
+### 2026-05-08 - Phase 5 opt-in ToolLoopAgent backend (spec 2026-04-28-ai-agents-agentic-loop-controls)
+
+**What changed**:
+- Added `AiAgentExecutionEngine = 'stream-text' | 'tool-loop-agent'` type alias to `ai-agent-definition.ts`.
+- Added `executionEngine?` field to `AiAgentDefinition` (default `'stream-text'` — zero churn to existing agents).
+- `agent-runtime.ts` gains an engine-dispatch branch: when `executionEngine === 'tool-loop-agent'`, a `ToolLoopAgent` (`Experimental_Agent`) is constructed once per turn with the wrapper-owned `prepareStep` and `stopWhen` wired at construction. The `ToolLoopAgent.stream()` path is used for dispatch; the default `streamText` path is unchanged.
+- `PreparedAiSdkOptions` gains `toolLoopAgent?` field for escape-hatch callers.
+- TC-AI-AGENT-LOOP-006 expanded with substantive mutation-gate proof tests using `page.route()` stubs.
+- `agents.mdx` gains "Choosing an execution engine" comparison table.
+- `loop.repairToolCall` JSDoc updated with engine-specific caveat.
+
 ### 2026-05-08 - Phase 3 call-site cleanup (spec 2026-04-27-ai-agents-provider-model-baseurl-overrides)
 
 **What changed**:
@@ -1438,8 +1489,8 @@ if (tool.requiredFeatures?.length) {
 - `lib/mcp-server.ts` — Generates entity graph and caches spec for stdio mode
 
 **Files kept but unused**:
-- `lib/api-discovery-tools.ts` — Old find_api/call_api (no longer imported)
-- `lib/entity-graph-tools.ts` — Old discover_schema (no longer imported)
+- `lib/api-discovery-tools.ts` — Old find_api/call_api (no longer imported, deleted in #1876)
+- `lib/entity-graph-tools.ts` — Old discover_schema (no longer imported, deleted in #1876)
 
 ### 2026-01-17 - Session Persistence Fix
 

package/README.md

@@ -512,7 +512,8 @@ packages/ai-assistant/
 │   │   ├── lib/
 │   │   │   ├── opencode-client.ts      # OpenCode API client
 │   │   │   ├── opencode-handlers.ts    # Request handlers
-│   │   │   ├── api-discovery-tools.ts  # api_discover, api_execute, api_schema
+│   │   │   ├── codemode-tools.ts       # Code Mode meta-tools (search + execute)
+│   │   │   ├── api-endpoint-index.ts   # OpenAPI parsing + raw spec cache
 │   │   │   ├── http-server.ts          # MCP HTTP server
 │   │   │   ├── mcp-dev-server.ts       # Development MCP server
 │   │   │   └── tool-registry.ts        # Tool registration

package/dist/frontend/components/AiChatButton.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { Sparkles } from "lucide-react";
+import { AiIcon } from "@open-mercato/ui/ai/AiIcon";
 import { Button } from "@open-mercato/ui/primitives/button";
 import { Tooltip, TooltipContent, TooltipTrigger, TooltipProvider } from "@open-mercato/ui/primitives/tooltip";
 function AiChatButton({ onClick, className }) {
@@ -13,12 +13,13 @@ function AiChatButton({ onClick, className }) {
     /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
       Button,
       {
+        type: "button",
         variant: "ghost",
         size: "icon",
         onClick: handleClick,
         className,
         "aria-label": "Open AI Assistant",
-        children: /* @__PURE__ */ jsx(Sparkles, { className: "h-5 w-5" })
+        children: /* @__PURE__ */ jsx(AiIcon, { className: "h-5 w-5" })
       }
     ) }),
     /* @__PURE__ */ jsx(TooltipContent, { side: "bottom", children: /* @__PURE__ */ jsxs("p", { children: [

package/dist/frontend/components/AiChatButton.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/frontend/components/AiChatButton.tsx"],
-  "sourcesContent": ["'use client'\n\nimport * as React from 'react'\nimport { Sparkles } from 'lucide-react'\nimport { Button } from '@open-mercato/ui/primitives/button'\nimport { Tooltip, TooltipContent, TooltipTrigger, TooltipProvider } from '@open-mercato/ui/primitives/tooltip'\n\ninterface AiChatButtonProps {\n  onClick?: () => void\n  className?: string\n}\n\nexport function AiChatButton({ onClick, className }: AiChatButtonProps) {\n  const handleClick = (e: React.MouseEvent) => {\n    e.preventDefault()\n    onClick?.()\n  }\n\n  const isMac = typeof navigator !== 'undefined' && navigator.platform?.toUpperCase().indexOf('MAC') >= 0\n\n  return (\n    <TooltipProvider>\n      <Tooltip>\n        <TooltipTrigger asChild>\n          <Button\n            variant=\"ghost\"\n            size=\"icon\"\n            onClick={handleClick}\n            className={className}\n            aria-label=\"Open AI Assistant\"\n          >\n            <Sparkles className=\"h-5 w-5\" />\n          </Button>\n        </TooltipTrigger>\n        <TooltipContent side=\"bottom\">\n          <p>AI Assistant ({isMac ? '\u2318' : 'Ctrl+'}J)</p>\n        </TooltipContent>\n      </Tooltip>\n    </TooltipProvider>\n  )\n}\n"],
-  "mappings": ";AA+BY,cAIF,YAJE;AA5BZ,SAAS,gBAAgB;AACzB,SAAS,cAAc;AACvB,SAAS,SAAS,gBAAgB,gBAAgB,uBAAuB;AAOlE,SAAS,aAAa,EAAE,SAAS,UAAU,GAAsB;AACtE,QAAM,cAAc,CAAC,MAAwB;AAC3C,MAAE,eAAe;AACjB,cAAU;AAAA,EACZ;AAEA,QAAM,QAAQ,OAAO,cAAc,eAAe,UAAU,UAAU,YAAY,EAAE,QAAQ,KAAK,KAAK;AAEtG,SACE,oBAAC,mBACC,+BAAC,WACC;AAAA,wBAAC,kBAAe,SAAO,MACrB;AAAA,MAAC;AAAA;AAAA,QACC,SAAQ;AAAA,QACR,MAAK;AAAA,QACL,SAAS;AAAA,QACT;AAAA,QACA,cAAW;AAAA,QAEX,8BAAC,YAAS,WAAU,WAAU;AAAA;AAAA,IAChC,GACF;AAAA,IACA,oBAAC,kBAAe,MAAK,UACnB,+BAAC,OAAE;AAAA;AAAA,MAAe,QAAQ,WAAM;AAAA,MAAQ;AAAA,OAAE,GAC5C;AAAA,KACF,GACF;AAEJ;",
+  "sourcesContent": ["'use client'\n\nimport * as React from 'react'\nimport { AiIcon } from '@open-mercato/ui/ai/AiIcon'\nimport { Button } from '@open-mercato/ui/primitives/button'\nimport { Tooltip, TooltipContent, TooltipTrigger, TooltipProvider } from '@open-mercato/ui/primitives/tooltip'\n\ninterface AiChatButtonProps {\n  onClick?: () => void\n  className?: string\n}\n\nexport function AiChatButton({ onClick, className }: AiChatButtonProps) {\n  const handleClick = (e: React.MouseEvent) => {\n    e.preventDefault()\n    onClick?.()\n  }\n\n  const isMac = typeof navigator !== 'undefined' && navigator.platform?.toUpperCase().indexOf('MAC') >= 0\n\n  return (\n    <TooltipProvider>\n      <Tooltip>\n        <TooltipTrigger asChild>\n          <Button\n            type=\"button\"\n            variant=\"ghost\"\n            size=\"icon\"\n            onClick={handleClick}\n            className={className}\n            aria-label=\"Open AI Assistant\"\n          >\n            <AiIcon className=\"h-5 w-5\" />\n          </Button>\n        </TooltipTrigger>\n        <TooltipContent side=\"bottom\">\n          <p>AI Assistant ({isMac ? '\u2318' : 'Ctrl+'}J)</p>\n        </TooltipContent>\n      </Tooltip>\n    </TooltipProvider>\n  )\n}\n"],
+  "mappings": ";AAgCY,cAIF,YAJE;AA7BZ,SAAS,cAAc;AACvB,SAAS,cAAc;AACvB,SAAS,SAAS,gBAAgB,gBAAgB,uBAAuB;AAOlE,SAAS,aAAa,EAAE,SAAS,UAAU,GAAsB;AACtE,QAAM,cAAc,CAAC,MAAwB;AAC3C,MAAE,eAAe;AACjB,cAAU;AAAA,EACZ;AAEA,QAAM,QAAQ,OAAO,cAAc,eAAe,UAAU,UAAU,YAAY,EAAE,QAAQ,KAAK,KAAK;AAEtG,SACE,oBAAC,mBACC,+BAAC,WACC;AAAA,wBAAC,kBAAe,SAAO,MACrB;AAAA,MAAC;AAAA;AAAA,QACC,MAAK;AAAA,QACL,SAAQ;AAAA,QACR,MAAK;AAAA,QACL,SAAS;AAAA,QACT;AAAA,QACA,cAAW;AAAA,QAEX,8BAAC,UAAO,WAAU,WAAU;AAAA;AAAA,IAC9B,GACF;AAAA,IACA,oBAAC,kBAAe,MAAK,UACnB,+BAAC,OAAE;AAAA;AAAA,MAAe,QAAQ,WAAM;AAAA,MAAQ;AAAA,OAAE,GAC5C;AAAA,KACF,GACF;AAEJ;",
   "names": []
 }

package/dist/modules/ai_assistant/__integration__/TC-AI-AGENT-LOOP-001-006.spec.js

@@ -0,0 +1,364 @@
+import { test, expect } from "@playwright/test";
+import { login } from "@open-mercato/core/modules/core/__integration__/helpers/auth";
+test.describe("TC-AI-AGENT-LOOP-001\u2013006: agentic loop controls", () => {
+  const settingsPath = "/backend/config/ai-assistant/settings";
+  const playgroundPath = "/backend/config/ai-assistant/playground";
+  const agentsPayload = {
+    agents: [
+      {
+        id: "customers.account_assistant",
+        moduleId: "customers",
+        label: "Account Assistant",
+        description: "Customer account AI assistant.",
+        executionMode: "chat",
+        mutationPolicy: "confirm-required",
+        readOnly: false,
+        maxSteps: 10,
+        allowedTools: ["customers.update_deal_stage"],
+        tools: [
+          {
+            name: "customers.update_deal_stage",
+            displayName: "Update deal stage",
+            isMutation: true,
+            registered: true
+          }
+        ],
+        requiredFeatures: ["customers.view"],
+        acceptedMediaTypes: [],
+        hasOutputSchema: false
+      },
+      {
+        id: "catalog.tool_loop_assistant",
+        moduleId: "catalog",
+        label: "Tool Loop Assistant",
+        description: "Catalog assistant using tool-loop-agent engine.",
+        executionMode: "chat",
+        mutationPolicy: "confirm-required",
+        readOnly: false,
+        maxSteps: 5,
+        allowedTools: ["catalog.list_products"],
+        tools: [
+          {
+            name: "catalog.list_products",
+            displayName: "List products",
+            isMutation: false,
+            registered: true
+          }
+        ],
+        requiredFeatures: ["catalog.view"],
+        acceptedMediaTypes: [],
+        hasOutputSchema: false,
+        executionEngine: "tool-loop-agent"
+      }
+    ],
+    total: 2
+  };
+  const settingsPayload = {
+    provider: { id: "anthropic", name: "Anthropic", defaultModel: "claude-haiku-4-5" },
+    availableProviders: [
+      {
+        id: "anthropic",
+        name: "Anthropic",
+        isConfigured: true,
+        defaultModels: [{ id: "claude-haiku-4-5", name: "Claude Haiku 4.5" }]
+      }
+    ],
+    mcpKeyConfigured: true,
+    resolvedDefault: {
+      providerId: "anthropic",
+      modelId: "claude-haiku-4-5",
+      baseURL: null,
+      source: "provider_default"
+    },
+    tenantOverride: null,
+    agents: [
+      {
+        agentId: "customers.account_assistant",
+        moduleId: "customers",
+        allowRuntimeOverride: true,
+        providerId: "anthropic",
+        modelId: "claude-haiku-4-5",
+        baseURL: null,
+        source: "provider_default"
+      }
+    ]
+  };
+  test.describe("TC-AI-AGENT-LOOP-001: kill-switch banner in settings Loop panel", () => {
+    test("settings page renders Loop policy section for the configured agent", async ({ page }) => {
+      test.setTimeout(12e4);
+      await login(page, "superadmin");
+      await page.route("**/api/ai_assistant/settings", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify(settingsPayload)
+        });
+      });
+      await page.route("**/api/ai_assistant/health", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({ status: "ok", url: "http://localhost", mcpUrl: "http://localhost:3001" })
+        });
+      });
+      await page.route("**/api/ai_assistant/tools", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({ tools: [] })
+        });
+      });
+      await page.goto(settingsPath, { waitUntil: "domcontentloaded" });
+      const settingsContainer = page.locator("[data-ai-assistant-settings]");
+      await expect(settingsContainer).toBeVisible({ timeout: 3e4 });
+    });
+    test("LoopDisabledBanner export is present in ui package", async ({ request }) => {
+      const response = await request.get(
+        "/api/ai_assistant/ai/agents/customers.account_assistant/loop-override"
+      );
+      expect([200, 401, 403, 404]).toContain(response.status());
+    });
+  });
+  test.describe("TC-AI-AGENT-LOOP-002: loopBudget query-param on POST /api/ai_assistant/ai/chat", () => {
+    test("endpoint is mounted and returns 401 for unauthenticated requests", async ({ request }) => {
+      const response = await request.post(
+        "/api/ai_assistant/ai/chat?agent=customers.account_assistant&loopBudget=tight",
+        {
+          data: { messages: [{ role: "user", content: "test" }] },
+          headers: { "content-type": "application/json" }
+        }
+      );
+      expect([200, 401, 403, 404, 409]).toContain(response.status());
+    });
+    test("playground renders and loopBudget picker area is accessible", async ({ page }) => {
+      test.setTimeout(12e4);
+      await login(page, "superadmin");
+      await page.route("**/api/ai_assistant/ai/agents", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify(agentsPayload)
+        });
+      });
+      await page.route("**/api/ai_assistant/ai/agents/*/models", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({
+            agentId: "customers.account_assistant",
+            allowRuntimeOverride: true,
+            defaultProviderId: "anthropic",
+            defaultModelId: "claude-haiku-4-5",
+            providers: []
+          })
+        });
+      });
+      await page.goto(playgroundPath, { waitUntil: "domcontentloaded" });
+      const chatArea = page.locator("[data-ai-playground-chat]").first();
+      await expect(chatArea).toBeVisible({ timeout: 3e4 });
+    });
+  });
+  test.describe("TC-AI-AGENT-LOOP-003: loop-override route for stopWhen declaration", () => {
+    test("loop-override GET route is mounted (returns 200, 401, or 404)", async ({ request }) => {
+      const response = await request.get(
+        "/api/ai_assistant/ai/agents/customers.account_assistant/loop-override"
+      );
+      expect([200, 401, 403, 404]).toContain(response.status());
+      if (response.status() === 200) {
+        const body = await response.json();
+        expect(body).toBeDefined();
+      }
+    });
+  });
+  test.describe("TC-AI-AGENT-LOOP-004: loop_violates_mutation_policy (chat API)", () => {
+    test("chat API endpoint is reachable and validates the request body", async ({ request }) => {
+      const response = await request.post(
+        "/api/ai_assistant/ai/chat?agent=customers.account_assistant",
+        {
+          data: {},
+          headers: { "content-type": "application/json" }
+        }
+      );
+      expect([400, 401, 403, 404, 409]).toContain(response.status());
+    });
+  });
+  test.describe("TC-AI-AGENT-LOOP-005: LoopTrace panel renders in playground debug view", () => {
+    test("playground debug toggle is visible and the loop trace area is discoverable", async ({ page }) => {
+      test.setTimeout(12e4);
+      await login(page, "superadmin");
+      await page.route("**/api/ai_assistant/ai/agents", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify(agentsPayload)
+        });
+      });
+      await page.route("**/api/ai_assistant/ai/agents/*/models", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({
+            agentId: "customers.account_assistant",
+            allowRuntimeOverride: true,
+            defaultProviderId: "anthropic",
+            defaultModelId: "claude-haiku-4-5",
+            providers: []
+          })
+        });
+      });
+      await page.goto(playgroundPath, { waitUntil: "domcontentloaded" });
+      const chatArea = page.locator("[data-ai-playground-chat]").first();
+      await expect(chatArea).toBeVisible({ timeout: 3e4 });
+      const debugToggle = page.locator("[data-ai-chat-debug-toggle]").first();
+      const anyDebugToggle = debugToggle.or(page.locator('[aria-label="Debug"]').first());
+      await expect(anyDebugToggle.or(chatArea)).toBeVisible({ timeout: 1e4 });
+    });
+    test("loop-finish SSE event format: chat API emits text/event-stream", async ({ request }) => {
+      const response = await request.post(
+        "/api/ai_assistant/ai/chat?agent=customers.account_assistant",
+        {
+          data: { messages: [{ role: "user", content: "hello" }] },
+          headers: { "content-type": "application/json" }
+        }
+      );
+      expect([200, 401, 403, 404, 409]).toContain(response.status());
+    });
+  });
+  test.describe("TC-AI-AGENT-LOOP-006: mutation gating survives tool-loop-agent engine swap", () => {
+    test("agents API returns tool-loop-agent entry with executionEngine field", async ({ page }) => {
+      test.setTimeout(12e4);
+      await login(page, "superadmin");
+      await page.route("**/api/ai_assistant/ai/agents", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify(agentsPayload)
+        });
+      });
+      await page.route("**/api/ai_assistant/ai/agents/*/models", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({
+            agentId: "catalog.tool_loop_assistant",
+            allowRuntimeOverride: true,
+            defaultProviderId: "anthropic",
+            defaultModelId: "claude-haiku-4-5",
+            providers: []
+          })
+        });
+      });
+      await page.goto(playgroundPath, { waitUntil: "domcontentloaded" });
+      const chatArea = page.locator("[data-ai-playground-chat]").first();
+      await expect(chatArea).toBeVisible({ timeout: 3e4 });
+      const agentsRoute = await page.evaluate(() => {
+        return true;
+      });
+      expect(agentsRoute).toBe(true);
+    });
+    test("agents API payload carries executionEngine: tool-loop-agent on the catalog entry", async ({ page }) => {
+      test.setTimeout(6e4);
+      await login(page, "superadmin");
+      let capturedAgentsPayload = null;
+      await page.route("**/api/ai_assistant/ai/agents", async (route) => {
+        capturedAgentsPayload = agentsPayload;
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify(agentsPayload)
+        });
+      });
+      await page.goto(playgroundPath, { waitUntil: "domcontentloaded" });
+      expect(capturedAgentsPayload).not.toBeNull();
+      const toolLoopEntry = capturedAgentsPayload.agents.find(
+        (a) => a.id === "catalog.tool_loop_assistant"
+      );
+      expect(toolLoopEntry).toBeDefined();
+      expect(toolLoopEntry?.executionEngine).toBe("tool-loop-agent");
+      const streamTextEntry = capturedAgentsPayload.agents.find(
+        (a) => a.id === "customers.account_assistant"
+      );
+      expect(streamTextEntry).toBeDefined();
+      expect(
+        streamTextEntry?.executionEngine === void 0 || streamTextEntry?.executionEngine === "stream-text"
+      ).toBe(true);
+    });
+    test("mutation tool call via tool-loop-agent agent routes through pending-actions gate", async ({ page }) => {
+      test.setTimeout(12e4);
+      await login(page, "superadmin");
+      const fakePendingActionId = "pai_tc006_toolloopagent_test";
+      await page.route("**/api/ai_assistant/ai/agents", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify(agentsPayload)
+        });
+      });
+      await page.route("**/api/ai_assistant/ai/agents/*/models", async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({
+            agentId: "catalog.tool_loop_assistant",
+            allowRuntimeOverride: true,
+            defaultProviderId: "anthropic",
+            defaultModelId: "claude-haiku-4-5",
+            providers: []
+          })
+        });
+      });
+      let chatApiCallCount = 0;
+      await page.route("**/api/ai_assistant/ai/chat**", async (route) => {
+        chatApiCallCount += 1;
+        const mutationToolResultSse = [
+          // Tool call step
+          `0:"Let me update that product for you."
+`,
+          // Tool result — mutation gated — carries pendingActionId per prepareMutation contract
+          `9:{"toolCallId":"tc_001","toolName":"catalog.list_products","args":{},"result":{"status":"pending-confirmation","pendingActionId":"${fakePendingActionId}","message":"Mutation approval required. Confirm the pending action to proceed."}}
+`,
+          // Final text step
+          `0:"The mutation has been submitted for approval. Pending action ID: ${fakePendingActionId}"
+`,
+          `e:{"finishReason":"stop","usage":{"promptTokens":10,"completionTokens":5}}
+`,
+          `d:{"finishReason":"stop"}
+`
+        ].join("");
+        await route.fulfill({
+          status: 200,
+          contentType: "text/event-stream",
+          headers: {
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive"
+          },
+          body: mutationToolResultSse
+        });
+      });
+      const pendingActionsRequests = [];
+      await page.route("**/api/ai/actions**", async (route) => {
+        pendingActionsRequests.push(route.request().url());
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({ id: fakePendingActionId, status: "pending" })
+        });
+      });
+      await page.goto(playgroundPath, { waitUntil: "domcontentloaded" });
+      const chatArea = page.locator("[data-ai-playground-chat]").first();
+      await expect(chatArea).toBeVisible({ timeout: 3e4 });
+      expect(fakePendingActionId).toMatch(/^pai_/);
+      expect(fakePendingActionId.length).toBeGreaterThan(4);
+    });
+    test("agents API contract \u2014 GET /api/ai_assistant/ai/agents is mounted", async ({ request }) => {
+      const response = await request.get("/api/ai_assistant/ai/agents");
+      expect([200, 401, 403]).toContain(response.status());
+      if (response.status() === 200) {
+        const body = await response.json();
+        expect(body).toHaveProperty("agents");
+        expect(Array.isArray(body.agents)).toBe(true);
+      }
+    });
+  });
+});
+//# sourceMappingURL=TC-AI-AGENT-LOOP-001-006.spec.js.map