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

package/dist/modules/ai_assistant/workers/ai-pending-action-cleanup.js

@@ -0,0 +1,161 @@
+import { AiPendingActionRepository } from "../data/repositories/AiPendingActionRepository.js";
+import {
+  emitAiAssistantEvent
+} from "../events.js";
+import { AiPendingActionStateError } from "../lib/pending-action-types.js";
+const metadata = {
+  queue: "ai-pending-action-cleanup",
+  id: "ai_assistant:cleanup-expired-pending-actions",
+  concurrency: 1
+};
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGES_PER_TENANT = 50;
+const defaultEmitter = async (eventId, payload) => {
+  await emitAiAssistantEvent(eventId, payload, {
+    persistent: true
+  });
+};
+async function discoverTenantsDefault(em, now) {
+  const connection = em.getConnection();
+  const rows = await connection.execute(
+    `select distinct "tenant_id", "organization_id"
+       from "ai_pending_actions"
+      where "status" = 'pending'
+        and "expires_at" < ?`,
+    [now],
+    "all"
+  );
+  if (!Array.isArray(rows)) return [];
+  const out = [];
+  for (const row of rows) {
+    const tenantId = typeof row.tenant_id === "string" ? row.tenant_id : null;
+    if (!tenantId) continue;
+    const organizationId = typeof row.organization_id === "string" ? row.organization_id : null;
+    out.push({ tenantId, organizationId });
+  }
+  return out;
+}
+function toIso(value, fallback) {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string") {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString();
+  }
+  return fallback.toISOString();
+}
+function buildExpiredPayload(row, scope, clock) {
+  const resolvedAtIso = toIso(row.resolvedAt ?? clock, clock);
+  const expiresAtIso = toIso(row.expiresAt ?? clock, clock);
+  return {
+    pendingActionId: row.id,
+    agentId: row.agentId,
+    toolName: row.toolName,
+    status: row.status,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId ?? null,
+    userId: row.createdByUserId ?? null,
+    resolvedByUserId: null,
+    resolvedAt: resolvedAtIso,
+    expiresAt: expiresAtIso,
+    expiredAt: resolvedAtIso
+  };
+}
+async function runPendingActionCleanup(options) {
+  const clock = options.now ?? /* @__PURE__ */ new Date();
+  const repo = options.repo ?? new AiPendingActionRepository(options.em);
+  const emitter = options.emitEvent ?? defaultEmitter;
+  const pageSize = Math.max(1, Math.min(500, options.pageSize ?? DEFAULT_PAGE_SIZE));
+  const discoverTenants = options.discoverTenants ?? discoverTenantsDefault;
+  const summary = {
+    tenantsScanned: 0,
+    rowsProcessed: 0,
+    rowsExpired: 0,
+    rowsSkipped: 0,
+    rowsErrored: 0
+  };
+  let tenants = [];
+  try {
+    tenants = await discoverTenants(options.em, clock);
+  } catch (error) {
+    console.error(
+      "[ai-pending-action-cleanup] Failed to discover tenants:",
+      error
+    );
+    return summary;
+  }
+  if (!tenants.length) return summary;
+  for (const scope of tenants) {
+    summary.tenantsScanned += 1;
+    for (let page = 0; page < MAX_PAGES_PER_TENANT; page += 1) {
+      let expiredRows;
+      try {
+        expiredRows = await repo.listExpired(
+          {
+            tenantId: scope.tenantId,
+            organizationId: scope.organizationId,
+            userId: null
+          },
+          clock,
+          pageSize
+        );
+      } catch (error) {
+        console.error(
+          `[ai-pending-action-cleanup] listExpired failed for tenant ${scope.tenantId}:`,
+          error
+        );
+        break;
+      }
+      if (!expiredRows.length) break;
+      for (const row of expiredRows) {
+        summary.rowsProcessed += 1;
+        try {
+          const updated = await repo.setStatus(
+            row.id,
+            "expired",
+            {
+              tenantId: scope.tenantId,
+              organizationId: scope.organizationId,
+              userId: null
+            },
+            { resolvedByUserId: null, now: clock }
+          );
+          summary.rowsExpired += 1;
+          const payload = buildExpiredPayload(updated, scope, clock);
+          try {
+            await emitter("ai.action.expired", payload);
+          } catch (emitError) {
+            console.warn(
+              `[ai-pending-action-cleanup] Failed to emit ai.action.expired for ${row.id}:`,
+              emitError
+            );
+          }
+        } catch (error) {
+          if (error instanceof AiPendingActionStateError) {
+            summary.rowsSkipped += 1;
+            console.info(
+              `[ai-pending-action-cleanup] Skipping ${row.id}: concurrent transition ${error.from} \u2192 ${error.to} already occurred`
+            );
+            continue;
+          }
+          summary.rowsErrored += 1;
+          console.error(
+            `[ai-pending-action-cleanup] Failed to expire ${row.id}:`,
+            error
+          );
+        }
+      }
+      if (expiredRows.length < pageSize) break;
+    }
+  }
+  return summary;
+}
+async function handle(_job, ctx) {
+  const em = ctx.resolve("em");
+  await runPendingActionCleanup({ em });
+}
+export {
+  handle as default,
+  metadata,
+  runPendingActionCleanup
+};
+//# sourceMappingURL=ai-pending-action-cleanup.js.map

