778fe1d321
Three new plan trees that fill in the gaps surfaced during repo review. Together they map out what remains between the current scaffold-with-stubs state and a daily-usable, multitenant, agent-coordinated app. * Plan-daily-driver-finish (P0): turn stubs into real data. Five tasks covering the lint/shared-types breakage, hardcoded dashboard mocks, AI-page setTimeout placeholder, post-signin landing decision, and a cross-browser collab smoke test against the deployed Hocuspocus instance. * Plan-multitenant-saas-hardening (P1): everything multitenant needs beyond what Plan-multitenant-cursor-sync already covers. Invites and role management, soft-delete + append-only audit log, rate limits on the auth + mutation hot paths, and a Vitest + GitHub Actions test foundation so PRs can't ship red. * Plan-agent-coordination (P2): the layer that makes a Task-*.md runnable, not just readable. Adds workflow_prompt with task -> epic -> plan inheritance, an agent_runs table for auditable sessions, and two new MCP tools (claim_task / complete_task) that replace the freeform update_object composition agents do today. Includes an intentionally-deferred Epic-optional-orchestrator that captures the Symphony-shaped runner as a decision point rather than an immediate build. Each task is bead-scale (one focused Cursor session) with explicit in-scope, out-of-scope, and anti-goal sections so a future agent can pick up a single Task-*.md and start without scrollback context. Co-authored-by: Cursor <cursoragent@cursor.com>
98 lines
3.6 KiB
Markdown
98 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`
|