hobots 1.0.0 → 1.1.0

package/docs/api-reference.md

@@ -4,10 +4,10 @@
 
 | Import | Conteúdo |
 | --- | --- |
-| `hobots` | Monitor: funções, `Client`, `Scope`, `Transaction`, `Span`, `parseDsn`, tipos. |
-| `hobots/protocol` | Tipos do wire format do Monitor. |
-| `hobots/manager` | Manager: `init`/`register`/`start`/`stop`, `ManagerAgent`, `ManagerApi`, tipos. |
-| `hobots/manager/protocol` | Tipos do wire format do Manager. |
+| `hobots` | Tudo: `init` único, funções do Monitor, `register`/`start`/`stop` do Manager, `close`, classes (`Client`, `Scope`, `Transaction`, `Span`, `ManagerAgent`, `ManagerApi`), `parseDsn` e tipos. |
+| `hobots/protocol` | Tipos do wire format (Monitor e Manager). |
+
+`hobots/manager/protocol` segue existindo como alias transitório dos tipos do wire format do Manager.
 
 ---
 
@@ -29,9 +29,19 @@
 | `checkIn` | `checkIn(options: CheckInOptions): string \| undefined` | check_in_id |
 | `withMonitor` | `withMonitor<T>(slug: string, fn: () => T \| Promise<T>, options?: WithMonitorOptions): Promise<T>` | retorno de `fn` |
 | `flush` | `flush(timeoutMs?: number): Promise<boolean>` | enviou tudo? |
-| `close` | `close(timeoutMs?: number): Promise<boolean>` | flush + para heartbeat/transport |
+| `close` | `close(timeoutMs?: number): Promise<boolean>` | para o Manager (aguarda runs) + heartbeat + flush final do transport |
+
+Classes exportadas: `Client`, `Scope`, `Transaction`, `Span`. Função `parseDsn(dsn): ParsedDsn` — parseia a DSN única do projeto:
 
-Classes exportadas: `Client`, `Scope`, `Transaction`, `Span`. Função `parseDsn(dsn): ParsedDsn`.
+```ts
+interface ParsedDsn {
+  key: string;            // chave secreta do projeto (vai no Authorization: Bearer, nunca na URL)
+  projectSlug: string;    // slug do projeto (informativo — a identidade real vem da chave)
+  origin: string;
+  ingestEndpoint: string; // <origin>/api/ingest
+  managerBaseUrl: string; // <origin>/api/manager
+}
+```
 
 ### Métodos de `Transaction` / `Span`
 
@@ -43,14 +53,17 @@ Classes exportadas: `Client`, `Scope`, `Transaction`, `Span`. Função `parseDsn
 
 ## Manager — funções
 
+Habilitado com `manager: true` (ou `ManagerOptions`) no `init()` único. Todas exportadas do import raiz `hobots`:
+
 | Função | Assinatura |
 | --- | --- |
-| `init` | `init(options: ManagerInitOptions): void` |
 | `register` | `register<P, R>(task: string, handler: ManagerTaskHandler<P, R>): void` |
-| `start` | `start(): void` |
-| `stop` | `stop(timeoutMs?: number): Promise<boolean>` |
+| `start` | `start(): void` — lança se o `init()` não configurou `manager` ou sem tasks registradas |
+| `stop` | `stop(timeoutMs?: number): Promise<boolean>` — para só o Manager; a telemetria continua |
 
-Classes/erros exportados: `ManagerAgent`, `ManagerApi`, `ManagerApiError`. Função `parseManagerDsn(dsn): ParsedManagerDsn`.
+Classes/erros exportados: `ManagerAgent`, `ManagerApi`, `ManagerApiError`.
+
+No poll, o agente se identifica com `ManagerAgentInfo` (`hobots/protocol`): o campo `instance_id` (o `instanceId` do `init()`) é a identidade canônica do agente — a mesma do heartbeat do Monitor, então os dois canais convergem em um agente no painel.
 
 ---
 
@@ -60,16 +73,17 @@ Classes/erros exportados: `ManagerAgent`, `ManagerApi`, `ManagerApiError`. Funç
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `dsn` | `string` | — | **obrigatório**; `<origin>/<publicKey>/<projectId>` |
+| `dsn` | `string` | — | **obrigatório**; a DSN única do projeto: `https://<secretKey>@host/<projectSlug>` |
 | `environment` | `string` | `'production'` | ambiente lógico |
 | `release` | `string` | — | versão do programa, ex. `robo-nfe@1.4.2` |
