feat: orchestrate zero-swarm two-stage ticks

apps/game-api/src/app.ts

@@ -6,7 +6,11 @@ import {
   AgentProviderError,
   OpenRouterModelCatalog,
   OpenRouterAgentProvider,
+  OpenRouterSwarmPlanner,
+  TypeSafeJevReflexProvider,
   type AgentProvider,
+  type ReflexProvider,
+  type SwarmPlanner,
 } from '@hexzero/agent-runtime';
 import {
   archiveExperimentExportRequestSchema,
@@ -74,6 +78,8 @@ export { healthResponseSchema };
 export interface AppOptions {
   service?: SimulationService;
   provider?: AgentProvider;
+  swarmPlanner?: SwarmPlanner;
+  reflexProvider?: ReflexProvider;
   catalog?: Pick<OpenRouterModelCatalog, 'getCatalog'>;
   geocoder?: Geocoder;
   archiveExperimentExport?: (
@@ -134,6 +140,8 @@ export function createApp(options: AppOptions = {}) {
     options.service ??
     new SimulationService({
       provider: options.provider ?? providerFromEnvironment(),
+      swarmPlanner: options.swarmPlanner ?? new OpenRouterSwarmPlanner(),
+      reflexProvider: options.reflexProvider ?? new TypeSafeJevReflexProvider(),
     });
   const catalog =
     options.catalog ??
@@ -545,10 +553,14 @@ export function createApp(options: AppOptions = {}) {
     try {
       const response = await mutationPromise(context, 'tick', async () => {
         const records = await service.executeNextTick();
+        const snapshot = service.getSnapshot();
         return singleTickResponseSchema.parse({
-          snapshot: service.getSnapshot(),
-          tickNumber: records[0]!.tickNumber,
+          snapshot,
+          tickNumber: snapshot.tickNumber,
           records,
+          ...(snapshot.scenario.cognitionMode === 'zero-swarm-v1'
+            ? { swarmTick: snapshot.swarmTicks?.at(-1) }
+            : {}),
         });
       });
       return context.json(response);

apps/game-api/src/experiment-export.ts

@@ -38,6 +38,7 @@ import {
   type ProviderAttemptRecord,
   type ProviderAttemptRetention,
   type ExperimentAttemptAccounting,
+  type SwarmTickRecord,
 } from '@hexzero/shared';
 
 export interface ExperimentSource {
@@ -48,6 +49,7 @@ export interface ExperimentSource {
   retentionLimit: number;
   totalCompletedTurns: number;
   turns: readonly AgentTurnRecord[];
+  swarmTicks?: readonly SwarmTickRecord[];
   initialAgents: readonly Agent[];
   currentAgents: readonly Agent[];
   configurationEvents: readonly ExperimentConfigurationEvent[];
@@ -745,6 +747,18 @@ export function createExperimentExport(
     requestedRangeExtendsBeyondRetention,
   };
   const include = inclusionsFor(request);
+  const exportedSwarmTicks: SwarmTickRecord[] | undefined =
+    source.scenario.cognitionMode === 'zero-swarm-v1' &&
+    request.agents.mode === 'all' &&
+    request.turns.mode === 'entire-retained'
+      ? [...structuredClone(source.swarmTicks ?? [])]
+      : undefined;
+  const selectedTickNumbers = new Set([
+    ...filtered
+      .map(({ tickNumber }) => tickNumber)
+      .filter((tick): tick is number => tick !== undefined),
+    ...(exportedSwarmTicks ?? []).map(({ tickNumber }) => tickNumber),
+  ]);
   const selectedAgents = source.currentAgents
     .filter(({ id }) => selectedSet.has(id))
     .map((agent) =>
@@ -779,22 +793,24 @@ export function createExperimentExport(
       matchingTurnCount: filtered.length,
       ...(source.schemaVersion === 10 || source.schemaVersion === 11
         ? {
-            matchingTickCount: new Set(
-              filtered.map(({ tickNumber }) => tickNumber).filter(Boolean),
-            ).size,
+            matchingTickCount:
+              exportedSwarmTicks?.length ??
+              new Set(
+                filtered.map(({ tickNumber }) => tickNumber).filter(Boolean),
+              ).size,
           }
         : {}),
+      ...(exportedSwarmTicks
+        ? { matchingSwarmTickCount: exportedSwarmTicks.length }
+        : {}),
       matchingCommunicationCount: communications.length,
       matchingControlChangeCount: controlChanges.length,
       matchingDiplomacyEventCount: allianceEvents.length,
       ...(source.schemaVersion === 11
         ? { matchingProviderAttemptCount: providerAttempts.length }
         : {}),
       matchingSimulatedPlayerEventCount: source.simulatedPlayerEvents.filter(
-        (event) =>
-          new Set(
-            filtered.map(({ tickNumber }) => tickNumber).filter(Boolean),
-          ).has(event.originatingTick),
+        (event) => selectedTickNumbers.has(event.originatingTick),
       ).length,
       firstMatchingTurn: filtered[0]?.turnNumber,
       lastMatchingTurn: filtered.at(-1)?.turnNumber,
@@ -857,10 +873,7 @@ export function createExperimentExport(
               return [structuredClone(turn.worldActionResult.event)];
             }),
             ...source.simulatedPlayerEvents.filter((event) => {
-              const selectedTicks = new Set(
-                filtered.map(({ tickNumber }) => tickNumber).filter(Boolean),
-              );
-              return selectedTicks.has(event.originatingTick);
+              return selectedTickNumbers.has(event.originatingTick);
             }),
           ],
         }
@@ -873,6 +886,7 @@ export function createExperimentExport(
       : {}),
     allianceEvents: structuredClone(allianceEvents),
     turns: filtered.map((turn) => exportTurn(turn, request)),
+    ...(exportedSwarmTicks ? { swarmTicks: exportedSwarmTicks } : {}),
     ...(source.schemaVersion === 10 || source.schemaVersion === 11
       ? { tickSummaries: summarizeTicks(filtered) }
       : {}),
@@ -995,6 +1009,9 @@ export function createExperimentPreview(
     ...(document.selection.matchingTickCount === undefined
       ? {}
       : { matchingTickCount: document.selection.matchingTickCount }),
+    ...(document.selection.matchingSwarmTickCount === undefined
+      ? {}
+      : { matchingSwarmTickCount: document.selection.matchingSwarmTickCount }),
     matchingCommunicationCount: document.selection.matchingCommunicationCount,
     matchingControlChangeCount: document.selection.matchingControlChangeCount,
     matchingDiplomacyEventCount: document.selection.matchingDiplomacyEventCount,

apps/game-api/src/reflex-execution.test.ts

@@ -52,7 +52,7 @@ describe('zero-swarm reflex execution seam', () => {
     });
     expect(snapshot.scenario.cognitionMode).toBe('zero-swarm-v1');
     await expect(service.executeNextTick()).rejects.toThrow(
-      'Zero-swarm ticks require the Agent Zero planner',
+      'Zero-swarm execution requires a planner and reflex provider',
     );
     expect(service.getSnapshot().tickNumber).toBe(0);
   });

apps/game-api/src/reflex-execution.ts

@@ -21,6 +21,7 @@ import {
   type WorldState,
 } from '@hexzero/world-engine';
 import { AttemptAccounting } from './attempt-accounting';
+import { geographicDirectionBetweenCells } from './geographic-direction';
 
 export interface ReflexLocalHistory {
   previousCell?: H3Cell;
@@ -88,7 +89,11 @@ function actionDescription(
         : nextDistance > currentDistance
           ? 'This moves away from the assigned target.'
           : 'This maintains the current target distance.';
-  return `Move into adjacent ${terrain}. ${progress}`;
+  const direction = geographicDirectionBetweenCells(
+    agent.currentCell,
+    action.targetCell,
+  );
+  return `Move ${direction} into adjacent ${terrain}. ${progress}`;
 }
 
 /** Compile only engine-legal actions from one frozen world state. */
@@ -185,6 +190,8 @@ export interface ReflexSelectionOptions {
   signal?: AbortSignal;
   deadlineAtMs?: number;
   accounting?: AttemptAccounting;
+  /** First HTTP dispatch consumes a permit reserved for the whole tick. */
+  initialPermitReserved?: boolean;
   intendedTickNumber?: number;
   intendedTurnNumber?: number;
   now?: () => string;
@@ -234,7 +241,7 @@ export async function chooseReflexWorldAction(
       deadlineAtMs: options.deadlineAtMs,
       beginAttempt: options.accounting
         ? (kind) => {
-            const permit = options.accounting!.startAdditional({
+            const details = {
               agentId: compiled.observation.agentId,
               intendedTurnNumber: options.intendedTurnNumber ?? 1,
               ...(options.intendedTickNumber
@@ -244,7 +251,11 @@ export async function chooseReflexWorldAction(
               startedAt: now(),
               modelId: model,
               reasoningProfile: 'provider-default',
-            });
+            } as const;
+            const permit =
+              kind === 'initial' && options.initialPermitReserved
+                ? options.accounting!.startReserved(details)
+                : options.accounting!.startAdditional(details);
             if (permit === null) return null;
             startedAttempts += 1;
             return (completion) =>