@coreplane/switchboard 0.0.0 → 1.18.0

package/dist/assets/src/core/runLedger/decisions.ts

@@ -0,0 +1,126 @@
+// The ledger's decisions (docs/reference/specs/run-history.md items 28–31), pure. The
+// Durable Object applies them inside one transaction; the in-memory ledger
+// applies them in tests; both agree because this is the only copy.
+
+import type { ClaimResult, FenceResult, LivePhase } from "./types.js";
+
+/** One live run per thread. The existing row, if any, is what `live_runs` holds
+ *  for the thread; the same run re-claimed by its owner is idempotent (a retry
+ *  after a lost response), anything else is refused with what the steer
+ *  message needs. */
+export function decideClaim(
+  existing: { runId: string; agent?: string; startedAt: number; ownerGen: string } | undefined,
+  req: { runId: string; gen: string },
+): ClaimResult {
+  if (!existing) return { ok: true };
+  if (existing.runId === req.runId && existing.ownerGen === req.gen) return { ok: true };
+  return {
+    ok: false,
+    reason: "thread-live",
+    live: {
+      runId: existing.runId,
+      ...(existing.agent !== undefined ? { agent: existing.agent } : {}),
+      startedAt: existing.startedAt,
+    },
+  };
+}
+
+/** What an accepted claim does to the thread's row (item 42). `insert`: no row.
+ *  `promote`: the owner's claim WITH a prompt on its own `attaching` row — the
+ *  prompt, tools, card and state land and the phase goes `live`, identity and
+ *  start untouched. `refresh`: the owner re-reserves (a retry after a lost
+ *  response) — the lease only. `keep`: any owner re-claim on a row past
+ *  attaching — idempotent, nothing written (as it always was). Decided only
+ *  after `decideClaim` accepted. */
+export type ClaimWrite = "insert" | "promote" | "refresh" | "keep";
+export function decideClaimWrite(
+  existing: { runId: string; ownerGen: string; phase: LivePhase } | undefined,
+  req: { runId: string; gen: string; phase?: "attaching" | "live" },
+): ClaimWrite {
+  if (!existing) return "insert";
+  if (existing.phase !== "attaching") return "keep";
+  return (req.phase ?? "live") === "attaching" ? "refresh" : "promote";
+}
+
+/** The phase a reclaimed row lands in: an `attaching` row stays so — the
+ *  launcher restarts it from its request rather than resuming a transcript it
+ *  does not have; every other row becomes `live` under the new owner. */
+export function reclaimPhase(from: LivePhase): LivePhase {
+  return from === "attaching" ? "attaching" : "live";
+}
+
+/** The fencing token: only the generation that holds the lease may write. */
+export function checkFence(row: { ownerGen: string } | undefined, gen: string): FenceResult {
+  if (!row) return { ok: false, reason: "unknown-run" };
+  return row.ownerGen === gen ? { ok: true } : { ok: false, reason: "fenced" };
+}
+
+/** What a reclaiming generation takes over: every run whose lease has expired
+ *  (a heartbeat lands strictly before `leaseUntil`, so equal is expired) and
+ *  every run the previous generation handed off — **never a row it owns
+ *  itself**. The reclaim runs on a sweep inside the live process too, and a
+ *  lapsed lease on our own row means a heartbeat that could not land (a state
+ *  Worker blip), not a dead owner: taking it would launch the run a second
+ *  time in the same process, and the fence, which compares generations, would
+ *  never stop the first. */
+export function selectReclaim<T extends { leaseUntil: number; phase: LivePhase; ownerGen: string }>(
+  rows: readonly T[],
+  now: number,
+  gen: string,
+): T[] {
+  return rows.filter((r) => r.ownerGen !== gen && (r.phase === "handoff" || r.leaseUntil <= now));
+}
+
+/** The compare-and-swap table for a run's phase. `attaching → live` (the
+ *  prompt landed) or `→ finishing` (the dispatch failed before it — never
+ *  handoff: an attaching run has nothing to resume from, so the drain waits
+ *  for it and a dead owner's row is restarted instead), `live → handoff`
+ *  (SIGTERM), `live → finishing` (before the reply), `handoff → finishing`
+ *  (the owner finished inside its own handoff window, before any reclaim —
+ *  the fence on the generation still keeps a reclaimed row from it), and back
+ *  to `live` from `handoff` or `finishing` by a reclaim. Nothing else. */
+export function phaseTransition(from: LivePhase, to: LivePhase): boolean {
+  switch (from) {
+    case "attaching":
+      return to === "live" || to === "finishing";
+    case "live":
+      return to === "handoff" || to === "finishing";
+    case "handoff":
+      return to === "live" || to === "finishing";
+    case "finishing":
+      return to === "live";
+    default:
+      return false;
+  }
+}
+
+export type Completeness = { kind: "resume" } | { kind: "run-step-fresh" } | { kind: "interrupted"; why: string };
+
+/** What a resume does with the rows it finds. A step write lands the step's
+ *  turns first (the previous results turn and this assistant turn: two turns),
+ *  then the step record with `turnIndex` = the transcript's turn count. So:
+ *  the count matches the last record → resume there; two more → the next
+ *  step's turns landed but its record did not, nothing was dispatched, run
+ *  that step's tools fresh; anything else is a partial write. With no record
+ *  yet, the seed plays the role of the last record. */
+export function transcriptCompleteness(input: {
+  lastStep: { turnIndex: number } | null;
+  seedTurns: number;
+  transcriptTurns: number;
+}): Completeness {
+  const { lastStep, seedTurns, transcriptTurns } = input;
+  if (transcriptTurns === 0) return { kind: "interrupted", why: "no transcript stored" };
+  const base = lastStep ? lastStep.turnIndex : seedTurns;
+  if (transcriptTurns === base) return { kind: "resume" };
+  if (transcriptTurns === base + 2) return { kind: "run-step-fresh" };
+  if (transcriptTurns < base) {
+    return {
+      kind: "interrupted",
+      why: `transcript has ${transcriptTurns} turns but the last step recorded ${base}`,
+    };
+  }
+  return {
+    kind: "interrupted",
+    why: `transcript has ${transcriptTurns} turns, one past the last step's ${base}: a partial step write`,
+  };
+}

