docs(ST-1111.9): document Claude job queue architecture and agent flow
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
2c2a246347
commit
b31d29bc2c
4 changed files with 125 additions and 2 deletions
|
|
@ -262,7 +262,7 @@ docs(ST-XXX): document profile feature
|
|||
|
||||
Scrum4Me heeft een eigen MCP-server in repo [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) die de REST-API als native tools voor Claude Code aanbiedt. Schema's worden gedeeld via een git submodule (`vendor/scrum4me`), niet gedupliceerd.
|
||||
|
||||
### Tools beschikbaar in Claude Code (16)
|
||||
### Tools beschikbaar in Claude Code (18)
|
||||
|
||||
**Read / context:**
|
||||
- `mcp__scrum4me__health` — service + DB ping
|
||||
|
|
@ -285,6 +285,10 @@ Scrum4Me heeft een eigen MCP-server in repo [`madhura68/scrum4me-mcp`](https://g
|
|||
- `mcp__scrum4me__list_open_questions` — eigen vragen, max 50, recente eerst
|
||||
- `mcp__scrum4me__cancel_question` — asker-only annulering van een eigen open vraag
|
||||
|
||||
**Job queue — agent worker mode (M13):**
|
||||
- `mcp__scrum4me__wait_for_job` — blokkeert ≤600s, claimt atomisch een QUEUED-job via FOR UPDATE SKIP LOCKED; retourneert volledige task-context (implementation_plan, story, pbi, sprint, repo_url). Zet stale CLAIMED-jobs (>30min) eerst terug naar QUEUED.
|
||||
- `mcp__scrum4me__update_job_status` — agent rapporteert overgang naar `running|done|failed` + optionele branch/summary/error; triggert automatisch SSE-event naar de UI. Auth: Bearer-token moet matchen `claimed_by_token_id`.
|
||||
|
||||
### Prompt
|
||||
|
||||
- `implement_next_story` (arg: `product_id`) — end-to-end workflow
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 414 KiB After Width: | Height: | Size: 470 KiB |
69
docs/plans/ST-1111-claude-job-trigger.md
Normal file
69
docs/plans/ST-1111-claude-job-trigger.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
# ST-1111 — 'Voer uit'-knop met Claude Code job queue
|
||||
|
||||
**Story:** Als developer wil ik op het solo-scherm per task een 'Voer uit'-knop, zodat ik mijn lokale Claude Code-sessie kan inschakelen om de taak uit te voeren.
|
||||
|
||||
**Branch:** `feat/M13-claude-job-queue`
|
||||
|
||||
---
|
||||
|
||||
## Sub-tasks en commits
|
||||
|
||||
| Task | Commit |
|
||||
|---|---|
|
||||
| ST-1111.1 DB: ClaudeJob model + enum + migration | `5274e1e` |
|
||||
| ST-1111.2 API: ClaudeJob status mappers | `a1b1f69` |
|
||||
| ST-1111.3 Server actions: enqueue + cancel | `9d9fb4b` |
|
||||
| ST-1111.4 SSE: ClaudeJob events op solo-stream + initial state | `ece0aa9` |
|
||||
| ST-1111.5 MCP-tools (scrum4me-mcp repo — aparte PR) | — |
|
||||
| ST-1111.6 UI: 'Voer uit' + cancel in TaskDetailDialog | `b9c65eb` |
|
||||
| ST-1111.7 UI: status-pill op SoloTaskCard | `dace427` |
|
||||
| ST-1111.8 Tests: mappers + actions | `2c2a246` |
|
||||
| ST-1111.9 Docs | dit bestand |
|
||||
|
||||
---
|
||||
|
||||
## Architectuur
|
||||
|
||||
### State machine
|
||||
|
||||
```
|
||||
QUEUED → CLAIMED → RUNNING → DONE
|
||||
→ FAILED
|
||||
→ CANCELLED (cancel-knop of server action)
|
||||
CLAIMED → QUEUED (stale cleanup, >30min, via wait_for_job)
|
||||
```
|
||||
|
||||
### NOTIFY-pijplijn
|
||||
|
||||
Omdat `claude_jobs` geen row-trigger heeft (zoals `tasks` en `stories`), stuurt de **server action** zelf `pg_notify` via `prisma.$executeRaw`:
|
||||
|
||||
```ts
|
||||
await prisma.$executeRaw`SELECT pg_notify('scrum4me_changes', ${JSON.stringify(payload)}::text)`
|
||||
```
|
||||
|
||||
Voordeel: expliciete controle over het payload-shape (met `type` i.p.v. `entity`). Nadeel: MCP-tools in de `scrum4me-mcp`-repo moeten hun eigen NOTIFY-aanroep hebben bij `update_job_status`.
|
||||
|
||||
### SSE-routing
|
||||
|
||||
De bestaande `/api/realtime/solo`-route herkent nu twee payload-shapes:
|
||||
- `entity: 'task'|'story'` — bestaande trigger-events
|
||||
- `type: 'claude_job_enqueued'|'claude_job_status'` — nieuwe job-events
|
||||
|
||||
Job-events worden gefilterd op `user_id + product_id`. Bij connect stuurt de route een `claude_jobs_initial`-event met alle actieve + recente (vandaag) jobs.
|
||||
|
||||
### Idempotency
|
||||
|
||||
`enqueueClaudeJobAction` weigert als `claude_jobs WHERE task_id=X AND status IN (QUEUED, CLAIMED, RUNNING)` bestaat. De client ontvangt `{ error, jobId }` zodat de UI naar de actieve job kan linken in plaats van een nieuw venstertje te openen.
|
||||
|
||||
---
|
||||
|
||||
## Beslissingen
|
||||
|
||||
**Waarom geen DB-trigger voor NOTIFY?**
|
||||
De MCP-server claimt jobs via raw SQL (FOR UPDATE SKIP LOCKED); die schrijft ook direct naar de DB. Een trigger zou clean zijn, maar de MCP-tools moeten hoe dan ook hun eigen NOTIFY-payload bouwen voor `update_job_status`. Applicatie-NOTIFY houdt de payloads consistent en expliciet.
|
||||
|
||||
**Waarom `cancelled` verwijderd uit de store?**
|
||||
Geannuleerde jobs zijn terminaal; het pill-element zou "Geannuleerd" tonen tot de gebruiker een refresh doet. In plaats daarvan wist `handleJobEvent` de entry bij `status === 'cancelled'` zodat de kaart teruggaat naar de "Voer uit"-staat.
|
||||
|
||||
**Auto-clear DONE/FAILED?**
|
||||
Niet geïmplementeerd in v1. De pill blijft staan totdat de SSE-connectie herstart (refresh, tab-hidden+visible). Acceptabel voor de eerste iteratie.
|
||||
|
|
@ -1001,6 +1001,56 @@ Iron-session cookie of Bearer-token (demo). De auth-check loopt éénmalig bij d
|
|||
|
||||
---
|
||||
|
||||
## Claude job queue (M13 — ST-1111)
|
||||
|
||||
Developers kunnen vanuit de Task Detail Dialog een lokale Claude Code-sessie inschakelen. De job queue zorgt voor coördinatie en realtime-status.
|
||||
|
||||
### State machine
|
||||
|
||||
```
|
||||
QUEUED → CLAIMED → RUNNING → DONE
|
||||
→ FAILED
|
||||
→ CANCELLED (door user)
|
||||
CLAIMED → QUEUED (stale claim cleanup, >30min)
|
||||
```
|
||||
|
||||
### ClaudeJob model
|
||||
|
||||
```
|
||||
claude_jobs
|
||||
id, user_id, product_id, task_id
|
||||
status: ClaudeJobStatus (QUEUED|CLAIMED|RUNNING|DONE|FAILED|CANCELLED)
|
||||
claimed_by_token_id (FK → api_tokens, nullable)
|
||||
claimed_at, started_at, finished_at
|
||||
branch, summary, error
|
||||
@@index([user_id, status])
|
||||
@@index([task_id, status])
|
||||
@@index([status, claimed_at]) — voor stale-claim cleanup
|
||||
```
|
||||
|
||||
### NOTIFY/LISTEN flow
|
||||
|
||||
```
|
||||
UI klikt 'Voer uit'
|
||||
→ enqueueClaudeJobAction() Server Action
|
||||
→ prisma.claudeJob.create(QUEUED)
|
||||
→ prisma.$executeRaw pg_notify('scrum4me_changes', {type:'claude_job_enqueued',...})
|
||||
→ /api/realtime/solo SSE server-side filter: user_id + product_id
|
||||
→ EventSource.onmessage browser: handleJobEvent()
|
||||
→ useSoloStore.claudeJobsByTaskId map
|
||||
→ SoloTaskCard pill + dialog-footer update
|
||||
```
|
||||
|
||||
### Idempotency
|
||||
|
||||
`enqueueClaudeJobAction` weigert een tweede enqueue als er al een job bestaat met `status IN (QUEUED, CLAIMED, RUNNING)`. Teruggestuurde fout bevat het bestaande `jobId` zodat de UI ernaar kan linken.
|
||||
|
||||
### Hybride-ready
|
||||
|
||||
De huidige implementatie verwacht een lokale Claude Code-sessie die `wait_for_job` aanroept vanuit `madhura68/scrum4me-mcp`. Toekomstige uitbreiding naar Vercel Sandbox (serverless agent) vereist alleen een nieuw claim-endpoint — het datamodel en SSE-flow zijn ongewijzigd.
|
||||
|
||||
---
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variabele | Doel | Waar te vinden |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue