@jr2/orchestrator 0.3.0 → 0.5.1

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

@@ -0,0 +1,237 @@
+---
+title: jr2Setup
+description: "Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`."
+---
+
+# `jr2Setup`
+
+Function, in `@jr2/orchestrator/src/setup.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+
+```ts
+function jr2Setup<
+  TContext extends MachineContext = MachineContext,
+  const TDefs extends readonly EventDef[] = readonly [],
+  TActors extends Record<string, UnknownActorLogic> = {},
+  TActions extends Record<string, ParameterizedObject["params"] | undefined> = {},
+  TGuards extends Record<string, ParameterizedObject["params"] | undefined> = {},
+  TDelay extends string = never,
+  TTag extends string = string,
+  TInput = NonReducibleUnknown,
+  TOutput extends NonReducibleUnknown = NonReducibleUnknown,
+  TEmitted extends EventObject = EventObject,
+  TMeta extends MetaObject = MetaObject,
+>(
+  def: {
+    types?: {
+      context?: TContext;
+      input?: TInput;
+      output?: TOutput;
+      tags?: TTag;
+      emitted?: TEmitted;
+      meta?: TMeta;
+    };
+    events?: TDefs;
+    actors?: TActors;
+    actions?: {
+      [K in keyof TActions]: ActionFunction<
+        TContext,
+        WorkflowEvent<TDefs>,
+        WorkflowEvent<TDefs>,
+        TActions[K],
+        ToProvidedActor<MergedActors<TActors>>,
+        ToParameterizedObject<TActions>,
+        ToParameterizedObject<TGuards>,
+        TDelay,
+        TEmitted
+      >;
+    };
+    guards?: {
+      [K in keyof TGuards]: GuardPredicate<TContext, WorkflowEvent<TDefs>, TGuards[K], ToParameterizedObject<TGuards>>;
+    };
+    delays?: {
+      [K in TDelay]: DelayConfig<
+        TContext,
+        WorkflowEvent<TDefs>,
+        ToParameterizedObject<TActions>["params"],
+        WorkflowEvent<TDefs>
+      >;
+    };
+  } = {},
+): SetupReturn<
+  TContext,
+  WorkflowEvent<TDefs>,
+  MergedActors<TActors>,
+  {},
+  TActions,
+  TGuards & SentByGuards,
+  TDelay,
+  TTag,
+  TInput,
+  TOutput,
+  TEmitted,
+  TMeta
+>
+```
+
+Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`. Write a Machine
+with it when an Agent or a Gate sends events into the Machine, or when the Machine declares a
+door. Call `.createMachine(config)` on the result, as with `setup()`. The Machine you get is a
+plain xstate Machine.
+
+What it adds to `setup()`:
+- `events` replaces `types.events`. The event type of the Machine comes from the
+  `defineEvent` events you list, plus the events jr2 itself sends (`agent.fault`,
+  `workspace.lost`). An event that a party sent has `event.sender`. A Machine that takes no
+  workflow event leaves out `events`.
+- The `gate` actor is ready to invoke by name: `invoke: { src: "gate" }`.
+- Each Agent slot (`actors: { coder: agent(…) }`) gets its Menu from the states that invoke it.
+- The `sentBy(id)` guard is ready to use.
+- `createMachine` also takes `input`: a zod object for the input that starts a run. jr2 checks
+  each start against it. Without it, a run can start with any input. The `setup()` of xstate
+  does not read this `input`, so a Machine with a door uses `jr2Setup`, also when it takes no
+  workflow event. `jr2 up` and the publish door refuse a registered Machine that has a zod
+  `input` if `jr2Setup` did not make the Machine: ``workflow "<name>": machine "<id>" has a zod `input` on
+  createMachine, but jr2Setup did not make this Machine, so no door reads that input …``
+
+The output of a run is the root `output` of `createMachine`, beside `id` and `states`, as in
+xstate v5. xstate does not read the `output` of a final state as the output of the Machine. It
+gives that output to the root `output` as `event.output`. Write
+`output: ({ event }) => event.output as Output` at the root, or make the output from `context`
+there. `createMachine` refuses an `output` on a final state directly below the root when the root
+has no `output` (see the list below).
+
+`createMachine` refuses a Machine that it cannot run as written. Among the refusals:
+- an `on` key that no listed event has: ``machine "<id>" handles event "<key>", which no def in
+  jr2Setup({ events }) declares (declared: <names>) — a typo, or a missing defineEvent``
+- a listed event that no state takes: ``machine "<id>" declares "<name>", which no state handles
+  — a pick no state takes is on no Menu and no Gate: handle it, or drop it from
+  jr2Setup({ events })``
+- an entry of `events` that `defineEvent` did not make, or one name listed twice:
+  ``machine "<id>": `events` entry is not a defineEvent() def: <entry>``,
+  ``machine "<id>": duplicate event "<name>" in `events` ``
+- an `agent()`, an Effect or a `workspace()` written on `invoke.src` instead of under `actors`:
+  ``machine "<id>": state "<state>" invokes <part> inline — a Part is a key of actors, so it has
+  a name that the ledger, the report and customize() share: actors: { <name>: <factory>(...) },
+  then invoke: { src: "<name>" }``. `<part>` is `an Agent`, `an Effect` or `a Workspace`.
+  `<factory>` is `agent`, the Effect's kind (such as `command`), or `workspace`.
+- an `output` on a final state directly below the root, when the root has no `output`:
+  ``machine "<id>": final state "<state>" declares an output, and the root has no output — xstate
+  v5 gives a run only its root output, so this output reaches nothing and the run ends with none:
+  write it at the root, as output: ({ context }) => ..., or keep it on the final state and pass it
+  on with output: ({ event }) => event.output at the root``. With more than one such final state,
+  it names each one and puts the words in the plural: ``final states "<state>", "<state>"
+  declare an output``, ``these outputs reach nothing``, ``write one at the root`` and ``keep
+  them on the final states and pass them on``. An `output` on a
+  final state inside a compound state is legal: the `onDone` of that compound state gets it as
+  `event.output`.
+- a parallel state at or below a state that invokes an Agent: ``machine "<id>": state "<state>"
+  is parallel, at or below Agent "<slot>"'s state "<state>" — a parallel region below an Agent's
+  state is reserved for picks the Agent does not wait for, which jr2 does not build; background
+  work goes above the Agent's state``
+- a state below an Agent's state that invokes something and that nothing enters: ``machine
+  "<id>": state "<state>" below Agent "<slot>"'s state "<state>" is entered by nothing, so what
+  it invokes (<src>) never runs — target it from a pick or a route, or delete it``
+- a state that invokes an Agent when that state and each state above it have no `agent.fault`
+  route: ``machine "<id>": state "<state>" invokes an Agent, and no route for "agent.fault" is
+  on it or on a state above — jr2 sends agent.fault when the Agent's Turn cannot go on, and with
+  no route the run faults: route it on that state or on a state above it, as on: {
+  "agent.fault": "<the state that handles it>" } (ADR-0074)``. A state that invokes an Open body
+  that lends an Agent or allows a model gets the same line, with `invokes an Open body that can
+  run an Agent`: the body sends it a Chart's unrouted `agent.fault`. When both kinds have no route,
+  one line names both, joined by `, and`. One route on the root is a route for each state. A
+  Chart's Machine does not get this refusal: in a Chart the route is optional ([ADR-0070](../decisions/0070-a-machine-lends-its-parts-to-a-chart.md)).
+
+It also refuses a `sentBy` that names no party (see `sentBy`). It refuses a pick param that
+nothing reads, where the pick enters a state that invokes an Effect (see `fromPick`). Shapes that
+are legal but probably not what you mean, such as a mode that nothing enters, are warnings that
+`jr2 up` prints.
+
+**Parameters**
+
+- `def`: What `setup()` takes, with `events` in place of `types.events`. A Machine that
+  needs none of it calls `jr2Setup()`.
+
+  - `types` (optional): `object`
+
+    The types of the Machine, as in `setup()`: `context`, `input`, `output`, `tags`, `emitted`
+    and `meta`. Not `events`: the event type comes from `events`.
+
+    - `context` (optional): `TContext`
+    - `input` (optional): `TInput`
+    - `output` (optional): `TOutput`
+    - `tags` (optional): `TTag`
+    - `emitted` (optional): `TEmitted`
+    - `meta` (optional): `TMeta`
+  - `events` (optional): `TDefs`
+
+    The workflow events this Machine takes: each one made by `defineEvent`. Leave it out when the
+    Machine takes none. Each listed event must be the name of an `on` key. Each `on` key must be
+    listed, if it is not a jr2 or xstate event (an event with a `.` in its name).
+  - `actors` (optional): `TActors`
+
+    The actors the states invoke by name, as in `setup()`: Agent slots (`agent(…)`), Effects
+    (`command(…)`, `http(…)`, `push(…)`), child Machines, `workspace(…)` and plain xstate logic.
+    The key is the slot's name. An actor named `gate` replaces jr2's Gate.
+  - `actions` (optional): `{ [K in keyof TActions]: ActionFunction<TContext, WorkflowEvent<TDefs>, WorkflowEvent<TDefs>, TActions[K], ToProvidedActor<MergedActors<TActors>>, ToParameterizedObject<TActions>, ToParameterizedObject<TGuards>, TDelay, TEmitted>; }`
+
+    Named actions, as in `setup()`. Their `event` has the type of this Machine's events.
+  - `guards` (optional): `{ [K in keyof TGuards]: GuardPredicate<TContext, WorkflowEvent<TDefs>, TGuards[K], ToParameterizedObject<TGuards>>; }`
+
+    Named guards, as in `setup()`. `sentBy` is there already; do not name a guard `jr2.sentBy`.
+  - `delays` (optional): `{ [K in TDelay]: DelayConfig<TContext, WorkflowEvent<TDefs>, ToParameterizedObject<TActions>["params"], WorkflowEvent<TDefs>>; }`
+
+    Named delays, as in `setup()`.
+
+**Returns**: What `setup()` returns. Call `.createMachine(config)` on it.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup } from "@jr2/orchestrator";
+
+const proposed = defineEvent({
+  name: "proposed",
+  description: "Call this with your plan.",
+  input: z.object({ plan: z.string() }),
+});
+const approve = defineEvent({ name: "approve", input: z.object({}) });
+const reject = defineEvent({ name: "reject", input: z.object({ reason: z.string() }) });
+
+export const machine = jr2Setup({
+  types: {} as { input: { goal: string }; context: { goal: string } },
+  events: [proposed, approve, reject],
+  actors: {
+    planner: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You plan small releases.",
+      workspace: "none",
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "plan",
+  input: z.object({ goal: z.string() }),
+  context: ({ input }) => ({ goal: input.goal }),
+  on: { "agent.fault": ".failed" },
+  initial: "planning",
+  states: {
+    planning: {
+      invoke: { src: "planner", input: ({ context }) => ({ prompt: `Plan this: ${context.goal}` }) },
+      on: { proposed: "review" },
+    },
+    review: {
+      invoke: { src: "gate" },
+      on: { approve: "approved", reject: "planning" },
+    },
+    approved: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**See also**
+
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [Machines and Workflows](../../concepts/machines-and-workflows.md)
+- [ADR-0015: Workflows are authored through `jr2Setup`; vocabulary and agent menus derive from the machine](../decisions/0015-authoring-surface-absorbs-the-mechanism.md)

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

@@ -0,0 +1,74 @@
+---
+title: open
+description: "Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`."
+---
+
+# `open`
+
+Constant, in `@jr2/orchestrator/src/open.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+const open: unique symbol
+```
+
+Leave a part of a Machine Open: for the Instance that registers the Machine to bind with
+`customize()`. Write it where a value goes, in a Machine that you publish as a package, for a
+part that the package cannot know or pay for:
+- a Repo Slot: `repos: { app: open }`, or the whole map: `repos: open`;
+- an Agent's model: `agent({ model: open, … })`;
+- an Effect's url or argv: `http({ url: open, … })`, `command(open)`;
+- the secret of an Effect's auth, of a header, or of a command's `env`: `secret(open)`.
+
+`jr2 up` refuses a Workflow with an Open part that nobody bound, and prints the `customize()`
+line that binds it: ``refusing: workflow "<name>" leaves <part> open — bind it where the Machine
+is registered: export const machine = customize(<import>, …)  (<adr>)``. A run never sees an
+Open part.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, customize, defineEvent, fail, jr2Setup, open, workspace } from "@jr2/orchestrator";
+
+const finish = defineEvent({
+  name: "finish",
+  description: "Call this when `node --test` passes.",
+  input: z.object({}),
+});
+
+const body = jr2Setup({
+  events: [finish],
+  actors: { coder: agent({ model: open, instructions: "You fix the failing test." }), fail: fail() },
+}).createMachine({
+  id: "fix",
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "coding",
+  states: {
+    coding: {
+      invoke: { src: "coder", input: { prompt: "Make `node --test` pass." } },
+      on: { finish: "done" },
+    },
+    done: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+// What a package exports: the repository and the model are Open.
+export const fix = workspace(body, {
+  repos: { app: open },
+  spec: () => ({ branch: "jr2/fix" }),
+});
+
+// What an Instance's `workflows/fix.ts` exports: the same Machine, its Open parts bound.
+export const machine = customize(fix, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+});
+```
+
+**See also**
+
+- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
+- [Composition](../../concepts/composition.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/openbody.md

@@ -0,0 +1,86 @@
+---
+title: openBody
+description: "Make an Open body: the actor slot that a Chart binds."
+---
+
+# `openBody`
+
+Function, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+
+```ts
+function openBody(decl: OpenBodyDeclaration): OpenBodyLogic
+```
+
+Make an Open body: the actor slot that a Chart binds. Put it in `actors`, and invoke it from a
+state with `{ chart, ...input }`. `chart` is the text of a Chart, or `{ name }` for a named
+Chart of this wrapper. The other keys are the input of the Chart, which it reads as
+`{{input.<key>}}`. A Machine with an Open body is a Chart wrapper.
+
+Each Agent Turn of the Chart runs where the Open body runs: in the Sandbox of its `workspace()`,
+or on the Instance Harness. The Open body ends with an [`OpenBodyOutput`](type-openbodyoutput.md).
+
+It refuses a declaration that is not correct: `openBody: <problem>; <problem>`, for example
+`ceilings.turns: missing; an Open body states every ceiling`. `createMachine` refuses a lent
+name that the Machine does not have: `machine "<id>": Open body "<slot>": lends.agents: "<name>"
+is no actor slot of this Machine; its actors: <slots>`.
+
+**Parameters**
+
+- `decl`: What a Chart can use, and its limits (see [`OpenBodyDeclaration`](type-openbodydeclaration.md)).
+
+**Returns**: The actor logic of the slot.
+
+**Example**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, chartSchema, fail, jr2Setup, openBody, type OpenBodyOutput } from "@jr2/orchestrator";
+
+// `chart` is a Chart, so a run input can carry one, and Charts can have names.
+const door = z.object({ topic: z.string(), chart: chartSchema });
+type Input = z.infer<typeof door>;
+type Context = Input & { result?: OpenBodyOutput };
+
+export const machine = jr2Setup({
+  types: {} as { context: Context; input: Input },
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      workspace: "none",
+      instructions: "You write clear, short text for engineers.",
+    }),
+    body: openBody({
+      lends: { agents: ["writer"] },
+      allows: { models: [], workspace: [] },
+      ceilings: { turns: 6, wallClock: "15m", transitions: 200, fanOut: 1, size: 65536 },
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "notes",
+  input: door,
+  context: ({ input }) => ({ ...input }),
+  // The fault of `writer` when a Chart does not route it: the Open body sends it here.
+  on: { "agent.fault": ".failed" },
+  initial: "running",
+  states: {
+    running: {
+      invoke: {
+        src: "body",
+        input: ({ context }: { context: Context }) => ({ chart: context.chart, topic: context.topic }),
+        onDone: { target: "done", actions: assign({ result: ({ event }) => event.output as OpenBodyOutput }) },
+      },
+    },
+    done: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**See also**
+
+- [Charts](../../concepts/charts.md)
+- [Run a Chart by name](../../guides/run-a-chart-by-name.md)
+- [Let an Agent write a Chart](../../guides/let-an-agent-write-a-chart.md)
+- [ADR-0070: A Machine lends its parts to a Chart](../decisions/0070-a-machine-lends-its-parts-to-a-chart.md)

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

@@ -0,0 +1,125 @@
+---
+title: paramsOf
+description: Read the params of a pick from the event that entered the state.
+---
+
+# `paramsOf`
+
+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 paramsOf<
+  N extends string,
+  I extends z.ZodObject,
+>(
+  event: EventObject,
+  def: EventDef<N, I>,
+): z.infer<I>
+```
+
+Read the params of a pick from the event that entered the state. Use it in a plain `input`
+mapper when the Machine must change a param before the invoked actor gets it. When the params go
+to the input as they are, use `fromPick`.
+
+It parses the params with the `input` schema of the pick. It refuses an event that is not this
+pick: `state entered by "<event>", but its input reads the params of pick "<pick>"`.
+
+`createMachine` calls each mapper one time to see which params it reads. When the mapper throws
+there, `jr2 up` prints a warning before a run starts: `pick "<pick>" enters state "<state>"
+(Effect "<slot>"): could not probe the input mapper (<error>); its params are unchecked`.
+
+`createMachine` refuses a param of a pick that enters a state that invokes an Effect, when
+nothing reads the param: `machine "<id>": pick "<pick>" enters state "<state>" (Effect
+"<slot>"), which never reads "<param>": the Agent supplies it and nothing uses it — map it in an
+invoke's input, store it with assign, or drop it from the def`.
+
+**Parameters**
+
+- `event`: The event that entered the state: the `event` that the mapper gets.
+- `def` ([`EventDef`](type-eventdef.md)): The pick, as `defineEvent` made it.
+
+**Returns**: The params of the pick, typed by its `input` schema.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  agent,
+  arg,
+  command,
+  defineEvent,
+  fail,
+  jr2Setup,
+  paramsOf,
+  workspace,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const runTest = defineEvent({
+  name: "run_test",
+  description: "Run the tests of one module.",
+  input: z.object({ module: z.string() }),
+});
+
+const finished = defineEvent({
+  name: "finished",
+  description: "Say that all the tests pass.",
+  input: z.object({}),
+});
+
+type Input = Workspaced<{}, "app">;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  events: [runTest, finished],
+  actors: {
+    coder: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You are a careful engineer.",
+    }),
+    test: command(["node", "--test", arg("file")]),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix-tests",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "coding",
+  states: {
+    coding: {
+      invoke: {
+        src: "coder",
+        input: { prompt: "Make the tests pass. Run the tests of one module at a time." },
+      },
+      on: { finished: "done" },
+      initial: "ready",
+      states: {
+        ready: { on: { run_test: "testing" } },
+        testing: {
+          invoke: {
+            src: "test",
+            // A plain mapper: the Machine makes the file name from the pick's `module`.
+            input: ({ event }) => ({ file: `test/${paramsOf(event, runTest).module}.test.js` }),
+            onDone: "ready",
+          },
+        },
+      },
+    },
+    done: { type: "final" },
+    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" } },
+  spec: () => ({ branch: "fix-tests" }),
+});
+```
+
+**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)