@softize/opus 25.1.0 → 25.2.0

package/src/core/runtime.ts

@@ -25,6 +25,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 +89,7 @@ import type {
   BoundAi,
   AiTool,
   AIConfig,
+  ActionAssistant,
   User,
   TraceContext,
 } from './types.ts'
@@ -321,6 +333,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 +546,33 @@ export class Runtime {
             'Use simple ou form para escrever (ADR 0041).',
         })
       }
+      this.claimAssistant(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 +762,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 +1159,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
@@ -943,6 +968,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 +1372,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/docs/content/actions.md

@@ -136,7 +136,7 @@ name, kind
   → public, requires, authorize, loads
   → handler
   → audit, confirm, invalidates, rateLimit, idempotency
-  → ai, automatable, internal
+  → ai, assistant, automatable, internal
 ```
 
 Campos específicos de um kind, como `fields`, `paginate`, `columns`, `filters`, `expand`,
@@ -179,6 +179,102 @@ A autorização é fechada por padrão: sem `public: true`, a action exige usuá
 `authorize`, exige também a permissão declarada. `automatable: true` permite que um
 [schedule](/docs/scheduler) execute a action como o sistema, sem abri-la a chamadores anônimos.
 
+## Declarar o assistente do recurso
+
+Um produto pode oferecer, além do chat geral, uma conversa sobre um recurso específico: um cliente,
+um relatório, um pedido. Essa conversa precisa ler o recurso com a permissão de quem conversa, seguir
+o procedimento próprio daquele tipo de recurso e entregar ao modelo só os dados necessários. Os três
+ficam declarados num lugar só: a action `view` que lê o recurso declara `assistant` e passa a ser a
+**action dona** daquele tipo de recurso.
+
+```ts
+export const customerViewContract = defineContract({
+  name: 'customer.view',
+  kind: 'view',
+  label: 'Ver cliente',
+  input: z.object({ id: z.string().uuid() }),
+  output: customerViewSchema,
+  personalData: true,
+  requires: 'customer.read',
+  authorize: (ctx) => ctx.can('customer.read'),
+  ai: true,
+  assistant: {
+    resource: 'customer',
+    skill: 'review-customer',
+    label: 'Assistente do cliente',
+    title: 'name',
+    context: ['kind', 'stage', 'sources', 'leads.totalCount', 'leads.latest.status'],
+  },
+})
+```
+
+| Campo | O que declara |
+| --- | --- |
+| `resource` | O tipo de recurso de que a action é dona, em camelCase. Cada tipo tem uma única action dona. |
+| `skill` | A chave do procedimento que a IA segue ao tratar do recurso, em minúsculas com hífen. O Opus não conhece o procedimento; o produto o mantém e confere que a chave existe. |
+| `label` | O nome do assistente para pessoas. Entra no inventário do `opus copy`. |
+| `title` | O caminho, na saída, do campo que nomeia o recurso. |
+| `context` | Os caminhos, na saída, dos campos que o host pode entregar ao modelo como dado do recurso. |
+| `maxContextChars` | Opcional. O teto do dado entregue, em caracteres de JSON: 4.000 por padrão, de 1.000 a 16.000. |
+
+A action dona precisa ser `view`, estar publicada para a IA (`ai`), declarar `personalData` e
+receber só `{ id }`: o `id`, do tipo texto, é o único campo obrigatório da entrada, e outros campos,
+se houver, têm valor padrão ou são opcionais. Os caminhos usam ponto para descer em objetos; um
+caminho que passa por uma lista vale para cada item, e um campo intermediário `null` aparece como
+`null`. Declare em `context` só o que orienta a conversa: o exemplo deixa fora contato, documento e
+endereço, e o nome já vai como `title`. Um caminho que termina num objeto ou numa lista leva tudo o
+que está abaixo dele, inclusive campos acrescentados depois à saída; para conferir num teste o que
+cada caminho alcança, use `assistantContextLeaves`, de `@softize/opus/assistant-schema`, sobre o
+schema de saída do manifest. O `title` precisa apontar para texto ou número.
+
+O `opus check` cobra a forma da declaração (regra `assistant-declaration`), o `opus gen` recusa
+`title`, caminho de `context` ou entrada que não conferem com os schemas, e o registro recusa duas
+actions donas do mesmo recurso. O manifest, `runtime.aiTools()` e o MCP (`com.softize.opus/assistant`
+em `_meta`) levam a declaração, e o manifest passa a mostrar também a publicação para a IA.
+
+### Ler o recurso pela action dona
+
+O recurso de um assistente é lido, e o acesso a ele é conferido, somente pela action dona.
+`runtime.readResource` executa a action com `{ id }` pelo mesmo `execute` de qualquer chamada; a
+autorização, a auditoria e a marca de dado pessoal são as da action:
+
+```ts
+const read = await runtime.readResource('customer', id, base, { context: true })
+if (!read.ok) return notFound() // o erro da action, com a categoria dela
+read.resource // { kind: 'customer', id, title: 'Maria Souza', label: 'Assistente do cliente', skill: 'review-customer' }
+read.context // { data, truncated, omitted, personalData: true }
+```
+
+Sem `{ context: true }`, a leitura devolve só o descritor, que basta para conferir o acesso e
+mostrar o nome. Um tipo sem action dona devolve `runtime.assistant_resource_unknown` sem executar
+nada. `runtime.assistants()` lista as declarações com a action dona de cada uma, para o produto
+montar rotas e telas sem lista paralela e para conferir, num teste, que cada `skill` existe no
+registro de procedimentos dele. O Opus não enxerga as rotas HTTP que o produto registra por conta
+própria: um teste do produto deve garantir que nenhuma rota confere acesso a recurso sem passar por
+uma action.
+
+### O dado que vai ao modelo
+
+`context.data` traz só os caminhos declarados, com a estrutura da saída. Quando o JSON passa do
+teto, o corte acontece por etapas, até caber, e fica registrado em `omitted`:
+
+1. sai o último item da maior lista, repetidamente;
+2. com as listas vazias, o texto mais longo é encurtado pela metade, até 200 caracteres;
+3. por fim, saem campos inteiros, do último declarado para o primeiro.
+
+Com qualquer corte, `truncated` vale `true`. O título fica fora do teto e é encurtado a 200
+caracteres. Um caminho que falta na saída em execução é omitido com o motivo `missing` e gera um
+aviso no log, sem falhar a leitura. Quem recebe a saída por outro canal, como o MCP, aplica a mesma
+projeção com `projectAssistantContext(assistant, output)`.
+
+Entregue o dado ao modelo como bloco delimitado, numa mensagem de dado, nunca no prompt de sistema.
+`resourceDataBlock`, de `@softize/opus/ai`, monta o bloco com o tipo, o id, o título, os dados e,
+quando houve corte ou ausência, `truncated` e `omitted`, e escapa dentro dos valores o que poderia
+fechar o delimitador. Quando o modelo chama a action dona como ferramenta, recebe a saída completa
+do contrato, como em qualquer chamada: a projeção governa só o que o host entrega por iniciativa
+própria. Cada execução de uma action com dado pessoal é uma exposição registrada, então reaproveite
+a leitura que já conferiu o acesso em vez de executar a action de novo só para obter o contexto.
+
 ## Prototipar com dados simulados
 
 Para desenhar a interface antes de o backend existir, rode o app em modo design. Nesse modo, toda

package/src/ui/docs/content/ai.md

@@ -86,8 +86,10 @@ const { text } = await ctx.ai!.run('Quais notas a Empresa X emitiu em junho?')
 usado na execução e na auditoria; `title` traz a `label` legível da action, quando existe;
 `description` vem de `ai.description` (ou da `description` da action) e `inputSchema`, do input.
 `metadata.dataProducts` lista os [Produtos de Dados](/docs/data-products) relacionados e
-`metadata.dataProductLabels` associa cada identificador ao seu nome legível. Esses metadados servem ao host: não entram no
-prompt e não concedem acesso.
+`metadata.dataProductLabels` associa cada identificador ao seu nome legível. Na action dona de um
+tipo de recurso, `metadata.assistant` traz o [assistente declarado](/docs/actions): o recurso, a
+chave do procedimento, o nome, o campo do título, os campos do dado ao modelo e o teto. Esses
+metadados servem ao host: não entram no prompt e não concedem acesso.
 
 O agente só executa nomes que `aiTools()` anunciou; uma chamada a outra action volta como erro
 para o modelo. Actions marcadas com `ai: { destructive: true }` ou `ai: { requiresConfirmation: true }`

package/src/ui/docs/content/cli.md

@@ -21,7 +21,8 @@ opus seed check       # bindings, dependências, ciclos e scripts paralelos de s
 ```
 
 `opus check` lê o código-fonte sem executá-lo e aplica regras em quatro grupos: actions
-(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind`), UI
+(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind` e
+`assistant-declaration`, que cobra a forma do [assistente do recurso](/docs/actions)), UI
 (`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`),
 [Produtos de Dados](/docs/data-products) (`data-product-export`, `-id`, `-duplicate`, `-version`,
 `-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`) e

package/src/ui/docs/content/mcp.md

@@ -60,7 +60,9 @@ Quando a action declara o que faz com os dados, a tool traz também as anotaçõ
 `readOnlyHint` vem de `effect`. Numa action que escreve, `destructiveHint` vai sempre explícito, a
 partir de `ai.destructive`, porque o MCP trata a ausência numa escrita como destrutiva.
 Em `_meta`, `com.softize.opus/effect` repete o efeito e `com.softize.opus/personal-data` diz se a
-resposta contém dado pessoal. Veja [Actions](/docs/actions).
+resposta contém dado pessoal. Na action dona de um tipo de recurso, `com.softize.opus/assistant`
+traz o assistente declarado, para o host conhecê-lo pelo catálogo que já consulta e aplicar à saída
+a mesma projeção com `projectAssistantContext`. Veja [Actions](/docs/actions).
 
 `CallTool` recusa com erro qualquer nome fora dessa lista; os demais seguem por `runtime.execute`.
 A exposição declarada em `ai` decide o que o cliente MCP pode executar, e a autorização do contexto