@jr2/machines 0.3.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/machines",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "The Machines the jr2 kit ships: packaged xstate Machines that leave their parts Open for a composer to bind.",
   "license": "MIT",
   "private": false,
@@ -35,20 +35,20 @@
   "peerDependencies": {
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.3.0"
+    "@jr2/orchestrator": "0.5.1"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "typescript": "^5.6.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.3.0"
+    "@jr2/orchestrator": "0.5.1"
   },
   "files": [
     "src"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --test"
+    "test": "node --test --test-global-setup=../../scripts/test-tmpdir.ts"
   }
 }

package/src/index.ts

@@ -3,8 +3,8 @@
 // Machines from this index: `import { task } from "@jr2/machines"`.
 //
 // It ships MACHINES and never Workflows. A Workflow is the name an Instance registers a Machine
-// under, and only the Instance's `workflows/` file can do that (CONTEXT.md) — so what a consumer
-// receives is a Machine object, and the line that turns it into a Workflow is theirs:
+// under, and only the Instance's `workflows/` file can do that (GLOSSARY.md, ADR-0009) — so what a
+// consumer receives is a Machine object, and the line that turns it into a Workflow is theirs:
 //
 //   import { customize } from "@jr2/orchestrator";
 //   import { task } from "@jr2/machines";
@@ -21,7 +21,7 @@
 // rejected for working by the ACCIDENT of equal versions and installing two copies silently on
 // skew (ADR-0054).
 //
-// Every Machine exported here leaves its unfillable parts OPEN (CONTEXT.md, ADR-0054): a package
+// Every Machine exported here leaves its unfillable parts OPEN (GLOSSARY.md, ADR-0054): a package
 // cannot know the repository or pay for the model, so it says so rather than guessing. `jr2 up`
 // refuses an Open part nobody bound and prints the `customize` line that binds it.
 

package/src/task.ts

@@ -2,7 +2,7 @@
 // done. It is the smallest shape that is still worth packaging — a coder in a Sandbox, a Gate a
 // human answers, and a loop between them that ends when the human ends it.
 //
-// Both of the parts a package cannot honestly fill are left OPEN (CONTEXT.md, ADR-0051/0054): the
+// Both of the parts a package cannot honestly fill are left OPEN (GLOSSARY.md, ADR-0051/0054): the
 // Repo Slots are Open as a MAP, because the package cannot know the repository — nor how many
 // checkouts the task wants beside it — and the Agent `coder` has no model, because the package
 // cannot pay for one. A consumer binds both on the line that registers this Machine as a
@@ -17,7 +17,7 @@
 //       target: { url: "https://github.com/you/repo.git" },
 //       reference: { url: "https://github.com/you/lib.git" }, // optional: more checkouts to read
 //     },
-//     agents: { coder: { model: "anthropic/claude-sonnet-4-6" } },
+//     agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
 //   });
 //
 // `jr2 up` walks the registered Machines and refuses either part unbound, printing exactly that
