@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/reference/authoring-surface/type-customize.md

@@ -5,7 +5,7 @@ description: "The parts of one Machine that `customize()` can retune: its Agents
 
 # `Customize`
 
-Type, in `@jr2/orchestrator/src/customize.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Type, in `@jr2/orchestrator/src/customize.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type Customize<M extends AnyStateMachine> = {
@@ -15,6 +15,14 @@ type Customize<M extends AnyStateMachine> = {
   effects?: [OpenEffectSlots<Reached<M>>] extends [never]
     ? never
     : { [K in OpenEffectSlots<Reached<M>>]?: BindingOf<LogicAt<Reached<M>, K>> };
+  gates?: [GateSlots<Reached<M>>] extends [never]
+    ? never
+    : {
+        [K in GateSlots<Reached<M>>]?: GateBinding<
+          GateTypesAt<Reached<M>, K>["meta"],
+          GateTypesAt<Reached<M>, K>["ev"]
+        >;
+      };
   actors?: [ChildSlots<Reached<M>>] extends [never]
     ? never
     : { [K in ChildSlots<Reached<M>>]?: Customize<ChildAt<Reached<M>, K>> };
@@ -54,6 +62,13 @@ Every key is optional. Write only what you change.
   whose target is Open. For an Effect with two Open parts, one object holds both keys, and
   a binding that leaves one out does not compile. Only Effects with an Open part are offered.
   See [`EffectBinding`](type-effectbinding.md) for the values and the refusals.
+- `gates` (optional): `[ GateSlots<Reached<M>> ] extends [ never ] ? never : { [K in GateSlots<Reached<M>>]?: GateBinding<GateTypesAt<Reached<M>, K>["meta"], GateTypesAt<Reached<M>, K>["ev"]>; }`
+
+  Bind the look of a Gate slot (`gate({ … })`) that a package left `open`, and add, replace or
+  remove its handlers by Hook kind id and event key (`null` removes one), by slot name:
+  `{ review: { look, hooks: { gitlab: { "note.MergeRequest": null } } } }`. At run time,
+  `customize()` refuses a slot that holds no Gate slot: `customize(): machine "<id>" carries no
+  Gate slot "<slot>" — its Gate slots are: <slots>`.
 - `actors` (optional): `[ ChildSlots<Reached<M>> ] extends [ never ] ? never : { [K in ChildSlots<Reached<M>>]?: Customize<ChildAt<Reached<M>, K>>; }`
 
   Retune a Machine that this Machine composes, by slot name. The value has the same shape as

package/docs/reference/authoring-surface/type-delivered.md

@@ -0,0 +1,17 @@
+---
+title: Delivered
+description: "One plain event of a list of defs: `{ type: \"approve\", by }`."
+---
+
+# `Delivered`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is an export of `@jr2/orchestrator`, in the [Gates](group-gates.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type Delivered<D extends readonly EventDef[]> = {
+  [K in keyof D]: D[K] extends EventDef ? EventFrom<D[K]> : never;
+}[number];
+```
+
+One plain event of a list of defs: `{ type: "approve", by }`. What a handler, a look's `until`
+and a Gate's `reply` see.

package/docs/reference/authoring-surface/type-deliveredevent.md

@@ -0,0 +1,18 @@
+---
+title: DeliveredEvent
+description: "A workflow event as delivered into a Machine: the def's name as `type`, plus its payload."
+---
+
+# `DeliveredEvent`
+
+Type, in `@jr2/orchestrator/src/registration.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type DeliveredEvent = { type: string } & Record<string, unknown>;
+```
+
+A workflow event as delivered into a Machine: the def's name as `type`, plus its payload.
+
+**Fields**
+
+- `type`: `string`

package/docs/reference/authoring-surface/type-dispatchdefinition.md

@@ -34,6 +34,7 @@ The definition of a `dispatch` Effect ([ADR-0071](../decisions/0071-a-run-starts
   How long the Effect waits: by default 30s for the start, and 10m with `wait`.
 - `target` (optional): `{ url: string; token: NamedSecret; } | typeof open`
 
-  A different Orchestrator: `url` is its origin, and `token` is the secret that holds its
-  Instance token. Or `open`, which the composer binds with `customize(<import>, { effects: {
-  <slot>: { target: { url, token } } } })`. Without it, the run starts in this Orchestrator.
+  A different Orchestrator: `url` is its origin, and `token` is the secret that holds the token
+  of a Caller of it with `start` for the Workflow, and `read` too when `wait` is true. Or `open`,
+  which the composer binds with `customize(<import>, { effects: { <slot>: { target: { url, token
+  } } } })`. Without it, the run starts in this Orchestrator.

package/docs/reference/authoring-surface/type-dispatchoutput.md

@@ -5,7 +5,7 @@ description: The output of a `dispatch` Effect.
 
 # `DispatchOutput`
 
-Type, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/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
 type DispatchOutput =

package/docs/reference/authoring-surface/type-effectbinding.md

@@ -5,7 +5,7 @@ description: The values that bind the Open parts of one Effect.
 
 # `EffectBinding`
 
-Type, in `@jr2/orchestrator/src/open-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Type, in `@jr2/orchestrator/src/open-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type EffectBinding = {
@@ -13,13 +13,16 @@ type EffectBinding = {
   readonly argv?: readonly (string | Arg)[];
   readonly secret?: string;
   readonly target?: { readonly url: string; readonly token: Secret };
+  readonly server?: string;
+  readonly tool?: string;
 };
 ```
 
 The values that bind the Open parts of one Effect. A packaged Machine leaves a part of an Effect
 Open when it cannot know it. That part is the url of an `http` Effect, the argv of a `command`,
 the name of a secret, written `secret(open)`, or the target of a `dispatch`: the url of another
-Orchestrator and the secret that holds its Instance token, bound as one. You bind it once, where you register the
+Orchestrator and the secret that holds its Instance token, bound as one, or the server or the tool
+of an `mcp` Effect. You bind it once, where you register the
 Machine, with `customize(machine, { effects: { <slot>: binding } })`. Each key binds one Open
 part. For an Effect with two Open parts, one object holds both keys.
 
@@ -63,6 +66,13 @@ check that a part written in the definition gets.
 
   - `url`: `string`
   - `token`: [`Secret`](type-secret.md)
+- `server` (optional): `string`
+
+  The server of an `mcp` Effect whose server is Open: a name of the `mcp` block of
+  `jr2.config.ts`. The server's url and its secret are the config's.
+- `tool` (optional): `string`
+
+  The tool of an `mcp.call` Effect whose tool is Open: a tool name of the server.
 
 **Example**
 

package/docs/reference/authoring-surface/type-framepath.md

@@ -5,7 +5,7 @@ description: "A Turn's Frame in a Workspace with the Repo Slots `S`."
 
 # `FramePath`
 
-Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, 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
 type FramePath<S extends string> = WorktreePath<S> | "/work";

package/docs/reference/authoring-surface/type-gatebinding.md

@@ -0,0 +1,15 @@
+---
+title: GateBinding
+description: A type that the Authoring surface names.
+---
+
+# `GateBinding`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type GateBinding<Meta, Ev> = {
+  readonly look?: GateLook<Meta, Ev> | "none";
+  readonly hooks?: GateHooksPatch<Meta, Ev>;
+};
+```

package/docs/reference/authoring-surface/type-gatehooks.md

@@ -0,0 +1,12 @@
+---
+title: GateHooks
+description: A type that the Authoring surface names.
+---
+
+# `GateHooks`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type GateHooks<Meta, Ev> = KindHooks<GateIn<Meta>, Ev | undefined>;
+```

package/docs/reference/authoring-surface/type-gatelook.md

@@ -0,0 +1,37 @@
+---
+title: GateLook
+description: "A Gate's read of the fact that it waits for (ADR-0011)."
+---
+
+# `GateLook`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is an export of `@jr2/orchestrator`, in the [Gates](group-gates.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type GateLook<Meta, Ev, R extends AnyActorLogic = AnyActorLogic> = {
+  readonly read: R;
+  readonly input: (meta: Meta) => InputFrom<R>;
+  readonly every?: Duration;
+  readonly until: (output: LookOutput<R>, meta: Meta) => Ev | undefined;
+};
+```
+
+A Gate's read of the fact that it waits for ([ADR-0011](../decisions/0011-workflow-defined-events.md)).
+
+- `read`: an `http` Effect marked `idempotent: true`, or a promise actor (`fromPromise`), which the
+  Machine can invoke anyway and which a restore runs again. `gate()` refuses any other logic.
+- `input`: the read's input, from the Gate's meta.
+- `every`: how often the Gate looks again while it is open. Default: `"10m"`.
+- `until`: the read's output as one event of `delivers`, or `undefined` for "not yet". Pure and
+  synchronous, as a guard is.
+
+The look runs once after the Gate registers, again after each restore, and every `every` while the
+Gate is open. It stops after the run takes its event, until the Gate opens again. A looked event
+has the Gate as its Sender and no Caller, and the feed marks it `looked`.
+
+**Fields**
+
+- `read`: `R`
+- `input`: `(meta: Meta) => InputFrom<R>`
+- `every` (optional): [`Duration`](type-duration.md)
+- `until`: `(output: LookOutput<R>, meta: Meta) => Ev | undefined`

package/docs/reference/authoring-surface/type-gateoutcome.md

@@ -0,0 +1,32 @@
+---
+title: GateOutcome
+description: What a delivery did at one open Gate.
+---
+
+# `GateOutcome`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is an export of `@jr2/orchestrator`, in the [Gates](group-gates.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type GateOutcome<Ev> =
+  | { readonly state: "delivered"; readonly event: Ev; readonly run: string }
+  | { readonly state: "refused"; readonly event?: Ev; readonly reason: string; readonly run: string };
+```
+
+What a delivery did at one open Gate. The run took the event, or it did not: the handler threw,
+its event is not in `delivers`, or the run does not take it now. A Gate whose handler gave
+`undefined` was not a target, and its `reply` does not run.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `state`, `event`, `run`
+
+  - `state`: `"delivered"`
+  - `event`: `Ev`
+  - `run`: `string`
+- Form 2: `state`, `event`, `reason`, `run`
+
+  - `state`: `"refused"`
+  - `event` (optional): `Ev`
+  - `reason`: `string`
+  - `run`: `string`

