@jr2/orchestrator 0.4.1 → 0.5.1

package/src/stub-harness.ts

@@ -5,20 +5,26 @@
 // the durable stream open, and never act — the Machine parks exactly as it would against a
 // silent real Harness, and e2e drives it by playing the agent against `/mcp/<iid>` instead.
 //
-// Wire (ADR-0027 — the normative model of the five endpoints; `@jr2/harness` serves it for real):
-//   POST /agents/:name/:id  {message, cwd?, definition, model?, thinkingLevel?} → 200 { streamUrl, offset, submissionId }
-//     (`message` and `cwd` are the Turn's Frame — what it is about and where it works, ADR-0057)
+// Wire (ADR-0027 — the normative model of the conversation endpoints; `@jr2/harness` serves it for
+// real), and the pod's memory kills, which a stub never has (ADR-0062):
+//   POST /agents/:name/:id  {message, cwd?, definition, model?, thinkingLevel?, notices?, kept?} → 200 { streamUrl, offset, submissionId }
+//     (`message` and `cwd` are the Turn's Frame — what it is about and where it works, ADR-0057;
+//     `kept` admits as any POST does, because the stub keeps every conversation — the real Harness
+//     answers 404 when it keeps none, ADR-0062)
 //   GET  /agents/:name/:id?offset=…[&view=updates] → 200 `[]` + Stream-Next-Offset/Up-To-Date
 //   GET  /agents/:name/:id?…&live=long-poll        → parked; 204 + same headers on timeout
-//   POST /agents/:name/:id/abort                   → 200 { aborted }
+//   POST /agents/:name/:id/abort  [{cause?}]       → 200 { aborted }
 //   GET  /agents/:name/:id?view=history            → 200 { …, settlements }
+//   GET  /memory-kills                             → 200 { kills: [] }
 // (the client's `wait(admission)` long-polls `streamUrl?view=updates` from the admission offset;
 // an empty stream parks it — exactly the "admitted, never settles" semantics the mechanics tier
 // needs.) The client then re-polls calmly at the long-poll cadence. `close()` severs parked polls.
 //
-// A stub submission therefore ends exactly one way: ABORTED, when the state that asked for the
-// turn stops waiting (ADR-0024). That is what `history`'s `settlements` carries, and it is the
-// only place a black-box test can see a turn end — the run itself is untouched by an abort.
+// A stub submission therefore ends one way: the sweep, when the state that asked for the turn stops
+// waiting (ADR-0024). Its outcome follows the sweep's cause, as the real Harness's does: `ended` for
+// the running Submission when the Turn's own pick ended it (`cause: "pick"`), `aborted` for every
+// other Submission and every other end. That is what `history`'s `settlements` carries, and it is
+// the only place a black-box test can see a turn end — the run itself is untouched by an abort.
 //
 // This can later grow scriptable behavior or be swapped for a real local Harness without
 // touching actor code — it is only a different URL.
@@ -55,8 +61,8 @@ export type Admission = {
 };
 
 /** One settled submission, in the shape `history()` reports it. The stub settles submissions for
- * exactly one reason — an abort (ADR-0024) — so `outcome` has exactly one value here. */
-export type StubSettlement = { submissionId: string; outcome: "aborted" };
+ * exactly one reason — an abort (ADR-0024) — so `outcome` is one of the two a sweep gives. */
+export type StubSettlement = { submissionId: string; outcome: "ended" | "aborted" };
 
 export type StubHarnessOptions = {
   /** Listen port. Default 0 → ephemeral (read back from `url`). */
@@ -102,17 +108,39 @@ export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<R
     // End every in-flight and queued submission for one instance (`agents.abort` — ADR-0024).
     // Answers `{ aborted }`: whether there was anything to end, exactly as the real Harness
     // does for an idle instance. Settlement is recorded here rather than pushed on the stream, because nothing is
-    // listening — the actor that asked for the turn is already stopped.
+    // listening — the actor that asked for the turn is already stopped. The body's cause decides the
+    // running Submission's outcome, the first unsettled one (`AbortRequest`): `ended` for `pick` with
+    // that Submission's id; no body, another id, or any other cause, `aborted`. What is queued
+    // behind it never ran: `aborted`.
     const aborting = req.method === "POST" && ABORT_PATH.exec(url.pathname);
     if (aborting) {
       const [, agentName, instanceId] = aborting as unknown as [string, string, string];
-      const k = key(decodeURIComponent(agentName), decodeURIComponent(instanceId));
-      const ended = unsettled.get(k)?.splice(0) ?? [];
-      const settled = settlements.get(k) ?? [];
-      settled.push(...ended.map((submissionId) => ({ submissionId, outcome: "aborted" as const })));
-      settlements.set(k, settled);
+      let body = "";
+      req.on("data", (chunk: Buffer) => (body += chunk));
+      req.on("end", () => {
+        const sent = safeParse(body) as { cause?: unknown; submissionId?: unknown } | undefined;
+        const k = key(decodeURIComponent(agentName), decodeURIComponent(instanceId));
+        const ended = unsettled.get(k)?.splice(0) ?? [];
+        const byPick = sent?.cause === "pick" && sent.submissionId === ended[0];
+        const settled = settlements.get(k) ?? [];
+        settled.push(
+          ...ended.map((submissionId, i) => ({
+            submissionId,
+            outcome: byPick && i === 0 ? ("ended" as const) : ("aborted" as const),
+          })),
+        );
+        settlements.set(k, settled);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ aborted: ended.length > 0 }));
+      });
+      return;
+    }
+
+    // The pod's memory kills (ADR-0062): a stub runs no process, so none. Answered, not a 404, so a
+    // Turn the stub admits logs no failed read.
+    if (req.method === "GET" && url.pathname === "/memory-kills") {
       res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({ aborted: ended.length > 0 }));
