@boxxy/dispatch 0.1.0 → 0.1.3

package/dist/test-utils/worker-contract.d.ts

@@ -0,0 +1,14 @@
+import type { AttemptId, SpawnRequest, WorkerKind } from '@boxxy/model';
+export interface WorkerHarness {
+    readonly worker: WorkerKind;
+    buildSpawnRequest: (attempt: AttemptId) => SpawnRequest;
+}
+export interface WorkerContractOutcome {
+    readonly received: unknown;
+    readonly expected: unknown;
+}
+export type WorkerContractCase = readonly [
+    title: string,
+    check: (harness: WorkerHarness) => Promise<WorkerContractOutcome>
+];
+export declare const workerContract: readonly WorkerContractCase[];

package/dist/timeouts.d.ts

@@ -0,0 +1,2 @@
+import type { DispatchTimeouts } from './types.ts';
+export declare const timeouts: DispatchTimeouts;

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+export interface DispatchTimeouts {
+    readonly spawnLostMinutes: number;
+    readonly resumeLostMinutes: number;
+    readonly closingGiveUpMinutes: number;
+    readonly stopGraceSeconds: number;
+    readonly seatlessSeconds: number;
+    readonly capacityBackoffSeconds: number;
+    readonly stallMinutes: number;
+    readonly keptSessionHours: number;
+    readonly failedSessionHours: number;
+    readonly usageLimitBackoffHours: number;
+    readonly strayHours: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/dispatch",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "boxxy's dispatch: claims the next task for an agent",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/modules/dispatch#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -20,7 +20,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -29,6 +30,18 @@
     "build": "rm -rf dist && tsrs -p tsconfig.build.json",
     "typecheck": "tsrs --noEmit"
   },
