@t4h/agent-runtime 0.1.1 → 0.2.0

package/dist/env.js

@@ -0,0 +1,134 @@
+/**
+ * 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 { loadProviderEnv, optionalEnv } from '@t4h/mcp-provider-sdk';
+import { parseEventSecrets } from './signature.js';
+/** Padrão do gateway para cortar a chamada ao provider (`PROVIDER_CALL_TIMEOUT_MS`). */
+export const GATEWAY_CALL_TIMEOUT_MS = 30_000;
+export const DEFAULT_WAKE_DEBOUNCE_MS = 10_000;
+/** `AGENT_<ID>_CLIENT_SECRET`: hífen vira `_`, tudo em maiúsculas. */
+export function agentSecretVar(agentId) {
+    return `AGENT_${agentId.toUpperCase().replace(/-/g, '_')}_CLIENT_SECRET`;
+}
+function intEnv(name, fallback, env, problems, min = 0) {
+    const raw = optionalEnv(name, env);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min) {
+        problems.push(`${name}="${raw}" inválido: use um inteiro >= ${min}`);
+        return fallback;
+    }
+    return n;
+}
+/**
+ * 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 function loadAgentEnv(agents, env = process.env) {
+    const nodeEnv = env.NODE_ENV ?? 'development';
+    const isProduction = nodeEnv === 'production';
+    const problems = [];
+    // ── banco ───────────────────────────────────────────────────────────────────────
+    const databaseUrl = optionalEnv('DATABASE_URL', env);
+    const isPostgres = Boolean(databaseUrl && /^postgres(ql)?:\/\//.test(databaseUrl));
+    if (isProduction && !isPostgres)
+        problems.push('DATABASE_URL postgres://… é obrigatório em produção (PGlite só fora dela)');
+    else if (databaseUrl && !isPostgres && !databaseUrl.startsWith('pglite:'))
+        problems.push('DATABASE_URL: use postgres://… ou pglite:<pasta>');
+    // ── eventos ─────────────────────────────────────────────────────────────────────
+    let secrets = new Map();
+    try {
+        secrets = parseEventSecrets(optionalEnv('EVENTS_HMAC_SECRETS', env));
+    }
+    catch (e) {
+        problems.push(e.message);
+    }
+    // O nome antigo (um segredo só) seria ignorado em silêncio: melhor parar.
+    if (optionalEnv('EVENTS_HMAC_SECRET', env))
+        problems.push('EVENTS_HMAC_SECRET não existe mais: use EVENTS_HMAC_SECRETS="fonte=segredo,…"');
+    if (isProduction && !secrets.size)
+        problems.push('EVENTS_HMAC_SECRETS com ao menos uma fonte é obrigatório em produção');
+    const eventsPort = intEnv('EVENTS_PORT', 8080, env, problems);
+    const wakeDebounceMs = intEnv('EVENTS_WAKE_DEBOUNCE_MS', DEFAULT_WAKE_DEBOUNCE_MS, env, problems);
+    // ── conversa ────────────────────────────────────────────────────────────────────
+    const gatewayTimeout = intEnv('PROVIDER_CALL_TIMEOUT_MS', GATEWAY_CALL_TIMEOUT_MS, env, problems, 1);
+    const askWaitMs = intEnv('AGENTS_ASK_WAIT_MS', 20_000, env, problems, 1);
+    if (askWaitMs >= gatewayTimeout) {
+        problems.push(`AGENTS_ASK_WAIT_MS (${askWaitMs}) tem de ficar abaixo do timeout do gateway para o provider (${gatewayTimeout} ms)`);
+    }
+    // ── gateway (identidade de cada agente) ─────────────────────────────────────────
+    const gatewayUrl = optionalEnv('GATEWAY_URL', env);
+    const devToken = optionalEnv('GATEWAY_DEV_TOKEN', env);
+    const keycloakIssuer = optionalEnv('KEYCLOAK_ISSUER', env);
+    const clientSecrets = new Map();
+    const missingSecrets = [];
+    for (const a of agents) {
+        const name = agentSecretVar(a.manifest.id);
+        const value = optionalEnv(name, env);
+        if (value)
+            clientSecrets.set(a.manifest.id, value);
+        else
+            missingSecrets.push(name);
+    }
+    let gateway;
+    if (isProduction) {
+        if (!gatewayUrl)
+            problems.push('GATEWAY_URL é obrigatório em produção');
+        if (devToken)
+            problems.push('GATEWAY_DEV_TOKEN é proibido em produção: cada agente usa a própria identidade');
+        if (!keycloakIssuer)
+            problems.push('KEYCLOAK_ISSUER é obrigatório em produção');
+        if (missingSecrets.length)
+            problems.push(`falta o segredo do client de cada agente: ${missingSecrets.join(', ')}`);
+    }
+    else if (gatewayUrl && !devToken && (!keycloakIssuer || missingSecrets.length)) {
+        problems.push(`com GATEWAY_URL, defina GATEWAY_DEV_TOKEN ou KEYCLOAK_ISSUER e ${missingSecrets.join(', ') || 'os segredos dos agentes'}`);
+    }
+    if (gatewayUrl) {
+        gateway = {
+            url: gatewayUrl,
+            ...(devToken && !isProduction ? { devToken } : {}),
+            ...(keycloakIssuer ? { keycloakIssuer } : {}),
+            clientSecrets,
+        };
+    }
+    // ── modelo ──────────────────────────────────────────────────────────────────────
+    const hasModel = Boolean(optionalEnv('ANTHROPIC_API_KEY', env) || optionalEnv('CLAUDE_CODE_USE_BEDROCK', env) || optionalEnv('CLAUDE_CODE_USE_VERTEX', env));
+    if (isProduction && !hasModel)
+        problems.push('ANTHROPIC_API_KEY (ou CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX) é obrigatório em produção');
+    // ── conector gRPC ───────────────────────────────────────────────────────────────
+    // Em produção, sempre (e o SDK já exige mTLS). Fora dela, só se o passaporte estiver
+    // configurado; configurado pela metade, falha como em produção.
+    let connector;
+    if (isProduction || optionalEnv('GATEWAY_JWKS_URL', env) || optionalEnv('SERVICE_JWT_PUBLIC_KEY', env)) {
+        try {
+            connector = loadProviderEnv(env);
+        }
+        catch (e) {
+            problems.push(`conector: ${e.message}`);
+        }
+    }
+    if (problems.length) {
+        throw new Error(`ambiente inválido${isProduction ? ' (produção)' : ''}:\n  - ${problems.join('\n  - ')}`);
+    }
+    return {
+        nodeEnv,
+        isProduction,
+        ...(databaseUrl ? { databaseUrl } : {}),
+        events: { port: eventsPort, secrets, allowManualRounds: !isProduction, wakeDebounceMs },
+        ...(gateway ? { gateway } : {}),
+        ...(connector ? { connector } : {}),
+        requireCallBinding: optionalEnv('PROVIDER_REQUIRE_CALL_BINDING', env) === '1',
+        askWaitMs,
+        debug: optionalEnv('AGENT_DEBUG', env) === '1',
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

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

package/dist/evals.js

@@ -7,7 +7,7 @@
  *
  * Formato (agents/<id>/evals/*.yaml):
  *
- *   - name: chamado de custo vai para FinOps
+ *   - name: chamado de custo vai para o time financeiro
  *     events:
  *       - { type: exemplo.item.opened, subject: "item:42", payload: { titulo: "..." } }
  *     expect:

package/dist/host.d.ts

@@ -5,7 +5,7 @@ import { type IncomingEvent } from './inbox.js';
 import type { LoadedAgent } from './manifest.js';
 import { type Notifier } from './notifier.js';
 import { type RoundReport } from './round.js';
-import type { ActionRow, LongTermStore } from './store/long-term.js';
+import { type ActionRow, type ConversationRow, type ConversationStatus, type LongTermStore } from './store/long-term.js';
 /** Executa uma ação aprovada, sem o modelo. Em produção, o gateway com a identidade do agente. */
 export interface ToolExecutor {
     call(agent: LoadedAgent, qualifiedTool: string, input: Record<string, unknown>): Promise<{
@@ -14,6 +14,24 @@ export interface ToolExecutor {
     }>;
 }
 export declare function gatewayExecutor(gateway: GatewayClient): ToolExecutor;
+/**
+ * Recusa do host que não é regra do agente: o processo está desligando (`unavailable`),
+ * passou do teto de conversas simultâneas (`resource_exhausted`) ou o pedido veio
+ * malformado (`invalid_argument`). O conector traduz para o status gRPC equivalente.
+ */
+export declare class HostError extends Error {
+    readonly code: 'unavailable' | 'resource_exhausted' | 'invalid_argument';
+    constructor(code: 'unavailable' | 'resource_exhausted' | 'invalid_argument', message: string);
+}
+/** `thread_id` vem de quem chama: só letras, dígitos, `_` e `-` (um `ask_id` serve). */
+export declare const THREAD_ID_PATTERN: RegExp;
+/** Quantas trocas anteriores do mesmo fio entram no prompt da conversa. */
+export declare const THREAD_HISTORY_LIMIT = 5;
+/** Teto de conversas rodando ao mesmo tempo com um agente (somando as réplicas). */
+export declare const DEFAULT_ASK_LIMITS: {
+    perAsker: number;
+    perAgent: number;
+};
 export interface AgentHostOptions {
     agents: LoadedAgent[];
     store: LongTermStore;
@@ -24,53 +42,133 @@ export interface AgentHostOptions {
     notifier?: Notifier;
     pluginsDir?: string;
     now?: () => Date;
+    /**
+     * Quanto `ask()` espera a resposta antes de devolver `running` (padrão 20 s). Tem de
+     * ficar abaixo do timeout do gateway para a chamada ao provider (30 s por padrão).
+     */
+    askWaitMs?: number;
+    /**
+     * Teto de conversas `running` com um agente: por quem pergunta e no total. Acima dele,
+     * `ask()` recusa (`resource_exhausted`). Padrão: `DEFAULT_ASK_LIMITS`.
+     */
+    askLimits?: {
+        perAsker: number;
+        perAgent: number;
+    };
+    /**
+     * Evento novo acorda o agente depois deste tempo, juntando os que chegarem no meio.
+     * Ausente: só o cron acorda (testes, demo).
+     */
+    wakeDebounceMs?: number;
+    /** Relatório de cada rodada disparada pelo cron ou por evento. */
+    onRound?: (agentId: string, r: RoundReport) => void;
 }
 export interface Asker {
     email: string;
     kind: 'person' | 'agent';
 }
+export interface AskResult {
+    ask_id: string;
+    status: ConversationStatus;
+    answer?: string;
+    error?: string;
+}
+export interface ListenOptions {
+    /** Segredo HMAC por fonte (`parseEventSecrets`). Vazio: só aceita fora de produção. */
+    secrets?: ReadonlyMap<string, string>;
+    /** `POST /agents/:id/rounds`. Padrão: fora de produção; em produção, nunca. */
+    allowManualRounds?: boolean;
+    /** Padrão: NODE_ENV=production. */
+    production?: boolean;
+}
+export declare const DEFAULT_ASK_WAIT_MS = 20000;
 export declare class AgentHost {
     private readonly o;
     readonly agents: Map<string, LoadedAgent>;
     private readonly skills;
     private readonly crons;
+    private readonly wakeTimers;
+    /** Conversas e rodadas em andamento: o `stop()` espera um pouco por elas. */
+    private readonly inflight;
     private readonly notifier;
+    private onRound;
     private http?;
+    private stopped;
     constructor(o: AgentHostOptions);
     get store(): LongTermStore;
     agent(id: string): LoadedAgent;
     private skillsOf;
-    enqueue(agentId: string, ev: IncomingEvent): Promise<{
+    /** `source` é a fonte do webhook: o id do evento fica `<fonte>:<id>` (dedup por fonte). */
+    enqueue(agentId: string, ev: IncomingEvent, source?: string): Promise<{
         itemId: number | null;
         duplicate: boolean;
     }>;
+    /**
+     * Agenda uma rodada para logo depois de um evento novo. Os eventos que chegam enquanto
+     * a rodada está agendada entram nela (não reinicia a espera, para uma rajada não adiar a
+     * rodada para sempre). O lock continua garantindo uma rodada por vez; se outra réplica
+     * estiver rodando, tenta de novo depois. O cron segue como rede de segurança.
+     */
+    private wake;
+    /** Acompanha o trabalho em andamento para o `stop()` esperar por ele antes do banco fechar. */
+    private track;
     runRound(agentId: string, hops?: number): Promise<RoundReport>;
     /**
-     * Conversa direta (pelo Claude, via conector do círculo, ou de outro agente). Corre à
-     * parte da fila. Só lê, com o acesso do próprio agente: ele é um colaborador virtual, e
-     * quem pode conversar com ele é decidido pelo grant do conector `agents_<círculo>`.
+     * Pergunta pelo conector: grava a conversa, roda em segundo plano e espera até
+     * `askWaitMs`. Se a resposta não vier a tempo, devolve `running`, e quem perguntou busca
+     * depois com `answer()`. O estado fica no Postgres: qualquer réplica responde.
+     */
+    ask(agentId: string, asker: Asker, message: string, threadId?: string): Promise<AskResult>;
+    /**
+     * A resposta de um `ask()`. Só quem perguntou lê: para os outros, a conversa não existe.
+     * `running` há mais tempo que uma rodada inteira (mais um minuto) virou erro: a réplica
+     * que respondia caiu.
+     */
+    answer(askId: string, askerEmail: string): Promise<ConversationRow | undefined>;
+    /**
+     * Conversa direta, à parte da fila. Síncrona: o conector usa `ask()`, que roda esta em
+     * segundo plano; aqui chega direto a conversa entre agentes (handoff). Só lê, com o
+     * acesso do próprio agente: ele é um colaborador virtual, e quem pode conversar com ele
+     * é decidido pelo grant do conector `agents_<círculo>`. `previous`: trocas anteriores do
+     * mesmo fio (o `ask()` só passa as de quem pergunta).
      */
-    converse(agentId: string, asker: Asker, message: string, conversationId: string, hops?: number): Promise<{
+    converse(agentId: string, asker: Asker, message: string, conversationId: string, hops?: number, previous?: Array<{
+        message: string;
+        answer: string | null;
+    }>): Promise<{
         answer: string;
         costUsd: number;
     }>;
     pendingProposals(agentId: string): Promise<ActionRow[]>;
-    /** Uma pessoa aprova ou recusa a proposta. Aprovada, roda pelo gateway com a identidade do agente. */
+    /**
+     * Uma pessoa aprova ou recusa a proposta. Aprovada, roda pelo gateway com a identidade do
+     * agente. Com o agente bloqueado, recusar vale; aprovar não (nada roda no nome dele).
+     */
     decideProposal(actionId: number, decision: 'approved' | 'rejected', by: string, note?: string): Promise<ActionRow>;
     /** Uma pessoa corrige o que ele fez. Vira aprendizado no próximo prompt e conta no disjuntor. */
     correctAction(actionId: number, by: string, note: string): Promise<ActionRow>;
+    private routineOf;
     /** Incidente: a rotina desce na hora, por decisão de pessoa. */
     demote(agentId: string, routine: string, to: 'shadow' | 'copilot' | 'agent', by: string, reason: string): Promise<void>;
+    /** Tira o teto: volta a valer o nível do manifesto (depois de tratar a causa). */
+    restore(agentId: string, routine: string, by: string, reason?: string): Promise<void>;
     /** Bloqueio de emergência: para tudo na hora, sem deploy. */
     kill(agentId: string, by: string, reason: string): Promise<void>;
+    /** Fim do bloqueio de emergência. Sem bloqueio, não faz nada (nem avisa). */
+    unblock(agentId: string, by: string, reason?: string): Promise<void>;
     /** Liga o despertar de cada agente e a agenda das rotinas. */
     startSchedules(onRound?: (agentId: string, r: RoundReport) => void): void;
     /**
-     * Entrada de eventos por webhook: POST /agents/:id/events, assinado com HMAC-SHA256
-     * (`x-t4h-signature: sha256=<hex>`). GET /healthz para o Container App.
+     * Entrada de eventos por webhook: POST /agents/:id/events, assinado por fonte
+     * (`x-t4h-source` + `x-t4h-signature`, ver signature.ts). POST /agents/:id/rounds acorda
+     * o agente na hora, só fora de produção. GET /healthz para o Container App.
+     */
+    listen(port: number, opts?: ListenOptions): Promise<number>;
+    /**
+     * Para a entrada (webhook, cron, despertares, novas perguntas) e espera até `graceMs`
+     * pelas conversas e rodadas em andamento. A conversa que não terminar fica `running` e
+     * vira erro no próximo `answer()`; o item de uma rodada interrompida fica `working` e
+     * volta para a fila quando o prazo do lock vencer (`leaseBatch`).
      */
-    listen(port: number, hmacSecret: string | undefined): Promise<number>;
-    stop(): Promise<void>;
+    stop(graceMs?: number): Promise<void>;
 }
-/** Sem segredo configurado, só aceita fora de produção. */
-export declare function verifySignature(raw: string, header: string | string[] | undefined, secret: string | undefined): boolean;