@fayz-ai/saas 0.8.1 → 0.8.2

package/src/shell/lib/core-ai-tools.ts

@@ -1,4 +1,7 @@
 import type { PluginAITool, PluginRegistryDef } from '../types/plugins'
+import type { EntityDef } from '@fayz-ai/core'
+import { getAllEntities, type RegisteredEntity } from '@fayz-ai/core'
+import { CORE_QUERY_ENTITIES } from '../../app/core-entities'
 
 /**
  * Core SaaS-level AI tools — always available, no plugin required.
@@ -19,7 +22,7 @@ export const coreAITools: PluginAITool[] = [
   {
     id: 'core.team-members',
     name: 'getTeamMembers',
-    description: 'Lists team members for the current tenant with their roles and status.',
+    description: 'Lists the WORKSPACE USERS (people with a login) and their roles. This is NOT the professionals/staff registry — for professionals, stylists or other staff the business manages as records, use the staff/people search tools instead.',
     icon: 'Users',
     mode: 'read',
     parameters: {
@@ -51,6 +54,37 @@ export const coreAITools: PluginAITool[] = [
   },
 ]
 
+/**
+ * Builds the LLM-facing function name for a registry tool.
+ *
+ * Derived from the registry id, never from the entity's display label: the
+ * label is translated, so a pt-BR app would mint `listCategoriasdeServiço` —
+ * which both violates the provider's `^[a-zA-Z0-9_-]+$` function-name rule and
+ * renames the tool whenever the user switches locale. The id is a stable ASCII
+ * slug. The human plural still drives the description, which is what the model
+ * actually reads to decide when to call it.
+ */
+function pascalCase(value: string): string {
+  // Transliterate diacritics BEFORE splitting: splitting on [^a-zA-Z0-9]
+  // treated an accent as a word boundary and dropped it mid-word — "Serviço"
+  // became "ServiO" and "Preço de Serviço" became "PreODeServiO", which both
+  // renames tools per locale and can trip the broker's ^[a-zA-Z0-9_-]+$ rule.
+  return value
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('')
+}
+
+export function registryToolName(pluginId: string, registryId: string): string {
+  // Namespaced by plugin because registry ids only need to be unique within
+  // their own plugin — `crm` and `inventory` can both ship a `tags` registry,
+  // and two tools sharing a function name is ambiguous to the model.
+  return `list${pascalCase(pluginId)}${pascalCase(registryId)}`
+}
+
 /**
  * Auto-generates read tools from plugin registry definitions.
  * Each registry gets a basic "list" tool so plugins get AI capabilities for free.
@@ -62,7 +96,7 @@ export function generateRegistryTools(pluginId: string, registries: PluginRegist
       const plural = registry.entity.namePlural ?? `${registry.entity.name}s`
       return {
         id: `${pluginId}.list-${registry.id}`,
-        name: `list${plural.replace(/\s+/g, '')}`,
+        name: registryToolName(pluginId, registry.id),
         description: `Lists all ${plural.toLowerCase()} for the current business.`,
         icon: registry.icon ?? registry.entity.icon,
         mode: 'read' as const,
@@ -88,3 +122,201 @@ export function formatToolSignature(tool: PluginAITool): string {
     : ''
   return `${tool.name}(${params})`
 }
+
+export function entityToolName(entityKey: string): string {
+  return `search${pascalCase(entityKey)}`
+}
+
+/**
+ * Auto-generates a search tool for every entity the app exposes as a CRUD page.
+ *
+ * Registries cover a plugin's auxiliary tables; these are the entities the
+ * business actually talks about — clients, appointments, services. Deriving
+ * them from the entity registry is what makes the agent useful in a new vertical
+ * without anyone hand-writing tools: whatever the app declares, the agent can
+ * read.
+ */
+/**
+ * The TWO generic data primitives that replace the per-entity/per-registry
+ * generated tools (43 searches → 2 tools): the model picks the TARGET as a
+ * parameter (closed enum), and the executor checks the target entity's OWN
+ * read permission at call time — one tool, per-user access preserved.
+ */
+/**
+ * Sentences describing entities that ATTACH to another record instead of
+ * standing alone. Appended to createRecord's description so the relationship is
+ * stated once, up front, rather than discovered through a failed write.
+ * Only entities actually present in this app's catalog are mentioned.
+ */
+function attachedRecordGuidance(writableKeys: string[]): string {
+  const hints = CORE_QUERY_ENTITIES
+    .filter((q) => q.agentHint && writableKeys.includes(q.key))
+    .map((q) => q.agentHint as string)
+  return hints.length ? ` Records that attach to another record: ${hints.join(' ')}` : ''
+}
+
+export function buildDataPrimitiveTools(input: {
+  entities: RegisteredEntity[]
+  registries: Map<string, PluginRegistryDef[]>
+  queryEntities?: Array<{ key: string; entity: EntityDef; writable?: boolean }>
+}): PluginAITool[] {
+  const options: Array<{ key: string; label: string }> = []
+  for (const e of input.entities) {
+    if (e.entityDef && !e.entityDef.agentHidden) options.push({ key: e.entityKey, label: e.labelPlural })
+  }
+  for (const [pluginId, defs] of input.registries) {
+    for (const registry of defs) {
+      if (registry.readOnly) continue
+      options.push({
+        key: `${pluginId}:${registry.id}`,
+        label: registry.entity.namePlural ?? registry.entity.name,
+      })
+    }
+  }
+  // Read-models are readable; base-table ones may opt into writes.
+  const writableKeys = options.map((o) => o.key)
+  // CORE_QUERY_ENTITIES is merged HERE, not at each call site: the primitives
+  // are built from three different places (deriveAgentContract, useAITools and
+  // the conversational e2e harness), and a spine entity added to only some of
+  // them is a catalog that disagrees with itself.
+  for (const q of [...(input.queryEntities ?? []), ...CORE_QUERY_ENTITIES]) {
+    options.push({ key: q.key, label: q.entity.namePlural ?? q.entity.name })
+    if (q.writable) writableKeys.push(q.key)
+  }
+  if (!options.length) return []
+  const keys = options.map((o) => o.key)
+  const catalogLine = options.map((o) => `${o.key} (${o.label.toLowerCase()})`).join(', ')
+
+  return [
+    {
+      id: 'data.find-anything',
+      name: 'findAnything',
+      description:
+        'Global search (like the app command center): looks a name/text up across ALL record types the user may see at once and returns grouped matches. Use this FIRST whenever you do not know what kind of record a name refers to ("quem é X?", "o que é Y?") — then drill down with searchRecords.' +
+        ' It matches TEXT INSIDE each record, so records attached to a person are never returned by that person\'s name — reaching them takes a second searchRecords call filtered by owner_id.' +
+        attachedRecordGuidance(keys),
+      icon: 'Command',
+      mode: 'read',
+      parameters: {
+        type: 'object',
+        properties: {
+          search: { type: 'string', description: 'Name or text to look up everywhere.' },
+        },
+        required: ['search'],
+      },
+      category: 'Data',
+      suggestions: [{ label: 'Quem é …?' }],
+    },
+    ...(writableKeys.length
+      ? [
+          {
+            id: 'data.create-record',
+            name: 'createRecord',
+            description:
+              'Creates ONE new record of an entity (client, service, supplier, …). ALWAYS search first to avoid duplicates. Field keys and required fields come from the entity — on a field error the response lists the valid fields; fix and retry. The user will confirm before anything is written.' +
+              attachedRecordGuidance(writableKeys),
+            icon: 'Plus',
+            mode: 'persist' as const,
+            // The handler orchestrates its own guard chain (permission → plan
+            // cap → confirmation → create) because the target is dynamic.
+            requiresConfirmation: false,
+            parameters: {
+              type: 'object' as const,
+              properties: {
+                entity: { type: 'string' as const, description: 'Which entity to create', enum: writableKeys },
+                values: { type: 'object' as const, description: 'Field values for the new record, e.g. {"name":"…","phone":"…"}' },
+              },
+              required: ['entity', 'values'],
+            },
+            category: 'Data',
+          } satisfies PluginAITool,
+        ]
+      : []),
+    ...(writableKeys.length
+      ? [
+          {
+            id: 'data.update-record',
+            name: 'updateRecord',
+            description:
+              'Updates fields on an EXISTING record (add an email, fix a phone, change a name…). Use the record id already known from this conversation or from a search. Only send the fields being changed. The user confirms before anything is written.',
+            icon: 'Pencil',
+            mode: 'persist' as const,
+            requiresConfirmation: false,
+            parameters: {
+              type: 'object' as const,
+              properties: {
+                entity: { type: 'string' as const, description: 'Which entity the record belongs to', enum: writableKeys },
+                id: { type: 'string' as const, description: 'Id of the record to update' },
+                values: { type: 'object' as const, description: 'Only the fields to change, e.g. {"email":"…"}' },
+              },
+              required: ['entity', 'id', 'values'],
+            },
+            category: 'Data',
+          } satisfies PluginAITool,
+        ]
+      : []),
+    {
+      id: 'data.search-records',
+      name: 'searchRecords',
+      description: `Searches or lists records of ONE entity and returns matching rows with their fields. Use \`search\` for names/text and \`filters\` for exact field values (e.g. {"status":"open"}) — never put a status word in search. Entities: ${catalogLine}.${attachedRecordGuidance(keys)}`,
+      icon: 'Search',
+      mode: 'read',
+      parameters: {
+        type: 'object',
+        properties: {
+          entity: { type: 'string', description: 'Which entity to search', enum: keys },
+          search: { type: 'string', description: 'Name or text to match. Omit to list recent records.' },
+          filters: { type: 'object', description: 'Optional exact-value filters {field: value}, e.g. {"status":"open"}.' },
+          orderBy: { type: 'string', description: 'Field to sort by (e.g. startsAt for "next/upcoming" questions).' },
+          direction: { type: 'string', description: 'Sort direction', enum: ['asc', 'desc'] },
+        },
+        required: ['entity'],
+      },
+      category: 'Data',
+    },
+    {
+      id: 'data.query-data',
+      name: 'queryData',
+      description: `Aggregates over ONE entity: count, sum or avg of a field, with optional date range, equality filters and a group-by. Use for analytical questions (revenue this week, new clients this month, busiest professional). Entities: ${catalogLine}.`,
+      icon: 'Sigma',
+      mode: 'read',
+      parameters: {
+        type: 'object',
+        properties: {
+          entity: { type: 'string', description: 'Which entity to aggregate', enum: keys },
+          metric: { type: 'string', description: 'Aggregation', enum: ['count', 'sum', 'avg'] },
+          field: { type: 'string', description: 'Field to sum/avg (record field name). Ignored for count.' },
+          dateField: { type: 'string', description: "Date field to range-filter (default 'created_at')." },
+          from: { type: 'string', description: 'ISO date/datetime lower bound (inclusive).' },
+          to: { type: 'string', description: 'ISO date/datetime upper bound (inclusive).' },
+          groupBy: { type: 'string', description: 'Optional field to group results by.' },
+          filters: { type: 'object', description: 'Optional equality filters {field: value}.' },
+        },
+        required: ['entity', 'metric'],
+      },
+      category: 'Data',
+    },
+  ]
+}
+
+export function generateEntityTools(entities: RegisteredEntity[] = getAllEntities()): PluginAITool[] {
+  return entities
+    .filter((e) => !!e.entityDef)
+    .map((entity) => ({
+      id: `entity.${entity.entityKey}`,
+      name: entityToolName(entity.entityKey),
+      description: `Searches ${entity.labelPlural.toLowerCase()} and returns matching records with their fields. Use this to answer questions about a specific ${entity.label.toLowerCase()} or to count them.`,
+      icon: entity.icon,
+      mode: 'read' as const,
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          search: {
+            type: 'string' as const,
+            description: `Name or text to match. Omit to list recent ${entity.labelPlural.toLowerCase()}.`,
+          },
+        },
+      },
+      category: 'Data',
+    }))
+}

