hobots 1.5.1 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -74
- package/dist/index.cjs +267 -144
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +31 -123
- package/dist/index.d.ts +31 -123
- package/dist/index.js +267 -144
- package/dist/index.js.map +1 -1
- package/dist/protocol.cjs.map +1 -1
- package/dist/protocol.d.cts +73 -4
- package/dist/protocol.d.ts +73 -4
- package/docs/README.md +8 -8
- package/docs/api-reference.md +40 -44
- package/docs/concepts.md +67 -52
- package/docs/getting-started.md +17 -17
- package/docs/monitor.md +8 -8
- package/docs/protocol.md +21 -25
- package/docs/{manager.md → tasks.md} +18 -18
- package/package.json +3 -7
- package/dist/manager/protocol.cjs +0 -19
- package/dist/manager/protocol.cjs.map +0 -1
- package/dist/manager/protocol.d.cts +0 -72
- package/dist/manager/protocol.d.ts +0 -72
- package/dist/manager/protocol.js +0 -1
- package/dist/manager/protocol.js.map +0 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Tasks (execução sob demanda)
|
|
2
2
|
|
|
3
|
-
Capability de **execução remota sob demanda**, habilitada com `
|
|
3
|
+
Capability de **execução remota sob demanda**, habilitada com `tasks: 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 — é o que alimenta o módulo **Solicitações** do app. Usa o mesmo Client Secret, o mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
|
|
4
4
|
|
|
5
5
|
O vocabulário desta página ([run](./concepts.md#run), [claim](./concepts.md#claim), [drain mode](./concepts.md#drain-mode), [ctx.tx](./concepts.md#transaction-de-run-ctxtx)) está explicado em [Conceitos](./concepts.md).
|
|
6
6
|
|
|
@@ -12,7 +12,7 @@ import * as Hobots from 'hobots';
|
|
|
12
12
|
Hobots.init({
|
|
13
13
|
clientSecret: 'hb_<64 hex>',
|
|
14
14
|
instanceId: 'vm-cliente-01',
|
|
15
|
-
|
|
15
|
+
tasks: true, // ou { pollIntervalMs, concurrency, taskTimeoutMs, logFlushIntervalMs }
|
|
16
16
|
});
|
|
17
17
|
|
|
18
18
|
Hobots.register('processar-nfe', async (params, ctx) => {
|
|
@@ -28,26 +28,26 @@ process.on('SIGINT', () => {
|
|
|
28
28
|
});
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
- `init({
|
|
32
|
-
- `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
|
|
33
|
-
- `start()` — começa o polling. Lança se o `init()` não configurou `
|
|
34
|
-
- `stop(timeoutMs?)` — para **só o
|
|
31
|
+
- `init({ tasks })` — cria o agente. Chamar `init()` de novo para o agente anterior e o substitui (os handlers registrados são preservados). Se havia runs em execução, elas são interrompidas **sem espera** e reportadas como `AgentTerminated` na hora — `init()` não é um jeito gracioso de reconfigurar um agente ocupado; para isso use `stop()` antes.
|
|
32
|
+
- `register(task, handler)` — `task` é o `task_slug` configurado no formulário do app (**Configurações → Formulários**). Registre **antes** de `start()`. Pode ser chamado antes do `init()`; se o `init()` não habilitou as tasks, o SDK avisa no console.
|
|
33
|
+
- `start()` — começa o polling. Lança se o `init()` não configurou `tasks` ou se nenhuma task foi registrada.
|
|
34
|
+
- `stop(timeoutMs?)` — para **só o polling de tasks**: encerra o polling e aguarda as runs ativas ([default](./api-reference.md#tempos-e-intervalos)); a telemetria continua. Retorna `false` se estourou o timeout.
|
|
35
35
|
- `close(timeoutMs?)` — encerra **tudo**: agente (aguardando runs em voo) → heartbeat → flush final.
|
|
36
36
|
|
|
37
|
-
O `instanceId` (obrigatório) é a identidade do agente no painel — o poll o envia como `agent.instance_id`, a **mesma identidade** do heartbeat
|
|
37
|
+
O `instanceId` (obrigatório) é a identidade do agente no painel — o poll o envia como `agent.instance_id`, a **mesma identidade** do heartbeat de telemetria. Com o `init()` único, os dois canais convergem em **um agente** no módulo Agentes automaticamente. Com `tasks: true`, o heartbeat é **opcional**: o próprio poll já marca a presença do agente; o heartbeat continua essencial para agentes só de telemetria.
|
|
38
38
|
|
|
39
39
|
> **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.
|
|
40
40
|
|
|
41
41
|
## O handler e o `RunContext`
|
|
42
42
|
|
|
43
43
|
```ts
|
|
44
|
-
type
|
|
44
|
+
type TaskHandler<P = Record<string, unknown>> =
|
|
45
45
|
(params: P, ctx: RunContext) => void | Promise<void>;
|
|
46
46
|
|
|
47
47
|
interface RunContext {
|
|
48
48
|
runId: string;
|
|
49
49
|
task: string;
|
|
50
|
-
log
|
|
50
|
+
log: RunLogger; // ctx.log.debug/info/warn/error/success(message)
|
|
51
51
|
tx: Transaction;
|
|
52
52
|
signal: AbortSignal;
|
|
53
53
|
throwIfCanceled(): void;
|
|
@@ -56,7 +56,7 @@ interface RunContext {
|
|
|
56
56
|
```
|
|
57
57
|
|
|
58
58
|
- **`params`** — os dados do formulário configurado no app (o JSON validado).
|
|
59
|
-
- **`ctx.log.<level>(message)`** — logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na
|
|
59
|
+
- **`ctx.log.<level>(message)`** — níveis `debug`, `info`, `warn`, `error` e `success`; logs enviados **incrementalmente** ao app (PATCHes com throttle), visíveis na solicitação em tempo quase real. Cada linha também é **impressa no terminal local** como `[hobots:<task>] INFO mensagem`, colorida por nível — útil para acompanhar o robô rodando na VM. A cor é desligada automaticamente fora de um TTY e quando a env `NO_COLOR` está definida; o eco local é independente do envio ao servidor.
|
|
60
60
|
- **`ctx.tx`** — a [transaction de performance](./concepts.md#transaction-de-run-ctxtx) desta run, já correlacionada e finalizada pelo SDK. Use `ctx.tx.startChild()` para medir as etapas (veja abaixo).
|
|
61
61
|
- **`ctx.signal`** — `AbortSignal` que dispara quando a run é **cancelada no app**, em **timeout** ou no **shutdown**. Cancelamento é cooperativo (veja abaixo).
|
|
62
62
|
- **`ctx.throwIfCanceled()`** — lança `RunCanceled` se o `signal` já disparou. O ponto de parada de 1 linha para chamar entre as etapas do trabalho.
|
|
@@ -66,7 +66,7 @@ interface RunContext {
|
|
|
66
66
|
|
|
67
67
|
Você pode tipar os params: `Hobots.register<{ lote: number }>(...)`.
|
|
68
68
|
|
|
69
|
-
> **Dados sensíveis:** o que você escreve em `ctx.log
|
|
69
|
+
> **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.
|
|
70
70
|
|
|
71
71
|
## Performance da run (`ctx.tx`)
|
|
72
72
|
|
|
@@ -89,14 +89,14 @@ Hobots.register('processar-nfe', async (params, ctx) => {
|
|
|
89
89
|
|
|
90
90
|
Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app — é como você responde "onde foram os 4 minutos". Sem nenhum span, a transaction ainda mede o tempo total da run; o waterfall só fica com uma barra.
|
|
91
91
|
|
|
92
|
-
- **
|
|
93
|
-
- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale só para as transactions
|
|
92
|
+
- **`startTransaction()` dentro do handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: se o seu código (ou uma lib sua já instrumentada) chamar `Hobots.startTransaction()` dentro de um handler, o SDK detecta o contexto da run e retorna a transaction dela em vez de criar uma segunda — os spans caem no mesmo waterfall. Fora de um handler, `startTransaction()` cria uma transaction nova, sem `run_id`.
|
|
93
|
+
- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale só para as transactions abertas com `startTransaction()` fora de uma run.
|
|
94
94
|
- Span que você esquecer aberto é fechado no `finish()` da transaction, então o dado não se perde.
|
|
95
95
|
- Marque etapas com ressalva usando `span.setStatus('warning')` (ex.: retry que deu certo, resultado parcial): elas aparecem em âmbar no waterfall, distintas de sucesso e de falha (`'error'`).
|
|
96
96
|
|
|
97
97
|
## Cancelamento cooperativo
|
|
98
98
|
|
|
99
|
-
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`. Enquanto o handler roda, o SDK mantém um **heartbeat de cancelamento** (a cada `cancelCheckIntervalMs`, veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)): a run cancelada no app é detectada em segundos, mesmo que o handler nunca chame `ctx.log
|
|
99
|
+
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`. Enquanto o handler roda, o SDK mantém um **heartbeat de cancelamento** (a cada `cancelCheckIntervalMs`, veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)): a run cancelada no app é detectada em segundos, mesmo que o handler nunca chame `ctx.log`. Chame **`ctx.throwIfCanceled()`** em loops longos e pontos de parada (e troque esperas por `ctx.sleep()`):
|
|
100
100
|
|
|
101
101
|
```js
|
|
102
102
|
Hobots.register('processar-nfe', async (params, ctx) => {
|
|
@@ -113,7 +113,7 @@ Quando o cancelamento veio do app, a run já está `cancelada` no servidor — o
|
|
|
113
113
|
|
|
114
114
|
Se o processo do agente **morre no meio de uma run**, a solicitação vira **falha** no app com erro `AgentTerminated` ("execução encerrada inesperadamente") — sem re-execução automática. Dois caminhos garantem isso:
|
|
115
115
|
|
|
116
|
-
- **Morte capturável** (SIGINT/SIGTERM sem handler próprio do programa, erro não tratado): o SDK reporta a falha na hora (~2s, um PATCH best-effort com timeout curto) e então deixa o processo morrer com a semântica default do sinal. Os handlers são instalados no `start()` e **nunca interferem** quando o programa tem handler próprio para o sinal (o shutdown gracioso via `close()` continua sendo o caminho normal). Desative com `
|
|
116
|
+
- **Morte capturável** (SIGINT/SIGTERM sem handler próprio do programa, erro não tratado): o SDK reporta a falha na hora (~2s, um PATCH best-effort com timeout curto) e então deixa o processo morrer com a semântica default do sinal. Os handlers são instalados no `start()` e **nunca interferem** quando o programa tem handler próprio para o sinal (o shutdown gracioso via `close()` continua sendo o caminho normal). Desative com `tasks: { installExitHandlers: false }`.
|
|
117
117
|
- **Morte dura** (kill -9, queda de energia, rede fora): nada roda no cliente. O heartbeat de cancelamento é também o **sinal de vida da run** — o servidor marca a run como falha ao notar silêncio prolongado (o [sweep](./api-reference.md#tempos-e-intervalos) server-side).
|
|
118
118
|
|
|
119
119
|
`close(timeoutMs)` que estoura o timeout com runs ainda em execução também reporta essas runs como `AgentTerminated` — o processo vai morrer em seguida e o app não deve mostrar a run como "executando" para sempre.
|
|
@@ -130,8 +130,8 @@ Se o agente morrer logo **após capturar** uma run (antes de reportar `running`)
|
|
|
130
130
|
|
|
131
131
|
`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.
|
|
132
132
|
|
|
133
|
-
Todas as opções em [Referência de API →
|
|
133
|
+
Todas as opções em [Referência de API → TasksOptions](./api-reference.md#tasksoptions).
|
|
134
134
|
|
|
135
135
|
## Como o claim funciona (resumo)
|
|
136
136
|
|
|
137
|
-
O SDK é um cliente HTTP: ele faz `POST /v1/
|
|
137
|
+
O SDK é um cliente HTTP: ele faz `POST /v1/tasks/poll` e o **servidor** reivindica as runs pendentes de forma atômica com `FOR UPDATE SKIP LOCKED` — dois agentes nunca pegam a mesma run. Conceito em [Claim](./concepts.md#claim), detalhes em [Protocolo & transporte](./protocol.md).
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hobots",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "SDK JavaScript da Hobots —
|
|
3
|
+
"version": "1.7.0",
|
|
4
|
+
"description": "SDK JavaScript da Hobots — telemetria (erros, transactions, check-ins de cron e heartbeats) e execução remota de tarefas sob demanda (tasks) para RPAs e integrações. Um único import e um único init().",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
7
7
|
"license": "MIT",
|
|
@@ -25,17 +25,13 @@
|
|
|
25
25
|
"types": "./dist/protocol.d.ts",
|
|
26
26
|
"import": "./dist/protocol.js",
|
|
27
27
|
"require": "./dist/protocol.cjs"
|
|
28
|
-
},
|
|
29
|
-
"./manager/protocol": {
|
|
30
|
-
"types": "./dist/manager/protocol.d.ts",
|
|
31
|
-
"import": "./dist/manager/protocol.js",
|
|
32
|
-
"require": "./dist/manager/protocol.cjs"
|
|
33
28
|
}
|
|
34
29
|
},
|
|
35
30
|
"scripts": {
|
|
36
31
|
"build": "tsup",
|
|
37
32
|
"dev": "tsup --watch",
|
|
38
33
|
"lint": "eslint . --max-warnings 0",
|
|
34
|
+
"test": "node --test \"test/**/*.test.mjs\"",
|
|
39
35
|
"typecheck": "tsc --noEmit"
|
|
40
36
|
},
|
|
41
37
|
"devDependencies": {
|
|
@@ -1,19 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __defProp = Object.defineProperty;
|
|
3
|
-
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
-
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
-
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
-
var __copyProps = (to, from, except, desc) => {
|
|
7
|
-
if (from && typeof from === "object" || typeof from === "function") {
|
|
8
|
-
for (let key of __getOwnPropNames(from))
|
|
9
|
-
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
10
|
-
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
11
|
-
}
|
|
12
|
-
return to;
|
|
13
|
-
};
|
|
14
|
-
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
15
|
-
|
|
16
|
-
// src/manager/protocol.ts
|
|
17
|
-
var protocol_exports = {};
|
|
18
|
-
module.exports = __toCommonJS(protocol_exports);
|
|
19
|
-
//# sourceMappingURL=protocol.cjs.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/manager/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e não pode importar nada:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias transitório).\n */\n\n/** Ciclo de vida completo de uma run no servidor. */\nexport type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';\n\n/** Subconjunto que o agente pode enviar no PATCH. */\nexport type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';\n\nexport type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';\n\nexport interface RunLogEntry {\n /** ISO 8601 — relógio do agente, apenas para exibição */\n ts: string;\n level: RunLogLevel;\n message: string;\n}\n\nexport interface ManagerAgentInfo {\n /** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */\n instance_id: string;\n name?: string;\n /** Versão do SDK */\n version?: string;\n /** Hostname da máquina */\n host?: string;\n /** Tasks registradas no agente */\n tasks?: string[];\n}\n\n/** POST /v1/manager/poll */\nexport interface ManagerPollRequest {\n agent?: ManagerAgentInfo;\n /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */\n max?: number;\n /** Só entrega runs destas tasks (nomes registrados no agente) */\n tasks?: string[];\n}\n\nexport interface ManagerRunDescriptor {\n id: string;\n task: string;\n params: Record<string, unknown>;\n form: { id: string; name: string } | null;\n /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */\n source: string;\n /** ISO 8601 (relógio do servidor) */\n created_at: string;\n}\n\nexport interface ManagerPollResponse {\n runs: ManagerRunDescriptor[];\n}\n\nexport interface ManagerRunError {\n /** ex.: nome da classe do erro */\n type?: string;\n message: string;\n stack?: string;\n}\n\n/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */\nexport interface ManagerRunUpdateRequest {\n status: ManagerRunUpdateStatus;\n /** Apenas com status 'failed' */\n error?: ManagerRunError;\n /** Delta desde o último envio — o servidor concatena */\n logs?: RunLogEntry[];\n}\n\nexport interface ManagerRunUpdateResponse {\n ok: true;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
|
|
@@ -1,72 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).
|
|
3
|
-
*
|
|
4
|
-
* Este arquivo é a fonte de verdade do wire format e não pode importar nada:
|
|
5
|
-
* o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
|
|
6
|
-
* contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias transitório).
|
|
7
|
-
*/
|
|
8
|
-
/** Ciclo de vida completo de uma run no servidor. */
|
|
9
|
-
type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
|
|
10
|
-
/** Subconjunto que o agente pode enviar no PATCH. */
|
|
11
|
-
type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';
|
|
12
|
-
type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';
|
|
13
|
-
interface RunLogEntry {
|
|
14
|
-
/** ISO 8601 — relógio do agente, apenas para exibição */
|
|
15
|
-
ts: string;
|
|
16
|
-
level: RunLogLevel;
|
|
17
|
-
message: string;
|
|
18
|
-
}
|
|
19
|
-
interface ManagerAgentInfo {
|
|
20
|
-
/** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */
|
|
21
|
-
instance_id: string;
|
|
22
|
-
name?: string;
|
|
23
|
-
/** Versão do SDK */
|
|
24
|
-
version?: string;
|
|
25
|
-
/** Hostname da máquina */
|
|
26
|
-
host?: string;
|
|
27
|
-
/** Tasks registradas no agente */
|
|
28
|
-
tasks?: string[];
|
|
29
|
-
}
|
|
30
|
-
/** POST /v1/manager/poll */
|
|
31
|
-
interface ManagerPollRequest {
|
|
32
|
-
agent?: ManagerAgentInfo;
|
|
33
|
-
/** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
|
|
34
|
-
max?: number;
|
|
35
|
-
/** Só entrega runs destas tasks (nomes registrados no agente) */
|
|
36
|
-
tasks?: string[];
|
|
37
|
-
}
|
|
38
|
-
interface ManagerRunDescriptor {
|
|
39
|
-
id: string;
|
|
40
|
-
task: string;
|
|
41
|
-
params: Record<string, unknown>;
|
|
42
|
-
form: {
|
|
43
|
-
id: string;
|
|
44
|
-
name: string;
|
|
45
|
-
} | null;
|
|
46
|
-
/** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
|
|
47
|
-
source: string;
|
|
48
|
-
/** ISO 8601 (relógio do servidor) */
|
|
49
|
-
created_at: string;
|
|
50
|
-
}
|
|
51
|
-
interface ManagerPollResponse {
|
|
52
|
-
runs: ManagerRunDescriptor[];
|
|
53
|
-
}
|
|
54
|
-
interface ManagerRunError {
|
|
55
|
-
/** ex.: nome da classe do erro */
|
|
56
|
-
type?: string;
|
|
57
|
-
message: string;
|
|
58
|
-
stack?: string;
|
|
59
|
-
}
|
|
60
|
-
/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */
|
|
61
|
-
interface ManagerRunUpdateRequest {
|
|
62
|
-
status: ManagerRunUpdateStatus;
|
|
63
|
-
/** Apenas com status 'failed' */
|
|
64
|
-
error?: ManagerRunError;
|
|
65
|
-
/** Delta desde o último envio — o servidor concatena */
|
|
66
|
-
logs?: RunLogEntry[];
|
|
67
|
-
}
|
|
68
|
-
interface ManagerRunUpdateResponse {
|
|
69
|
-
ok: true;
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
export type { ManagerAgentInfo, ManagerPollRequest, ManagerPollResponse, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateRequest, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel };
|
|
@@ -1,72 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).
|
|
3
|
-
*
|
|
4
|
-
* Este arquivo é a fonte de verdade do wire format e não pode importar nada:
|
|
5
|
-
* o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`
|
|
6
|
-
* contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias transitório).
|
|
7
|
-
*/
|
|
8
|
-
/** Ciclo de vida completo de uma run no servidor. */
|
|
9
|
-
type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
|
|
10
|
-
/** Subconjunto que o agente pode enviar no PATCH. */
|
|
11
|
-
type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';
|
|
12
|
-
type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';
|
|
13
|
-
interface RunLogEntry {
|
|
14
|
-
/** ISO 8601 — relógio do agente, apenas para exibição */
|
|
15
|
-
ts: string;
|
|
16
|
-
level: RunLogLevel;
|
|
17
|
-
message: string;
|
|
18
|
-
}
|
|
19
|
-
interface ManagerAgentInfo {
|
|
20
|
-
/** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */
|
|
21
|
-
instance_id: string;
|
|
22
|
-
name?: string;
|
|
23
|
-
/** Versão do SDK */
|
|
24
|
-
version?: string;
|
|
25
|
-
/** Hostname da máquina */
|
|
26
|
-
host?: string;
|
|
27
|
-
/** Tasks registradas no agente */
|
|
28
|
-
tasks?: string[];
|
|
29
|
-
}
|
|
30
|
-
/** POST /v1/manager/poll */
|
|
31
|
-
interface ManagerPollRequest {
|
|
32
|
-
agent?: ManagerAgentInfo;
|
|
33
|
-
/** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
|
|
34
|
-
max?: number;
|
|
35
|
-
/** Só entrega runs destas tasks (nomes registrados no agente) */
|
|
36
|
-
tasks?: string[];
|
|
37
|
-
}
|
|
38
|
-
interface ManagerRunDescriptor {
|
|
39
|
-
id: string;
|
|
40
|
-
task: string;
|
|
41
|
-
params: Record<string, unknown>;
|
|
42
|
-
form: {
|
|
43
|
-
id: string;
|
|
44
|
-
name: string;
|
|
45
|
-
} | null;
|
|
46
|
-
/** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
|
|
47
|
-
source: string;
|
|
48
|
-
/** ISO 8601 (relógio do servidor) */
|
|
49
|
-
created_at: string;
|
|
50
|
-
}
|
|
51
|
-
interface ManagerPollResponse {
|
|
52
|
-
runs: ManagerRunDescriptor[];
|
|
53
|
-
}
|
|
54
|
-
interface ManagerRunError {
|
|
55
|
-
/** ex.: nome da classe do erro */
|
|
56
|
-
type?: string;
|
|
57
|
-
message: string;
|
|
58
|
-
stack?: string;
|
|
59
|
-
}
|
|
60
|
-
/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */
|
|
61
|
-
interface ManagerRunUpdateRequest {
|
|
62
|
-
status: ManagerRunUpdateStatus;
|
|
63
|
-
/** Apenas com status 'failed' */
|
|
64
|
-
error?: ManagerRunError;
|
|
65
|
-
/** Delta desde o último envio — o servidor concatena */
|
|
66
|
-
logs?: RunLogEntry[];
|
|
67
|
-
}
|
|
68
|
-
interface ManagerRunUpdateResponse {
|
|
69
|
-
ok: true;
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
export type { ManagerAgentInfo, ManagerPollRequest, ManagerPollResponse, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateRequest, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel };
|
package/dist/manager/protocol.js
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
//# sourceMappingURL=protocol.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
|