-| `serverName` | `string` | hostname | identifica a máquina; também vira `instanceId` do heartbeat |
+| `instanceId` | `string` | **obrigatório** | identidade única da instância; heartbeat do Monitor e agente do Manager convergem nela |
 | `tags` | `Record<string,string>` | — | tags aplicadas a todos os eventos |
 | `sampleRate` | `number` | `1` | amostragem de erros (0..1) |
 | `tracesSampleRate` | `number` | `1` | amostragem de transactions (0..1) |
 | `maxBreadcrumbs` | `number` | `100` | tamanho do buffer de breadcrumbs |
 | `captureUnhandled` | `boolean` | `true` | handlers globais de erro |
 | `heartbeat` | `boolean \| HeartbeatOptions` | `false` | heartbeat periódico |
+| `manager` | `boolean \| ManagerOptions` | `false` | habilita o agente Manager (`true` usa defaults) |
 | `beforeSend` | `(event) => event \| null` | — | edita/descarta evento (retorne `null` para descartar) |
 | `debug` | `boolean` | `false` | loga atividade do SDK |
 | `flushIntervalMs` | `number` | `2000` | intervalo do flush automático do transport |
@@ -80,8 +94,7 @@ Classes/erros exportados: `ManagerAgent`, `ManagerApi`, `ManagerApiError`. Funç
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
 | `intervalMs` | `number` | `30000` | intervalo entre batimentos |
-| `instanceId` | `string` | `serverName`/`HOSTNAME`/id aleatório | identificador estável da instância |
-| `name` | `string` | — | nome amigável no dashboard |
+| `name` | `string` | o `instanceId` | nome amigável no dashboard |
 | `metadata` | `Record<string,unknown>` | — | metadados anexados ao batimento |
 
 ### CaptureHint
@@ -113,23 +126,23 @@ Classes/erros exportados: `ManagerAgent`, `ManagerApi`, `ManagerApiError`. Funç
 | `schedule` | `string` | expressão cron (upsert do monitor) |
 | `timezone` | `string` | fuso do `schedule` |
 
-### ManagerInitOptions
+### ManagerOptions
+
+Valor do campo `manager` do `InitOptions`. A DSN, o `debug` e a identidade (`instanceId`) vêm do `init()`.
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `dsn` | `string` | — | **obrigatório**, com a **manager key** (não a chave de ingestão) |
 | `pollIntervalMs` | `number` | `5000` | intervalo entre polls sem trabalho (mínimo `1000`) |
 | `concurrency` | `number` | `1` | runs simultâneas (clamp 1..5) |
-| `agentName` | `string` | hostname | nome exibido no dashboard |
 | `taskTimeoutMs` | `number` | — | timeout client-side por run (não mata o handler; servidor é o backstop) |
 | `logFlushIntervalMs` | `number` | `2000` | intervalo do envio incremental de logs |
-| `debug` | `boolean` | `false` | loga atividade do agente |
 
 ### ManagerTaskHandler / RunContext
 
 ```ts
-type ManagerTaskHandler<P = Record<string, unknown>, R = unknown> =
-  (params: P, ctx: RunContext) => R | Promise<R>;
+// o retorno do handler é ignorado — nada além de status/logs/erro é enviado ao servidor
+type ManagerTaskHandler<P = Record<string, unknown>> =
+  (params: P, ctx: RunContext) => void | Promise<void>;
 
 interface RunContext {
   runId: string;

package/docs/getting-started.md

@@ -10,37 +10,39 @@ Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). O Moni
 
 ## O DSN
 
-Toda credencial do SDK é um **DSN** no formato `<protocolo>://<key>@<host>[:porta]/<projeto>`. A `key` vai embutida na URL e o `host` aponta para o app da Hobots.
+Cada projeto tem **uma única DSN** — a mesma credencial autentica o Monitor **e** o Manager:
 
