@jr2/orchestrator 0.6.0 → 0.7.0

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

@@ -0,0 +1,47 @@
+---
+title: McpOptions
+description: The options of an `mcp` Effect.
+---
+
+# `McpOptions`
+
+Type, 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
+type McpOptions<S extends z.ZodObject | undefined = undefined> = {
+  input?: S;
+  timeout?: Duration;
+  maxBody?: number;
+  idempotent?: boolean;
+};
+```
+
+The options of an `mcp` Effect.
+
+**Fields**
+
+- `input` (optional): `S`
+
+  The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+  gives it. For `mcp.call` the parsed input is the tool's arguments; for `mcp.prompt`, the
+  prompt's arguments, each a string. 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): `mcp
+  "<slot>": its input does not match the definition's input schema — <path>: <message>`. With no
+  schema, the input of the `invoke` is the arguments as it is, and `{}` when it has none.
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default:
+  the server's `timeout` in `jr2.config.ts` (60 seconds when it sets none). With no answer in
+  that time, the output is `unknown`. It refuses a value that is not a positive duration: `mcp:
+  timeout "<timeout>" is not a positive duration (like "30s", "2m")`.
+- `maxBody` (optional): `number`
+
+  The largest number of bytes of `text`, and of `structured` as JSON, that the output keeps.
+  Default 65536. Past it, jr2 cuts `text`, drops `structured`, and sets `truncated`. It refuses
+  a value that is not a positive whole number: `mcp({ maxBody }): a positive number of bytes`.
+- `idempotent` (optional): `boolean`
+
+  `true` when it is safe to send the request two times: the tool only reads, or it has its own
+  idempotency key. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the
+  request went out. Then it sends an idempotent one again, and gives any other the output
+  `unknown`. jr2 does not read the tool's `idempotentHint`.

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

@@ -0,0 +1,50 @@
+---
+title: McpOutput
+description: "The output of any `mcp` Effect: a call's, a read's or a prompt's."
+---
+
+# `McpOutput`
+
+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 McpOutput = McpCallOutput | McpReadOutput;
+```
+
+The output of any `mcp` Effect: a call's, a read's or a prompt's.
+
+**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`, `text`, `structured`, `truncated`
+
+  - `outcome`: `"returned"`
+  - `text`: `string`
+  - `structured` (optional): `unknown`
+  - `truncated` (optional): `boolean`
+- Form 7: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`

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

@@ -0,0 +1,53 @@
+---
+title: McpReadOutput
+description: The output of an `mcp.read` or an `mcp.prompt` Effect.
+---
+
+# `McpReadOutput`
+
+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 McpReadOutput =
+  | { outcome: "returned"; text: string; structured?: unknown; truncated?: boolean }
+  | McpNotReturned;
+```
+
+The output of an `mcp.read` or an `mcp.prompt` Effect. Its outcomes are those of
+[`McpCallOutput`](type-mcpcalloutput.md), with no `isError`. For a read, `text` joins the text of the resource's
+contents, and `structured` is the `contents` list: a blob is given only as its `mimeType` and its
+size. For a prompt, `text` joins the text of the prompt's messages, and `structured` is the
+`messages` list. Past the bound, `structured` is dropped and `truncated` is set.
+
+**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`, `text`, `structured`, `truncated`
+
+  - `outcome`: `"returned"`
+  - `text`: `string`
+  - `structured` (optional): `unknown`
+  - `truncated` (optional): `boolean`
+- Form 6: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`
+
+**See also**
+
+- [Effects](../../concepts/effects.md)

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

@@ -0,0 +1,50 @@
+---
+title: McpRemoteServer
+description: A remote MCP server, which the Harness reaches over Streamable HTTP.
+---
+
+# `McpRemoteServer`
+
+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 McpRemoteServer = {
+  url: string;
+  secret?: string;
+  timeout?: `${number}s` | `${number}m` | `${number}h`;
+};
+```
+
+A remote MCP server, which the Harness reaches over Streamable HTTP. An Agent that names it in its
+`mcp` list gets the tools that its `tools` allowlist names.
+
+A server with a `secret` needs an `https://` url, because the Custodian puts the value on TLS
+only: `mcp.<name>.url must be an https:// URL`. A server with no secret can use `http://`. The
+Harness sends `Authorization: Bearer <Stand-in>`, and the Custodian of each pod whose Agents name
+the server puts the value in its place. A `secret` that the `secrets` list does not hold is
+refused when the config loads: `<file> at mcp.<name>.secret: "<NAME>" is not an entry of secrets`.
+Past `timeout`, the Harness cancels the call, and the model reads jr2's text.
+
+**Fields**
+
+- `url`: `string`
+
+  Its Streamable HTTP endpoint: `https://` when it has a `secret`.
+- `secret` (optional): `string`
+
+  A name of the `secrets` list: its bearer token. With no `hosts`, that entry is bound to the
+  url's host, in `authorization`. Default: none.
+- `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+  How long one call can run, such as `"90s"`. Default `"60s"`.
+
+**Example**
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  secrets: [{ name: "SLACK_ACME_TOKEN", value: process.env.SLACK_ACME_TOKEN }],
+  mcp: { "slack-acme": { url: "https://mcp.slack.example/mcp", secret: "SLACK_ACME_TOKEN" } },
+});
+```

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

@@ -0,0 +1,41 @@
+---
+title: McpServer
+description: "One MCP server of the Instance: a `McpRemoteServer` (`url`) or a `McpStdioServer` (`command`)."
+---
+
+# `McpServer`
+
+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 McpServer = McpRemoteServer | McpStdioServer;
+```
+
+One MCP server of the Instance: a [`McpRemoteServer`](type-mcpremoteserver.md) (`url`) or a [`McpStdioServer`](type-mcpstdioserver.md)
+(`command`).
+
+**Forms**: it is one of these objects.
+
+- Form 1: `url`, `secret`, `timeout`
+
+  - `url`: `string`
+
+    Its Streamable HTTP endpoint: `https://` when it has a `secret`.
+  - `secret` (optional): `string`
+
+    A name of the `secrets` list: its bearer token. With no `hosts`, that entry is bound to the
+    url's host, in `authorization`. Default: none.
+  - `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+    How long one call can run, such as `"90s"`. Default `"60s"`.
+- Form 2: `command`, `args`, `timeout`
+
+  - `command`: `string`
+
+    A program of the Sandbox Image.
+  - `args` (optional): `readonly string[]`
+
+    Its arguments.
+  - `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+    How long one call can run, such as `"90s"`. Default `"60s"`.

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

@@ -0,0 +1,42 @@
+---
+title: McpStdioServer
+description: "A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent conversation, through jr2's spawner, inside the Agent's confinement."
+---
+
+# `McpStdioServer`
+
+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 McpStdioServer = {
+  command: string;
+  args?: readonly string[];
+  timeout?: `${number}s` | `${number}m` | `${number}h`;
+};
+```
+
+A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent
+conversation, through jr2's spawner, inside the Agent's confinement. It is Workspace code: its env
+holds only the Stand-ins that the `workspace()` grants, so it has no `secret` of its own. A
+`"none"` Agent cannot name one, because its Turns run on the Instance Harness, where no Workspace
+code runs.
+
+**Fields**
+
+- `command`: `string`
+
+  A program of the Sandbox Image.
+- `args` (optional): `readonly string[]`
+
+  Its arguments.
+- `timeout` (optional): `` `${number}s` | `${number}m` | `${number}h` ``
+
+  How long one call can run, such as `"90s"`. Default `"60s"`.
+
+**Example**
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({ mcp: { notes: { command: "notes-mcp", args: ["--root", "/work"] } } });
+```

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

@@ -1,6 +1,6 @@
 ---
 title: NamedSecret
-description: "A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present."
+description: A secret bound to a name, never `secret(open)`.
 ---
 
 # `NamedSecret`
