@softize/opus 25.1.0 → 25.3.0

package/docs/protocol.md

@@ -129,12 +129,23 @@ type ListAction<In, Out> = ActionBase<In, Paginated<Out>> & {
   paginate?: 'cursor' | 'offset' | false
   text?:     { fields: string[] }
   periods?:  { value: string, label: I18nRef }[]
+  grouping?: { fields: string[] }
 }
 
 type ViewAction<In, Out> = ActionBase<In, Out> & {
   kind: 'view'
   projection: string[]
   expand?:    Record<string, ExpandSpec>
+  assistant?: ActionAssistant           // torna a view a action dona do recurso (ADR 0053)
+}
+
+type ActionAssistant = {
+  resource:         string              // tipo de recurso, camelCase, único no runtime
+  skill:            string              // chave do procedimento da IA, minúsculas com hífen
+  label:            string              // nome do assistente para pessoas
+  title:            string              // caminho, na saída, do campo que nomeia o recurso
+  context:          string[]            // caminhos, na saída, do dado que pode ir ao modelo
+  maxContextChars?: number              // teto do JSON de context: padrão 4.000, de 1.000 a 16.000
 }
 ```
 
@@ -195,7 +206,10 @@ type OptionsSpec =
 
 **`search`**
 - `filters?: Record<string, FilterSpec>` — filtros disponíveis (chave é nome).
-- `sort?`, `paginate?`, `text?`, `periods?` — ver tipos abaixo.
+- `sort?`, `paginate?`, `text?`, `periods?`, `grouping?` — ver tipos abaixo.
+- `grouping.fields` referencia filtros `select` com opções fechadas (`static` ou
+  `dictionary`). A interface consulta cada valor como um recorte da mesma action; não agrupa só a
+  página carregada.
 
 ```ts
 type FilterSpec = {
@@ -230,6 +244,47 @@ Output de search action é **sempre** `Paginated<Output>` (ver §6).
 **`view`**
 - `projection: string[]` — campos/relações sempre carregados (`['owner', 'company.address']`).
 - `expand?: Record<string, ExpandSpec>` — relações opt-in por request.
+- `assistant?: ActionAssistant` — declara o assistente do recurso que a view lê e a torna a
+  **action dona** desse tipo de recurso (ADR 0053). Ver "Assistente do recurso", abaixo.
+
+### Assistente do recurso
+
+Uma conversa sobre um recurso específico, como um cliente ou um relatório, precisa ler o recurso
+com a permissão de quem conversa, seguir o procedimento próprio daquele tipo e entregar ao modelo só
+o dado necessário. A action `view` que lê o recurso declara as três coisas em `assistant` (ADR 0053).
+
+- **Requisitos da action dona.** Ser `view`; ter `ai` habilitado; declarar `personalData`; ter
+  entrada em que `id`, do tipo texto, é o único campo obrigatório. Cada `resource` tem uma única
+  action dona no runtime. O registro recusa a forma inválida (`runtime.assistant_declaration_invalid`),
+  o teto fora do intervalo (`runtime.assistant_context_limit_invalid`) e o dono duplicado
+  (`runtime.assistant_duplicate_resource`); o `opus check` (regra `assistant-declaration`) e o
+  `opus gen` (caminhos e entrada contra o JSON Schema) cobram o mesmo antes da execução.
+- **Caminhos.** O ponto desce em objetos; um caminho que passa por uma lista vale para cada item;
+  um intermediário `null` aparece como `null`. Num campo anulável ou numa união, o `opus gen` aceita
+  o caminho que existe em algum ramo não nulo. Um caminho que termina num objeto ou numa lista leva
+  tudo abaixo dele (`assistantContextLeaves`, de `@softize/opus/assistant-schema`, lista o que cada
+  caminho alcança). `title` aponta para texto ou número, fora de lista.
+- **Leitura.** `runtime.readResource(resource, id, base, { context? })` executa a action dona com
+  `{ id }` pelo `execute`: autorização, loaders, auditoria, marca de dado pessoal e span são os da
+  action. Devolve `{ ok: true, resource: { kind, id, title, label, skill }, context?, meta }` ou o
+  erro da action; um tipo sem dona devolve `runtime.assistant_resource_unknown` sem executar nada.
+  `runtime.assistants()` lista as declarações com a action dona.
+- **Projeção.** `projectAssistantContext(assistant, output)`, função pura do core, devolve só os
+  caminhos declarados. Acima do teto, corta por etapas até caber: o último item da maior lista; com
+  as listas vazias, o texto mais longo pela metade, até 200 caracteres; por fim, campos inteiros, do
+  último declarado ao primeiro. Marca `truncated` e registra o que saiu em `omitted`. O título fica
+  fora do teto e é encurtado a 200 caracteres. Caminho ausente na saída vai a `omitted` com o motivo
+  `missing`, sem falhar a leitura.
+- **Entrega ao modelo.** O host entrega a projeção como bloco de dado delimitado, numa mensagem de
+  dado, nunca no prompt de sistema (`resourceDataBlock`, de `@softize/opus/ai`). A projeção governa
+  só o que o host entrega por iniciativa própria; quando o modelo chama a action dona como
+  ferramenta, recebe a saída completa do contrato.
+
+**Princípio: acesso a recurso só por action.** O recurso de um assistente é lido, e o acesso a ele é
+conferido, somente pela action dona. O SDK não oferece outro caminho: a declaração não exporta
+regra de acesso, consulta nem atalho que dispense a action. O Opus não enxerga as rotas HTTP que o
+consumidor registra por conta própria; recomenda-se que o consumidor mantenha um teste que reprove
+rota que leia tabela de recurso ou chame regra de acesso de domínio fora de uma action.
 
 ### Exemplos por kind
 
@@ -2279,6 +2334,9 @@ chamada, inclusive por IA e MCP.
 - **`isSystemActor(ctx)`** — responde se a execução foi criada pelo runtime para o sistema (schedule ou job que ele enfileirou). Usado no `authorize` de actions `automatable`. Ver §4.
 - **`internal`** — flag que indica action service-to-service apenas; server adapter não expõe como REST público. Ver §2.
 - **`effect`** — o que a action faz com o estado: `read` ou `write`. `list` e `view` são leitura pelo `GET` e não declaram; `simple` e `form` declaram. Projetado no manifest, nas ferramentas de IA e no MCP (`readOnlyHint`). Ver ADR 0041.
+- **`assistant`** — declaração, numa action `view`, do assistente do recurso que ela lê: tipo de recurso, chave do procedimento, nome, campo do título e caminhos do dado ao modelo. Ver §2 e ADR 0053.
+- **Action dona** — a única action `view` que declara `assistant` para um tipo de recurso; é por ela que o recurso é lido e que o acesso a ele é conferido. Ver §2.
+- **`runtime.readResource`** — lê um recurso pela action dona, pelo mesmo `execute` de qualquer chamada, e devolve o descritor e, quando pedida, a projeção limitada do dado ao modelo. Ver §2.
 - **`personalData`** — a resposta contém dados que identificam pessoas. Com `true`, toda execução bem-sucedida é marcada no `AuditRecord` (`personalData.records`) e no span, qualquer que seja o consumidor. Ver §5 e ADR 0041.
 - **Reaction** — declaração que escuta evento(s) e executa handler. Auto-registrada pelo runtime via EventBusAdapter. Pareada com Action (ator inicia × sistema reage). Ver §12.
 - **`defineReaction`** — função que constrói uma reaction declarativa.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.1.0",
+  "version": "25.3.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,10 @@
     "./introspect": {
       "default": "./bin/lib/introspect.mjs"
     },
+    "./assistant-schema": {
+      "types": "./bin/lib/assistant-schema.d.mts",
+      "default": "./bin/lib/assistant-schema.mjs"
+    },
     "./init": {
       "default": "./bin/lib/init.mjs"
     },

package/registry/skills/create-opus-action/SKILL.md

@@ -16,6 +16,7 @@ registrados no runtime do projeto.
 - nome `<resource>.<verb>` e `kind` (`simple`, `form`, `list` ou `view`);
 - comportamento, autorização, input, output, erros e efeitos esperados;
 - se a action só lê ou altera estado e se a resposta contém dados que identificam pessoas;
+- se a action `view` é a leitura de um tipo de recurso com conversa própria da IA (assistente);
 - caminhos reais de `shared` e `api` adotados pelo repo.
 
 ## Procedimento
@@ -28,13 +29,17 @@ registrados no runtime do projeto.
    `effect: 'write'` e deixa `personalData` comentado de propósito: a ausência aparece no aviso do
    `opus check` até alguém decidir, porque um `false` preenchido por padrão esconderia exposição de
    dado pessoal.
-6. Exportar e registrar o binding no domínio/runtime existente.
-7. Carregar e seguir `$test-opus-action` para cobrir contrato, sucesso, erros e efeitos relevantes.
+6. Quando a `view` for a action dona de um tipo de recurso com assistente, declarar `assistant`
+   depois de `ai`, com `ai` habilitado, `personalData` declarado e entrada `{ id }`, conforme
+   [contrato e binding](references/contract-and-binding.md).
+7. Exportar e registrar o binding no domínio/runtime existente.
+8. Carregar e seguir `$test-opus-action` para cobrir contrato, sucesso, erros e efeitos relevantes.
 
 ## Verificação
 
 Rodar `opus check <escopo>`, typecheck e testes do domínio. Se o projeto gera manifest,
-OpenAPI ou docs, regenerar e conferir o diff. Regenerar também o inventário com `opus copy`
+OpenAPI ou docs, regenerar e conferir o diff; com `assistant`, o `opus gen` confere `title`,
+`context` e a entrada contra os schemas. Regenerar também o inventário com `opus copy`
 e executar `base copy check` quando o contrato declarar texto humano.
 
 ## Limites

package/registry/skills/create-opus-action/references/contract-and-binding.md

@@ -14,6 +14,29 @@ O contrato também declara o que a action faz com os dados (ADR 0041): `effect`
 em todos os kinds. Os dois fatos alimentam a auditoria de exposição de dado pessoal, as ferramentas
 de IA e as anotações do MCP.
 
+## Assistente do recurso
+
+Uma `view` que lê um tipo de recurso com conversa própria da IA declara `assistant` e passa a ser a
+action dona do recurso (ADR 0053): é por ela que o recurso é lido e o acesso, conferido.
+
+```ts
+ai: true,
+assistant: {
+  resource: 'customer',          // camelCase, uma única action dona por recurso
+  skill: 'review-customer',      // chave do procedimento, mantido pelo produto
+  label: 'Assistente do cliente',
+  title: 'name',                 // caminho da saída que nomeia o recurso
+  context: ['stage', 'leads.totalCount'], // só o que orienta a conversa
+},
+```
+
+- Exigir `ai` habilitado, `personalData` declarado e entrada em que `id`, do tipo texto, é o único
+  campo obrigatório.
+- Escolher `context` campo a campo e deixar fora contato, documento, endereço e texto livre sobre
+  pessoas; o título já vai ao modelo.
+- Não criar rota, consulta ou regra de acesso paralela para ler o recurso: o produto usa
+  `runtime.readResource` e confere as chaves de `skill` com `runtime.assistants()` num teste.
+
 Ordem cobrada pelo check: identidade → documentação → input/output e natureza (`effect`,
-`personalData`) → autorização → handler → comportamento. Campos específicos do kind permanecem junto do grupo ao qual
+`personalData`) → autorização → handler → comportamento → integração (`ai`, `assistant`). Campos específicos do kind permanecem junto do grupo ao qual
 servem e o scaffold acompanha a forma atual do SDK.

