feat(PBI-67): model + mode-selectie per ClaudeJob-kind (#169)

* feat(PBI-67/ST-1297): datamodel-velden voor job-model-selectie

Voegt 8 nieuwe optionele velden toe verspreid over Product, Task en
ClaudeJob ten dienste van de override-cascade:

  task.requires_opus → job.requested_* → product.preferred_* → kind-default

Bestaande rijen krijgen NULL (Product/ClaudeJob) of false (Task) en
vallen daarmee terug op de kind-defaults uit de resolver (ST-1298).

Migration is additief: alleen ALTER TABLE ADD COLUMN, geen RENAME of
DROP. Bestaande factories en seed-script blijven werken zonder
aanpassing omdat alle nieuwe velden default-waardes hebben.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-67/ST-1299): job-config snapshot bij enqueue + worker-flag-runbook

T-789: Snapshot van resolved JobConfig in ClaudeJob.requested_*
bij elke job-creatie. Helper in lib/job-config-snapshot.ts laadt
product (preferred_*) en task (requires_opus) en draait de resolver
uit lib/job-config.ts (mirror van scrum4me-mcp/src/lib/job-config.ts —
zelfde matrix, sync-comment in bestand). Toegepast op alle 5
enqueue-locaties:

  - actions/user-questions.ts          (PLAN_CHAT)
  - actions/sprint-runs.ts × 3         (SPRINT_IMPLEMENTATION x2,
                                        TASK_IMPLEMENTATION loop)
  - actions/ideas.ts                   (IDEA_GRILL / IDEA_MAKE_PLAN)

Test-mocks uitgebreid met product.findUnique en task.findUnique zodat
de helper bij unit tests veilig terugvalt op kind-defaults (alle 563
tests groen).

T-790: Sectie 'Config doorgeven aan Claude Code' toegevoegd aan
docs/runbooks/worker-idempotency.md met CLI-flag-mapping en de
verwachte aanroep per kind. Forward-link naar
docs/runbooks/job-model-selection.md (volgt in T-794).

Plus: docs/plans/job-model-selection.md (de approved plan-doc).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-67/ST-1300): cost-attribution voor thinking-tokens + admin UI

T-792: token-stats + token-history rekenen actual_thinking_tokens nu
mee in de totale kosten (tegen input-rate, conform Anthropic billing).
COALESCE-veilig zodat oude rijen 0 bijdragen i.p.v. NaN. Nieuwe export
`getTokenStatsByKind` aggregeert tokens en kosten per ClaudeJob.kind
zodat we relatieve uitgaven van IDEA_GRILL/IDEA_MAKE_PLAN/PLAN_CHAT/
TASK_IMPLEMENTATION/SPRINT_IMPLEMENTATION kunnen zien.

T-793: admin/jobs Kosten-tabel toont:
  - Nieuwe kolom 'Thinking' (aantal verbruikte thinking-tokens)
  - Mismatch-marker (rood) als requested_model afwijkt van actuele
    model_id — duidt op een worker die de CLI-flag niet doorgaf.
    Tooltip toont aangevraagd model. Geen Sentry/log-noise.

Page-level cost-berekening volgt dezelfde formule (input_price ×
thinking_tokens). 563 tests groen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(PBI-67/ST-1301): runbook + CLAUDE.md updates voor model/mode-selectie

T-794: Nieuwe runbook docs/runbooks/job-model-selection.md met
override-cascade, kind-default-matrix, override-voorbeelden,
auditspoor en cost-attribution-formule. 107 regels.

T-795: CLAUDE.md hardstop-bullet voor 'Model/mode per ClaudeJob'
(verwijst naar nieuwe runbook) + patterns-quickref-rij voor
job-config resolver. CLAUDE.md blijft 139 regels (≤ 150).

T-796: docs:check-links groen — 108 files, geen broken links. Twee
externe-repo verwijzingen (scrum4me-mcp/...) ge-de-linked tot plain
text omdat de check-links script de zustertree niet traverseert; de
referenties blijven leesbaar.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-05-08 11:20:10 +02:00 committed by GitHub
parent f233dd815e
commit 8c63ba377d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 648 additions and 9 deletions

View file

@ -57,12 +57,13 @@ export async function getSprintTokenHistory(
sp.id AS sprint_id,
sp.code AS sprint_code,
sp.sprint_goal,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens), 0) AS total_tokens,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens + COALESCE(cj.actual_thinking_tokens, 0)), 0) AS total_tokens,
SUM(
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
) FILTER (WHERE cj.input_tokens IS NOT NULL) AS total_cost,
COUNT(*) FILTER (WHERE cj.input_tokens IS NOT NULL) AS job_count
FROM claude_jobs cj
@ -82,12 +83,13 @@ export async function getSprintTokenHistory(
sp.id AS sprint_id,
sp.code AS sprint_code,
sp.sprint_goal,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens), 0) AS total_tokens,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens + COALESCE(cj.actual_thinking_tokens, 0)), 0) AS total_tokens,
SUM(
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
) FILTER (WHERE cj.input_tokens IS NOT NULL) AS total_cost,
COUNT(*) FILTER (WHERE cj.input_tokens IS NOT NULL) AS job_count
FROM claude_jobs cj
@ -118,12 +120,13 @@ export async function getDayTokenData(userId: string, sprintId: string): Promise
const rows = await prisma.$queryRaw<RawDayRow[]>`
SELECT
DATE(cj.finished_at) AS day,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens), 0) AS total_tokens,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens + COALESCE(cj.actual_thinking_tokens, 0)), 0) AS total_tokens,
SUM(
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
) FILTER (WHERE cj.input_tokens IS NOT NULL) AS total_cost
FROM claude_jobs cj
JOIN tasks t ON cj.task_id = t.id
@ -152,12 +155,13 @@ export async function getPbiTokenAggregates(userId: string, sprintId: string): P
p.id AS pbi_id,
p.code AS pbi_code,
p.title AS pbi_title,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens), 0) AS total_tokens,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens + COALESCE(cj.actual_thinking_tokens, 0)), 0) AS total_tokens,
SUM(
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
) FILTER (WHERE cj.input_tokens IS NOT NULL) AS total_cost
FROM claude_jobs cj
JOIN tasks t ON cj.task_id = t.id

View file

@ -16,10 +16,18 @@ export interface TokenJobRow {
outputTokens: number | null
cacheReadTokens: number | null
cacheWriteTokens: number | null
thinkingTokens: number | null
costUsd: number | null
durationSeconds: number | null
}
export interface TokenStatsByKindRow {
kind: string
jobCount: number
totalTokens: number
totalCostUsd: number
}
export interface TokenStatsResult {
kpi: TokenKpi
jobs: TokenJobRow[]
@ -41,10 +49,18 @@ type RawJobRow = {
output_tokens: number | null
cache_read_tokens: number | null
cache_write_tokens: number | null
actual_thinking_tokens: number | null
cost_usd: number | null
duration_seconds: number | null
}
type RawByKindRow = {
kind: string
job_count: bigint
total_tokens: bigint
total_cost: number | null
}
const EMPTY_KPI: TokenKpi = { totalTokens: 0, totalCostUsd: 0, avgCostPerJob: 0, jobCount: 0 }
export async function getTokenStats(userId: string, sprintId: string): Promise<TokenStatsResult> {
@ -53,18 +69,20 @@ export async function getTokenStats(userId: string, sprintId: string): Promise<T
const [kpiRows, jobRows] = await Promise.all([
prisma.$queryRaw<RawKpiRow[]>`
SELECT
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens), 0) AS total_tokens,
COALESCE(SUM(cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens + COALESCE(cj.actual_thinking_tokens, 0)), 0) AS total_tokens,
SUM(
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
) FILTER (WHERE cj.input_tokens IS NOT NULL) AS total_cost,
AVG(
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
) FILTER (WHERE cj.input_tokens IS NOT NULL) AS avg_cost,
COUNT(*) FILTER (WHERE cj.input_tokens IS NOT NULL) AS job_count
FROM claude_jobs cj
@ -85,11 +103,13 @@ export async function getTokenStats(userId: string, sprintId: string): Promise<T
cj.output_tokens,
cj.cache_read_tokens,
cj.cache_write_tokens,
cj.actual_thinking_tokens,
CASE WHEN cj.input_tokens IS NOT NULL THEN
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
END AS cost_usd,
EXTRACT(EPOCH FROM (cj.finished_at - cj.claimed_at)) AS duration_seconds
FROM claude_jobs cj
@ -122,8 +142,54 @@ export async function getTokenStats(userId: string, sprintId: string): Promise<T
outputTokens: r.output_tokens,
cacheReadTokens: r.cache_read_tokens,
cacheWriteTokens: r.cache_write_tokens,
thinkingTokens: r.actual_thinking_tokens,
costUsd: r.cost_usd != null ? Number(r.cost_usd) : null,
durationSeconds: r.duration_seconds != null ? Number(r.duration_seconds) : null,
})),
}
}
// PBI-67: per-kind aggregatie. Toont totaal tokens + kosten per ClaudeJob.kind
// binnen één sprint zodat we de relatieve uitgaven van IDEA_GRILL vs
// TASK_IMPLEMENTATION etc. kunnen zien. Voor jobs zonder sprint-koppeling
// (idea-jobs) blijven we filteren op user_id + sprint_id; idea-jobs zonder
// task vallen buiten deze view.
export async function getTokenStatsByKind(
userId: string,
sprintId: string,
): Promise<TokenStatsByKindRow[]> {
if (!sprintId) return []
const rows = await prisma.$queryRaw<RawByKindRow[]>`
SELECT
cj.kind::text AS kind,
COUNT(*) FILTER (WHERE cj.input_tokens IS NOT NULL) AS job_count,
COALESCE(SUM(
cj.input_tokens + cj.output_tokens + cj.cache_read_tokens + cj.cache_write_tokens
+ COALESCE(cj.actual_thinking_tokens, 0)
), 0) AS total_tokens,
SUM(
cj.input_tokens * mp.input_price_per_1m / 1000000.0
+ cj.output_tokens * mp.output_price_per_1m / 1000000.0
+ cj.cache_read_tokens * mp.cache_read_price_per_1m / 1000000.0
+ cj.cache_write_tokens * mp.cache_write_price_per_1m / 1000000.0
+ COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0
) FILTER (WHERE cj.input_tokens IS NOT NULL) AS total_cost
FROM claude_jobs cj
JOIN tasks t ON cj.task_id = t.id
JOIN stories s ON t.story_id = s.id
LEFT JOIN model_prices mp ON mp.model_id = cj.model_id
WHERE cj.user_id = ${userId}
AND s.sprint_id = ${sprintId}
AND cj.status = 'DONE'
GROUP BY cj.kind
ORDER BY total_cost DESC NULLS LAST
`
return rows.map((r) => ({
kind: r.kind,
jobCount: Number(r.job_count),
totalTokens: Number(r.total_tokens),
totalCostUsd: Number(r.total_cost ?? 0),
}))
}

View file

@ -0,0 +1,40 @@
// PBI-67: snapshot-helper voor ClaudeJob.requested_*-velden.
//
// Roep hem aan vóór elke `prisma.claudeJob.create({ data: { ... } })` en spread
// het resultaat in `data`. Doet één extra Product-query (en optioneel Task)
// om de override-cascade in te vullen op enqueue-tijd. Bij claim (in scrum4me-
// mcp/wait-for-job) wordt dezelfde resolver opnieuw aangeroepen — als
// requested_* dan al gezet zijn winnen die boven product/kind-defaults.
import { prisma } from '@/lib/prisma'
import { resolveJobConfig, snapshotFromConfig, type ClaudeJobSnapshotFields } from '@/lib/job-config'
export async function getJobConfigSnapshot(opts: {
kind: string
productId: string
taskId?: string | null
}): Promise<ClaudeJobSnapshotFields> {
const [product, task] = await Promise.all([
prisma.product.findUnique({
where: { id: opts.productId },
select: {
preferred_model: true,
thinking_budget_default: true,
preferred_permission_mode: true,
},
}),
opts.taskId
? prisma.task.findUnique({
where: { id: opts.taskId },
select: { requires_opus: true },
})
: Promise.resolve(null),
])
const cfg = resolveJobConfig(
{ kind: opts.kind },
product ?? {},
task ?? undefined,
)
return snapshotFromConfig(cfg)
}

141
lib/job-config.ts Normal file
View file