package/docs/reference/authoring-surface/type-gatereply.md

@@ -0,0 +1,19 @@
+---
+title: GateReply
+description: The text that the person who acted reads.
+---
+
+# `GateReply`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is an export of `@jr2/orchestrator`, in the [Gates](group-gates.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type GateReply<Meta, Ev> = (
+  outcome: GateOutcome<Ev>,
+  at: { readonly meta: Meta; readonly caller: CallerRecord },
+) => string | undefined;
+```
+
+The text that the person who acted reads. Plain text: the Hook kind
+escapes it and puts it in its envelope. Pure and synchronous. `undefined` or `""`: this Gate says
+nothing. It runs only for a delivery whose answer a person reads (`slack`, `discord`).

package/docs/reference/authoring-surface/type-gateslot.md

@@ -0,0 +1,21 @@
+---
+title: GateSlot
+description: A Gate with parts that the Machine carries.
+---
+
+# `GateSlot`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type GateSlot<Meta, Ev> = CallbackActorLogic<
+  DeliveredEvent,
+  {} extends Meta ? GateSlotInput<Meta> | undefined : GateSlotInput<Meta>
+> & {
+  readonly gateSlot: GateSlotParts;
+  readonly [gateSlotMark]?: { readonly meta: Meta; readonly ev: Ev };
+};
+```
+
+A Gate with parts that the Machine carries. Put it in `actors` and invoke it by its key. The
+brand `gateSlot` holds its parts.

package/docs/reference/authoring-surface/type-gateslotinput.md

@@ -0,0 +1,13 @@
+---
+title: GateSlotInput
+description: A type that the Authoring surface names.
+---
+
+# `GateSlotInput`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type GateSlotInput<Meta> = Omit<GateInput, "meta"> &
+  ({} extends Meta ? { readonly meta?: Meta } : { readonly meta: Meta });
+```

package/docs/reference/authoring-surface/type-gateslotparts.md

@@ -0,0 +1,18 @@
+---
+title: GateSlotParts
+description: A type that the Authoring surface names.
+---
+
+# `GateSlotParts`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type GateSlotParts = {
+  readonly meta?: z.ZodType;
+  readonly delivers: readonly EventDef[];
+  readonly hooks: Readonly<Record<string, Readonly<Record<string, AnyHandler>>>>;
+  readonly look?: LooseLook | typeof open | "none";
+  readonly reply?: (outcome: GateOutcome<DeliveredEvent>, at: { meta: unknown; caller: CallerRecord }) => unknown;
+};
+```

package/docs/reference/authoring-surface/type-gateslots.md

@@ -0,0 +1,12 @@
+---
+title: GateSlots
+description: A type that the Authoring surface names.
+---
+
+# `GateSlots`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type GateSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: GateSlot<any, any> }>["src"];
+```

package/docs/reference/authoring-surface/type-gatetypesat.md

@@ -0,0 +1,13 @@
+---
+title: GateTypesAt
+description: A type that the Authoring surface names.
+---
+
+# `GateTypesAt`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type GateTypesAt<M extends AnyStateMachine, K extends string> =
+  LogicAt<M, K> extends GateSlot<infer Meta, infer Ev> ? { meta: Meta; ev: Ev } : never;
+```

package/docs/reference/authoring-surface/type-hostinjectedinput.md

@@ -5,7 +5,7 @@ description: The fields that jr2 adds to the input of the Machine that a run sta
 
 # `HostInjectedInput`
 
-Type, in `@jr2/orchestrator/src/vocabulary.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+Type, in `@jr2/orchestrator/src/vocabulary.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
 type HostInjectedInput = { instanceId: string };

package/docs/reference/authoring-surface/type-httpoutput.md

@@ -5,7 +5,7 @@ description: "The output of an `http` Effect: what the `onDone` of its state get
 
 # `HttpOutput`
 