package/dist/assets/src/core/runLedger/types.ts

@@ -0,0 +1,177 @@
+// The run ledger's contract (docs/decisions/0019-durable-run-ledger-resume-after-kill.md;
+// docs/reference/specs/run-history.md items 28–34): what a live run leaves on the state
+// Worker so the next bot generation can resume it. Node-free — imported by the
+// bot and by `deploy/cloudflare-memory/worker.ts` alike, the way runRecord.ts is.
+
+import type { ChatMessage, ToolDef } from "../../providers/types.js";
+import type { ChannelVisibility } from "../authz/types.js";
+import type { RunEvent } from "../runEvents.js";
+
+/** How long a generation's claim on a run lasts without a heartbeat. */
+export const LEASE_MS = 30_000;
+/** How often the owning generation renews the lease. */
+export const HEARTBEAT_MS = 10_000;
+/** The append flusher's batch window and size. */
+export const APPEND_FLUSH_MS = 500;
+export const APPEND_FLUSH_EVENTS = 32;
+/** Request-body ceiling for a transcript write (the Worker's `/runs/put` fence). */
+export const TRANSCRIPT_REQUEST_BYTES = 2 * 1024 * 1024;
+/** One content part per row; a row must stay under the Durable Object's 2 MB
+ *  row limit with headroom for the JSON envelope. */
+export const TRANSCRIPT_PART_BYTES = 1_500_000;
+/** Base64 attachment data over this size is stored once and referenced. */
+export const ATTACHMENT_REF_BYTES = 1_000_000;
+/** A generation id: the bot's process start plus a random suffix. */
+export const GEN_PATTERN = /^[A-Za-z0-9_.:-]{1,128}$/;
+
+/** `attaching`: reserved at admission (item 42) — the row holds the request
+ *  and no prompt yet; a reclaim restarts the run from the request. `live`:
+ *  the prompt and seed landed. `handoff`: the owner drained. `finishing`: the
+ *  owner replied. */
+export type LivePhase = "attaching" | "live" | "handoff" | "finishing";
+export type StopMode = "soft" | "hard";
+
+/** Where the run's status card is, so a resumed run edits the same message. */
+export interface CardHandle {
+  channel: string;
+  ts: string;
+}
+
+/** The registry's `RunMeta` fields (spelled out rather than imported: the
+ *  registry is a Node module and this file is shared with the state Worker)
+ *  plus what a resume needs that the dispatcher otherwise keeps in closures. */
+export interface LiveRunMeta {
+  agent?: string;
+  model?: string;
+  channelId: string;
+  userId: string;
+  threadKey: string;
+  channelVisibility?: ChannelVisibility;
+  repo?: string;
+  sourceUrl?: string;
+  userName?: string;
+  effort?: string;
+  ref?: string;
+  headSha?: string;
+  pr?: number;
+  readonly?: boolean;
+  /** Which executor the run attached: what `makeExecutor` chose. */
+  selection?: "resident" | "sandbox" | "local" | "none";
+  /** The worktree path the system prompt names. */
+  workspace?: string;
+  /** The request the run was admitted for (item 42), in the durable inbox
+   *  row's shape — text with its directives, sender, link, arrival time, the
+   *  attachments when they fit — so a reclaim of an `attaching` row can
+   *  dispatch it again under the same run id and card. */
+  request?: Record<string, unknown>;
+}
+
+/** Dispatcher-local run state a resume must restore (the `submit_*` callbacks,
+ *  the checklist, the pushed branch, the review head, the infra counters). */
+export type RunState = Record<string, unknown>;
+
+export interface LiveRunRow {
+  runId: string;
+  threadKey: string;
+  ownerGen: string;
+  /** Epoch ms. */
+  leaseUntil: number;
+  startedAt: number;
+  phase: LivePhase;
+  stop: StopMode | null;
+  meta: LiveRunMeta;
+  card: CardHandle | null;
+  /** The composed system prompt, verbatim. */
+  system: string;
+  /** The tool definitions the run was started with, verbatim. */
+  tools: ToolDef[];
+  state: RunState;
+}
+
+/** One tool call the step dispatched; `tool` decides how a resume settles it. */
+export interface InFlightCall {
+  callId: string;
+  tool: string;
+}
+
+/** Written BEFORE a step's tools run (after its transcript turns landed). */
+export interface StepRecord {
+  step: number;
+  /** The registry `seq` at the time, for ordering against events. */
+  seq: number;
+  /** Transcript turns present when this record was written. */
+  turnIndex: number;
+  inFlight: InFlightCall[];
+  /** The inbox `seq` the run has consumed up to (0 = none). */
+  inboxConsumedSeq: number;
+  remainingMs: number;
+  turn: number;
+  iteration: number;
+}
+
+export interface InboxItem {
+  seq: number;
+  /** The `IncomingMessage` minus attachment bytes, plus channel/ts/threadTs. */
+  message: Record<string, unknown>;
+}
+
+export interface RunJob {
+  kind: string;
+  payload: unknown;
+}
+
+export interface ClaimRequest {
+  runId: string;
+  threadKey: string;
+  gen: string;
+  leaseMs: number;
+  startedAt: number;
+  meta: LiveRunMeta;
+  card?: CardHandle | null;
+  system: string;
+  tools: ToolDef[];
+  state?: RunState;
+  /** `attaching` reserves the thread at admission with an empty prompt (item
+   *  42); absent (or `live`) is the claim with the prompt — which, on the
+   *  owner's own attaching row, promotes it in place. */
+  phase?: "attaching" | "live";
+}
+
+export type ClaimResult =
+  { ok: true } | { ok: false; reason: "thread-live"; live: { runId: string; agent?: string; startedAt: number } };
+
+export type FenceResult = { ok: true } | { ok: false; reason: "fenced" | "unknown-run" };
+
+export interface ReclaimedRun {
+  /** The row as the new generation now holds it (`phase: live`, its lease). */
+  row: LiveRunRow;
+  /** The phase the row was in when taken: `live` (an expired lease — the
+   *  owner died), `handoff` (the owner drained), or `finishing` (the owner
+   *  had replied and died before `finish` — the run is closed, never resumed). */
+  reclaimedFrom: LivePhase;
+  lastStep: StepRecord | null;
+  inbox: InboxItem[];
+  jobs: RunJob[];
+}
+
+/** One transcript row: a content part of turn `idx`. */
+export interface TranscriptRow {
+  idx: number;
+  part: number;
+  json: string;
+}
+
+/** An externalized attachment: base64 data stored once, referenced from a row. */
+export interface TranscriptAttachment {
+  ref: string;
+  mediaType: string;
+  data: string;
+}
+
+/** The turns a step write carries: the previous step's results and this step's assistant turn. */
+export interface TranscriptTurn {
+  idx: number;
+  message: ChatMessage;
+}
+
+export type AppendableEvent = RunEvent & { seq: number };