@boxxy/dispatch 0.1.1 → 0.1.3

package/src/attempts/end-item-attempts.ts

@@ -0,0 +1,95 @@
+import type {
+  ActorRef,
+  AnyNewFact,
+  AttemptId,
+  AttemptRow,
+  Instant,
+  NewId,
+  RowWrite,
+  StoreChange,
+} from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { buildAttemptChange } from './build-attempt-change.ts';
+import type { MoveEvent } from './types.ts';
+
+interface EndItemAttemptsInput {
+  // the item's live attempts, read in the same lock as the close
+  readonly attempts: readonly AttemptRow[];
+  readonly actor: ActorRef;
+  readonly now: Instant;
+  readonly newId: NewId;
+}
+
+export interface EndedAttempts {
+  // the lease of the item's live attempt; null when it has none
+  readonly under: NonNullable<StoreChange['under']> | null;
+  readonly writes: readonly RowWrite[];
+  readonly facts: readonly AnyNewFact[];
+
+  // what `boxxy.item.closed` lists
+  readonly ended: readonly { readonly attempt: AttemptId; readonly how: 'settled' | 'closing' }[];
+}
+
+// The writes that the close of an item makes to its live attempts. A sleeping attempt settles
+// at once, with no wake; a closing one is left as it is, for the runner to settle; any other
+// moves to `closing` and keeps its seats until the runner stops its session.
+export function endItemAttempts(input: EndItemAttemptsInput): EndedAttempts {
+  const moves = input.attempts.flatMap((attempt) => {
+    const event = pickEndEvent(attempt);
+
+    if (event === null) {
+      return [];
+    }
+
+    const built = buildAttemptChange({
+      attempt,
+      event,
+      actor: input.actor,
+      now: input.now,
+      newId: input.newId,
+    });
+
+    invariant(built.kind === 'change', `a ${attempt.state} attempt can end with its item`);
+
+    return [
+      {
+        change: built.change,
+        ended: {
+          attempt: attempt.id,
+          how: event.kind === 'settled' ? 'settled' : 'closing',
+        } as const,
+      },
+    ];
+  });
+
+  // an item stands at one phase, so it has one live attempt at most
+  invariant(moves.length <= 1, 'an item has one live attempt at most');
+
+  return {
+    under: moves[0]?.change.under ?? null,
+    writes: moves.flatMap((move) => move.change.writes),
+    facts: moves.flatMap((move) => move.change.facts),
+    ended: moves.map((move) => move.ended),
+  };
+}
+
+function pickEndEvent(attempt: AttemptRow): MoveEvent | null {
+  if (attempt.state === 'sleeping') {
+    return {
+      kind: 'settled',
+      state: 'failed',
+      failure: 'item-closed',
+      outcome: 'lost',
+      returnedOutcome: null,
+      sessionStopped: true,
+      criteria: [],
+      matched: [],
+      frictionDropped: 0,
+      skippedEffects: [],
+    };
+  }
+
+  return attempt.state === 'closing' || attempt.state === 'succeeded' || attempt.state === 'failed'
+    ? null
+    : { kind: 'item-closed' };
+}

package/src/attempts/is-same-guard.ts

@@ -0,0 +1,22 @@
+import type { AttemptRow } from '@boxxy/model';
+
+// The columns the machine's guards read.
+const attemptGuardColumns = [
+  'state',
+  'holdGen',
+  'suspendRequestedAt',
+  'wakeRequestedAt',
+  'closing',
+  'atcSession',
+  'strayedAt',
+  'sessionStoppedAt',
+  'sessionForgottenAt',
+] as const satisfies readonly (keyof AttemptRow)[];
+
+export type AttemptGuard = Pick<AttemptRow, (typeof attemptGuardColumns)[number]>;
+
+// True when the row agrees with each guard column the caller decided on. A caller that passes a
+// whole row checks every column; a caller that passes some columns checks only those.
+export function isSameGuard(seen: Partial<AttemptGuard>, row: AttemptRow): boolean {
+  return attemptGuardColumns.every((column) => !(column in seen) || seen[column] === row[column]);
+}

package/src/attempts/pick-call-attempt.ts

