@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/machines.md

@@ -0,0 +1,189 @@
+---
+title: "@jr2/machines"
+description: "The Machines that @jr2/machines ships: their input, their output, and their Open parts."
+---
+
+# @jr2/machines
+
+`@jr2/machines` ships Machines, not Workflows. A Machine becomes a Workflow when a file in the Instance's `workflows/` folder exports it, with each [Open](glossary.md#open) part bound by [`customize`](authoring-surface/customize.md). Install it beside `@jr2/orchestrator`, at the same version: it is a peer of the kit, never a copy of it.
+
+## Contents
+
+- [`TaskInput`](#type-taskinput), [`TaskOutput`](#type-taskoutput), [`body`](#body), [`task`](#task)
+
+<a id="type-taskinput"></a>
+
+### `TaskInput`
+
+Type, in `@jr2/machines/src/task.ts`.
+
+```ts
+type TaskInput = {
+  prompt: string;
+  branch?: string | undefined;
+  model?: string | undefined;
+  thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | undefined;
+};
+```
+
+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.
+
+**Fields**
+
+- `prompt`: `string`
+
+  What to do, in prose. Required. The coder's first Turn is this prompt, with the Worktree it
+  works in.
+- `branch` (optional): `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.
+- `model` (optional): `string`
+
+  The coder's model for this run only, as `"<provider>/<modelId>"`. Default: the model of the
+  coder Agent.
+- `thinkingLevel` (optional): `"off" | "minimal" | "low" | "medium" | "high" | "xhigh"`
+
+  The coder's thinking level for this run only: `off`, `minimal`, `low`, `medium`, `high` or
+  `xhigh`. Default: the thinking level of the coder Agent.
+
+**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",
+};
+```
+
+<a id="type-taskoutput"></a>
+
+### `TaskOutput`
+
+Type, in `@jr2/machines/src/task.ts`.
+
+```ts
+type TaskOutput = { branch: string };
+```
+
+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](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)).
+
+**Fields**
+
+- `branch`: `string`
+
+**Example**
+
+```ts
+import type { TaskOutput } from "@jr2/machines";
+
+export function describe(output: TaskOutput): string {
+  return `approved on ${output.branch}`;
+}
+```
+
+<a id="body"></a>
+
+### `body`
+
+Constant, in `@jr2/machines/src/task.ts`.
+
+```ts
+const body: StateMachine<…>
+```
+
+Type: `StateMachine`, from `xstate`.
+
+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 also**
+
+- [Workspaces](../concepts/workspaces.md)
+
+<a id="task"></a>
+
+### `task`
+
+Constant, in `@jr2/machines/src/task.ts`.
+
+```ts
+const task: WorkspaceMachine<…>
+```
+
+Type: [`WorkspaceMachine`](authoring-surface/type-workspacemachine.md).
+
+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 also**
+
+- [An Agent in a Sandbox](../get-started/an-agent-in-a-sandbox.md)
+- [Bind a shipped Machine's Open parts](../guides/bind-open-parts.md)
+- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)

package/docs/reference/mechanism-events.md