@@ -11,9 +11,9 @@ Type, in `@jr2/orchestrator/src/http-effect.ts`. The signature of an export, or
 type NamedSecret = Secret & { readonly [K in keyof OpenSecretMark]?: never };
 ```
 
-A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a
-secret — a dispatch's target ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)) — the secret is bound with it, to a name, so the mark
-`secret(open)` carries may not be present. One type for the definition and the binding.
+A secret bound to a name, never `secret(open)`. Where a definition's Open part is a whole that
+holds a secret — a dispatch's target ([ADR-0071](../decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)) — the secret is bound with it, to a name, so the
+mark `secret(open)` carries may not be present. One type for the definition and the binding.
 
 **Fields**
 

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

@@ -5,7 +5,7 @@ description: "What an Open body declares: the parts that it lends a Chart, what
 
 # `OpenBodyDeclaration`
 
-Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type OpenBodyDeclaration = {

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

@@ -5,7 +5,7 @@ description: The output of an Open body.
 
 # `OpenBodyOutput`
 
-Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Type, in `@jr2/orchestrator/src/open-body.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type OpenBodyOutput =

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

@@ -5,7 +5,7 @@ description: "The input of a Source's `next`: the ids of the items that workers
 
 # `PoolNextInput`
 
-Type, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Type, in `@jr2/orchestrator/src/pool.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 PoolNextInput<TInput = unknown> = { active: string[]; settled: string[]; input: TInput };

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

@@ -1,6 +1,6 @@
 ---
 title: PoolSpec
-description: "What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets."
+description: What you pass to `pool()` with a child Machine as its worker.
 ---
 
 # `PoolSpec`
@@ -11,17 +11,18 @@ Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type
 type PoolSpec<T, TInput = unknown> = {
   id?: string;
   input?: z.ZodObject;
-  source: SourceSpec<T, TInput> | SourceSpec<T>;
+  source: SourceSpec<T, TInput> | SourceSpec<T> | ReadSourceSpec<T, TInput> | ReadSourceSpec<T>;
   itemId: (item: T) => string;
   cap?: number | ((args: { input: TInput }) => number);
   itemInput?: (item: T, args: { input: TInput }) => unknown;
   onDrained?: "final";
   failures?: "fail" | "report";
+  standing?: false;
 };
 ```
 
-What you pass to `pool()`: where the items come from, how many workers run at once, and what
-each worker gets.
+What you pass to `pool()` with a child Machine as its worker. It says where the items come
+from, how many workers run at once, and what each worker gets.
 
 **Fields**
 
@@ -33,9 +34,10 @@ each worker gets.
   The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
   `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
   none, and then their `input` is `unknown`.
-- `source`: `SourceSpec<T, TInput> | SourceSpec<T>`
+- `source`: `SourceSpec<T, TInput> | SourceSpec<T> | ReadSourceSpec<T, TInput> | ReadSourceSpec<T>`
 
-  Where the items come from. Make it with [`source`](source.md).
+  Where the items come from: a pull or a read Source. Make it with [`source`](source.md). A push Source
+  needs a standing Pool of runs.
 - `itemId`: `(item: T) => string`
 
   The id of an item. The Pool uses it as the id of the item's worker and in the `active` list
@@ -58,3 +60,6 @@ each worker gets.
   ends with failures, `drained` or `deadlocked`, it fails the run with the reason
   `"<n> of <m> items failed"` and the detail `{ status, items, failures }`. `"report"`: the Pool
   ends `done`, with the failures in its output. Default: `"fail"`.
+- `standing` (optional): `false`
+
+  A Pool of child Machines never stands: a child cannot be handed over.

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

@@ -5,7 +5,7 @@ description: "The output of a `push` Effect: what the `onDone` of its state gets
 
 # `PushOutput`
 
-Type, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Type, in `@jr2/orchestrator/src/sandbox-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 PushOutput =

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

