feat(swarm): compile semantic strategic options for Agent Zero - #73
Merged
Merged
Conversation
Introduces swarm-planner-v2: the model request contains no raw H3 cell IDs and no agent IDs. Server compiles bounded semantic options (≤8/worker) with opaque optionIds; Agent Zero selects optionId per worker; server resolves optionId → (mission, targetCell) authoritatively. - packages/shared: add strategicOptionSchema, worldSummarySchema, WorkerOptions; update ZeroStrategicObservation (remove strategicTargetCells, add worldSummary + workerOptions); bump schemaVersion → 13; SWARM_PLANNER_CONTRACT_VERSION → 'swarm-planner-v2' - apps/game-api: new strategic-options.ts compiler (hold always first, continue-active, expand ≤3 sector-diversified radius-4-first scan, evade ≤2 under pressure, reinforce ≤1, relocate capped at 1, priority-aware bounding, swarmDirectiveIssue final filter) - apps/game-api: simulation-service.ts wires compileStrategicOptions, removes offeredOptions map from #assertSwarmPlan, reverts hold+null-target at-target telemetry change - packages/agent-runtime: swarm-planner.ts updated for v2 contract (compactPlanSchema uses optionId, decodePlanChoice resolves server-side, planAuthorityIssue checks mission:targetCell keys, no raw cells in request) - docs: ADR 0034, update ARCHITECTURE/SECURITY/TESTING/README/GAMEPLAY_FOUNDATION - tests: 13 strategic-options unit tests (including 20-agent/radius-12 swarmDirectiveIssue assertion and priority-bounding reclaim-abandoned test); swarm test redesigned for completed-directive identity reporting Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
christopherjnelson
marked this pull request as ready for review
September 22, 2026 23:49
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agent Zero now chooses among engine-compiled, worker-relative semantic strategic options instead of global raw-H3 targets. Code owns geometry and legality; the model makes bounded judgments over opaque option IDs. See ADR 0034.
Why: in the 20-agent / ~469-cell real-provider run, ~140 of ~183 worker decisions were
hold, final infection was ~22/469 cells, and planner prompts reached ~15–16k tokens. v1 serialized every world cell plus a global target list built from lexicographically sorted H3 IDs sliced to 80 — worlds over 80 cells silently lost targets.Changes
apps/game-api/src/strategic-options.ts(new): deterministic compiler, ≤8 options per worker — hold (always), continue-active, expand (≤3, radius-4 scan with widening, one per 60° sector), evade (≤2, only under pressure, never reduces separation), reinforce (≤1, prefers reclaiming abandoned territory), relocate (≤1). Priority-aware bounding; greedy cross-worker deconfliction; every option pre-validated withswarmDirectiveIssue().swarm-planner-v2: model returns only{ workerId, optionId, priority, riskTolerance }. Request carries aworldSummaryand per-worker options — nocells, raw H3, or agent IDs; default-valued option fields omitted. Server mapsoptionId → (mission, targetCell); decode rejects unknown, cross-worker, repeated, and v1-shaped raw-H3 plans.#assertSwarmPlanchecks each directive against the options offered to that agent.{id, description}only).Prompt size (real
buildSwarmPlannerRequest)Request size now scales with roster, not world size.
Tests
Option compiler geometry/bounds/determinism/diversity/pressure tests; planner rejection tests; an end-to-end SimulationService → OpenRouterSwarmPlanner (mocked fetch) test asserting no H3 cell or agent UUID reaches the model and chosen options map to authoritative directives. Threat-awareness tests unchanged and green.
Validation
Owner-confirmed local:
pnpm validate(245 tests) andpnpm test:e2e(2/2).Follow-up
Owner real-provider scale run (20 agents, radius 12, trail hunter, Gemini Flash low, Jev, 10–20 ticks) to compare directive distribution, hold %, dispersion, captures, prompt tokens/cost against the prior run.
🤖 Generated with Claude Code