@boxxy/dispatch 0.1.1 → 0.1.3

package/src/claims/claim-next.ts

@@ -0,0 +1,306 @@
+import { contentHash } from '@boxxy/content-hash';
+import type {
+  ActorRef,
+  AttemptId,
+  AttemptRow,
+  Claim,
+  ItemDetailRows,
+  ItemView,
+  JsonValue,
+  KeptSession,
+  LimitCount,
+  LimitName,
+  LoadedRules,
+  Recipe,
+  RecipeMaterial,
+  SessionMode,
+  Snapshot,
+  SpawnRequest,
+  StartPick,
+  StoreTx,
+  WakePick,
+} from '@boxxy/model';
+import { brandSchemas, toJSONValue } from '@boxxy/model';
+import { buildFrame, decide } from '@boxxy/planning';
+import invariant from 'tiny-invariant';
+import type { AttemptChange } from '../attempts/build-attempt-change.ts';
+import { buildAttemptChange } from '../attempts/build-attempt-change.ts';
+import type { ClaimedEvent, DecisionDraft } from '../attempts/types.ts';
+import { buildSnapshotHash } from './build-snapshot-hash.ts';
+import { pickKeptSession } from './pick-kept-session.ts';
+import type { ClaimInput, SpawnSettings } from './types.ts';
+
+// A race that `decide` did not see: the change took no lease or no seat. The runner ends the
+// tick's claim loop on it.
+export class ClaimRaceError extends Error {
+  constructor(result: string) {
+    super(`the claim lost a race: ${result}`);
+
+    this.name = 'ClaimRaceError';
+  }
+}
+
+// Picks with `decide` and writes the first pick, all inside one store lock. A start pick takes
+// the item-phase lease and its seats; a wake pick takes the sleeping attempt's seats.
+export function claimNext(input: ClaimInput): Promise<Claim | null> {
+  return input.store.exclusive(async (tx) => {
+    const runner = await tx.readRunner(input.runner);
+
+    if (runner?.paused === true) {
+      return null;
+    }
+
+    const snapshot = await tx.readSnapshot(input.now, input.rules);
+
+    const backoff = [...input.backoff.listHeld(input.now)];
+    const frame = buildFrame({ snapshot, rules: input.rules, now: input.now });
+    const decision = decide({ frame, pools: input.rules.pools, snapshot, backoff });
+    const [pick] = decision.picks;
+
+    if (pick === undefined) {
+      return null;
+    }
+
+    const draft = {
+      rulesVersion: input.rules.version,
+      snapshotHash: buildSnapshotHash(snapshot, backoff),
+      storeVersion: snapshot.storeVersion,
+      pepysOffsets: {},
+      faults: frame.faults,
+      limits: collectLimitCounts(snapshot, pick.limits),
+    };
+
+    return pick.kind === 'start'
+      ? writeStartClaim(tx, input, pick, draft)
+      : writeWakeClaim(tx, input, pick, draft);
+  });
+}
+
+function collectLimitCounts(snapshot: Snapshot, limits: readonly LimitName[]): LimitCount[] {
+  return snapshot.limits
+    .filter((limit) => limits.includes(limit.name))
+    .map((limit) => ({ limit: limit.name, held: limit.held, max: limit.max }));
+}
+
+type SharedDraft = Omit<DecisionDraft, 'item' | 'kind' | 'pool'>;
+
+async function writeStartClaim(
+  tx: StoreTx,
+  input: ClaimInput,
+  pick: StartPick,
+  draft: SharedDraft,
+): Promise<Claim> {
+  const detail = await tx.readItemDetail(pick.item, input.now, input.rules);
+
+  invariant(detail !== null, `decide picked the item ${pick.item}, which the store holds`);
+
+  const event = buildClaimedEvent({
+    pick,
+    detail,
+    rules: input.rules,
+    settings: input.spawn,
+    attempt: brandSchemas.attemptId.parse(input.newId()),
+    leaseGen: (await tx.readLastLeaseGen(pick.item, pick.phase)) + 1,
+    draft,
+    runner: input.runner,
+  });
+
+  const built = buildAttemptChange({ ...buildBase(input), attempt: null, event: event.claimed });
+
+  const attempt = await writeClaimChange(tx, built, event.claimed.attempt);
+
+  return { kind: 'start', attempt, spawn: event.spawn, kept: event.kept };
+}
+
+interface ClaimedParts {
+  readonly pick: StartPick;
+  readonly detail: ItemDetailRows;
+  readonly rules: LoadedRules;
+  readonly settings: SpawnSettings;
+  readonly attempt: AttemptId;
+  readonly leaseGen: number;
+  readonly draft: SharedDraft;
+  readonly runner: ClaimInput['runner'];
+}
+
+// The new attempt's round, input, mode, recipe and spawn request. Pure.
+function buildClaimedEvent(parts: ClaimedParts): {
+  readonly claimed: ClaimedEvent;
+  readonly spawn: SpawnRequest;
+  readonly kept: KeptSession | null;
+} {
+  const item = parts.detail.item;
+  const phase = parts.rules.phases.get(parts.pick.phase);
+  const kind = parts.rules.kinds.get(item.kind);
+
+  invariant(phase !== undefined, `the rules load every phase of a pipeline: ${parts.pick.phase}`);
+  invariant(kind !== undefined, `decide picks only an item of a loaded kind: ${item.kind}`);
+
+  const mode: SessionMode = phase.mode?.(item) ?? 'agent';
+
+  const recipeName =
+    (mode === 'attended' ? kind.recipes[`${parts.pick.phase}/attended`] : undefined) ??
+    kind.recipes[parts.pick.phase];
+
+  const material = recipeName === undefined ? undefined : parts.rules.recipes.get(recipeName);
+
+  invariant(
+    material !== undefined,
+    `the loader refuses a step with no recipe: ${parts.pick.phase}`,
+  );
+
+  const phaseInput = phase.input({
+    item,
+    history: parts.detail.attempts,
+    pullRequests: parts.detail.pullRequests,
+  });
+
+  const spawn = buildSpawnRequest({
+    item,
+    attempt: parts.attempt,
+    recipe: material.recipe,
+    input: phaseInput,
+    settings: parts.settings,
+  });
+
+  const kept = pickKeptSession({
+    item,
+    attempts: parts.detail.attempts,
+    pipeline: kind.pipeline,
+    phase: parts.pick.phase,
+  });
+
+  return {
+    spawn,
+    kept,
+    claimed: {
+      kind: 'claimed',
+      attempt: parts.attempt,
+      pick: parts.pick,
+      number: 1 + parts.detail.attempts.filter((row) => row.phase === parts.pick.phase).length,
+      runner: parts.runner,
+      leaseGen: parts.leaseGen,
+      recipe: {
+        hash: buildRecipeHash(material, parts.rules),
+        rulesVersion: parts.rules.version,
+      },
+      skillsRef: parts.rules.skills?.ref ?? null,
+      spawnRequest: toJSONValue(spawn),
+      spawnRequestHash: contentHash(toJSONValue(spawn)),
+      input: phaseInput,
+      mode,
+
+      // the resumed session makes its first call before the worker answers the resume
+      caller: kept?.caller ?? null,
+      decision: { ...parts.draft, item: item.id, kind: 'start', pool: parts.pick.pool },
+    },
+  };
+}
+
+interface SpawnParts {
+  readonly item: ItemView;
+  readonly attempt: AttemptId;
+  readonly recipe: Recipe;
+  readonly input: JsonValue;
+  readonly settings: SpawnSettings;
+}
+
+function buildSpawnRequest(parts: SpawnParts): SpawnRequest {
+  const cwd = parts.settings.repoPaths.get(parts.item.repo);
+  const template = parts.settings.prompts.get(parts.recipe.prompt);
+
+  invariant(cwd !== undefined, `the configuration names no path for the repo ${parts.item.repo}`);
+  invariant(template !== undefined, `the rules checkout has no prompt ${parts.recipe.prompt}`);
+
+  return {
+    target: parts.settings.target,
+    cwd,
+    prompt: renderPrompt(template, {
+      title: parts.item.title,
+      outcome: parts.item.outcome,
+      repo: parts.item.repo,
+      attempt_id: parts.attempt,
+      acceptance: parts.item.acceptance
+        .map((criterion) => `- ${criterion.id}: ${criterion.text}`)
+        .join('\n'),
+      input: JSON.stringify(parts.input, null, 2),
+    }),
+    agent: parts.recipe.agent,
+    model: parts.recipe.model,
+    effort: parts.recipe.effort,
+    name: `boxxy/${parts.attempt}`,
+    idempotencyKey: parts.attempt,
+  };
+}
+
+// Each `{{name}}` with a value is replaced; any other text stays as it is.
+function renderPrompt(template: string, values: Readonly<Record<string, string>>): string {
+  return template.replaceAll(
+    /\{\{(?<name>[a-z_]+)\}\}/gu,
+    (whole, name: string) => values[name] ?? whole,
+  );
+}
+
+// The recipe hash covers the recipe's fields, its prompt, the rules version and the skills pin.
+function buildRecipeHash(material: RecipeMaterial, rules: LoadedRules) {
+  const hash = contentHash(
+    toJSONValue({
+      recipe: material.recipe,
+      promptHash: material.promptHash,
+      rulesVersion: material.rulesVersion,
+      skills: rules.skills,
+    }),
+  );
+
+  return brandSchemas.recipeHash.parse(hash);
+}
+
+function buildBase(input: ClaimInput) {
+  const actor: ActorRef = `boxxy:runner:${input.runner}`;
+
+  return { actor, now: input.now, newId: input.newId };
+}
+
+async function writeClaimChange(
+  tx: StoreTx,
+  built: AttemptChange,
+  id: AttemptId,
+): Promise<AttemptRow> {
+  invariant(built.kind === 'change', `the attempt machine refused the claim of ${id}`);
+
+  const result = await tx.applyChange(built.change);
+
+  if (result.kind !== 'applied') {
+    throw new ClaimRaceError(result.kind);
+  }
+
+  const row = await tx.readAttempt(id);
+
+  invariant(row !== null, 'the claim wrote the attempt');
+
+  return row;
+}
+
+async function writeWakeClaim(
+  tx: StoreTx,
+  input: ClaimInput,
+  pick: WakePick,
+  draft: SharedDraft,
+): Promise<Claim> {
+  const attempt = await tx.readAttempt(pick.attempt);
+
+  invariant(attempt !== null, `decide picked the wake of ${pick.attempt}, which the store holds`);
+
+  const built = buildAttemptChange({
+    ...buildBase(input),
+    attempt,
+    event: {
+      kind: 'woken',
+      pick,
+      decision: { ...draft, item: attempt.item, kind: 'wake', pool: attempt.pool },
+      overCap: false,
+    },
+  });
+
+  return { kind: 'wake', attempt: await writeClaimChange(tx, built, attempt.id) };
+}