@@ -0,0 +1,32 @@
+import type { AttemptRow, CallerIdentity } from '@boxxy/model';
+import type { CallRef } from '../closeouts/types.ts';
+
+export type CallAttempt =
+  | { readonly kind: 'attempt'; readonly attempt: AttemptRow }
+  | { readonly kind: 'refused'; readonly reason: 'no-attempt' | 'not-current' };
+
+// The one check of every call from inside a session. `latest` is the latest attempt of the
+// calling session, read inside the caller's lock. The call reaches the attempt it names only
+// when that one is `latest` and holds the proven caller. Pure.
+export function pickCallAttempt(latest: AttemptRow | null, call: CallRef): CallAttempt {
+  if (latest === null) {
+    return { kind: 'refused', reason: 'no-attempt' };
+  }
+
+  if (latest.id !== call.attempt) {
+    return { kind: 'refused', reason: 'not-current' };
+  }
+
+  // a row with no caller, or another caller, is refused; an older row of the session never counts
+  if (!isSameCaller(latest.caller, call.caller)) {
+    return { kind: 'refused', reason: 'no-attempt' };
+  }
+
+  return { kind: 'attempt', attempt: latest };
+}
+
+function isSameCaller(recorded: CallerIdentity | null, proven: CallerIdentity): boolean {
+  return (
+    recorded !== null && recorded.issuer === proven.issuer && recorded.subject === proven.subject
+  );
+}

package/src/attempts/stop-stray-session.ts

@@ -0,0 +1,48 @@
+import type {
+  ActorRef,
+  AttemptRow,
+  ClaimStore,
+  Instant,
+  NewId,
+  StopOutcome,
+  WorkerKind,
+} from '@boxxy/model';
+import type { MoveResult } from './types.ts';
+import { writeAttemptMove } from './write-attempt-move.ts';
+
+export interface StopStraySessionInput {
+  readonly store: ClaimStore;
+  readonly worker: WorkerKind;
+
+  // an attempt that the give-up rule settled while its session still ran
+  readonly attempt: AttemptRow;
+  readonly actor: ActorRef;
+  readonly now: Instant;
+  readonly newId: NewId;
+}
+
+// Sends the stop again, and records `stray-stopped` once the session is gone. The runner calls
+// it on every tick for each stray, so a stop that fails is tried again on the next tick. null:
+// the session still runs, or it never appeared.
+export async function stopStraySession(input: StopStraySessionInput): Promise<MoveResult | null> {
+  const outcome = await input.worker.stop(input.attempt);
+
+  if (!isSessionGone(input.attempt, outcome)) {
+    return null;
+  }
+
+  return input.store.exclusive((tx) =>
+    writeAttemptMove(
+      tx,
+      input.attempt.id,
+      { kind: 'stray-stopped' },
+      { actor: input.actor, now: input.now, newId: input.newId },
+    ),
+  );
+}
+
+// An attempt with no session is looked for by its spawn name, so `absent` there means the session
+// has not appeared yet, and the loop keeps sending the stop.
+function isSessionGone(attempt: AttemptRow, outcome: StopOutcome): boolean {
+  return outcome.kind === 'stopped' || (outcome.kind === 'absent' && attempt.atcSession !== null);
+}

package/src/attempts/types.ts

