@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/authoring-surface/agent.md

@@ -0,0 +1,151 @@
+---
+title: agent
+description: "Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it."
+---
+
+# `agent`
+
+Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+
+```ts
+function agent<
+  const D extends AgentDeclaration,
+>(
+  declaration: D,
+): AgentLogic & (D extends { workspace: "none" } ? { readonly definition: { readonly workspace: "none" } } : unknown)
+```
+
+Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it. Put it
+under `actors` in `jr2Setup`, and invoke it by its key: `actors: { coder: agent(…) }`, then
+`invoke: { src: "coder", input: { prompt } }`. The key is the Agent's name.
+
+The invoke's `input` is the Turn: `prompt` (required), `cwd`, `model`, `thinkingLevel` and
+`continue`. `cwd` is the absolute directory where the Working tools work. Under Repo Slots it
+is required: a Worktree that a cut made, `<slot>/default` to read, or `/work`. An Agent with
+`workspace: "none"`, and a Workspace with no Repo Slot, need no `cwd`. `continue: true` continues the Agent's conversation
+in this Machine. Absent, each Turn starts a new conversation. `continue` is the literal `true`,
+not a `boolean`. A Turn can join only a conversation that an earlier Turn started with
+`continue: true`. Thus in a retry loop, put `continue: true` on each Turn, also on the first, so
+that attempt 2 sees attempt 1. Then a Runaway on the first Turn gets no second start, because a
+continued Turn gets none ([ADR-0035](../decisions/0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md)). Spread it only when a state must start a clean conversation
+on some Turns only: `...(context.clean ? {} : { continue: true as const })`. A clean Turn does not
+start the continued conversation again: the next Turn with `continue: true` joins the earlier
+one. The Turn ends when the state that invoked the Agent exits, usually on a pick from the
+Agent's Menu.
+
+The actor of an Agent never finishes, so an `onDone` on its invoke never runs. Give the Agent a
+pick, such as `finish`, and route on it. When a Turn fails with no pick, jr2 sends the event
+`agent.fault` to the Machine. It is an event, not an error of the invoke, so an `onError` does
+not get it. Route it on each state that invokes an Agent, or once on a state above them:
+`on: { "agent.fault": "failed" }`. `jr2 check` and `jr2 up` refuse a state that invokes an
+Agent with no route for it, and an `agent.fault` that no transition takes ends the run `error`.
+
+An Agent with `workspace: "write"` or `"read"` works in a Sandbox, so invoke it inside a
+`workspace()` body. An Agent with `workspace: "none"` can run anywhere. A model can lack the
+definition's thinking level: see [`ThinkingLevel`](type-thinkinglevel.md).
+
+When a Turn starts, it refuses:
+- a key in `input` that a Turn does not have: ``agent "<slot>": the Turn's input carries
+  `<key>`, which a Turn has no use for — its input is its Frame (`prompt`, `cwd`), its Dials
+  (`model`, `thinkingLevel`), and `continue` (ADR-0057)``
+- no `cwd` under Repo Slots: ``turn <id>: agent "<slot>" works under a Workspace with Repo Slots
+  (<slots>) and its Turn framed no `cwd`: say where it works, a Worktree, or `cwd: "/work"` above
+  them (ADR-0057)``
+- a `cwd` that is not an absolute path: ``agent "<slot>": the Turn's Frame carries a `cwd` that
+  is not an absolute path — the Frame says WHERE this Turn works (ADR-0057), and a Turn rooted
+  anywhere else would work in the wrong directory silently``. The Harness makes this refusal
+  when it admits the Turn, and the error starts with `harness admission failed (400): `.
+- an Agent with Working tools outside a `workspace()`: ``turn <id>: agent "<slot>" has
+  workspace: "<access>" — invoke it inside a workspace() (ambient resolution), or pass an
+  explicit `endpoint` (workspace-less stub path)``
+- a `model` that is still `open`: ``agent "<slot>" has an Open model — nobody bound it; bind it
+  where the Machine is registered (`customize(<machine>, { agents: { <slot>: { model:
+  "<provider>/<model>" } } })`), because a packaged Machine cannot pick a model on your behalf
+  (ADR-0054)``. `jr2 up` refuses this before it builds anything.
+
+**Parameters**
+
+- `declaration` ([`AgentDeclaration`](type-agentdeclaration.md)): The Agent's definition (see [`AgentDefinition`](type-agentdefinition.md)). `model` may be `open`
+  in a Machine that you publish as a package.
+
+**Returns**: The actor logic of the Agent's slot.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  agent,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const finish = defineEvent({
+  name: "finish",
+  description: "Call this when `node --test` passes.",
+  input: z.object({}),
+});
+const runInput = z.object({ branch: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  events: [finish],
+  actors: {
+    coder: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You fix failing tests. You change no test.",
+    }),
+    cut: worktree(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({
+          prompt: "Make `node --test` pass, then commit.",
+          cwd: fixTree(context),
+          thinkingLevel: "high",
+        }),
+      },
+      on: { finish: "done" },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+**See also**
+
+- [Agents and Turns](../../concepts/agents-and-turns.md)
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [ADR-0049: A Machine carries its parts and composes by invoke](../decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)
+- [ADR-0057: A Turn is its Frame, its Dials, and whether it continues](../decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md)

package/docs/reference/authoring-surface/answer.md

@@ -0,0 +1,156 @@
+---
+title: answer
+description: Set what the Agent reads when jr2 answers its pick.
+---
+
+# `answer`
+
+Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function answer<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject["params"] | undefined,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+>(
+  fn: (args: { context: TContext; event: TExpressionEvent; chain: readonly ChainLink<TActor, TEvent>[] }) => unknown,
+): ActionFunction<TContext, TExpressionEvent, TEvent, TParams, TActor, never, never, never, never> & AnswerAction
+```
+
+Set what the Agent reads when jr2 answers its pick. It is an xstate action: write it in
+`entry`, `exit` or the `actions` of a transition. Without it, the Agent reads the last reply
+since the pick.
+
+`fn` gets `{ context, event, chain }`. `chain` is every reply since the pick, oldest first. Each
+link is `{ kind: "output", src, output }`, the output of an invoked actor, or `{ kind: "event",
+event }`, an event that a Gate or a nested Agent sent. TypeScript types each link, but not the
+order or the number of links. What `fn` gives back goes to the Agent as JSON. A value with no
+JSON form clears the answer: the Agent then reads the last reply. When more than one `answer`
+runs, the last one wins.
+
+Where you write it decides which pick it answers:
+
+- At or below the state of an Agent, it answers only a pick of that Agent.
+- On a transition below no Agent's state, it answers a pick of the Agent whose event took the
+  transition.
+- On an `entry` or an `exit` below no Agent's state, it sets nothing, and `jr2 up` prints a
+  warning: `an answer on the <entry|exit> of "<state>" is below no Agent's state, so it shapes
+  no pick — an <entry|exit> there is no transition an Agent's event takes; move it under
+  "<agent state>", or onto a transition (ADR-0067)`.
+
+The error of an invoked actor is no link, and the Agent does not see it. To tell the Agent,
+write `answer` on the `onError` route. An Effect never takes that route for an outcome: every
+outcome is output.
+
+**Parameters**
+
+- `fn`: Gets `{ context, event, chain }` and gives back what the Agent reads, as a value
+  with a JSON form.
+
+**Returns**: An xstate action.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  agent,
+  answer,
+  command,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const runTests = defineEvent({
+  name: "run_tests",
+  description: "Run the test suite. Its result is this call's answer.",
+  input: z.object({}),
+});
+
+const finished = defineEvent({
+  name: "finished",
+  description: "Say that the tests pass.",
+  input: z.object({}),
+});
+
+type Input = Workspaced<{}, "app">;
+
+const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  events: [runTests, finished],
+  actors: {
+    coder: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You are a careful engineer.",
+    }),
+    cut: worktree(),
+    tests: command(["npm", "test"]),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix-tests",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: "fix-tests" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
+    coding: {
+      invoke: {
+        src: "coder",
+        input: ({ context }) => ({ prompt: "Make the tests pass.", cwd: fixTree(context) }),
+      },
+      on: { finished: "done" },
+      initial: "ready",
+      states: {
+        ready: { on: { run_tests: "testing" } },
+        testing: {
+          invoke: {
+            src: "tests",
+            input: ({ context }) => ({ worktree: fixTree(context) }),
+            onDone: {
+              target: "ready",
+              // The Agent reads this string, not the whole output of the command.
+              actions: answer(({ event }) =>
+                event.output.outcome === "exited" && event.output.code === 0
+                  ? "The tests pass."
+                  : `The tests fail:\n${"tail" in event.output ? event.output.tail : event.output.reason}`,
+              ),
+            },
+          },
+        },
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+});
+```
+
+**See also**
+
+- [The Menu](../../concepts/the-menu.md)
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)
+- [ADR-0024: An Agent's turn ends with the state that asked for it](../decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md)

package/docs/reference/authoring-surface/arg.md

@@ -0,0 +1,82 @@
+---
+title: arg
+description: Mark one argv entry of a `command` that the input of the Effect fills.
+---
+
+# `arg`
+
+Constant, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+const arg: <const N extends string>(name: N) => Arg<N>
+```
+
+Mark one argv entry of a `command` that the input of the Effect fills. `arg("file")` is one
+argument: the value of the `file` key of the input, whatever its characters. No shell reads it.
+
+The input of the Effect then has a string key for each `arg`. Give it in the `input` of the
+`invoke`, or use `fromPick` to give it from a pick.
+
+When it starts, with no string in the input for an entry, the Effect fails (its `onError`
+route): `command "<slot>": argv slot <<name>> has no string value in its input (got <type>) —
+map it in the invoke's input`. The angle brackets around the name are in the text.
+
+**Returns**: The argv entry, for the argv list of `command`.
+
+**Example**
+
+```ts
+import {
+  arg,
+  command,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+type Input = Workspaced<{ file: string }, "app">;
+
+const lintTree = (context: Input) => `${context.workspace.repos.app}/lint` as const;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  actors: { cut: worktree(), lint: command(["npx", "eslint", arg("file")]), fail: fail() },
+}).createMachine({
+  id: "lint",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: lintTree(context), branch: "lint" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "lint" }, { target: "notCut" }],
+      },
+    },
+    lint: {
+      invoke: {
+        src: "lint",
+        input: ({ context }) => ({ file: context.file, worktree: lintTree(context) }),
+        onDone: "done",
+      },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)

package/docs/reference/authoring-surface/basic.md

@@ -0,0 +1,62 @@
+---
+title: basic
+description: "Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`."
+---
+
+# `basic`
+
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function basic<
+  const U extends string | Secret | Text,
+  const P extends string | Secret | Text,
+>(
+  user: U,
+  password: P,
+): MarkedIf<U | P, { readonly basic: { user: Text; password: Text } }>
+```
+
+Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value
+is the base64 of `user:password`. The Effector puts in the value of each secret.
+
+Each of `user` and `password` is a string, a `secret(...)` or a `text`. In a packaged Machine,
+one of them can hold `secret(open)`. It refuses another value: `` expected a string, a
+secret("name") or a text`…`, got <value> ``.
+
+**Parameters**
+
+- `user`: The user name: a string, a `secret(...)` or a `text`.
+- `password`: The password: a string, a `secret(...)` or a `text`.
+
+**Returns**: The `auth` of an `http` Effect.
+
+**Example**
+
+```ts
+import { basic, http, jr2Setup, secret } from "@jr2/orchestrator";
+
+export const machine = jr2Setup({
+  actors: {
+    issue: http({
+      method: "GET",
+      url: "https://jira.example.com/rest/api/2/issue/APP-1",
+      auth: basic("jr2-bot@example.com", secret("jira-token")),
+    }),
+  },
+}).createMachine({
+  id: "issue",
+  initial: "reading",
+  states: {
+    reading: { invoke: { src: "issue", onDone: "done" } },
+    done: { type: "final" },
+  },
+});
+```
+
+**See also**
+
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [Secrets and trust](../../concepts/secrets-and-trust.md)
+- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.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/authoring-surface/bearer.md

@@ -0,0 +1,53 @@
+---
+title: bearer
+description: "Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret."
+---
+
+# `bearer`
+
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function bearer<const S extends Secret>(s: S): MarkedIf<S, { readonly bearer: Secret }>
+```
+
+Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value
+of an Effect secret. In a packaged Machine, the secret can be `secret(open)`.
+
+It refuses a value that is not a secret: `bearer(…) takes a secret("name")`.
+
+**Parameters**
+
+- `s` ([`Secret`](type-secret.md)): The secret: `secret("name")`, or `secret(open)`.
+
+**Returns**: The `auth` of an `http` Effect.
+
+**Example**
+
+```ts
+import { bearer, http, jr2Setup, secret } from "@jr2/orchestrator";
+
+export const machine = jr2Setup({
+  actors: {
+    status: http({
+      method: "GET",
+      url: "https://api.github.com/repos/you/app",
+      auth: bearer(secret("github")),
+    }),
+  },
+}).createMachine({
+  id: "status",
+  initial: "reading",
+  states: {
+    reading: { invoke: { src: "status", onDone: "done" } },
+    done: { type: "final" },
+  },
+});
+```
+
+**See also**
+
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [Secrets and trust](../../concepts/secrets-and-trust.md)
+- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.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/authoring-surface/branchname.md

@@ -0,0 +1,15 @@
+---
+title: branchName
+description: A kit schema for a pick param that names a branch.
+---
+
+# `branchName`
+
+Constant, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+const branchName: ZodString
+```
+
+A kit schema for a pick param that names a branch. For example:
+`input: z.object({ branch: branchName })`.

package/docs/reference/authoring-surface/chartschema.md

@@ -0,0 +1,23 @@
+---
+title: chartSchema
+description: The Chart grammar, as a zod schema.
+---
+
+# `chartSchema`
+
+Constant, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+
+```ts
+const chartSchema: z.ZodType<ChartText>
+```
+
+The Chart grammar, as a zod schema. Make a field of the run input of a Chart wrapper this schema,
+as in `z.object({ topic: z.string(), chart: chartSchema })`. Then a run input can carry a Chart,
+and the wrapper can keep Charts under names: Chart files in `workflows/<wrapper>/`, and runtime
+Charts. For the pick of a planner, use `chartSchemaFor`, which knows the names that the Open body
+lends.
+
+**See also**
+
+- [Run a Chart by name](../../guides/run-a-chart-by-name.md)
+- [Charts](../../concepts/charts.md)

package/docs/reference/authoring-surface/chartschemafor.md

@@ -0,0 +1,48 @@
+---
+title: chartSchemaFor
+description: The Chart grammar for one Open body, as a zod schema.
+---
+
+# `chartSchemaFor`
+
+Function, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+
+```ts
+function chartSchemaFor(decl: OpenBodyDeclaration): z.ZodType<ChartText>
+```
+
+The Chart grammar for one Open body, as a zod schema. The names that the Open body lends, and the
+models and the Workspace accesses that it allows, are the only values that the schema takes.
+Make it the parameter of the pick of a planner. The model then gets the grammar as the
+parameters of its tool, and the Briefing tells it how a Chart runs. The door still checks each
+Chart before it runs.
+
+**Parameters**
+
+- `decl` ([`OpenBodyDeclaration`](type-openbodydeclaration.md)): The declaration of the Open body that the Chart binds.
+
+**Returns**: The schema of a Chart for that Open body.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { chartSchemaFor, defineEvent, type OpenBodyDeclaration } from "@jr2/orchestrator";
+
+const declaration: OpenBodyDeclaration = {
+  lends: { agents: ["writer"], gate: true },
+  allows: { models: ["anthropic/claude-haiku-5-5"], workspace: ["none"] },
+  ceilings: { turns: 12, wallClock: "30m", transitions: 500, fanOut: 2, size: 65536 },
+};
+
+export const runChart = defineEvent({
+  name: "run_chart",
+  description: "Run this Chart. Its outcome is the answer to this call.",
+  input: z.object({ chart: chartSchemaFor(declaration) }),
+});
+```
+
+**See also**
+
+- [Let an Agent write a Chart](../../guides/let-an-agent-write-a-chart.md)
+- [Charts](../../concepts/charts.md)