@jr2/orchestrator 0.5.1 → 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,13 +15,23 @@ 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>> };
   image?: string;
   user?: string | UserContainer;
   resources?: Size;
-  repos?: [RepoSlotsOf<M>] extends [never] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<InputFrom<WorkspaceOf<M>>> };
+  repos?: [RepoSlotsOf<M>] extends [never]
+    ? never
+    : { [K in RepoSlotsOf<M>]?: RepoSlot<Exclude<InputFrom<WorkspaceOf<M>>, undefined>> };
 };
 ```
 
@@ -52,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
@@ -74,7 +91,7 @@ Every key is optional. Write only what you change.
   The Size, layered field by field over the Size of the `workspace()`: `{ limits: { memory } }`
   keeps the author's cpu. Only `limits.memory` and `limits.cpu`. See [`Size`](type-size.md). Only for a
   Machine that composes a `workspace()`.
-- `repos` (optional): `[ RepoSlotsOf<M> ] extends [ never ] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<InputFrom<WorkspaceOf<M>>>; }`
+- `repos` (optional): `[ RepoSlotsOf<M> ] extends [ never ] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<Exclude<InputFrom<WorkspaceOf<M>>, undefined>>; }`
 
   Bind the Repo Slots of the `workspace()`, by slot name. Each value is one of these:
 

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 =
@@ -18,7 +18,8 @@ type DispatchOutput =
     }
   | { outcome: "refused"; status: number; report: string[] }
   | { outcome: "unreachable"; reason: string }
-  | Unknown;
+  | Unknown
+  | LaterOutcome;
 ```
 
 The output of a `dispatch` Effect. Route on `outcome`:
@@ -34,6 +35,8 @@ The output of a `dispatch` Effect. Route on `outcome`:
 - `unreachable`: the Orchestrator of the target did not answer. No run started.
 - `unknown`: jr2 cannot tell if a run started.
 
+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`, `reason`
@@ -59,6 +62,10 @@ The output of a `dispatch` Effect. Route on `outcome`:
 
   - `outcome`: `"unreachable"`
   - `reason`: `string`
+- Form 6: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **See also**
 

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

@@ -0,0 +1,19 @@
+---
+title: DoorlessInput
+description: A type that the Authoring surface names.
+---
+
+# `DoorlessInput`
+
+Type, in `@jr2/orchestrator/src/workspace.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 DoorlessInput<TBody extends AnyStateMachine> =
+  unknown extends InputFrom<TBody>
+    ? unknown
+    : [keyof Omit<InputFrom<TBody>, "workspace">] extends [never]
+      ? unknown
+      : {} extends Omit<InputFrom<TBody>, "workspace">
+        ? Omit<InputFrom<TBody>, "workspace"> | undefined
+        : Omit<InputFrom<TBody>, "workspace">;
+```

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-filebody.md

@@ -1,6 +1,6 @@
 ---
 title: FileBody
-description: "`file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body."
+description: "`file(path, { segments?, contentType? })`: a Worktree file as an `http` body."
 ---
 
 # `FileBody`
@@ -11,14 +11,13 @@ Type, in `@jr2/orchestrator/src/http-effect.ts`. The signature of an export, or
 type FileBody<S extends z.ZodType | undefined = undefined> = {
   readonly file: {
     readonly path: FromInput<S, string>;
-    readonly slot?: string;
     readonly segments?: FromInput<S, readonly string[]>;
     readonly contentType?: string;
   };
 };
 ```
 
-`file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
+`file(path, { segments?, contentType? })`: a Worktree file as an `http` body.
 
 **Fields**
 
@@ -26,11 +25,8 @@ type FileBody<S extends z.ZodType | undefined = undefined> = {
 
   - `path`: `FromInput<S, string>`
 
-    The file, relative to the Repo Slot's Worktree, or to `/work` in a Workspace with no Repo
-    Slot.
-  - `slot` (optional): `string`
-
-    The Repo Slot whose Worktree holds it. Write it only when the Workspace has more than one.
+    The file, relative to the Worktree that `worktree` of the Effect's input names, or to `/work`
+    in a Workspace with no Repo Slot.
   - `segments` (optional): `FromInput<S, readonly string[]>`
 
     Path segments that jr2 adds to the end of the url, as `path` of `request` does for a json

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

@@ -0,0 +1,14 @@
+---
+title: FramePath
+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`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type FramePath<S extends string> = WorktreePath<S> | "/work";
+```
+
+A Turn's Frame in a Workspace with the Repo Slots `S`.

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 };
@@ -20,10 +20,8 @@ caller sends it. jr2 writes it over any value that a caller sends.
 
 Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
 that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
-`workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`.
-
-The `spec` of a root `workspace()` also gets it, and the type of its input shows it:
-``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``.
+`workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`. For example, a cut
+can name a branch for each run: `` branch: `fix/${context.instanceId}` ``.
 
 It is not the run id. Use it, for example, to give each run a branch of its own.
 

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

@@ -79,10 +79,13 @@ An `http` Effect's definition.
   Effect secret. Do not write it beside `body`.
 - `body` (optional): `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

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

@@ -0,0 +1,20 @@
+---
+title: HttpFileInput
+description: The input of an `http` Effect with a Worktree file as its body.
+---
+
+# `HttpFileInput`
+
+Type, in `@jr2/orchestrator/src/http-effect.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 HttpFileInput<S> = (S extends z.ZodType ? z.infer<S> : unknown) & { worktree?: AnyWorktreePath };
+```
+
+The input of an `http` Effect with a Worktree file as its body. Under a Workspace with Repo
+Slots, `worktree` names the Worktree. In a Workspace with no Repo Slot, the input has no
+`worktree`, and the path is relative to `/work`.
+
+**Fields**
+
+- `worktree` (optional): [`AnyWorktreePath`](type-anyworktreepath.md)

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

@@ -5,10 +5,10 @@ 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 = {
+type HttpOutput = LaterOutcome | {
   outcome: "response";
   status: number;
   headers: Record<string, string>;
@@ -37,6 +37,8 @@ outcome is output. A 4xx or 5xx status is output too. Route on `outcome`:
 - `unknown`: the call can have gone out, but no answer came, or jr2 cannot tell after a restart.
   `reason` tells why. jr2 does not send it again unless it is marked `idempotent`.
 
+The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+
 **Forms**: it is one of these objects.
 
 - Form 1: `outcome`, `status`, `headers`, `contentType`, `size`, `body`, `truncated`
@@ -52,6 +54,10 @@ outcome is output. A 4xx or 5xx status is output too. Route on `outcome`:
 
   - `outcome`: `"unknown" | "unreachable" | "refused"`
   - `reason`: `string`
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
 
 **Example**
 

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