agora-creations/mikros

Testando fluxos de trabalho megálos

1. Escopo e não-objetivos

Este skill ensina um agente de IA de codificação a verificar o comportamento de um arquivo YAML de fluxo de trabalho megálos antes de sua implantação. A superfície primária é a CLI de dry-run (python -m megalos_server.dryrun), que percorre um fluxo de trabalho pelo runtime de produção com uma fonte de entrada simulada no lugar de um LLM real. O dry-run responde à pergunta: "dadas essas respostas simuladas, este fluxo de trabalho segue, ramifica, avalia, desce e termina da maneira que o autor pretendia?" Ele é rápido, offline e determinístico; não faz chamadas a LLM nem viagens de ida e volta ao MCP. Uma execução ao vivo contra uma implantação real de megálos está disponível como uma superfície secundária limitada para os casos que o dry-run não alcança — ramificações de saída com LLM real e digressões de mcp_tool_call do registro real — e é abordada na §6 (elaborada em uma tarefa posterior).

No escopo. A receita interativa de dry-run (§3). Fixtures de respostas roteirizadas (§4) para repetição de regressão. Erros de carregamento entre fluxos de trabalho — unknown_call_target e call_cycle_detected — e como o dry-run os expõe via bootstrap create_app() (§5). Contratos de código de saída e banner de erro que o agente deve ler.

Fora do escopo. Validação de fluxo de trabalho por arquivo — coberta pelo skill complementar validating-workflows. Criação de fluxos de trabalho — coberta por authoring-workflows. Empacotamento de repositório de domínio, implantação no Horizon e configuração de registro — cobertos por deploying-workflows. Testes de nível de framework e contribuições de fixtures de fluxo de trabalho para o próprio repositório megálos: pytest/conftest não é uma superfície que este skill ensina. O skill testing-workflows verifica o comportamento do fluxo de trabalho com dry-run; a criação de testes de framework é uma atividade distinta para contribuidores do megálos e está explicitamente fora do escopo. Invocação real de LLM — o dry-run nunca chama um LLM; autores que precisam de um LLM real no loop recorrem à superfície de execução ao vivo (§6) ou a uma instância implantada.

Público-alvo. O leitor é um agente de IA de codificação agindo em nome de um autor de fluxo de trabalho. O design do dry-run enquadra explicitamente este público: autores não são engenheiros de teste. Um autor de fluxo de trabalho precisa ver o template da diretiva renderizado, as avaliações listadas e o feedback do esquema em cada etapa — não escrever um caso pytest. As receitas interativa e roteirizada de dry-run abaixo são moldadas para esse público.

2. Dry-run como modo primário

python -m megalos_server.dryrun carrega um fluxo de trabalho e o percorre pelo caminho de execução de produção, lendo a "resposta LLM" simulada de cada etapa da stdin (ou de um arquivo YAML roteirizado — veja §4) em vez de chamar um modelo. O dry-run não é um simulador paralelo; é o runtime de produção com uma fonte de entrada simulada. O mesmo start_workflow, submit_step, classificação, validação output_schema, contabilização de repetições, seleção de ramificações e descida em sub-fluxo que um servidor ao vivo executa são o que o dry-run executa. Qualquer coisa que o dry-run aceite, o servidor aceita; qualquer coisa que o dry-run rejeite no bootstrap, o servidor rejeita na inicialização.

O que o dry-run exercita. Renderização de etapas (banner, pré-condição, avaliações, diretiva). Validação output_schema e a superfície de repetições (dicas de validação, contagens de repetições restantes, esgotamento de orçamento). Seleção de ramificações e resolução de ramificação padrão. Detecção de salto por pré-condição — quando a precondition: de uma etapa não é atendida em tempo de execução, o dry-run imprime Skipped: <step_id> em stdout e avança (veja §3 para o contrato da superfície; §9 para a forma de erro comum). Descida em sub-fluxo e retomada do pai. Verificações em tempo de carregamento do create_app() sobre todo o conjunto de fluxos de trabalho no diretório pai do alvo, incluindo unknown_call_target e call_cycle_detected (§5).

O que o dry-run não exercita. Qualidade de geração real de LLM. Viagens de ida e volta reais ao registro MCP (etapas mcp_tool_call são cobertas por verificações estruturais e de esquema em tempo de carregamento, mas uma chamada real ao registro é uma preocupação de execução ao vivo). Persistência de sessão, latência ou concorrência em escala de produção. Quando o autor precisa verificar qualquer um destes, a superfície de execução ao vivo é a ferramenta (§6).

Contrato de código de saída. O dry-run sai com 0 em workflow_complete e 1 em qualquer outro status terminal — o frozenset de _TERMINAL_STATUSES de produção é {"workflow_complete", "error", "session_escalated", "workflow_changed"}. Uma saída não zero sempre é acompanhada por um banner de erro decodificado em stderr. Scripts em torno do dry-run (testes de fumaça em CI, verificações de pre-commit) devem tratar a saída 0 como o único verde.

3. Receita interativa de dry-run

O modo interativo é o caso comum: o agente (ou seu operador humano) digita uma resposta LLM simulada em cada etapa e observa o fluxo de trabalho se desenrolar. Invocação:

python -m megalos_server.dryrun workflows/my_workflow.yaml

O dry-run carrega cada arquivo *.yaml no diretório pai do alvo (necessário para que os alvos call: de sub-fluxo possam ser resolvidos — veja §5), então inicializa o fluxo de trabalho e entra em um REPL. Em cada etapa, o runtime renderiza um banner, a linha opcional de pré-condição, quaisquer avaliações e o template da diretiva da etapa, então solicita com > . O agente digita uma resposta LLM simulada e pressiona enter. O fluxo de trabalho avança.

Uma sessão mínima de fluxo de trabalho linear de três etapas se parece com isso:

$ python -m megalos_server.dryrun workflows/example.yaml

=== Step: alpha — Primeira etapa ===
<template da diretiva renderizado aqui>
> ok

=== Step: bravo — Segunda etapa ===
<template da diretiva renderizado aqui>
> ok

=== Step: charlie — Terceira etapa ===
<template da diretiva renderizado aqui>
> ok

Workflow complete

Código de saída 0. Três respostas simuladas conduziram três etapas a workflow_complete.

Solicitações que o agente pode encontrar.

• Solicitação de resposta da etapa (> ). A solicitação padrão em cada etapa. Qualquer coisa que o agente digite é alimentada ao runtime como se um LLM a tivesse produzido. Para etapas com um output_schema, a resposta deve ser um JSON válido correspondente ao esquema; uma carga JSON inválida aciona um erro de validação (com uma linha Retries remaining: N em stderr) e re-solicita na mesma etapa. Esgotar o orçamento de repetições termina a execução com um banner Max retries (N) exceeded e saída 1.

• Solicitação de seleção de ramificação. Quando uma etapa com um bloco branches: é alcançada, o dry-run primeiro consome uma resposta da etapa, então imprime:

  Branches:
    1. first_branch_target
    2. second_branch_target [default]
  Choose branch [1-2, empty = default]: 
  

  A tag [default] marca a ramificação escolhida quando o seletor avalia a resposta da etapa. Uma entrada vazia resolve para o padrão.

• Linha de pré-condição. Etapas com uma precondition: a renderizam na entrada como Precondition: <ref> == "<value>" ou Precondition: <ref> is present, antes da diretiva.

• Superfície de salto (Skipped: <step_id>). Quando a pré-condição de uma etapa não é atendida em tempo de execução, o dry-run não renderiza o banner ou a solicitação dessa etapa; em vez disso, imprime Skipped: <step_id> em stdout e avança para a próxima etapa. A linha Precondition: renderizada anteriormente na etapa anterior é a explicação implícita. A detecção de salto sinaliza apenas etapas com pré-condição; ramificações alternativas que simplesmente não foram seguidas não são "puladas" — são um caminho não alcançado. Uma execução que pula involuntariamente uma etapa ainda termina com workflow_complete na saída 0, então o único sinal de um salto não intencional é a linha Skipped: em stdout. Leia cada linha Skipped: e confirme que a pré-condição que suprimiu a etapa deveria supri-la.