-- **Monitor** usa a **public key** (chave de ingestão) e o `projectId`. Você a copia da página do projeto em `/monitor` — o snippet de integração já vem pronto.
-- **Manager** usa a **manager key** (chave secreta do agente, criada em `/manager/agents`) e o `projectSlug`. **Não** é a chave de ingestão.
+```
+<protocolo>://<secretKey>@<host>[:porta]/<projectSlug>
+```
+
+A `secretKey` (64 hex) é **secreta**: ela vai embutida na DSN só por conveniência — nas requisições viaja sempre no header `Authorization: Bearer`, nunca na URL. O `projectSlug` no path é informativo; a identidade do projeto vem da chave. Copie a DSN pronta no app, em **Configurações → Agentes** — os snippets de integração já vêm prontos.
 
 ```
-Monitor:  http://<publicKey>@localhost:3002/<projectId>
-Manager:  http://<managerKey>@localhost:3002/<projectSlug>
+http://<secretKey>@localhost:3002/<projectSlug>
 ```
 
-Veja [Protocolo & transporte](./protocol.md) para os endpoints que cada DSN deriva.
+Veja [Protocolo & transporte](./protocol.md) para os endpoints que a DSN deriva.
 
-## Monitor vs Manager — qual usar
+## Monitor e Manager — qual usar
 
-As duas capabilities são independentes e você usa **uma, outra ou as duas**:
+As duas capabilities vivem no mesmo `init()` e você usa **uma, outra ou as duas**:
 
-- Quer só saber se o robô quebrou, quanto demora e se está vivo? → **Monitor**.
-- Quer disparar o robô sob demanda a partir de um formulário no app? → **Manager**.
-- Ambos? Inicialize os dois no mesmo processo (credenciais separadas). É o cenário do
-  [`demo.ts`](../../../apps/webapp/scripts/demo.ts).
+- Quer só saber se o robô quebrou, quanto demora e se está vivo? → `init({ dsn, heartbeat: true })`.
+- Quer disparar o robô sob demanda a partir de um formulário no app? → `init({ dsn, manager: true })` + `register()` + `start()`.
+- Ambos? Passe `heartbeat` e `manager` no **mesmo `init()`**. É o cenário do
+  [`full.ts`](../../hobots-sdk-demos/src/full.ts) nos demos do SDK.
 
-## Primeiro `init` (Monitor)
+## O `init` único
 
 ```js
-import * as Monitor from 'hobots';
+import * as Hobots from 'hobots';
 
-Monitor.init({
-  dsn: 'http://<publicKey>@localhost:3002/<projectId>',
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
   environment: 'production',
   release: 'robo-nfe@1.4.2',
-  serverName: 'vm-cliente-01',
+  instanceId: 'vm-cliente-01', // identidade única: heartbeat + agente Manager
   heartbeat: true, // "estou vivo" a cada 30s
 });
 
@@ -49,40 +51,53 @@ Monitor.init({
 try {
   await processarNota(nota);
 } catch (error) {
-  Monitor.captureException(error, { tags: { cliente: 'acme' } });
+  Hobots.captureException(error, { tags: { cliente: 'acme' } });
   throw error;
 }
 ```
 
-Chame `Monitor.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Monitor](./monitor.md).
+Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Monitor](./monitor.md).
 
 ## Primeiro agente (Manager)
 
+Habilite a execução sob demanda com o campo `manager` no mesmo `init()`:
+
 ```js
-import * as Manager from 'hobots/manager';
+import * as Hobots from 'hobots';
 
-Manager.init({ dsn: 'http://<managerKey>@localhost:3002/<projectSlug>', agentName: 'VM Cliente 01' });
-Manager.register('processar-nfe', async (params, ctx) => {
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
+  instanceId: 'vm-cliente-01',
+  manager: true, // ou { pollIntervalMs, concurrency, ... }
+});
+
+Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log('info', `processando lote ${params.lote}…`);
   return { processadas: 12 };
 });
