@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/reference/authoring-surface/group-charts.md

@@ -0,0 +1,16 @@
+---
+title: "Authoring surface: Charts"
+description: "The Open body a Chart wrapper places in `actors`, and the grammar a planner's pick declares, whole or narrowed to one wrapper (ADR-0070)."
+---
+
+# Authoring surface: Charts
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+The Open body a Chart wrapper places in `actors`, and the grammar a planner's pick declares, whole or narrowed to one wrapper ([ADR-0070](../decisions/0070-a-machine-lends-its-parts-to-a-chart.md)).
+
+- [`openBody`](openbody.md) (function): Make an Open body: the actor slot that a Chart binds.
+- [`OpenBodyDeclaration`](type-openbodydeclaration.md) (type): What an Open body declares: the parts that it lends a Chart, what the Agents of a Chart can have, and the limits of a Chart.
+- [`OpenBodyOutput`](type-openbodyoutput.md) (type): The output of an Open body.
+- [`chartSchema`](chartschema.md) (constant): The Chart grammar, as a zod schema.
+- [`chartSchemaFor`](chartschemafor.md) (function): The Chart grammar for one Open body, as a zod schema.

package/docs/reference/authoring-surface/group-composition.md

@@ -0,0 +1,25 @@
+---
+title: "Authoring surface: Composition"
+description: "A part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017, ADR-0049, ADR-0054, ADR-0060)."
+---
+
+# Authoring surface: Composition
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+A part left Open, a Machine's parts retuned, a Pool over a Source ([ADR-0017](../decisions/0017-pool-over-a-source-port.md), [ADR-0049](../decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md), [ADR-0054](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md), [ADR-0060](../decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)).
+
+- [`open`](open.md) (constant): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`.
+- [`customize`](customize.md) (function): Retune the parts that a Machine carries, without a change to the module that exports it.
+- [`Customize`](type-customize.md) (type): The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the Machines it composes, and the Sandbox of its `workspace()`.
+- [`EffectBinding`](type-effectbinding.md) (type): The values that bind the Open parts of one Effect.
+- [`Size`](type-size.md) (type): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
+- [`UserContainer`](type-usercontainer.md) (type): The User Container in its object form: its image, and its part of the Workspace's Size.
+- [`carry`](carry.md) (function): Give the item itself.
+- [`pool`](pool.md) (function): Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most `cap` workers at once.
+- [`reread`](reread.md) (function): Read the Source again.
+- [`skip`](skip.md) (function): Bring nothing, and say why.
+- [`source`](source.md) (function): Declare a Source: where a `pool()` gets its work items, one at a time.
+- [`PoolNextInput`](type-poolnextinput.md) (type): The input of a Source's `next`: the ids of the items that workers have now, the ids of the items that settled, and the Pool's input.
+- [`SourceReply`](type-sourcereply.md) (type): The text that the person who acted reads, from this Source's verdict (ADR-0011, ADR-0017).
+- [`SourceVerdict`](type-sourceverdict.md) (type): A Source's verdict on one delivery, as its `reply` reads it (ADR-0017).

package/docs/reference/authoring-surface/group-config.md

@@ -0,0 +1,17 @@
+---
+title: "Authoring surface: Config"
+description: "`jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050)."
+---
+
+# Authoring surface: Config
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+`jr2.config.ts`, the deployment facts a Machine cannot carry ([ADR-0050](../decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)).
+
+- [`defineConfig`](defineconfig.md) (function): Declare the config of an Instance: the default export of `jr2.config.ts`.
+- [`JR2Config`](type-jr2config.md) (type): The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
+- [`McpRemoteServer`](type-mcpremoteserver.md) (type): A remote MCP server, which the Harness reaches over Streamable HTTP.
+- [`McpServer`](type-mcpserver.md) (type): One MCP server of the Instance: a `McpRemoteServer` (`url`) or a `McpStdioServer` (`command`).
+- [`McpStdioServer`](type-mcpstdioserver.md) (type): A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent conversation, through jr2's spawner, inside the Agent's confinement.
+- [`RunsConfig`](type-runsconfig.md) (type): How long jr2 keeps an ended run, and the volume that keeps it (ADR-0065).

package/docs/reference/authoring-surface/group-effects.md

