@jr2/machines 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/machines",
-  "version": "0.4.1",
+  "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,14 +35,14 @@
   "peerDependencies": {
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.4.1"
+    "@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.4.1"
+    "@jr2/orchestrator": "0.5.1"
   },
   "files": [
     "src"

package/src/task.ts

@@ -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
@@ -141,6 +189,31 @@ type BodyContext = BodyInput & {
   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],
@@ -165,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",
@@ -172,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: {
@@ -257,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,
 });
 
@@ -271,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.
@@ -283,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 —
@@ -300,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.",
     );
   }