@open-mercato/core 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3043.1a796c3920

package/src/modules/customer_accounts/widgets/injection/portal-ai-assistant-trigger/widget.client.tsx

@@ -0,0 +1,136 @@
+"use client"
+
+/**
+ * Step 4.10 — Portal AiChat injection widget (client).
+ *
+ * Renders an "Ask AI" trigger button + sheet inside the portal profile
+ * page's `portal:profile:after` injection spot. Clicking the trigger
+ * opens a right-side sheet embedding `<AiChat>` wired to
+ * `customers.account_assistant`.
+ *
+ * Feature-gating:
+ *   - Declared in `widget.ts` metadata (`portal.account.manage`).
+ *   - The widget ALSO self-checks `context.resolvedFeatures` as a
+ *     defense-in-depth measure so the button never renders for a
+ *     customer who lacks the feature (portal pages are themselves
+ *     feature-gated, but the injection registry does not currently
+ *     enforce metadata.features at render time).
+ *
+ * `pageContext` shape:
+ *   { view: 'portal.profile', recordType: 'customer', recordId: <userId|null>, extra: {} }
+ */
+
+import * as React from 'react'
+import { Sparkles } from 'lucide-react'
+import { AiChat } from '@open-mercato/ui/ai/AiChat'
+import { Button } from '@open-mercato/ui/primitives/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@open-mercato/ui/primitives/dialog'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { cn } from '@open-mercato/shared/lib/utils'
+import { hasFeature } from '@open-mercato/shared/security/features'
+
+export const PORTAL_AI_INJECT_AGENT_ID = 'customers.account_assistant'
+export const PORTAL_AI_INJECT_REQUIRED_FEATURE = 'portal.account.manage'
+
+export interface PortalAiInjectPageContext {
+  view: 'portal.profile'
+  recordType: 'customer'
+  recordId: string | null
+  extra: Record<string, never>
+}
+
+interface PortalInjectionContext {
+  orgSlug?: string
+  user?: { id?: string | null } | null
+  resolvedFeatures?: string[]
+  isPortalAdmin?: boolean
+}
+
+interface PortalAiAssistantTriggerProps {
+  context?: PortalInjectionContext
+}
+
+function readUserId(user: PortalInjectionContext['user']): string | null {
+  if (!user) return null
+  const id = user.id
+  return typeof id === 'string' && id.length > 0 ? id : null
+}
+
+export default function PortalAiAssistantTriggerWidget({ context }: PortalAiAssistantTriggerProps) {
+  const t = useT()
+  const [open, setOpen] = React.useState(false)
+
+  const resolvedFeatures = Array.isArray(context?.resolvedFeatures)
+    ? (context?.resolvedFeatures as string[])
+    : []
+  const featureAllowed =
+    context?.isPortalAdmin === true ||
+    hasFeature(resolvedFeatures, PORTAL_AI_INJECT_REQUIRED_FEATURE)
+
+  const pageContext = React.useMemo<PortalAiInjectPageContext>(() => ({
+    view: 'portal.profile',
+    recordType: 'customer',
+    recordId: readUserId(context?.user ?? null),
+    extra: {},
+  }), [context?.user])
+
+  if (!featureAllowed) return null
+
+  return (
+    <div className="mt-6" data-ai-portal-inject-wrapper="">
+      <Button
+        type="button"
+        variant="outline"
+        size="sm"
+        onClick={() => setOpen(true)}
+        data-ai-portal-inject-trigger=""
+        aria-label={t(
+          'customer_accounts.portal_ai_assistant.trigger.ariaLabel',
+          'Open portal AI assistant',
+        )}
+      >
+        <Sparkles className="size-4" aria-hidden />
+        <span>{t('customer_accounts.portal_ai_assistant.trigger.label', 'Ask AI')}</span>
+      </Button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent
+          className={cn(
+            'sm:max-w-xl sm:top-0 sm:bottom-0 sm:right-0 sm:left-auto sm:translate-x-0 sm:translate-y-0',
+            'sm:h-screen sm:max-h-screen sm:rounded-none sm:rounded-l-2xl',
+            'flex flex-col gap-3 p-4',
+          )}
+          data-ai-portal-inject-sheet=""
+        >
+          <DialogHeader>
+            <DialogTitle>
+              {t('customer_accounts.portal_ai_assistant.sheet.title', 'Portal AI assistant')}
+            </DialogTitle>
+            <DialogDescription>
+              {t(
+                'customer_accounts.portal_ai_assistant.sheet.description',
+                'Read-only assistant for portal customers. Ask about your account and recent activity.',
+              )}
+            </DialogDescription>
+          </DialogHeader>
+          <div className="min-h-0 flex-1" data-ai-portal-inject-chat-container="">
+            <AiChat
+              agent={PORTAL_AI_INJECT_AGENT_ID}
+              pageContext={pageContext as unknown as Record<string, unknown>}
+              className="h-full"
+              placeholder={t(
+                'customer_accounts.portal_ai_assistant.sheet.composerPlaceholder',
+                'Ask about your account...',
+              )}
+            />
+          </div>
+        </DialogContent>
+      </Dialog>
+    </div>
+  )
+}