@@ -0,0 +1,48 @@
+---
+title: "Authoring surface: Effects"
+description: Work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071, ADR-0079), and what an author writes between a pick and that work.
+---
+
+# Authoring surface: Effects
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+Work a Machine does outside itself, as an actor slot ([ADR-0067](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), [ADR-0068](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md), [ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md), [ADR-0079](../decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)), and what an author writes between a pick and that work.
+
+- [`arg`](arg.md) (constant): Mark one argv entry of a `command` that the input of the Effect fills.
+- [`CommandOutput`](type-commandoutput.md) (type): The output of a `command` Effect: what the `onDone` of its state gets as `event.output`.
+- [`LaterOutcome`](type-lateroutcome.md) (type): A value of `outcome` that this kit does not give.
+- [`command`](command.md) (function): Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
+- [`basic`](basic.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`.
+- [`bearer`](bearer.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret.
+- [`file`](file.md) (function): Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`.
+- [`http`](http.md) (function): Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads.
+- [`secret`](secret.md) (function): Name an Effect secret: `secret("jira")`.
+- [`text`](text.md) (function): Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret("x")}` ``.
+- [`HttpOutput`](type-httpoutput.md) (type): The output of an `http` Effect: what the `onDone` of its state gets as `event.output`.
+- [`push`](push.md) (function): Make a `push` Effect: it pushes the branch of a Worktree to the Binding of its Repo Slot.
+- [`PushOutput`](type-pushoutput.md) (type): The output of a `push` Effect: what the `onDone` of its state gets as `event.output`.
+- [`branchName`](branchname.md) (constant): A kit schema for a pick param that names a branch.
+- [`isReady`](isready.md) (constant): Is it `ready`?
+- [`readyOf`](readyof.md) (function): The `ready` output of an `onDone` arm that `isReady` guards.
+- [`worktree`](worktree.md) (function): Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there.
+- [`AnyFramePath`](type-anyframepath.md) (type): A Turn's Frame: a Worktree, or `/work`, stated.
+- [`AnyWorktreePath`](type-anyworktreepath.md) (type): A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the slots of the body.
+- [`FramePath`](type-framepath.md) (type): A Turn's Frame in a Workspace with the Repo Slots `S`.
+- [`WorktreeFound`](type-worktreefound.md) (type): What a cut found.
+- [`WorktreeInput`](type-worktreeinput.md) (type): The input of a `worktree()`: a branch Worktree, or a detached one.
+- [`WorktreeOptions`](type-worktreeoptions.md) (type): The options of `worktree()`.
+- [`WorktreeOutput`](type-worktreeoutput.md) (type): The output of a `worktree()`.
+- [`WorktreePath`](type-worktreepath.md) (type): A Worktree of the Repo Slots `S`.
+- [`WorktreeReady`](type-worktreeready.md) (type)
+- [`WorktreeRefused`](type-worktreerefused.md) (type): No Worktree, and nothing changed.
+- [`dispatch`](dispatch.md) (function): Make a `dispatch` Effect: it starts a run of a Workflow.
+- [`DispatchOutput`](type-dispatchoutput.md) (type): The output of a `dispatch` Effect.
+- [`mcp`](mcp.md) (constant): The `mcp` Effects (ADR-0067, ADR-0079): `mcp.call(server, tool, { input })` calls a tool, `mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a prompt.
+- [`McpOptions`](type-mcpoptions.md) (type): The options of an `mcp` Effect.
+- [`McpCallOutput`](type-mcpcalloutput.md) (type): The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`.
+- [`McpOutput`](type-mcpoutput.md) (type): The output of any `mcp` Effect: a call's, a read's or a prompt's.
+- [`McpReadOutput`](type-mcpreadoutput.md) (type): The output of an `mcp.read` or an `mcp.prompt` Effect.
+- [`answer`](answer.md) (function): Set what the Agent reads when jr2 answers its pick.
+- [`fromPick`](frompick.md) (function): Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the input of the invoked actor by name.
+- [`paramsOf`](paramsof.md) (function): Read the params of a pick from the event that entered the state.

package/docs/reference/authoring-surface/group-failure.md

@@ -0,0 +1,13 @@
+---
+title: "Authoring surface: Failure"
+description: The Part a Machine invokes to fail its run, and the guard that tells a Failure from a defect in an `onError` (ADR-0073).
+---
+
+# Authoring surface: Failure
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+The Part a Machine invokes to fail its run, and the guard that tells a Failure from a defect in an `onError` ([ADR-0073](../decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)).
+
+- [`fail`](fail.md) (function): Fail the run: the Part a Machine invokes to end work that did not succeed.
+- [`isFailure`](isfailure.md) (function): Is this error a Failure, which a state invoked `fail` to make?

package/docs/reference/authoring-surface/group-gates.md

@@ -0,0 +1,16 @@
+---
+title: "Authoring surface: Gates"
+description: A Gate slot hears a Hook (ADR-0011).
+---
+
+# Authoring surface: Gates
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+A Gate slot hears a Hook ([ADR-0011](../decisions/0011-workflow-defined-events.md)).
+
+- [`gate`](gate.md) (function): The Gate: an input that a run waits for from outside the run (ADR-0011).
+- [`Delivered`](type-delivered.md) (type): One plain event of a list of defs: `{ type: "approve", by }`.
+- [`GateLook`](type-gatelook.md) (type): A Gate's read of the fact that it waits for (ADR-0011).
+- [`GateOutcome`](type-gateoutcome.md) (type): What a delivery did at one open Gate.
+- [`GateReply`](type-gatereply.md) (type): The text that the person who acted reads.

package/docs/reference/authoring-surface/group-machine-and-events.md

@@ -0,0 +1,15 @@
+---
+title: "Authoring surface: Machine and events"
+description: The setup a workflow writes its Machine with, the events its parties send, and the guard that makes a writing decline other senders (ADR-0011, ADR-0015).
+---
+
+# Authoring surface: Machine and events
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+The setup a workflow writes its Machine with, the events its parties send, and the guard that makes a writing decline other senders ([ADR-0011](../decisions/0011-workflow-defined-events.md), [ADR-0015](../decisions/0015-authoring-surface-absorbs-the-mechanism.md)).
+
+- [`defineEvent`](defineevent.md) (function): Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine.
+- [`jr2Setup`](jr2setup.md) (function): Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`.
+- [`sentBy`](sentby.md) (function): A guard that is true for an event that one party sent, and false for an event that another party sent: `guard: sentBy("coder")`.
+- [`HostInjectedInput`](type-hostinjectedinput.md) (type): The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.

package/docs/reference/authoring-surface/group-steering.md

@@ -0,0 +1,12 @@
+---
+title: "Authoring surface: Steering"
+description: "The Machine's free text to one of its Agents, which the Agent hears once (ADR-0002)."
+---
+
+# Authoring surface: Steering
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+The Machine's free text to one of its Agents, which the Agent hears once ([ADR-0002](../decisions/0002-duplex-streaming-actor.md)).
+
+- [`steer`](steer.md) (function): Send a Steering message to one Agent of this Machine: an action for a transition.

package/docs/reference/authoring-surface/group-types-these-signatures-name.md

@@ -0,0 +1,137 @@
+---
+title: "Authoring surface: Types these signatures name"
+description: The signature of an export, or a type here, names each of these types.
+---
+
+# Authoring surface: Types these signatures name
+
+This page is one group of the [Authoring surface](../authoring-surface.md). It gives each type its first sentence. Each type has a page of its own, in this folder.
+
+The signature of an export, or a type here, names each of these types. They are not exports of `@jr2/orchestrator`, so a workflow module does not import them by name.
+
+- [`EventSemantics`](type-eventsemantics.md): How the party that sends an event gets its answer.
+- [`EventAudience`](type-eventaudience.md): Who may send an event: `"agent"` (an Agent, as a pick from its Menu), `"external"` (the caller of a Gate), or `"any"` (both).
+- [`EventDef`](type-eventdef.md): A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere.
+- [`WorkflowEvent`](type-workflowevent.md): The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event.
+- [`GateSlot`](type-gateslot.md): A Gate with parts that the Machine carries.
+- [`Duration`](type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
+- [`CallerRecord`](type-callerrecord.md): A Caller as a run records it (ADR-0078): who acted, and the party it says it acted for.
+- [`FailSlot`](type-failslot.md): The logic `fail()` returns: `failLogic` with the brand the walk reads.
+- [`Failure`](type-failure.md): A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
+- [`AgentDeclaration`](type-agentdeclaration.md): What `agent()` takes: an `AgentDefinition`, except that `model` can also be `open`.
+- [`WorkspaceAccess`](type-workspaceaccess.md): What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`.
+- [`WorkspaceOptions`](type-workspaceoptions.md): The options of a `workspace()` that declares the input that starts a run.
+- [`NoSlotWorkspaceOptions`](type-noslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
+- [`WithoutEmptyIndex`](type-withoutemptyindex.md): The fields of the run input `T`.
+- [`PermissiveWorkspaceOptions`](type-permissiveworkspaceoptions.md): The options of a `workspace()` with no `input`: it starts with any input.
+- [`PermissiveNoSlotWorkspaceOptions`](type-permissivenoslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
+- [`WorkspaceHandles`](type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot.
+- [`ExecOutcome`](type-execoutcome.md): How an exec ended.
+- [`Unknown`](type-unknown.md): The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
+- [`Arg`](type-arg.md): One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it.
+- [`CommandOptions`](type-commandoptions.md): The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its output it keeps, its Effect secrets, and the commit it runs against.
+- [`CommandInput`](type-commandinput.md): A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`); none when there is neither.
+- [`OpenCommandInput`](type-opencommandinput.md): The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds, and with `pin`, the commit (`{ sha }`).
+- [`Secret`](type-secret.md): What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`.
+- [`Text`](type-text.md): What the `text` template gives: a string of literal text and Effect secrets, in order.
+- [`FromInput`](type-frominput.md): A value of a file body's part: as written, or from the Effect's input.
+- [`FileBody`](type-filebody.md): `file(path, { segments?, contentType? })`: a Worktree file as an `http` body.
+- [`HttpDefinition`](type-httpdefinition.md): An `http` Effect's definition.
+- [`HttpFileInput`](type-httpfileinput.md): The input of an `http` Effect with a Worktree file as its body.
+- [`OpenSecret`](type-opensecret.md): `secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and leaves for its composer to name (ADR-0054).
+- [`PushOptions`](type-pushoptions.md): The options of `push()`.
+- [`PushInput`](type-pushinput.md): The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and `{ message }` with `squash`.
+- [`NameStart`](type-namestart.md): What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path.
+- [`DispatchDefinition`](type-dispatchdefinition.md): The definition of a `dispatch` Effect (ADR-0071).
+- [`DispatchInput`](type-dispatchinput.md): A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
+- [`DispatchOpenParts`](type-dispatchopenparts.md): The Open part a dispatch definition states: its target, when it is `open`.
+- [`McpNotReturned`](type-mcpnotreturned.md): The outcomes that an `mcp` Effect gives besides `returned`.
+- [`ChainLink`](type-chainlink.md): One reply since the pick, as the author reads it.
+- [`SteerArgs`](type-steerargs.md): The arguments a `steer` text or `from` function gets: the Machine's context and the event that the transition takes.
+- [`Sender`](type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
+- [`Quantity`](type-quantity.md): A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory).
+- [`Carry`](type-carry.md): What `carry(item)` gives.
+- [`PoolSpec`](type-poolspec.md): What you pass to `pool()` with a child Machine as its worker.
+- [`StandingPoolSpec`](type-standingpoolspec.md): What you pass to `pool()` for a Pool of runs.
+- [`Reread`](type-reread.md): What `reread()` gives.
+- [`Skip`](type-skip.md): What `skip(reason)` gives: the delivery brings nothing, and the reason says why.
+- [`SourceSpec`](type-sourcespec.md): A pull Source.
+- [`SourceHooks`](type-sourcehooks.md): A Source's handlers, by Hook kind and event key.
+- [`PushSourceSpec`](type-pushsourcespec.md): A push Source.
+- [`ReadSourceSpec`](type-readsourcespec.md): A read Source.
+- [`OpenBodyLogic`](type-openbodylogic.md): The logic `openBody()` returns: actor logic that carries the brand.
+- [`Lends`](type-lends.md): The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`, `actions` and `delays`.
+- [`Ceilings`](type-ceilings.md): The limits that an Open body sets on its Chart.
+- [`ChartText`](type-charttext.md): The Chart text (ADR-0070).
+- [`DeliveredEvent`](type-deliveredevent.md): A workflow event as delivered into a Machine: the def's name as `type`, plus its payload.
+- [`Caller`](type-caller.md): A request's Caller (ADR-0078): who acts, through which authenticator, and what it may do.
+- [`FailureInput`](type-failureinput.md): What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader.
+- [`SandboxOptions`](type-sandboxoptions.md): The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
+- [`SlotHandles`](type-slothandles.md): The handles of a Workspace that declares Repo Slots.
+- [`CommandEnv`](type-commandenv.md): The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a file that holds it.
+- [`TextPart`](type-textpart.md): One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret.
+- [`HttpMethod`](type-httpmethod.md): The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.
+- [`HttpRequestParts`](type-httprequestparts.md): What the `request` of an `http` definition returns: the part of the request that changes for each run.
+- [`NamedSecret`](type-namedsecret.md): A secret bound to a name, never `secret(open)`.
+- [`SenderCallerField`](type-sendercallerfield.md): A field of a `Sender`'s Caller that jr2 can verify.
+- [`SourceNextResult`](type-sourcenextresult.md): What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready now; or `{ item, open }`, where `open` is the number of items that exist but are not ready.
+- [`SourceIn`](type-sourcein.md): What a Source's handler reads beside `payload`.
+- [`OpenBodySlot`](type-openbodyslot.md): The brand an Open body slot carries, as `definition` marks an Agent slot (ADR-0049).
+- [`ChartJson`](type-chartjson.md): Plain JSON.
+- [`ChartEvent`](type-chartevent.md): An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
+- [`ChartAgent`](type-chartagent.md): An Agent a Chart mints: the plain fields of an Agent definition (ADR-0049).
+- [`ChartState`](type-chartstate.md): A state node.
+- [`ChartValue`](type-chartvalue.md): A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be `{ "$ref": "<root>.<path>" }`.
+- [`ChartInvoke`](type-chartinvoke.md): An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`.
+- [`ChartTransitions`](type-charttransitions.md): One transition or a list, in xstate's order.
+- [`ChartAction`](type-chartaction.md): An action.
+- [`ChartTransition`](type-charttransition.md): A transition: a target alone, or the object form.
+- [`ChartGuard`](type-chartguard.md): A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or `not`/`and`/`or`.
+
+**Type plumbing.** These types compute a type from the types of a Machine or of its parts. A workflow module does not write them. Each has a page with its declaration:
+
+- [`ToProvidedActor`](type-toprovidedactor.md)
+- [`MergedActors`](type-mergedactors.md)
+- [`ToParameterizedObject`](type-toparameterizedobject.md)
+- [`BindActors`](type-bindactors.md)
+- [`SentByGuards`](type-sentbyguards.md)
+- [`GateHooks`](type-gatehooks.md)
+- [`EventFrom`](type-eventfrom.md)
+- [`LookOutput`](type-lookoutput.md)
+- [`AgentLogic`](type-agentlogic.md)
+- [`BodyAcceptsDoor`](type-bodyacceptsdoor.md)
+- [`WorkspaceMachine`](type-workspacemachine.md)
+- [`DoorlessInput`](type-doorlessinput.md)
+- [`BodyAcceptsSlots`](type-bodyacceptsslots.md)
+- [`EffectLogic`](type-effectlogic.md)
+- [`OpenOf`](type-openof.md)
+- [`EnvOpenParts`](type-envopenparts.md)
+- [`OpenEffect`](type-openeffect.md)
+- [`MarkedIf`](type-markedif.md)
+- [`HttpOpenParts`](type-httpopenparts.md)
+- [`HttpInput`](type-httpinput.md)
+- [`PushWireOutput`](type-pushwireoutput.md)
+- [`SyncState`](type-syncstate.md)
+- [`AnswerAction`](type-answeraction.md)
+- [`AgentSlots`](type-agentslots.md)
+- [`Reached`](type-reached.md)
+- [`OpenEffectSlots`](type-openeffectslots.md)
+- [`BindingOf`](type-bindingof.md)
+- [`LogicAt`](type-logicat.md)
+- [`GateSlots`](type-gateslots.md)
+- [`GateBinding`](type-gatebinding.md)
+- [`GateTypesAt`](type-gatetypesat.md)
+- [`ChildSlots`](type-childslots.md)
+- [`ChildAt`](type-childat.md)
+- [`RepoSlotsOf`](type-reposlotsof.md)
+- [`WorkspaceOf`](type-workspaceof.md)
+- [`PoolMachine`](type-poolmachine.md)
+- [`StandingPoolMachine`](type-standingpoolmachine.md)
+- [`GateSlotInput`](type-gateslotinput.md)
+- [`GateSlotParts`](type-gateslotparts.md)
+- [`ArgNames`](type-argnames.md)
+- [`WorktreeKey`](type-worktreekey.md)
+- [`NotWorktreeKeys`](type-notworktreekeys.md)
+- [`OpenSecretMark`](type-opensecretmark.md)
+
+These names come from a dependency: from `zod`, `z.ZodObject`, `z.output`, `z.infer`, `z.ZodType`; from `xstate`, `MachineContext`, `UnknownActorLogic`, `ParameterizedObject`, `NonReducibleUnknown`, `EventObject`, `MetaObject`, `ActionFunction`, `GuardPredicate`, `DelayConfig`, `SetupReturn`, `AnyActorLogic`, `InputFrom`, `AnyStateMachine`, `OutputFrom`, `ProvidedActor`, `AnyActorRef`, `CallbackActorLogic`, `PromiseActorLogic`.