package/registry/skills/create-opus-action/references/evaluations.md

@@ -6,3 +6,6 @@
 - Execução: “Crie `customer.list`, que lista clientes com nome e telefone” resulta em
   `personalData: true` declarado; “Crie `sales.performance`, que soma vendas por mês” resulta em
   `effect: 'read'` e `personalData: false`.
+- Execução: “Crie `customer.view`, que o assistente do cliente usa para ler o cadastro” resulta em
+  `assistant` depois de `ai`, `personalData` declarado, entrada `{ id }` e `context` sem contato
+  nem documento; `opus check` e `opus gen` passam.

package/registry/skills/test-opus-action/SKILL.md

@@ -18,7 +18,10 @@ infraestrutura real quando a unidade é o contrato.
    pelas opções do harness.
 3. Cobrir sucesso, input inválido, autorização negada e erros de negócio materiais.
 4. Afirmar output e efeitos observáveis como `emitted`, `logged` e estado do adapter fake.
-5. Adicionar integração somente para a fronteira não provada pela unidade: banco, transporte,
+5. Quando a action declarar `assistant`, ler o recurso por `runtime.readResource` num runtime com a
+   action registrada e provar a autorização da action, o descritor e o `context.data` só com os
+   caminhos declarados, conforme o [harness](references/harness.md).
+6. Adicionar integração somente para a fronteira não provada pela unidade: banco, transporte,
    registro real ou wiring entre actions.
 
 ## Verificação