package/src/shell/lib/create-client-orders-provider.ts

@@ -14,6 +14,23 @@ const STAGE_FILTER_MAP: Record<string, string[]> = {
   paid: ['paid'],
 }
 
+/**
+ * A shop order's lifecycle is not in `status` (open/archived/cancelled) but in
+ * the payment state the shop plugin mirrors into metadata. Without this every
+ * storefront purchase showed up as "rascunho" on the customer's record — the
+ * same tab, the same table, but reading the wrong column for that kind.
+ */
+function mapShopOrderToStage(row: { status?: string | null; metadata?: Record<string, unknown> | null }): ClientDocumentStage {
+  if (row.status === 'cancelled') return 'cancelled'
+  switch (String(row.metadata?.financial_status ?? '')) {
+    case 'paid': return 'paid'
+    case 'partially_refunded': return 'partial'
+    case 'refunded':
+    case 'voided': return 'cancelled'
+    default: return 'invoiced'   // placed, awaiting payment
+  }
+}
+
 function mapOrderStatusToStage(status: string | null | undefined): ClientDocumentStage {
   switch (status) {
     case 'scheduled':
@@ -83,12 +100,17 @@ export function createClientOrdersProvider(): ClientOrdersProvider {
           return {
             id: row.id,
             kind: row.kind as string,
-            stage: mapOrderStatusToStage(row.status as string | null | undefined),
+            stage: row.kind === 'shop'
+              ? mapShopOrderToStage(row)
+              : mapOrderStatusToStage(row.status as string | null | undefined),
             referenceNumber: row.reference_number ?? undefined,
             date: startsAt?.slice(0, 10) ?? (row.created_at as string)?.slice(0, 10) ?? '',
             startsAt,
             total: Number(row.total) || 0,
-            paidAmount: Number(meta.paidAmount) || 0,
+            // A paid shop order has no separate paidAmount; the total is what
+            // was settled.
+            paidAmount: Number(meta.paidAmount)
+              || (row.kind === 'shop' && meta.financial_status === 'paid' ? Number(row.total) || 0 : 0),
             description: (meta.itemsSummary as string) ?? (meta.serviceNames as string) ?? row.notes ?? undefined,
             createdAt: row.created_at as string,
           }

package/src/shell/lib/fayz-agent.ts

@@ -0,0 +1,56 @@
+import { createFayzAgentClient, type FayzAgentClient } from '@fayz-ai/sdk/agent'
+
+/**
+ * Resolves the connection to the project's Fayz agent.
+ *
+ * The container writes `VITE_FAYZ_PROJECT_ID`, `VITE_FAYZ_API_BASE_URL` and
+ * `VITE_FAYZ_AGENT_KEY` into every preview's `.env`, so enabling an agent in
+ * Fayz is enough to light up the app's assistant — no app-side config edit and
+ * no key to copy. `chat.agent` overrides are for self-hosted deployments where
+ * the app is built outside a Fayz container.
+ */
+
+export interface FayzAgentConnectionConfig {
+  projectId?: string
+  apiBaseUrl?: string
+  publishableKey?: string
+}
+
+export interface ResolvedFayzAgentConnection {
+  projectId: string
+  apiBaseUrl: string
+  publishableKey: string
+}
+
+function env(key: string): string | undefined {
+  const value = (import.meta.env as Record<string, string | undefined>)[key]
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+export function resolveFayzAgentConnection(
+  override?: FayzAgentConnectionConfig | false,
+): ResolvedFayzAgentConnection | null {
+  if (override === false) return null
+
+  const projectId = override?.projectId ?? env('VITE_FAYZ_PROJECT_ID')
+  const apiBaseUrl = override?.apiBaseUrl ?? env('VITE_FAYZ_API_BASE_URL')
+  const publishableKey = override?.publishableKey ?? env('VITE_FAYZ_AGENT_KEY')
+
+  if (!projectId || !apiBaseUrl || !publishableKey) return null
+  return { projectId, apiBaseUrl, publishableKey }
+}
+
+let cached: { key: string; client: FayzAgentClient } | null = null
+
+export function getFayzAgentClient(connection: ResolvedFayzAgentConnection): FayzAgentClient {
+  const key = `${connection.apiBaseUrl}|${connection.projectId}|${connection.publishableKey}`
+  if (cached?.key === key) return cached.client
+
+  const client = createFayzAgentClient({
+    baseUrl: connection.apiBaseUrl,
+    projectId: connection.projectId,
+    publishableKey: connection.publishableKey,
+  })
+  cached = { key, client }
+  return client
+}

package/src/shell/lib/i18n.ts

@@ -595,6 +595,43 @@ export const defaultTranslations: Record<string, string> = {
   'billing.paywall.requiresPlan': 'This feature requires the {{plan}} plan or higher.',
   'billing.paywall.upgradeRequired': 'Upgrade Required',
   'billing.paywall.viewPlans': 'View Plans',
+
+  // ---------------------------------------------------------------------------
+  // Entitlements — upgrade prompts, plan limits, soft-limit banner
+  // ---------------------------------------------------------------------------
+  'upgrade.title': 'Premium feature',
+  'upgrade.description': 'This feature is available on a higher plan. Upgrade to unlock it.',
+  'upgrade.descriptionFeature': 'The {feature} feature is available on a higher plan. Upgrade to unlock it.',
+  'upgrade.includes': 'Includes {feature}',
+  'upgrade.cta': 'View plans',
+  'upgrade.badgeTooltip': 'Available on a higher plan',
+  'limit.reached': "You've reached the {label} limit of the {plan} plan.",
+  'banner.overLimit': "You've exceeded the {label} limit of your plan — upgrade to keep growing.",
+  'billing.featureMatrix': 'Feature comparison',
+  'billing.unlimited': 'Unlimited',
+  'billing.upTo': 'Up to {count}',
+  // Limit labels — apps/plugins may override per key; these cover the base caps.
+  'limit.label.clients': 'clients',
+  'limit.label.users': 'team members',
+  'limit.label.locations': 'locations',
+  'limit.label.bookings_month': 'monthly bookings',
+  'limit.label.products': 'products',
+  'limit.label.students': 'students',
+  'limit.label.courses': 'courses',
+  'limit.label.contacts': 'contacts',
+  'limit.label.deals': 'deals',
+  'limit.label.menu_items': 'menu items',
+  'limit.label.orders_month': 'monthly orders',
+  'limit.label.connected_banks': 'connected banks',
+  'limit.label.movements_month': 'monthly movements',
+  'limit.label.leads': 'leads',
+  'limit.label.quotes': 'quotes',
+  'limit.label.conversations_month': 'monthly conversations',
+  'limit.label.recipes': 'recipes',
+  'limit.label.form_templates': 'form templates',
+  'limit.label.documents_month': 'monthly documents',
+  'limit.label.content_posts_month': 'monthly content posts',
+  'limit.label.blog_posts': 'blog posts',
   'chat.defaultTitle': 'Assistant',
   'chat.tryAsking': 'Try asking',
   'chat.fab.tryIt': 'Try it',
@@ -2345,6 +2382,40 @@ export const builtInLocales: Record<string, Record<string, string>> = {
     'billing.paywall.upgradeRequired': 'Upgrade Necessário',
     'billing.paywall.viewPlans': 'Ver Planos',
 
+    // Entitlements — upgrade prompts, limites de plano, banner de soft-limit
+    'upgrade.title': 'Recurso premium',
+    'upgrade.description': 'Este recurso está disponível em um plano superior. Faça upgrade para liberá-lo.',
+    'upgrade.descriptionFeature': 'O recurso {feature} está disponível em um plano superior. Faça upgrade para liberá-lo.',
+    'upgrade.includes': 'Inclui {feature}',
+    'upgrade.cta': 'Ver planos',
+    'upgrade.badgeTooltip': 'Disponível em um plano superior',
+    'limit.reached': 'Você atingiu o limite de {label} do plano {plan}.',
+    'banner.overLimit': 'Você excedeu o limite de {label} do seu plano — faça upgrade para continuar crescendo.',
+    'billing.featureMatrix': 'Comparação de recursos',
+    'billing.unlimited': 'Ilimitado',
+    'billing.upTo': 'Até {count}',
+    'limit.label.clients': 'clientes',
+    'limit.label.users': 'membros da equipe',
+    'limit.label.locations': 'locais',
+    'limit.label.bookings_month': 'agendamentos mensais',
+    'limit.label.leads': 'leads',
+    'limit.label.quotes': 'orçamentos',
+    'limit.label.conversations_month': 'conversas mensais',
+    'limit.label.recipes': 'receitas',
+    'limit.label.form_templates': 'modelos de formulário',
+    'limit.label.documents_month': 'documentos mensais',
+    'limit.label.content_posts_month': 'posts de conteúdo mensais',
+    'limit.label.blog_posts': 'posts de blog',
+    'limit.label.products': 'produtos',
+    'limit.label.students': 'alunos',
+    'limit.label.courses': 'cursos',
+    'limit.label.contacts': 'contatos',
+    'limit.label.deals': 'negócios',
+    'limit.label.menu_items': 'itens do cardápio',
+    'limit.label.orders_month': 'pedidos mensais',
+    'limit.label.connected_banks': 'bancos conectados',
+    'limit.label.movements_month': 'movimentações mensais',
+
     // auth (additional duplicates/variants)
     'auth.login.enterCredentials': 'Insira suas credenciais para acessar sua conta',
     'auth.login.failedDefault': 'Falha ao entrar. Tente novamente.',

package/src/shell/stores/chat.store.ts

@@ -1,10 +1,50 @@
 import { create } from 'zustand'
 
+/** A record the reply concerns — rendered as a "goto" button under the
+ *  bubble. Semantic ref only (id + archetype/kind); the SURFACE resolves the
+ *  URL against its own route map (agents.md: a missing link is correct, an
+ *  invented one is a dead end). */
+export interface ChatRecordLink {
+  id: string
+  label: string
+  archetype?: string
+  kind?: string
+}
+
+export interface ChatToolCall {
+  name: string
+  /** Pretty-printed arguments (may be empty). */
+  args: string
+  /** Result content, truncated for display. */
+  result?: string
+}
+
 export interface ChatMessage {
   id: string
   role: 'user' | 'assistant'
   content: string
   timestamp: string
+  /** Tool calls this assistant reply made, accumulated across rounds —
+   *  rendered as an expandable trace under the bubble. */
+  toolCalls?: ChatToolCall[]
+  /** Records to offer as navigation buttons under the reply. */
+  links?: ChatRecordLink[]
+}
+
+/**
+ * A write the agent wants to perform, parked until the human decides. The turn
+ * loop awaits the promise this action's resolver settles — the chat composer
+ * stays frozen behind the card, mirroring the broker's PENDING_CONFIRMATION
+ * step for server-plane tools.
+ */
+export interface PendingAgentAction {
+  id: string
+  toolName: string
+  title: string
+  params: Record<string, unknown>
+  /** 'client' = executed locally after approval; 'server' = approval is sent
+   *  back to the broker as confirmAction. */
+  plane: 'client' | 'server'
 }
 
 interface ChatState {
@@ -16,13 +56,41 @@ interface ChatState {
   addMessage: (message: ChatMessage) => void
   updateLastAssistant: (content: string) => void
   setStreaming: (streaming: boolean) => void
+  setConversationId: (id: string | null) => void
   reset: () => void
+  /**
+   * Server-side thread id when talking to a Fayz agent. History lives in Fayz,
+   * so subsequent turns only send the new message plus this id.
+   */
+  conversationId: string | null
+  /** The write awaiting human confirmation (renders the ConfirmActionCard). */
+  pendingAction: PendingAgentAction | null
+  /** Park an action + register its decision resolver. */
+  requestConfirmation: (action: PendingAgentAction) => Promise<boolean>
+  /** Card buttons: settle the parked action. */
+  resolvePendingAction: (approved: boolean) => void
+  /** Tool names executing right now — rendered as live activity chips. */
+  activeTools: string[]
+  setActiveTools: (names: string[]) => void
+  /** Record the tool calls an assistant reply made (expandable per-message trace). */
+  appendToolCallsToLastAssistant: (calls: ChatToolCall[]) => void
+  /** Attach goto-record buttons to the reply (deduped by id, capped). */
+  appendLinksToLastAssistant: (links: ChatRecordLink[]) => void
+  /** The signed-in user's threads (history drawer). */
+  conversations: Array<{ id: string; title: string | null; updatedAt: string }>
+  setConversations: (rows: Array<{ id: string; title: string | null; updatedAt: string }>) => void
+  /** Replace the transcript wholesale (resuming a past conversation). */
+  setMessages: (messages: ChatMessage[]) => void
 }
 
+// Module-level so the resolver never round-trips through React state.
+let pendingResolver: ((approved: boolean) => void) | null = null
+
 export const useChatStore = create<ChatState>((set) => ({
   messages: [],
   isOpen: false,
   isStreaming: false,
+  conversationId: null,
 
   setOpen: (open) => set({ isOpen: open }),
   toggleOpen: () => set((s) => ({ isOpen: !s.isOpen })),
@@ -41,5 +109,54 @@ export const useChatStore = create<ChatState>((set) => ({
     }),
 
   setStreaming: (isStreaming) => set({ isStreaming }),
-  reset: () => set({ messages: [], isStreaming: false }),
+  setConversationId: (conversationId) => set({ conversationId }),
+  reset: () => {
+    pendingResolver?.(false)
+    pendingResolver = null
+    set({ messages: [], isStreaming: false, conversationId: null, pendingAction: null, activeTools: [] })
+  },
+
+  pendingAction: null,
+  requestConfirmation: (action) => {
+    // A newer request supersedes an unanswered one (treated as declined).
+    pendingResolver?.(false)
+    return new Promise<boolean>((resolve) => {
+      pendingResolver = resolve
+      set({ pendingAction: action })
+    })
+  },
+  resolvePendingAction: (approved) => {
+    const resolve = pendingResolver
+    pendingResolver = null
+    set({ pendingAction: null })
+    resolve?.(approved)
+  },
+
+  activeTools: [],
+  setActiveTools: (activeTools) => set({ activeTools }),
+  appendToolCallsToLastAssistant: (calls) =>
+    set((s) => {
+      if (!calls.length) return s
+      const msgs = [...s.messages]
+      const lastIdx = msgs.length - 1
+      if (lastIdx >= 0 && msgs[lastIdx].role === 'assistant') {
+        msgs[lastIdx] = { ...msgs[lastIdx], toolCalls: [...(msgs[lastIdx].toolCalls ?? []), ...calls] }
+      }
+      return { messages: msgs }
+    }),
+  appendLinksToLastAssistant: (links) =>
+    set((s) => {
+      if (!links.length) return s
+      const msgs = [...s.messages]
+      const lastIdx = msgs.length - 1
+      if (lastIdx >= 0 && msgs[lastIdx].role === 'assistant') {
+        const seen = new Map((msgs[lastIdx].links ?? []).map((l) => [l.id, l]))
+        for (const l of links) if (!seen.has(l.id)) seen.set(l.id, l)
+        msgs[lastIdx] = { ...msgs[lastIdx], links: Array.from(seen.values()).slice(0, 3) }
+      }
+      return { messages: msgs }
+    }),
+  conversations: [],
+  setConversations: (conversations) => set({ conversations }),
+  setMessages: (messages) => set({ messages }),
 }))

package/src/shell/styles.css

@@ -428,6 +428,36 @@ select.bg-card,
   to { opacity: 1; transform: translateX(0); }
 }
 
+/* Sidebar rail push — see @fayz-ai/ui styles.css for the rationale. */
+.saas-rail-in-forward  { animation: saas-rail-in-forward  var(--saas-rail-duration, 260ms) var(--saas-transition-easing) both; }
+.saas-rail-out-forward { animation: saas-rail-out-forward var(--saas-rail-duration, 260ms) var(--saas-transition-easing) both; }
+.saas-rail-in-back     { animation: saas-rail-in-back     var(--saas-rail-duration, 260ms) var(--saas-transition-easing) both; }
+.saas-rail-out-back    { animation: saas-rail-out-back    var(--saas-rail-duration, 260ms) var(--saas-transition-easing) both; }
+
+@keyframes saas-rail-in-forward {
+  from { opacity: 0; transform: translateX(100%); }
+  to   { opacity: 1; transform: translateX(0); }
+}
+@keyframes saas-rail-out-forward {
+  from { opacity: 1; transform: translateX(0); }
+  to   { opacity: 0; transform: translateX(-35%); }
+}
+@keyframes saas-rail-in-back {
+  from { opacity: 0; transform: translateX(-100%); }
+  to   { opacity: 1; transform: translateX(0); }
+}
+@keyframes saas-rail-out-back {
+  from { opacity: 1; transform: translateX(0); }
+  to   { opacity: 0; transform: translateX(35%); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .saas-rail-in-forward, .saas-rail-out-forward,
+  .saas-rail-in-back, .saas-rail-out-back {
+    animation-duration: 1ms;
+  }
+}
+
 /* ═══ Print — intentionally left minimal here. ═══ */
 /* Runtime-injected print styles live in PrintChrome.tsx  */
 /* to guarantee they bypass any build-tool reordering.    */

package/src/shell/types/billing.ts

@@ -1,3 +1,5 @@
+import type { PlanEntitlements } from '@fayz-ai/core'
+
 export type PlanInterval = 'monthly' | 'yearly'
 export type SubscriptionStatus = 'active' | 'trialing' | 'past_due' | 'canceled' | 'paused'
 
@@ -37,6 +39,12 @@ export interface PlanConfig {
   limits?: Record<string, number>
   popular?: boolean
   verticalId?: string
+  /**
+   * Structured plan entitlements (feature gates + quantity caps) — the
+   * enforcement source of truth the access engine reads. Preserved verbatim by
+   * normalizeBillingPlan onto the runtime `Plan`.
+   */
+  entitlements?: PlanEntitlements
 }
 
 export function normalizePlanConfig(plan: PlanConfig, index?: number): Plan {