@@ -0,0 +1,231 @@
+import type {
+  ActorRef,
+  AgentSessionId,
+  AtcSessionId,
+  AttemptId,
+  AttemptRow,
+  AttemptSessionRow,
+  AttemptState,
+  CallerIdentity,
+  CloseOut,
+  ClosingCause,
+  CommitSha,
+  DecisionRow,
+  FactId,
+  FactType,
+  Instant,
+  Minutes,
+  NewId,
+  ResolvedRecipe,
+  RunnerId,
+  SessionMode,
+  StartPick,
+  WakePick,
+  WakeSource,
+  WorkFacts,
+} from '@boxxy/model';
+
+// What the guards of the attempt machine read. Each field comes from one column of the attempt
+// row.
+export interface AttemptContext {
+  // `suspendRequestedAt` is set
+  readonly mark: boolean;
+
+  // `wakeRequestedAt` is set
+  readonly wakeRequested: boolean;
+  readonly mode: SessionMode;
+  readonly holdGen: number;
+  readonly closing: ClosingCause | null;
+
+  // `atcSession` is set
+  readonly hasSession: boolean;
+
+  // `strayedAt` is set
+  readonly strayed: boolean;
+
+  // `sessionStoppedAt` is set
+  readonly sessionStopped: boolean;
+
+  // `sessionForgottenAt` is set
+  readonly sessionForgotten: boolean;
+}
+
+// The machine's events. XState names the kind `type`; `claimed` is the initial transition and
+// has no event.
+export type AttemptMachineEvent =
+  | { readonly type: 'started'; readonly via: 'start' | 'reconcile' }
+  | { readonly type: 'woken'; readonly overCap: boolean }
+  | {
+      readonly type: 'settled';
+      readonly state: 'succeeded' | 'failed';
+      readonly sessionStopped: boolean;
+    }
+  | {
+      readonly type:
+        | 'spawn-unanswered'
+        | 'session-seen'
+        | 'closed-out'
+        | 'timed-out'
+        | 'item-closed'
+        | 'turn-ended'
+        | 'stalled'
+        | 'skill-missing'
+        | 'usage-limited'
+        | 'suspend-asked'
+        | 'suspend-refused'
+        | 'slept'
+        | 'wake-requested'
+        | 'resumed'
+        | 'wake-refused'
+        | 'stray-stopped'
+        | 'session-forgotten';
+    };
+
+// A write that a move makes besides the attempt row, or a fact it records.
+export type MoveEffect =
+  | 'take-lease'
+  | 'release-lease'
+  | 'take-seats'
+  | 'release-seats'
+  | 'record-decision'
+  | 'bind-session'
+  | FactType;
+
+// One row of the table of moves.
+export interface AttemptMove {
+  readonly event: AttemptMachineEvent['type'] | 'claimed';
+
+  // empty for `claimed`, which starts from no attempt
+  readonly from: readonly AttemptState[];
+
+  // the move is allowed only when this holds; no `when` allows it from every `from` state
+  readonly when?: (context: AttemptContext, event: AttemptMachineEvent) => boolean;
+  readonly to: AttemptState | 'same';
+  readonly effects: readonly MoveEffect[];
+  readonly context?: (
+    context: AttemptContext,
+    event: AttemptMachineEvent,
+  ) => Partial<AttemptContext>;
+}
+
+// What the claim, a wake and the decision fact record; the builder adds the ID, the attempt and
+// the time.
+export type DecisionDraft = Omit<DecisionRow, 'id' | 'attempt' | 'at'>;
+
+export interface ClaimedEvent {
+  readonly kind: 'claimed';
+
+  // made before the change, because the spawn request names it
+  readonly attempt: AttemptId;
+  readonly pick: StartPick;
+  readonly number: number;
+  readonly runner: RunnerId;
+
+  // one above the item phase's last lease generation
+  readonly leaseGen: number;
+  readonly recipe: Pick<ResolvedRecipe, 'hash' | 'rulesVersion'>;
+  readonly skillsRef: CommitSha | null;
+  readonly spawnRequest: AttemptRow['spawnRequest'];
+  readonly spawnRequestHash: AttemptRow['spawnRequestHash'];
+  readonly input: AttemptRow['input'];
+  readonly mode: SessionMode;
+
+  // a claim through a resume edge copies the kept session's caller
+  readonly caller: CallerIdentity | null;
+  readonly decision: DecisionDraft;
+}
+
+type SettledFact = WorkFacts['boxxy.attempt.settled'];
+
+export type MoveEvent =
+  | {
+      readonly kind: 'started';
+      readonly via: 'start' | 'reconcile';
+      readonly atcSession: AtcSessionId;
+      readonly caller: CallerIdentity | null;
+      readonly resumeFallback: boolean;
+    }
+  | { readonly kind: 'spawn-unanswered'; readonly reason: string }
+  | { readonly kind: 'session-seen'; readonly row: AttemptSessionRow }
+  | {
+      readonly kind: 'closed-out';
+      readonly closeOut: CloseOut;
+      readonly hash: NonNullable<AttemptRow['closeOutHash']>;
+    }
+  | { readonly kind: 'timed-out'; readonly afterMinutes: Minutes }
+  | { readonly kind: 'item-closed' }
+  | { readonly kind: 'turn-ended' }
+  | { readonly kind: 'stalled' }
+  | { readonly kind: 'skill-missing' }
+  | { readonly kind: 'usage-limited' }
+  | { readonly kind: 'suspend-asked' }
+  | { readonly kind: 'suspend-refused' }
+  | { readonly kind: 'slept'; readonly idleSince: Instant; readonly asked: boolean }
+  | { readonly kind: 'wake-requested'; readonly by: WakeSource }
+  | {
+      readonly kind: 'woken';
+      readonly pick: WakePick;
+      readonly decision: DecisionDraft;
+      readonly overCap: boolean;
+    }
+  | {
+      readonly kind: 'resumed';
+      readonly atcSession: AtcSessionId;
+      readonly caller: CallerIdentity | null;
+    }
+  | { readonly kind: 'wake-refused' }
+  | (Pick<
+      SettledFact,
+      | 'state'
+      | 'failure'
+      | 'returnedOutcome'
+      | 'sessionStopped'
+      | 'criteria'
+      | 'matched'
+      | 'frictionDropped'
+      | 'skippedEffects'
+    > & {
+      readonly kind: 'settled';
+      readonly outcome: NonNullable<AttemptRow['outcome']>;
+    })
+  | { readonly kind: 'stray-stopped' }
+  | { readonly kind: 'session-forgotten' };
+
+export type AttemptEvent = ClaimedEvent | MoveEvent;
+
+// The rows one move reads and writes: the attempt as read, the attempt as the move leaves it,
+// and the decision row of a claim or a wake.
+export interface MoveParts {
+  readonly before: AttemptRow;
+  readonly after: AttemptRow;
+  readonly event: AttemptEvent;
+  readonly decision: DecisionRow | null;
+}
+
+// What every move of a caller outside the builder passes on.
+export interface MoveBase {
+  readonly actor: ActorRef;
+  readonly now: Instant;
+  readonly newId: NewId;
+}
+
+export type MoveResult =
+  | { readonly kind: 'applied' }
+  | { readonly kind: 'not-allowed' }
+
+  // the store refused the change: a race the next tick reads again
+  | { readonly kind: 'refused'; readonly reason: string };
+
+export interface SeenSession {
+  readonly atcSession: AtcSessionId;
+  readonly agentSession: AgentSessionId;
+
+  // the attempt whose kept session this one resumed; it holds the same agent session
+  readonly keptFrom?: AttemptId | null;
+}
+
+export interface FactEnvelopeParts {
+  readonly id: FactId;
+  readonly actor: ActorRef;
+  readonly now: Instant;
+}