package/src/claims/pick-kept-session.ts

@@ -0,0 +1,41 @@
+import type { AttemptRow, ItemView, KeptSession, PhaseName, Pipeline } from '@boxxy/model';
+
+interface KeptSessionInput {
+  readonly item: ItemView;
+
+  // the item's attempts, oldest first
+  readonly attempts: readonly AttemptRow[];
+  readonly pipeline: Pipeline;
+
+  // the phase of the new claim
+  readonly phase: PhaseName;
+}
+
+// The item's kept session, when the claim came back to `phase` through an edge with
+// `resume: true`; else null. Pure.
+export function pickKeptSession(input: KeptSessionInput): KeptSession | null {
+  const kept = input.item.keptSession;
+
+  if (kept === null) {
+    return null;
+  }
+
+  const latest = input.attempts
+    .filter((attempt) => attempt.endedAt !== null && isCounted(attempt))
+    .toSorted((first, second) => (first.endedAt ?? 0) - (second.endedAt ?? 0))
+    .at(-1);
+
+  const step = input.pipeline.steps.find((candidate) => candidate.phase === latest?.phase);
+
+  const edge =
+    latest?.outcome === null || latest === undefined ? undefined : step?.on[latest.outcome];
+
+  return typeof edge === 'object' && 'to' in edge && edge.to === input.phase && edge.resume === true
+    ? kept
+    : null;
+}
+
+// the two failures that move no item
+function isCounted(attempt: AttemptRow): boolean {
+  return attempt.failure !== 'no-capacity' && attempt.failure !== 'usage-limit';
+}

