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>
93 lines
3.4 KiB
Markdown
93 lines
3.4 KiB
Markdown
---
|
|
kind: task
|
|
slug: mcp-claim-task-tool
|
|
title: MCP claim_task tool — open an agent_runs row and return the prompt
|
|
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 `claim_task` that an agent calls at session start. It flips the backlog item to `in_progress`, opens an `agent_runs` row, and returns the effective workflow prompt + run id.
|
|
|
|
## Description
|
|
|
|
### Contract
|
|
|
|
Register in `apps/mcp-server/src/tools/claim-task.ts` (mirror the structure of `create-object.ts`).
|
|
|
|
Input zod schema:
|
|
|
|
```typescript
|
|
{
|
|
workspace: string, // slug or UUID, resolved via resolveWorkspaceHandle
|
|
backlogItemId: string, // uuid
|
|
actorUserId?: string, // optional — defaults to null ("system / dev session")
|
|
notes?: string, // short opener text the agent can attach to the run
|
|
}
|
|
```
|
|
|
|
Behavior:
|
|
|
|
1. Resolve the workspace handle (existing helper).
|
|
2. Look up the backlog item; verify it belongs to the resolved workspace. 404 otherwise.
|
|
3. Check for an existing open `agent_runs` row (`finished_at IS NULL`) for this `backlog_item_id`:
|
|
- If one exists *with the same `actor_user_id`*: return it (idempotent re-claim). Refresh its `notes` if provided.
|
|
- If one exists *with a different actor* (or actor is null on both sides): return error `ALREADY_CLAIMED` with the existing actor id (or "anonymous").
|
|
4. Insert a new `agent_runs` row: `workspace_id`, `backlog_item_id`, `actor_user_id`, `started_at=now()`, `notes`.
|
|
5. Update the backlog item: `status='in_progress'` (only if currently `ready` or `draft`; leave alone if already `in_progress` or `done`).
|
|
6. Compute and return:
|
|
- `runId`: the new `agent_runs.id`
|
|
- `workflowPrompt`: result of `resolveWorkflowPrompt`
|
|
- `backlogItem`: a minimal snapshot (`title`, `body_markdown`, `status`)
|
|
|
|
### Output shape
|
|
|
|
Use the existing `toolOk` / `toolErr` helpers in `apps/mcp-server/src/tools/tool-result.ts`. Return as structured tool output so the in-session model can pattern-match.
|
|
|
|
### Audit log
|
|
|
|
Write an `audit_log` row (`action: "task.claimed"`, `target_type: "agent_run"`, `target_id: runId`, `metadata: { backlog_item_id, prior_status }`). Assumes `audit_log` from `Plan-multitenant-saas-hardening` has landed; if not, file a follow-up to add audit writes when it does.
|
|
|
|
### Anti-goals
|
|
|
|
- No re-fetching from external systems. The tool only touches Echodo's DB.
|
|
- No "soft lock" mechanic (timeout-based claims). If a run goes stale, the operator (or `complete_task`) ends it explicitly.
|
|
|
|
## Subtasks
|
|
|
|
- [ ] Create `apps/mcp-server/src/tools/claim-task.ts`.
|
|
- [ ] Register in `apps/mcp-server/src/tools/index.ts`.
|
|
- [ ] Implement the 6-step behavior with proper zod validation.
|
|
- [ ] Audit log write (or follow-up task if `audit_log` isn't in yet).
|
|
- [ ] Verify by running the MCP server locally and calling the tool with a stub agent.
|
|
|
|
## Owner or assignee
|
|
|
|
Unassigned
|
|
|
|
## Status
|
|
|
|
ready
|
|
|
|
## Estimation
|
|
|
|
M
|
|
|
|
## Acceptance criteria
|
|
|
|
- [ ] Successful claim returns `runId`, `workflowPrompt`, and `backlogItem`.
|
|
- [ ] Re-claim by same actor returns the same `runId`.
|
|
- [ ] Claim by different actor errors with `ALREADY_CLAIMED`.
|
|
- [ ] Backlog item transitions to `in_progress` only if previously `ready` or `draft`.
|
|
|
|
## Links to related Epic / Plan
|
|
|
|
- Epic: `./Epic-mcp-claim-complete.md`
|
|
- Plan: `../Plan-agent-coordination.md`
|