-Type, in `@jr2/orchestrator/src/effector-wire.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/effector-wire.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type HttpOutput = LaterOutcome | {

package/docs/reference/authoring-surface/type-jr2config.md

@@ -5,7 +5,7 @@ description: "The shape of `jr2.config.ts`: the deployment facts of an Instance,
 
 # `JR2Config`
 
-Type, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Config.
+Type, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, in the [Config](group-config.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type JR2Config = {
@@ -15,6 +15,11 @@ type JR2Config = {
   harness?: HarnessConfig;
   sandbox?: SandboxConfig;
   priorityClasses?: PriorityClasses;
+  callers?: CallersConfig;
+  cors?: readonly string[];
+  hooks?: Readonly<Record<string, Hook>>;
+  mcp?: Readonly<Record<string, McpServer>>;
+  runs?: RunsConfig;
   registry?: string;
   kitRegistry?: string;
   platforms?: readonly string[];
@@ -32,7 +37,7 @@ Sandbox Image: a Machine names those itself.
 Every field is optional, and an Instance can run with no `jr2.config.ts`. Write the file as
 `export default defineConfig({ … })`. When the config loads, a file with no default export is
 refused: `` <file> has no default export (use `export default defineConfig({…})`) ``. The load also
-checks the shape of `git.credentials`, `secrets`, `harness.catalog` and `priorityClasses`. It
+checks the shape of `git.credentials`, `secrets`, `harness.catalog`, `priorityClasses` and `mcp`. It
 checks that `sandbox` is an object, and checks its `resources`. Each refusal names the field.
 `jr2 up` checks the rest.
 
@@ -67,6 +72,36 @@ checks that `sandbox` is an object, and checks its `resources`. Each refusal nam
 
   Existing PriorityClasses to use in place of the two that `jr2 up` creates. See
   [`PriorityClasses`](../config.md#priorityclasses).
+- `callers` (optional): [`CallersConfig`](../config.md#callers)
+
+  The Callers that act on the Instance with a credential of their own, and what each may do.
+  Default: none; only the Instance token acts. See [`CallersConfig`](../config.md#callers).
+- `cors` (optional): `readonly string[]`
+
+  The origins from which a browser app may call the Instance's HTTP API, such as
+  `https://ops.example.com`. Each entry is an origin alone: a scheme, a host and an optional port,
+  with no path. Default: none. The Console is served from the Orchestrator's own origin, so it
+  needs no entry. The config load refuses an entry that is not an origin:
+  `<file> at cors[<i>]: <entry> is not an origin — scheme://host[:port], with no path`.
+- `hooks` (optional): `Readonly<Record<string, Hook>>`
+
+  The Hooks of the Instance, by name: each one is a door, `POST /hooks/<name>`, for one outside
+  service. A Hook's value comes from its kind's constructor, which the config imports:
+  `github({ secret: secret("GH_HOOK") })`, `gitlab({ secret: secret("GL_HOOK"), may })`,
+  `discord({ publicKey: "…" })`. `may.answer` names the Workflows whose Gates the Hook may answer,
+  every Workflow by default. A Hook never starts a run. A name has the rule of a Caller token's
+  name. When the config loads, a bad entry is refused: `<file> at hooks.<name>: <problem>`.
+  Default: none.
+- `mcp` (optional): `Readonly<Record<string, McpServer>>`
+
+  The MCP servers, by a name of yours: `[a-z][a-z0-9-]*`, not `jr2`. A remote server has a
+  `url` (`https://` with a secret), a `secret` (a name of the `secrets` list; with no `hosts`, it
+  is bound to the url's host) and a `timeout` (default `"60s"`). A stdio server has a `command`
+  of the Sandbox Image, its `args` and a `timeout`. An Agent names a server in its `mcp` list.
+  Default: none. See [`McpServer`](type-mcpserver.md).
+- `runs` (optional): [`RunsConfig`](type-runsconfig.md)
+
+  How long ended runs are kept, and the volume size. Default: `{ retain: "30d", volume: "5Gi" }`.
 - `registry` (optional): `string`
 
   The image registry prefix to which `jr2 up` pushes the images that it builds, such as

package/docs/reference/authoring-surface/type-lateroutcome.md

@@ -5,7 +5,7 @@ description: A value of `outcome` that this kit does not give.
 
 # `LaterOutcome`
 
-Type, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/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
 type LaterOutcome = { outcome: "(a later outcome)"; reason?: string };

package/docs/reference/authoring-surface/type-lends.md

@@ -12,6 +12,7 @@ type Lends = {
   agents?: string[];
   effects?: string[];
   machines?: string[];
+  gates?: string[];
   guards?: string[];
   actions?: string[];
   delays?: string[];
@@ -21,7 +22,9 @@ type Lends = {
 ```
 
 The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`,
-`actions` and `delays`. `gate: true` lends the Gate, so that a Chart can wait for an answer from
+`actions` and `delays`. `gates` lends Gate slots (`gate({ … })`) that hear a Hook, by slot name:
+the door refuses a Chart that invokes one whose `delivers` names an event that is not in the
+Chart's `events`. `gate: true` lends the Gate, so that a Chart can wait for an answer from
 outside the run. `fail: true` lends the Part that fails the run, so that a Chart can end its run
 as a Failure ([ADR-0073](../decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)): the Machine decides which ends a Chart can choose. A Chart can use no
 other part.
@@ -31,6 +34,7 @@ other part.
 - `agents` (optional): `string[]`
 - `effects` (optional): `string[]`
 - `machines` (optional): `string[]`
+- `gates` (optional): `string[]`
 - `guards` (optional): `string[]`
 - `actions` (optional): `string[]`
 - `delays` (optional): `string[]`

package/docs/reference/authoring-surface/type-lookoutput.md

@@ -0,0 +1,14 @@
+---
+title: LookOutput
+description: A type that the Authoring surface names.
+---
+
+# `LookOutput`
+
+Type, in `@jr2/orchestrator/src/gate.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type LookOutput<R> = R extends { getInitialSnapshot: (...a: never[]) => { output?: infer O } }
+  ? Exclude<O, undefined>
+  : unknown;
+```

package/docs/reference/authoring-surface/type-mcpcalloutput.md

@@ -0,0 +1,78 @@
+---
+title: McpCallOutput
+description: "The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`."
+---
+
+# `McpCallOutput`
+
+Type, in `@jr2/orchestrator/src/effector-wire.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type McpCallOutput =
+  | { outcome: "returned"; isError: boolean; text: string; structured?: unknown; truncated?: boolean }
+  | McpNotReturned;
+```
+
+The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`. Every
+outcome is output. Route on `outcome`:
+
+- `returned`: the server answered the call. `isError` is the tool's own `isError`: the tool ran
+  and says that it failed. `text` joins the text of the result's content; a part that is not text
+  is one line that names its type. `structured` is the result's `structuredContent`, when it has
+  one. `text` and `structured` each have the byte bound of the Effect's `maxBody`: past it, jr2
+  cuts `text`, drops `structured`, and sets `truncated`.
+- `refused`: the request did not run. The server answered an HTTP 3xx or 4xx status (a 401 or a
+  403 included) at any step, the handshake too; it refused the handshake; or it answered the
+  request with the JSON-RPC error `-32700`, `-32600`, `-32601` or `-32602`: a request that it
+  could not read, an unknown method, an unknown tool, or bad arguments; or it answered a read with
+  `-32002`: the resource does not exist. It is also the Effector's
+  own refusal, with nothing sent: the server or its secret is not in its `effector.json`.
+- `unreachable`: nothing of the request was sent: the name did not resolve, or the connection,
+  TLS or the handshake failed otherwise (a 5xx, the timeout, an answer that is not MCP's, a
+  revision of MCP that jr2 does not speak).
+- `input-required`: the server asked for input, which jr2 does not give. After the error
+  `-32042`, the tool did not run. After an `elicitation/create` request, which comes while the
+  tool runs, the tool may have begun. jr2 does not send the request again: a Machine that
+  invokes the Effect again after a Gate can run a part of the tool two times.
+- `unknown`: the request was sent and no answer came (the timeout, a reset, a stream that ended
+  first), or the server answered with a 5xx or another JSON-RPC error. The tool may have acted.
+  jr2 does not send it again unless it is marked `idempotent`.
+
+jr2 replaces each value of an Effect secret that the Effector holds with `[secret:<name>]`, in
+every string of the output. The union is open ([`LaterOutcome`](type-lateroutcome.md)): give the rest a last arm
+with no guard.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `isError`, `text`, `structured`, `truncated`
+
+  - `outcome`: `"returned"`
+  - `isError`: `boolean`
+  - `text`: `string`
+  - `structured` (optional): `unknown`
+  - `truncated` (optional): `boolean`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"unreachable"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"input-required"`
+  - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 6: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**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/type-mcpnotreturned.md

@@ -0,0 +1,42 @@
+---
+title: McpNotReturned
+description: The outcomes that an `mcp` Effect gives besides `returned`.
+---
+
+# `McpNotReturned`
+
+Type, in `@jr2/orchestrator/src/effector-wire.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type McpNotReturned =
+  | { outcome: "refused"; reason: string }
+  | { outcome: "unreachable"; reason: string }
+  | { outcome: "input-required"; reason: string }
+  | { outcome: "unknown"; reason: string }
+  | LaterOutcome;
+```
+
+The outcomes that an `mcp` Effect gives besides `returned`. Each one has a `reason` in words.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"unreachable"`
+  - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"input-required"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 5: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`