@ -0,0 +1,141 @@
// PBI-67: model + mode-selectie per ClaudeJob-kind.
//
// Sync with scrum4me-mcp/src/lib/job-config.ts — als je hier een veld
// aanpast, doe hetzelfde aan de MCP-kant. Dit is bewust een duplicate
// (geen gedeeld package) om de MCP-server eigenstandig te houden.
//
// Override-cascade (eerste match wint):
// 1. task.requires_opus === true → forceer Opus
// 2. job.requested_* (snapshot bij enqueue, ingevuld door deze module)
// 3. product.preferred_*
// 4. KIND_DEFAULTS hieronder
export type ClaudeModel =
| 'claude-opus-4-7'
| 'claude-sonnet-4-6'
| 'claude-haiku-4-5-20251001'
export type PermissionMode = 'plan' | 'default' | 'acceptEdits' | 'bypassPermissions'
export type JobConfig = {
model: ClaudeModel
thinking_budget: number
permission_mode: PermissionMode
max_turns: number | null
allowed_tools: string[] | null
}
export type JobInput = {
kind: string
requested_model?: string | null
requested_thinking_budget?: number | null
requested_permission_mode?: string | null
}
export type ProductInput = {
preferred_model?: string | null
thinking_budget_default?: number | null
preferred_permission_mode?: string | null
}
export type TaskInput = {
requires_opus?: boolean | null
}
const KIND_DEFAULTS: Record<string, JobConfig> = {
IDEA_GRILL: {
model: 'claude-sonnet-4-6',
thinking_budget: 12000,
permission_mode: 'plan',
max_turns: 15,
allowed_tools: ['Read', 'Grep', 'Glob', 'WebSearch', 'AskUserQuestion'],
},
IDEA_MAKE_PLAN: {
model: 'claude-opus-4-7',
thinking_budget: 24000,
permission_mode: 'plan',
max_turns: 20,
allowed_tools: ['Read', 'Grep', 'Glob', 'WebSearch', 'AskUserQuestion', 'Write'],
},
PLAN_CHAT: {
model: 'claude-sonnet-4-6',
thinking_budget: 6000,
permission_mode: 'plan',
max_turns: 5,
allowed_tools: ['Read', 'Grep', 'AskUserQuestion'],
},
TASK_IMPLEMENTATION: {
model: 'claude-sonnet-4-6',
thinking_budget: 6000,
permission_mode: 'bypassPermissions',
max_turns: 50,
allowed_tools: null,
},
SPRINT_IMPLEMENTATION: {
model: 'claude-sonnet-4-6',
thinking_budget: 6000,
permission_mode: 'bypassPermissions',
max_turns: null,
allowed_tools: null,
},
}
const FALLBACK: JobConfig = {
model: 'claude-sonnet-4-6',
thinking_budget: 6000,
permission_mode: 'default',
max_turns: 50,
allowed_tools: null,
}
export function getKindDefault(kind: string): JobConfig {
return KIND_DEFAULTS[kind] ?? FALLBACK
}
// max_turns en allowed_tools blijven kind-default (geen product/task override
// in V1 — als de behoefte ontstaat, voeg analoge velden toe aan Product/Task).
export function resolveJobConfig(
job: JobInput,
product: ProductInput,
task?: TaskInput,
): JobConfig {
const base = getKindDefault(job.kind)
const model = (
task?.requires_opus
? 'claude-opus-4-7'
: job.requested_model ?? product.preferred_model ?? base.model
) as ClaudeModel
const thinking_budget =
job.requested_thinking_budget ?? product.thinking_budget_default ?? base.thinking_budget
const permission_mode = (job.requested_permission_mode ??
product.preferred_permission_mode ??
base.permission_mode) as PermissionMode
return {
model,
thinking_budget,
permission_mode,
max_turns: base.max_turns,
allowed_tools: base.allowed_tools,
}
}
// Snapshot-velden voor ClaudeJob.requested_*. Bij elke enqueue laden we
// product (voor preferred_*) en optioneel task (voor requires_opus), draaien
// de resolver, en schrijven het resultaat als auditspoor in de job-rij.
export type ClaudeJobSnapshotFields = {
requested_model: string
requested_thinking_budget: number
requested_permission_mode: string
}
export function snapshotFromConfig(cfg: JobConfig): ClaudeJobSnapshotFields {
return {
requested_model: cfg.model,
requested_thinking_budget: cfg.thinking_budget,
requested_permission_mode: cfg.permission_mode,
}
}