@@ -0,0 +1,38 @@
+---
+title: PushSourceSpec
+description: A push Source.
+---
+
+# `PushSourceSpec`
+
+Type, in `@jr2/orchestrator/src/pool.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 PushSourceSpec<T> = {
+  item: z.ZodType<T>;
+  hooks: SourceHooks<Carry<T>, {}>;
+  hold?: number;
+  reply?: SourceReply<T>;
+};
+```
+
+A push Source. Nothing can be read again, and each item comes in a Hook's delivery. A handler
+gives `carry(item)` or `skip(reason)`. The Pool holds each carried item in its run's blob, in the
+order of arrival, until it claims it. Only a standing Pool takes a push Source. Make one with
+[`source`](source.md).
+
+**Fields**
+
+- `item`: `z.ZodType<T>`
+
+  The schema of an item. The Pool parses each carried item with it before it holds it.
+- `hooks`: `SourceHooks<Carry<T>, {}>`
+
+  A handler for each Hook kind id and event key. It gives `carry(item)` or `skip(reason)`.
+- `hold` (optional): `number`
+
+  The most items that the Pool holds. Above it, a carried item is `hold-full`, and the Hook's
+  answer is 429. Default: 1000.
+- `reply` (optional): `SourceReply<T>`
+
+  The text that the person who acted reads, from the verdict. Default: none.

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

@@ -0,0 +1,47 @@
+---
+title: ReadSourceSpec
+description: A read Source.
+---
+
+# `ReadSourceSpec`
+
+Type, in `@jr2/orchestrator/src/pool.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 ReadSourceSpec<T, TInput = unknown, R extends AnyActorLogic = AnyActorLogic> = {
+  read: R;
+  items?: (output: LookOutput<R>, args: { input: TInput }) => readonly T[];
+  wake?: EventDef;
+  pollEvery?: number;
+  hooks?: SourceHooks<Reread, TInput>;
+  reply?: SourceReply<T>;
+};
+```
+
+A read Source. `read` reads the whole set, and `items` turns its answer into the items, in
+order. The read is an `http` Effect marked `idempotent: true`, so it can spend a secret that the
+Instance Effector holds, or a promise (`fromPromise`). Its input is the Pool's input. A read that
+fails gives no items. The read is the truth: a Hook's delivery only says "read again". Make one
+with [`source`](source.md).
+
+**Fields**
+
+- `read`: `R`
+
+  The read: an `http` Effect marked `idempotent: true`, or a promise. The Pool runs it at the
+  start, after a worker settles, on `wake`, on a Hook's `reread()` and every `pollEvery`.
+- `items` (optional): `(output: LookOutput<R>, args: { input: TInput; }) => readonly T[]`
+
+  The items in the read's answer, in order. Default: the answer itself, when it is an array.
+- `wake` (optional): [`EventDef`](type-eventdef.md)
+
+  As a pull Source's `wake`.
+- `pollEvery` (optional): `number`
+
+  Read again after this many milliseconds while the Pool waits. Default: none.
+- `hooks` (optional): `SourceHooks<Reread, TInput>`
+
+  What a Hook's delivery does: a handler gives `reread()` or `skip(reason)`. Default: none.
+- `reply` (optional): `SourceReply<T>`
+
+  The text that the person who acted reads, from the verdict. Default: none.

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

@@ -5,7 +5,7 @@ description: The value of one Repo Slot in `workspace({ repos })`.
 
 # `RepoSlot`
 
