@t4h/agent-runtime 0.1.1 → 0.2.0

package/README.md

@@ -1,10 +1,12 @@
 # @t4h/agent-runtime
 
 Runtime dos **colaboradores digitais** da Tech for Humans. Um agente é uma pasta
-(`agent.yaml`, `persona.md`, `skills/`, `evals/`); este pacote faz o resto:
+(`agent.yaml`, `persona.md`, `skills/`, `evals/`); este pacote faz o resto, como o
+`@t4h/mcp-provider-sdk` faz para os providers:
 
 - valida o `agent.yaml` (schema v1 em `schema/agent.schema.json` + regras entre campos);
-- caixa de entrada no Postgres: junta eventos por assunto, descarta repetido, ordena por prioridade;
+- caixa de entrada no Postgres: junta eventos por assunto, descarta repetido (por fonte),
+  ordena por prioridade; evento novo acorda o agente, e o cron fica como rede de segurança;
 - rodadas com lock, teto de itens e de tempo, backoff e exceção para o DRI;
 - portão de política em toda chamada de ferramenta: nível por rotina (shadow, copilot,
   agent, autonomous), proibidas, motivo obrigatório, idempotência, janela e teto por hora;
@@ -12,13 +14,83 @@ Runtime dos **colaboradores digitais** da Tech for Humans. Um agente é uma past
 - memória curta (SQLite, uma execução) e longa (Postgres);
 - acesso aos sistemas só pelo Enterprise MCP Gateway, com a identidade própria do agente
   (client do Keycloak com service account);
-- cérebro: Claude Agent SDK isolado (sem ferramentas built-in, sem config do disco).
+- cérebro: Claude Agent SDK isolado (sem ferramentas built-in, sem config do disco);
+- o conector `agents_<círculo>` (proto, handlers e catálogo base, versionados juntos),
+  o ambiente validado no boot e o processo inteiro em `startAgents()`.
 