@@ -0,0 +1,72 @@
+---
+title: Mechanism events
+description: The events that jr2 itself sends into every jr2Setup Machine, and their payloads.
+---
+
+# Mechanism events
+
+jr2's own mechanism delivers these events into every Machine that `jr2Setup` makes, beside the workflow events its `defineEvent` defs declare. Handle one with an `on` key, as any event: `on: { "agent.fault": "failed" }`. A Mechanism event's name has a dot, and a workflow event's name cannot, so the two never collide. The Machine's event type, `WorkflowEvent`, holds them already.
+
+Each Mechanism event must have a route. `jr2 check` and `jr2 up` refuse a state that invokes an Agent, or an Open body that lends an Agent or allows a model, when that state and each state above it have no `agent.fault` route, and `workspace()` refuses a body with a state that is not final and has no `workspace.lost` route on itself or on a state above. One route on the root satisfies each rule. A route with actions only is a route. When the event comes and no transition takes it, because the guard of its route is false, the run ends `error`, and its fault names the event, the state and the reason. In a [Chart](../concepts/charts.md), the `agent.fault` route is optional: when no transition of the Chart takes it, the Open body sends it, unchanged, to the Machine that invoked the body, and that Machine's own route takes it.
+
+To end the run as a Failure when a Mechanism event comes, route it to a state that invokes [`fail`](authoring-surface/fail.md): `lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } }`. The run then ends `failed`, not `done`, because a final state means that the work succeeded.
+
+<a id="type-mechanismevent"></a>`MechanismEvent` is one of these events: [`agent.fault`](#agent-fault), [`workspace.lost`](#workspace-lost).
+
+<a id="agent-fault"></a>
+
+## `agent.fault`
+
+- Type: `FaultTelemetry`
+- Sent by: The Agent slot (`agent()`) that the state invoked, to the Machine that invoked it.
+
+```ts
+type FaultTelemetry = {
+  type: "agent.fault";
+  instanceId: string;
+  reason: string;
+};
+```
+
+jr2 sends `agent.fault` to the Machine when an Agent's Turn cannot go on: the Harness failed
+the Turn, or the Agent ended its Turns with no pick after every nudge. The Machine decides what
+to do next. Route it in the state that invokes the Agent, or in a state above it, with
+`on: { "agent.fault": … }`; one route on the root is a route for each state. `jr2 check` and
+`jr2 up` refuse a state that invokes an Agent, or an Open body that can run one, with no route for
+it. When the event comes and no transition takes it (the route's guard is false), the run ends
+`error`, with the event, the state and the reason in its fault. In a Chart the route is optional:
+when no transition of the Chart takes the event, the Open body sends it, unchanged, to the Machine
+that invoked the body, whose route takes it.
+
+**Payload**
+
+- `instanceId`, `string`: The Instance ID of the Agent's conversation that failed: the same id on each Turn that continues it.
+- `reason`, `string`: Why the Turn failed, as text for a person or a log: the Harness's error, or that the Agent ended its Turns without a pick after every nudge. Route on the event, not on this text.
+
+<a id="workspace-lost"></a>
+
+## `workspace.lost`
+
+- Type: `WorkspaceLost`
+- Sent by: `workspace()`, to its body Machine, when the Workspace's Sandbox is gone.
+
+```ts
+type WorkspaceLost = {
+  type: "workspace.lost";
+  reason?: string;
+  message?: string;
+};
+```
+
+jr2 sends `workspace.lost` to the body of a `workspace()` when its Sandbox is gone: its pod was
+evicted or deleted, or its node went. jr2 does not make the Sandbox again, and the commits that
+were not pushed go with it. The body decides what to do next: route the event with
+`on: { "workspace.lost": … }`, usually once, on the body's root. `workspace()` refuses a body
+with a state that is not final and has no route for it on itself or on a state above. When the
+event comes and no transition takes it (the route's guard is false), the run ends `error`, with
+the event, the state and the reason in its fault.
+
+**Payload**
+
+- `reason` (optional), `string`: Why the Sandbox is gone, for a person or a log: the pod's reason (`Evicted`, `NodeShutdown`), the operator's (`PodDeleted`, `NodeLost`), or `Deleted`. A body can act without it.
+- `message` (optional), `string`: More text about the loss, when jr2 has it.

package/docs/why.md

@@ -0,0 +1,207 @@
+---
+title: Why jr2
+description: The parts of jr2, the problems of agentic workflows that each part solves, and one run through them.
+---
+
+# Why jr2
+
+jr2 runs an agentic workflow as a [Machine](reference/glossary.md#machine): a graph of states that you write. In a
+state, an [Agent](reference/glossary.md#agent) or an [Effect](reference/glossary.md#effect) does the work, or a
+[Gate](reference/glossary.md#gate) waits for an answer. The Machine decides which state comes next. The diagram shows
+the parts of jr2, from you to the world outside your cluster.
+
+**The parts of jr2, from you to the world outside your cluster**
+
+- **You**: start runs, and answer them
+  - jr2 CLI
+  - Console
+  - your own app
+- ↓ you start a run · ↑ approval → You: a Gate asks you · ↓ You → approval: you answer
+- **your cluster**: `jr2 up` sets it up
+  - **Orchestrator**: runs your Machine, and keeps each run
+    - ● → code → **review** → approval → ◉ done
+      - review → approval: `approved`
+      - review → code: `changes`
+      - approval → code: `changes`
+  - ↓ `review` gives the reviewer a Turn and its Menu · ↑ the reviewer picks `approved`
+  - **Sandbox**: one pod for each Workspace
+    - **Harness**: runs each Turn, with a shell
+      - **coder** (Agent): edits and commits
+      - **reviewer** (Agent): its Menu: `approved` `changes`
+      - **Worktree**: your code
+    - **Custodian**: keys that the Agents can use but not read, such as the model key
+    - **Effector**: keys that only your Effects use, such as a git credential
+- ↓ Custodian → Outside · Effector → Outside
+- **Outside**: what the work uses
+  - model provider
+  - your APIs
+  - git host
+
+Each section below gives one problem of agentic workflows, and the part of the diagram that solves it. The sections go
+from the top of the diagram to the bottom.
+
+## Headless
+
+A workflow must connect to the systems that you use, such as a code review, a chat or a CI job. One user interface
+cannot be the right one for each of them.
+
+The You band of the diagram holds the clients of jr2. The [Orchestrator](reference/glossary.md#orchestrator) is an HTTP
+API. The [jr2 CLI](reference/glossary.md#jr2-cli) and the [Console](reference/glossary.md#console) are its clients, and
+your own app, such as a webhook, can be one too. For example, a client can start a run with
+[`POST /workflows/:name/runs`](reference/http-api.md#post-workflows-name-runs). In the diagram, a
+[Gate](reference/glossary.md#gate) in the state `approval` asks you, and you answer from any of these clients, with
+[`POST /runs/:runId/gates/:gate/events`](reference/http-api.md#post-runs-runid-gates-gate-events).
+
+Read [Architecture](concepts/architecture.md) and [Gates](concepts/gates.md).
+
+## Determinism
+
+A workflow must do the steps that it sets, in the order that it sets. But a model does not do the same thing two times.
+When the steps of a workflow are text in a prompt, the model can skip a step or change the order. "You must" and "never"
+are requests to the model, not rules that it must obey. You can review the code that an agentic workflow makes, but you
+cannot easily review how it made that code.
+
+In jr2, a workflow is a Machine: an [xstate](https://xstate.js.org) state machine in TypeScript. The Orchestrator band
+of the diagram holds an example Machine, with the states `code`, `review` and `approval`, and the final state `done`.
+Its states and its transitions are a graph that you can read before a run starts. The Console draws that graph, and
+while a run runs, it shows the state that the run is in. A Machine can have loops: in the diagram, `changes` sends the
+run back to `code`.
+
+An Agent does not move the Machine itself. A [Turn](reference/glossary.md#turn) is one piece of work for one Agent. The
+state that the run is in gives the Agent a prompt and a [Menu](reference/glossary.md#menu): the events that go out of
+that state. In the diagram, the run is in `review`, so the Menu of the reviewer is `approved` and `changes`. The Agent
+ends its Turn with one pick from its Menu, and the Machine refuses a pick that is not one of its
+[Allowed picks](reference/glossary.md#allowed-picks) now. Thus the model makes the decision in each state, and the
+Machine sets the transition that each decision causes. You review how the work happens, not only the code that comes out
+of it. The model is not deterministic, but the Machine is: in one state, one pick always causes the same transition.
+
+The Agent can also decide the order of the work. A pick whose target is inside the Agent's state does not end the Turn.
+The Machine runs the work of the pick, such as an Effect or a Gate, and answers the pick with the result. A
+[mode](reference/glossary.md#mode) or a guard sets which picks the Agent can make next. Thus the Agent decides when each
+step runs, and the Machine decides what each step does. An Agent can also write a [Chart](reference/glossary.md#chart):
+a Machine as data, which jr2 checks before it runs.
+
+Read [Machines and Workflows](concepts/machines-and-workflows.md),
+[The Menu](concepts/the-menu.md#keep-the-turn-or-end-it) and [Charts](concepts/charts.md).
+
+## Composition
+
+An Agent does one thing well. When you give it many things at the same time, it loses its focus. The infrastructure of a
+workflow, such as a Sandbox or a set of work items, also must not get into the task of the Agent.
+
+The diagram shows one Machine, but the infrastructure around it is xstate too. A
+[Workspace](reference/glossary.md#workspace) wraps a body Machine that does not know about the Sandbox. A
+[Pool](reference/glossary.md#pool) runs one worker Machine for each item that a [Source](reference/glossary.md#source)
+gives. A Gate is an actor that a state invokes to wait for an outside input, such as the Gate in `approval`. Each state
+sets the [Frame](reference/glossary.md#frame) of one Turn, so an Agent does one thing at a time.
+
+A Machine can invoke a different Machine. A Machine can also leave a part [Open](reference/glossary.md#open), such as
+the URL of a Repo or the model of an Agent. You bind that part with
+[`customize()`](reference/authoring-surface/customize.md). Thus a Machine can come from an npm package, such as the
+[`task`](reference/machines.md#task) Machine in `@jr2/machines`.
+
+Read [Composition](concepts/composition.md) and [Pools and Sources](concepts/pools-and-sources.md).
+
+## Isolation
+
+A filesystem sandbox is not isolation. Agents on one computer share its ports, its processes and its credentials. Two
+Agents can need the same port, or the same file in your home folder. An Agent can also leave a process or a server that
+runs after the work stops.
+
+The Sandbox band of the diagram is one pod. An Agent that works on a [Repo](reference/glossary.md#repo) works in a
+[Sandbox](reference/glossary.md#sandbox): a pod with its own filesystem, network and processes. There is one Sandbox for
+each Workspace, and the Agents of one Workspace share it. The [Harness](reference/glossary.md#harness) runs each Turn.
+It talks to the model, and it runs the tools of the Agent. The Agent can run each command in the Harness container. An
+Agent that needs only its Menu has no Sandbox. Its Turns run on the
+[Instance Harness](reference/glossary.md#instance-harness).
+
+The Harness runs each command of an Agent confined with Landlock, so the command cannot read a credential, and it cannot
+send a pick for a different Agent. jr2 keeps each credential in one of the two containers beside the Harness:
+
+- The [Custodian](reference/glossary.md#custodian) holds each [Held secret](reference/glossary.md#held-secret): a key
+  that the Agents can use, but cannot read. The Harness holds only a [Stand-in](reference/glossary.md#stand-in) for it.
+  The Custodian puts the real key in place of the Stand-in, in each request to the host of that key. A Stand-in has no
+  value outside its pod. The model key is a Held secret. A token for an API that the Agents call can be one too.
+- The [Effector](reference/glossary.md#effector) holds each [Effect secret](reference/glossary.md#effect-secret): a key
+  that only an [Effect](reference/glossary.md#effect) of your Machine uses, such as a push or a call to an API. The
+  Agents cannot use it.
+
+Put a key in the Custodian when the Agents can use it as they decide. Put it in the Effector when only your Machine
+decides when to use it. One key can be in both containers.
+
+When the Workspace ends, its Sandbox ends too. When a [Lease](reference/glossary.md#lease) lapses, the operator removes
+what the Agents left behind.
+
+Read [Workspaces](concepts/workspaces.md) and [Secrets and trust](concepts/secrets-and-trust.md).
+
+## Model agnostic
+
+A workflow must not depend on one model or one provider. You can change the model of one Agent, and keep the Machine.
+
+In the diagram, the line from the Custodian goes to a model provider outside your cluster. jr2 has one Harness, and it
+is jr2's own. An Agent is a model and its instructions. The model is a name such as `<provider>/<model>`. The provider
+is one from the model catalog of the Harness, or an endpoint that you run and set in
+[`harness.provider`](reference/config.md#harness-provider). The same Harness runs the Turns of each Agent, with each
+provider. A state can set the model of one Turn.
+
+Read [Agents and Turns](concepts/agents-and-turns.md).
+
+## Distribution
+
+One computer has a limit. One build can use all of its CPU, and the other Agents then wait. A run on a laptop also stops
+when the laptop stops.
+
+In the diagram, the bracket is your cluster, and the compute is in it. For each Agent, the Orchestrator holds only an
+[Actor](reference/glossary.md#actor): a local handle. The Harness that runs the Turns of the Agent runs where the
+cluster puts it. A Sandbox can go on each node that can run an ordinary pod. The Orchestrator keeps a snapshot of each
+run on its volume, so a run continues after a restart of the Orchestrator. On a shared cluster, a run continues when
+your computer is off.
+
+Read [Architecture](concepts/architecture.md).
+
+## One converging command
+
+A workflow that runs on a laptop must also run on a shared cluster, without a second set of steps.
+
+The bracket of the diagram has the label `jr2 up`. [`jr2 up`](reference/cli.md#up) converges an
+[Instance](reference/glossary.md#instance) folder into the cluster of the current kubectl context. It builds the images
+that the folder needs, and it puts the Orchestrator and the operator in the cluster. It does not start a Sandbox: during
+a run, the operator makes one Sandbox for each Workspace. The same folder converges into kind on a laptop or into a
+shared cluster. You select the cluster with the kubectl context. A shared cluster also needs a container registry, which
+`.env` gives to [`registry`](reference/config.md#registry). You can run `jr2 up` again at any time.
+
+Read [Converge](concepts/converge.md).
+
+## A typed Instance
+
+An error in a workflow or in its config can show only when a run gets to it. A run can take many minutes to get there.
+
+In jr2, a Machine names its Agents, its [Repo Slots](reference/glossary.md#repo-slot) and the Machines that it invokes,
+and TypeScript checks each name. `jr2.config.ts` uses [`defineConfig()`](reference/authoring-surface/defineconfig.md),
+so TypeScript checks the config too. `jr2 up` runs the typecheck first. When the typecheck fails, `jr2 up` builds
+nothing and changes nothing on the cluster. Next, it refuses an Open part that no `customize()` binds. Thus you find
+these errors before a run starts.
+
+Read [Converge](concepts/converge.md) and [Machines and Workflows](concepts/machines-and-workflows.md).
+
+## One run
+
+These steps follow one run of the example Machine in the diagram. You write a Machine like it in TypeScript, or your
+[Assistant](reference/glossary.md#assistant) writes it for you.
+
+1. **You start a run.** You run `jr2 run feature`, with the ticket as the input of the run. The Machine starts in its
+   first state, `code`.
+2. **The coder works in a Sandbox.** The state `code` is in a Workspace, so jr2 makes a Sandbox for it. The Sandbox
+   holds a clone of your Repo, and the Machine cuts a [Worktree](reference/glossary.md#worktree) on the branch of the
+   run. The coder edits the files, runs the tests and commits. Then it picks `finish`, and the Machine moves to
+   `review`.
+3. **The reviewer gets a Turn.** The state `review` gives the reviewer a prompt and its Menu: `approved` and `changes`.
+   The reviewer reads the change in the same Sandbox.
+4. **The reviewer picks.** If it picks `approved`, the Machine moves to `approval`. If it picks `changes`, the Machine
+   goes back to `code`, and the coder continues its work.
+5. **The run waits for you.** In `approval`, a Gate holds the run until you answer. You approve the work, or you ask for
+   changes. You answer in the Console, with `jr2 send`, or from your own app.
+6. **The run ends.** The Machine gets to `done`. The Workspace ends, and its Sandbox pod stops with it.
+
+The [`task`](reference/machines.md#task) Machine in `@jr2/machines` is a smaller Machine of this kind: a coder in a
+Sandbox, and a Gate that you answer. The [Get started](get-started/install.md) tutorial runs it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "The jr2 Orchestrator: xstate runtime, HTTP API and Console, and the kit pieces a Workflow imports.",
   "license": "MIT",
   "private": false,
@@ -30,6 +30,7 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./internal": "./src/internal.ts",
     "./tsconfig.instance.json": "./tsconfig.instance.json"
   },
   "types": "./src/index.ts",
@@ -41,15 +42,16 @@
     "ts-blank-space": "^0.9.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/agent-protocol": "0.4.1"
+    "@jr2/agent-protocol": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.4.1"
+    "@jr2/harness": "0.6.0"
   },
   "files": [
     "bin",
     "console",
+    "docs",
     "src",
     "tsconfig.instance.json"
   ],