@jr2/machines 0.4.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/machines",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "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.6.0"
   },
   "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.6.0"
   },
   "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,18 +36,22 @@ import { z } from "zod";
 import {
   agent,
   defineEvent,
+  fail,
   jr2Setup,
   open,
   workspace,
+  worktree,
+  branchName,
   type HostInjectedInput,
   type ThinkingLevel,
   type Workspaced,
+  type WorktreePath,
 } from "@jr2/orchestrator";
 
 // ---------------------------------------------------------------------------------------------
 // The door (ADR-0033): what a caller sends to start a run, declared on the `workspace()` that is
 // this Machine's root. One source of truth — the types below derive from it, the Console generates
-// its start form from it, and it types the spec mapper.
+// its start form from it, and it types the body's input.
 //
 // No `repo` field, deliberately (ADR-0054): a packaged door cannot enumerate the Instance's
 // repositories, and "a Workflow is a name" reads best when the name means "a prompt against THIS
@@ -65,27 +69,73 @@ 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."),
-  branch: z
-    .string()
+  /** 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: branchName
     .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
@@ -124,6 +174,9 @@ const requestChanges = defineEvent({
 type BodyInput = Workspaced<TaskInput & HostInjectedInput, string>;
 
 type BodyContext = BodyInput & {
+  /** The branch of this run: the door's, or `jr2/task-<instance id>`. Undefined only under a parent
+   * Machine with no `branch` in its input. */
+  branch: string | undefined;
   /** Turns COMPLETED on the conversation the next Turn will land on. Zero means that Turn is its
    * first, so the prompt has to carry the whole task and the worktree framing again — which is
    * exactly what a post-fault Turn needs and a continued one does not. It counts for the PROMPT
@@ -141,6 +194,30 @@ 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" } },
+ * });
+ *
+ * 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,25 +242,43 @@ 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.`,
     }),
+    cut: worktree(),
+    // The Failure (ADR-0073): the `lost` state invokes it, and the run ends `failed`.
+    fail: fail(),
   },
 }).createMachine({
   id: "task",
-  context: ({ input }) => ({ ...input, turns: 0 }),
-  initial: "working",
+  context: ({ input }) => ({ ...input, branch: branchOf(input), turns: 0 }),
+  initial: "starting",
 
   // 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: {
+    // A bad name is the door's (`branchName`): it costs no pod, under a parent also, because
+    // `place` holds an invocation's input to the wrapper's door. A name that NO ONE gave cannot be a
+    // door rule: the host adds `instanceId` after the door. So this one line stays, and it costs a
+    // pod: a Failure, and not a defect: under a pool(), one item fails, and the run goes on.
+    starting: {
+      always: [{ guard: ({ context }) => context.branch === undefined, target: "noBranch" }, { target: "cutting" }],
+    },
+    // The first slot is the coder's. A slot after it needs no cut: `<slot>/default` is on its base.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: worktreeOf(context).path, branch: context.branch! }),
+        onDone: [{ guard: ({ event }) => event.output.outcome === "ready", target: "working" }, { target: "notCut" }],
+      },
+    },
     working: {
       invoke: {
         src: "coder",
         input: ({ context }) => ({
           // This Turn's FRAME (ADR-0057): what it is about, and where it works. The `cwd` is
-          // stated rather than left to the single-slot default, because "the first slot is the one
-          // the coder edits" is this Machine's convention (`worktreeOf`) and a convention is
-          // stated — a consumer who binds a second slot must not change where the coder works.
+          // required under Repo Slots (ADR-0075): "the first slot is the one the coder edits" is this
+          // Machine's convention (`worktreeOf`), and a consumer who binds a second slot must not
+          // change where the coder works.
           prompt: coderPrompt(context),
           cwd: worktreeOf(context).path,
           // One human steering one Agent wants the Agent to remember what it did (ADR-0054), so
@@ -235,9 +330,9 @@ export const body = jr2Setup({
           meta: {
             ...(context.summary !== undefined ? { summary: context.summary } : {}),
             ...(context.reason !== undefined ? { reason: context.reason } : {}),
-            // The branch the attach actually made and the worktree the coder committed in — what
+            // The branch the cut made and the Worktree the coder committed in — what
             // an `exec` needs, and what a push would name.
-            branch: context.workspace.branch,
+            branch: context.branch!,
             worktree: worktreeOf(context).path,
           },
         }),
@@ -257,13 +352,30 @@ 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.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.
+    noBranch: {
+      invoke: {
+        src: "fail",
+        input: { reason: "task: no `branch` on the door and no Instance ID to derive one from" },
+      },
+    },
+    notCut: { invoke: { src: "fail", input: { reason: "task: the Worktree was not cut" } } },
+    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 +383,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.
@@ -279,11 +436,10 @@ export const task = workspace(body, {
   // the coder is told about and may read. A named
   // `target: open` would have said "one repository", which is not what the body knows.
   repos: open,
-  spec: ({ input }) => ({ branch: branchOf(input) }),
 });
 
 /**
- * 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 —
@@ -291,21 +447,12 @@ export const task = workspace(body, {
  * carry it and reading it takes a cast that says why.
  *
  * A `task` composed UNDER another Machine is fed by its parent rather than by the host, so the
- * field is absent there and there is no per-run id to name a branch after. Refuse, loudly and
- * before any pod exists: the alternative is a constant branch name, which two concurrent workers
- * would both cut and neither would own.
+ * field is absent there and there is no per-run id to name a branch after: undefined.
  */
-function branchOf(input: TaskInput): string {
+function branchOf(input: TaskInput): string | undefined {
   if (input.branch) return input.branch;
   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` " +
-        "was started by a parent Machine instead. Pass `branch` in the run input.",
-    );
-  }
-  return `jr2/task-${instanceId}`;
+  return instanceId ? `jr2/task-${instanceId}` : undefined;
 }
 
 /**
@@ -325,11 +472,12 @@ function coderPrompt(context: BodyContext): string {
   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 { repos } = context.workspace;
+  const { branch } = context;
   const worktree = worktreeOf(context);
   const beside = Object.entries(repos)
     .filter(([slot]) => slot !== worktree.slot)
-    .map(([slot, path]) => `\n- ${slot}: ${path}`)
+    .map(([slot, path]) => `\n- ${slot}: ${path}/default`)
     .join("");
   return (
     `${context.prompt}${ended}${notes}\n\n` +
@@ -357,7 +505,7 @@ function memoryKill(reason: string | undefined): string | undefined {
  * (ADR-0051) — so it is decided here, in one place, and stated on the line that registers the
  * Machine. The wrapper refuses a map with no slot, so the first always exists.
  */
-function worktreeOf(context: Pick<BodyContext, "workspace">): { slot: string; path: string } {
-  const [slot, path] = Object.entries(context.workspace.repos)[0]!;
-  return { slot, path };
+function worktreeOf(context: Pick<BodyContext, "workspace">): { slot: string; path: WorktreePath<string> } {
+  const [slot, folder] = Object.entries(context.workspace.repos)[0]!;
+  return { slot, path: `${folder}/task` };
 }