-Manager.start(); // mantém o processo vivo até stop()
+Hobots.start(); // mantém o processo vivo até stop()/close()
 ```
 
+> O `instanceId` é a identidade dos **dois** canais (heartbeat do Monitor e agente do Manager) — o robô aparece como **um agente só** no painel, sem configuração extra.
+
 Detalhes (cancelamento, concorrência, idempotência) em [Manager](./manager.md).
 
 ## Encerramento
 
-O **Monitor** não segura o processo (timers `unref`'d), mas faça o flush final para não perder eventos em buffer:
+`close()` encerra tudo na ordem certa: para o Manager (aguardando a run atual), o heartbeat e faz o flush final do transport.
+
+Sem Manager iniciado, o SDK não segura o processo (timers `unref`'d), mas faça o flush final para não perder eventos em buffer:
 
 ```js
-await Monitor.close(2000);
+await Hobots.close(2000);
 ```
 
-O **Manager** segura o processo por design. Encerre de forma graciosa aguardando a run atual:
+Com o Manager, `start()` segura o processo por design. Encerre de forma graciosa aguardando a run atual:
 
 ```js
 process.on('SIGINT', () => {
-  void Manager.stop(15_000).then(() => process.exit(0));
+  void Hobots.close(15_000).then(() => process.exit(0));
 });
 ```
+
+Para parar de aceitar execuções **sem** derrubar a telemetria, use `Hobots.stop(timeoutMs?)`.

package/docs/manager.md

@@ -1,43 +1,46 @@
 # Manager
 
-Capability de **execução remota sob demanda**. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status, logs incrementais e resultado. Entry próprio:
-
-```js
-import * as Manager from 'hobots/manager';
-```
-
-Independente do Monitor: credencial própria (**manager key**), singletons próprios e nenhum handler global instalado. Pode conviver com `Monitor.init()` no mesmo processo.
+Capability de **execução remota sob demanda**, habilitada com `manager: true` (ou opções) no `init()` único. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais. Usa a mesma DSN, o mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
 
 ## Ciclo de vida
 
 ```js
-Manager.init({ dsn: 'http://<managerKey>@localhost:3002/<projectSlug>', agentName: 'VM Cliente 01' });
+import * as Hobots from 'hobots';
 
-Manager.register('processar-nfe', async (params, ctx) => {
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
+  instanceId: 'vm-cliente-01',
+  manager: true, // ou { pollIntervalMs, concurrency, taskTimeoutMs, logFlushIntervalMs }
+});
+
+Hobots.register('processar-nfe', async (params, ctx) => {
   ctx.log('info', `processando lote ${params.lote}…`);
   if (ctx.signal.aborted) return; // cancelamento cooperativo
-  return { processadas: 12 }; // vira o resultado da execução no app
+  ctx.log('info', '12 notas processadas');
 });
 
-Manager.start(); // começa o polling e MANTÉM O PROCESSO VIVO
+Hobots.start(); // começa o polling e MANTÉM O PROCESSO VIVO
 
 process.on('SIGINT', () => {
-  void Manager.stop(15_000).then(() => process.exit(0));
+  void Hobots.close(15_000).then(() => process.exit(0));
 });
 ```
 
-- `init(options)` — cria o agente (singleton). Chamar de novo para o anterior e substitui.
-- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app. Registre **antes** de `start()`.
-- `start()` — começa o polling. Lança se `init()` não foi chamado ou se nenhuma task foi registrada.
-- `stop(timeoutMs?)` — para o polling e aguarda as runs ativas (default 30s). Retorna `false` se estourou o timeout.
+- `init({ manager })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (os handlers registrados são preservados).
+- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app. Registre **antes** de `start()`. Pode ser chamado antes do `init()`; se o `init()` não habilitou o Manager, o SDK avisa no console.
+- `start()` — começa o polling. Lança se o `init()` não configurou `manager` ou se nenhuma task foi registrada.
+- `stop(timeoutMs?)` — para **só o Manager**: encerra o polling e aguarda as runs ativas (default 30s); a telemetria continua. Retorna `false` se estourou o timeout.
+- `close(timeoutMs?)` — encerra **tudo**: agente (aguardando runs em voo) → heartbeat → flush final.
 
