@softize/opus 25.0.0 → 25.2.0

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}>`
+}