+      res.end(JSON.stringify({ kills: [] }));
       return;
     }
 

package/src/timers.ts

@@ -106,11 +106,15 @@ export function scheduledFor(ref: AnyActorRef): Array<{ id: string; event: Event
  * Install it before `start()` (the root's creation event is early enough): a timer armed before the
  * wrap is not seen. The same xstate internals as the rest of this module; the canary is the same.
  */
-export function watchTimers(system: AnyActorRef["system"]): (source: unknown, event: unknown) => boolean {
+export function watchTimers(
+  system: AnyActorRef["system"],
+  hooks: TimerHooks = {},
+): (source: unknown, event: unknown) => boolean {
   const scheduler = system.scheduler;
   const { schedule, cancel } = scheduler;
   const armed = new Map<string, { source: AnyActorRef; event: EventObject }>();
   scheduler.schedule = (source, target, event, delay, id = Math.random().toString(36).slice(2)) => {
+    hooks.arming?.(source);
     schedule(source, target, event, delay, id);
     armed.set(keyOf(source, id), { source, event });
   };
@@ -129,6 +133,15 @@ export function watchTimers(system: AnyActorRef["system"]): (source: unknown, ev
   };
 }
 
+/** What `watchTimers` tells as the scheduler arms a timer: `arming` is called with the timer's
+ * source just before xstate schedules it, and xstate then arms it on the system's clock in the same
+ * call. xstate schedules in the deferred effects of the event whose actions armed the timer, so the
+ * source still takes that event. The run host keeps each timer's cause this way (`cause.ts`,
+ * ADR-0024). */
+export type TimerHooks = {
+  arming?: (source: AnyActorRef) => void;
+};
+
 /**
  * Start a restored run, then schedule each recorded timer again on it. One function, so the order
  * cannot be got wrong: re-armed BEFORE `start()`, a timer is armed twice and fires twice, because

package/src/vocabulary.ts

@@ -101,6 +101,23 @@ export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined
   return inputSchemas.get(machine.config);
 }
 
+/** A zod schema, by its shape: the Instance can resolve a zod of its own, so `instanceof` does not
+ * tell. */
+export function isZodSchema(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "_zod" in value &&
+    typeof (value as { safeParse?: unknown }).safeParse === "function"
+  );
+}
+
+/** The run input that a machine declares: the door that `jr2Setup` attached, or a zod `input` on
+ * its `createMachine` config that no door reads (a machine that `setup()` made). */
+export function declaresRunInput(machine: AnyStateMachine): boolean {
+  return inputSchemaOf(machine) !== undefined || isZodSchema((machine.config as { input?: unknown }).input);
+}
+
 // Who may send what, per state (ADR-0015): the seats the menu-derivation walk computed. Same key
 // choice as the vocabulary, for the same reasons. The Machine's doc carries them; `jr2 up` and the
 // Console show them, so an author reads the audience rule's answer for their own Machine.
@@ -144,22 +161,60 @@ export function loadWarningsOf(machine: AnyStateMachine): string[] {
   return loadWarnings.get(machine.config) ?? [];
 }
 
+// What the HOST adds to the input of the machine a run STARTS with, beside the door
+// (`RunHost.start`). One field today: the run's seed Instance ID, minted with the run and
+// reported by `jr2 status`. It names the RUN, never a conversation — jr2 mints every Agent
+// Instance ID in the input mapper (ADR-0016, ADR-0057), and a Machine cannot pass one in.
+//
+// It is deliberately NOT door material (ADR-0033): no caller sends it — `start` overwrites
+// whatever arrived, after the parse — and it is never served as JSON Schema, so putting it in a
+// door schema would publish it and demand of every caller a field the host supplies anyway.
+//
+// It is also PLACEMENT-DEPENDENT: only the ROOT machine is started with it. A machine invoked
+// further down is fed by its parent, which passes what it chooses. No type can see where a machine
+// sits, so the one contract that must reason about this — `workspace()`'s body guard — takes the
+// permissive answer and counts these keys as PROVIDED, which lets a body declare the field
+// honestly. Counting them as provided (rather than subtracting them from what the body demands)
+// is what keeps their TYPE checked: `instanceId` is a string, and a body asking for anything else
+// is still rejected.
 /**
- * What the HOST adds to the input of the machine a run STARTS with, beside the door
- * (`RunHost.start`). One field today: the run's seed Instance ID, minted with the run and
- * reported by `jr2 status`. It names the RUN, never a conversation — jr2 mints every Agent
- * Instance ID in the input mapper (ADR-0016, ADR-0057), and a Machine cannot pass one in.
+ * The fields that jr2 adds to the input of the Machine that a run starts, beside the input that
+ * the caller sent. Today it is one field: `instanceId`, an id that jr2 makes for the run.
+ *
+ * Add it to the type of your root Machine's input when the Machine reads it:
+ * `HostInjectedInput & RunInput`. Do not put it in the `input` schema that a run starts with. No
+ * caller sends it. jr2 writes it over any value that a caller sends.
+ *
+ * Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
+ * that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
+ * `workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`.
+ *
+ * The `spec` of a root `workspace()` also gets it, and the type of its input shows it:
+ * ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``.
+ *
+ * It is not the run id. Use it, for example, to give each run a branch of its own.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { jr2Setup, type HostInjectedInput } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ ticket: z.string() });
+ * type Input = HostInjectedInput & z.infer<typeof runInput>;
  *
- * It is deliberately NOT door material (ADR-0033): no caller sends it — `start` overwrites
- * whatever arrived, after the parse — and it is never served as JSON Schema, so putting it in a
- * door schema would publish it and demand of every caller a field the host supplies anyway.
+ * export const machine = jr2Setup({
+ *   types: {} as { input: Input; context: Input; output: { run: string; ticket: string } },
+ * }).createMachine({
+ *   id: "ticket",
+ *   input: runInput,
+ *   context: ({ input }) => input,
+ *   initial: "done",
+ *   states: { done: { type: "final" } },
+ *   output: ({ context }) => ({ run: context.instanceId, ticket: context.ticket }),
+ * });
+ * ```
  *
- * It is also PLACEMENT-DEPENDENT: only the ROOT machine is started with it. A machine invoked
- * further down is fed by its parent, which passes what it chooses. No type can see where a machine
- * sits, so the one contract that must reason about this — `workspace()`'s body guard — takes the
- * permissive answer and counts these keys as PROVIDED, which lets a body declare the field
- * honestly. Counting them as provided (rather than subtracting them from what the body demands)
- * is what keeps their TYPE checked: `instanceId` is a string, and a body asking for anything else
- * is still rejected.
+ * @see docs/guides/write-a-workflow.md
+ * @see docs/reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md
  */
 export type HostInjectedInput = { instanceId: string };

package/src/wire.ts

@@ -13,19 +13,35 @@
 // asserts each shape here is mutually assignable with `@jr2/harness/wire`'s, and `@jr2/harness`
 // stays a devDependency so that file — and only that file — can see the server's copy.
 
-/** How a Submission ends (ADR-0024/0027): `completed` (the prompt resolved), `failed` (the turn
- * threw — provider failure after retries, or the Menu connect/list failed), `aborted` (swept). */
-export type SettlementOutcome = "completed" | "failed" | "aborted";
-
-/** The error payload a non-`completed` Settlement carries. */
+/** How a Submission ends (ADR-0024/0027). The Orchestrator is the one judge of how a Turn ended:
+ * `completed` (the run returned, and the Turn is still open — the Agent actor asks again,
+ * ADR-0016), `ended` (the Turn's own pick ended the Turn, from this Submission or an earlier one of
+ * the same Turn, and the sweep said `cause: "pick"`),
+ * `failed` (the turn threw — provider failure after retries, the Menu connect/list failed, a
+ * Runaway), `aborted` (something else ended the Turn, no sweep came in time, or it was over before
+ * it started — ADR-0026). */
+export type SettlementOutcome = "completed" | "ended" | "failed" | "aborted";
+
+/** The error payload a `failed` or `aborted` Settlement carries. A `completed` or an `ended` one
+ * carries none. */
 export type SettlementError = { type: string; message?: string };
 
 /** `SettlementError.type` for a swept Submission (ADR-0024/0025). */
 export const SUBMISSION_ABORTED = "submission_aborted";
 
-/** `SettlementError.type` for a Turn the Harness ended as a Runaway (ADR-0035) — no fourth
- * `SettlementOutcome`; the typed error on a `failed` settlement is what lets the Agent actor switch
- * on the class (one fresh-conversation reroll) without parsing prose. */
+/** Why the Orchestrator sweeps a conversation (ADR-0024): `pick` — the Turn's own pick ended it, so
+ * the running Submission settles `ended`. Any other end sends no cause, and the sweep settles
+ * `aborted`. */
+export type AbortCause = "pick";
+
+/** The body of `POST /agents/:name/:id/abort`. `submissionId` names the Submission the cause is
+ * about: the last one ledgered for the Turn, which the Harness settles `ended` only while it is the
+ * running one (ADR-0024). */
+export type AbortRequest = { cause?: AbortCause; submissionId?: string };
+
+/** `SettlementError.type` for a Turn the Harness ended as a Runaway (ADR-0035). A Runaway is a kind
+ * of failure, so it has no outcome of its own: the typed error on a `failed` settlement is what lets
+ * the Agent actor switch on the class (one fresh-conversation reroll) without parsing prose. */
 export const SUBMISSION_RUNAWAY = "runaway";
 
 /** `SettlementError.type` for a Submission the Harness admitted but had not settled when it
@@ -33,11 +49,18 @@ export const SUBMISSION_RUNAWAY = "runaway";
  * Settlement, not a 404. The Agent actor switches on this type, never on the message's prose. */
 export const SUBMISSION_HARNESS_RESTARTED = "harness_restarted";
 
-/** One settled Submission, in the shape `?view=history`'s `settlements` reports. */
+/** What a Submission's model answers spent, summed: tokens, and the cost in US dollars from the
+ * model's catalog rates (0 for a model with no rates). */
+export type SubmissionUsage = { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number };
+
+/** One settled Submission, in the shape `?view=history`'s `settlements` reports. `usage` is absent
+ * when no model answer reported one, or when the Submission was lost with a restarted Harness. The
+ * Orchestrator does not read it yet: the @model tier records it per trial (ADR-0066). */
 export type Settlement = {
   submissionId: string;
   outcome: SettlementOutcome;
   error?: SettlementError;
+  usage?: SubmissionUsage;
 };
 
 /** Where a chunk sits on the durable stream. Ordering only (`batch`, then `index`); the Harness
@@ -59,10 +82,16 @@ export type SubmissionSettledEvent = StreamChunk<"submission-settled"> & Settlem
 /**
  * The Harness's memory guard killed the Agent's processes (ADR-0061, layer 4), on the stream of the
  * conversation whose Turn was running. The Agent heard it in its `bash` answer; this is how the
- * Orchestrator hears it, so the next Turn in the Workspace is told (ADR-0062). `peak` and `limit`
- * are the guard's own spellings — carried to the notice as they are, never parsed.
+ * Orchestrator hears it, so the next Turn in the Workspace is told (ADR-0062). `id` is the kill's:
+ * the same on every stream that carries it and in `GET /memory-kills`, so one kill is one notice.
+ * `peak` and `limit` are the guard's own spellings — carried to the notice as they are, never parsed.
  */
-export type MemoryLimitEvent = StreamChunk<"memory-limit"> & { peak: string; limit: string };
+export type MemoryLimitEvent = StreamChunk<"memory-limit"> & {
+  /** Absent from an older Harness's event, which had none. */
+  id?: string;
+  peak: string;
+  limit: string;
+};
 
 /** One event on the durable stream (`GET ?offset=…&view=updates` → 200 JSON array). */
 export type StreamEvent = MessageAppendedEvent | SubmissionSettledEvent | MemoryLimitEvent;
@@ -73,14 +102,16 @@ export type StreamEvent = MessageAppendedEvent | SubmissionSettledEvent | Memory
 // Harness writes every word of the Briefing's Turn part from them.
 
 /** The Sandbox's processes were killed at its memory limit during `agent`'s Turn — by the
- * Harness's guard (`peak` known) or by the kernel (`peak` unknown). Workspace scope: the next Turn
- * of any Agent in that Workspace. */
+ * Harness's guard (`peak` known) or by the kernel (`peak` unknown). `agent` is absent for every
+ * kill read from the pod's list, which cannot say whose Turn a kill ended. Workspace scope: the next
+ * Turn of any Agent in that Workspace. */
 export type MemoryLimitNotice = {
   kind: "memory-limit";
   scope: "workspace";
-  agent: string;
+  agent?: string;
   peak?: string;
-  limit: string;
+  /** Absent with `peak` when the sizes read were not sizes: the notice says no sizes. */
+  limit?: string;
 };
 
 /** This conversation is new; earlier context is gone. Conversation scope: that Agent's next
@@ -147,6 +178,49 @@ export type LiveSetRequest = { live: LiveConversation[] };
 /** What `PUT /agents` answers (200): how many conversations this statement freed. */
 export type LiveSetResponse = { freed: number };
 
+/** What a Harness answers (404) to an admission with `kept: true` when it keeps no such
+ * conversation (ADR-0062). The client takes a 404 as "not kept" only with `kept: false` on it: a
+ * 404 from anything else is a failed admission. */
+export type NotKeptResponse = { error: string; kept: false };
+
+// ---- The pod's guard kills (`GET /memory-kills` — ADR-0061, ADR-0062) -------------------------
+// Every guard kill, kept by the Harness pod-scoped. A stream is read only while the Agent actor
+// waits on a Submission, and that wait stops when the Agent's state exits — so a kill while no
+// Submission runs, or after the wait stopped, has no reader there. The actor reads this list before
+// it admits a Turn into the Workspace. The read is idempotent: the notice ledger keeps each `id` it
+// raised (`seen`), whichever path it came by.
+
+/** One guard kill: `id` unique for the pod's life and the stream events' `id`, `at` when the guard
+ * fired, the guard's own `peak` and `limit`, and `told` — the conversations with a `bash` call
+ * running then, whose answer told the Agent of the kill. None when no call ran. */
+export type PodMemoryKill = {
+  id: string;
+  at: string;
+  /** Absent, with `limit`, when the pod could not keep the sizes as sizes. */
+  peak?: string;
+  limit?: string;
+  told: LiveConversation[];
+};
+
+/** What `GET /memory-kills` answers (200): the newest kills, oldest first. */
+export type MemoryKillsResponse = { kills: PodMemoryKill[] };
+
+// The bounds of the list, the same on the two sides of the wire (ADR-0062). The Agent's uid can
+// write the file the list is read from, so the Harness keeps no kill, and no `told` entry, that the
+// Orchestrator drops. With these bounds the largest answer is 149,259 bytes, under the
+// Orchestrator's read of 256 KiB: 16 kills of 208 bytes and 32 `told` entries of 284 bytes each.
+
+/** How many kills the pod keeps. A guard kill is rare; a burst of them is one piece of news. */
+export const KEPT_KILLS = 16;
+/** The most conversations one kill's `told` holds: far more Agents than a Workspace runs. */
+export const MAX_TOLD = 32;
+/** The longest `id` and `at` of a kill. A minted id and an ISO time are less than half of it. */
+export const MAX_KILL_STAMP = 64;
+/** The longest `agent` and `instanceId` of a `told` entry. */
+export const MAX_KILL_NAME = 128;
+/** The most of `GET /memory-kills` the Orchestrator reads, in bytes. */
+export const MAX_KILLS_BODY = 256 * 1024;
+
 // ---- The run-narrative echo (`POST /echo` — ADR-0023) ------------------------------------------
 // "Print these events": the Orchestrator — the observation feed's one subscriber (ADR-0022) — tees
 // the owning run's feed to the enclosing Workspace's Harness, which renders it into its own pod log.