Consolidate agent harness course into 19 lessons

This commit is contained in:
Haoran
2026-08-04 02:25:40 +08:00
parent 2ad77cee19
commit b36dbcd84f
168 changed files with 6544 additions and 10400 deletions

View File

@@ -1,60 +1,105 @@
{
"version": "s15",
"title": "Agent Teams",
"description": "The Lead proposes a team for a normal user request, waits for confirmation, then coordinates persistent teammates through runtime-delivered events.",
"title": "Agent Team Runtime",
"description": "The Lead coordinates persistent teammates while the runtime owns message delivery, atomic task claims, and task-bound worktree directories.",
"steps": [
{
"type": "user_message",
"content": "Refactor the configuration loader and authentication flow, then update the tests.",
"annotation": "The user describes the goal without designing a team."
"content": "Refactor authentication and update its dependent tests in parallel without mixing the edits.",
"annotation": "The user states the outcome and parallel-edit boundary, not an implementation-specific worktree procedure."
},
{
"type": "assistant_text",
"content": "These areas can be handled in parallel. I propose one teammate for configuration and authentication, and another for tests. Shall I start that team?",
"annotation": "The Lead chooses a small team and makes the extra-agent decision visible."
"content": "I propose a backend teammate for authentication and a test teammate that picks up the dependent checks once they are ready. Shall I start the team?",
"annotation": "The Lead makes the extra-agent decision visible before spawning."
},
{
"type": "user_message",
"content": "Yes, go ahead.",
"annotation": "Teammates start only after explicit confirmation."
"annotation": "The team starts only after explicit confirmation."
},
{
"type": "tool_call",
"toolName": "create_task",
"content": "{\"subject\":\"Refactor authentication\"}",
"annotation": "The shared task board remains the source of ownership and status."
},
{
"type": "tool_result",
"toolName": "create_task",
"content": "Created task_1712345678_0042: Refactor authentication",
"annotation": "The runtime-generated task ID is carried into every later operation on this task."
},
{
"type": "tool_call",
"toolName": "create_worktree",
"content": "{\"name\":\"auth-refactor\",\"task_id\":\"task_1712345678_0042\"}",
"annotation": "The worktree directory is recorded on the task instead of managed as a separate workflow or security sandbox."
},
{
"type": "tool_call",
"toolName": "create_task",
"content": "{\"subject\":\"Update authentication tests\",\"blockedBy\":[\"task_1712345678_0042\"]}",
"annotation": "The task graph keeps dependent work from starting early."
},
{
"type": "tool_result",
"toolName": "create_task",
"content": "Created task_1712345678_0043: Update authentication tests (blockedBy: task_1712345678_0042)",
"annotation": "The second generated ID names the dependent task that the test teammate will later claim."
},
{
"type": "tool_call",
"toolName": "spawn_teammate",
"content": "{\"name\":\"backend\",\"role\":\"backend engineer\",\"prompt\":\"Refactor configuration and authentication while preserving interfaces.\"}",
"annotation": "The first persistent teammate enters WORK with a focused assignment."
"content": "{\"name\":\"backend\",\"role\":\"backend engineer\",\"prompt\":\"Claim the authentication task and propose a plan.\"}",
"annotation": "A persistent teammate receives focused work through the team runtime."
},
{
"type": "tool_call",
"toolName": "spawn_teammate",
"content": "{\"name\":\"tests\",\"role\":\"test engineer\",\"prompt\":\"Update and run tests for the refactor.\"}",
"annotation": "The second teammate gets an independent slice."
"content": "{\"name\":\"tests\",\"role\":\"test engineer\",\"prompt\":\"Watch the board and claim the dependent test task when it becomes ready.\"}",
"annotation": "A second persistent teammate can wait in IDLE without another direct dispatch."
},
{
"type": "system_event",
"content": "backend -> Lead: result(refactor complete) -> idle_notification",
"content": "plan_request(req_plan_7) -> plan_response(req_plan_7, approved=true)",
"annotation": "Typed correlation and an approval gate protect mutating tools."
},
{
"type": "system_event",
"content": "claim_next_task(backend) -> task_1712345678_0042; task_lock commits owner=backend",
"annotation": "The ownership check and state transition are atomic."
},
{
"type": "system_event",
"content": "backend tool cwd -> .worktrees/auth-refactor",
"annotation": "Bash, read, and write derive their directory from the claimed task binding."
},
{
"type": "tool_call",
"toolName": "complete_task",
"content": "{\"task_id\":\"task_1712345678_0042\"}",
"annotation": "Completing the first task makes its dependent test task ready."
},
{
"type": "system_event",
"content": "backend -> Lead: result(auth refactor complete) -> idle_notification",
"annotation": "Result and idle state are separate events; the teammate remains available."
},
{
"type": "system_event",
"content": "tests -> Lead: result(test suite passed) -> idle_notification",
"annotation": "The runtime observes mailbox writes and wakes the Lead without a polling tool."
},
{
"type": "assistant_text",
"content": "Both parts are complete. The interfaces were preserved and the updated tests pass.",
"annotation": "The Lead combines teammate results into one user-facing answer."
},
{
"type": "tool_call",
"toolName": "request_shutdown",
"content": "{\"teammate\":\"backend\"}",
"annotation": "A typed request with a request id closes the persistent teammate cleanly."
"content": "claim_next_task(tests) -> task_1712345678_0043; task_lock commits owner=tests",
"annotation": "An idle teammate discovers newly ready work without another direct assignment."
},
{
"type": "system_event",
"content": "shutdown_response(request_id=req_42, approve=true)",
"annotation": "The matching response resolves the pending protocol request."
"content": "tests -> Lead: result(test suite passed) -> idle_notification",
"annotation": "The runtime wakes the Lead when mailbox events arrive instead of asking the model to poll."
},
{
"type": "assistant_text",
"content": "Authentication was refactored in its task-bound worktree and the dependent tests pass.",
"annotation": "The Lead combines parallel results into one user-facing outcome."
}
]
}

View File

@@ -1,50 +1,46 @@
{
"version": "s16",
"title": "Autonomous Agents",
"description": "Idle teammates discover ready tasks on a shared board and use an atomic claim before starting work.",
"title": "MCP Tools",
"description": "The agent discovers external MCP tools and exposes them through a normalized tool namespace.",
"steps": [
{
"type": "user_message",
"content": "Update the API examples, then add tests that use the final examples.",
"annotation": "The request contains two tasks with a clear dependency."
"content": "Search the documentation for deployment guidance.",
"annotation": "The user asks for a tool source outside the built-in set."
},
{
"type": "tool_call",
"toolName": "create_task",
"content": "{\"subject\":\"Update API examples\"}",
"annotation": "The Lead creates the first task in the shared graph."
"toolName": "connect_mcp",
"content": "{\"name\":\"docs\"}",
"annotation": "The runtime creates an MCP client for the named server."
},
{
"type": "system_event",
"content": "normalize_mcp_name(\"docs\", \"search\") -> mcp__docs__search",
"annotation": "External tools are namespaced to avoid collisions."
},
{
"type": "tool_result",
"toolName": "connect_mcp",
"content": "Connected to MCP server 'docs'. Discovered 2 tools: search, get_version",
"annotation": "Tool discovery expands the active tool pool."
},
{
"type": "tool_call",
"toolName": "create_task",
"content": "{\"subject\":\"Add example tests\",\"blockedBy\":[\"task_examples\"]}",
"annotation": "The second task cannot start until the examples are complete."
"toolName": "mcp__docs__search",
"content": "{\"query\":\"deployment\"}",
"annotation": "The LLM can now call the discovered tool by its normalized name."
},
{
"type": "system_event",
"content": "alice, bob: state=IDLE -> scan_unclaimed_tasks()",
"annotation": "Existing IDLE teammates scan the board after waiting for messages."
"type": "tool_result",
"toolName": "mcp__docs__search",
"content": "[docs] Found 3 results for 'deployment'",
"annotation": "The external result is appended like any other tool result."
},
{
"type": "system_event",
"content": "claim_next_task(alice) -> task_examples; task_lock commits owner=alice",
"annotation": "The ownership check and pending-to-in_progress update are atomic."
},
{
"type": "system_event",
"content": "claim_next_task(bob) -> no ready task; remain IDLE",
"annotation": "The test task is still blocked, so Bob does not start it early."
},
{
"type": "tool_call",
"toolName": "complete_task",
"content": "{\"task_id\":\"task_examples\"}",
"annotation": "Completing the examples unblocks the dependent test task."
},
{
"type": "system_event",
"content": "claim_next_task(bob) -> task_tests; task_lock commits owner=bob",
"annotation": "Bob claims the newly ready work without another direct assignment."
"type": "assistant_text",
"content": "The docs server found three matches for deployment guidance.",
"annotation": "The agent summarizes external tool output for the user."
}
]
}

View File

@@ -1,45 +1,97 @@
{
"version": "s17",
"title": "Worktree Isolation",
"description": "A task can be bound to an isolated git worktree so concurrent agents avoid stepping on each other.",
"title": "Integrated Harness",
"description": "The harness composes context assembly, tools, memory, teams, background work, cron, worktrees, and MCP.",
"steps": [
{
"type": "user_message",
"content": "Update the docs and parser in parallel without letting the changes interfere.",
"annotation": "Concurrent edits need isolated working directories."
"content": "Prepare this project for release. Check the code, update the docs, and report deployment readiness.",
"annotation": "One ordinary request needs several earlier capabilities to work together."
},
{
"type": "system_event",
"content": "assemble_prompt: memory + task graph + skills + available tools + policy",
"annotation": "The runtime builds the prompt from layered sources of context."
},
{
"type": "assistant_text",
"content": "I suggest a docs teammate while I run the release checks and inspect deployment status. Shall I start that team?",
"annotation": "The Lead proposes the team before adding another persistent agent."
},
{
"type": "user_message",
"content": "Yes. Start the docs teammate and continue.",
"annotation": "User confirmation opens the team boundary inherited from S15."
},
{
"type": "tool_call",
"toolName": "load_skill",
"content": "{\"name\":\"code-review\"}",
"annotation": "Skills contribute procedural context before execution."
},
{
"type": "tool_call",
"toolName": "create_task",
"content": "{\"subject\":\"Update release notes\",\"description\":\"Prepare release documentation and report the result.\"}",
"annotation": "The shared task board gives the docs work a stable owner and lifecycle."
},
{
"type": "tool_result",
"toolName": "create_task",
"content": "Created task_1712345678_0042: Update release notes",
"annotation": "The task ID connects the assignment to its working directory."
},
{
"type": "tool_call",
"toolName": "create_worktree",
"content": "{\"task_id\":\"task_docs\",\"name\":\"docs-fix\"}",
"annotation": "The tool validates a safe worktree name before touching git."
},
{
"type": "system_event",
"content": "git worktree add .worktrees/docs-fix -b agent/docs-fix",
"annotation": "A separate branch and checkout are created for that task."
"content": "{\"name\":\"release-docs\",\"task_id\":\"task_1712345678_0042\"}",
"annotation": "The pending docs task receives a separate checkout before it is claimed."
},
{
"type": "tool_result",
"toolName": "create_worktree",
"content": "task_docs bound to .worktrees/docs-fix",
"annotation": "The task record stores the assigned worktree path."
},
{
"type": "system_event",
"content": ".worktrees/events.jsonl <- {event:\"created\", task:\"task_docs\", worktree:\"docs-fix\"}",
"annotation": "Lifecycle events are emitted as a side channel."
"content": "Worktree 'release-docs' created for task_1712345678_0042",
"annotation": "The task now carries the checkout used by its eventual owner."
},
{
"type": "tool_call",
"toolName": "keep_worktree",
"content": "{\"task_id\":\"task_docs\",\"reason\":\"needs human review\"}",
"annotation": "Closeout can preserve a worktree instead of deleting it immediately."
"toolName": "spawn_teammate",
"content": "{\"name\":\"docs\",\"role\":\"documentation engineer\",\"prompt\":\"Claim task_1712345678_0042, update the release notes in its task-bound worktree, and report the result.\"}",
"annotation": "Team delegation handles a parallel slice of the release."
},
{
"type": "tool_call",
"toolName": "bash",
"content": "{\"command\":\"npm run lint && npm run test\",\"run_in_background\":true}",
"annotation": "Long-running validation goes through the background task path."
},
{
"type": "tool_call",
"toolName": "connect_mcp",
"content": "{\"name\":\"deploy\"}",
"annotation": "External capabilities are added only when needed."
},
{
"type": "tool_call",
"toolName": "mcp__deploy__status",
"content": "{\"service\":\"web\"}",
"annotation": "Connecting discovers the tool; a separate call performs the status check."
},
{
"type": "tool_result",
"toolName": "mcp__deploy__status",
"content": "[deploy] web: running (v1.4.2)",
"annotation": "The readiness statement now comes from the MCP tool result rather than the connection event."
},
{
"type": "system_event",
"content": "recover: background task done, teammate replied, deploy status result appended",
"annotation": "The integrated runtime folds asynchronous results back into the loop."
},
{
"type": "assistant_text",
"content": "The docs task now has an isolated worktree and can be reviewed independently from parser changes.",
"annotation": "The user sees the isolation boundary, not just a raw git command."
"content": "Release preparation is ready: checks passed, docs are updated in the teammate worktree, and deployment status is available.",
"annotation": "The integrated harness returns a single user-facing outcome."
}
]
}

View File

@@ -1,46 +1,54 @@
{
"version": "s18",
"title": "MCP Tools",
"description": "The agent discovers external MCP tools and exposes them through a normalized tool namespace.",
"title": "Workflow Runtime",
"description": "A fixed review pipeline executes inside one Workflow call, records a journal, emits lifecycle and progress events, and returns one final tool result.",
"steps": [
{
"type": "user_message",
"content": "Search the documentation for deployment guidance.",
"annotation": "The user asks for a tool source outside the built-in set."
"content": "Review this change across correctness, security, performance, and style.",
"annotation": "The goal is open-ended, but the review procedure has a fixed shape."
},
{
"type": "tool_call",
"toolName": "connect_mcp",
"content": "{\"server\":\"docs\",\"command\":\"mock-docs-server\"}",
"annotation": "The runtime creates an MCP client for the named server."
"toolName": "Workflow",
"content": "{\"name\":\"review-changes\",\"description\":\"Review changed files across dimensions and verify each finding\",\"phases\":[\"Review\",\"Verify\"]}",
"annotation": "One tool call hands deterministic orchestration to the workflow runtime."
},
{
"type": "system_event",
"content": "normalize_mcp_name(\"docs\", \"search\") -> mcp__docs__search",
"annotation": "External tools are namespaced to avoid collisions."
"content": "async_launched(runId=wf_review-changes_6779) -> task_started",
"annotation": "The runtime emits launch lifecycle events before it executes the script; this is not a tool result."
},
{
"type": "system_event",
"content": "phase=Review -> pipeline([correctness, security, performance, style])",
"annotation": "Each item advances independently through the scripted stages."
},
{
"type": "system_event",
"content": "phase=Verify -> adversarial checks run in parallel",
"annotation": "Structured results cross a validation boundary before aggregation."
},
{
"type": "system_event",
"content": "workflow_agent status=done -> journal append",
"annotation": "Every completed agent call is checkpointed as the script runs."
},
{
"type": "system_event",
"content": "task_notification(status=completed, outputFile=.runtime/wf_review-changes_6779.output.json)",
"annotation": "The task emits its final lifecycle event after output is written."
},
{
"type": "tool_result",
"toolName": "connect_mcp",
"content": "Connected docs with tools: mcp__docs__search, mcp__docs__read",
"annotation": "Tool discovery expands the active tool pool."
"toolName": "Workflow",
"content": "{\"launched\":{\"status\":\"async_launched\",\"runId\":\"wf_review-changes_6779\"},\"result\":{\"confirmed\":[]},\"task\":{\"status\":\"completed\"}}",
"annotation": "The completed call returns once, with launch metadata, the workflow result, and task state together."
},
{
"type": "tool_call",
"toolName": "mcp__docs__search",
"content": "{\"query\":\"deployment\"}",
"annotation": "The LLM can now call the discovered tool by its normalized name."
},
{
"type": "tool_result",
"toolName": "mcp__docs__search",
"content": "[\"Deploy with npm run build\", \"Use environment variables for tokens\"]",
"annotation": "The external result is appended like any other tool result."
},
{
"type": "assistant_text",
"content": "The docs server says to build first and keep tokens in environment variables.",
"annotation": "The agent summarizes external tool output for the user."
"type": "system_event",
"content": "append Workflow tool_result -> messages[]",
"annotation": "The main loop receives that single result and continues with the updated conversation."
}
]
}

View File

@@ -1,57 +1,49 @@
{
"version": "s19",
"title": "Integrated Harness",
"description": "The harness composes context assembly, tools, memory, teams, background work, cron, worktrees, and MCP.",
"title": "Goal Loop",
"description": "A separate evaluator reads the conversation at the end of a turn and sends unfinished work back through the same loop.",
"steps": [
{
"type": "user_message",
"content": "Prepare this project for release. Check the code, update the docs, and report deployment readiness.",
"annotation": "One ordinary request needs several earlier capabilities to work together."
},
{
"type": "system_event",
"content": "assemble_prompt: memory + task graph + skills + available tools + policy",
"annotation": "The runtime builds the prompt from layered sources of context."
"content": "/goal pytest tests/auth exits with code 0",
"annotation": "The command stores an active completion condition and starts the work."
},
{
"type": "assistant_text",
"content": "I'll inspect the task graph, delegate docs, start the slow scan in the background, and use the release checklist skill.",
"annotation": "The model chooses multiple mechanisms while keeping one coherent plan."
"content": "The authentication code looks correct. The tests should pass now.",
"annotation": "With no more tool calls, the session asks the evaluator whether the active goal is complete."
},
{
"type": "tool_call",
"toolName": "load_skill",
"content": "{\"name\":\"release-check\"}",
"annotation": "Skills contribute procedural context before execution."
"type": "system_event",
"content": "goal_evaluated ok=false -> block",
"annotation": "The evaluator finds no test exit code in the conversation."
},
{
"type": "tool_call",
"toolName": "spawn_teammate",
"content": "{\"name\":\"docs\",\"role\":\"Update release notes in its worktree.\"}",
"annotation": "Team delegation handles a parallel slice of the release."
"type": "system_event",
"content": "[Goal still active] Run pytest tests/auth and surface the exit code.",
"annotation": "The controller appends the reason to messages[] and continues the same loop; no queue is involved."
},
{
"type": "tool_call",
"toolName": "bash",
"content": "npm run lint && npm run test",
"toolInput": "{\"background\":true}",
"annotation": "Long-running validation goes through the background task path."
"content": "pytest tests/auth",
"annotation": "The next agent turn runs the missing check."
},
{
"type": "tool_call",
"toolName": "connect_mcp",
"content": "{\"server\":\"deploy\",\"command\":\"mock-deploy-server\"}",
"annotation": "External capabilities are added only when needed."
},
{
"type": "system_event",
"content": "recover: background task done, teammate replied, MCP deploy status ready",
"annotation": "The integrated runtime folds asynchronous results back into the loop."
"type": "tool_result",
"toolName": "bash",
"content": "exit_code=0\n12 passed in 0.42s",
"annotation": "The concrete command result enters the same conversation."
},
{
"type": "assistant_text",
"content": "Release preparation is ready: checks passed, docs are updated in the teammate worktree, and deployment status is available.",
"annotation": "The integrated harness returns a single user-facing outcome."
"content": "pytest tests/auth exited 0: 12 tests passed.",
"annotation": "A turn with no further tool call reaches the Stop hook again."
},
{
"type": "system_event",
"content": "goal_evaluated ok=true -> achieved",
"annotation": "The controller records success, clears the active goal, and returns."
}
]
}

View File

@@ -1,43 +0,0 @@
{
"version": "s20",
"title": "Workflow Runtime",
"description": "A fixed review pipeline runs in parallel, records a journal, and resumes completed agent calls from cache.",
"steps": [
{
"type": "user_message",
"content": "Review this change across correctness, security, performance, and style.",
"annotation": "The goal is open-ended, but the review procedure has a fixed shape."
},
{
"type": "tool_call",
"toolName": "Workflow",
"content": "{\"name\":\"review-changes\",\"phases\":[\"Review\",\"Verify\"]}",
"annotation": "One tool call hands deterministic orchestration to the workflow runtime."
},
{
"type": "tool_result",
"content": "{\"status\":\"async_launched\",\"runId\":\"wf_review-changes_6779\"}",
"annotation": "The product runtime returns a claim ticket while work continues in the background."
},
{
"type": "system_event",
"content": "phase=Review -> pipeline([correctness, security, performance, style])",
"annotation": "Each item advances independently through the scripted stages."
},
{
"type": "system_event",
"content": "phase=Verify -> adversarial checks run in parallel",
"annotation": "Structured results cross a validation boundary before aggregation."
},
{
"type": "system_event",
"content": "journal append -> task_notification(status=completed)",
"annotation": "Every completed agent call is checkpointed before the final notification."
},
{
"type": "system_event",
"content": "resumeFromRunId -> unchanged calls status=cached",
"annotation": "Semantic keys reuse completed work without depending on concurrency order."
}
]
}

View File

@@ -1,37 +0,0 @@
{
"version": "s21",
"title": "Goal Loop",
"description": "A host-owned completion gate keeps the turn alive until trusted evidence satisfies the active goal.",
"steps": [
{
"type": "user_message",
"content": "/goal until tests passed and deploy green",
"annotation": "The command defines the condition but sits outside the evidence window."
},
{
"type": "system_event",
"content": "goal_started -> evidence window reset",
"annotation": "The harness, not the working model, owns the completion gate."
},
{
"type": "assistant_text",
"content": "Tests passed and deployment is green.",
"annotation": "Assistant prose is not trusted completion evidence."
},
{
"type": "system_event",
"content": "goal_evaluated satisfied=false -> continuation queued",
"annotation": "An unmet condition pushes the loop into another bounded turn."
},
{
"type": "tool_result",
"content": "<task_notification>tests passed; deploy green</task_notification>",
"annotation": "Only an allowlisted host event can attach a trusted evidence origin."
},
{
"type": "system_event",
"content": "goal_evaluated satisfied=true -> goal_completed",
"annotation": "Trusted evidence closes the goal and releases the stop gate."
}
]
}