• EOF (Ctrl-D). Fechar stdin no meio do fluxo de trabalho aborta com Dry-run aborted by user (EOF) em stderr e saída 1.

Descida em sub-fluxo. Quando o alvo call: de uma etapa resolve para um fluxo de trabalho irmão, o dry-run imprime Entering sub-workflow <name> e indentifica os banners do filho em dois espaços por nível de aninhamento. No workflow_complete do filho, o dry-run imprime Returned from sub-workflow e retoma o pai na próxima etapa.

Disciplina de diretório limpo. Como o dry-run carrega todos os *.yaml no diretório pai, um YAML irmão quebrado impede o carregamento do alvo. Se o banner de erro em tempo de inicialização nomear um arquivo diferente do alvo, a culpa é de um irmão — corrija-o ou mova o alvo para um diretório que contenha apenas ele e seus alvos call:. O parágrafo de enquadramento que o dry-run imprime na falha de carregamento é:

Failed to load workflows from <parent_dir>: <exception>
Note: dry-run loads all *.yaml files in the parent directory (required
for sub-workflow 'call' target resolution). If the error above names a
file other than <target.yaml>, a sibling workflow has a problem — fix
it, or move <target.yaml> to a directory containing only it and its
call targets.

4. Fixtures de respostas roteirizadas

Para repetição de regressão e testes de fumaça em CI, o dry-run aceita um --responses-file apontando para uma fixture YAML que conduz o fluxo de trabalho de forma não interativa:

python -m megalos_server.dryrun workflows/my_workflow.yaml \
    --responses-file tests/responses/my_workflow_happy.yaml

O arquivo de respostas tem uma forma fixa: um mapeamento de nível superior com uma chave version: 1 obrigatória e uma lista entries: obrigatória. Cada entrada é um mapeamento com um step_id: obrigatório e exatamente um de response: (para conteúdo da etapa) ou branch: (para solicitações de seleção de ramificação) — nunca ambos, nunca nenhum. Uma fixture mínima de caminho feliz de três etapas:

version: 1
entries:
  - step_id: alpha
    response: ok
  - step_id: bravo
    response: ok
  - step_id: charlie
    response: ok

Consumo ordenado. No quadro do fluxo de trabalho raiz (profundidade de descida 0), as entradas são consumidas em ordem: a primeira entrada deve corresponder ao step_id da primeira etapa, a segunda entrada à segunda etapa e assim por diante. Um desvio de grafia ou ordem aborta a execução. Durante a descida em sub-fluxo (profundidade > 0), o dry-run percorre entradas não correspondentes até que uma correspondência seja encontrada, então entradas do quadro pai e do quadro filho podem ser intercaladas na ordem do arquivo — mas as próprias entradas de cada quadro devem aparecer na ordem de execução desse quadro.

Banners de detecção de desvio. O analisador e a camada de consumo roteirizado imprimem banners literais em stderr antes de sair com 1. Os autores verão exatamente essas strings quando uma fixture estiver errada:

• Campo de versão ausente: Responses file missing required 'version' field. Expected: version: 1
• Versão desconhecida: Unknown responses-file version: <n>. Supported: [1]
• Exclusão mútua response/branch (ambos presentes): ... must have exactly one of 'response' or 'branch', not both.
• Exclusão mútua response/branch (nenhum presente): ... must have exactly one of 'response' or 'branch'.
• Desvio de step-id na profundidade raiz: Script entry expected step_id=<entry_step>, REPL at step_id=<repl_step>
• Incompatibilidade de tipo de entrada (etapa esperava resposta, roteiro forneceu ramificação): At step <repl_step>, expected step response but script provided branch selection (ou, simetricamente, expected branch selection but script provided response)
• Esgotamento (poucas entradas): Responses file exhausted at step <repl_step> (expecting: <expected_label>)
• Entradas não utilizadas na conclusão (muitas entradas): Responses file had <N> unused entries after workflow completion