package/docs/reference/authoring-surface/group-workspaces-and-repos.md

@@ -0,0 +1,15 @@
+---
+title: "Authoring surface: Workspaces and Repos"
+description: A Sandbox and the Repo Slots it binds (ADR-0012, ADR-0051).
+---
+
+# Authoring surface: Workspaces and Repos
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+A Sandbox and the Repo Slots it binds ([ADR-0012](../decisions/0012-workspace-wrapper-machine.md), [ADR-0051](../decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)).
+
+- [`workspace`](workspace.md) (function): Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot.
+- [`Workspaced`](type-workspaced.md) (type): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, the folder of each Repo Slot).
+- [`Binding`](type-binding.md) (type): The repository of a Repo Slot: `{ url, ref }`.
+- [`RepoSlot`](type-reposlot.md) (type): The value of one Repo Slot in `workspace({ repos })`.

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

@@ -5,7 +5,7 @@ description: "Make an `http` Effect: a call to a URL, with Effect secrets that t
 
 # `http`
 
-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.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 

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

@@ -5,7 +5,7 @@ description: Is this error a Failure, which a state invoked `fail` to make?
 
 # `isFailure`
 
-Function, in `@jr2/orchestrator/src/fail.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Failure.
+Function, in `@jr2/orchestrator/src/fail.ts`. It is an export of `@jr2/orchestrator`, in the [Failure](group-failure.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function isFailure(error: unknown): error is Failure

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

@@ -5,7 +5,7 @@ description: Is it `ready`?
 
 # `isReady`
 
-Constant, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Constant, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const isReady: <O extends { outcome: string; }>(output: O) => output is Extract<O, { outcome: "ready"; }>

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

@@ -5,7 +5,7 @@ description: "Set up a Machine that takes workflow events: the jr2 form of xstat
 
 # `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.