package/src/claims/request-wake.ts

@@ -0,0 +1,17 @@
+import type { MoveResult } from '../attempts/types.ts';
+import { writeAttemptMove } from '../attempts/write-attempt-move.ts';
+import type { RequestWakeInput } from './types.ts';
+
+// The one way to ask for a wake: `boxxy item wake`, a session that runs while its attempt
+// sleeps, and a host that slept with no request all end here. The next claim seats the attempt
+// and resumes it. A second request, or an attempt that does not sleep, is `not-allowed`.
+export function requestWake(input: RequestWakeInput): Promise<MoveResult> {
+  return input.store.exclusive((tx) =>
+    writeAttemptMove(
+      tx,
+      input.attempt,
+      { kind: 'wake-requested', by: input.by },
+      { actor: input.actor, now: input.now, newId: input.newId },
+    ),
+  );
+}

package/src/claims/resume-claim.ts

@@ -0,0 +1,56 @@
+import type { ActorRef, SessionFault } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { writeAttemptMove } from '../attempts/write-attempt-move.ts';
+import { writeSessionBind } from '../attempts/write-session-bind.ts';
+import { timeouts } from '../timeouts.ts';
+import type { ResumeClaimInput } from './types.ts';
+
+const secondMs = 1000;
+
+// Resumes a woken attempt's session outside the store lock. A refusal for capacity sleeps the
+// row the claim woke again and holds its pool back; any other answer but `started` leaves it
+// `waking` for the reading to retry.
+export async function resumeClaim(input: ResumeClaimInput): Promise<SessionFault | null> {
+  const attempt = input.claim.attempt;
+  const actor: ActorRef = `boxxy:runner:${attempt.runner}`;
+  const base = { actor, now: input.now, newId: input.newId };
+
+  const outcome = await input.worker.resume(attempt);
+
+  if (outcome.kind === 'refused' && outcome.cause === 'capacity') {
+    input.backoff.hold(
+      attempt.pool,
+      brandSchemas.instant.parse(input.now + timeouts.capacityBackoffSeconds * secondMs),
+    );
+
+    await input.store.exclusive((tx) =>
+      writeAttemptMove(tx, attempt.id, { kind: 'wake-refused' }, { ...base, seen: attempt }),
+    );
+
+    return null;
+  }
+
+  if (outcome.kind !== 'started') {
+    return null;
+  }
+
+  return input.store.exclusive(async (tx) => {
+    const moved = await writeAttemptMove(
+      tx,
+      attempt.id,
+      { kind: 'resumed', atcSession: outcome.atcSession, caller: outcome.caller },
+      base,
+    );
+
+    const row = await tx.readAttempt(attempt.id);
+
+    return moved.kind === 'applied' && row !== null && outcome.agentSession !== null
+      ? writeSessionBind(
+          tx,
+          row,
+          { atcSession: outcome.atcSession, agentSession: outcome.agentSession },
+          base,
+        )
+      : null;
+  });
+}