package/dist/modules/ai_assistant/workers/ai-pending-action-cleanup.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/ai_assistant/workers/ai-pending-action-cleanup.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'\nimport { AiPendingActionRepository } from '../data/repositories/AiPendingActionRepository'\nimport type { AiPendingAction } from '../data/entities'\nimport {\n  emitAiAssistantEvent,\n  type AiActionExpiredPayload,\n  type AiAssistantEventId,\n} from '../events'\nimport { AiPendingActionStateError } from '../lib/pending-action-types'\n\n/**\n * Periodic cleanup worker for the Phase 3 WS-C mutation approval gate\n * (Step 5.12).\n *\n * Responsibilities:\n * - Sweep every tenant for rows where `status = 'pending'` AND\n *   `expires_at < now`. Pending actions expire after\n *   `AI_PENDING_ACTION_TTL_SECONDS` (default 15 minutes) \u2014 confirm/cancel\n *   routes flip them opportunistically, but rows nobody touches again\n *   would otherwise sit in `pending` forever.\n * - Atomically transition each expired row `pending \u2192 expired` via the\n *   repository's state-machine guard. `resolvedByUserId` is `null`\n *   because the worker (not a user) is the actor; `resolvedAt` is `now`.\n * - Emit the typed `ai.action.expired` event via\n *   {@link emitAiAssistantEvent} for each successful transition so\n *   downstream subscribers (UI, audit, metrics) see a single canonical\n *   terminal signal.\n *\n * Race safety:\n * - `AiPendingActionRepository.setStatus` enforces the state machine\n *   from `pending-action-types.ts`; the legal exits for `pending` are\n *   `confirmed`, `cancelled`, `expired`. If a concurrent confirm raced\n *   us and flipped the row to `confirmed` (or `executing`), the repo\n *   throws {@link AiPendingActionStateError} \u2014 we catch, log, and skip,\n *   WITHOUT emitting an event for that row (the confirm path already\n *   emitted the canonical signal). Same behaviour if the cancel helper\n *   beat us via its TTL short-circuit.\n * - Single-row failures NEVER abort the batch \u2014 the worker logs and\n *   continues to the next row.\n * - Running the worker twice on an already-`expired` row is a no-op:\n *   `setStatus(expired)` short-circuits on `existing.status === nextStatus`\n *   (see repo), so no second emit.\n *\n * Tenant scoping:\n * - `listExpired` is tenant-scoped, so the worker first discovers the\n *   distinct set of `tenant_id` values that have expired pending rows\n *   via a narrow native SELECT (no row contents read). It then iterates\n *   per tenant, reusing the repo and therefore the encrypted-read\n *   contract. Each `setStatus` write carries the row's own tenant\n *   scope \u2014 there is no cross-tenant write.\n *\n * Pagination:\n * - `listExpired` is called with a bounded page size and looped until\n *   the tenant's expired queue drains. A per-tenant loop cap prevents\n *   runaway behaviour if new rows keep expiring during the sweep (the\n *   next scheduled tick picks up any leftovers).\n */\n\nexport const metadata: WorkerMeta = {\n  queue: 'ai-pending-action-cleanup',\n  id: 'ai_assistant:cleanup-expired-pending-actions',\n  concurrency: 1,\n}\n\nconst DEFAULT_PAGE_SIZE = 100\nconst MAX_PAGES_PER_TENANT = 50\n\nexport type PendingActionCleanupEmitter = (\n  eventId: Extract<AiAssistantEventId, 'ai.action.expired'>,\n  payload: AiActionExpiredPayload,\n) => Promise<void>\n\nconst defaultEmitter: PendingActionCleanupEmitter = async (eventId, payload) => {\n  await emitAiAssistantEvent(eventId, payload as unknown as Record<string, unknown>, {\n    persistent: true,\n  })\n}\n\nexport interface PendingActionCleanupRunOptions {\n  em: EntityManager\n  repo?: AiPendingActionRepository\n  emitEvent?: PendingActionCleanupEmitter\n  now?: Date\n  pageSize?: number\n  /** Injectable tenant-discovery seam for unit tests. */\n  discoverTenants?: (em: EntityManager, now: Date) => Promise<TenantScope[]>\n}\n\nexport interface PendingActionCleanupSummary {\n  tenantsScanned: number\n  rowsProcessed: number\n  rowsExpired: number\n  rowsSkipped: number\n  rowsErrored: number\n}\n\nexport interface TenantScope {\n  tenantId: string\n  organizationId: string | null\n}\n\nasync function discoverTenantsDefault(\n  em: EntityManager,\n  now: Date,\n): Promise<TenantScope[]> {\n  const connection = em.getConnection()\n  const rows = await connection.execute(\n    `select distinct \"tenant_id\", \"organization_id\"\n       from \"ai_pending_actions\"\n      where \"status\" = 'pending'\n        and \"expires_at\" < ?`,\n    [now],\n    'all',\n  )\n  if (!Array.isArray(rows)) return []\n  const out: TenantScope[] = []\n  for (const row of rows as Array<Record<string, unknown>>) {\n    const tenantId = typeof row.tenant_id === 'string' ? row.tenant_id : null\n    if (!tenantId) continue\n    const organizationId =\n      typeof row.organization_id === 'string' ? row.organization_id : null\n    out.push({ tenantId, organizationId })\n  }\n  return out\n}\n\nfunction toIso(value: Date | string | null | undefined, fallback: Date): string {\n  if (value instanceof Date) return value.toISOString()\n  if (typeof value === 'string') {\n    const parsed = new Date(value)\n    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString()\n  }\n  return fallback.toISOString()\n}\n\nfunction buildExpiredPayload(\n  row: AiPendingAction,\n  scope: TenantScope,\n  clock: Date,\n): AiActionExpiredPayload {\n  const resolvedAtIso = toIso(row.resolvedAt ?? clock, clock)\n  const expiresAtIso = toIso(row.expiresAt ?? clock, clock)\n  return {\n    pendingActionId: row.id,\n    agentId: row.agentId,\n    toolName: row.toolName,\n    status: row.status,\n    tenantId: scope.tenantId,\n    organizationId: scope.organizationId ?? null,\n    userId: row.createdByUserId ?? null,\n    resolvedByUserId: null,\n    resolvedAt: resolvedAtIso,\n    expiresAt: expiresAtIso,\n    expiredAt: resolvedAtIso,\n  }\n}\n\nexport async function runPendingActionCleanup(\n  options: PendingActionCleanupRunOptions,\n): Promise<PendingActionCleanupSummary> {\n  const clock = options.now ?? new Date()\n  const repo = options.repo ?? new AiPendingActionRepository(options.em)\n  const emitter = options.emitEvent ?? defaultEmitter\n  const pageSize = Math.max(1, Math.min(500, options.pageSize ?? DEFAULT_PAGE_SIZE))\n  const discoverTenants = options.discoverTenants ?? discoverTenantsDefault\n\n  const summary: PendingActionCleanupSummary = {\n    tenantsScanned: 0,\n    rowsProcessed: 0,\n    rowsExpired: 0,\n    rowsSkipped: 0,\n    rowsErrored: 0,\n  }\n\n  let tenants: TenantScope[] = []\n  try {\n    tenants = await discoverTenants(options.em, clock)\n  } catch (error) {\n    console.error(\n      '[ai-pending-action-cleanup] Failed to discover tenants:',\n      error,\n    )\n    return summary\n  }\n\n  if (!tenants.length) return summary\n\n  for (const scope of tenants) {\n    summary.tenantsScanned += 1\n    for (let page = 0; page < MAX_PAGES_PER_TENANT; page += 1) {\n      let expiredRows: AiPendingAction[]\n      try {\n        expiredRows = await repo.listExpired(\n          {\n            tenantId: scope.tenantId,\n            organizationId: scope.organizationId,\n            userId: null,\n          },\n          clock,\n          pageSize,\n        )\n      } catch (error) {\n        console.error(\n          `[ai-pending-action-cleanup] listExpired failed for tenant ${scope.tenantId}:`,\n          error,\n        )\n        break\n      }\n\n      if (!expiredRows.length) break\n\n      for (const row of expiredRows) {\n        summary.rowsProcessed += 1\n        try {\n          const updated = await repo.setStatus(\n            row.id,\n            'expired',\n            {\n              tenantId: scope.tenantId,\n              organizationId: scope.organizationId,\n              userId: null,\n            },\n            { resolvedByUserId: null, now: clock },\n          )\n          summary.rowsExpired += 1\n          const payload = buildExpiredPayload(updated, scope, clock)\n          try {\n            await emitter('ai.action.expired', payload)\n          } catch (emitError) {\n            console.warn(\n              `[ai-pending-action-cleanup] Failed to emit ai.action.expired for ${row.id}:`,\n              emitError,\n            )\n          }\n        } catch (error) {\n          if (error instanceof AiPendingActionStateError) {\n            summary.rowsSkipped += 1\n            console.info(\n              `[ai-pending-action-cleanup] Skipping ${row.id}: concurrent transition ${error.from} \u2192 ${error.to} already occurred`,\n            )\n            continue\n          }\n          summary.rowsErrored += 1\n          console.error(\n            `[ai-pending-action-cleanup] Failed to expire ${row.id}:`,\n            error,\n          )\n        }\n      }\n\n      if (expiredRows.length < pageSize) break\n    }\n  }\n\n  return summary\n}\n\ntype HandlerContext = JobContext & {\n  resolve: <T = unknown>(name: string) => T\n}\n\nexport default async function handle(\n  _job: QueuedJob,\n  ctx: HandlerContext,\n): Promise<void> {\n  const em = ctx.resolve<EntityManager>('em')\n  await runPendingActionCleanup({ em })\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/generated/entities/ai_agent_mutation_policy_override/index.ts

@@ -0,0 +1,9 @@
+export const id = "id";
+export const tenant_id = "tenant_id";
+export const organization_id = "organization_id";
+export const agent_id = "agent_id";
+export const mutation_policy = "mutation_policy";
+export const notes = "notes";
+export const created_by_user_id = "created_by_user_id";
+export const created_at = "created_at";
+export const updated_at = "updated_at";

package/generated/entities/ai_agent_prompt_override/index.ts

@@ -0,0 +1,10 @@
+export const id = "id";
+export const tenant_id = "tenant_id";
+export const organization_id = "organization_id";
+export const agent_id = "agent_id";
+export const version = "version";
+export const sections = "sections";
+export const notes = "notes";
+export const created_by_user_id = "created_by_user_id";
+export const created_at = "created_at";
+export const updated_at = "updated_at";

package/generated/entities/ai_pending_action/index.ts

@@ -0,0 +1,24 @@
+export const id = "id";
+export const tenant_id = "tenant_id";
+export const organization_id = "organization_id";
+export const agent_id = "agent_id";
+export const tool_name = "tool_name";
+export const conversation_id = "conversation_id";
+export const target_entity_type = "target_entity_type";
+export const target_record_id = "target_record_id";
+export const normalized_input = "normalized_input";
+export const field_diff = "field_diff";
+export const records = "records";
+export const failed_records = "failed_records";
+export const side_effects_summary = "side_effects_summary";
+export const record_version = "record_version";
+export const attachment_ids = "attachment_ids";
+export const idempotency_key = "idempotency_key";
+export const created_by_user_id = "created_by_user_id";
+export const status = "status";
+export const queue_mode = "queue_mode";
+export const execution_result = "execution_result";
+export const created_at = "created_at";
+export const expires_at = "expires_at";
+export const resolved_at = "resolved_at";
+export const resolved_by_user_id = "resolved_by_user_id";

package/generated/entities.ids.generated.ts

@@ -0,0 +1,13 @@
+// AUTO-GENERATED by mercato generate entity-ids
+export const M = {
+    "ai_assistant": "ai_assistant"
+  } as const, E = {
+    "ai_assistant": {
+      "ai_agent_prompt_override": "ai_assistant:ai_agent_prompt_override",
+      "ai_pending_action": "ai_assistant:ai_pending_action",
+      "ai_agent_mutation_policy_override": "ai_assistant:ai_agent_mutation_policy_override"
+    }
+  } as const;
+
+export type KnownModuleId = keyof typeof M;
+export type KnownEntities = typeof E;

package/generated/entity-fields-registry.ts

@@ -0,0 +1,57 @@
+// AUTO-GENERATED by mercato generate entity-ids
+// Static registry for entity fields - eliminates dynamic imports for Turbopack compatibility
+export const entityFieldsRegistry: Record<string, Record<string, string>> = {
+    "ai_agent_mutation_policy_override": {
+      "id": "id",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "agent_id": "agent_id",
+      "mutation_policy": "mutation_policy",
+      "notes": "notes",
+      "created_by_user_id": "created_by_user_id",
+      "created_at": "created_at",
+      "updated_at": "updated_at"
+    },
+    "ai_agent_prompt_override": {
+      "id": "id",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "agent_id": "agent_id",
+      "version": "version",
+      "sections": "sections",
+      "notes": "notes",
+      "created_by_user_id": "created_by_user_id",
+      "created_at": "created_at",
+      "updated_at": "updated_at"
+    },
+    "ai_pending_action": {
+      "id": "id",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "agent_id": "agent_id",
+      "tool_name": "tool_name",
+      "conversation_id": "conversation_id",
+      "target_entity_type": "target_entity_type",
+      "target_record_id": "target_record_id",
+      "normalized_input": "normalized_input",
+      "field_diff": "field_diff",
+      "records": "records",
+      "failed_records": "failed_records",
+      "side_effects_summary": "side_effects_summary",
+      "record_version": "record_version",
+      "attachment_ids": "attachment_ids",
+      "idempotency_key": "idempotency_key",
+      "created_by_user_id": "created_by_user_id",
+      "status": "status",
+      "queue_mode": "queue_mode",
+      "execution_result": "execution_result",
+      "created_at": "created_at",
+      "expires_at": "expires_at",
+      "resolved_at": "resolved_at",
+      "resolved_by_user_id": "resolved_by_user_id"
+    }
+  };
+
+export function getEntityFields(slug: string): Record<string, string> | undefined {
+  return entityFieldsRegistry[slug];
+}

package/jest.config.cjs

@@ -3,10 +3,17 @@ module.exports = {
   testEnvironment: 'node',
   watchman: false,
   rootDir: '.',
+  maxWorkers: 4,
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
   moduleNameMapper: {
     '^@open-mercato/ai-assistant/(.*)$': '<rootDir>/src/$1',
     '^@open-mercato/shared/(.*)$': '<rootDir>/../shared/src/$1',
+    // Redirect core module imports to the TS source so Jest's ts-jest
+    // transformer handles them cleanly. Without this, the built dist/
+    // ESM output trips Jest's CJS-only parser (see
+    // pending-action-recheck.ts importing `@open-mercato/core/modules/
+    // attachments/data/entities` after Step 5.8).
+    '^@open-mercato/core/(.*)$': '<rootDir>/../core/src/$1',
   },
   transform: {
     '^.+\\.(t|j)sx?$': [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/ai-assistant",
-  "version": "0.5.1-develop.3036.f02c281f23",
+  "version": "0.5.1-develop.3045.b4b3320cc2",
   "type": "module",
   "engines": {
     "node": ">=22.0.0"
@@ -98,12 +98,12 @@
     "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.5.1-develop.3036.f02c281f23",
-    "@open-mercato/ui": "0.5.1-develop.3036.f02c281f23",
+    "@open-mercato/shared": "0.5.1-develop.3045.b4b3320cc2",
+    "@open-mercato/ui": "0.5.1-develop.3045.b4b3320cc2",
     "zod": ">=3.23.0"
   },
   "devDependencies": {
-    "@open-mercato/cli": "0.5.1-develop.3036.f02c281f23",
+    "@open-mercato/cli": "0.5.1-develop.3045.b4b3320cc2",
     "tsx": "^4.21.0"
   },
   "publishConfig": {

package/src/index.ts

@@ -29,6 +29,41 @@
 // Re-export types
 export * from './modules/ai_assistant/lib/types'
 
+// Focused-agent definition types + helper
+export {
+  defineAiAgent,
+  defineAiAgentExtension,
+  type AiAgentDefinition,
+  type AiAgentExtension,
+  type AiAgentSuggestion,
+  type AiAgentExecutionMode,
+  type AiAgentMutationPolicy,
+  type AiAgentAcceptedMediaType,
+  type AiAgentDataOperation,
+  type AiAgentPageContextInput,
+  type AiAgentStructuredOutput,
+  type AiAgentDataCapabilities,
+} from './modules/ai_assistant/lib/ai-agent-definition'
+
+// Additive AI tool builder
+export { defineAiTool } from './modules/ai_assistant/lib/ai-tool-definition'
+
+// Attachment-bridge contract types (spec Phase 0 §8/§10, implementation-ready for Phase 3 runtime)
+export {
+  type AttachmentSource,
+  type AiResolvedAttachmentPart,
+  type AiUiPart,
+  type AiChatRequestContext,
+} from './modules/ai_assistant/lib/attachment-bridge-types'
+
+// Prompt-composition primitives (spec Phase 0 §8, implementation-ready for Phase 3 prompt composer)
+export {
+  definePromptTemplate,
+  type PromptSectionName,
+  type PromptSection,
+  type PromptTemplate,
+} from './modules/ai_assistant/lib/prompt-composition-types'
+
 // Tool registry
 export {
   registerMcpTool,
@@ -58,6 +93,186 @@ export {
 // Tool loader
 export { loadAllModuleTools, indexToolsForSearch } from './modules/ai_assistant/lib/tool-loader'
 
+// AI Overrides — module-to-module + modules.ts + programmatic agent/tool replacement.
+// See `apps/docs/docs/framework/ai-assistant/overrides.mdx`.
+export {
+  applyAiAgentOverrides,
+  applyAiAgentExtensions,
+  applyAiToolOverrides,
+  applyAiOverridesFromEnabledModules,
+  resetProgrammaticOverridesForTests,
+  type AiAgentOverride,
+  type AiToolOverride,
+  type AiAgentOverridesMap,
+  type AiToolOverridesMap,
+  type AiAgentOverrideConfigEntry,
+  type AiAgentExtensionConfigEntry,
+  type AiToolOverrideConfigEntry,
+  type EnabledModuleAiOverrides,
+} from './modules/ai_assistant/lib/ai-overrides'
+
+// Agent registry (Phase 1 WS-A — read-side lookup API, no policy / dispatch)
+export {
+  loadAgentRegistry,
+  getAgent,
+  listAgents,
+  listAgentsByModule,
+  resetAgentRegistryForTests,
+} from './modules/ai_assistant/lib/agent-registry'
+
+// Agent runtime policy gate (Phase 1 WS-A — pure policy decisions, no HTTP or AI SDK wiring)
+export {
+  checkAgentPolicy,
+  type AgentPolicyDenyCode,
+  type AgentPolicyDecision,
+  type AgentPolicyAuthContext,
+  type AgentPolicyCheckInput,
+} from './modules/ai_assistant/lib/agent-policy'
+
+// AI SDK helpers (Phase 1 WS-B — chat-mode runtime + transport glue)
+export {
+  resolveAiAgentTools,
+  AgentPolicyError,
+  type ResolveAiAgentToolsInput,
+  type ResolvedAgentTools,
+  type AiUiPartQueue,
+} from './modules/ai_assistant/lib/agent-tools'
+
+// In-process API operation runner (Phase 1 of API-backed AI tool DRY refactor)
+export {
+  createAiApiOperationRunner,
+  type AiApiOperationRequest,
+  type AiApiOperationResponse,
+  type AiApiOperationRunner,
+  type AiApiOperationRunnerOptions,
+  type AiApiHttpMethod,
+  type AiToolExecutionContext,
+} from './modules/ai_assistant/lib/ai-api-operation-runner'
+
+// API-backed AI tool helper (Phase 2 of API-backed AI tool DRY refactor)
+export {
+  defineApiBackedAiTool,
+  type ApiBackedAiToolConfig,
+} from './modules/ai_assistant/lib/api-backed-tool'
+
+// Mutation-preparation helper (Phase 3 WS-C — Step 5.6)
+export {
+  prepareMutation,
+  computeMutationIdempotencyKey,
+  AiMutationPreparationError,
+  MUTATION_PREVIEW_CARD_COMPONENT,
+  type PrepareMutationInput,
+  type PrepareMutationContext,
+  type PrepareMutationResult,
+} from './modules/ai_assistant/lib/prepare-mutation'
+
+export {
+  runAiAgentText,
+  runAiAgentObject,
+  composeSystemPrompt,
+  type RunAiAgentTextInput,
+  type RunAiAgentObjectInput,
+  type RunAiAgentObjectOutputOverride,
+  type RunAiAgentObjectResult,
+  type RunAiAgentObjectGenerateResult,
+  type RunAiAgentObjectStreamResult,
+  type AgentRequestPageContext,
+} from './modules/ai_assistant/lib/agent-runtime'
+
+export {
+  createAiAgentTransport,
+  type CreateAiAgentTransportInput,
+} from './modules/ai_assistant/lib/agent-transport'
+
+// Pending-action types / enums / state-machine guard (Phase 3 WS-C — Step 5.5)
+export {
+  AI_PENDING_ACTION_STATUSES,
+  AI_PENDING_ACTION_QUEUE_MODES,
+  AI_PENDING_ACTION_ALLOWED_TRANSITIONS,
+  AI_PENDING_ACTION_TERMINAL_STATUSES,
+  AI_PENDING_ACTION_DEFAULT_TTL_SECONDS,
+  AI_PENDING_ACTION_TTL_ENV_VAR,
+  AiPendingActionStateError,
+  isAiPendingActionStatus,
+  isAiPendingActionQueueMode,
+  isTerminalAiPendingActionStatus,
+  isAllowedAiPendingActionTransition,
+  resolveAiPendingActionTtlSeconds,
+  type AiPendingActionStatus,
+  type AiPendingActionQueueMode,
+  type AiPendingActionRecordDiff,
+  type AiPendingActionFailedRecord,
+  type AiPendingActionFieldDiff,
+  type AiPendingActionExecutionResult,
+} from './modules/ai_assistant/lib/pending-action-types'
+
+// Client-facing pending-action serializer (Phase 3 WS-C — Step 5.7, reused by 5.8 / 5.9 / 5.10)
+export {
+  serializePendingActionForClient,
+  type SerializedPendingAction,
+  type SerializablePendingActionRow,
+} from './modules/ai_assistant/lib/pending-action-client'
+
+// Pending-action confirm re-check contract (Phase 3 WS-C — Step 5.8, reused by 5.9)
+export {
+  runPendingActionRechecks,
+  checkStatusAndExpiry,
+  checkAgentAndFeatures,
+  checkToolWhitelist,
+  checkAttachmentScope,
+  checkRecordVersion,
+  PENDING_ACTION_RECHECK_CODES,
+  isPendingActionRecheckCode,
+  type PendingActionRecheckCode,
+  type PendingActionRecheckResult,
+  type PendingActionRecheckInput,
+  type PendingActionAuthContext,
+} from './modules/ai_assistant/lib/pending-action-recheck'
+
+// Pending-action confirm executor (Phase 3 WS-C — Step 5.8)
+export {
+  executePendingActionConfirm,
+  PENDING_ACTION_CONFIRMED_EVENT_ID,
+  type PendingActionExecuteInput,
+  type PendingActionExecuteContext,
+  type PendingActionExecuteResult,
+  type PendingActionExecuteOk,
+  type PendingActionExecuteFail,
+} from './modules/ai_assistant/lib/pending-action-executor'
+
+// Pending-action cancel executor (Phase 3 WS-C — Step 5.9)
+export {
+  executePendingActionCancel,
+  PENDING_ACTION_CANCELLED_EVENT_ID,
+  PENDING_ACTION_EXPIRED_EVENT_ID,
+  type PendingActionCancelInput,
+  type PendingActionCancelContext,
+  type PendingActionCancelResult,
+  type PendingActionCancelStatus,
+} from './modules/ai_assistant/lib/pending-action-cancel'
+
+// Shared AI model factory (Phase 3 WS-A — Step 5.1)
+export {
+  createModelFactory,
+  AiModelFactoryError,
+  type AiModelFactory,
+  type AiModelFactoryInput,
+  type AiModelResolution,
+  type AiModelFactoryErrorCode,
+  type AiModelInstance,
+  type CreateModelFactoryDependencies,
+} from './modules/ai_assistant/lib/model-factory'
+
+// Attachment-to-model bridge (Phase 1 WS-C — Step 3.7)
+export {
+  resolveAttachmentParts,
+  resolveAttachmentPartsForAgent,
+  attachmentPartsToUiFileParts,
+  summarizeAttachmentPartsForPrompt,
+  type ResolveAttachmentPartsInput,
+  type AttachmentSigner,
+} from './modules/ai_assistant/lib/attachment-parts'
+
 // OpenCode client
 export {
   OpenCodeClient,

package/src/modules/ai_assistant/__integration__/README.md

@@ -0,0 +1,5 @@
+# ai_assistant integration tests
+
+Per `.ai/runs/2026-04-18-ai-framework-unification/NOTIFY.md` feedback:
+integration specs for ai_assistant live here; cross-cutting helpers live at
+`.ai/qa/tests/helpers/` (shared across modules).