dag-library

Use esta habilidade quando o usuário quiser GUARDAR uma definição de DAG e executá-la novamente mais tarde — o grafo é um ativo, não algo de uso único. Para criar um grafo totalmente novo, leia mass-ulw primeiro; esta habilidade cobre a parte de armazenamento e reexecução.

A estrutura

Uma definição armazenada é um arquivo JSON de definição de DAG simples chamado <name>.json em um dos diretórios da biblioteca. O primeiro a ser encontrado vence:

1. $OMO_DAG_LIBRARY (múltiplos diretórios, separados por : — ou por ; no Windows, para que caminhos com letras de unidade sobrevivam)
2. $PWD/.omo/dags
3. $HOME/.omo/dags

{
  "key": "nightly-audit",
  "name": "Nightly audit",
  "nodes": [
    { "id": "audit", "category": "unspecified-low", "prompt": "Audit docs/ for stale claims; write findings to /tmp/audit-{{key}}.md." },
    { "id": "verify", "category": "quick", "prompt": "Verify each finding in /tmp/audit-{{key}}.md against src/.", "dependsOn": ["audit"] }
  ]
}

Valores de string podem conter placeholders, preenchidos no momento do carregamento: {{key}} (a chave rotacionada final — use-a em caminhos de arquivo para que as reexecuções nunca se sobreponham), {{date}} (UTC AAAA MM DD), {{datetime}} (UTC AAAA MM DD-HHmmss). Os prompts dos nós ainda devem ser autônomos: dependsOn é apenas para ordenação, então passe dados entre os nós através de arquivos, exatamente como em mass-ulw.

Executando — célula de avaliação JS, duas linhas

A extensão publica library.js ao lado de sdk.js em OMO_DAG_SDK_ROOT:

const lib = await import(`${env("OMO_DAG_SDK_ROOT")}/library.js`)
const run = await lib.start("nightly-audit")
const result = await run.done()

await lib.load(name) retorna a definição preenchida sem iniciá-la; await lib.start(name) carrega e inicia em uma única chamada e retorna a mesma forma de handle que sdk.start (run_id, done(), cancel(reason)). Ambos são assíncronos — o global read do kernel é assíncrono, então nunca os chame sem aguardar.

Rotação de chave — a única regra que importa

O motor DAG baseia a idempotência em key + impressão digital do grafo: reiniciar a mesma chave com o mesmo grafo REUTILIZA a execução antiga em vez de executar novamente. Portanto, a biblioteca trata o key armazenado como uma chave BASE e o rotaciona a cada carregamento:

• lib.start("nightly-audit") → a chave se torna nightly-audit-<UTC YYYYMMDD-HHmmss>: cada chamada é uma nova execução. Este é o padrão porque querer uma nova execução é o caso comum.
• lib.start("nightly-audit", { suffix: "20260818" }) → a chave se torna nightly-audit-20260818: sufixo explícito, então reexecutar a mesma execução lógica a reutiliza (recuperação idempotente), enquanto um novo dia obtém uma nova execução. Recuperar um nó FALHO dentro de tal execução é retry/amend nesse ID de execução, não um novo sufixo.
• lib.start("nightly-audit", { suffix: "" }) → a chave permanece nightly-audit: idempotência total; só use isso quando reutilizar o resultado anterior for exatamente o que você deseja.

Células Python

Python não pode importar a biblioteca ESM. Reproduza a mesma semântica com dicionários simples — leia o arquivo, rotacione a chave, preencha os placeholders, chame tool.workflow:

import json
from datetime import datetime, timezone
defn = json.loads(read(f"{env('HOME')}/.omo/dags/nightly-audit.json"))
stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
defn["key"] = f"{defn['key']}-{stamp}"
text = json.dumps(defn).replace("{{key}}", defn["key"]).replace("{{date}}", stamp[:8]).replace("{{datetime}}", stamp)
run = tool.workflow({"action": "start", "definition": json.loads(text)})
result = tool.workflow({"action": "wait", "run_id": run["run_id"], "detach": False})  # detach=False keeps the cell-blocking wait; the bare tool action detaches against a live run

Salvando uma nova definição

Quando o usuário pede para salvar o grafo atual: escreva-o como <name>.json em $HOME/.omo/dags (nível do usuário, sobrevive a mudanças de cwd) ou <repo>/.omo/dags (nível do projeto, compartilhável via git se a equipe o confirmar), então confirme executando-o uma vez via lib.start. Nomes são letras, dígitos, ponto, traço, sublinhado — a biblioteca rejeita nomes em formato de caminho.