From 787b7fb1aed92c2b701724a7741576053b93cccb Mon Sep 17 00:00:00 2001 From: Claude Sonnet 5 Date: Fri, 3 Jul 2026 23:01:50 +0000 Subject: feat(role): add versioned role configs + escalation ladder + scheduler (Phase 5) Two parts: Part A (fixes a gap from Phase 1): Groq/OpenRouter/OpenAI were documented in docs/api-keys-setup.md as usable once configured, but nothing actually constructed runners for them. internal/cli/cloudrunners.go consolidates anthropic/google/groq/openrouter/openai NativeRunner construction into one table-driven registerCloudRunners() helper, replacing the two hand-written per-provider blocks in serve.go/run.go. Groq/OpenRouter/OpenAI reuse openaicompat (no new adapter code) at SandboxKind: "docker". Part B: the token-husbanding harness's core routing mechanism. - internal/role: RoleConfig/Tier/Rung -- a role's system prompt and a multi-tier (provider, model) escalation ladder, versioned via config_json. - storage: new role_configs table (draft/active/retired, UNIQUE(role, version)) with transactional activate-retires-prior-active semantics; new executions.escalation_rung column. - task.AgentConfig.Role string -- purely additive; every existing task shape (Agent.Role == "") is unaffected, proven by TestPool_Execute_NonRoleTask_Unaffected plus the full pre-existing suite passing unchanged. - executor.Pool.execute(): role-typed tasks with no Agent.Type yet resolve tier 0 of their active ladder (round-robin across multi-candidate tiers, skipping rate-limited providers, falling back to soonest-clearing) before the existing pickAgent/Classifier path runs; SystemPrompt applies to Agent.SystemPromptAppend. Already-resolved role tasks (scheduler resubmits) get their escalation_rung re-derived read-only via findTierIndex. - internal/scheduler: polls role-typed FAILED tasks, retries at the same rung under MaxRetries or escalates to the next tier's first candidate when budget.Accountant.Allow() permits (emitting event.KindEscalated), else leaves the task FAILED with a final:true KindEscalated event. An in-memory per-execution-ID "handled" set keeps the poll loop convergent. Started by `serve` only, config knob [scheduler].poll_interval_seconds. - internal/api: POST/GET /api/roles/{role}/versions, POST /api/roles/{role}/activate -- unauthenticated, matching the existing projects/tasks REST endpoints' auth posture (only chatbot MCP, agent MCP, and WebSocket are api_token-gated in this codebase today). Documented as stored-but-not-yet-enforced (CLAUDE.md Design Debt, matching how task.Priority/RetryConfig are already documented): RoleConfig.Tools/ SandboxKind don't affect dispatch yet; DefaultBudgetUSD is read narrowly as the scheduler's escalation cost estimate, not enforced at initial dispatch; scheduler escalation always targets Candidates[0] (no round-robin, unlike initial-dispatch tier-0 resolution); the scheduler's dedupe is per-process and resets on restart (idempotent, harmless). go build/vet/test -race -count=1 all pass, 21 packages. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs --- internal/role/role.go | 73 ++++++++++++++++++++++++++++++++++++++++++++++ internal/role/role_test.go | 73 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 internal/role/role.go create mode 100644 internal/role/role_test.go (limited to 'internal/role') diff --git a/internal/role/role.go b/internal/role/role.go new file mode 100644 index 0000000..f65edba --- /dev/null +++ b/internal/role/role.go @@ -0,0 +1,73 @@ +// Package role defines the per-role configuration shape (system prompt, tool +// allowlist, sandbox kind, budget, and — the part actually driven this phase — +// a multi-tier provider/model escalation ladder) used by the token-husbanding +// harness. A RoleConfig is stored as a versioned row in storage's +// role_configs table (see internal/storage/roleconfig.go); internal/executor +// resolves tier 0 of a role's EscalationLadder for the initial dispatch of a +// role-typed task, and internal/scheduler walks the ladder on failure +// (retry-then-escalate). +// +// Not everything on RoleConfig is enforced yet. See the field doc comments +// below and CLAUDE.md's Design Debt section for what's stored-but-not-wired, +// matching how this codebase already documents task.Priority/RetryConfig. +package role + +// RoleConfig is one version of a role's configuration. +type RoleConfig struct { + // Role names the role this config applies to (e.g. "coder", "reviewer"). + Role string `json:"role"` + + // SystemPrompt is appended to Agent.SystemPromptAppend when a task + // dispatches through this role (internal/executor.Pool.execute()). Wired. + SystemPrompt string `json:"system_prompt,omitempty"` + + // Tools, SandboxKind, and DefaultBudgetUSD are stored and round-tripped + // through the API/storage layer but are NOT YET enforced by the executor: + // guardrails/tool availability are still applied uniformly by + // NativeRunner (Phase 3) regardless of role, and SandboxKind here has no + // effect on which sandbox.Sandbox implementation a runner picks (that's + // still purely provider-driven, see NativeRunner.SandboxKind). A later + // phase should thread these through. DefaultBudgetUSD is read by + // internal/scheduler as the estimated cost passed to + // budget.Accountant.Allow() when considering an escalation, which is a + // narrow, specific use — not general per-role budget enforcement at + // dispatch time. + Tools []string `json:"tools,omitempty"` + SandboxKind string `json:"sandbox_kind,omitempty"` + DefaultBudgetUSD float64 `json:"default_budget_usd,omitempty"` + + // EscalationLadder is the ordered list of tiers a role-typed task climbs + // on repeated failure. Tier 0 is used for the initial dispatch. + EscalationLadder []Tier `json:"escalation_ladder,omitempty"` +} + +// Tier is one rung-group in an escalation ladder: a set of candidate +// (provider, model) rungs to choose among, plus how many attempts may be made +// at this tier before the scheduler escalates to the next one. +type Tier struct { + Candidates []Rung `json:"candidates"` + // SelectionMode is "round_robin" (default, when empty) or "single" (always + // use Candidates[0]). + SelectionMode string `json:"selection_mode,omitempty"` + // MaxRetries is the number of attempts allowed at this tier before the + // scheduler escalates to the next tier. 0 means "escalate immediately + // after the first failure at this tier" (no retries held here). + MaxRetries int `json:"max_retries"` +} + +// Rung is a single (provider, model) pair. Provider must match a registered +// executor runner key: "local", "anthropic", "google", "groq", "openrouter", +// "openai". +type Rung struct { + Provider string `json:"provider"` + Model string `json:"model"` +} + +// EffectiveSelectionMode returns t.SelectionMode, defaulting to +// "round_robin" when unset. +func (t Tier) EffectiveSelectionMode() string { + if t.SelectionMode == "" { + return "round_robin" + } + return t.SelectionMode +} diff --git a/internal/role/role_test.go b/internal/role/role_test.go new file mode 100644 index 0000000..6d2294e --- /dev/null +++ b/internal/role/role_test.go @@ -0,0 +1,73 @@ +package role + +import ( + "encoding/json" + "reflect" + "testing" +) + +func TestRoleConfig_JSONRoundTrip(t *testing.T) { + rc := RoleConfig{ + Role: "coder", + SystemPrompt: "You are a careful coding agent.", + Tools: []string{"Bash", "Read", "Edit"}, + SandboxKind: "docker", + DefaultBudgetUSD: 1.5, + EscalationLadder: []Tier{ + { + Candidates: []Rung{ + {Provider: "local", Model: "llama3.1:8b"}, + }, + SelectionMode: "single", + MaxRetries: 2, + }, + { + Candidates: []Rung{ + {Provider: "groq", Model: "llama-3.3-70b-versatile"}, + {Provider: "openrouter", Model: "meta-llama/llama-3.3-70b-instruct:free"}, + }, + SelectionMode: "round_robin", + MaxRetries: 1, + }, + { + Candidates: []Rung{ + {Provider: "anthropic", Model: "claude-sonnet-5"}, + }, + MaxRetries: 0, + }, + }, + } + + b, err := json.Marshal(rc) + if err != nil { + t.Fatalf("Marshal: %v", err) + } + + var got RoleConfig + if err := json.Unmarshal(b, &got); err != nil { + t.Fatalf("Unmarshal: %v", err) + } + + if !reflect.DeepEqual(rc, got) { + t.Errorf("round trip mismatch:\n want: %+v\n got: %+v", rc, got) + } +} + +func TestTier_EffectiveSelectionMode(t *testing.T) { + cases := []struct { + name string + tier Tier + want string + }{ + {"empty defaults to round_robin", Tier{}, "round_robin"}, + {"explicit single", Tier{SelectionMode: "single"}, "single"}, + {"explicit round_robin", Tier{SelectionMode: "round_robin"}, "round_robin"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := c.tier.EffectiveSelectionMode(); got != c.want { + t.Errorf("got %q, want %q", got, c.want) + } + }) + } +} -- cgit v1.2.3