Add structured worker result passing for multi-agent orchestration#21
Open
lukabudik wants to merge 1 commit intoRigos0:mainfrom
Open
Add structured worker result passing for multi-agent orchestration#21lukabudik wants to merge 1 commit intoRigos0:mainfrom
lukabudik wants to merge 1 commit intoRigos0:mainfrom
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdgets a Result-Passing Pattern section with a ready-to-use injection template.META_SHARED.mdgets a matching note under task decomposition.Changes
conductor_state.py—results/dir in state layout;result_path()andload_worker_result()statefile.py—result_file_path();_write_fallback_result(); called fromrecord_completion_pending()andrecord_failure_pending()prompts.py/loops.py— YOLO_PROMPT and REVIEWER_PROMPT instruct workers to write result files;worker_nameandresult_filethreaded through as template variablesconductor-supervisor.ts—writeFallbackResultIfAbsent()for timeout case;loadWorkerResultForInbox()+ result data embedded in inbox textconductor-snapshot.ts/cron-supervision-queue.ts—workerResultJsonfield in snapshot context and prepared snapshotdashboard-types.ts/dashboard/details.ts/dashboard/renderers.ts—WorkerResultRecordtype and "Worker result" cardTests