+Function, in `@jr2/orchestrator/src/setup.ts`. It is an export of `@jr2/orchestrator`, in the [Machine and events](group-machine-and-events.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function jr2Setup<
@@ -83,7 +83,9 @@ What it adds to `setup()`:
   `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" }`.
+- The `gate` actor is ready to invoke by name: `invoke: { src: "gate" }`. A Gate slot that hears a
+  Hook (`actors: { review: gate({ … }) }`) is invoked by its key. An event in its `delivers` whose
+  def leaves `audience` unset is `audience: "external"` in this Machine.
 - 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
@@ -140,6 +142,13 @@ has no `output` (see the list below).
   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)).
+- an event in a Gate slot's `delivers` that `events` does not list: ``machine "<id>": Gate slot
+  "<slot>" delivers "<name>", which no def in jr2Setup({ events }) declares (declared: <names>) —
+  list it in events (ADR-0011)``
+- an event in a Gate slot's `delivers` that the Gate does not accept at a state that invokes it:
+  ``machine "<id>": state "<state>" invokes Gate slot "<slot>", which delivers "<name>", and its
+  Gate does not accept it (accepts: <names>) — no handler or look could deliver it: handle it on
+  that state, a state above it or a plain child, or drop it from delivers (ADR-0011)``
 
 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