package/src/claims/start-claim.ts

@@ -0,0 +1,99 @@
+import type { ActorRef, SessionFault, StartOutcome } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { match } from 'ts-pattern';
+import { writeAttemptMove } from '../attempts/write-attempt-move.ts';
+import { writeSessionBind } from '../attempts/write-session-bind.ts';
+import { settleAttempt } from '../closeouts/settle-attempt.ts';
+import { buildKeptClear } from '../sessions/build-kept-clear.ts';
+import { resumeKeptSession } from '../sessions/resume-kept-session.ts';
+import { timeouts } from '../timeouts.ts';
+import type { StartClaimInput } from './types.ts';
+
+const secondMs = 1000;
+
+// Starts the claim's session outside the store lock, and records the worker's answer. A refusal
+// for capacity settles `no-capacity` and holds the pool back. Returns the fault of an agent
+// session that another attempt holds, or null.
+export async function startClaim(input: StartClaimInput): Promise<SessionFault | null> {
+  const attempt = input.claim.attempt;
+  const actor: ActorRef = `boxxy:runner:${attempt.runner}`;
+  const base = { actor, now: input.now, newId: input.newId };
+  const kept = input.claim.kept;
+
+  const woken =
+    kept === null
+      ? { outcome: await input.worker.start(input.claim.spawn), resumeFallback: false }
+      : await resumeKeptSession(input.worker, kept, input.claim.spawn);
+
+  const outcome = woken.outcome;
+  const resumeFallback = woken.resumeFallback;
+  const keptClear = kept === null ? [] : [buildKeptClear(attempt.item, kept)];
+
+  return match<StartOutcome, Promise<SessionFault | null>>(outcome)
+    .with({ kind: 'started' }, (started) =>
+      input.store.exclusive(async (tx) => {
+        const moved = await writeAttemptMove(
+          tx,
+          attempt.id,
+          {
+            kind: 'started',
+            via: 'start',
+            atcSession: started.atcSession,
+            caller: started.caller,
+            resumeFallback,
+          },
+          { ...base, also: keptClear },
+        );
+
+        const row = await tx.readAttempt(attempt.id);
+
+        return moved.kind === 'applied' && row !== null && started.agentSession !== null
+          ? writeSessionBind(
+              tx,
+              row,
+              {
+                atcSession: started.atcSession,
+                agentSession: started.agentSession,
+                keptFrom: resumeFallback || kept === null ? null : kept.attempt,
+              },
+              base,
+            )
+          : null;
+      }),
+    )
+    .with({ kind: 'unknown' }, async (unknown) => {
+      await input.store.exclusive((tx) =>
+        writeAttemptMove(
+          tx,
+          attempt.id,
+          { kind: 'spawn-unanswered', reason: unknown.reason },
+          base,
+        ),
+      );
+
+      return null;
+    })
+    .with({ kind: 'refused' }, async (refused) => {
+      if (refused.cause === 'capacity') {
+        input.backoff.hold(
+          attempt.pool,
+          brandSchemas.instant.parse(input.now + timeouts.capacityBackoffSeconds * secondMs),
+        );
+      }
+
+      await settleAttempt({
+        ...base,
+        store: input.store,
+        attempt: attempt.id,
+        forced: refused.cause === 'capacity' ? 'no-capacity' : 'spawn-refused',
+        sessionStopped: true,
+
+        // a session recorded since, by another start of the same attempt, keeps it alive
+        seen: { atcSession: attempt.atcSession },
+        rules: input.rules,
+      });
+
+      return null;
+    })
+    .exhaustive();
+}

