From 1fb1931136c4e0dea9f995638f648eccaddfac80 Mon Sep 17 00:00:00 2001 From: mathcolombo Date: Tue, 10 Nov 2026 21:03:48 -0300 Subject: [PATCH] =?UTF-8?q?feat(orchestrator):=20andamento=20da=20execu?= =?UTF-8?q?=C3=A7=C3=A3o=20no=20terminal?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cada evento do trace também é exibido no terminal: fases do supervisor, mensagens e ferramentas dos agentes, bloqueios de guarda-corpo, custo por agente, CI, gates e virada. `--quiet` desliga a exibição. Co-Authored-By: Claude Opus 5.5 --- docs/piloto/protocolo.md | 2 + orchestrator/__main__.py | 3 + orchestrator/console.py | 95 ++++++++++++++++++++++++++++++ orchestrator/flows.py | 16 +++++ orchestrator/runner.py | 8 ++- orchestrator/tests/test_console.py | 33 +++++++++++ orchestrator/tracing.py | 12 +++- 7 files changed, 167 insertions(+), 2 deletions(-) create mode 100644 orchestrator/console.py create mode 100644 orchestrator/tests/test_console.py diff --git a/docs/piloto/protocolo.md b/docs/piloto/protocolo.md index 910dbe9..90a5678 100644 --- a/docs/piloto/protocolo.md +++ b/docs/piloto/protocolo.md @@ -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 diff --git a/orchestrator/__main__.py b/orchestrator/__main__.py index c152fe5..3384dd5 100644 --- a/orchestrator/__main__.py +++ b/orchestrator/__main__.py @@ -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 @@ -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() @@ -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, diff --git a/orchestrator/console.py b/orchestrator/console.py new file mode 100644 index 0000000..539d0c5 --- /dev/null +++ b/orchestrator/console.py @@ -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 diff --git a/orchestrator/flows.py b/orchestrator/flows.py index 640d898..1e3aa84 100644 --- a/orchestrator/flows.py +++ b/orchestrator/flows.py @@ -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) @@ -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}, " @@ -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": @@ -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 " @@ -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, @@ -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 = [] @@ -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) @@ -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: @@ -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" @@ -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) @@ -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?", diff --git a/orchestrator/runner.py b/orchestrator/runner.py index c811953..745cc9f 100644 --- a/orchestrator/runner.py +++ b/orchestrator/runner.py @@ -9,6 +9,7 @@ ClaudeSDKClient, HookMatcher, ResultMessage, + TextBlock, ToolUseBlock, ) @@ -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 diff --git a/orchestrator/tests/test_console.py b/orchestrator/tests/test_console.py new file mode 100644 index 0000000..58fa923 --- /dev/null +++ b/orchestrator/tests/test_console.py @@ -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() == "" diff --git a/orchestrator/tracing.py b/orchestrator/tracing.py index 8bd5fb2..349a778 100644 --- a/orchestrator/tracing.py +++ b/orchestrator/tracing.py @@ -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 @@ -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: @@ -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)