@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/5-referencia/runner-system.md

@@ -0,0 +1,113 @@
+# Runner System
+
+> Subsistema de execução persistente para tarefas fora do loop principal de sessão. Introduzido na v1.7.0+.
+
+## Quando usar
+
+O runner é útil quando você precisa:
+- Executar tarefas em **background** sem bloquear a sessão atual
+- Processar **filas de trabalho** com prioridade
+- Manter um **daemon 24/7** para workers automáticos
+- Executar planos de implementação por **fase** de forma independente
+
+## Comandos
+
+| Comando | O que faz |
+|---|---|
+| `runner:run` | Executa uma tarefa ou worker diretamente |
+| `runner:queue` | Enfileira tarefas com prioridade e agente designado |
+| `runner:plan` | Gera ou inspeciona planos de execução do runner |
+| `runner:daemon` | Inicia, para ou monitora o daemon de background |
+| `runner:queue:from-plan` | Extrai fases de um plano `.md` e enfileira automaticamente |
+
+## Ciclo de vida básico
+
+### 1. Inicializar o runtime
+
+O runner depende do banco SQLite de runtime:
+
+```bash
+aioson runtime:init .
+```
+
+### 2. Enfileirar tarefas manualmente
+
+```bash
+aioson runner:queue . \
+  --task="implementar-checkout" \
+  --agent=dev \
+  --priority=1 \
+  --input='{"feature":"checkout","phase":1}'
+```
+
+### 3. Executar uma tarefa diretamente
+
+```bash
+aioson runner:run . --task="implementar-checkout"
+```
+
+### 4. Usar um plano como fonte
+
+```bash
+# Gerar plano a partir de uma feature
+aioson runner:plan . --feature=checkout --generate
+
+# Enfileirar todas as fases do plano
+aioson runner:queue:from-plan . --feature=checkout --agent=dev
+```
+
+### 5. Daemon para execução contínua
+
+```bash
+# Iniciar daemon
+aioson runner:daemon . --sub=start
+
+# Ver status
+aioson runner:daemon . --sub=status
+
+# Parar
+aioson runner:daemon . --sub=stop
+```
+
+## Estrutura interna
+
+O runner é composto por 4 módulos principais em `src/runner/`:
+
+| Módulo | Responsabilidade |
+|---|---|
+| `queue-store.js` | Persistência da fila no SQLite |
+| `plan-importer.js` | Parsing de planos Markdown em tarefas enfileiráveis |
+| `cascade.js` | Lógica de execução sequencial/paralela e retry |
+| `cli-launcher.js` | Interface entre CLI e o motor do runner |
+
+## Integração com squads
+
+Squads podem usar o runner para executar workers não-LLM em background:
+
+```bash
+# Enfileirar worker de uma squad
+aioson runner:queue . \
+  --squad=marketing \
+  --worker=gerar-post \
+  --input='{"tema":"IA no marketing"}'
+```
+
+## Diferença entre runner e squad:daemon
+
+| | Runner | Squad Daemon |
+|---|---|---|
+| **Escopo** | Tarefas genéricas do projeto | Workers específicos de uma squad |
+| **Trigger** | Manual, plano ou fila | Cron, webhook ou evento |
+| **Persistência** | SQLite do runtime | SQLite do runtime + bus JSONL |
+| **Uso típico** | Execução por fase de plano | Workers 24/7 (WhatsApp, notificações) |
+
+## Troubleshooting
+
+**Erro: "Runtime not initialized"**
+→ Rode `aioson runtime:init .` antes de qualquer comando do runner.
+
+**Erro: "No tasks in queue"**
+→ Verifique se as tarefas foram enfileiradas corretamente com `runner:queue` ou `runner:queue:from-plan`.
+
+**Daemon não inicia**
+→ Verifique permissões de escrita no diretório do projeto e se a porta padrão está livre.

package/docs/pt/{runtime-observability.md → 5-referencia/runtime-observability.md}

