@jr2/orchestrator 0.5.1 → 0.7.0

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,9 @@ 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
 
 ```ts
 function http<
@@ -14,8 +16,8 @@ function http<
   const A extends HttpDefinition<S>["auth"] = undefined,
   const H extends HttpDefinition<S>["headers"] = undefined,
 >(
-  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H },
-): EffectLogic<HttpInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
+  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H; body: FileBody<S> },
+): EffectLogic<HttpFileInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
 ```
 
 Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads. Put it
@@ -23,8 +25,9 @@ in `actors`, and invoke it by its key: `actors: { comment: http({ ... }) }`, the
 src: "comment" }`.
 
 It runs in the Instance Effector, which `jr2 up` deploys when a Machine has an `http` Effect.
-With `body: file(...)`, it runs in the Sandbox Effector of the Workspace whose body invokes it.
-The Effector makes the call. The Orchestrator holds no secret.
+With `body: file(...)`, it runs in the Sandbox Effector of the Workspace whose body invokes it,
+and under Repo Slots its input names the Worktree in `worktree`. The Effector makes the call. The
+Orchestrator holds no secret.
 
 Every outcome is output (`HttpOutput`): `response`, `unreachable`, `refused` or `unknown`. A 4xx
 or 5xx status is output too. jr2 sends the call at most one time, unless you mark it
@@ -91,12 +94,15 @@ customize() share: actors: { <name>: http(...) }, then invoke: { src: "<name>" }
     A function that makes the part of the request that changes for each run, from the input:
     `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
     Effect secret. Do not write it beside `body`.
-  - `body` (optional): `FileBody<S>`
+  - `body`: `FileBody<S>`
 
-    A Worktree file as the body: `file(path, { slot?, segments?, contentType? })`. The Effect then
-    runs in the Sandbox Effector of its Workspace. Do not write `request` beside it: the `segments`
+    A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+    runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+    input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+    it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+    input names no `worktree` ``. Do not write `request` beside it: the `segments`
     of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
-    slot?, segments?, contentType? }) — json and text come from `request` ``.
+    segments?, contentType? }) — json and text come from `request` ``.
   - `timeout` (optional): [`Duration`](type-duration.md)
 
     How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
@@ -157,3 +163,97 @@ export const machine = jr2Setup({
 - [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-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)
+
+## Overload 2
+
+```ts
+function http<
+  S extends z.ZodType | undefined = undefined,
+  const U extends HttpDefinition<S>["url"] = string,
+  const A extends HttpDefinition<S>["auth"] = undefined,
+  const H extends HttpDefinition<S>["headers"] = undefined,
+>(
+  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H },
+): EffectLogic<HttpInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
+```
+
+**Parameters**
+
+- `def`
+
+  - `method`: [`HttpMethod`](type-httpmethod.md)
+
+    The HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. It refuses
+    another: `http({ method: "<method>" }): the method is one of GET, HEAD, POST, PUT, PATCH,
+    DELETE, OPTIONS`.
+  - `url`: `string | Text | typeof open`
+
+    The url: `http://` or `https://`, then a literal host. No input, param or Effect secret can
+    change where the call goes. An Effect secret can be only in the path:
+    `` text`https://api.telegram.org/bot${secret("tg")}/sendMessage` ``.
+
+    Or `open`: a packaged Machine that cannot know the host leaves the url Open, and the composer
+    binds it one time with `customize(machine, { effects: { <slot>: { url } } })`.
+
+    It refuses:
+    - a scheme or host that is not literal: `` http({ url }): the url is an http:// or https:// url
+      whose scheme and host are literal — a secret may sit only in its path, after a "/":
+      text`https://api.example.com/bot${secret("tg")}/send` (ADR-0068) ``
+    - an Effect secret after `?` or `#`: `` http({ url }): secret("<name>") sits in the url's query
+      or fragment — a secret may sit only in its path; send it in `auth` or a header instead:
+      headers: { "x-api-key": text`${secret("...")}` } (ADR-0068) ``
+    - a host that is not a host: `http({ url }): "<scheme>://<host>" is not a host`
+    - a user name or password in the url: ``http({ url }): the url carries userinfo — use `auth` ``
+  - `headers` (optional): `Readonly<Record<string, string | Text>>`
+
+    Headers that are the same for each run. Each name is lowercase. A value is a string, or a
+    `text` with an Effect secret.
+
+    It refuses:
+    - a name that is not lowercase, or that frames or routes the request (`host`,
+      `content-length`, `transfer-encoding`, `connection`, `upgrade`, `te`, `trailer`,
+      `keep-alive`, `proxy-*`): `http({ headers }): "<name>" is not a header an Effect sets — a
+      lowercase name that does not frame or route the request (ADR-0068)`
+    - an `authorization` header beside `auth`: ``http({ headers }): "authorization" is set by
+      `auth` — write one of them``
+  - `auth` (optional): `{ readonly bearer: Secret; } | { readonly basic: { user: Text; password: Text; }; } | Text`
+
+    The `Authorization` header: `bearer(secret("x"))`, `basic(user, password)`, or a `text` that
+    is the whole value.
+  - `input` (optional): `S`
+
+    The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+    gives it. jr2 parses the input with it before the call. When it starts, input that does not
+    agree with it makes the Effect fail (its `onError` route): `http "<slot>": its input does not
+    match the definition's input schema — <path>: <message>`, one `<path>: <message>` for each
+    problem, joined by `; `.
+  - `request` (optional): `(input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts`
+
+    A function that makes the part of the request that changes for each run, from the input:
+    `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
+    Effect secret. Do not write it beside `body`.
+  - `body` (optional): `FileBody<S>`
+
+    A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+    runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+    input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+    it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+    input names no `worktree` ``. Do not write `request` beside it: the `segments`
+    of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
+    segments?, contentType? }) — json and text come from `request` ``.
+  - `timeout` (optional): [`Duration`](type-duration.md)
+
+    How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
+    `"30s"`. With no answer in that time, the output is `unknown`. It refuses a value that is not
+    a positive duration: `http: timeout "<timeout>" is not a positive duration (like "30s",
+    "2m")`.
+  - `maxBody` (optional): `number`
+
+    The largest number of bytes of a text response body that the output keeps. Default 65536.
+    When jr2 cuts the body, `truncated` is `true`. It refuses a value that is not a positive whole
+    number: `http({ maxBody }): a positive number of bytes`.
+  - `idempotent` (optional): `boolean`
+
+    `true` when it is safe to send the call two times: it has its own idempotency key, or it only
+    reads. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the call went
+    out. Then it sends an idempotent call again, and gives any other call the output `unknown`.

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

@@ -0,0 +1,14 @@
+---
+title: isReady
+description: Is it `ready`?
+---
+
+# `isReady`
+
+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"; }>
+```
+
+Is it `ready`? For a guard. A Chart's form is the guard `jr2.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<
@@ -60,7 +60,7 @@ function jr2Setup<
 ): SetupReturn<
   TContext,
   WorkflowEvent<TDefs>,
-  MergedActors<TActors>,
+  MergedActors<BindActors<TActors, TInput, TContext>>,
   {},
   TActions,
   TGuards & SentByGuards,
@@ -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)