+  "dependencies": {
+    "@boxxy/closeout": "0.1.3",
+    "@boxxy/content-hash": "0.1.3",
+    "@boxxy/model": "0.1.3",
+    "@boxxy/planning": "0.1.3",
+    "tiny-invariant": "1.3.3",
+    "ts-pattern": "5.9.2",
+    "xstate": "6.0.0-beta.2"
+  },
+  "devDependencies": {
+    "@boxxy/rules": "0.1.3"
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"

package/src/attempts/attempt-machine.ts

@@ -0,0 +1,147 @@
+import type { AttemptState, SessionMode } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { createMachine, types } from 'xstate';
+import { attemptMoves } from './attempt-moves.ts';
+import type { AttemptContext, AttemptMachineEvent, AttemptMove, MoveEffect } from './types.ts';
+
+// The attempt states as an XState machine, built from the table of moves. Callers run it only
+// through the pure `transition` and `initialTransition`, and read each move's writes from the
+// `effect` events it emits.
+export const attemptMachine = createMachine({
+  schemas: {
+    context: types<AttemptContext>(),
+    input: types<{ mode: SessionMode }>(),
+    events: {
+      started: types<{ via: 'start' | 'reconcile' }>(),
+      'spawn-unanswered': types<void>(),
+      'session-seen': types<void>(),
+      'closed-out': types<void>(),
+      'timed-out': types<void>(),
+      'item-closed': types<void>(),
+      'turn-ended': types<void>(),
+      stalled: types<void>(),
+      'skill-missing': types<void>(),
+      'usage-limited': types<void>(),
+      'suspend-asked': types<void>(),
+      'suspend-refused': types<void>(),
+      slept: types<void>(),
+      'wake-requested': types<void>(),
+      woken: types<{ overCap: boolean }>(),
+      resumed: types<void>(),
+      'wake-refused': types<void>(),
+      settled: types<{ state: 'succeeded' | 'failed'; sessionStopped: boolean }>(),
+      'stray-stopped': types<void>(),
+      'session-forgotten': types<void>(),
+    },
+    emitted: { effect: types<{ effect: MoveEffect }>() },
+  },
+  context: (args) => ({
+    mark: false,
+    wakeRequested: false,
+    mode: args.input.mode,
+    holdGen: 1,
+    closing: null,
+    hasSession: false,
+    strayed: false,
+    sessionStopped: false,
+    sessionForgotten: false,
+  }),
+  entry: (_args, enq) => {
+    for (const effect of getClaimedMove().effects) {
+      enq.emit({ type: 'effect', effect });
+    }
+  },
+  initial: 'starting',
+  states: {
+    starting: { on: buildStateHandlers('starting') },
+    reconciling: { on: buildStateHandlers('reconciling') },
+    running: { on: buildStateHandlers('running') },
+    sleeping: { on: buildStateHandlers('sleeping') },
+    waking: { on: buildStateHandlers('waking') },
+    closing: { on: buildStateHandlers('closing') },
+
+    // plain states, not final: a final state drops `session-seen` and `stray-stopped`
+    succeeded: { on: buildStateHandlers('succeeded') },
+    failed: { on: buildStateHandlers('failed') },
+  },
+});
+
+function getClaimedMove(): AttemptMove {
+  const claimed = attemptMoves.find((move) => move.event === 'claimed');
+
+  invariant(claimed !== undefined, 'the table of moves has a claimed row');
+
+  return claimed;
+}
+
+interface MoveArgs {
+  readonly context: AttemptContext;
+  readonly event: AttemptMachineEvent;
+}
+
+interface EffectEvent {
+  type: 'effect';
+  effect: MoveEffect;
+}
+
+interface MoveEnqueue {
+  readonly emit: (event: EffectEvent) => void;
+}
+
+interface MoveTarget {
+  target?: AttemptState;
+  context?: Partial<AttemptContext>;
+}
+
+type MoveHandler = (args: MoveArgs, enq: MoveEnqueue) => MoveTarget | undefined;
+
+// Every state lists every event, and a handler with no matching row leaves its event unhandled.
+// The type check of `createMachine` refuses an `on` object whose keys are optional.
+function buildStateHandlers(state: AttemptState): Record<AttemptMachineEvent['type'], MoveHandler> {
+  const build = (event: AttemptMachineEvent['type']): MoveHandler =>
+    buildMoveHandler(
+      attemptMoves.filter((move) => move.event === event && move.from.includes(state)),
+    );
+
+  return {
+    started: build('started'),
+    'spawn-unanswered': build('spawn-unanswered'),
+    'session-seen': build('session-seen'),
+    'closed-out': build('closed-out'),
+    'timed-out': build('timed-out'),
+    'item-closed': build('item-closed'),
+    'turn-ended': build('turn-ended'),
+    stalled: build('stalled'),
+    'skill-missing': build('skill-missing'),
+    'usage-limited': build('usage-limited'),
+    'suspend-asked': build('suspend-asked'),
+    'suspend-refused': build('suspend-refused'),
+    slept: build('slept'),
+    'wake-requested': build('wake-requested'),
+    woken: build('woken'),
+    resumed: build('resumed'),
+    'wake-refused': build('wake-refused'),
+    settled: build('settled'),
+    'stray-stopped': build('stray-stopped'),
+    'session-forgotten': build('session-forgotten'),
+  };
+}
+
+function buildMoveHandler(moves: readonly AttemptMove[]): MoveHandler {
+  return (args, enq) => {
+    const move = moves.find((candidate) => candidate.when?.(args.context, args.event) ?? true);
+
+    // XState counts any queued effect as a taken move, so the guard runs before the effects
+    return move === undefined ? undefined : takeMove(move, args, enq);
+  };
+}
+
+function takeMove(move: AttemptMove, args: MoveArgs, enq: MoveEnqueue): MoveTarget {
+  for (const effect of move.effects) {
+    enq.emit({ type: 'effect', effect });
+  }
+
+  const patch = move.context?.(args.context, args.event) ?? {};
+
+  return move.to === 'same' ? { context: patch } : { target: move.to, context: patch };
+}

package/src/attempts/attempt-moves.ts

@@ -0,0 +1,218 @@
+import type { AttemptState } from '@boxxy/model';
+import type { AttemptMove } from './types.ts';
+
+const liveStates: readonly AttemptState[] = [
+  'starting',
+  'reconciling',
+  'running',
+  'sleeping',
+  'waking',
+  'closing',
+];
+
+// The table of section A of the core flow sketch. The attempt machine is built from it, and the
+// first row whose `from` and `when` match an event is the move.
+export const attemptMoves: readonly AttemptMove[] = [
+  {
+    event: 'claimed',
+    from: [],
+    to: 'starting',
+    effects: [
+      'take-lease',
+      'take-seats',
+      'record-decision',
+      'boxxy.attempt.claimed',
+      'boxxy.decision.recorded',
+    ],
+  },
+  {
+    event: 'started',
+    from: ['starting', 'reconciling'],
+    when: (_context, event) => event.type === 'started' && event.via === 'start',
+    to: 'running',
+    effects: ['boxxy.attempt.started'],
+    context: () => ({ hasSession: true }),
+  },
+  {
+    event: 'started',
+    from: ['starting', 'reconciling'],
+    when: (_context, event) => event.type === 'started' && event.via === 'reconcile',
+    to: 'running',
+    effects: ['boxxy.attempt.reconciled'],
+    context: () => ({ hasSession: true }),
+  },
+  {
+    event: 'started',
+    from: ['closing'],
+    when: (context) => context.closing === 'item-closed' && !context.hasSession,
+    to: 'same',
+    effects: ['boxxy.attempt.started'],
+    context: () => ({ hasSession: true }),
+  },
+  {
+    event: 'spawn-unanswered',
+    from: ['starting'],
+    to: 'reconciling',
+    effects: ['boxxy.attempt.spawn_unanswered'],
+  },
+  {
+    event: 'session-seen',
+    from: [...liveStates, 'succeeded', 'failed'],
+    to: 'same',
+    effects: ['bind-session', 'boxxy.attempt.session_bound'],
+  },
+  {
+    event: 'closed-out',
+    from: ['starting', 'reconciling', 'running', 'sleeping', 'waking'],
+    to: 'closing',
+    effects: ['boxxy.attempt.closed_out'],
+    context: () => ({ closing: 'closed-out', mark: false, wakeRequested: false }),
+  },
+  {
+    event: 'timed-out',
+    from: ['running'],
+    when: (context) => context.mode === 'agent',
+    to: 'closing',
+    effects: ['boxxy.attempt.timed_out'],
+    context: () => ({ closing: 'timed-out' }),
+  },
+  {
+    // the close of the item writes `boxxy.item.closed` for each attempt it ends
+    event: 'item-closed',
+    from: ['starting', 'reconciling', 'running', 'waking'],
+    to: 'closing',
+    effects: [],
+    context: () => ({ closing: 'item-closed', mark: false, wakeRequested: false }),
+  },
+  {
+    event: 'turn-ended',
+    from: ['running'],
+    when: (context) => context.mode === 'agent',
+    to: 'closing',
+    effects: ['boxxy.attempt.turn_ended'],
+    context: () => ({ closing: 'turn-ended' }),
+  },
+  {
+    // `boxxy.attempt.settled` carries the cause
+    event: 'stalled',
+    from: ['running'],
+    when: (context) => context.mode === 'agent',
+    to: 'closing',
+    effects: [],
+    context: () => ({ closing: 'stalled' }),
+  },
+  {
+    // `boxxy.attempt.settled` carries the cause
+    event: 'skill-missing',
+    from: ['starting', 'reconciling', 'running'],
+    to: 'closing',
+    effects: [],
+    context: () => ({ closing: 'skill-missing' }),
+  },
+  {
+    // `boxxy.attempt.settled` carries the cause
+    event: 'usage-limited',
+    from: ['running'],
+    to: 'closing',
+    effects: [],
+    context: () => ({ closing: 'usage-limit' }),
+  },
+  {
+    event: 'suspend-asked',
+    from: ['running'],
+    when: (context) => !context.mark,
+    to: 'same',
+    effects: [],
+    context: () => ({ mark: true }),
+  },
+  {
+    event: 'suspend-refused',
+    from: ['running'],
+    when: (context) => context.mark,
+    to: 'same',
+    effects: [],
+    context: () => ({ mark: false, wakeRequested: false }),
+  },
+  {
+    event: 'slept',
+    from: ['starting', 'reconciling', 'running'],
+    to: 'sleeping',
+    effects: ['release-seats', 'boxxy.attempt.slept'],
+    context: () => ({ mark: false }),
+  },
+  {
+    event: 'wake-requested',
+    from: ['sleeping'],
+    when: (context) => !context.wakeRequested,
+    to: 'same',
+    effects: ['boxxy.attempt.wake_requested'],
+    context: () => ({ wakeRequested: true }),
+  },
+  {
+    event: 'wake-requested',
+    from: ['running'],
+    when: (context) => context.mark,
+    to: 'same',
+    effects: ['boxxy.attempt.wake_requested'],
+    context: () => ({ wakeRequested: true }),
+  },
+  {
+    event: 'woken',
+    from: ['sleeping'],
+    to: 'waking',
+    effects: ['take-seats', 'record-decision', 'boxxy.attempt.woken', 'boxxy.decision.recorded'],
+    context: (context) => ({ holdGen: context.holdGen + 1 }),
+  },
+  {
+    // the wake is done, so a later sleep starts with no request
+    event: 'resumed',
+    from: ['waking'],
+    to: 'running',
+    effects: ['boxxy.attempt.resumed'],
+    context: () => ({ wakeRequested: false }),
+  },
+  {
+    // the request stays, so a later claim tries the wake again
+    event: 'wake-refused',
+    from: ['waking'],
+    to: 'sleeping',
+    effects: ['release-seats', 'boxxy.attempt.slept'],
+  },
+  {
+    event: 'settled',
+    from: liveStates,
+    when: (_context, event) => event.type === 'settled' && event.state === 'succeeded',
+    to: 'succeeded',
+    effects: ['release-seats', 'release-lease', 'boxxy.attempt.settled'],
+    context: (_context, event) => ({
+      strayed: event.type === 'settled' && !event.sessionStopped,
+    }),
+  },
+  {
+    event: 'settled',
+    from: liveStates,
+    when: (_context, event) => event.type === 'settled' && event.state === 'failed',
+    to: 'failed',
+    effects: ['release-seats', 'release-lease', 'boxxy.attempt.settled'],
+    context: (_context, event) => ({
+      strayed: event.type === 'settled' && !event.sessionStopped,
+    }),
+  },
+  {
+    event: 'stray-stopped',
+    from: ['succeeded', 'failed'],
+    when: (context) => context.strayed && !context.sessionStopped,
+    to: 'same',
+    effects: [],
+    context: () => ({ sessionStopped: true }),
+  },
+  {
+    // a stray session is forgotten only after it has stopped
+    event: 'session-forgotten',
+    from: ['succeeded', 'failed'],
+    when: (context) => !context.sessionForgotten && (!context.strayed || context.sessionStopped),
+    to: 'same',
+    effects: [],
+    context: () => ({ sessionForgotten: true }),
+  },
+];

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

@@ -0,0 +1,61 @@
+import type {
+  AgentSessionId,
+  ClaimStore,
+  Instant,
+  NewId,
+  SessionFault,
+  StoreTx,
+} from '@boxxy/model';
+import type { CallRef } from '../closeouts/types.ts';
+import { pickCallAttempt } from './pick-call-attempt.ts';
+import { writeAttemptMove } from './write-attempt-move.ts';
+import { writeSessionBind } from './write-session-bind.ts';
+
+export interface BindAttemptSessionInput {
+  readonly store: ClaimStore;
+  readonly call: CallRef;
+  readonly agentSession: AgentSessionId;
+
+  // each skill the recipe lists that the session-start hook did not find after its fetch
+  readonly missingSkills: readonly string[];
+  readonly now: Instant;
+  readonly newId: NewId;
+}
+
+export type BindAnswer =
+  | { readonly kind: 'bound' | 'no-attempt' | 'not-current' | 'skill-missing' }
+  | SessionFault;
+
+// The session-start hook's call. It reaches only the attempt that `pickCallAttempt` gives. A
+// missing skill moves the attempt to `closing`, and the runner settles it as `skill-missing`.
+export function bindAttemptSession(input: BindAttemptSessionInput): Promise<BindAnswer> {
+  return input.store.exclusive((tx) => writeBind(tx, input));
+}
+
+async function writeBind(tx: StoreTx, input: BindAttemptSessionInput): Promise<BindAnswer> {
+  const latest = await tx.findAttemptBySession(input.call.session);
+
+  const picked = pickCallAttempt(latest, input.call);
+
+  if (picked.kind === 'refused') {
+    return { kind: picked.reason };
+  }
+
+  const attempt = picked.attempt;
+  const base = { actor: `boxxy:hook:${attempt.id}`, now: input.now, newId: input.newId } as const;
+
+  if (input.missingSkills.length > 0) {
+    await writeAttemptMove(tx, attempt.id, { kind: 'skill-missing' }, base);
+
+    return { kind: 'skill-missing' };
+  }
+
+  const fault = await writeSessionBind(
+    tx,
+    attempt,
+    { atcSession: input.call.session, agentSession: input.agentSession },
+    base,
+  );
+
+  return fault ?? { kind: 'bound' };
+}