@@ -170,7 +179,8 @@ are legal but probably not what you mean, such as a mode that nothing enters, ar
   - `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.
+    (`command(…)`, `http(…)`, `push(…)`), Gate slots (`gate({ … })`), 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>; }`
 

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

@@ -0,0 +1,107 @@
+---
+title: mcp
+description: "The `mcp` Effects (ADR-0067, ADR-0079): `mcp.call(server, tool, { input })` calls a tool, `mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a prompt."
+---
+
+# `mcp`
+
+Constant, in `@jr2/orchestrator/src/mcp-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+const mcp: { readonly call: typeof call; readonly read: typeof read; readonly prompt: typeof prompt; }
+```
+
+The `mcp` Effects ([ADR-0067](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), [ADR-0079](../decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)): `mcp.call(server, tool, { input })` calls a tool,
+`mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a
+prompt. Each one is an Effect that the Machine runs, with no model, in the Instance Effector.
+Put it in `actors`, and invoke it by its key.
+
+`server` is a name of the `mcp` block of `jr2.config.ts`: a remote server, whose url and secret
+are the config's. The Instance Effector holds that secret as an Effect secret, and sends it as
+`Authorization: Bearer <value>`. The Agent and the Orchestrator never read it. `jr2 up` refuses
+a server that the `mcp` block does not declare, and a stdio server. `server`, and a call's
+`tool`, can each be `open`: the composer binds them one time with `customize(machine, { effects:
+{ <slot>: { server, tool } } })`.
+
+Every outcome is output ([`McpCallOutput`](type-mcpcalloutput.md), [`McpReadOutput`](type-mcpreadoutput.md)): `returned`, `refused`,
+`unreachable`, `input-required` or `unknown`. jr2 sends the request at most one time, unless you
+mark it `idempotent`. jr2 does not read the tool's `idempotentHint`.
+
+An Agent that holds a server's tools (its `mcp` list) calls them with no approval. When a call
+needs an approval, the Machine makes it: the Agent picks, a Gate waits for a person, and the
+Effect makes the call. The Effect's output is the pick's answer.
+
+**Example**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, gate, jr2Setup, mcp } from "@jr2/orchestrator";
+
+const postMessage = defineEvent({
+  name: "post_message",
+  description: "Post one message to the team's channel. A person approves it first.",
+  input: z.object({ text: z.string() }),
+});
+const approve = defineEvent({ name: "approve", input: z.object({ by: z.string() }) });
+const reject = defineEvent({ name: "reject", input: z.object({ by: z.string() }) });
+
+export const machine = jr2Setup({
+  types: {} as { context: { text: string } },
+  events: [postMessage, approve, reject],
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You write the release note for the team.",
+      workspace: "none",
+    }),
+    // A person answers it, in the Console or with `jr2 answer`.
+    approval: gate({ meta: z.object({ text: z.string() }), delivers: [approve, reject], look: "none" }),
+    // "slack-acme" is a remote server of the mcp block of jr2.config.ts.
+    post: mcp.call("slack-acme", "post_message", {
+      input: z.object({ channel: z.string(), text: z.string() }),
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "release-note",
+  context: { text: "" },
+  on: { "agent.fault": ".failed" },
+  initial: "writing",
+  states: {
+    writing: {
+      invoke: { src: "writer", input: { prompt: "Write the release note, then post it." } },
+      initial: "ready",
+      states: {
+        ready: {
+          on: {
+            post_message: { target: "approving", actions: assign({ text: ({ event }) => event.text }) },
+          },
+        },
+        approving: {
+          invoke: { src: "approval", input: ({ context }) => ({ meta: { text: context.text } }) },
+          on: { approve: "posting", reject: "ready" },
+        },
+        posting: {
+          invoke: {
+            src: "post",
+            input: ({ context }) => ({ channel: "#releases", text: context.text }),
+            // On another outcome, the Agent reads the output as the answer to its pick.
+            onDone: [
+              { guard: ({ event }) => event.output.outcome === "returned" && !event.output.isError, target: "#posted" },
+              { target: "ready" },
+            ],
+          },
+        },
+      },
+    },
+    posted: { id: "posted", type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [ADR-0079: An Agent holds MCP tools, a Machine calls them as an Effect, and the Machine is the approval](../decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md)

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

@@ -5,7 +5,7 @@ description: "Leave a part of a Machine Open: for the Instance that registers th
 
 # `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.
+Constant, in `@jr2/orchestrator/src/open.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const open: unique symbol
@@ -17,12 +17,14 @@ 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)`.
+- the secret of an Effect's auth, of a header, or of a command's `env`: `secret(open)`;
+- the look of a Gate slot: `gate({ …, look: 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.
+Open part. An Open look is the one exception: `jr2 up` warns about it and does not refuse,
+because a person can still answer the Gate with `jr2 send`.
 
 **Example**
 

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

@@ -5,7 +5,7 @@ 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.
+Function, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function openBody(decl: OpenBodyDeclaration): OpenBodyLogic

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

@@ -5,7 +5,7 @@ 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.
+Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function paramsOf<