@@ -1,76 +1,76 @@
-# Runtime Observability
-
-## Objetivo
-
-Estabelecer o runtime do projeto como autoridade unica para:
-
-- task
-- run de agente
-- eventos operacionais
-- enforcement de workflow
-
-O prompt do agente nao e mais responsavel por persistir telemetria.
-
-## Principios
-
-1. Toda execucao relevante deve passar por um gateway oficial.
-2. O SQLite em `.aioson/runtime/aios.sqlite` e a fonte primaria de runtime por projeto.
-3. `execution_events` e o event store canonico.
-4. `tasks` e `agent_runs` permanecem como projecoes operacionais para UI e consultas simples.
-5. Workflow obrigatorio deve ser aplicado no runtime, nao em convencoes textuais de prompt.
-
-## Tabelas
-
-- `tasks`: unidade de trabalho visivel para o usuario
-- `agent_runs`: execucao concreta de um agente
-- `agent_events`: feed legado de compatibilidade
-- `execution_events`: trilha canonica append-only de observabilidade
-
-## Metadados novos em `agent_runs`
-
-- `source`
-- `workflow_id`
-- `workflow_stage`
-- `parent_run_key`
-
-## Taxonomia de runtime
-
-- `agent_kind=official`: agentes nativos do AIOS executados de forma direta ou governada
-- `agent_kind=squad`: sessoes e handoffs ligados a `@squad`
-- `agent_kind=workflow`: controlador de workflow e etapas de governanca
-
-- `source=direct`: handoff direto de agente oficial
-- `source=workflow`: execucao ou redirecionamento governado por workflow
-- `source=orchestration`: operacoes de controle como `parallel:*` e handoff de `@orchestrator`
-- `source=squad_session`: handoff direto para `@squad`
-
-## Papel do gateway
-
-O gateway oficial de execucao deve:
-
-1. resolver o projeto alvo
-2. garantir o runtime inicializado
-3. abrir ou reutilizar a task correta
-4. abrir ou reutilizar runs necessarios
-5. emitir eventos canonicos
-6. atualizar estado final de task e runs
-
-## Estado atual da implementacao
-
-- `install` e `init` agora inicializam o runtime no projeto
-- `execution_events` foi adicionado ao schema do runtime
-- `workflow:next` sincroniza task/run/eventos reais no SQLite via gateway
-- `agent:prompt` classifica handoffs diretos de agentes oficiais e cria a task/run inicial no runtime
-- `runtime:session:start|log|finish|status` oferece uma camada direta para manter sessoes de agentes oficiais abertas e visiveis no dashboard durante o trabalho iterativo
-- `live:start|handoff|status|close` e `runtime:emit` formam o launcher/supervisor oficial para clientes externos, mantendo uma `session_key` viva, trocando `active_agent` por handoff e persistindo estado compacto no SQLite com historico verbose em `.aioson/runtime/live/{session_key}/`
-- `runtime:status --json` agora expoe projecoes prontas para dashboard e scripts: `activeLiveSessions`, `activeMicroTasks`, `recentLiveSessions`, `recentMicroTasks` e `recentHandoffs`
-- ativacao por linguagem natural direto no cliente (ex.: mencionar `@deyvin` no Codex) ainda nao passa pelo gateway e, portanto, nao garante registros em `tasks` e `agent_runs`
-- `parallel:init`, `parallel:assign` e `parallel:status` registram operacoes canonicas de orquestracao
-- templates novos nao instruem mais o agente a chamar `runtime-log` por shell snippet
-
-## Proximos passos
-
-1. instrumentar execucao de subagentes e runs filhas com `parent_run_key`
-2. conectar comandos de doctor/qa/squad pipeline ao mesmo gateway operacional
-3. migrar o dashboard para consumir `execution_events` como feed principal
-4. adicionar spool append-only como fallback de resiliencia
+# Runtime Observability
+
+## Objetivo
+
+Estabelecer o runtime do projeto como autoridade unica para:
+
+- task
+- run de agente
+- eventos operacionais
+- enforcement de workflow
+
+O prompt do agente nao e mais responsavel por persistir telemetria.
+
+## Principios
+
+1. Toda execucao relevante deve passar por um gateway oficial.
+2. O SQLite em `.aioson/runtime/aios.sqlite` e a fonte primaria de runtime por projeto.
+3. `execution_events` e o event store canonico.
+4. `tasks` e `agent_runs` permanecem como projecoes operacionais para UI e consultas simples.
+5. Workflow obrigatorio deve ser aplicado no runtime, nao em convencoes textuais de prompt.
+
+## Tabelas
+
+- `tasks`: unidade de trabalho visivel para o usuario
+- `agent_runs`: execucao concreta de um agente
+- `agent_events`: feed legado de compatibilidade
+- `execution_events`: trilha canonica append-only de observabilidade
+
+## Metadados novos em `agent_runs`
+
+- `source`
+- `workflow_id`
+- `workflow_stage`
+- `parent_run_key`
+
+## Taxonomia de runtime
+
+- `agent_kind=official`: agentes nativos do AIOS executados de forma direta ou governada
+- `agent_kind=squad`: sessoes e handoffs ligados a `@squad`
+- `agent_kind=workflow`: controlador de workflow e etapas de governanca
+
+- `source=direct`: handoff direto de agente oficial
+- `source=workflow`: execucao ou redirecionamento governado por workflow
+- `source=orchestration`: operacoes de controle como `parallel:*` e handoff de `@orchestrator`
+- `source=squad_session`: handoff direto para `@squad`
+
+## Papel do gateway
+
+O gateway oficial de execucao deve:
+
+1. resolver o projeto alvo
+2. garantir o runtime inicializado
+3. abrir ou reutilizar a task correta
+4. abrir ou reutilizar runs necessarios
+5. emitir eventos canonicos
+6. atualizar estado final de task e runs
+
+## Estado atual da implementacao
+
+- `install` e `init` agora inicializam o runtime no projeto
+- `execution_events` foi adicionado ao schema do runtime
+- `workflow:next` sincroniza task/run/eventos reais no SQLite via gateway
+- `agent:prompt` classifica handoffs diretos de agentes oficiais e cria a task/run inicial no runtime
+- `runtime:session:start|log|finish|status` oferece uma camada direta para manter sessoes de agentes oficiais abertas e visiveis no dashboard durante o trabalho iterativo
+- `live:start|handoff|status|close` e `runtime:emit` formam o launcher/supervisor oficial para clientes externos, mantendo uma `session_key` viva, trocando `active_agent` por handoff e persistindo estado compacto no SQLite com historico verbose em `.aioson/runtime/live/{session_key}/`
+- `runtime:status --json` agora expoe projecoes prontas para dashboard e scripts: `activeLiveSessions`, `activeMicroTasks`, `recentLiveSessions`, `recentMicroTasks` e `recentHandoffs`
+- ativacao por linguagem natural direto no cliente (ex.: mencionar `@deyvin` no Codex) ainda nao passa pelo gateway e, portanto, nao garante registros em `tasks` e `agent_runs`
+- `parallel:init`, `parallel:assign` e `parallel:status` registram operacoes canonicas de orquestracao
+- templates novos nao instruem mais o agente a chamar `runtime-log` por shell snippet
+
+## Proximos passos
+
+1. instrumentar execucao de subagentes e runs filhas com `parent_run_key`
+2. conectar comandos de doctor/qa/squad pipeline ao mesmo gateway operacional
+3. migrar o dashboard para consumir `execution_events` como feed principal
+4. adicionar spool append-only como fallback de resiliencia

