graph

Habilidade Graph

Execute um grafo de orquestração determinística a partir de um descritor JSON declarativo. O runtime consome os contratos de descritor lacrado e escalonador puro em src/graph/* e executa por meio de um processo independente (omc graph run), então a recuperação de falhas (mate no meio da execução, execute novamente, retome do journal) funciona de verdade.

Uso

/oh-my-claudecode:graph <descritor.json>
/oh-my-claudecode:graph "build depois test depois pergunte antes de deploy"   (crie o descritor primeiro)

A superfície de execução é sempre o subcomando CLI:

omc graph run <descritor.json> [--runs-root <dir>]

Execute-o via a ferramenta Bash para gráficos não interativos. As linhas de progresso são transmitidas como [run], [node], [ok], [fail], [join], [done].

Quando Usar

• Pipelines multi-etapas repetíveis com dependências explícitas (DAG)
• Trabalhos que devem sobreviver a interrupções: mate/reinicie retoma do journal
• Execuções auditáveis: journal + snapshots de projeção sob .omc/graph-runs/<run_id>/

Quando NÃO usar: trabalhos exploratórios únicos (use conversa ou /team); qualquer coisa que precise de replanejamento adaptativo no meio da execução (gráficos são determinísticos).

Fluxo de Trabalho

1. Descritor fornecido -> vá para o passo 3.

2. Pipeline descrito -> crie o descritor JSON (esquema abaixo), escreva-o próximo ao projeto (sugira .omc/graphs/<nome>.json) e mostre-o ao usuário antes de executar. run_id deve ser único por pipeline lógico; reexecutar com o mesmo run_id RETOMA, não reinicia.

3. Nós de aprovação: se o descritor contiver algum nó "kind": "human-approval", NÃO o execute através da ferramenta Bash (stdin não é interativo lá; EOF falha fechado para negado). Diga ao usuário para executar interativamente:

   ! omc graph run <arquivo>
   

   O prefixo ! executa dentro desta sessão com stdin ao vivo, então s/n funciona.

4. Execute e relate o progresso. Códigos de saída (normativos): 0 sucesso | 1 falha terminal | 19 outro escritor possui esta execução (ocupado) 20 journal corrompido/adulterado (falha fechada) | 21 desvio de descritor na retomada | 70 falha do runtime (erro não mapeado)

5. Retomar: reexecutar o mesmo comando após uma falha reproduz as transições confirmadas e continua. Nós concluídos nunca são reexecutados.

Esquema do Descritor (mínimo)

{
  "descriptor_version": 1,
  "run_id": "id-pipeline-unico",
  "revision_id": "rev-1",
  "goal": "uma linha",
  "nodes": [
    { "id": "n1", "kind": "command", "title": "...", "timeout_ms": 60000,
      "max_attempts": 2, "effect_policy": { "policy": "side_effect_free" },
      "command": "npm test" },
    { "id": "a1", "kind": "agent", "title": "...", "timeout_ms": 300000,
      "max_attempts": 1, "effect_policy": { "policy": "side_effect_free" },
      "instructions": "..." },
    { "id": "gate", "kind": "human-approval", "title": "...",
      "prompt": "Prosseguir?" }
  ],
  "edges": [ { "id": "e1", "kind": "fixed", "from": "n1", "to": "a1" } ],
  "entry_node_ids": ["n1"],
  "concurrency_limit": 2,
  "terminal_verification_node_id": "a1"
}

Tipos de aresta: fixed | conditional | fan_out/join pairs | back_edge (retentativas limitadas via max_traversals). Consulte src/graph/schema.ts para o esquema Zod oficial — e leia a seção Limite de Capacidade acima para saber quais executores embutidos realmente executam hoje.

Limite de Capacidade e Semântica (leia antes de criar)

• Suporte a arestas: executores embutidos de comando/agente cobrem arestas fixed e pares fan_out/join. Rotas conditional e back_edge são totalmente suportadas pelos contratos de runtime e escalonador, mas exigem um NodeExecutor personalizado que emita route em seus resultados — executores embutidos nunca produzem rotas, então gráficos que dependem delas falham rapidamente com route_required em vez de adivinhar.
• Garantia de recuperação de falhas é pelo menos uma vez para nós de comando: uma falha entre um efeito colateral externo e seu anexo ao journal reexecuta esse nó na retomada. Para comandos idempotent, a chave resolvida está disponível para o comando como GRAPH_IDEMPOTENCY_KEY antes de iniciar e também é registrada para desduplicação a jusante. Executores embutidos rejeitam reconcile; reconciliação exige um executor personalizado com uma autoridade de reconciliação externa real. Exatamente uma vez para efeitos colaterais externos está fora do escopo para v1.
• Limite de confiança do comando: nós de comando são linhas shell arbitrárias com autoridade de processo no diretório de trabalho atual. Execute apenas descritores que você escreveu ou em que confia. Os filhos do comando recebem um ambiente na lista de permissões (PATH, HOME/USERPROFILE, TEMP/TMP, locale/timezone, identidade do usuário, GRAPH_* e a chave de idempotência opcional), não os segredos completos do host. Comandos não são isolados em sandbox de sistema de arquivos/processo.
• Limite de autoridade do agente: nós de agente embutidos são explicitamente somente leitura. Eles executam no diretório de trabalho atual sem diretórios adicionais, apenas Read, Glob e Grep, permissionMode: dontAsk, persistência de sessão desabilitada e uma lista de permissões de ambiente específica do provedor. Timeouts do agente abortam e interrompem a consulta do SDK. Use um executor personalizado para qualquer agente que precise de mutação ou efeitos externos. Trate .omc/graph-runs/<run_id>/descriptor.json como conteúdo executável.