package/registry/skills/test-opus-action/references/evaluations.md

@@ -3,3 +3,5 @@
 - Dispara: “Cubra com testes a action Opus de arquivar cliente.”
 - Não dispara: “Teste este parser CSV que não usa action.”
 - Execução: provar input inválido, autorização e efeitos com `runAction`, sem rede real.
+- Execução: para `customer.view` com `assistant`, provar por `runtime.readResource` que a
+  autorização da action vale e que `context.data` não traz campo fora de `context`.

package/registry/skills/test-opus-action/references/harness.md

@@ -8,3 +8,17 @@
 
 Teste o binding completo. Um contrato sem handler falha com `testing.no_handler`: os dados do modo
 design são gerados pelo plugin `opusDesign()` e não são comportamento da action.
+
+## Assistente do recurso
+
+`runAction` executa a action, mas não a leitura do recurso. Para uma action com `assistant`
+(ADR 0053), registrar o `ActionDef` com `createRuntime` e chamar
+`runtime.readResource(resource, id, base, { context: true })`:
+
+- negar a permissão no `base` e afirmar `ok: false` com a categoria da action, sem o handler rodar;
+- afirmar `resource.title`, `resource.skill` e `context.personalData`;
+- afirmar que `context.data` traz só os caminhos de `context` e que um campo pessoal fora deles não
+  aparece;
+- quando a saída puder faltar um caminho declarado, afirmar `omitted` com o motivo `missing`.
+
+Os cortes do teto são do SDK e já têm cobertura nele; o teste do produto prova a declaração.

