@jr2/orchestrator 0.4.1 → 0.6.0

package/src/vocabulary.ts

@@ -101,6 +101,44 @@ export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined
   return inputSchemas.get(machine.config);
 }
 
+/**
+ * The door of a wrapper under a parent (ADR-0033). No other door reads a parent's input, so the
+ * wrapper parses it, and the parsed shape is what it uses: defaults are applied and unknown keys
+ * go. A key in `beside` is no one's to send, so it stays out of the parse and rides beside the
+ * result. A value that is wrong is a defect of the parent's Machine: a throw, and its `onError`.
+ *
+ * @param refusal - the start of the error, which says what the refusal saved
+ * @internal
+ */
+export function parsedNestedDoor(
+  door: z.ZodObject,
+  value: Record<string, unknown>,
+  beside: readonly string[],
+  refusal: string,
+): Record<string, unknown> {
+  const kept = Object.entries(value).filter(([key, v]) => beside.includes(key) && v !== undefined);
+  const parsed = door.safeParse(Object.fromEntries(Object.entries(value).filter(([key]) => !beside.includes(key))));
+  if (!parsed.success) throw new Error(`${refusal}: ${parsed.error.message}`);
+  return { ...(parsed.data as Record<string, unknown>), ...Object.fromEntries(kept) };
+}
+
+/** 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 +182,58 @@ 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">`. For example, a cut
+ * can name a branch for each run: `` branch: `fix/${context.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.
@@ -193,18 +267,18 @@ export type EchoRequest = { events: EchoEvent[] };
 /** One Repo Slot to attach. The Orchestrator resolves the Repo's `identity` and cache `key`
  * (repo-identity.ts) — the Harness never re-derives them, so the cache it clones from and the node
  * cache the operator mounted agree by construction (ADR-0051). `url` is the Binding's own spelling,
- * the push url (ADR-0005); `ref` is the base the branch starts from, omitted for the Repo's default
- * branch. */
+ * the push url (ADR-0005); `ref` is the base that `default/` stays on and a new branch starts from,
+ * omitted for the Repo's default branch. */
 export type AttachSlot = { slot: string; url: string; identity: string; key: string; ref?: string };
 
-/** What `POST /attach` accepts: the slots in declaration order, the Workspace's branch, and — for a
- * reviewer's seat — the sha the detached review worktree is forced to (ADR-0028). */
-export type AttachRequest = { slots: AttachSlot[]; branch: string; reviewSha?: string };
+/** What `POST /attach` accepts: the slots in declaration order. The Workspace only clones, so the
+ * request names no branch and no commit (ADR-0075). */
+export type AttachRequest = { slots: AttachSlot[] };
 
-/** What `POST /attach` answers (200): the branch worktree per slot, and the review worktree per
- * slot when the request named a `reviewSha`. Freshness is the operator's verdict on the Sandbox,
- * which the Orchestrator reads itself — never the Harness's to report. */
-export type AttachResponse = { repos: Record<string, string>; review?: Record<string, string> };
+/** What `POST /attach` answers (200): the folder of each slot, and the base that each slot's
+ * `default/` holds. Freshness is the operator's verdict on the Sandbox, which the Orchestrator
+ * reads itself — never the Harness's to report. */
+export type AttachResponse = { repos: Record<string, string>; bases: Record<string, string> };
 
 /** What a failed attach answers: 400 for a body that is not an `AttachRequest`, 500 when a step
  * failed — `slot` names the Repo Slot, and `error` carries the step and git's own stderr. */
@@ -238,7 +312,7 @@ export type SyncAnswer =
 
 /** What `POST /exec/:id` accepts: argv (never shell text), an absolute `cwd` or none, the timeout,
  * and how many characters of the stream's end the output keeps. */
-export type ExecRequest = { argv: string[]; cwd?: string; timeoutMs: number; tail: number };
+export type ExecRequest = { argv: string[]; cwd?: string; root?: true; timeoutMs: number; tail: number };
 
 /** How an exec ended. Every one is output; none is a fault. */
 export type ExecOutcome =