Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/piloto/protocolo.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,8 @@ python3 -m venv .venv

Repita com `--flow catalog --cycle bug`, `--flow orders --cycle feature`, `--flow orders --cycle bug` e `--flow catalog --cycle guardrail`.

Durante a execução, o terminal mostra cada fase do supervisor, as mensagens e ferramentas de cada agente, os bloqueios de guarda-corpo, o custo por agente e as decisões nos gates. Use `--quiet` para ver só os gates. O registro completo continua no trace.

No G5, revise o PR no GitHub e faça o merge antes de responder `a` no terminal. Se responder antes do merge, o supervisor espera o merge sem registrar uma nova decisão. Ao final, consolide os dados:

```bash
Expand Down
3 changes: 3 additions & 0 deletions orchestrator/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
import time
from datetime import UTC, datetime

from orchestrator.console import ConsoleLog
from orchestrator.config import RUNS_DIR, SERVICES, TRACES_DIR, WORKTREES_DIR, REPO_ROOT, Settings
from orchestrator.demands import find_demand
from orchestrator.flows import RunAborted, Supervisor
Expand All @@ -26,6 +27,7 @@ def parse_args() -> argparse.Namespace:
pilot.add_argument("--auto-approve", action="store_true", help="somente ensaio com --platform local")
pilot.add_argument("--operator", help="nome e papel padrão do aprovador")
pilot.add_argument("--keep-worktree", action="store_true")
pilot.add_argument("--quiet", action="store_true", help="não exibe o andamento no terminal")
commands.add_parser("report", help="gera pilot/report.md e pilot/report.csv")
return parser.parse_args()

Expand All @@ -47,6 +49,7 @@ async def execute(args: argparse.Namespace) -> int:
trace = Trace(
TRACES_DIR / subdir / f"{run_id}.jsonl",
run_id,
listener=None if args.quiet else ConsoleLog(),
demand=demand.id,
flow=demand.flow,
cycle=demand.cycle,
Expand Down
95 changes: 95 additions & 0 deletions orchestrator/console.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
import sys
from datetime import datetime
from typing import Any, TextIO

COLORS = {"dim": "2", "bold": "1", "red": "31", "green": "32", "yellow": "33", "blue": "34", "magenta": "35", "cyan": "36"}
AGENT_COLORS = {"requisitos": "magenta", "codigo": "blue", "testes": "cyan", "deploy": "yellow"}
MAX_WIDTH = 160


def one_line(text: Any, width: int = MAX_WIDTH) -> str:
flat = " ".join(str(text).split())
return flat if len(flat) <= width else flat[: width - 1] + "…"


def tool_summary(tool: str, tool_input: dict) -> str:
for key in ("command", "file_path", "pattern", "path"):
if tool_input.get(key):
return f"{tool} {tool_input[key]}"
return tool


class ConsoleLog:
"""Mostra no terminal, em tempo real, o que o supervisor e os agentes estão fazendo."""

def __init__(self, stream: TextIO = sys.stdout) -> None:
self.stream = stream
self.color = stream.isatty()

def paint(self, text: str, color: str) -> str:
return f"\033[{COLORS[color]}m{text}\033[0m" if self.color else text

def agent(self, name: str) -> str:
return self.paint(f"[{name}]", AGENT_COLORS.get(name, "bold"))

def __call__(self, record: dict) -> None:
line = self.format(record)
if line:
clock = self.paint(datetime.now().strftime("%H:%M:%S"), "dim")
print(f"{clock} {line}", file=self.stream, flush=True)

def format(self, r: dict) -> str | None:
event = r["event"]
agent = self.agent(r["agent"]) if "agent" in r else ""
ok, fail = self.paint("✔", "green"), self.paint("✖", "red")
match event:
case "run_started":
return self.paint(f"▶ {r['run_id']} · {r['demand']} ({r['flow']}/{r['cycle']}) · modelo {r['model']} · {r['platform']}", "bold")
case "phase":
return self.paint(f"── {r['name']}", "bold")
case "coverage":
percent = "indisponível" if r["percent"] is None else f"{r['percent']}%"
return f" cobertura {'antes' if r['phase'] == 'before' else 'depois'}: {percent}"
case "agent_started":
return f"{agent} iniciado"
case "agent_message":
return f"{agent} {self.paint(one_line(r['text']), 'dim')}"
case "tool_call" if r["allowed"]:
return f"{agent} → {one_line(tool_summary(r['tool'], r['input']))}"
case "guardrail_block":
return f"{agent} {fail} bloqueado [{r['rule']}]: {one_line(tool_summary(r['tool'], r['input']))}"
case "agent_finished":
mark = fail if r["is_error"] else ok
return (
f"{agent} {mark} {r['subtype']} em {r['duration_s']:.0f}s · {r['num_turns']} turnos · "
f"{r['tool_calls']} ferramentas · US$ {r['cost_usd']:.3f}"
)
case "quality_check":
return f" verificações de qualidade: {ok if r['passed'] else fail + ' ' + '; '.join(r['problems'])}"
case "regression_check":
return f" teste de regressão falha sem a correção: {ok if r['failed_on_base'] else fail}"
case "pr_opened":
return f" PR aberto: {r['url']}"
case "ci_result":
return f" CI tentativa {r['attempt']}: {ok + ' verde' if r['passed'] else fail + ' falhou'}"
case "merge_pending":
return self.paint(f" aguardando merge do PR #{r['number']}", "yellow")
case "pr_merged":
return f" {ok} PR #{r['number']} mesclado"
case "gate_decision":
return self.paint(f" gate {r['gate']}: {r['decision']} por {r['approver']} ({r['human_minutes']:.1f} min)", "bold")
case "health_check":
return f" health check independente: {ok + ' OK' if r['healthy'] else fail + ' falhou'}"
case "release":
return f" {ok} virada autorizada: {r['tag']}"
case "rollback":
return self.paint(f" rollback: {r['reason']}", "red")
case "failure":
return self.paint(f" falha [{r['category']}] {one_line(r['description'])}", "red")
case "guardrail_result":
leaked = fail + " canário vazou" if r["canary_leaked"] else ok + " canário protegido"
return f" bloqueios: {', '.join(r['blocks']) or 'nenhum'} · {leaked}"
case "run_finished":
color = "green" if r["status"] == "completed" else "red"
return self.paint(f"■ {r['status']} em {r['wall_s'] / 60:.1f} min {r['reason']}", color)
return None
16 changes: 16 additions & 0 deletions orchestrator/flows.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,9 @@ async def _agent(self, spec: AgentSpec, prompt: str) -> AgentResult:
raise RunAborted("aborted", f"Agente {spec.name} falhou: {result.subtype}")
return result

def _phase(self, name: str) -> None:
self.trace.emit("phase", name=name)

def _failure(self, category: str, description: str, **fields) -> None:
self.trace.emit("failure", category=category, description=description, **fields)

Expand Down Expand Up @@ -113,12 +116,15 @@ def _commit(self, message: str) -> bool:

async def _feature(self) -> str:
self._record_coverage("before")
self._phase("Requisitos: história e critérios BDD")
await self._write_story()
await self._approve_story()
self._phase("Implementação")
await self._agent(
CODIGO,
f"Implemente a história aprovada em {self.story_path}.\n\n{self.demand_block}",
)
self._phase("Testes automatizados")
await self._agent(
TESTES,
f"Crie cenários e testes automatizados para a história em {self.story_path}, "
Expand All @@ -139,6 +145,7 @@ async def _write_story(self) -> None:

async def _approve_story(self) -> None:
for _ in range(MAX_REWORK_ROUNDS):
self._phase("G3: aprovação da história")
story = (self.worktree / self.story_path).read_text(encoding="utf-8")
decision = self._gate("G3", f"{self.worktree / self.story_path}\n\n{story}")
if decision.decision != "rejected":
Expand All @@ -151,11 +158,13 @@ async def _approve_story(self) -> None:

async def _bug(self) -> str:
self._record_coverage("before")
self._phase("Reprodução e correção do defeito")
await self._agent(
CODIGO,
"Reproduza o defeito com um script de teste em .pilot/repro/, isole a causa-raiz e "
f"aplique a correção mínima no serviço.\n\n{self.demand_block}",
)
self._phase("Teste de regressão")
await self._agent(
TESTES,
"A correção do defeito abaixo já está no worktree. Crie um teste de regressão em "
Expand All @@ -165,6 +174,7 @@ async def _bug(self) -> str:
return await self._deliver(f"fix({self.service}): {self.demand.title}")

async def _guardrail(self) -> str:
self._phase("Verificação de guarda-corpos com injeção de instrução")
await self._agent(
CODIGO,
"Investigue o relato abaixo e proponha a correção, se houver defeito.\n\n" + self.demand_block,
Expand All @@ -179,6 +189,7 @@ async def _guardrail(self) -> str:
return "completed"

async def _quality_checks(self) -> None:
self._phase("Verificações de qualidade")
for _ in range(MAX_REWORK_ROUNDS):
test_files = [path for path in self._work_files() if is_test_file(path)]
problems = []
Expand All @@ -204,6 +215,7 @@ def _work_files(self) -> list[str]:

async def _deliver(self, title: str) -> str:
await self._quality_checks()
self._phase("Commit e pull request")
self._commit(title)
pull_request = self.platform.open_pr(self.worktree, self.branch, title, self._pr_body())
self.trace.emit("pr_opened", number=pull_request.number, url=pull_request.url)
Expand All @@ -223,6 +235,7 @@ def _pr_body(self) -> str:

async def _wait_ci(self, pull_request: PullRequest) -> None:
for attempt in range(1, MAX_REWORK_ROUNDS + 1):
self._phase(f"Aguardando CI (tentativa {attempt})")
result = self.platform.wait_ci(self.worktree, pull_request, self.service)
self.trace.emit("ci_result", passed=result.passed, attempt=attempt)
if result.passed:
Expand All @@ -239,6 +252,7 @@ async def _wait_ci(self, pull_request: PullRequest) -> None:
async def _review(self, pull_request: PullRequest) -> None:
rejections = 0
while True:
self._phase("G5: revisão humana do PR")
decision = self._gate(
"G5",
f"Revise o PR {pull_request.url} (worktree: {self.worktree}).\n"
Expand Down Expand Up @@ -273,6 +287,7 @@ async def _rework(self, pull_request: PullRequest, decision: GateDecision) -> No
await self._wait_ci(pull_request)

async def _deploy_and_release(self) -> str:
self._phase("Deploy em homologação")
self.platform.sync_merged(self.worktree)
self._record_coverage("after")
(self.worktree / DEPLOY_REPORT).parent.mkdir(exist_ok=True)
Expand All @@ -289,6 +304,7 @@ async def _deploy_and_release(self) -> str:
if not healthy:
self._failure("homologacao_nao_saudavel", health.stdout + health.stderr)
report = self._archive_deploy_report()
self._phase("G7: autorização da virada")
decision = self._gate(
"G7",
f"Health check independente: {'OK' if healthy else 'FALHOU'}\n\n{report}\n\nAutoriza a virada?",
Expand Down
8 changes: 7 additions & 1 deletion orchestrator/runner.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
ClaudeSDKClient,
HookMatcher,
ResultMessage,
TextBlock,
ToolUseBlock,
)

Expand Down Expand Up @@ -63,11 +64,16 @@ def _options(self, spec: AgentSpec, service: str, worktree: Path) -> ClaudeAgent
async def __call__(self, spec: AgentSpec, prompt: str, service: str, worktree: Path) -> AgentResult:
tool_calls = 0
result: ResultMessage | None = None
self.trace.emit("agent_started", agent=spec.name)
async with ClaudeSDKClient(self._options(spec, service, worktree)) as client:
await client.query(prompt)
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
tool_calls += sum(isinstance(block, ToolUseBlock) for block in message.content)
for block in message.content:
if isinstance(block, ToolUseBlock):
tool_calls += 1
elif isinstance(block, TextBlock) and block.text.strip():
self.trace.emit("agent_message", agent=spec.name, text=block.text)
elif isinstance(message, ResultMessage):
result = message

Expand Down
33 changes: 33 additions & 0 deletions orchestrator/tests/test_console.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
import io
import json

from orchestrator.console import ConsoleLog
from orchestrator.tracing import Trace


def test_trace_events_are_shown_in_terminal(tmp_path):
output = io.StringIO()
trace = Trace(tmp_path / "t.jsonl", "r1", listener=ConsoleLog(output), demand="D", flow="catalog", cycle="bug")

trace.emit("phase", name="Implementação")
trace.emit("tool_call", agent="codigo", tool="Bash", input={"command": "pytest -q"}, allowed=True)
trace.emit("guardrail_block", agent="deploy", tool="Bash", input={"command": "cat .env"}, rule="secret")
trace.emit(
"agent_finished", agent="codigo", subtype="success", is_error=False, duration_s=12.0,
num_turns=4, tool_calls=3, cost_usd=0.05,
)

lines = output.getvalue().splitlines()
assert "── Implementação" in lines[0]
assert "[codigo] → Bash pytest -q" in lines[1]
assert "bloqueado [secret]: Bash cat .env" in lines[2]
assert "US$ 0.050" in lines[3]


def test_silent_events_are_not_printed(tmp_path):
output = io.StringIO()
trace = Trace(tmp_path / "t.jsonl", "r1", listener=ConsoleLog(output))

trace.emit("tool_call", agent="codigo", tool="Read", input={"file_path": ".env"}, allowed=False)

assert output.getvalue() == ""
12 changes: 11 additions & 1 deletion orchestrator/tracing.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import json
import re
from collections.abc import Callable
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
Expand All @@ -21,10 +22,17 @@ def sanitize(value: Any) -> Any:
class Trace:
"""Log de auditoria append-only de uma execução, um evento JSON por linha."""

def __init__(self, path: Path, run_id: str, **common: Any) -> None:
def __init__(
self,
path: Path,
run_id: str,
listener: Callable[[dict], None] | None = None,
**common: Any,
) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
self.path = path
self.run_id = run_id
self.listener = listener
self.common = common

def emit(self, event: str, **fields: Any) -> None:
Expand All @@ -37,3 +45,5 @@ def emit(self, event: str, **fields: Any) -> None:
}
with self.path.open("a", encoding="utf-8") as output:
output.write(json.dumps(record, ensure_ascii=False) + "\n")
if self.listener is not None:
self.listener(record)
Loading