94 lines
3.4 KiB
Markdown
94 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`
|