A proteção de entradas não utilizadas é executada no workflow_complete imediatamente antes da saída da execução; uma fixture mais longa que o necessário é um erro de script, não uma aprovação silenciosa. Cada caso de desvio sai com 1, então CI que trata a saída 0 como verde falhará ruidosamente em qualquer um dos acima.

Paridade de cobertura com o modo interativo. O modo roteirizado conduz a mesma superfície que o modo interativo: validação output_schema e banners de repetição (uma response: inválida aciona o mesmo re-prompt de erro de validação), seleção de ramificação (via entradas branch:) e descida em sub-fluxo (com entradas pai/filho intercaladas). Uma fixture roteirizada que percorre um fluxo de trabalho de ponta a ponta é o artefato de regressão canônico para esse fluxo de trabalho.

5. Erros de carregamento entre fluxos de trabalho — unknown_call_target e call_cycle_detected

Dois erros entre fluxos de trabalho aparecem no tempo de carregamento do conjunto de fluxos, não na validação por arquivo. Ambos são emitidos a partir da mesma passagem que o skill validating-workflows sinalizou como uma referência direta:

Uma nuance que vale a pena internalizar: esses dois erros aparecem no tempo de carregamento do conjunto de fluxos de trabalho, não sob uma execução python -m megalos_server.validate <file> por arquivo. O validador por arquivo cobre apenas as próprias regras estruturais e semânticas do fluxo de trabalho externo; ele não pode saber sobre os outros fluxos de trabalho que o servidor eventualmente carregará. As verificações de alvo de chamada e ciclo são executadas dentro do create_app() do servidor depois que todos os YAMLs de fluxo de trabalho no diretório de fluxos foram carregados individualmente, e eles são executados antes de o aplicativo MCP ser construído. Na prática, isso significa: um agente que cria ou modifica um fluxo de trabalho com uma etapa call: deve carregar o conjunto completo de fluxos de trabalho no servidor para expor unknown_call_target e call_cycle_detected, ou usar a superfície de teste coberta em testing-workflows. Uma execução verde de validação por arquivo é uma condição necessária, mas não suficiente, para um servidor carregável.

Esta seção é essa superfície de teste. As formas literais de f-string que o carregador emite são:

Workflow '<parent_name>' step '<step_id>' calls unknown workflow '<target>' (code: unknown_call_target)

call cycle detected: <wf_a> -> <wf_b> -> ... -> <wf_a> (code: call_cycle_detected)

Como o dry-run os expõe. O bootstrap do dry-run chama create_app(workflow_dir=<diretório pai do alvo>). create_app() carrega cada *.yaml naquele diretório e, em seguida, executa a passagem de resolução de chamada entre fluxos de trabalho antes de o aplicativo MCP ser construído. Se qualquer alvo call: não resolver para um fluxo de trabalho carregado, ou se o grafo de chamada contiver um ciclo, o carregamento falha com o código de erro acima e o dry-run sai com 1 no bootstrap, antes de o REPL começar. A falha é envolvida no parágrafo de enquadramento mostrado na §3 ("dry-run loads all *.yaml files in the parent directory …") para que o autor possa ver qual arquivo está implicado.

A implicação prática. Uma execução por arquivo python -m megalos_server.validate <file> não pode expor unknown_call_target ou call_cycle_detected. O dry-run e sua execução ao vivo são as únicas superfícies que o fazem. Um autor que adiciona ou modifica uma etapa call: deve sempre iniciar um dry-run para confirmar que o alvo da chamada existe e o grafo está livre de ciclos, mesmo que a forma da etapa de chamada em si pareça correta sob validação por arquivo.

Cobertura de dry-run para referências circulares. Não há entry point separado para verificação de ciclo. O ciclo é descoberto durante o bootstrap — se o dry-run não iniciar porque call_cycle_detected foi emitido, o autor corrige a cadeia de chamada e tenta novamente. O parágrafo de enquadramento (veja §3) identifica o diretório e o alvo; o banner de erro dá o caminho do ciclo. O autor então inspeciona manualmente (ou com a ajuda do agente) cada call: na cadeia para quebrar o ciclo.