package/src/ai/index.ts

@@ -15,3 +15,6 @@ export type { AiAdapter, AiCompleteOptions } from '../core/index.ts'
 // o formatador. É o ponto de consistência pra qualquer consumidor (chat, copilot, MCP externo).
 export type { AskOption, AskQuestion, AskAnswer } from '../core/index.ts'
 export { ASK_USER_TOOL, ASK_TOOL_DESCRIPTION, ASK_INPUT_SCHEMA, formatAnswers } from './ask.ts'
+// Dado do recurso de um assistente (ADR 0053): o bloco delimitado que o host entrega ao modelo.
+export { RESOURCE_DATA_TAG, resourceDataBlock } from './resource-context.ts'
+export type { ResourceDataBlockInput, ResourceDataBlockOptions } from './resource-context.ts'

package/src/ai/resource-context.ts

@@ -0,0 +1,113 @@
+/**
+ * O bloco de dado do recurso que o host entrega ao modelo (ADR 0053, seção 3).
+ *
+ * O dado do recurso é dado, nunca instrução: vai numa mensagem de dado, delimitado, e nunca no
+ * prompt de sistema. O bloco leva o tipo, o id, o título e os dados e, quando a projeção cortou ou
+ * não encontrou algum campo, `truncated` e `omitted`, para o modelo saber que o dado está
+ * incompleto e decidir chamar a action dona. O conteúdo é JSON e nenhum valor consegue fechar o
+ * delimitador: os sinais de menor e maior, os sinais que se parecem com eles, os caracteres de
+ * controle, os invisíveis (formatação, seletores de variação, preenchimentos) e os espaços
+ * incomuns saem como escapes `\uXXXX`, que continuam valendo o mesmo texto quando o JSON é lido.
+ */
+
+import type { ResourceContext, ResourceDescriptor } from '../core/index.ts'
+
+/** A etiqueta padrão do bloco. */
+export const RESOURCE_DATA_TAG = 'resource-data'
+
+const TAG_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+
+// Os códigos ficam numéricos para o arquivo não depender da exibição desses sinais.
+//
+// Sinais que um modelo pode ler como `<` ou `>`. A primeira lista sai do confusables.txt do Unicode
+// (UTS #39, versão de 2026-08-06): todo caractere cujo esqueleto contém `<` ou `>`, como ‹, ❮, ≪
+// e ᐸ. A segunda traz colchetes angulares de outros blocos, que o arquivo não liga a `<` e `>` mas
+// que delimitam texto do mesmo jeito. Os que a NFKC transforma em `<` ou `>` são pegos também pela
+// regra de `isUnsafe`, sem depender das listas.
+const ANGLE_CONFUSABLES = [
+  0x02c2, 0x02c3, 0x1032d, 0x1433, 0x1437, 0x1438, 0x1440, 0x1441, 0x1444, 0x1445, 0x150c, 0x16aec,
+  0x16b2, 0x16f3f, 0x1d236, 0x1d237, 0x2039, 0x203a, 0x226a, 0x226b, 0x22d6, 0x22d7, 0x22d8, 0x22d9,
+  0x276e, 0x276f, 0x2a20, 0x2aa5, 0x2cb4, 0x2cb5, 0x2d66, 0xfe64, 0xfe65, 0xff1c, 0xff1e,
+]
+const ANGLE_BRACKETS = [
+  0x2329, 0x232a, // 〈 〉 técnicos
+  0x276c, 0x276d, 0x2770, 0x2771, // ornamentais
+  0x27e8, 0x27e9, 0x27ea, 0x27eb, // matemáticos
+  0x29fc, 0x29fd, // curvos
+  0x3008, 0x3009, 0x300a, 0x300b, // CJK
+  0xfe3d, 0xfe3e, 0xfe3f, 0xfe40, // formas verticais
+]
+const ANGLE_LOOKALIKES = new Set([...ANGLE_CONFUSABLES, ...ANGLE_BRACKETS])
+
+// Caracteres sem glifo próprio que escondem ou deslocam o texto: preenchimentos do hangul e
+// seletores de variação, que alteram o glifo anterior sem aparecer.
+const INVISIBLE = new Set([0x115f, 0x1160, 0x3164, 0xffa0, 0x180b, 0x180c, 0x180d, 0x180f])
+
+function isVariationSelector(code: number): boolean {
+  return (code >= 0xfe00 && code <= 0xfe0f) || (code >= 0xe0100 && code <= 0xe01ef)
+}
+
+// Controle (C0, DEL, C1 e NEL), formatação invisível (zero-width, bidi, tags), separadores de linha e
+// parágrafo, que o JSON não escapa, e espaços que não são o espaço comum.
+const UNSAFE_CATEGORY = /^[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Zs}]$/u
+
+function isUnsafe(char: string): boolean {
+  if (char === ' ') return false
+  const code = char.codePointAt(0)!
+  if (code === 0x3c || code === 0x3e) return true
+  if (ANGLE_LOOKALIKES.has(code) || INVISIBLE.has(code) || isVariationSelector(code)) return true
+  if (UNSAFE_CATEGORY.test(char)) return true
+  if (code < 0x80) return false
+  const normalized = char.normalize('NFKC')
+  return normalized.includes('<') || normalized.includes('>')
+}
+
+function escapeUnsafe(json: string): string {
+  let out = ''
+  for (const char of json) {
+    if (!isUnsafe(char)) {
+      out += char
+      continue
+    }
+    for (let index = 0; index < char.length; index += 1) {
+      out += `\\u${char.charCodeAt(index).toString(16).padStart(4, '0')}`
+    }
+  }
+  return out
+}
+
+export interface ResourceDataBlockOptions {
+  /** Etiqueta do delimitador, em minúsculas com hífen. Padrão: `resource-data`. */
+  tag?: string
+}
+
+/** O que o bloco recebe: o descritor e a projeção de `runtime.readResource(..., { context: true })`. */
+export interface ResourceDataBlockInput {
+  resource: Pick<ResourceDescriptor, 'kind' | 'id' | 'title'>
+  context: Pick<ResourceContext, 'data' | 'truncated' | 'omitted'>
+}
+
+/**
+ * Monta o bloco delimitado com o dado do recurso. Exemplo:
+ *
+ * ```text
+ * <resource-data>
+ * {"kind":"customer","id":"c1","title":"Maria Souza","data":{"stage":"lead"}}
+ * </resource-data>
+ * ```
+ */
+export function resourceDataBlock(input: ResourceDataBlockInput, options: ResourceDataBlockOptions = {}): string {
+  const tag = options.tag ?? RESOURCE_DATA_TAG
+  if (!TAG_RE.test(tag)) throw new Error(`A etiqueta "${tag}" precisa estar em minúsculas com hífen.`)
+  const { resource, context } = input
+  const incomplete = context.truncated || context.omitted.length > 0
+  const payload = {
+    kind: resource.kind,
+    id: resource.id,
+    title: resource.title,
+    data: context.data,
+    ...(incomplete ? { truncated: context.truncated, omitted: context.omitted } : {}),
+  }
+  const json = escapeUnsafe(JSON.stringify(payload))
+  return `<${tag}>\n${json}\n</${tag}>`
+}

package/src/core/actions.ts

@@ -9,8 +9,9 @@
  * resto server-only) — ver `contracts.ts`. `defineAction` continua válido e
  * suportado para action server-only, em que não há contrato a compartilhar.
  *
- * Validação estrutural acontece no `Runtime.register()`, não aqui. Esta função
- * é puramente sobre **declaração**.
+ * A factory valida contradições que existem inteiras na declaração, como um
+ * `grouping` que referencia um filtro incompatível. O runtime repete essas
+ * guardas para actions montadas sem a factory.
  *
  * Ver §2 do protocolo.
  */
@@ -22,6 +23,7 @@ import type {
   SimpleAction,
   ViewAction,
 } from './types.ts'
+import { assertValidListGrouping } from './list-grouping.ts'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
@@ -61,6 +63,7 @@ export function defineAction<In, Out, ParsedIn = In>(
 ): ViewAction<In, Out, ParsedIn>
 
 export function defineAction(spec: any): any {
+  if (spec.kind === 'list') assertValidListGrouping(spec)
   return spec
 }