package/src/modules/customer_accounts/widgets/injection/portal-ai-assistant-trigger/widget.ts

@@ -0,0 +1,43 @@
+import type { InjectionWidgetModule } from '@open-mercato/shared/modules/widgets/injection'
+import PortalAiAssistantTriggerWidget from './widget.client'
+
+/**
+ * Step 4.10 — Portal AiChat injection example.
+ *
+ * Demonstrates how a third-party module can drop `<AiChat>` onto a
+ * portal page it does NOT own (the customer-portal profile page) via
+ * the existing widget-injection system. Targets spot
+ * `portal:profile:after` (see `PortalInjectionSpots.pageAfter('profile')`
+ * in `packages/ui/src/backend/injection/spotIds.ts`).
+ *
+ * The trigger opens a right-side sheet embedding
+ * `<AiChat agent="customers.account_assistant" pageContext={...} />`.
+ * `pageContext` follows the spec §10.1 shape:
+ *
+ *   { view: 'portal.profile',
+ *     recordType: 'customer',
+ *     recordId: <customer-user-id | null>,
+ *     extra: {} }
+ *
+ * Gated behind customer feature `portal.account.manage`, which is the
+ * closest existing customer-facing feature (no dedicated
+ * `portal.ai_assistant.view` feature exists yet — tracked as a
+ * follow-up gap; see Step 4.10 checks).
+ *
+ * Phase 2 ships `customers.account_assistant` as the agent (read-only)
+ * because no dedicated customer-portal agent has been introduced yet.
+ */
+const widget: InjectionWidgetModule<Record<string, unknown>, Record<string, unknown>> = {
+  metadata: {
+    id: 'customer_accounts.injection.portal-ai-assistant-trigger',
+    title: 'Portal AI Assistant Trigger',
+    description:
+      'Renders an "Ask AI" button on the portal profile page that opens a sheet embedding the customers account assistant.',
+    features: ['portal.account.manage'],
+    priority: 100,
+    enabled: true,
+  },
+  Widget: PortalAiAssistantTriggerWidget,
+}
+
+export default widget

package/src/modules/customer_accounts/widgets/injection-table.ts

@@ -19,6 +19,15 @@ export const injectionTable: ModuleInjectionTable = {
       priority: 200,
     },
   ],
+  // Step 4.10 — Portal AiChat injection example.
+  // Mapped to the portal profile page's `pageAfter('profile')` spot;
+  // third-party modules targeting other portal pages can copy this entry.
+  'portal:profile:after': [
+    {
+      widgetId: 'customer_accounts.injection.portal-ai-assistant-trigger',
+      priority: 100,
+    },
+  ],
 }
 
 export default injectionTable

package/src/modules/customers/AGENTS.md