-> **Atenção:** ao contrário do Monitor, `Manager.start()` **segura o processo vivo** aguardando trabalho até `Manager.stop()` — o agente é a razão do processo existir.
+O `instanceId` (obrigatório) é a identidade do agente no painel — o poll o envia como `agent.instance_id`, a **mesma identidade** do heartbeat do Monitor. Com o `init()` único, os dois canais convergem em **um agente** automaticamente.
+
+> **Atenção:** ao contrário da telemetria, `start()` **segura o processo vivo** aguardando trabalho até `stop()`/`close()` — o agente é a razão do processo existir.
 
 ## O handler e o `RunContext`
 
 ```ts
-type ManagerTaskHandler<P = Record<string, unknown>, R = unknown> =
-  (params: P, ctx: RunContext) => R | Promise<R>;
+type ManagerTaskHandler<P = Record<string, unknown>> =
+  (params: P, ctx: RunContext) => void | Promise<void>;
 
 interface RunContext {
   runId: string;
@@ -50,21 +53,23 @@ interface RunContext {
 - **`params`** — os dados do formulário configurado no app (o JSON validado).
 - **`ctx.log(level, message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na run em tempo quase real.
 - **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**. Cancelamento é cooperativo (veja abaixo).
-- **Retorno** — vira o resultado da execução exibido no app (serializado em JSON, cap de ~100KB; resultados maiores/circulares são descartados com um marcador `__truncated`).
+- **Retorno** — **ignorado**. O SDK não captura nem envia o valor retornado pelo handler ao servidor — resultados de execução podem conter dados sensíveis e não são coletados.
 - **Erro lançado** — a run é reportada como `failed` com tipo/mensagem/stack (mensagem cap 10k, stack 20k).
 
-Você pode tipar params e retorno: `Manager.register<{ lote: number }, { processadas: number }>(...)`.
+Você pode tipar os params: `Hobots.register<{ lote: number }>(...)`.
+
+> **Dados sensíveis:** o que você escreve em `ctx.log()` e as mensagens/stack de erros lançados **são enviados ao servidor** e ficam visíveis na execução no app. Não inclua senhas, tokens, documentos, dados pessoais ou qualquer informação sensível em logs e mensagens de erro.
 
 ## Cancelamento cooperativo
 
 Uma run cancelada no app **não mata** o seu handler — o SDK não interrompe código em execução. Ele apenas dispara `ctx.signal`. **Verifique `ctx.signal.aborted`** em loops longos e pontos de parada:
 
 ```js
-Manager.register('processar-nfe', async (params, ctx) => {
+Hobots.register('processar-nfe', async (params, ctx) => {
   for (const nota of params.notas) {
     if (ctx.signal.aborted) {
       ctx.log('warning', 'cancelamento detectado — parando');
-      return { canceladas: true };
+      return;
     }
     await processar(nota);
   }
@@ -73,7 +78,7 @@ Manager.register('processar-nfe', async (params, ctx) => {
 
 ## Idempotência (at-least-once)
 
-A entrega é **at-least-once**: se o agente morrer logo após capturar uma run (antes de reportar o resultado), ela é re-entregue quando o agente voltar. Escreva handlers **idempotentes** — processar a mesma run duas vezes não pode causar efeito duplicado (use uma chave de deduplicação sua, como o número da nota).
+A entrega é **at-least-once**: se o agente morrer logo após capturar uma run (antes de reportar a conclusão), ela é re-entregue quando o agente voltar. Escreva handlers **idempotentes** — processar a mesma run duas vezes não pode causar efeito duplicado (use uma chave de deduplicação sua, como o número da nota).
 
 ## Concorrência
 
@@ -83,7 +88,7 @@ A entrega é **at-least-once**: se o agente morrer logo após capturar uma run (
 
 `taskTimeoutMs` é um timeout **client-side**. No estouro o SDK **não mata** o handler — ele dispara `ctx.signal`, libera o slot de concorrência e reporta a run como falha (`TaskTimeout`). O handler pode continuar rodando em background; respeite o `signal` para parar de verdade. Sem `taskTimeoutMs`, o backstop é o servidor.
 
-Todas as opções em [Referência de API → ManagerInitOptions](./api-reference.md#managerinitoptions).
+Todas as opções em [Referência de API → ManagerOptions](./api-reference.md#manageroptions).
 
 ## Como o claim funciona (resumo)
 

package/docs/monitor.md

@@ -1,21 +1,21 @@
 # Monitor
 
-Capability de telemetria: erros, performance, crons e uptime. Import raiz:
+Capability de telemetria: erros, performance, crons e uptime. Sempre ativa no `init()` único:
 
 ```js
-import * as Monitor from 'hobots';
+import * as Hobots from 'hobots';
 ```
 
-Todas as funções abaixo são no-op seguros se `Monitor.init()` não foi chamado (com aviso no console). Assinaturas completas em [Referência de API](./api-reference.md).
+Todas as funções abaixo são no-op seguros se `Hobots.init()` não foi chamado (com aviso no console). Assinaturas completas em [Referência de API](./api-reference.md).
 
 ## init
 
 ```js
-Monitor.init({
-  dsn: 'http://<publicKey>@localhost:3002/<projectId>',
+Hobots.init({
+  dsn: 'http://<secretKey>@localhost:3002/<projectSlug>',
   environment: 'production',
   release: 'robo-nfe@1.4.2',
-  serverName: 'vm-cliente-01',
+  instanceId: 'vm-cliente-01',
   tags: { squad: 'automacoes' },
   heartbeat: true,
 });
@@ -27,14 +27,14 @@ Cria o cliente, instala handlers globais de erro (a menos que `captureUnhandled:
 
 ```js
 // exceções
-Monitor.captureException(error, {
+Hobots.captureException(error, {
   tags: { cliente: 'acme' },
   level: 'error',
   fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
 });
 
 // mensagens sem exceção
-Monitor.captureMessage('Lote processado com sucesso', 'info');
+Hobots.captureMessage('Lote processado com sucesso', 'info');
 ```
 
 Ambas retornam o `event_id` (ou `undefined` se não inicializado). O segundo argumento é um [`CaptureHint`](./api-reference.md#capturehint) (`level`, `tags`, `extra`, `fingerprint`).
@@ -46,7 +46,7 @@ Erros **não tratados** (`uncaughtException` / `unhandledRejection`) são captur
 Trilha do que aconteceu antes do erro; enviada junto do próximo evento.
 
 ```js
-Monitor.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
+Hobots.addBreadcrumb({ category: 'nfe', message: 'Baixou XML da nota 123', level: 'info' });
 ```
 
 O buffer é limitado por `maxBreadcrumbs` (default 100, mais antigos descartados).
@@ -56,26 +56,26 @@ O buffer é limitado por `maxBreadcrumbs` (default 100, mais antigos descartados
 Dados anexados a **todos** os eventos seguintes:
 
 ```js
-Monitor.setTag('regiao', 'nordeste');
-Monitor.setTags({ squad: 'automacoes', cliente: 'acme' });
-Monitor.setUser({ id: 'op-42', email: 'op@acme.com' });
-Monitor.setContext('vm', { cpu: 4, ram: '8GB' });
-Monitor.setExtra('ultimoLote', 128);
+Hobots.setTag('regiao', 'nordeste');
+Hobots.setTags({ squad: 'automacoes', cliente: 'acme' });
+Hobots.setUser({ id: 'op-42', email: 'op@acme.com' });
+Hobots.setContext('vm', { cpu: 4, ram: '8GB' });
+Hobots.setExtra('ultimoLote', 128);
 ```
 
 Para um escopo **isolado** (sem vazar para o global), use `withScope`:
 
 ```js
-Monitor.withScope((scope) => {
+Hobots.withScope((scope) => {
   scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
-  Monitor.captureMessage('Reprocessando lote 128');
+  Hobots.captureMessage('Reprocessando lote 128');
 });
 ```
 
 ## Performance: transactions e spans
 
 ```js
-const tx = Monitor.startTransaction('processar-lote', 'rpa.job');
+const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
 
 const span = tx.startChild('http.client', 'GET /api/notas');
 await api.buscarNotas();
@@ -98,7 +98,7 @@ tx.finish(); // só aqui a transaction é enviada (respeitando tracesSampleRate)
 Monitora jobs agendados: um check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
 
 ```js
-await Monitor.withMonitor(
+await Hobots.withMonitor(
   'sync-notas',
   () => executarSync(),
   { schedule: '0 */2 * * *', timezone: 'America/Fortaleza' }
@@ -108,9 +108,9 @@ await Monitor.withMonitor(
 O `schedule` (expressão cron) faz o servidor **criar/atualizar o monitor automaticamente** (upsert) e habilita a detecção de **execução perdida**. Para controle manual, use `checkIn` diretamente (veja [Referência](./api-reference.md#checkinoptions)):
 
 ```js
-const id = Monitor.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
+const id = Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
 // … trabalho …
-Monitor.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
+Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
 ```
 
 ## Heartbeat (uptime)
@@ -118,19 +118,21 @@ Monitor.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durati
 Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os batimentos param.
 
 ```js
-Monitor.init({
+Hobots.init({
   dsn,
   heartbeat: { intervalMs: 30_000, name: 'Robô NFe — VM 01' },
 });
 ```
 
-`heartbeat: true` usa os defaults. O `instanceId` default é o `serverName` / `HOSTNAME` / um id aleatório por processo. Campos em [HeartbeatOptions](./api-reference.md#heartbeatoptions).
+`heartbeat: true` usa os defaults. A identidade é o `instanceId` do `init()`. Campos em [HeartbeatOptions](./api-reference.md#heartbeatoptions).
+
+Essa identidade é a mesma que o Manager envia no poll (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** em Monitor → Agentes automaticamente.
 
 ## Flush e close
 
 ```js
-await Monitor.flush(2000); // envia o que está em buffer, mantém o SDK vivo
-await Monitor.close(2000); // flush final + para o heartbeat + fecha o transport
+await Hobots.flush(2000); // envia o que está em buffer, mantém o SDK vivo
+await Hobots.close(2000); // para o Manager (se ativo) + heartbeat + flush final do transport
 ```
 
-Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d, então ele **não** segura o processo vivo sozinho.
+Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d, então a telemetria **não** segura o processo vivo sozinha (só o `start()` do Manager segura).

package/docs/protocol.md

@@ -4,19 +4,26 @@ O SDK é um **cliente HTTP puro**, sem dependências de runtime: ele só fala co
 
 Os arquivos `src/protocol.ts` e `src/manager/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift.
 
-## DSNs e endpoints derivados
+## A DSN e os endpoints derivados
 
-| Capability | DSN | Endpoint | Autenticação |
-| --- | --- | --- | --- |
-| Monitor | `<proto>://<publicKey>@host/<projectId>` | `<origin>/api/ingest/<publicKey>` | public key **na URL** (sem header) |
-| Manager | `<proto>://<managerKey>@host/<projectSlug>` | `<origin>/api/manager` | `Authorization: Bearer <managerKey>` (**nunca** na URL) |
+Cada projeto tem **uma única DSN secreta**, a mesma para as duas capabilities:
 
-- Monitor: `parseDsn(dsn) → { publicKey, projectId, endpoint }`.
-- Manager: `parseManagerDsn(dsn) → { key, projectSlug, origin, baseUrl }`.
+```
+<proto>://<secretKey>@host[:porta]/<projectSlug>
+```
+
+| Canal | Endpoint | Autenticação |
+| --- | --- | --- |
+| Monitor (ingestão) | `POST <origin>/api/ingest` | `Authorization: Bearer <secretKey>` |
+| Manager (execução) | `<origin>/api/manager/*` | `Authorization: Bearer <secretKey>` |
+
+`parseDsn(dsn) → { key, projectSlug, origin, ingestEndpoint, managerBaseUrl }` (em `src/dsn.ts`). A chave é **secreta** (64 hex) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição. O `projectSlug` do path é informativo: a identidade real do projeto vem da chave.
+
+> A DSN antiga do Monitor (public key na URL, `POST /api/ingest/<key>`) foi descontinuada — o endpoint responde **410** e o transport descarta sem retry. Copie a DSN nova em **Configurações → Agentes** no app.
 
 ## Monitor — ingestão
 
-Endpoint único `POST /api/ingest/<publicKey>` recebe **envelopes** JSON. O transport mantém uma fila em memória, agrupa itens em envelopes e faz POST via `fetch`.
+Endpoint fixo `POST /api/ingest` recebe **envelopes** JSON autenticados por Bearer. O transport mantém uma fila em memória, agrupa itens em envelopes e faz POST via `fetch`.
 
 ```jsonc
 {
@@ -37,7 +44,7 @@ Tipos de item: `event`, `transaction`, `check_in`, `heartbeat` (definidos em `ho
 
 ## Manager — polling e reporte
 
-Dois endpoints sob `<origin>/api/manager`, ambos com `Authorization: Bearer <managerKey>`:
+Dois endpoints sob `<origin>/api/manager`, ambos com `Authorization: Bearer <secretKey>` (a chave única do projeto):
 
 ### `POST /api/manager/poll`
 
@@ -45,7 +52,13 @@ Corpo `ManagerPollRequest`:
 
 ```jsonc
 {
-  "agent": { "name": "VM 01", "version": "1.0.0", "host": "vm-01", "tasks": ["processar-nfe"] },
+  "agent": {
+    "instance_id": "vm-01",       // identidade canônica do agente (obrigatória)
+    "name": "VM 01",
+    "version": "1.0.0",
+    "host": "vm-01",
+    "tasks": ["processar-nfe"]
+  },
   "max": 1,                       // quantas reivindicar (1..5)
   "tasks": ["processar-nfe"]      // só runs destas tasks registradas
 }
@@ -53,6 +66,8 @@ Corpo `ManagerPollRequest`:
 
 Resposta `ManagerPollResponse` = `{ runs: ManagerRunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
 
+O `agent.instance_id` é a **mesma identidade** do heartbeat do Monitor (`instance_id`): o servidor correlaciona os dois canais numa tabela `agents` por `(project_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente.
+
 **Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
 
 ### `PATCH /api/manager/runs/{id}`
@@ -63,7 +78,6 @@ Corpo `ManagerRunUpdateRequest`:
 {
   "status": "running",            // 'running' | 'succeeded' | 'failed'
   "logs":   [{ "ts": "…", "level": "info", "message": "…" }], // delta; o servidor concatena
-  "result": { "processadas": 12 },// só com 'succeeded'
   "error":  { "type": "Error", "message": "…", "stack": "…" } // só com 'failed'
 }
 ```
@@ -71,7 +85,7 @@ Corpo `ManagerRunUpdateRequest`:
 - `status: 'running'` pode repetir para enviar **logs incrementais** (throttle por `logFlushIntervalMs`, flush ao acumular 20, chunk de 100, teto de 500 logs/run, mensagem cap 10k).
 - Ordem garantida `running → logs → terminal` (PATCHes serializados numa cadeia de promise).
 - Retry `[1s, 4s, 16s]`; 4xx exceto 429 é terminal (**409** = run cancelada / transição inválida → marca a run como morta e dispara `ctx.signal`).
-- `result` é serializado com cap de ~100KB (circular/grande → descartado com marcador `__truncated`).
+- O protocolo **não transporta resultado** de execução: o retorno do handler é ignorado pelo SDK e o servidor descarta qualquer campo `result` de SDKs antigos (dados de negócio podem ser sensíveis e não são coletados).
 
 Ciclo de vida completo da run no servidor: `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed`.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hobots",
-  "version": "1.0.0",
-  "description": "SDK JavaScript da Hobots — captura de erros, transactions, check-ins de cron e heartbeats (Monitor) e execução remota de tarefas sob demanda (Manager) para RPAs e integrações.",
+  "version": "1.1.0",
+  "description": "SDK JavaScript da Hobots — captura de erros, transactions, check-ins de cron e heartbeats (Monitor) e execução remota de tarefas sob demanda (Manager) para RPAs e integrações. Um único import e um único init().",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -26,28 +26,23 @@
       "import": "./dist/protocol.js",
       "require": "./dist/protocol.cjs"
     },
-    "./manager": {
-      "types": "./dist/manager.d.ts",
-      "import": "./dist/manager.js",
-      "require": "./dist/manager.cjs"
-    },
     "./manager/protocol": {
       "types": "./dist/manager/protocol.d.ts",
       "import": "./dist/manager/protocol.js",
       "require": "./dist/manager/protocol.cjs"
     }
   },
-  "devDependencies": {
-    "@types/node": "^20",
-    "tsup": "^8.4.0",
-    "typescript": "5.7.3",
-    "@workspace/eslint-config": "0.0.0",
-    "@workspace/typescript-config": "0.0.0"
-  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint . --max-warnings 0",
     "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@workspace/eslint-config": "workspace:*",
+    "@workspace/typescript-config": "workspace:*",
+    "tsup": "^8.4.0",
+    "typescript": "5.7.3"
   }
-}
+}