-Type, in `@jr2/orchestrator/src/parts.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+Type, in `@jr2/orchestrator/src/parts.ts`. It is an export of `@jr2/orchestrator`, in the [Workspaces and Repos](group-workspaces-and-repos.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type RepoSlot<TInput = unknown> =

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

@@ -0,0 +1,18 @@
+---
+title: Reread
+description: What `reread()` gives.
+---
+
+# `Reread`
+
+Type, in `@jr2/orchestrator/src/pool.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 Reread = { readonly [VERDICT]: "reread" };
+```
+
+What `reread()` gives. Only a Source that can read (`next` or `read`) gives it.
+
+**Fields**
+
+- `[VERDICT]`: `"reread"`

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

@@ -0,0 +1,41 @@
+---
+title: RunsConfig
+description: How long jr2 keeps an ended run, and the volume that keeps it (ADR-0065).
+---
+
+# `RunsConfig`
+
+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 RunsConfig = {
+  retain?: `${number}${"m" | "h" | "d" | "w"}`;
+  volume?: string;
+};
+```
+
+How long jr2 keeps an ended run, and the volume that keeps it ([ADR-0065](../decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md)). When the config loads,
+a bad field is refused: `<file> at runs.<field>: <problem>`.
+
+**Fields**
+
+- `retain` (optional): `` `${number}${"m" | "h" | "d" | "w"}` ``
+
+  How long jr2 keeps an ended run: its row, its conversations and the hook log. A number and
+  `m`, `h`, `d` or `w`, such as `"90d"`. At least `"1h"`, with no upper limit. A live run is
+  never removed. Default: `"30d"`.
+- `volume` (optional): `string`
+
+  The size of the Orchestrator's state volume claim: a number and a unit, such as `"5Gi"` or
+  `"500Mi"` (a number with no unit is refused). Default: `"5Gi"` for a
+  new claim; unset, `jr2 up` keeps the size of a claim that exists. A larger size grows the
+  claim where its StorageClass allows expansion, else `jr2 up` refuses it. A smaller size is
+  refused: Kubernetes never makes a claim smaller.
+
+**Example**
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({ runs: { retain: "90d", volume: "20Gi" } });
+```

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

@@ -8,12 +8,37 @@ description: "Who delivered an event: an Agent by its slot, or a Gate by its inv
 Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. 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 Sender = { readonly party: "agent" | "gate"; readonly id: string };
+type Sender = {
+  readonly party: "agent" | "gate";
+  readonly id: string;
+  readonly via?: "token" | "jwt" | "hook";
+  readonly name?: string;
+  readonly onBehalfOf?: string;
+  readonly checked?: readonly SenderCallerField[];
+};
 ```
 
 Who delivered an event: an Agent by its slot, or a Gate by its invoke id ([ADR-0015](../decisions/0015-authoring-surface-absorbs-the-mechanism.md)).
 
+A Gate's event also carries the Caller that answered it ([ADR-0011](../decisions/0011-workflow-defined-events.md), [ADR-0078](../decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): `via` and `name`
+name it, `onBehalfOf` is the party that it says it acts for, and `checked` names the fields that
+jr2 verified. `via` and `name` are always checked, because an authenticator made them;
+`onBehalfOf` is checked only for a Hook, whose signature covers the payload that it comes from.
+An event that a Gate gives with no Caller (its `look`) has none of these fields.
+
 **Fields**
 
 - `party`: `"agent" | "gate"`
 - `id`: `string`
+- `via` (optional): `"token" | "jwt" | "hook"`
+
+  The authenticator that made the Caller: `token`, `jwt` or `hook`. A Gate's event only.
+- `name` (optional): `string`
+
+  The Caller's name for that authenticator. A Gate's event only.
+- `onBehalfOf` (optional): `string`
+
+  The party that the Caller says it acts for. A claim, unless `checked` names it.
+- `checked` (optional): `readonly SenderCallerField[]`
+
+  The fields of the Caller that jr2 verified.

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

@@ -0,0 +1,14 @@
+---
+title: SenderCallerField
+description: "A field of a `Sender`'s Caller that jr2 can verify."
+---
+
+# `SenderCallerField`
+
+Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. 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 SenderCallerField = "via" | "name" | "onBehalfOf";
+```
+
+A field of a [`Sender`](type-sender.md)'s Caller that jr2 can verify.

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

@@ -5,7 +5,7 @@ description: "The Size of a Workspace: the most memory and cpu that its whole Sa
 
 # `Size`
 
-Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Type, in `@jr2/orchestrator/src/size.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 Size = {

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

@@ -0,0 +1,19 @@
+---
+title: Skip
+description: "What `skip(reason)` gives: the delivery brings nothing, and the reason says why."
+---
+
+# `Skip`
+
+Type, in `@jr2/orchestrator/src/pool.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 Skip = { readonly [VERDICT]: "skip"; readonly reason: string };
+```
+
+What `skip(reason)` gives: the delivery brings nothing, and the reason says why.
+
+**Fields**
+
+- `[VERDICT]`: `"skip"`
+- `reason`: `string`