@@ -93,3 +93,16 @@ Use `collectCustomFieldValues()` from `@open-mercato/ui/backend/utils/customFiel
 ## Module Files Checklist — All MUST Be Present
 
 `acl.ts`, `ce.ts`, `di.ts`, `events.ts`, `index.ts`, `notifications.ts`, `search.ts`, `setup.ts`, `analytics.ts`, `vector.ts`
+
+## AI Agents in This Module
+
+This module is the reference implementation for the AI framework. Copy `ai-agents.ts` + `ai-tools.ts` when adding AI agents to other modules. See `/framework/ai-assistant/agents` for the full guide.
+
+| Agent ID | Mode | Policy | Purpose |
+|----------|------|--------|---------|
+| `customers.account_assistant` | chat | read-only (mutation-capable via per-tenant override that unlocks `customers.update_deal_stage`; see `packages/core/src/modules/customers/ai-agents.ts` for the whitelist and prompt) | Operator-facing assistant that explores people, companies, deals, activities, tasks, addresses, tags, and settings through the customers tool pack. |
+| `customers.update_deal_stage` | tool (mutation) | `destructive-confirm-required` — goes through `prepareMutation` + the approval card | Moves a deal between stages / flips status between open, won, lost. Declared via `defineAiTool` in `ai-tools.ts` and exposed only when the tenant mutation-policy override promotes the agent above read-only. |
+
+`<AiChat agent="customers.account_assistant" />` is injected in two places (both live in `widgets/injection/`):
+- People list: `data-table:customers.people.list:header` via the `ai-assistant-trigger` widget.
+- Deal detail: `detail:customers.deal:header` via the `ai-deal-detail-trigger` widget.

package/src/modules/customers/ai-agents-context.ts

@@ -0,0 +1,150 @@
+/**
+ * Page-context hydration helpers for `customers.account_assistant`
+ * (Phase 3 WS-A, Step 5.2).
+ *
+ * The `resolvePageContext` callback on the module-root `ai-agents.ts`
+ * delegates to this file when the incoming request carries an `entityType`
+ * + `recordId` combination the runtime recognises. Each helper reuses the
+ * same tool-pack handler the Step 3.9 pack ships (`customers.get_person`,
+ * `customers.get_company`, `customers.get_deal`) so there is exactly one
+ * loader per record type — not a second parallel query path that could
+ * drift from what the agent is actually allowed to call.
+ *
+ * Every helper:
+ *  - Runs only when `tenantId` is present; cross-tenant ids return `null`
+ *    (the tool handlers already guard tenant scope via
+ *    `findOneWithDecryption`, but we double-check in the output).
+ *  - Caps `includeRelated` payloads to what the tool's own cap enforces.
+ *  - Swallows errors and returns `null` so a hydration fault NEVER breaks
+ *    the chat request — the runtime will proceed without extra context.
+ */
+import type { AwilixContainer } from 'awilix'
+import customersAiTools from './ai-tools'
+import type {
+  CustomersAiToolDefinition,
+  CustomersToolContext,
+} from './ai-tools/types'
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+function isUuid(value: unknown): value is string {
+  return typeof value === 'string' && UUID_REGEX.test(value)
+}
+
+function findTool(name: string): CustomersAiToolDefinition | null {
+  return (
+    (customersAiTools as CustomersAiToolDefinition[]).find((tool) => tool.name === name) ?? null
+  )
+}
+
+function buildToolContext(
+  container: AwilixContainer,
+  tenantId: string,
+  organizationId: string | null,
+): CustomersToolContext {
+  return {
+    tenantId,
+    organizationId,
+    userId: null,
+    container,
+    userFeatures: [],
+    isSuperAdmin: true,
+    apiKeySecret: undefined,
+    sessionId: undefined,
+  }
+}
+
+function renderContextBlock(label: string, payload: unknown): string {
+  return `## Page context — ${label}\n${JSON.stringify(payload, null, 2)}`
+}
+
+export interface HydrateCustomersContextInput {
+  entityType: string
+  recordId: string
+  container: AwilixContainer
+  tenantId: string | null
+  organizationId: string | null
+}
+
+const PERSON_ENTITY_TYPES = new Set([
+  'person',
+  'customers.person',
+  'customers:customer_entity',
+])
+
+const COMPANY_ENTITY_TYPES = new Set([
+  'company',
+  'customers.company',
+])
+
+const DEAL_ENTITY_TYPES = new Set([
+  'deal',
+  'customers.deal',
+])
+
+async function hydrateWithTool(
+  toolName: string,
+  inputArgs: Record<string, unknown>,
+  toolContext: CustomersToolContext,
+): Promise<unknown | null> {
+  const tool = findTool(toolName)
+  if (!tool) {
+    console.warn(`[customers.account_assistant] resolvePageContext: tool "${toolName}" not registered`)
+    return null
+  }
+  try {
+    const result = await tool.handler(inputArgs as never, toolContext)
+    if (!result || typeof result !== 'object') return null
+    if ((result as { found?: boolean }).found === false) return null
+    return result
+  } catch (error) {
+    console.warn(
+      `[customers.account_assistant] resolvePageContext: tool "${toolName}" failed (reason="hydration_error"); skipping`,
+      error instanceof Error ? error.message : error,
+    )
+    return null
+  }
+}
+
+export async function hydrateCustomersAccountContext(
+  input: HydrateCustomersContextInput,
+): Promise<string | null> {
+  const tenantId = input.tenantId
+  if (!tenantId) return null
+  if (!isUuid(input.recordId)) return null
+  const entityType = input.entityType.trim().toLowerCase()
+  if (!entityType) return null
+  const toolContext = buildToolContext(input.container, tenantId, input.organizationId)
+
+  if (PERSON_ENTITY_TYPES.has(entityType)) {
+    const result = await hydrateWithTool(
+      'customers.get_person',
+      { personId: input.recordId, includeRelated: true },
+      toolContext,
+    )
+    if (!result) return null
+    return renderContextBlock(`Person ${input.recordId}`, result)
+  }
+
+  if (COMPANY_ENTITY_TYPES.has(entityType)) {
+    const result = await hydrateWithTool(
+      'customers.get_company',
+      { companyId: input.recordId, includeRelated: true },
+      toolContext,
+    )
+    if (!result) return null
+    return renderContextBlock(`Company ${input.recordId}`, result)
+  }
+
+  if (DEAL_ENTITY_TYPES.has(entityType)) {
+    const result = await hydrateWithTool(
+      'customers.get_deal',
+      { dealId: input.recordId, includeRelated: true },
+      toolContext,
+    )
+    if (!result) return null
+    return renderContextBlock(`Deal ${input.recordId}`, result)
+  }
+
+  return null
+}