@jr2/machines 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rich Snapp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @jr2/machines
+
+The Machines the kit ships (ADR-0054). A fourth published package beside `@jr2/{cli,orchestrator,agent-protocol}`, on
+the same release train, exporting named Machines from its index.
+
+It ships **Machines**, never Workflows: a Workflow is the name an Instance registers a Machine under, and only the
+Instance's `workflows/` file can do that. So the consumer line is one file of your own —
+
+```ts
+// workflows/task.ts  →  the workflow "task"
+import { customize } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+export const machine = customize(task, {
+  repos: { target: { url: "https://github.com/you/repo.git" } },
+  agents: { coder: { model: "anthropic/claude-sonnet-4-6" } },
+});
+```
+
+## The Open parts
+
+A packaged Machine leaves the parts a package cannot honestly fill **Open** — a Repo Slot with no url, a slot map with
+no slots, an Agent with no model — because a package cannot know your repository or pay for your model. `jr2 up` walks
+the registered Machines, refuses an Open part nobody bound before anything is built, and prints the `customize` line
+that binds it.
+
+`task` has two: its Repo Slots, Open as a map, and the Agent `coder`. Both are bound above. The slot names are yours:
+`task` reads none of them. Their order is `task`'s convention (jr2 itself gives no slot a meaning): the first you write
+is where the coder works; any others are checked out beside it and the coder is told where they are, so a change that
+targets a library, or wants a handbook to hand, is one more line —
+
+```ts
+repos: {
+  target: { url: "https://github.com/you/repo.git" },
+  reference: { url: "https://github.com/you/lib.git", ref: "v3" },
+},
+```
+
+## Peer dependencies
+
+`@jr2/orchestrator`, `xstate` and `zod` are **peer** dependencies, never regular ones. Every part a Machine carries is
+keyed in maps `@jr2/orchestrator` holds and in xstate's own machinery; a second copy of either is a Machine whose Menus
+are empty and whose Gates accept nothing, with no error anywhere. Your own Machine package copies this shape.
+
+## Machines
+
+- **`task`** — one prompt, one Workspace, one human says done. The coder works in a Sandbox on `jr2/task-<run id>` (or
+  the branch you pass), `finish` parks the run at the `review` Gate, `request_changes` sends it back on the same
+  conversation, `approve` ends the run and tears the Workspace down. It does not push: while the run is parked you can
+  `exec` into the Sandbox, read the branch, and push it yourself with your own credential.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jr2/machines",
+  "version": "0.1.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,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snapwich/jr2.git",
+    "directory": "packages/machines"
+  },
+  "homepage": "https://github.com/snapwich/jr2#readme",
+  "bugs": {
+    "url": "https://github.com/snapwich/jr2/issues"
+  },
+  "keywords": [
+    "jr2",
+    "agents",
+    "agentic",
+    "xstate",
+    "kubernetes",
+    "workflow"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "peerDependencies": {
+    "xstate": "^5.18.0",
+    "zod": "^4.4.3",
+    "@jr2/orchestrator": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^5.6.0",
+    "xstate": "^5.18.0",
+    "zod": "^4.4.3",
+    "@jr2/orchestrator": "0.1.0"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// @jr2/machines — the Machines the kit ships (ADR-0054). A fourth published package beside
+// `@jr2/{cli,orchestrator,agent-protocol}` (ADR-0043), on the same release train, exporting named
+// 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:
+//
+//   import { customize } from "@jr2/orchestrator";
+//   import { task } from "@jr2/machines";
+//   export const machine = customize(task, { repos: { target: { url } }, agents: { coder: { model } } });
+//
+// PEER DEPENDENCIES, NO REGULAR ONES — the one fact about this package's manifest that a comment
+// has to carry, because `package.json` cannot hold one. Every part a Machine here carries is keyed
+// in maps `@jr2/orchestrator` holds (vocabulary.ts, parts.ts) and in `xstate`'s own `provide` and
+// machine tests. A SECOND copy of either — which a regular dependency installs the moment the
+// consumer's version skews from ours — is a Machine whose Menus are empty and whose Gates accept
+// nothing, with no error anywhere: the walk finds no vocabulary, the Gate resolves no names, and
+// the run parks on a surface that accepts nothing. Peer deps state the fact instead, and are the
+// shape a user's own Machine package copies. Regular deps pinned at the exact kit version were
+// 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
+// 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.
+
+export * from "./task.ts";

package/src/task.ts

@@ -0,0 +1,349 @@
+// `task` — the kit's first shipped Machine (ADR-0054): one prompt, one Workspace, one human says
+// 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
+// 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
+// Workflow, naming every slot. The ORDER is this Machine's convention, not the kit's (ADR-0051:
+// the handles keep declaration order and the kit reads nothing into it): the FIRST slot is the
+// one the coder works in, and any others are attached beside it for the coder to read (a library
+// the change targets, a handbook):
+//
+//   export const machine = customize(task, {
+//     repos: {
+//       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" } },
+//   });
+//
+// `jr2 up` walks the registered Machines and refuses either part unbound, printing exactly that
+// line (parts.ts, `customizeLine`); the Agent actor refuses to admit a Turn under an Open model as
+// the second fence. So the failure mode of forgetting is a converge that stops, never a run that
+// silently spends money on a model nobody chose.
+//
+// The Machine does NOT push (ADR-0005/0053): the Agent holds no credential, and the push url is
+// the caller's own spelling with the caller's own credential. The `review` Gate IS the inspection
+// window — while the run is parked the Sandbox is alive (parking is retention, ADR-0012), so a
+// human execs in, reads the branch, pushes it if the work should outlive the run, and only then
+// answers. Unpushed commits go with the pod, as ADR-0012 always said.
+
+import { assign } from "xstate";
+import { z } from "zod";
+import {
+  agent,
+  defineEvent,
+  jr2Setup,
+  open,
+  workspace,
+  type HostInjectedInput,
+  type ThinkingLevel,
+  type Workspaced,
+} 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.
+//
+// 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
+// repository". The repositories are the Workflow's `customize` line, not the run's input.
+
+/** Mirrors `ThinkingLevel` as a value, since the door needs a zod enum and the type is a type.
+ * `satisfies` is what keeps the two from drifting: a level added to the type fails here. */
+const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const satisfies readonly ThinkingLevel[];
+
+const door = z.object({
+  prompt: z.string().describe("What to do, in prose. The coder's first turn is this, framed with the worktree."),
+  branch: z
+    .string()
+    .optional()
+    .describe("The branch to cut and commit on. Default: jr2/task-<run id>, so concurrent runs never collide."),
+  // 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.
+  model: z.string().optional().describe('Override the coder\'s model for this run only, as "<provider>/<modelId>".'),
+  thinkingLevel: z
+    .enum(THINKING_LEVELS)
+    .optional()
+    .describe("Override the coder's reasoning effort for this run only."),
+});
+
+/** What a caller sends. */
+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" };
+
+// ---------------------------------------------------------------------------------------------
+// Vocabulary (ADR-0011/0015), scoped to this Machine alone: the agent event becomes the coder
+// state's Menu, the two external ones become the Gate's accepted set.
+
+const finish = defineEvent({
+  name: "finish",
+  description: "End the turn: the work is committed on the branch and ready for a human to read.",
+  audience: "agent",
+  input: z.object({ summary: z.string().describe("What you did, in a few sentences.") }),
+});
+
+const approve = defineEvent({
+  name: "approve",
+  description: "Accept the work. The run finishes and the Workspace — and anything unpushed in it — is torn down.",
+  audience: "external",
+  input: z.object({}),
+});
+
+const requestChanges = defineEvent({
+  name: "request_changes",
+  description: "Send the work back to the coder with notes. The coder continues the same conversation.",
+  audience: "external",
+  input: z.object({ notes: z.string().describe("What to change, in prose.") }),
+});
+
+// ---------------------------------------------------------------------------------------------
+// The body. It receives the door PLUS the handles `workspace()` injects and, because the wrapper is
+// this Machine's ROOT, the field the host injects beside the door (`instanceId`, ADR-0033).
+//
+// `Workspaced<…, string>` — the body names NO slot (ADR-0051): it works in the FIRST checkout the
+// handles carry, which is whatever the consumer wrote first (`worktreeOf`), and frames every
+// other one. That is what lets the wrapper leave the slot map Open; a body that named
+// `repos.target` could not.
+
+type BodyInput = Workspaced<TaskInput & HostInjectedInput, string>;
+
+type BodyContext = BodyInput & {
+  /**
+   * Which conversation the coder's Turns ride. `request_changes` continues the SAME conversation —
+   * one human steering one Agent wants the Agent to remember what it did (ADR-0054) — but a
+   * terminal `agent.fault` means jr2 already rerolled that conversation and gave up on it
+   * (ADR-0035), so there is nothing left to continue. Bumping the generation folds into the
+   * conversation's disambiguator, and the next Turn starts a fresh conversation instead of
+   * addressing a dead one.
+   */
+  generation: number;
+  /** Turns COMPLETED on the current conversation. Zero means the next 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. */
+  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`. */
+  reason?: string;
+  /** The human's last notes, which are the next Turn's prompt. */
+  notes?: string;
+};
+
+/** The conversation pin (ADR-0016): a workflow-chosen name, so every `working` Turn of a run
+ * derives one deterministic instance id and the coder's context survives the round trip through
+ * the Gate. The name is the slot key, because that is what the conversation is about. */
+const CONVERSATION = "coder";
+
+export const body = jr2Setup({
+  types: {} as { context: BodyContext; input: BodyInput; output: TaskOutput },
+  events: [finish, approve, requestChanges],
+  // The Agent rides the Machine (ADR-0049): the slot key is its name on the Harness wire, in the
+  // minted iid, and in the `customize` line that binds its model.
+  actors: {
+    coder: agent({
+      // OPEN (ADR-0054). Not a default — a stock model would have this package pick a vendor and
+      // spend a user's money on a choice they never read. The consumer binds it with `customize`.
+      model: open,
+      description: "Works one task through to committed work in its own Workspace.",
+      // Explicit, though it is also the default (ADR-0028): this Agent writes, and the ADR-0031
+      // placement scan reads this field off the declaration to decide where its Turns run.
+      workspace: "write",
+      instructions: `You are a software engineer working alone on one task, in a container of your own.
+
+- Edit only inside the worktree the conversation names as yours. Nothing you write outside it
+  survives. Any other checkout it names is there for you to read.
+- Commit your work on the named branch. You cannot push, and you do not need to: a human reads the
+  branch in this container before the run ends.
+- Read before you write, and prefer the smallest change that does the task.
+- 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.`,
+    }),
+  },
+}).createMachine({
+  id: "task",
+  context: ({ input }) => ({ ...input, generation: 0, turns: 0 }),
+  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.
+  on: { "workspace.lost": { target: ".lost" } },
+
+  states: {
+    working: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({
+          prompt: coderPrompt(context),
+          // One conversation per generation (see `BodyContext.generation`). `scope` is the
+          // disambiguator the pin already has for exactly this: it rides the derived iid, so a
+          // post-fault Turn addresses a new conversation instead of a dead one.
+          conversation: CONVERSATION,
+          scope: `g${context.generation}`,
+          // This run's Dials, if the caller set them (ADR-0018/0054) — passed straight through,
+          // layered over the bound definition when the Submission starts.
+          ...(context.model !== undefined ? { model: context.model } : {}),
+          ...(context.thinkingLevel !== undefined ? { thinkingLevel: context.thinkingLevel } : {}),
+        }),
+      },
+      on: {
+        finish: {
+          target: "review",
+          actions: assign({
+            summary: ({ event }) => event.summary,
+            reason: undefined,
+            notes: undefined,
+            turns: ({ context }) => context.turns + 1,
+          }),
+        },
+        // ADR-0016's ONE terminal telemetry, ROUTED: jr2 has already retried, nudged and rerolled
+        // (ADR-0027/0035), so this is the end of that conversation, not of the run. Park at the
+        // same Gate — the Workspace is still alive and the work so far is still on the branch —
+        // and start the next Turn on a fresh conversation.
+        "agent.fault": {
+          target: "review",
+          actions: assign({
+            reason: ({ event }) => event.reason,
+            summary: undefined,
+            generation: ({ context }) => context.generation + 1,
+            turns: 0,
+          }),
+        },
+      },
+    },
+
+    // The one park, and the whole point of the Machine: a human reads the branch and decides. The
+    // Gate id derives from the actor path (leaf = this state's key), so it stays fan-out-safe if
+    // this Machine is ever composed under a Pool; its accepted set derives from this state's
+    // external transitions; `meta` is what `jr2 status`, the Console's drawer, and a webhook
+    // translator read (ADR-0011/0015).
+    review: {
+      invoke: {
+        src: "gate",
+        input: ({ context }) => ({
+          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
+            // an `exec` needs, and what a push would name.
+            branch: context.workspace.branch,
+            worktree: worktreeOf(context).path,
+          },
+        }),
+      },
+      on: {
+        approve: { target: "done" },
+        // No round cap (ADR-0054): the human is the cap. They see every Turn's result before the
+        // 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 }),
+        },
+      },
+    },
+
+    // Reaching a final state is what tears the Workspace down (ADR-0012): approve means done with
+    // the pod, and anything still unpushed in it goes too.
+    done: {
+      type: "final",
+      output: ({ context }): TaskOutput => ({ outcome: "approved", branch: context.workspace.branch }),
+    },
+    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.
+  output: ({ event }) => (event as { output?: TaskOutput }).output as TaskOutput,
+});
+
+// ---------------------------------------------------------------------------------------------
+// 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.
+
+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.
+  // The package names none, because the body reads none — the first slot the consumer writes is
+  // the one the coder edits (this Machine's convention, `worktreeOf`), and the rest are checkouts
+  // 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 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 —
+ * no caller sends it and it is never served as JSON Schema (ADR-0033) — so the schema does not
+ * 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.
+ */
+function branchOf(input: TaskInput): string {
+  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}`;
+}
+
+/**
+ * The turn's framing. The FIRST Turn of a conversation carries the whole task and the geography,
+ * because the conversation holds nothing yet; every Turn after it carries the human's notes alone,
+ * because the coder remembers the rest (ADR-0054's continued conversation). A post-fault Turn is a
+ * first Turn again — that is what `turns` counts.
+ *
+ * The geography is every slot the handles carry (ADR-0051): the first is where the work goes, and
+ * each other checkout is named by the consumer's own word for it, at the path the attach put it —
+ * the only way the coder can learn what is beside it, since the package never knew.
+ */
+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 { branch, repos } = context.workspace;
+  const worktree = worktreeOf(context);
+  const beside = Object.entries(repos)
+    .filter(([slot]) => slot !== worktree.slot)
+    .map(([slot, path]) => `\n- ${slot}: ${path}`)
+    .join("");
+  return (
+    `${context.prompt}${notes}\n\n` +
+    `Work in ${worktree.path}, on branch ${branch}. Commit what you do there, then call finish.` +
+    (beside ? `\n\nAlso checked out beside it, for you to read:${beside}` : "")
+  );
+}
+
+/**
+ * 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
+ * (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 };
+}