package/src/claims/types.ts

@@ -0,0 +1,67 @@
+import type {
+  ActorRef,
+  AttemptId,
+  CapacityBackoff,
+  Claim,
+  ClaimStore,
+  Instant,
+  LoadedRules,
+  NewId,
+  RepoName,
+  RunnerId,
+  WakeSource,
+  WorkerKind,
+} from '@boxxy/model';
+
+// What the server reads from its configuration and the rules checkout for a spawn request. A
+// module reads no files, so the claim gets these as input.
+export interface SpawnSettings {
+  // the worker target every session starts on
+  readonly target: string;
+
+  // each repo's path on the target
+  readonly repoPaths: ReadonlyMap<RepoName, string>;
+
+  // the text of each prompt template, by its path in the rules checkout
+  readonly prompts: ReadonlyMap<string, string>;
+}
+
+export interface ClaimInput {
+  readonly store: ClaimStore;
+  readonly runner: RunnerId;
+  readonly rules: LoadedRules;
+  readonly now: Instant;
+  readonly newId: NewId;
+
+  // the runner's memory of the pools in backoff
+  readonly backoff: CapacityBackoff;
+  readonly spawn: SpawnSettings;
+}
+
+export interface StartClaimInput {
+  readonly store: ClaimStore;
+  readonly worker: WorkerKind;
+  readonly rules: LoadedRules;
+  readonly claim: Extract<Claim, { kind: 'start' }>;
+  readonly now: Instant;
+  readonly newId: NewId;
+  readonly backoff: CapacityBackoff;
+}
+
+export interface ResumeClaimInput {
+  readonly store: ClaimStore;
+  readonly worker: WorkerKind;
+  readonly claim: Extract<Claim, { kind: 'wake' }>;
+  readonly now: Instant;
+  readonly newId: NewId;
+  readonly backoff: CapacityBackoff;
+}
+
+export interface RequestWakeInput {
+  readonly store: ClaimStore;
+  readonly attempt: AttemptId;
+  readonly by: WakeSource;
+  readonly actor: ActorRef;
+  readonly now: Instant;
+  readonly newId: NewId;
+}