package/src/attempts/write-attempt-move.ts

@@ -0,0 +1,41 @@
+import type { AttemptId, RowWrite, StoreTx } from '@boxxy/model';
+import { buildAttemptChange } from './build-attempt-change.ts';
+import type { AttemptGuard } from './is-same-guard.ts';
+import { isSameGuard } from './is-same-guard.ts';
+import type { MoveBase, MoveEvent, MoveResult } from './types.ts';
+
+// Applies one move of the attempt as the store holds it inside `tx`, built from the row it
+// changes. `also` rides in the same change. A row that moved on from `seen`, the row a caller
+// decided on before the lock, refuses the move.
+export async function writeAttemptMove(
+  tx: StoreTx,
+  attempt: AttemptId,
+  event: MoveEvent,
+  base: MoveBase & {
+    readonly also?: readonly RowWrite[];
+    readonly seen?: Partial<AttemptGuard>;
+  },
+): Promise<MoveResult> {
+  const row = await tx.readAttempt(attempt);
+
+  if (row === null) {
+    return { kind: 'not-allowed' };
+  }
+
+  if (base.seen !== undefined && !isSameGuard(base.seen, row)) {
+    return { kind: 'refused', reason: 'guard-mismatch' };
+  }
+
+  const built = buildAttemptChange({ ...base, attempt: row, event });
+
+  if (built.kind === 'not-allowed') {
+    return { kind: 'not-allowed' };
+  }
+
+  const result = await tx.applyChange({
+    ...built.change,
+    writes: [...built.change.writes, ...(base.also ?? [])],
+  });
+
+  return result.kind === 'applied' ? result : { kind: 'refused', reason: result.kind };
+}

package/src/attempts/write-session-bind.ts

@@ -0,0 +1,47 @@
+import type { AttemptRow, SessionFault, StoreTx } from '@boxxy/model';
+import type { MoveBase, SeenSession } from './types.ts';
+import { writeAttemptMove } from './write-attempt-move.ts';
+
+// Binds the agent session to the attempt, once. An agent session that another attempt holds
+// writes nothing and gives the fault, which the server logs.
+export async function writeSessionBind(
+  tx: StoreTx,
+  attempt: AttemptRow,
+  session: SeenSession,
+  base: MoveBase,
+): Promise<SessionFault | null> {
+  const holder = await tx.findAttemptByAgentSession(session.agentSession);
+
+  if (holder === attempt.id) {
+    return null;
+  }
+
+  if (holder !== null && holder !== session.keptFrom) {
+    return {
+      kind: 'fault',
+      fault: 'agent-session-owned',
+      agentSession: session.agentSession,
+      attempt: attempt.id,
+      holder,
+    };
+  }
+
+  await writeAttemptMove(
+    tx,
+    attempt.id,
+    {
+      kind: 'session-seen',
+      row: {
+        attempt: attempt.id,
+        agentSession: session.agentSession,
+        atcSession: session.atcSession,
+        product: 'claude_code',
+        source: 'worker',
+        seenAt: base.now,
+      },
+    },
+    base,
+  );
+
+  return null;
+}

package/src/claims/build-snapshot-hash.ts

@@ -0,0 +1,9 @@
+import { contentHash } from '@boxxy/content-hash';
+import type { PoolName, Snapshot, SnapshotHash } from '@boxxy/model';
+import { brandSchemas, toJSONValue } from '@boxxy/model';
+
+// The hash covers the pools in backoff too: they decide the picks as much as the rows do, and
+// the runner keeps them in memory only.
+export function buildSnapshotHash(snapshot: Snapshot, backoff: readonly PoolName[]): SnapshotHash {
+  return brandSchemas.snapshotHash.parse(contentHash(toJSONValue({ snapshot, backoff })));
+}