> ## Documentation Index > Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt > Use this file to discover all available pages before exploring further. # Scheduler (Chronos) — Agendamento durável > Sistema de agendamento com cron, wait-until, DAG e daemon mode. Agents agendam ações sozinhos; jobs sobrevivem a reinícios. O **Scheduler** (codename **Chronos**) é a camada de automação durável do ChatCLI. Ele permite: * **Agendar ações** por tempo absoluto, relativo, cron ou interval. * **Esperar condições** (HTTP, K8s, Docker, TCP, file, shell, LLM) e disparar ações só quando satisfeitas. * **Encadear jobs** em DAG com `DependsOn` / `Triggers`. * **Rodar em daemon** que sobrevive ao fechar da CLI — perfeito para deploys longos, `terraform apply`, migrações de banco. * **Dar aos agents** uma ferramenta `@scheduler` para planejar os próprios follow-ups ("aguarde o deploy e me avise"). Tudo persistente via **WAL com CRC32**, **snapshots** periódicos, **circuit breakers** por evaluator/action, **rate limiter** global e por-owner, **audit log** JSONL, **métricas Prometheus** e **hooks** de lifecycle. Todos os três modos do ChatCLI (CLI interativa, servidor gRPC, operador K8s) podem usar o scheduler. O daemon é opcional — em uso casual o scheduler roda in-process e o WAL replaya os jobs na próxima vez que você abrir o CLI. *** ## Visão geral do fluxo Cada job pode disparar imediatamente, esperar uma condição, encadear outros jobs e propagar lifecycle hooks. O diagrama abaixo mostra um pipeline típico de deploy + verificação + notificação: ```mermaid theme={"system"} flowchart LR Start([/ /schedule deploy /]) --> J1[deploy
terraform apply] J1 -->|on success| Wait{{wait
k8s:deployment/api:Available}} Wait -->|condição satisfeita| J2[verify
kubectl get pods] Wait -->|timeout 10m| Fail[on_failure
rollback] J2 -->|on success| J3[notify
Slack/PagerDuty] J1 -.->|lifecycle hooks| Hook[Webhook
audit log] J2 -.->|lifecycle hooks| Hook J3 -.->|lifecycle hooks| Hook classDef start fill:#2563EB,stroke:#1E40AF,color:#fff classDef job fill:#10B981,stroke:#059669,color:#fff classDef wait fill:#F59E0B,stroke:#D97706,color:#fff classDef fail fill:#EF4444,stroke:#DC2626,color:#fff classDef hook fill:#7C3AED,stroke:#6D28D9,color:#fff class Start start class J1,J2,J3 job class Wait wait class Fail fail class Hook hook ``` *** ## Por que você precisa disso Antes do scheduler, ChatCLI era sempre síncrono. Você pedia algo, esperava, recebia resposta. Agora: ```bash theme={"system"} ❯ /schedule deploy --when +0s --do "shell: terraform apply -auto-approve" --triggers verify ❯ /schedule verify --when manual --do "/run kubectl get pods" --wait "k8s:deployment/prod/api:Available" --timeout 10m ❯ exit # pode fechar o CLI — jobs continuam se o daemon estiver rodando ``` O `terraform apply` roda, espera a deployment ficar Available, então executa o check final. Você volta horas depois e pergunta `/jobs history` para ver o que aconteceu. *** ## Dois modos de execução **Sem setup.** Abra o chatcli normal e use `/schedule` / `/wait` / `/jobs`. O scheduler roda dentro do próprio processo. ```bash theme={"system"} ❯ chatcli ❯ /schedule backup --cron "0 2 * * *" --do "/run backup diário" ``` O status line no prompt mostra `[jobs: 1⏳]` enquanto há jobs ativos. Se você sair do chatcli, os workers param. Os jobs pendentes ficam no WAL (`~/.chatcli/scheduler/wal/`) e serão **replayados** automaticamente na próxima vez que você abrir o CLI. **Setup uma vez, roda sozinho.** Jobs continuam mesmo se você fechar o terminal. ```bash theme={"system"} # Sobe o daemon em background $ chatcli daemon start --detach chatcli daemon started (pid=12345, socket=/tmp/chatcli-scheduler.sock, log=~/.chatcli/scheduler/daemon.log) # Qualquer chatcli que você abrir conecta sozinho $ chatcli [scheduler: connected to daemon at /tmp/chatcli-scheduler.sock] ❯ /schedule deploy ... ❯ exit # Daemon continua rodando. Volte depois: $ chatcli daemon status chatcli daemon socket : /tmp/chatcli-scheduler.sock uptime : 3h 14m jobs : 4 active, queue=2 wal segs : 11 clients : 0 ``` **Parar o daemon:** `chatcli daemon stop` — jobs pendentes ficam no WAL e serão retomados no próximo start. *** ## Comando `/schedule` — criar um job ```bash theme={"system"} /schedule --when --do [flags] ``` ### Valores de `--when` O DSL aceita múltiplos formatos: | Formato | Exemplo | Comportamento | | --------------- | ----------------------------------------------------- | -------------------------------------------------- | | Relative | `+5m`, `in 30s`, `after 2h` | Uma vez, após a duração | | Absolute | `at 2026-04-25T14:00`, `at now` | Uma vez, em tempo exato | | Cron 5-campos | `cron:0 2 * * *`, `0 2 * * *` | Recorrente, padrão Vixie-cron | | Cron shorthand | `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly` | Presets comuns | | Interval | `every 30s`, `every 5m`, `every 1h` | Recorrente com intervalo fixo | | Condition-gated | `when-ready` | Sem tempo — dispara quando `--wait` for satisfeito | | Manual | `manual`, `triggered` | Só dispara via `--triggers` de outro job | ### Valores de `--do` Sete tipos de action: | Tipo | Sintaxe | Descrição | | ----------------- | ------------------------------------------- | ----------------------------------------------------- | | **Slash command** | `/run tests` / `/coder refactor X` | Executa slash command como se o user tivesse digitado | | **Shell** | `shell: docker compose up -d` | Comando shell sob CoderMode safety | | **Agent task** | `agent: deploy e verifique` | Boota ReAct agent com a tarefa | | **LLM prompt** | `llm: resumir o relatório semanal` | Single LLM call headless | | **Webhook** | `POST https://hooks.slack.com/... \| hello` | HTTP request | | **Hook** | `hook:PostToolUse` | Dispara hook chatcli por event name | | **Noop** | `noop` | Útil para pipelines só com Triggers | ### Flags completas | Flag | Valor | Descrição | | -------------------- | ----------------------------- | ------------------------------------------- | | `--when` | DSL | Quando disparar (obrigatório) | | `--cron` | expr 5-campos | Atalho para `--when cron:` | | `--every` | duração | Atalho para `--when every ` | | `--do` | DSL | Ação a executar (obrigatório) | | `--wait` / `--until` | DSL condição | Poll até satisfazer antes da ação | | `--timeout` | duração | Timeout da ação (padrão 5m) | | `--wait-timeout` | duração | Timeout do loop de wait (padrão 30m) | | `--poll` | duração | Intervalo entre polls (padrão 5s) | | `--max-polls` | int | Limite de polls (0=ilimitado) | | `--max-retries` | int | Retries em falha transiente | | `--depends-on` | job\_id | Bloqueia até o job dependency completar | | `--triggers` | job\_id | Dispara o job alvo quando este completar | | `--ttl` | duração | Quanto tempo manter o registro pós-terminal | | `--description` | texto | Descrição livre para `/jobs show` | | `--tag` | k=v | Tag para filtrar em `/jobs list` | | `--on-timeout` | `fail\|fire_anyway\|fallback` | Comportamento no timeout do wait | | `--async` | — | Não bloqueia — retorna o job ID | | `--i-know` | — | Confirma comando shell perigoso | ### Exemplos ```bash theme={"system"} # Cron diário /schedule backup --cron "0 2 * * *" --do "/run backup --full" # Um-shot com wait /schedule deploy --when +0s --do "shell: terraform apply -auto-approve" \ --wait "k8s:deployment/prod/api:Available" --timeout 15m \ --triggers smoke-tests # Interval com tag /schedule health-check --every 30s --do "/run healthcheck prod" --tag env=prod # Manual (só dispara via triggers do pai) /schedule notify --when manual --do "POST https://slack.webhook | deploy done" ``` *** ## Comando `/wait` — bloquear até condição Açúcar sintático para "esperar que X aconteça e opcionalmente fazer Y". ```bash theme={"system"} /wait --until [--then ] [flags] ``` ### DSL de condições | Sintaxe | Evaluator interno | Exemplo | | ------------------------------- | ------------------------- | ----------------------------------- | | `http://host/path==200` | `http_status` | Aguarda HTTP 200 | | `http://host~=/ok/` | `http_status` (regex) | Aguarda regex bater no body | | `tcp://host:port` | `tcp_reachable` | Aguarda porta TCP aberta | | `k8s://:` | `k8s_resource_ready` | `k8s:pod/prod/api:Ready` | | `k8s:/` | `k8s_resource_ready` | Namespace default, condição `Ready` | | `docker::running` | `docker_running` | Container rodando | | `docker::healthy` | `docker_running` | Container com healthcheck OK | | `file:/path` | `file_exists` | Arquivo existe | | `file:/path>=100` | `file_exists` (min\_size) | Arquivo ≥ 100 bytes | | `shell: ` | `shell_exit` | Shell retorna 0 | | `~=/pattern/` | `regex_match` | Output do cmd casa regex | | `llm: ` | `llm_check` | LLM responde YES à pergunta | | `and(, , ...)` | `all_of` | Todos satisfeitos | | `or(, , ...)` | `any_of` | Qualquer um satisfeito | | `not ` | `negate` | Nega a expressão filha | ### Exemplos ```bash theme={"system"} # Esperar o endpoint ficar saudável e rodar smoke test /wait --until http://localhost:8080/health==200 --then "/run smoke" --every 5s --timeout 10m # Async: registra e volta imediato; você vê em /jobs list /wait --until "k8s:pod/prod/api-*:Ready" --async --name api-ready # Composta: porta aberta E arquivo de lock removido /wait --until "and(tcp://db:5432, not file:/tmp/migrating)" --then "/run app restart" ``` ### Timeouts * **`--on-timeout fail`** (padrão) — marca como `timed_out` e encerra. * **`--on-timeout fire_anyway`** — roda a ação mesmo sem a condição satisfeita. * **`--on-timeout fallback`** — roda o action alternativo definido em `WaitSpec.Fallback` (via JSON spec) e depois falha. *** ## Comando `/jobs` — gerenciar ```bash theme={"system"} /jobs list # ativos (pending, blocked, waiting, running, paused) /jobs list --all # inclui terminais /jobs list --status running /jobs list --owner me /jobs list --tag env=prod --name backup /jobs show # detalhe completo + histórico de execuções /jobs tree # DAG ASCII (depends_on / triggers) /jobs logs # histórico de execuções (falhas, outputs) /jobs history # jobs terminais (alias de list --all filtrado) /jobs cancel [motivo...] /jobs pause /jobs resume /jobs daemon # status do daemon ou in-process /jobs gc # força snapshot + WAL garbage collection ``` O autocomplete (pressione Tab) sugere: * Subcomandos (`list`, `show`, `cancel`, …) * IDs reais dos jobs para `show`/`cancel`/`pause`/`resume`/`logs` * Valores para `--status` (pending, running, waiting, …) e `--owner` (me, user, agent, worker, system, hook) *** ## Daemon mode ### Ciclo de vida ```bash theme={"system"} chatcli daemon start [--detach] [--socket ] chatcli daemon stop [--socket ] chatcli daemon status [--socket ] chatcli daemon ping [--socket ] chatcli daemon install # imprime template systemd/launchd ``` * **`--detach`** faz re-exec com `setsid` (Unix) / `CREATE_NEW_PROCESS_GROUP` (Windows), libera o terminal. Log vai para `/daemon.log`. * O CLI interativo auto-detecta um daemon na socket configurada e vira **thin client** — `/schedule`, `/wait`, `/jobs` round-trip por IPC. * Stale sockets (processo morto) são limpos automaticamente antes de `start`. ### Protocolo IPC Socket UNIX com frames de 4-byte length-prefix + JSON payload. Kinds suportados: * `ping`, `bye` — health/close * `enqueue`, `cancel`, `pause`, `resume`, `query`, `list`, `snapshot`, `stats` — operações * `subscribe` — server-sent events para UI **Durabilidade** é idêntica ao in-process: WAL fsync antes de admitir, snapshot periódico, replay on boot. ### systemd / launchd `chatcli daemon install` imprime um template pronto para colar em `/etc/systemd/system/chatcli-scheduler.service` ou `~/Library/LaunchAgents/`. *** ## `@scheduler` — tool para agents Dentro do ReAct loop, o agent pode chamar `@scheduler` com 5 subcomandos. Isso permite agents plancjar pausas autônomas. ```xml theme={"system"} ``` Subcomandos: | `cmd` | Args shape | Retorna | | ---------- | ------------------------------------------------------------------ | -------------------------------------------------- | | `schedule` | `{name, when, do, wait?, timeout?, depends_on?, triggers?, ...}` | `{job_id, status, summary}` | | `wait` | `{until, every?, timeout?, async?, then?}` | Sync: `{outcome, job}` · Async: `{job_id, status}` | | `query` | `{id}` | Job completo (status, history, transitions) | | `list` | `{filter?: {owner, statuses, tag, name_substr, include_terminal}}` | `{jobs: [...]}` | | `cancel` | `{id, reason?}` | `{ok, job_id}` | Owner do agent é preservado automaticamente — `filter.owner == OwnerAgent` por default no `list`, e agents só podem cancelar jobs que criaram (ou jobs de workers filhos). *** ## Evaluators e actions — plug-in registry ### Evaluators builtin Cada um implementa `ConditionEvaluator` em `cli/scheduler/condition/`: Executa comando, compara exit code com `expected` (default 0). GET/POST para URL, matching exato ou por regex no body. Presença de arquivo, tamanho mínimo, mtime estável. `kubectl get` + jsonpath; Pod, Deployment, StatefulSet, Service, etc. `docker inspect`; running + healthcheck. Dial TCP com timeout. Shell cmd + regex contra stdout/stderr/combined. LLM headless responde YES/NO à sua pergunta. User script — args via env `CHATCLI_SCHEDULER_SPEC`. Composite com curto-circuito e negação por filho. ### Actions builtin Em `cli/scheduler/action/`: * **slash\_cmd** — invoca `/foo args` via command handler. * **shell** — comando shell sob CoderMode safety (allowlist/denylist de `/config security`). * **agent\_task** — boota ReAct loop com a tarefa. * **worker\_dispatch** — single-agent worker invocation. * **llm\_prompt** — LLM call headless, opção de append na history. * **webhook** — HTTP POST/GET/PUT com JSON body, headers, expected status. * **hook** — fire hook chatcli por evento. * **noop** — útil para pipelines só com Triggers. * **agent\_resume** — retoma um agent estacionado via `@park`. Carrega snapshot, reentra o ReAct loop com a history restaurada. Veja [Agent Park & Resume](/pt/features/agent-park). * **park\_poll** — driver de polling do `@park for_url` / `for_cmd`. Roda a cada interval; ao casar `success_when` ou estourar deadline, dispara um `agent_resume`. Self-rescheduling crash-safe. *** ## Durabilidade ### WAL (Write-Ahead Log) * Um arquivo por job: `~/.chatcli/scheduler/wal/.wal` * Framing: `magic[4] | length[4] | crc32[4] | payload | crc32[4]` — duplo CRC detecta torn writes. * Atomic write via `tmp+rename` + `dir fsync`. * Arquivos corrompidos viram `.wal.corrupt` para inspeção. ### Snapshot * Escrito a cada `SNAPSHOT_INTERVAL` (padrão 5min) em `snapshot.json`. * Atomic replace via tmp-rename. * Boot preferencial: snapshot → overlay com qualquer `.wal` mais novo. ### Replay on boot * Jobs `Running` ou `Waiting` no momento do crash voltam a `Pending` com `Attempts` preservado. * Missed fires respeitam `MissPolicy`: * **`fire_once`** (padrão) — coalesce de todos os ticks perdidos em um único fire. * **`fire_all`** — fire por cada tick perdido (opt-in, pode saturar). * **`skip`** — ignora a janela perdida, forward pra próxima. ### Garbage collection * Jobs terminais ficam `TTL` em disco (padrão 24h) para `/jobs history`. * GC loop (`WAL_GC_INTERVAL`, padrão 1h) unlink `.wal` expirados. *** ## Segurança ### Action allowlist `CHATCLI_SCHEDULER_ACTION_ALLOWLIST` controla quais tipos de action podem ser agendados. Default: ``` slash_cmd, llm_prompt, agent_task, worker_dispatch, hook, noop, webhook, shell ``` Cada action passa pela sua porta de segurança específica: * `shell` → **preflight + re-check no fire contra CoderMode** (ver próxima seção). * `webhook` → http.Client com timeout e max response size. * `agent_task` → reenter ReAct loop que mantém sua própria policy interativa. * `slash_cmd` → vai pelo CommandHandler do CLI (sujeito ao fluxo normal da sessão). ### Preflight CoderMode para shell O scheduler **nunca prompta interativamente**. Em modo daemon não existe usuário presente; em cron noturno o usuário pode estar offline. Então **toda aprovação acontece na hora do `/schedule`**, não no fire. Todo comando shell embutido num job (na `Action`, no `Wait.Condition` ou nos filhos de composites `all_of`/`any_of`) passa pelo `PolicyManager` do CoderMode — o mesmo que `/coder` e `/agent` usam interativamente. Três resultados: | Classificação | Comportamento no scheduler | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | **Allow** (allowlist match ou read-only conhecido tipo `kubectl get`) | ✅ job admitido | | **Deny** (denylist match) | ❌ rejeita no `/schedule` com `ErrShellPolicyDeny`. **Denylist bate `--i-know`** — não é override. | | **Ask** (fora da allowlist, comando desconhecido) | ⚠️ rejeita com `ErrShellPolicyAsk` **a menos que** o job tenha `DangerousConfirmed=true` (via `--i-know`) | O preflight acontece **antes do WAL write**, então jobs perigosos nunca chegam a ficar persistidos. E no fire, o `RunShell` do bridge **re-carrega a policy do disco e re-classifica** — se o operator adicionou uma Deny rule entre o schedule e a execução, o job falha em vez de rodar. ### Como editar a policy do CoderMode `/config security` agora é **hierárquico**. A forma sem subcomando continua mostrando o panorama read-only; subcomandos novos mutam o `PolicyManager` ao vivo e persistem em `~/.chatcli/coder_policy.json`: ```bash theme={"system"} /config security # dump read-only (como antes) /config security rules # lista rules ativas agrupadas por action /config security allow "@coder exec my-tool" # adiciona ALLOW /config security deny "@coder exec rm -rf /" # adiciona DENY (confirma [y/N]) /config security forget "" # remove rule (confirma [y/N]) /config security reload # relê o JSON do disco ``` Fluxo típico depois do `/schedule` reclamar: ``` ❯ /schedule backup --when +5m --do "shell: my-tool --backup" ❌ scheduler: shell command requires approval: my-tool --backup ❯ /config security allow "@coder exec my-tool" ✔ rule ALLOW adicionada: @coder exec my-tool persistido em ~/.chatcli/coder_policy.json ❯ /schedule backup --when +5m --do "shell: my-tool --backup" ✔ Job a1b2c3 criado (backup). ``` **Confirmação destrutiva:** `deny` e `forget` sempre perguntam `[y/N]`. `allow` pergunta apenas quando o pattern é "amplo" (ex: `@coder exec` sozinho ou um sufixo muito curto). Adicione `--yes` / `-y` para pular o prompt em scripts. **Scope das mudanças:** `allow` / `deny` / `forget` atualizam o JSON imediatamente; o CLI interativo (`workerPolicyAdapter`) recarrega a cada prompt Ask, e o scheduler recarrega a cada `RunShell`. Se você editou o JSON externamente, use `/config security reload` para forçar todos os caches a re-lerem. Os caminhos alternativos (mais antigos) continuam válidos: 1. **Pelo prompt interativo do `/coder`** — escolher "Allow always" ou "Deny forever" num safety prompt também persiste a rule via `PolicyManager.AddRule`. Mesma infraestrutura do `/config security allow/deny`. 2. **Editar `~/.chatcli/coder_policy.json` direto** — útil para onboarding em lote (copiar um coder\_policy.json pronto pro time), ou para regras por-projeto em `/coder_policy.json` (merged com a global). ```json theme={"system"} { "rules": [ {"pattern": "@coder exec my-proprietary-tool", "action": "allow"}, {"pattern": "@coder exec rm -rf /", "action": "deny"} ], "merge": true } ``` A pattern usa prefix match sobre ` ` como o PolicyManager normaliza. Deny sempre bate allow. ### `--i-know` e `i_know` (agents) Quando você quer agendar um comando fora da allowlist sem adicioná-lo permanentemente: ```bash theme={"system"} /schedule custom-probe --when +30s \ --do "shell: my-proprietary-tool --probe" \ --i-know ``` Isso seta `Job.DangerousConfirmed=true` e o job passa pelo preflight mesmo com classificação `Ask`. Denylist **continua** bloqueando — `--i-know` não sobrepõe um `deny` explícito. Agents também têm a forma equivalente via tool call: ```xml theme={"system"} ``` A autorização aqui é implícita: você já autorizou o agent quando rodou `/agent`. Se quiser travar agents de usarem `i_know`, configure `CHATCLI_SCHEDULER_ALLOW_AGENTS=false` ou mantenha os comandos perigosos na denylist (agents nunca conseguem burlar denylist). ### Bypass total (trusted automation) Para automações internas em ambiente confiável, você pode desligar a checagem de policy inteiramente por-job: 1. Operator permite: `CHATCLI_SCHEDULER_SHELL_ALLOW_BYPASS=true` 2. Job cria com `bypass_safety: true` no spec JSON da action: ```json theme={"system"} {"type": "shell", "payload": {"command": "...", "bypass_safety": true}} ``` **Evite** — quase sempre o caminho correto é aprovar o comando uma vez via `/coder` (escolher "Allow always") ou usar `--i-know` explicitamente no `/schedule`. Bypass é para CI/CD em containers efêmeros onde a sandbox é o isolamento. ### Rate limiting Token-bucket global + per-owner com tolerância de nanodelay: ``` CHATCLI_SCHEDULER_RATE_LIMIT_GLOBAL_RPS=5.0 # default CHATCLI_SCHEDULER_RATE_LIMIT_GLOBAL_BURST=20 CHATCLI_SCHEDULER_RATE_LIMIT_OWNER_RPS=1.0 CHATCLI_SCHEDULER_RATE_LIMIT_OWNER_BURST=10 ``` Um agent em ReAct loop runaway não consegue inundar a fila — o rate limiter rejeita com `Retry-After` hint. ### Circuit breakers Um breaker por evaluator type e um por action type, com `closed → open → half_open` classic: ``` CHATCLI_SCHEDULER_BREAKER_FAILURE_THRESHOLD=5 CHATCLI_SCHEDULER_BREAKER_WINDOW=60s CHATCLI_SCHEDULER_BREAKER_COOLDOWN=30s ``` Se o k8s API cair, o breaker `k8s_resource_ready` abre e todos os jobs dependentes fail-fast com `ErrBreakerOpen` em vez de saturar o worker pool. ### Audit log Toda mutação (create, transition, cancel, fire) escreve uma linha JSON em `~/.chatcli/scheduler/audit.log`. Rotação por lumberjack (padrão 10 MiB, 7 backups, 30 dias). ### Autorização * `OwnerUser` e `OwnerSystem` podem cancelar qualquer job. * `OwnerAgent` só pode cancelar jobs próprios ou de workers filhos. * Cross-owner cancel retorna `ErrNotAuthorized` e fire hook `PreJobCancel` para auditoria. *** ## Observabilidade ### Métricas Prometheus | Métrica | Tipo | Labels | | ------------------------------------------- | --------- | ---------------------------------------------- | | `chatcli_scheduler_jobs_created_total` | Counter | `owner_kind`, `action_type` | | `chatcli_scheduler_jobs_fired_total` | Counter | `outcome`, `action_type` | | `chatcli_scheduler_wait_checks_total` | Counter | `condition_type`, `satisfied` | | `chatcli_scheduler_wait_duration_seconds` | Histogram | `condition_type` | | `chatcli_scheduler_action_duration_seconds` | Histogram | `action_type`, `outcome` | | `chatcli_scheduler_queue_depth` | Gauge | — | | `chatcli_scheduler_active_jobs` | Gauge | — | | `chatcli_scheduler_breaker_state` | Gauge | `kind`, `key` (0=closed, 1=open, 2=half\_open) | | `chatcli_scheduler_retries_total` | Counter | `attempt` (bucketed 1/2/3/4+) | | `chatcli_scheduler_enqueue_errors_total` | Counter | `reason` (rate\_limited, full, invalid, …) | | `chatcli_scheduler_wal_segments` | Gauge | — | | `chatcli_scheduler_audit_writes_total` | Counter | — | | `chatcli_scheduler_daemon_connections` | Gauge | — | ### Events Scheduler publica no `cli/bus` e dispara hooks chatcli: * `job.created`, `job.scheduled`, `job.fired` * `job.wait_started`, `job.wait_tick`, `job.wait_satisfied` * `job.running`, `job.completed`, `job.failed`, `job.timed_out`, `job.cancelled`, `job.skipped` * `job.retry_queued`, `job.paused`, `job.resumed`, `job.dependency_resolved` * `breaker.opened`, `breaker.half_open`, `breaker.closed` * `daemon.started`, `daemon.stopped` Hooks recebem `Scheduler.` como `HookEvent.Type` — você pode amarrar um Slack webhook em `Scheduler.job.failed` via `~/.chatcli/hooks.json`. ### Status line no prompt Quando há jobs ativos, o prefix do prompt ganha `[jobs: 2▶ 1⏳ 1✗]`: * `▶` running * `👁` waiting (em polling) * `⏳` pending * `⛓` blocked (aguardando deps) * `✗` failed *** ## Configuração completa Veja [Variáveis de Ambiente → Scheduler](/pt/reference/environment-variables#scheduler) para as \~25 env vars. ### `/config scheduler` ``` ❯ /config scheduler ⏲ Scheduler (Chronos) — Agendamento & Wait-Until Núcleo CHATCLI_SCHEDULER_ENABLED: enabled CHATCLI_SCHEDULER_DATA_DIR: ~/.chatcli/scheduler CHATCLI_SCHEDULER_MAX_JOBS: 256 CHATCLI_SCHEDULER_WORKER_COUNT: 4 CHATCLI_SCHEDULER_ALLOW_AGENTS: enabled CHATCLI_SCHEDULER_ACTION_ALLOWLIST: slash_cmd,shell,agent_task,... Budget Padrão CHATCLI_SCHEDULER_DEFAULT_ACTION_TIMEOUT: 5m CHATCLI_SCHEDULER_DEFAULT_POLL_INTERVAL: 5s CHATCLI_SCHEDULER_DEFAULT_WAIT_TIMEOUT: 30m ... Daemon CHATCLI_SCHEDULER_DAEMON_SOCKET: /tmp/chatcli-scheduler.sock CHATCLI_SCHEDULER_DAEMON_AUTO_CONNECT: enabled Active jobs: 3 Queue depth: 2 WAL segments: 11 Daemon: connected @ /tmp/chatcli-scheduler.sock ``` *** ## Arquitetura interna (resumida) ``` ┌──────────────────────────────────────────────────────────────┐ │ ChatCLI process │ │ │ │ /schedule ─┐ │ │ /wait ─┼──▶ Scheduler ◀──▶ WAL + snapshot │ │ /jobs ─┘ │ │ │ @scheduler ────────┤ │ │ │ │ │ ├──▶ Condition evaluators (plug-in) │ │ ├──▶ Action executors (plug-in) │ │ ├──▶ Rate limiter (global + per-owner) │ │ ├──▶ Circuit breakers (cond + action) │ │ ├──▶ bus.EventBus + hook manager │ │ └──▶ audit log (JSONL) + Prometheus │ └──────────────────────────────────────────────────────────────┘ │ ▼ (opcional) UNIX socket ─▶ chatcli-daemon (mesma binary, --detach) ``` * **Schedule pump** (1 goroutine) drena a priority queue por `NextFireAt`. * **Worker pool** (N goroutines = `WORKER_COUNT`) executa handleJob (wait → action → finalize). * **Snapshot loop** (1 goroutine) freeze periódico. * **GC loop** (1 goroutine) reap terminais expirados. *** ## Próximos passos Exemplos práticos: deploy com wait, cron de backup, pipeline com DAG. Tabela completa de flags e subcomandos. Todas as 25+ variáveis do scheduler. Amarrar webhooks Slack/PagerDuty nos eventos do scheduler.