@@ -36,6 +36,7 @@ import { z } from "zod";
 import {
   agent,
   defineEvent,
+  fail,
   jr2Setup,
   open,
   workspace,
@@ -65,27 +66,74 @@ const THINKING_LEVELS = [
 ] as const satisfies readonly ThinkingLevel[];
 
 const door = z.object({
+  /** What to do, in prose. Required. The coder's first Turn is this prompt, with the Worktree it
+   * works in. */
   prompt: z.string().describe("What to do, in prose. The coder's first turn is this, framed with the worktree."),
+  /** The branch to cut and commit on. Default: `jr2/task-<instance id>`, where `<instance id>` is
+   * the seed Instance ID of the run (`instanceId` in `jr2 status`). It is not the run id. Two runs
+   * never use the same branch. Required when `task` runs inside another Machine, such as a
+   * `pool()`: there is no Instance ID to name the branch after. */
   branch: z
     .string()
     .optional()
-    .describe("The branch to cut and commit on. Default: jr2/task-<run id>, so concurrent runs never collide."),
+    .describe(
+      "The branch to cut and commit on. Default: jr2/task-<instance id>, where <instance id> is the seed " +
+        "Instance ID of the run (instanceId in jr2 status). It is not the run id.",
+    ),
   // The two Dials (ADR-0018) as a PER-RUN escape hatch, not a default (ADR-0054): the bound
   // definition is what `jr2 up` preflights, and a door value overrides it for this one run's Turns.
   // Identity — instructions, workspace access — is deliberately absent: an invocation that rewrote
   // those would make the Agent's name a lie.
+  /** The coder's model for this run only, as `"<provider>/<modelId>"`. Default: the model of the
+   * coder Agent. */
   model: z.string().optional().describe('Override the coder\'s model for this run only, as "<provider>/<modelId>".'),
+  /** The coder's thinking level for this run only: `off`, `minimal`, `low`, `medium`, `high` or
+   * `xhigh`. Default: the thinking level of the coder Agent. */
   thinkingLevel: z
     .enum(THINKING_LEVELS)
     .optional()
     .describe("Override the coder's reasoning effort for this run only."),
 });
 
-/** What a caller sends. */
+/**
+ * The run input of `task`: what a caller sends to start a run, for example with
+ * `jr2 run <workflow> --input '{"prompt":"…"}'`.
+ *
+ * `prompt` is required. `branch`, `model` and `thinkingLevel` are optional. Each field has its own
+ * doc.
+ *
+ * @example
+ * ```ts
+ * import type { TaskInput } from "@jr2/machines";
+ *
+ * export const input: TaskInput = {
+ *   prompt: "Make the failing test in test/greet.test.ts pass.",
+ *   branch: "fix/greet",
+ *   thinkingLevel: "high",
+ * };
+ * ```
+ *
+ * @see @jr2/orchestrator/docs/reference/machines.md
+ */
 export type TaskInput = z.infer<typeof door>;
 
-/** What a run of `task` settles as — approved by the human, or lost with its Workspace. */
-export type TaskOutput = { outcome: "approved"; branch: string } | { outcome: "lost" };
+/**
+ * The output of a run of `task` that ends `done`: `{ branch }`, the branch of the work that the
+ * human approved. A run whose Workspace is lost has no output of this type: it fails, and the run
+ * ends `failed` with the reason `the Workspace was lost` (ADR-0073).
+ *
+ * @example
+ * ```ts
+ * import type { TaskOutput } from "@jr2/machines";
+ *
+ * export function describe(output: TaskOutput): string {
+ *   return `approved on ${output.branch}`;
+ * }
+ * ```
+ *
+ * @see @jr2/orchestrator/docs/reference/machines.md
+ */
+export type TaskOutput = { branch: string };
 
 // ---------------------------------------------------------------------------------------------
 // Vocabulary (ADR-0011/0015), scoped to this Machine alone: the agent event becomes the coder
@@ -133,12 +181,39 @@ type BodyContext = BodyInput & {
   turns: number;
   /** The coder's own account of the last finished Turn — the Gate's `summary`. */
   summary?: string;
-  /** Why the run is parked without a summary: the reason the fault carried — the Gate's `reason`. */
+  /** Why the run is parked without a summary: the reason the fault carried — the Gate's `reason`.
+   * Kept into the re-briefed Turn that follows, which tells the coder of a memory kill (ADR-0061);
+   * the next `finish` clears it. */
   reason?: string;
   /** The human's last notes, which are the next Turn's prompt. */
   notes?: string;
 };
 
+/**
+ * The Machine inside `task`: the coder's loop and the `review` Gate, with no `workspace()` around
+ * it. Use `task` to run it. Use `body` only to put the same loop in a `workspace()` of your own.
+ * For example, your `workspace()` can have Repo Slots or a run input that differ from those of
+ * `task`. Its input is the run input plus the `workspace` handles, and it works in the first Repo
+ * Slot of those handles.
+ *
+ * @example
+ * ```ts
+ * import { customize, workspace } from "@jr2/orchestrator";
+ * import { body, type TaskInput } from "@jr2/machines";
+ *
+ * const fixed = workspace(body, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   spec: ({ input }: { input: TaskInput }) => ({ branch: input.branch ?? "jr2/fix" }),
+ * });
+ *
+ * export const machine = customize(fixed, {
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ * });
+ * ```
+ *
+ * @see @jr2/orchestrator/docs/reference/machines.md
+ * @see @jr2/orchestrator/docs/concepts/workspaces.md
+ */
 export const body = jr2Setup({
   types: {} as { context: BodyContext; input: BodyInput; output: TaskOutput },
   events: [finish, approve, requestChanges],
@@ -163,6 +238,8 @@ export const body = jr2Setup({
 - You MUST end your turn by calling \`finish\` exactly once, with a summary of what you did. An
   uncalled tool parks the whole workflow waiting for you.`,
     }),
+    // The Failure (ADR-0073): the `lost` state invokes it, and the run ends `failed`.
+    fail: fail(),
   },
 }).createMachine({
   id: "task",
@@ -170,7 +247,7 @@ export const body = jr2Setup({
   initial: "working",
 
   // Our Sandbox is gone — reaped, or replaced after an eviction (ADR-0021). The pod-local clone and
-  // every unpushed commit went with it, so settle as lost rather than pretend we can resume.
+  // every unpushed commit went with it, so fail the run rather than pretend we can resume.
   on: { "workspace.lost": { target: ".lost" } },
 
   states: {
@@ -246,7 +323,7 @@ export const body = jr2Setup({
         // next one starts, so a count jr2 chose would only ever interrupt them.
         request_changes: {
           target: "working",
-          actions: assign({ notes: ({ event }) => event.notes, summary: undefined, reason: undefined }),
+          actions: assign({ notes: ({ event }) => event.notes, summary: undefined }),
         },
       },
     },
@@ -255,13 +332,23 @@ export const body = jr2Setup({
     // the pod, and anything still unpushed in it goes too.
     done: {
       type: "final",
-      output: ({ context }): TaskOutput => ({ outcome: "approved", branch: context.workspace.branch }),
+      output: ({ context }): TaskOutput => ({ branch: context.workspace.branch }),
+    },
+    // Not a final state: a final state means `done`, and this work did not succeed. The Failure
+    // goes up through the wrapper, and the run ends `failed` (ADR-0073). A parent catches it with
+    // an `onError` that `isFailure` guards.
+    lost: {
+      invoke: {
+        src: "fail",
+        input: {
+          reason: "the Workspace was lost",
+          detail: { lost: "the Sandbox is gone, with every commit that was not pushed" },
+        },
+      },
     },
-    lost: { type: "final", output: { outcome: "lost" } satisfies TaskOutput },
   },
 
-  // The body's output is whichever final state settled it — the wrapper forwards it verbatim, so
-  // `jr2 status` on a finished run says which of the two things happened.
+  // The body's output is the output of its one final state, `done`; the wrapper forwards it.
   output: ({ event }) => (event as { output?: TaskOutput }).output as TaskOutput,
 });
 
@@ -269,6 +356,51 @@ export const body = jr2Setup({
 // The wrapper is this Machine's ROOT, so its `input` is the run's door (ADR-0033) and both mappers
 // are typed by it — nothing here restates a shape.
 
+/**
+ * A Machine in which a coder Agent works on one prompt in a Workspace until a human approves the
+ * work. The coder works in a Sandbox and commits on a branch. Then the run waits at the `review`
+ * Gate. The human answers `request_changes` with `notes`, and the coder continues the same
+ * conversation, or `approve`, and the run ends. A run has no limit on the number of rounds.
+ *
+ * `task` does not push. While the run waits at the Gate, the Sandbox stays. You can exec into it
+ * and read the branch. To keep the work, push it yourself. `approve` removes the Sandbox, and
+ * every commit that was not pushed goes with it. If the Sandbox is lost, `task` fails: the run
+ * ends `failed` with the reason `the Workspace was lost`. A parent Machine catches that Failure
+ * with an `onError` that `isFailure` guards.
+ *
+ * `task` leaves two parts Open, so you bind them with `customize()` where you register it:
+ *
+ * - `repos`: the whole Repo Slot map. Name every slot, and at least one. The first slot is the
+ *   Repo that the coder works in. The coder can read the others.
+ * - `agents.coder.model`: the coder's model, as `"<provider>/<modelId>"`. You can also change the
+ *   coder's other fields, such as `instructions` or `thinkingLevel`.
+ *
+ * `jr2 up` refuses a Workflow that leaves either part Open, and prints the `customize()` line
+ * that binds it. You can also give `task` an `image`, a `user` or a Size (`resources`). Without an
+ * image, it uses the Instance's `images/default`, or jr2's Harness image when there is none.
+ * Without a Size, it uses the Instance's `sandbox.resources`, or the kit's Size when it has none.
+ * Inside another Machine, `task` needs `branch` in its input, or it refuses:
+ * ``task: no `branch` on the door and no Instance ID to derive one from``.
+ *
+ * @example
+ * ```ts
+ * import { customize } from "@jr2/orchestrator";
+ * import { task } from "@jr2/machines";
+ *
+ * export const machine = customize(task, {
+ *   repos: {
+ *     app: { url: "https://github.com/you/app.git" },
+ *     lib: { url: "https://github.com/you/lib.git" },
+ *   },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ * });
+ * ```
+ *
+ * @see @jr2/orchestrator/docs/reference/machines.md
+ * @see @jr2/orchestrator/docs/get-started/an-agent-in-a-sandbox.md
+ * @see @jr2/orchestrator/docs/guides/bind-open-parts.md
+ * @see @jr2/orchestrator/docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md
+ */
 export const task = workspace(body, {
   input: door,
   // The Repo Slots, OPEN as a map (ADR-0051/0054): the consumer names every slot and every Repo.
@@ -281,7 +413,7 @@ export const task = workspace(body, {
 });
 
 /**
- * The branch this run works on: the door's, or `jr2/task-<run id>` (ADR-0054).
+ * The branch this run works on: the door's, or `jr2/task-<instance id>` (ADR-0054).
  *
  * The id is the run's seed Instance ID, which `RunHost.start` injects beside the door on the ROOT
  * machine's input ({@link HostInjectedInput}) and `jr2 status` reports. It is not door material —
@@ -298,8 +430,8 @@ function branchOf(input: TaskInput): string {
   const { instanceId } = input as TaskInput & Partial<HostInjectedInput>;
   if (!instanceId) {
     throw new Error(
-      "task: no `branch` on the door and no run id to derive one from — `jr2/task-<run id>` needs the " +
-        "id the host injects beside the door of the ROOT machine (ADR-0033), and this run of `task` " +
+      "task: no `branch` on the door and no Instance ID to derive one from — `jr2/task-<instance id>` needs " +
+        "the id the host injects beside the door of the ROOT machine (ADR-0033), and this run of `task` " +
         "was started by a parent Machine instead. Pass `branch` in the run input.",
     );
   }
@@ -321,6 +453,8 @@ function branchOf(input: TaskInput): string {
 function coderPrompt(context: BodyContext): string {
   const notes = context.notes ? `\n\nThe human reviewed your work and asks for changes:\n${context.notes}` : "";
   if (context.turns > 0) return notes.trimStart() || "Continue.";
+  const fault = memoryKill(context.reason);
+  const ended = fault ? `\n\nThe last attempt ended: ${fault}` : "";
   const { branch, repos } = context.workspace;
   const worktree = worktreeOf(context);
   const beside = Object.entries(repos)
@@ -328,13 +462,25 @@ function coderPrompt(context: BodyContext): string {
     .map(([slot, path]) => `\n- ${slot}: ${path}`)
     .join("");
   return (
-    `${context.prompt}${notes}\n\n` +
+    `${context.prompt}${ended}${notes}\n\n` +
     `Work in ${worktree.path}, on branch ${branch} — your tools are rooted there, so a relative ` +
     `path lands inside it. Commit what you do there, then call finish.` +
     (beside ? `\n\nAlso checked out beside it, for you to read:${beside}` : "")
   );
 }
 
+/**
+ * A memory kill's named line (ADR-0061, layer 5), or undefined for any other fault. The one fault
+ * the coder can act on — fewer workers, smaller steps — so the retry Turn carries it: the example
+ * for authors. The Orchestrator names it with the fixed prefix `memory limit` on the first line;
+ * the lines after it are the transport's words, not the coder's business. Any other fault (a
+ * provider down, a runaway rerolled) is the human's, and stays on the Gate alone.
+ */
+function memoryKill(reason: string | undefined): string | undefined {
+  const line = reason?.split("\n")[0]?.trim();
+  return line?.startsWith("memory limit") ? line : undefined;
+}
+
 /**
  * The checkout the coder edits: the FIRST slot the consumer wrote. This is `task`'s convention,
  * not the kit's — the handles keep the slots in declaration order and give none a meaning