Skip to content

Add structured worker result passing for multi-agent orchestration#21

Open
lukabudik wants to merge 1 commit intoRigos0:mainfrom
lukabudik:feat/orchestrator-result-passing
Open

Add structured worker result passing for multi-agent orchestration#21
lukabudik wants to merge 1 commit intoRigos0:mainfrom
lukabudik:feat/orchestrator-result-passing

Conversation

@lukabudik
Copy link
Copy Markdown

@lukabudik lukabudik commented Apr 20, 2026

What this does

SuperTurtle's SubTurtle system is already multi-agent — the meta agent spawns workers and gets wakeup notifications when they complete. But handoffs between dependent workers are currently manual: when Worker B depends on Worker A, the meta agent has to read A's workspace, run `git log`, and synthesize what was built. There's no structured output format, no established convention, and nothing to guarantee B gets correct context about A's API contracts or key decisions.

This PR adds the missing layer: structured result files that flow between agents, with fallback guarantees so the system is robust even when an agent forgets to write one.

How it works

Workers write `.superturtle/state/results/.json` at completion:

{
  "summary": "JWT middleware with RS256. 12 tests passing.",
  "artifacts": ["src/auth/jwt.ts"],
  "key_decisions": ["RS256 over HS256 for public-key verification"],
  "questions_for_orchestrator": ["Should refresh TTL be configurable?"]
}

The meta agent reads this before spawning B and injects it into B's CLAUDE.md as ## Inputs from upstream workers. B starts with zero ambiguity about A's API shape, decisions, and open questions — no manual workspace inspection needed.

Fallback guarantees — Python and TypeScript each write a fallback result if the agent didn't, covering all three terminal wakeup kinds (completion, fatal error, timeout).

Conductor inbox auto-embeds result data — the notification the meta agent receives on completion now includes result summary, key decisions, artifacts, and open questions directly in the text, so the meta agent doesn't need to cat any files.

Dashboard shows a "Worker result" card on the SubTurtle detail page.

DECOMPOSITION_PROMPT.md gets a Result-Passing Pattern section with a ready-to-use injection template. META_SHARED.md gets a matching note under task decomposition.

Changes

  • conductor_state.pyresults/ dir in state layout; result_path() and load_worker_result()
  • statefile.pyresult_file_path(); _write_fallback_result(); called from record_completion_pending() and record_failure_pending()
  • prompts.py / loops.py — YOLO_PROMPT and REVIEWER_PROMPT instruct workers to write result files; worker_name and result_file threaded through as template variables
  • conductor-supervisor.tswriteFallbackResultIfAbsent() for timeout case; loadWorkerResultForInbox() + result data embedded in inbox text
  • conductor-snapshot.ts / cron-supervision-queue.tsworkerResultJson field in snapshot context and prepared snapshot
  • dashboard-types.ts / dashboard/details.ts / dashboard/renderers.tsWorkerResultRecord type and "Worker result" card

Tests

  • 30 Python tests passing (8 new: fallback writing, non-overwrite guarantee, failure result, path helper)
  • 20 TypeScript tests passing (3 new: inbox embeds result data, snapshot loads result file, timeout writes fallback)

SubTurtles now write a structured result file at completion so the meta
agent can pass outputs from one worker directly into the next, enabling
real dependency-aware orchestration instead of manual workspace inspection.

Worker result files (.superturtle/state/results/<name>.json) carry:
- summary: what was built
- artifacts: files a downstream worker must read
- key_decisions: choices downstream workers must conform to
- questions_for_orchestrator: open items for the meta agent

Python infrastructure writes a fallback result automatically if the agent
forgets to, covering clean completion, fatal failure, and (via TypeScript)
watchdog timeout — so every terminal wakeup kind is guaranteed to have a
result file by the time the meta agent processes it.

Conductor inbox items for completed workers now embed the result summary,
key decisions, artifacts, and open questions directly in the notification
text, so the meta agent sees everything it needs to spawn a well-informed
downstream worker without manually inspecting the workspace.

DECOMPOSITION_PROMPT.md gains a Result-Passing Pattern section with a
ready-to-use injection template for wiring upstream outputs into downstream
CLAUDE.md files. META_SHARED.md gets a matching note under task decomposition.

Dashboard SubTurtle detail pages show a Worker result card.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant