99 lines
3.6 KiB
Markdown
99 lines
3.6 KiB
Markdown
|
---
|
||
|
|
kind: task
|
||
|
|
slug: mcp-complete-task-tool
|
||
|
|
title: MCP complete_task tool — close an agent_runs row and finalize status
|
||
|
|
plan_slug: agent-coordination
|
||
|
|
epic_slug: mcp-claim-complete
|
||
|
|
status: ready
|
||
|
|
priority: P2
|
||
|
|
tenant_id: global
|
||
|
|
owner: unassigned
|
||
|
|
cursor_todo_id: null
|
||
|
|
updated_at: "2026-06-01"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Task summary
|
||
|
|
|
||
|
|
A new MCP tool `complete_task` that an agent calls at session end. It closes the `agent_runs` row with an outcome and token totals, and optionally flips the backlog item to `done` (or another terminal status).
|
||
|
|
|
||
|
|
## Description
|
||
|
|
|
||
|
|
### Contract
|
||
|
|
|
||
|
|
Register in `apps/mcp-server/src/tools/complete-task.ts`.
|
||
|
|
|
||
|
|
Input zod schema:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
{
|
||
|
|
runId: string, // uuid of the agent_runs row to close
|
||
|
|
outcome: "succeeded" | "failed" | "cancelled" | "stalled",
|
||
|
|
tokensInput?: number,
|
||
|
|
tokensOutput?: number,
|
||
|
|
tokensTotal?: number,
|
||
|
|
notes?: string, // freeform summary, capped at ~2000 chars
|
||
|
|
error?: string, // optional failure message
|
||
|
|
finalStatus?: "done" | "blocked" | "ready" | "in_progress" | "cancelled",
|
||
|
|
// optional override for the backlog item's status
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Behavior:
|
||
|
|
|
||
|
|
1. Look up the run; verify it's still open (`finished_at IS NULL`). If already closed, error `RUN_ALREADY_FINISHED`.
|
||
|
|
2. Resolve the backlog item and confirm its workspace matches the run's workspace.
|
||
|
|
3. Update the run row: `finished_at=now()`, `outcome`, tokens, `notes`, `error`.
|
||
|
|
4. Compute the final backlog status:
|
||
|
|
- If `finalStatus` provided: use it (validate it's a legal `markdown_backlog_items.status` value).
|
||
|
|
- Else if `outcome === "succeeded"`: set status to `done`.
|
||
|
|
- Else if `outcome === "failed"`: set status to `blocked`.
|
||
|
|
- Else: leave status as-is.
|
||
|
|
5. Write `audit_log` row (`action: "task.completed"`, `metadata: { outcome, final_status }`).
|
||
|
|
6. Return `{ runId, finishedAt, finalStatus, tokensTotal }`.
|
||
|
|
|
||
|
|
### Token semantics
|
||
|
|
|
||
|
|
Take the agent at its word for `tokensTotal` — don't recompute from input+output. This matches Symphony's "prefer absolute thread totals" rule (`SPEC.md` §13.5) and avoids double-counting when models report cumulative totals natively.
|
||
|
|
|
||
|
|
If `tokensTotal` is omitted but `tokensInput` and `tokensOutput` are provided, compute total as `input + output` and store. If all three are present and inconsistent, prefer `tokensTotal` and don't error.
|
||
|
|
|
||
|
|
### Idempotency
|
||
|
|
|
||
|
|
Closing an already-closed run is an error, not a silent no-op. The agent should know it tried to close something twice. If the operator wants to amend a closed run, they can do it via a future tRPC procedure — not through this tool.
|
||
|
|
|
||
|
|
### Anti-goals
|
||
|
|
|
||
|
|
- No streaming updates. This tool runs once at session end.
|
||
|
|
- No "extend" or "renew" semantics. A long session that the agent thinks is still going should keep its run open by *not* calling `complete_task`. Stall detection is the orchestrator's job (deferred).
|
||
|
|
|
||
|
|
## Subtasks
|
||
|
|
|
||
|
|
- [ ] Create `apps/mcp-server/src/tools/complete-task.ts`.
|
||
|
|
- [ ] Register in `apps/mcp-server/src/tools/index.ts`.
|
||
|
|
- [ ] Implement the 6-step behavior with zod validation.
|
||
|
|
- [ ] Audit log write.
|
||
|
|
- [ ] Verify with a manual end-to-end loop: `claim_task` → do nothing → `complete_task` and confirm the run row is closed.
|
||
|
|
|
||
|
|
## Owner or assignee
|
||
|
|
|
||
|
|
Unassigned
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
ready
|
||
|
|
|
||
|
|
## Estimation
|
||
|
|
|
||
|
|
M
|
||
|
|
|
||
|
|
## Acceptance criteria
|
||
|
|
|
||
|
|
- [ ] Successful close updates `finished_at`, `outcome`, tokens, and (when appropriate) the backlog item's status.
|
||
|
|
- [ ] Double-close errors with `RUN_ALREADY_FINISHED`.
|
||
|
|
- [ ] Token inconsistency is resolved by preferring `tokensTotal`.
|
||
|
|
|
||
|
|
## Links to related Epic / Plan
|
||
|
|
|
||
|
|
- Epic: `./Epic-mcp-claim-complete.md`
|
||
|
|
- Plan: `../Plan-agent-coordination.md`
|