@softize/opus 25.1.0 → 25.3.0

package/src/core/runtime.ts

@@ -13,6 +13,7 @@
 
 import { isReaction } from './reactions.ts'
 import { isBackgroundAction } from './actions.ts'
+import { assertValidListGrouping } from './list-grouping.ts'
 import { isSchedule } from './schedules.ts'
 import {
   collectDomainWarnings,
@@ -25,6 +26,17 @@ import { createPurgeHandler, entityTableName, type PurgeHandler } from './retent
 import type { DataProductConfig } from './data-product.ts'
 import { AuditEmitter } from './audit.ts'
 import { countReturnedRecords, hasInvalidEffect, resolveActionEffect } from './action-nature.ts'
+import {
+  assertAssistantDeclaration,
+  projectAssistantContext,
+  publicAssistant,
+  resolveAssistantTitle,
+  type AssistantOmission,
+  type ReadResourceOptions,
+  type ResourceContext,
+  type RegisteredAssistant,
+  type ResourceReadResult,
+} from './assistant.ts'
 import { error, isActionError, normalizeError } from './errors.ts'
 import { normalizeTraceContext } from './trace.ts'
 import { isSystemActor, markSystemActor } from './system-actor.ts'
@@ -78,6 +90,7 @@ import type {
   BoundAi,
   AiTool,
   AIConfig,
+  ActionAssistant,
   User,
   TraceContext,
 } from './types.ts'
@@ -321,6 +334,8 @@ export class Runtime {
   private aiToolsCache: AiTool[] | null = null
 
   private readonly actions = new Map<string, ActionDef>()
+  /** A action dona de cada tipo de recurso com assistente (ADR 0053). */
+  private readonly assistantOwners = new Map<string, ActionDef & { assistant: ActionAssistant }>()
   private readonly reactions = new Map<string, ReactionDef<any>>()
   private readonly schedules = new Map<string, ScheduleDef>()
   private readonly dataProducts = new Map<string, DataProductConfig>()
@@ -532,11 +547,34 @@ export class Runtime {
             'Use simple ou form para escrever (ADR 0041).',
         })
       }
+      this.claimAssistant(action)
+      if (action.kind === 'list') assertValidListGrouping(action)
       this.actions.set(action.name, action)
       if (this.config.dev) this.warnIgnoredExecutionFields(action)
     }
   }
 