package/docs/pt/{sandbox.md → 5-referencia/sandbox.md}

@@ -1,125 +1,125 @@
-# Sandbox de Execução
-
-> Executa comandos shell com timeout automático, redação de secrets e summarização de output longo.
-
-O `sandbox:exec` roda comandos em subprocesso isolado com três garantias: o comando é interrompido se passar do tempo máximo, qualquer secret reconhecido no output é redatado antes de ser exibido, e outputs maiores que 5KB são automaticamente resumidos mantendo início e fim.
-
----
-
-## Comando
-
-### `sandbox:exec`
-
-```bash
-aioson sandbox:exec "<comando>" [opções]
-```
-
-**Opções:**
-
-| Opção | Descrição |
-|---|---|
-| `--timeout=<ms>` | Interromper após N milissegundos (padrão: 30000) |
-| `--cwd=<path>` | Diretório de trabalho do comando |
-| `--intent="..."` | Rótulo para output truncado (aparece na marcação de omissão) |
-| `--json` | Retorna stdout, stderr, exitCode e timedOut em JSON |
-
-**Exemplos:**
-
-```bash
-# Rodar testes com timeout de 60 segundos
-aioson sandbox:exec "npm test" --timeout=60000
-
-# Comando que pode exibir secrets (redatado automaticamente)
-aioson sandbox:exec "env | grep TOKEN"
-
-# Executar em outro diretório
-aioson sandbox:exec "npm run build" --cwd=./frontend
-
-# Capturar resultado estruturado
-aioson sandbox:exec "node -e 'console.log(JSON.stringify({ok:true}))'" --json
-```
-
----
-
-## Redação automática de secrets
-
-O output é varrido automaticamente antes de ser exibido. Qualquer padrão reconhecido é substituído por `[REDACTED]`:
-
-| Padrão | Exemplo |
-|---|---|
-| GitHub token (`ghp_*`) | `ghp_abc123...` → `ghp_[REDACTED]` |
-| GitHub fine-grained (`github_pat_*`) | `github_pat_abc...` → `github_pat_[REDACTED]` |
-| AWS access key (`AKIA*`) | `AKIAIOSFODNN7EXAMPLE` → `AKIA[REDACTED]` |
-| Google OAuth (`ya29.*`) | `ya29.A0ARrd...` → `ya29.[REDACTED]` |
-| Bearer token | `Bearer eyJhb...` → `Bearer [REDACTED]` |
-| Senha em URL | `:minhasenha@host` → `:[REDACTED]@host` |
-| `password=...` | `password=abc123` → `password=[REDACTED]` |
-| `passwd=...` | `passwd=abc123` → `passwd=[REDACTED]` |
-| `secret=...` | `secret=xyz` → `secret=[REDACTED]` |
-| `api_key=...` | `api_key=sk-abc` → `api_key=[REDACTED]` |
-| Bloco de chave privada | `-----BEGIN PRIVATE KEY-----...` → `[REDACTED]` |
-
-A redação é aplicada tanto ao stdout quanto ao stderr.
-
----
-
-## Timeout e interrupção
-
-O comando é encerrado com `AbortController` quando o timeout é atingido. O resultado retorna `timedOut: true` e `ok: false`.
-
-```bash
-# Vai ser interrompido após 500ms
-aioson sandbox:exec "sleep 10" --timeout=500
-```
-
----
-
-## Summarização de output longo
-
-Se o output ultrapassar 5KB, a resposta mantém o início e o fim e indica quantos bytes foram omitidos:
-
-```
-[início do output...]
-
-[... 12.450 bytes omitted (npm test) ...]
-
-[...fim do output]
-```
-
-Use `--intent="..."` para que o rótulo apareça na marcação de omissão.
-
----
-
-## JSON output
-
-```json
-{
-  "ok": true,
-  "stdout": "Tests: 42 passed\n",
-  "stderr": "",
-  "exitCode": 0,
-  "timedOut": false,
-  "signal": null
-}
-```
-
-Quando há timeout:
-
-```json
-{
-  "ok": false,
-  "stdout": "",
-  "stderr": "Command timed out after 500ms",
-  "exitCode": null,
-  "timedOut": true
-}
-```
-
----
-
-## Quando usar
-
-- Rodar scripts ou testes dentro de uma sessão de agente sem expor secrets do ambiente
-- Capturar output de comandos que podem conter variáveis de ambiente sensíveis
-- Executar builds ou verificações com tempo máximo controlado
-- Testar comandos cujo output vai ser lido de volta pelo agente (redação evita envenenamento de contexto com secrets)
+# Sandbox de Execução
+
+> Executa comandos shell com timeout automático, redação de secrets e summarização de output longo.
+
+O `sandbox:exec` roda comandos em subprocesso isolado com três garantias: o comando é interrompido se passar do tempo máximo, qualquer secret reconhecido no output é redatado antes de ser exibido, e outputs maiores que 5KB são automaticamente resumidos mantendo início e fim.
+
+---
+
+## Comando
+
+### `sandbox:exec`
+
+```bash
+aioson sandbox:exec "<comando>" [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--timeout=<ms>` | Interromper após N milissegundos (padrão: 30000) |
+| `--cwd=<path>` | Diretório de trabalho do comando |
+| `--intent="..."` | Rótulo para output truncado (aparece na marcação de omissão) |
+| `--json` | Retorna stdout, stderr, exitCode e timedOut em JSON |
+
+**Exemplos:**
+
+```bash
+# Rodar testes com timeout de 60 segundos
+aioson sandbox:exec "npm test" --timeout=60000
+
+# Comando que pode exibir secrets (redatado automaticamente)
+aioson sandbox:exec "env | grep TOKEN"
+
+# Executar em outro diretório
+aioson sandbox:exec "npm run build" --cwd=./frontend
+
+# Capturar resultado estruturado
+aioson sandbox:exec "node -e 'console.log(JSON.stringify({ok:true}))'" --json
+```
+
+---
+
+## Redação automática de secrets
+
+O output é varrido automaticamente antes de ser exibido. Qualquer padrão reconhecido é substituído por `[REDACTED]`:
+
+| Padrão | Exemplo |
+|---|---|
+| GitHub token (`ghp_*`) | `ghp_abc123...` → `ghp_[REDACTED]` |
+| GitHub fine-grained (`github_pat_*`) | `github_pat_abc...` → `github_pat_[REDACTED]` |
+| AWS access key (`AKIA*`) | chave começando com `AKIA` seguida de 16 caracteres → `AKIA[REDACTED]` |
+| Google OAuth (`ya29.*`) | `ya29.A0ARrd...` → `ya29.[REDACTED]` |
+| Bearer token | `Bearer eyJhb...` → `Bearer [REDACTED]` |
+| Senha em URL | `:minhasenha@host` → `:[REDACTED]@host` |
+| `password=...` | `password=abc123` → `password=[REDACTED]` |
+| `passwd=...` | `passwd=abc123` → `passwd=[REDACTED]` |
+| `secret=...` | `secret=xyz` → `secret=[REDACTED]` |
+| `api_key=...` | `api_key=sk-abc` → `api_key=[REDACTED]` |
+| Bloco de chave privada | linha que começa com `--- BEGIN PRIVATE KEY ---` (PEM) → `[REDACTED]` |
+
+A redação é aplicada tanto ao stdout quanto ao stderr.
+
+---
+
+## Timeout e interrupção
+
+O comando é encerrado com `AbortController` quando o timeout é atingido. O resultado retorna `timedOut: true` e `ok: false`.
+
+```bash
+# Vai ser interrompido após 500ms
+aioson sandbox:exec "sleep 10" --timeout=500
+```
+
+---
+
+## Summarização de output longo
+
+Se o output ultrapassar 5KB, a resposta mantém o início e o fim e indica quantos bytes foram omitidos:
+
+```
+[início do output...]
+
+[... 12.450 bytes omitted (npm test) ...]
+
+[...fim do output]
+```
+
+Use `--intent="..."` para que o rótulo apareça na marcação de omissão.
+
+---
+
+## JSON output
+
+```json
+{
+  "ok": true,
+  "stdout": "Tests: 42 passed\n",
+  "stderr": "",
+  "exitCode": 0,
+  "timedOut": false,
+  "signal": null
+}
+```
+
+Quando há timeout:
+
+```json
+{
+  "ok": false,
+  "stdout": "",
+  "stderr": "Command timed out after 500ms",
+  "exitCode": null,
+  "timedOut": true
+}
+```
+
+---
+
+## Quando usar
+
+- Rodar scripts ou testes dentro de uma sessão de agente sem expor secrets do ambiente
+- Capturar output de comandos que podem conter variáveis de ambiente sensíveis
+- Executar builds ou verificações com tempo máximo controlado
+- Testar comandos cujo output vai ser lido de volta pelo agente (redação evita envenenamento de contexto com secrets)