-O template de repositório de agentes e o agente de referência vivem em
-[`t4h-agents`](https://github.com/tech4humans-brasil/t4h-agents).
+Cada círculo cria o seu repositório de agentes a partir de um template (ver
+[Usar como template](../../web/src/content/agents/01-usar-como-template.md)). A documentação
+completa está na seção **Agentes** do site do gateway.
 
 ```bash
 pnpm --filter @t4h/agent-runtime build
 pnpm --filter @t4h/agent-runtime test     # sem modelo: ScriptedBrain + PGlite
 t4h-agent validate agents/                 # valida os agent.yaml de um repositório
+t4h-agent catalog financeiro --endpoint agentes-financeiro.example.com:443 > catalog.yaml
 ```
+
+## Entrypoint de um repositório de agentes
+
+```ts
+import { startAgents } from '@t4h/agent-runtime';
+
+await startAgents({ agentsDir: 'agents', pluginsDir: process.env.PLUGINS_DIR });
+```
+
+`startAgents` carrega os agentes, valida o ambiente (`loadAgentEnv`), abre o banco e roda
+as migrações, sobe o webhook de eventos, o cron e o conector gRPC (`createProviderServer`
+do SDK, auditoria em JSON no stdout) e trata SIGINT/SIGTERM parando na ordem: entrada,
+conector, conversas em andamento, banco. Opções: `wiring` (substitui o gateway por um stub
+local; recusado em produção), `notifier`, `brain`. Fora de produção, sem as variáveis do
+passaporte, sobe sem o conector (com aviso).
+
+## Conector `agents_<círculo>`
+
+Contrato em `proto/t4h/agents/v1/agents.proto` (`AGENTS_SERVICE_FQN`, `agentsProtoPath()`),
+handlers em `agentsConnectorHandlers(host)` e catálogo base em
+`catalog/agents.catalog.yaml` (`agentsCatalog({ circle, endpoint })` ou
+`t4h-agent catalog`). O slug segue `^agents_[a-z0-9_]+$`. Os grants são por tabela:
+
+| Tabela | Tools | Quem recebe |
+|---|---|---|
+| `agente` | `agents_list`, `agent_ask`, `agent_answer` | quem pode ver e conversar com os agentes |
+| `acao` | `agent_explain`, `action_correct` | quem audita e corrige |
+| `proposta` | `agent_proposals`, `proposal_decide` | quem aprova (líder do time, DRI) |
+| `controle` | `agent_block`, `routine_cap` | só Segurança e o DRI |
+
+A conversa é assíncrona: o gateway corta a chamada ao provider em
+`PROVIDER_CALL_TIMEOUT_MS` (30 s por padrão). `agent_ask` espera até `AGENTS_ASK_WAIT_MS`
+(20 s) e, se a resposta não veio, devolve `running` com o `ask_id`; `agent_answer` busca
+depois, de qualquer réplica, e só para quem perguntou.
+
+## Eventos
+
+`POST /agents/:id/events` com `x-t4h-source: <fonte>` e
+`x-t4h-signature: t=<unix s>,v1=<hex>`, onde `v1 = HMAC-SHA256(segredo da fonte, "<t>.<corpo cru>")`
+(`signEvent()` monta o header). Tolerância de 300 s. O id do evento é gravado como
+`<fonte>:<id>`. `POST /agents/:id/rounds` só existe fora de produção.
+
+## Ambiente
+
+| Variável | Produção | Padrão / fora de produção |
+|---|---|---|
+| `DATABASE_URL` | `postgres://…` obrigatório | `pglite:<pasta>` ou em memória |
+| `EVENTS_HMAC_SECRETS` | `fonte=segredo,…`, ao menos uma | sem: aceita sem assinatura |
+| `EVENTS_PORT` / `EVENTS_WAKE_DEBOUNCE_MS` | | 8080 / 10000 |
+| `GATEWAY_URL`, `KEYCLOAK_ISSUER` | obrigatórios | sem `GATEWAY_URL`: `wiring` local |
+| `AGENT_<ID>_CLIENT_SECRET` | um por agente (hífen vira `_`) | |
+| `GATEWAY_DEV_TOKEN` | proibido | token fixo no lugar do Keycloak |
+| `ANTHROPIC_API_KEY` | obrigatório (ou `CLAUDE_CODE_USE_BEDROCK`/`_VERTEX`) | |
+| `AGENTS_ASK_WAIT_MS` | | 20000, abaixo de `PROVIDER_CALL_TIMEOUT_MS` (30000) |
+| `PORT`, `GATEWAY_JWKS_URL`, `GATEWAY_ISSUER`, `SERVICE_AUDIENCE`, mTLS | como em `loadProviderEnv()` | sem passaporte: sem conector |
+
+## Da 0.1 para a 0.2
+
+- O conector (proto, handlers, catálogo) e o wiring do gateway saíram do template e
+  vieram para cá; o template deixa de depender de `@t4h/mcp-provider-sdk` e `@grpc/grpc-js`.
+- `AskAgent` agora devolve `ask_id`/`status` e ganhou `GetAnswer`; `conversation_id` virou
+  `thread_id`. RPCs novas: `SetBlocked` e `CapRoutine` (tabela `controle`).
+- `host.listen(port, secret)` virou `host.listen(port, { secrets, allowManualRounds, production })`;
+  `EVENTS_HMAC_SECRET` virou `EVENTS_HMAC_SECRETS` (por fonte, com timestamp) e
+  `verifySignature` saiu (use `verifyEventSignature`).
+- Migração aditiva: tabela `agent_conversation` e coluna `agent_event.source`.

package/catalog/agents.catalog.yaml

@@ -0,0 +1,123 @@
+# Catálogo do conector de agentes de um círculo, gerado por
+#   t4h-agent catalog {{circle}} --endpoint {{endpoint}}
+# a partir do catálogo base do @t4h/agent-runtime (versionado junto do proto). Não edite à
+# mão: gere de novo com a versão do runtime que o círculo usa.
+#
+# Cada chave de inputSchema.properties é um campo do request no proto (snake_case). Grants
+# (URN `agents_{{circle}}:<resourceTable>:<campo>`) seguem o fluxo de permissões da
+# plataforma, nunca este arquivo:
+#   agente:   agents, agent_id, ask_id, status, answer, error  quem pode ver e conversar com os agentes
+#   acao:     actions, action_id, status, routine_level         quem audita e corrige
+#   proposta: proposals, action_id, status, result_json         quem aprova (líder do time, DRI)
+#   controle: agent_id, blocked, routine, level                 só Segurança e o DRI
+subservice: agents_{{circle}}
+endpoints:
+  local: '{{local_endpoint}}'
+  production: '{{endpoint}}'
+tools:
+  - name: agents_list
+    rpc: ListAgents
+    description: 'Lista os colaboradores digitais deste círculo: o que cada um faz, o nível de cada rotina agora (e por que desceu, se desceu), DRI, time e se está bloqueado.'
+    resourceTable: agente
+    readOnly: true
+    inputSchema: { type: object, properties: {} }
+
+  - name: agent_ask
+    rpc: AskAgent
+    description: 'Conversa com um agente. Ele só lê, com o acesso dele. Se a resposta vier com status "running", chame agent_answer com o ask_id em alguns segundos; se vier "error", agent_answer traz o motivo. Cada pessoa tem um teto de perguntas em andamento com o mesmo agente. Para pedir uma ação, abra a demanda pelo canal normal.'
+    resourceTable: agente
+    readOnly: false
+    inputSchema:
+      type: object
+      properties:
+        agent_id: { type: string }
+        message: { type: string }
+        thread_id: { type: string, description: 'Opcional: para continuar uma conversa, passe o ask_id da primeira pergunta (ou um id seu: até 64 letras, dígitos, "_" ou "-"). O agente recebe as últimas trocas desse fio feitas por você.' }
+      required: [agent_id, message]
+
+  - name: agent_answer
+    rpc: GetAnswer
+    description: 'Busca a resposta de uma pergunta feita com agent_ask. Enquanto vier "running", espere alguns segundos e chame de novo. Só quem perguntou lê a resposta.'
+    resourceTable: agente
+    readOnly: true
+    inputSchema:
+      type: object
+      properties:
+        ask_id: { type: string }
+      required: [ask_id]
+
+  - name: agent_explain
+    rpc: ExplainActions
+    description: 'Mostra o que um agente fez, em que modo (executou, propôs, só registrou, foi barrado) e com que motivo. Filtra por assunto (ex.: ticket:123).'
+    resourceTable: acao
+    readOnly: true
+    inputSchema:
+      type: object
+      properties:
+        agent_id: { type: string }
+        subject: { type: string }
+        limit: { type: integer, minimum: 1, maximum: 100 }
+      required: [agent_id]
+
+  - name: agent_proposals
+    rpc: ListProposals
+    description: 'Propostas de um agente esperando aprovação de uma pessoa (rotinas no nível Copiloto).'
+    resourceTable: proposta
+    readOnly: true
+    inputSchema:
+      type: object
+      properties:
+        agent_id: { type: string }
+      required: [agent_id]
+
+  - name: proposal_decide
+    rpc: DecideProposal
+    description: 'Aprova ou recusa uma proposta. Aprovada, a ação roda na hora com a identidade do agente e fica registrada com quem aprovou.'
+    resourceTable: proposta
+    readOnly: false
+    inputSchema:
+      type: object
+      properties:
+        action_id: { type: integer }
+        approve: { type: boolean }
+        note: { type: string }
+      required: [action_id, approve]
+
+  - name: action_correct
+    rpc: CorrectAction
+    description: 'Corrige uma ação que o agente executou: diga o que estava errado e o certo. Vira aprendizado e conta no disjuntor, que desce o nível da rotina se os erros passarem do limite.'
+    resourceTable: acao
+    readOnly: false
+    inputSchema:
+      type: object
+      properties:
+        action_id: { type: integer }
+        note: { type: string }
+      required: [action_id, note]
+
+  - name: agent_block
+    rpc: SetBlocked
+    description: 'Bloqueio de emergência: blocked=true para tudo o que o agente faz na hora, sem deploy (motivo obrigatório); blocked=false libera. Avisa o DRI e Segurança.'
+    resourceTable: controle
+    readOnly: false
+    inputSchema:
+      type: object
+      properties:
+        agent_id: { type: string }
+        blocked: { type: boolean }
+        reason: { type: string }
+      required: [agent_id, blocked]
+
+  - name: routine_cap
+    rpc: CapRoutine
+    description: 'Limita o nível de uma rotina do agente (shadow, copilot ou agent), com motivo. Com level vazio, tira o teto e volta a valer o nível do manifesto. Avisa o DRI e Segurança.'
+    resourceTable: controle
+    readOnly: false
+    inputSchema:
+      type: object
+      properties:
+        agent_id: { type: string }
+        routine: { type: string }
+        level: { type: string, enum: ['', shadow, copilot, agent] }
+        reason: { type: string }
+      required: [agent_id, routine, level]

package/dist/catalog.d.ts

@@ -0,0 +1,13 @@
+/** `agents_<círculo>`: o schema do catálogo não aceita hífen no subservice. */
+export declare const AGENTS_SLUG_PATTERN: RegExp;
+export declare function agentsCatalogPath(): string;
+export interface AgentsCatalogOptions {
+    /** Nome do círculo em minúsculas, com `_` no lugar de hífen: `financeiro`, `dados_bi`. */
+    circle: string;
+    /** Endpoint gRPC de produção do conector (`host:porta`). */
+    endpoint: string;
+    /** Endpoint para TARGET_ENV=local. Padrão: o mesmo de `endpoint`. */
+    localEndpoint?: string;
+}
+/** O catálogo de `agents_<círculo>` em YAML, pronto para o repositório de catálogos. */
+export declare function agentsCatalog(o: AgentsCatalogOptions): string;

package/dist/catalog.js

@@ -0,0 +1,39 @@
+/**
+ * Catálogo do conector `agents_<círculo>`: o base (`catalog/agents.catalog.yaml`) mora
+ * aqui, versionado junto do proto, para tool e RPC nunca se desencontrarem. O repositório
+ * de catálogos do gateway gera o de cada círculo com `t4h-agent catalog`, sem escrever à mão.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+/** `agents_<círculo>`: o schema do catálogo não aceita hífen no subservice. */
+export const AGENTS_SLUG_PATTERN = /^agents_[a-z0-9_]+$/;
+/** Mesmo padrão de endpoint do schema do catálogo (`host:porta`). */
+const ENDPOINT_PATTERN = /^[a-zA-Z0-9.-]+:[0-9]{1,5}$/;
+/** O subservice tem no máximo 50 caracteres (schema do catálogo). */
+const MAX_SUBSERVICE = 50;
+export function agentsCatalogPath() {
+    return fileURLToPath(new URL('../catalog/agents.catalog.yaml', import.meta.url));
+}
+/** O catálogo de `agents_<círculo>` em YAML, pronto para o repositório de catálogos. */
+export function agentsCatalog(o) {
+    const slug = `agents_${o.circle}`;
+    if (!AGENTS_SLUG_PATTERN.test(slug) || slug.length > MAX_SUBSERVICE) {
+        throw new Error(`círculo "${o.circle}" inválido: use minúsculas, dígitos e _ (o slug ${slug} precisa casar ${AGENTS_SLUG_PATTERN} e ter até ${MAX_SUBSERVICE} caracteres)`);
+    }
+    const local = o.localEndpoint ?? o.endpoint;
+    for (const e of [o.endpoint, local]) {
+        if (!ENDPOINT_PATTERN.test(e))
+            throw new Error(`endpoint "${e}" inválido: use host:porta`);
+    }
+    const yaml = readFileSync(agentsCatalogPath(), 'utf8')
+        .replaceAll('{{circle}}', o.circle)
+        .replaceAll('{{local_endpoint}}', local)
+        .replaceAll('{{endpoint}}', o.endpoint);
+    // Falha aqui, e não no apply, se a substituição quebrar o YAML.
+    const parsed = parseYaml(yaml);
+    if (parsed.subservice !== slug)
+        throw new Error(`catálogo base gerou subservice "${parsed.subservice}", esperado ${slug}`);
+    return yaml;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAEzD,qEAAqE;AACrE,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAEvD,qEAAqE;AACrE,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B,MAAM,UAAU,iBAAiB;IAC/B,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,gCAAgC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACnF,CAAC;AAWD,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,CAAuB;IACnD,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,MAAM,mDAAmD,IAAI,kBAAkB,mBAAmB,cAAc,cAAc,cAAc,CAAC,CAAC;IAC9K,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,QAAQ,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,4BAA4B,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,iBAAiB,EAAE,EAAE,MAAM,CAAC;SACnD,UAAU,CAAC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;SAClC,UAAU,CAAC,oBAAoB,EAAE,KAAK,CAAC;SACvC,UAAU,CAAC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC1C,gEAAgE;IAChE,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAA4B,CAAC;IAC1D,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,MAAM,CAAC,UAAU,eAAe,IAAI,EAAE,CAAC,CAAC;IAC3H,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli.js

@@ -1,14 +1,16 @@
 /**
- * t4h-agent validate <pasta agents/>   valida todos os agent.yaml (schema + regras)
+ * t4h-agent validate [pasta agents/]                       valida todos os agent.yaml (schema + regras)
+ * t4h-agent catalog <círculo> --endpoint <host:porta>      imprime o catálogo de agents_<círculo>
+ *           [--local-endpoint <host:porta>]
  */
-import { loadAgents } from './manifest.js';
+import { parseArgs } from 'node:util';
+import { agentsCatalog } from './catalog.js';
 import { effectiveLevel } from './levels.js';
-const [cmd, dir = 'agents'] = process.argv.slice(2);
-if (cmd !== 'validate') {
-    console.error('uso: t4h-agent validate [pasta]');
-    process.exit(2);
-}
-try {
+import { loadAgents } from './manifest.js';
+const USAGE = `uso:
+  t4h-agent validate [pasta]
+  t4h-agent catalog <círculo> --endpoint <host:porta> [--local-endpoint <host:porta>]`;
+function validate(dir = 'agents') {
     const agents = loadAgents(dir);
     for (const a of agents) {
         const m = a.manifest;
@@ -20,6 +22,29 @@ try {
     }
     console.info(`\n${agents.length} agente(s) válido(s).`);
 }
+function catalog(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { endpoint: { type: 'string' }, 'local-endpoint': { type: 'string' } },
+    });
+    const [circle] = positionals;
+    if (!circle || !values.endpoint || positionals.length > 1)
+        throw new Error(USAGE);
+    // Só o YAML no stdout: dá para redirecionar direto para o catalog.yaml.
+    process.stdout.write(agentsCatalog({ circle, endpoint: values.endpoint, ...(values['local-endpoint'] ? { localEndpoint: values['local-endpoint'] } : {}) }));
+}
+const [cmd, ...rest] = process.argv.slice(2);
+try {
+    if (cmd === 'validate')
+        validate(rest[0]);
+    else if (cmd === 'catalog')
+        catalog(rest);
+    else {
+        console.error(USAGE);
+        process.exit(2);
+    }
+}
 catch (e) {
     console.error(e.message);
     process.exit(1);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEpD,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;IACvB,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QAChF,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnD,MAAM,GAAG,GAAG,cAAc,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YACvE,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvH,CAAC;IACH,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,MAAM,uBAAuB,CAAC,CAAC;AAC1D,CAAC;AAAC,OAAO,CAAC,EAAE,CAAC;IACX,OAAO,CAAC,KAAK,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/connector.d.ts

@@ -0,0 +1,13 @@
+import { type ProviderHandlers } from '@t4h/mcp-provider-sdk';
+import { type AgentHost } from './host.js';
+export declare const AGENTS_SERVICE_FQN = "t4h.agents.v1.AgentsService";
+/** O proto do conector, publicado com o pacote (o gateway o puxa por reflection). */
+export declare function agentsProtoPath(): string;
+export interface AgentsConnectorOptions {
+    /** Quantas ações `ExplainActions` devolve sem `limit` (padrão 20) e no máximo (100). */
+    historyLimit?: {
+        default: number;
+        max: number;
+    };
+}
+export declare function agentsConnectorHandlers(host: AgentHost, opts?: AgentsConnectorOptions): ProviderHandlers;

package/dist/connector.js

@@ -0,0 +1,208 @@
+/**
+ * Handlers do conector de agentes do círculo (`proto/t4h/agents/v1/agents.proto`).
+ *
+ * Mesmo modelo de qualquer provider do gateway: o gateway autentica e autoriza (grants URN
+ * por papel, concedidos pela plataforma), manda a FieldMask e o passaporte; aqui só
+ * executamos e projetamos. `ctx.user` é auditoria e "quem pergunta": nunca autorização.
+ * Quem pode bloquear ou limitar um agente é decidido pelo grant da tabela `controle`.
+ */
+import { status as grpcStatus } from '@grpc/grpc-js';
+import { applyFieldMask, ProviderError } from '@t4h/mcp-provider-sdk';
+import { fileURLToPath } from 'node:url';
+import { HostError } from './host.js';
+import { effectiveLevel } from './levels.js';
+import { CONVERSATION_ROUTINE } from './store/long-term.js';
+export const AGENTS_SERVICE_FQN = 't4h.agents.v1.AgentsService';
+/** O proto do conector, publicado com o pacote (o gateway o puxa por reflection). */
+export function agentsProtoPath() {
+    return fileURLToPath(new URL('../proto/t4h/agents/v1/agents.proto', import.meta.url));
+}
+/** Tetos que uma pessoa pode pôr numa rotina pelo conector. */
+const CAP_LEVELS = ['shadow', 'copilot', 'agent'];
+function toAction(a) {
+    return {
+        id: String(a.id),
+        subject: a.subject ?? '',
+        routine: a.routine,
+        tool: a.tool,
+        mode: a.mode,
+        status: a.status,
+        level: a.level,
+        reason: a.reason ?? '',
+        input_json: JSON.stringify(a.input),
+        note: a.note ?? '',
+        created_at: new Date(a.created_at).toISOString(),
+    };
+}
+function agentOr404(host, id) {
+    if (!id || !host.agents.has(id))
+        throw new ProviderError(grpcStatus.NOT_FOUND, `agente "${id}" não existe neste conector`);
+    return host.agent(id);
+}
+function routineOr404(a, routine) {
+    const spec = a.manifest.routines[routine];
+    if (!routine || !spec)
+        throw new ProviderError(grpcStatus.NOT_FOUND, `${a.manifest.id} não tem a rotina "${routine}"`);
+    return spec;
+}
+/** O id de ação chega como texto (uint64 com `longs: String`). */
+function actionId(raw) {
+    const id = Number(raw);
+    if (!Number.isSafeInteger(id) || id <= 0)
+        throw new ProviderError(grpcStatus.INVALID_ARGUMENT, 'action_id inválido');
+    return id;
+}
+const HOST_STATUS = {
+    unavailable: grpcStatus.UNAVAILABLE,
+    resource_exhausted: grpcStatus.RESOURCE_EXHAUSTED,
+    invalid_argument: grpcStatus.INVALID_ARGUMENT,
+};
+/**
+ * Erro de regra do host (não existe, já decidida, bloqueado) vira FAILED_PRECONDITION;
+ * desligando, teto de conversas e pedido malformado têm status próprio.
+ */
+function precondition(e) {
+    if (e instanceof ProviderError)
+        throw e;
+    if (e instanceof HostError)
+        throw new ProviderError(HOST_STATUS[e.code], e.message);
+    throw new ProviderError(grpcStatus.FAILED_PRECONDITION, e.message);
+}
+async function levelNow(host, a, routine) {
+    const spec = a.manifest.routines[routine];
+    if (!spec)
+        return '';
+    const caps = await host.store.levelCaps(a.manifest.id);
+    return effectiveLevel({ stage: a.manifest.stage, manifestLevel: spec.level, cap: caps.get(routine)?.cap ?? null });
+}
+export function agentsConnectorHandlers(host, opts = {}) {
+    const limits = opts.historyLimit ?? { default: 20, max: 100 };
+    // ── agente ──────────────────────────────────────────────────────────────────────
+    const listAgents = async (ctx) => {
+        const agents = await Promise.all([...host.agents.values()].map(async (a) => {
+            const m = a.manifest;
+            const caps = await host.store.levelCaps(m.id);
+            return {
+                id: m.id,
+                name: m.name,
+                description: m.description,
+                stage: m.stage,
+                dri: m.owner.dri,
+                team: `${m.team.area}/${m.team.team}`,
+                blocked: Boolean(await host.store.killSwitch(m.id)),
+                routines: Object.entries(m.routines).map(([name, r]) => ({
+                    name,
+                    does: r.does,
+                    level: effectiveLevel({ stage: m.stage, manifestLevel: r.level, cap: caps.get(name)?.cap ?? null }),
+                    target: r.target ?? r.level,
+                    capped_reason: caps.get(name)?.reason ?? '',
+                })),
+            };
+        }));
+        return applyFieldMask({ agents }, ctx.fieldMaskPaths);
+    };
+    const askAgent = async (ctx) => {
+        const { agent_id, message, thread_id } = ctx.request;
+        agentOr404(host, agent_id);
+        if (!message?.trim())
+            throw new ProviderError(grpcStatus.INVALID_ARGUMENT, 'message é obrigatório');
+        const r = await host.ask(agent_id, { email: ctx.user.email, kind: 'person' }, message, thread_id || undefined).catch(precondition);
+        // Sem o ask_id, quem perguntou não tem como buscar a resposta: vai sempre.
+        return applyFieldMask({ agent_id, ask_id: r.ask_id, status: r.status, answer: r.answer ?? '' }, ctx.fieldMaskPaths, {
+            alwaysInclude: ['agent_id', 'ask_id', 'status'],
+        });
+    };
+    const getAnswer = async (ctx) => {
+        const askId = ctx.request.ask_id?.trim();
+        if (!askId)
+            throw new ProviderError(grpcStatus.INVALID_ARGUMENT, 'ask_id é obrigatório');
+        // Pergunta de outra pessoa responde igual a uma que não existe.
+        const row = await host.answer(askId, ctx.user.email);
+        if (!row)
+            throw new ProviderError(grpcStatus.NOT_FOUND, `pergunta "${askId}" não existe`);
+        return applyFieldMask({ ask_id: row.id, agent_id: row.agent_id, status: row.status, answer: row.answer ?? '', error: row.error ?? '' }, ctx.fieldMaskPaths, { alwaysInclude: ['ask_id', 'status'] });
+    };
+    // ── acao ────────────────────────────────────────────────────────────────────────
+    const explainActions = async (ctx) => {
+        agentOr404(host, ctx.request.agent_id);
+        // As conversas ficam de fora: guardam quem perguntou o quê, e só quem perguntou lê
+        // (pelo agent_answer).
+        const rows = await host.store.history(ctx.request.agent_id, {
+            excludeRoutine: CONVERSATION_ROUTINE,
+            ...(ctx.request.subject ? { subject: ctx.request.subject } : {}),
+            limit: Math.min(ctx.request.limit || limits.default, limits.max),
+        });
+        return applyFieldMask({ actions: rows.map(toAction) }, ctx.fieldMaskPaths);
+    };
+    const correctAction = async (ctx) => {
+        const id = actionId(ctx.request.action_id);
+        if (!ctx.request.note?.trim())
+            throw new ProviderError(grpcStatus.INVALID_ARGUMENT, 'note é obrigatório: diga o que estava errado e o certo');
+        const row = await host.correctAction(id, ctx.user.email, ctx.request.note).catch(precondition);
+        const level = await levelNow(host, host.agent(row.agent_id), row.routine);
+        return applyFieldMask({ action_id: String(row.id), status: row.status, routine_level: level }, ctx.fieldMaskPaths, { alwaysInclude: ['action_id'] });
+    };
+    // ── proposta ────────────────────────────────────────────────────────────────────
+    const listProposals = async (ctx) => {
+        agentOr404(host, ctx.request.agent_id);
+        return applyFieldMask({ proposals: (await host.pendingProposals(ctx.request.agent_id)).map(toAction) }, ctx.fieldMaskPaths);
+    };
+    const decideProposal = async (ctx) => {
+        const id = actionId(ctx.request.action_id);
+        const row = await host
+            .decideProposal(id, ctx.request.approve ? 'approved' : 'rejected', ctx.user.email, ctx.request.note || undefined)
+            .catch(precondition);
+        return applyFieldMask({ action_id: String(row.id), status: row.status, result_json: JSON.stringify(row.result ?? null) }, ctx.fieldMaskPaths, {
+            alwaysInclude: ['action_id'],
+        });
+    };
+    // ── controle ────────────────────────────────────────────────────────────────────
+    const setBlocked = async (ctx) => {
+        const { agent_id, blocked } = ctx.request;
+        agentOr404(host, agent_id);
+        const reason = ctx.request.reason?.trim() ?? '';
+        if (blocked) {
+            if (!reason)
+                throw new ProviderError(grpcStatus.INVALID_ARGUMENT, 'reason é obrigatório ao bloquear');
+            await host.kill(agent_id, ctx.user.email, reason);
+        }
+        else {
+            await host.unblock(agent_id, ctx.user.email, reason || undefined);
+        }
+        const now = Boolean(await host.store.killSwitch(agent_id));
+        return applyFieldMask({ agent_id, blocked: now }, ctx.fieldMaskPaths, { alwaysInclude: ['agent_id'] });
+    };
+    const capRoutine = async (ctx) => {
+        const { agent_id, routine } = ctx.request;
+        const a = agentOr404(host, agent_id);
+        routineOr404(a, routine);
+        const level = ctx.request.level?.trim() ?? '';
+        const reason = ctx.request.reason?.trim() ?? '';
+        if (!level) {
+            await host.restore(agent_id, routine, ctx.user.email, reason || undefined);
+        }
+        else {
+            if (!CAP_LEVELS.includes(level)) {
+                throw new ProviderError(grpcStatus.INVALID_ARGUMENT, `level "${level}" inválido: use ${CAP_LEVELS.join(', ')} ou vazio para restaurar`);
+            }
+            if (!reason)
+                throw new ProviderError(grpcStatus.INVALID_ARGUMENT, 'reason é obrigatório ao limitar o nível');
+            await host.demote(agent_id, routine, level, ctx.user.email, reason);
+        }
+        return applyFieldMask({ agent_id, routine, level: await levelNow(host, a, routine) }, ctx.fieldMaskPaths, {
+            alwaysInclude: ['agent_id', 'routine'],
+        });
+    };
+    return {
+        ListAgents: listAgents,
+        AskAgent: askAgent,
+        GetAnswer: getAnswer,
+        ExplainActions: explainActions,
+        ListProposals: listProposals,
+        DecideProposal: decideProposal,
+        CorrectAction: correctAction,
+        SetBlocked: setBlocked,
+        CapRoutine: capRoutine,
+    };
+}
+//# sourceMappingURL=connector.js.map

package/dist/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Ambiente do processo dos agentes, num lugar só e fail-fast: espelha o `loadProviderEnv()`
+ * do SDK de providers (e o reusa para o conector). Combinação inválida falha no boot, não
+ * na primeira rodada.
+ *
+ * Em produção (`NODE_ENV=production`) não há atalho: Postgres de verdade, eventos
+ * assinados, identidade própria de cada agente no Keycloak, chave do modelo e o conector
+ * com mTLS. Fora de produção, o que faltar cai no modo local (PGlite, eventos sem
+ * assinatura, sem conector, `wiring` de stub no lugar do gateway).
+ */
+import { type ProviderEnv } from '@t4h/mcp-provider-sdk';
+import type { LoadedAgent } from './manifest.js';
+export interface AgentEnv {
+    nodeEnv: string;
+    isProduction: boolean;
+    /** `postgres://…` em produção; fora dela também `pglite:<pasta>` ou ausente (em memória). */
+    databaseUrl?: string;
+    events: {
+        port: number;
+        /** Segredo HMAC por fonte. Vazio só fora de produção. */
+        secrets: Map<string, string>;
+        /** `POST /agents/:id/rounds`: fora de produção sim; em produção, nunca. */
+        allowManualRounds: boolean;
+        /** Espera entre o evento novo e a rodada que ele dispara (junta a rajada). */
+        wakeDebounceMs: number;
+    };
+    /** Ausente fora de produção sem `GATEWAY_URL`: quem sobe passa um `wiring` de stub. */
+    gateway?: {
+        url: string;
+        /** Só fora de produção: token fixo no lugar do client_credentials. */
+        devToken?: string;
+        keycloakIssuer?: string;
+        /** `AGENT_<ID>_CLIENT_SECRET` de cada agente, pelo id do agente. */
+        clientSecrets: Map<string, string>;
+    };
+    /** Ambiente do conector gRPC (`loadProviderEnv`). Ausente fora de produção sem passaporte configurado. */
+    connector?: ProviderEnv;
+    /**
+     * `PROVIDER_REQUIRE_CALL_BINDING=1`: o conector recusa passaporte sem o vínculo com a
+     * chamada (`requireCallBinding` do SDK de providers). Desligado por padrão, como no SDK.
+     */
+    requireCallBinding: boolean;
+    /** Quanto `agent_ask` espera a resposta antes de devolver `running`. */
+    askWaitMs: number;
+    debug: boolean;
+}
+/** Padrão do gateway para cortar a chamada ao provider (`PROVIDER_CALL_TIMEOUT_MS`). */
+export declare const GATEWAY_CALL_TIMEOUT_MS = 30000;
+export declare const DEFAULT_WAKE_DEBOUNCE_MS = 10000;
+/** `AGENT_<ID>_CLIENT_SECRET`: hífen vira `_`, tudo em maiúsculas. */
+export declare function agentSecretVar(agentId: string): string;
+/**
+ * Lê e valida o ambiente para estes agentes. Junta todos os problemas numa mensagem só
+ * (quem sobe o processo corrige tudo de uma vez) e lança.
+ */
+export declare function loadAgentEnv(agents: LoadedAgent[], env?: NodeJS.ProcessEnv): AgentEnv;