+  /**
+   * Valida a declaração do assistente e reserva o tipo de recurso para a action (ADR 0053). Duas
+   * actions donas do mesmo recurso são recusadas com `runtime.assistant_duplicate_resource`.
+   */
+  private claimAssistant(action: ActionDef): void {
+    assertAssistantDeclaration(action)
+    const assistant = (action as { assistant?: ActionAssistant }).assistant
+    if (assistant === undefined) return
+    const owner = this.assistantOwners.get(assistant.resource)
+    if (owner !== undefined) {
+      throw error({
+        code: 'runtime.assistant_duplicate_resource',
+        category: 'internal',
+        message:
+          `O recurso "${assistant.resource}" já tem a action dona "${owner.name}"; ` +
+          `"${action.name}" não pode declarar o mesmo resource (ADR 0053).`,
+      })
+    }
+    this.assistantOwners.set(assistant.resource, action as ActionDef & { assistant: ActionAssistant })
+  }
+
   /**
    * `emits` e `background` pertencem ao binding de qualquer kind pelo tipo, mas o runtime e o
    * manifest só os aplicam em `simple` e `form`. Restringir o tipo quebraria bindings
@@ -726,6 +764,103 @@ export class Runtime {
     return this.executeAction(action, input, ctxBase, 'request')
   }
 
+  /**
+   * Lê um recurso pela action dona do tipo (ADR 0053). Executa a action com `{ id }` pelo mesmo
+   * `execute` de qualquer chamada: autorização, loaders, auditoria, marca de dado pessoal e span são
+   * os da action. Em caso de sucesso, devolve o descritor e, com `{ context: true }`, a projeção
+   * limitada que o host pode entregar ao modelo. Em caso de falha, devolve o erro da action. Um tipo
+   * sem action dona devolve `runtime.assistant_resource_unknown`, sem executar nada.
+   */
+  async readResource(
+    resource: string,
+    id: string,
+    ctxBase: ContextBase,
+    options: ReadResourceOptions = {},
+  ): Promise<ResourceReadResult> {
+    const owner = this.assistantOwners.get(resource)
+    if (owner === undefined) {
+      return {
+        ok: false,
+        error: error({
+          code: 'runtime.assistant_resource_unknown',
+          category: 'validation',
+          // O tipo veio de fora: a mensagem é fixa, e o valor recebido fica em `meta`.
+          message: 'O tipo de recurso informado não tem action dona.',
+          meta: { resource },
+        }),
+      }
+    }
+    const result = await this.execute(owner.name, { id }, ctxBase)
+    if (!result.ok) return { ok: false, error: result.error, meta: result.meta }
+
+    const { assistant } = owner
+    let title: string | null
+    let omitted: AssistantOmission[]
+    let context: ResourceContext | undefined
+    try {
+      if (options.context === true) {
+        // A projeção já resolve o título; sem contexto pedido, basta o título, sem pagar o corte.
+        const projection = projectAssistantContext(assistant, result.data)
+        title = projection.title
+        omitted = projection.omitted
+        context = {
+          data: projection.data,
+          truncated: projection.truncated,
+          omitted: projection.omitted,
+          personalData: owner.personalData === true,
+        }
+      } else {
+        ;({ title, omitted } = resolveAssistantTitle(assistant, result.data))
+      }
+    } catch (thrown) {
+      // A action executou e foi auditada; o que falhou foi transformar a saída em dado ao modelo
+      // (por exemplo, `BigInt` ou referência circular, que o JSON não representa).
+      this.log.error('A saída da action dona não pôde ser projetada para o assistente.', {
+        code: 'runtime.assistant_projection_failed',
+        action: owner.name,
+        resource,
+        error: thrown instanceof Error ? thrown.message : String(thrown),
+      })
+      return {
+        ok: false,
+        error: error({
+          code: 'runtime.assistant_projection_failed',
+          category: 'internal',
+          message: 'Não foi possível preparar os dados deste recurso para o assistente.',
+          cause: thrown,
+        }),
+        meta: result.meta,
+      }
+    }
+    const missing = omitted.filter((entry) => entry.reason === 'missing').map((entry) => entry.path)
+    if (missing.length > 0) {
+      this.log.warn(
+        `A saída de "${owner.name}" não trouxe ${missing.map((path) => `\`${path}\``).join(', ')}, ` +
+          'declarado no assistente, como texto ou valor esperado; o recurso foi lido sem esses campos.',
+        { code: 'runtime.assistant_path_missing', action: owner.name, resource, paths: missing },
+      )
+    }
+    return {
+      ok: true,
+      resource: { kind: resource, id, title, label: assistant.label, skill: assistant.skill },
+      ...(context !== undefined ? { context } : {}),
+      meta: result.meta,
+    }
+  }
+
+  /**
+   * As declarações de assistente registradas, com a action dona de cada uma (ADR 0053). Serve ao
+   * consumidor para montar rotas e telas a partir da declaração e para conferir as chaves de
+   * procedimento contra o registro que ele mantém.
+   */
+  assistants(): RegisteredAssistant[] {
+    return [...this.assistantOwners.values()].map((owner) => ({
+      action: owner.name,
+      ...publicAssistant(owner.assistant),
+      personalData: owner.personalData === true,
+    }))
+  }
+
   /**
    * Executa no worker um envelope criado por `execute()`. O consumer fornece
    * auth/can reidratados; identidade, provenance e trace vêm do envelope.
@@ -1026,6 +1161,9 @@ export class Runtime {
         metadata: {
           ...(effect !== undefined ? { effect } : {}),
           ...(action.personalData !== undefined ? { personalData: action.personalData } : {}),
+          ...(action.kind === 'view' && action.assistant !== undefined
+            ? { assistant: publicAssistant(action.assistant) }
+            : {}),
           dataProducts,
           dataProductLabels: Object.fromEntries(
             dataProducts.map((id) => [id, this.dataProducts.get(id)?.label ?? id]),

package/src/core/types.ts

@@ -21,6 +21,7 @@
  *  13. RuntimeConfig (§14)
  */
 
+import type { AssistantDeclaration } from './assistant.ts'
 import type { SoftDeleteEntity } from './retention.ts'
 
 // =============================================================================
@@ -548,6 +549,30 @@ export interface AIConfig {
   requiresConfirmation?: boolean
 }
 
+/**
+ * O assistente do recurso que uma action `view` lê (ADR 0053). A action que o declara é a action
+ * dona do tipo de recurso: é por ela que o recurso é lido e que o acesso a ele é conferido. A
+ * declaração é serializável e não carrega função, consulta nem regra de acesso.
+ */
+export interface ActionAssistant {
+  /** O tipo de recurso de que a action é dona, em camelCase e único no runtime (`customer`). */
+  resource: string
+  /** A chave do procedimento que a IA segue ao tratar do recurso, em minúsculas com hífen. */
+  skill: string
+  /** O nome do assistente para pessoas (`Assistente do cliente`). */
+  label: string
+  /** O caminho, na saída, do campo que nomeia o recurso para pessoas (`name`). */
+  title: string
+  /**
+   * Os caminhos, na saída, dos campos que o host pode entregar ao modelo como dado do recurso. O
+   * ponto desce em objetos (`leads.totalCount`); um caminho que passa por uma lista se aplica a cada
+   * item.
+   */
+  context: readonly string[]
+  /** Teto, em caracteres, do JSON de `context`. Padrão de 4.000, mínimo de 1.000, máximo de 16.000. */
+  maxContextChars?: number
+}
+
 export interface Example {
   name: string
   description?: string
@@ -899,6 +924,9 @@ export interface SearchFilters {
   paginate?: 'cursor' | 'offset' | false
   text?: { fields: string[]; placeholder?: I18nRef }
   periods?: PeriodSpec[]
+  /** Dimensões fechadas que a ActionList pode usar para agrupar a tabela. Cada nome
+   *  referencia um filtro select com opções static ou dictionary. */
+  grouping?: { fields: string[] }
   /**
    * Cláusula DSL aplicada **sempre** pelo repository do consumer (ex:
    * `'NOT archived'`). Runtime NÃO executa SQL — quem consome a search
@@ -931,6 +959,8 @@ export interface ListAction<In, Out, ParsedIn = In>
   paginate?: 'cursor' | 'offset' | false
   text?: { fields: string[]; placeholder?: I18nRef }
   periods?: PeriodSpec[]
+  /** Dimensões fechadas que a ActionList pode usar para agrupar a tabela. */
+  grouping?: { fields: string[] }
   /**
    * Ver `SearchFilters.where`. Baseline DSL aplicado pelo repository
    * via `compileWhere` (do `@softize/opus/dsl`). Runtime não executa SQL.
@@ -943,6 +973,12 @@ export interface ViewAction<In, Out, ParsedIn = In> extends ActionBase<In, Out,
   /** Entidades relacionadas projetáveis. View simples não projeta nada — omita. */
   projection?: string[]
   expand?: Record<string, ExpandSpec>
+  /**
+   * Torna esta action a dona de um tipo de recurso e declara o assistente dele (ADR 0053). Exige
+   * `ai` habilitado, `personalData` declarado e uma entrada em que `id`, do tipo texto, é o único
+   * campo obrigatório. O runtime lê o recurso por `runtime.readResource`.
+   */
+  assistant?: ActionAssistant
 }
 
 /**
@@ -1341,6 +1377,9 @@ export interface AiTool {
     effect?: ActionEffect
     /** A action declara devolver dado pessoal; ausente quando não declarou. */
     personalData?: boolean
+    /** O assistente do recurso de que a action é dona (ADR 0053), com o teto resolvido; ausente
+     *  quando não declara. */
+    assistant?: AssistantDeclaration
   }
 }
 

package/src/mcp/index.ts

@@ -58,6 +58,9 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
         ...(t.metadata?.personalData !== undefined
           ? { 'com.softize.opus/personal-data': t.metadata.personalData }
           : {}),
+        // O assistente do recurso de que a action é dona (ADR 0053): o host conhece o assistente
+        // pelo catálogo que já consulta.
+        ...(t.metadata?.assistant !== undefined ? { 'com.softize.opus/assistant': t.metadata.assistant } : {}),
       },
     })),
   }))

package/src/ui/components/patterns/grouped-list.ts

@@ -0,0 +1,88 @@
+import { useQueries } from '@tanstack/react-query'
+import { useRef } from 'react'
+import type { ActionDef, ActionError, Paginated } from '../../../core/index.ts'
+import { useClient } from '../../drivers/context.tsx'
+
+export interface ListActionGroup<TItem> {
+  value: string
+  items: TItem[]
+  total: number | undefined
+  error: ActionError | undefined
+  isLoading: boolean
+  isFetching: boolean
+  isError: boolean
+  refetch: () => Promise<void>
+}
+
+/** Implementação interna do ActionList para executar um recorte paginado por grupo. */
+export function useGroupedListAction<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+  action: { name: string; kind: 'list' },
+  input: TInput,
+  field: string | null,
+  values: string[],
+  multiple: boolean,
+  pages: Record<string, number>,
+  pageSize: number,
+): ListActionGroup<TItem>[] {
+  const client = useClient('ActionList grouping')
+  const previous = useRef<{
+    field: string | null
+    groups: Map<string, { items: TItem[]; total: number }>
+  }>({ field, groups: new Map() })
+  if (previous.current.field !== field) {
+    previous.current = { field, groups: new Map() }
+  }
+  const groupField = field ?? '__disabled_group__'
+  const requests =
+    field === null
+      ? []
+      : values.flatMap((value) =>
+          Array.from({ length: pages[value] ?? 1 }, (_, index) => ({
+            value,
+            page: index + 1,
+          })),
+        )
+  const queries = useQueries({
+    queries: requests.map(({ value, page }) => {
+      const groupInput = {
+        ...input,
+        [groupField]: multiple ? [value] : value,
+        page,
+        limit: pageSize,
+      }
+      return {
+        queryKey: [action.name, groupInput],
+        queryFn: async (): Promise<Paginated<TItem>> => {
+          const result = await client.run<Paginated<TItem>>(action as unknown as ActionDef, groupInput)
+          if (!result.ok) throw result.error
+          return result.data
+        },
+      }
+    }),
+  })
+
+  return values.map((value) => {
+    const groupQueries = queries.filter((_, index) => requests[index]?.value === value)
+    const items = groupQueries.flatMap((query) => query.data?.items ?? [])
+    const total = groupQueries.find((query) => query.data?.total !== undefined)?.data?.total
+    const isError = groupQueries.some((query) => query.isError)
+    const hasCompleteData = groupQueries.length > 0 && groupQueries.every((query) => query.data !== undefined)
+    if (hasCompleteData && !isError && total !== undefined) {
+      previous.current.groups.set(value, { items, total })
+    }
+    const fallback = previous.current.groups.get(value)
+    const hasCurrentData = groupQueries.some((query) => query.data !== undefined)
+    return {
+      value,
+      items: hasCurrentData ? items : (fallback?.items ?? []),
+      total: hasCurrentData ? total : fallback?.total,
+      error: (groupQueries.find((query) => query.error !== null)?.error as unknown as ActionError | null) ?? undefined,
+      isLoading: (groupQueries[0]?.isPending ?? true) && fallback === undefined,
+      isFetching: groupQueries.some((query) => query.isFetching),
+      isError,
+      refetch: async () => {
+        await Promise.all(groupQueries.map((query) => query.refetch()))
+      },
+    }
+  })
+}