@jr2/orchestrator 0.6.0 → 0.7.0

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

@@ -1,11 +1,11 @@
 ---
 title: pool
-description: "Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once."
+description: "Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most `cap` workers at once."
 ---
 
 # `pool`
 
-Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Function, 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.
 
 ## Overload 1
 
@@ -19,9 +19,12 @@ function pool<
 ): PoolMachine<TWorker, z.infer<TSchema>>
 ```
 
-Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at
-most `cap` workers at once. Use it as the root of a Workflow (`export const machine = pool(…)`),
-or compose it in another Machine.
+Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most
+`cap` workers at once. Use it as the root of a Workflow (`export const machine = pool(…)`), or
+compose it in another Machine.
+
+The worker is a Machine, which runs inside the Pool's run, or a `dispatch(...)` slot, which makes
+each item a run of its own (a Pool of runs, which stands; see the third form).
 
 The run ends when the Source has no item ready and no worker runs. Its output is
 `{ status, items, failures }`: `status` is `"drained"` when no item is left, or `"deadlocked"`
@@ -51,9 +54,10 @@ its own.
     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
@@ -76,6 +80,9 @@ its own.
     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.
 
 **Returns**: The Pool, as a Machine.
 
@@ -151,9 +158,10 @@ an example.
     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
@@ -176,6 +184,9 @@ an example.
     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.
 
 **Returns**: The Pool, as a Machine.
 
@@ -184,3 +195,60 @@ an example.
 - [Run one worker per item](../../guides/run-one-worker-per-item.md)
 - [Pools and Sources](../../concepts/pools-and-sources.md)
 - [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)
+
+## Overload 3
+
+```ts
+function pool<
+  I,
+  T,
+>(
+  worker: EffectLogic<I, DispatchOutput>,
+  spec: StandingPoolSpec<T, I>,
+): StandingPoolMachine
+```
+
+Make a standing Pool of runs: each item that the Source gives is a run of the `dispatch` slot's
+Workflow, keyed by `itemId` in that Workflow, with at most `cap` live at once ([ADR-0017](../decisions/0017-pool-over-a-source-port.md)). The
+slot says `wait: true` and has no `target`. The Pool never ends by itself: when it has no work, it
+waits for a Hook's delivery, a `reread` or its `pollEvery`. A run that ends in any way frees its
+slot, and is a `settled` mark on the run's feed; it is never the Pool's error, because the run is
+not the Pool's child. Use it as the top Machine of its Workflow, in a file of its own.
+
+**Parameters**
+
+- `worker` ([`EffectLogic`](type-effectlogic.md)): The `dispatch(...)` slot of the Workflow that runs each item.
+- `spec`: The Source, the item id, the cap and the run's body. See [`StandingPoolSpec`](type-standingpoolspec.md).
+
+**Returns**: The standing Pool, as a Machine.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { carry, dispatch, pool, skip, source } from "@jr2/orchestrator";
+import type {} from "@jr2/orchestrator/hooks/gitlab";
+
+const failed = z.object({ sha: z.string() });
+
+export const machine = pool(dispatch("triage", { input: failed, wait: true }), {
+  id: "pipelines",
+  standing: true,
+  source: source({
+    item: failed,
+    hooks: {
+      gitlab: {
+        "pipeline.failed": ({ payload }) =>
+          payload.object_attributes.sha === "" ? skip("no commit") : carry({ sha: payload.object_attributes.sha }),
+      },
+    },
+  }),
+  itemId: (p) => `pipeline-${p.sha}`,
+  cap: 4,
+});
+```
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)
+- [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)

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

@@ -5,7 +5,7 @@ description: "Make a `push` Effect: it pushes the branch of a Worktree to the Bi
 
 # `push`
 
-Function, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, 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
 function push<const O extends PushOptions>(options?: O): EffectLogic<PushInput<O>, PushOutput>

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

@@ -5,7 +5,7 @@ description: The `ready` output of an `onDone` arm that `isReady` guards.
 
 # `readyOf`
 
-Function, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, 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
 function readyOf<O extends { outcome: string }>(output: O): Extract<O, { outcome: "ready" }>

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

@@ -0,0 +1,19 @@
+---
+title: reread
+description: Read the Source again.
+---
+
+# `reread`
+
+Function, 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
+function reread(): Reread
+```
+
+Read the Source again. The Pool calls its `next`, or runs its `read`, at once; a read that runs
+now reads once more after it ends. Only a Source that can read gives it.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)

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

@@ -5,7 +5,7 @@ description: "Name an Effect secret: `secret(\"jira\")`."
 
 # `secret`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 

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

@@ -5,7 +5,7 @@ description: "A guard that is true for an event that one party sent, and false f
 
 # `sentBy`
 
-Function, in `@jr2/orchestrator/src/party.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/party.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 sentBy<const Id extends string>(id: Id): { type: typeof SENT_BY; params: { id: Id } }

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

@@ -0,0 +1,22 @@
+---
+title: skip
+description: Bring nothing, and say why.
+---
+
+# `skip`
+
+Function, 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
+function skip(reason: string): Skip
+```
+
+Bring nothing, and say why. The reason goes in the Hook's answer and in its hook log.
+
+**Parameters**
+
+- `reason`: Why the delivery brings nothing, for a person to read.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)

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

@@ -5,7 +5,9 @@ description: "Declare a Source: where a `pool()` gets its work items, one at a t
 
 # `source`
 
-Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Function, 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.
+
+## Overload 1
 
 ```ts
 function source<T, TInput = unknown>(spec: SourceSpec<T, TInput>): SourceSpec<T, TInput>
@@ -49,3 +51,56 @@ export const issues = source<Issue>({
 - [Run one worker per item](../../guides/run-one-worker-per-item.md)
 - [Pools and Sources](../../concepts/pools-and-sources.md)
 - [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)
+
+## Overload 2
+
+```ts
+function source<const S extends z.ZodType>(spec: {
+  item: S;
+  hooks: SourceHooks<Carry<z.output<NoInfer<S>>>, {}>;
+  hold?: number;
+  reply?: SourceReply<z.output<NoInfer<S>>>;
+}): PushSourceSpec<z.output<S>>
+```
+
+Declare a PUSH Source: the schema of an item, and the handlers that carry it. Only a standing
+Pool of runs takes it.
+
+**Parameters**
+
+- `spec`: `item`, `hooks`, `hold` and `reply`. See [`PushSourceSpec`](type-pushsourcespec.md).
+
+  - `item`: `S`
+  - `hooks`: `SourceHooks<Carry<z.output<NoInfer<S>>>, {}>`
+  - `hold` (optional): `number`
+  - `reply` (optional): `SourceReply<z.output<NoInfer<S>>>`
+
+**Returns**: The same spec.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)
+
+## Overload 3
+
+```ts
+function source<
+  T,
+  TInput = unknown,
+  R extends AnyActorLogic = AnyActorLogic,
+>(
+  spec: ReadSourceSpec<T, TInput, R>,
+): ReadSourceSpec<T, TInput, R>
+```
+
+Declare a READ Source: a read of the whole set, and the items in its answer.
+
+**Parameters**
+
+- `spec`: `read`, `items`, `wake`, `pollEvery`, `hooks` and `reply`. See [`ReadSourceSpec`](type-readsourcespec.md).
+
+**Returns**: The same spec.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)

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

@@ -0,0 +1,93 @@
+---
+title: steer
+description: "Send a Steering message to one Agent of this Machine: an action for a transition."
+---
+
+# `steer`
+
+Function, in `@jr2/orchestrator/src/steer.ts`. It is an export of `@jr2/orchestrator`, in the [Steering](group-steering.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+function steer<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject["params"] | undefined,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+>(
+  agent: string,
+  text: string | ((args: SteerArgs<TContext, TExpressionEvent>) => string),
+  opts: { from?: Sender | ((args: SteerArgs<TContext, TExpressionEvent>) => Sender | undefined) } = {},
+): ActionFunction<TContext, TExpressionEvent, TEvent, TParams, TActor, never, never, never, never>
+```
+
+Send a Steering message to one Agent of this Machine: an action for a transition. The Agent hears
+the text once, without an interrupt. When a Turn of the Agent is open, its Harness adds the text
+at the Turn's next step boundary. Otherwise the text waits for the Agent's next Turn in this
+Machine instance. When this Machine instance ends first, the message is not delivered.
+
+A Steering message is not an event: no guard reads it, and no Gate takes it. The Agent decides
+what to do with it, and acts on the workflow only by its picks.
+
+Use it to relay what one Agent says to another. Give `from` the Sender of the event (the
+`sender` field that the Orchestrator writes on it): the Agent then reads the text as the word of
+a peer, not as an order. When the Sender is a Gate, the Agent reads the text as what the Gate
+received, not as an order. With no `from`, the Agent reads the text as the workflow's own.
+
+`agent` is the name of an Agent in this Machine's `actors`. A text longer than 16 KiB is cut.
+The Machine can steer an Agent whose definition says `steerable: false`: that refuses Callers
+only.
+
+**Parameters**
+
+- `agent`
+- `text`
+- `opts`
+
+  - `from` (optional): `Sender | ((args: SteerArgs<TContext, TExpressionEvent>) => Sender | undefined)`
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, jr2Setup, steer } from "@jr2/orchestrator";
+
+const done = defineEvent({ name: "done", description: "The draft is ready.", input: z.object({}) });
+const note = defineEvent({
+  name: "note",
+  description: "Send the draft back to the writer, with what to change.",
+  input: z.object({ text: z.string().min(1) }),
+});
+
+export const machine = jr2Setup({
+  events: [done, note],
+  actors: {
+    writer: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You write.", workspace: "none" }),
+    reviewer: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You review.", workspace: "none" }),
+  },
+}).createMachine({
+  initial: "writing",
+  states: {
+    writing: {
+      invoke: { src: "writer", input: { prompt: "Write the notes.", continue: true } },
+      on: { done: "reviewing" },
+    },
+    reviewing: {
+      invoke: { src: "reviewer", input: { prompt: "Review the notes." } },
+      on: {
+        // The writer's next Turn hears the note as the reviewer's word, not as an order.
+        note: {
+          target: "writing",
+          actions: steer("writer", ({ event }) => event.text, { from: ({ event }) => event.sender }),
+        },
+      },
+    },
+  },
+});
+```
+
+**See also**
+
+- [Steer an Agent](../../guides/steer-an-agent.md)
+- [Agents and Turns](../../concepts/agents-and-turns.md)
+- [ADR-0002: The agent actor is a duplex channel; its control plane is Menu tool calls](../decisions/0002-duplex-streaming-actor.md)

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

@@ -5,7 +5,7 @@ description: "Make a string from literal text and Effect secrets, as a tagged te
 
 # `text`
 
-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.
 
 ```ts
 function text<

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

@@ -5,7 +5,7 @@ description: "An Agent's definition: which model it runs, its instructions, and
 
 # `AgentDefinition`
 
-Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 type AgentDefinition = {
@@ -14,6 +14,8 @@ type AgentDefinition = {
   description?: string;
   thinkingLevel?: ThinkingLevel;
   workspace?: WorkspaceAccess;
+  mcp?: readonly AgentMcpServer[];
+  steerable?: boolean;
 };
 ```
 
@@ -55,6 +57,17 @@ cannot change `instructions` or `workspace`.
     Worktree: cut it with `{ path, detach: sha }`, then give that `path` as `cwd`.
   - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
     runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it.
+- `mcp` (optional): `readonly AgentMcpServer[]`
+
+  The MCP servers whose tools the Agent gets, each with its allowlist: see
+  [`AgentMcpServer`](type-agentmcpserver.md). The tools join the Agent's tools, after its Working tools and before
+  its Menu. A call to one is not a pick, and the Turn goes on after it. Default: none. A composer
+  replaces the whole list with `customize(machine, { agents: { <slot>: { mcp: [...] } } })`.
+- `steerable` (optional): `boolean`
+
+  May a Caller send this Agent a Steering message? Default: `true`. With `false`,
+  `POST /runs/:runId/steering` and `jr2 steer` refuse it, and `GET /runs/:runId/agents` says
+  `steerable: false`. The Machine can still steer the Agent with the `steer` action.
 
 **Example**
 

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

@@ -0,0 +1,54 @@
+---
+title: AgentMcpServer
+description: One MCP server that an Agent uses, and the tools that it may call there.
+---
+
+# `AgentMcpServer`
+
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+type AgentMcpServer = {
+  server: string;
+  tools?: readonly string[] | "*";
+};
+```
+
+One MCP server that an Agent uses, and the tools that it may call there.
+
+- `server` is a name of the `mcp` block of `jr2.config.ts`. `jr2 up` refuses a name that the
+  block does not declare, and prints the `customize()` line that binds the Agent to one it does.
+- `tools` is the allowlist. A remote server needs it: a list of tool names, or `"*"` for every
+  tool. The Harness offers and runs only those tools. When Workspace code in the Agent's Sandbox
+  can spend the server's secret, `jr2 up` takes only `"*"`, because a list would then not be a
+  limit. A stdio server takes no `tools`: the Agent gets every tool of the server.
+
+The model reads each tool as `mcp__<server>__<tool>`. A tool name in the list must keep that name
+within `[A-Za-z0-9_-]` and 128 characters.
+
+**Fields**
+
+- `server`: `string`
+
+  A server name of the `mcp` block of `jr2.config.ts`.
+- `tools` (optional): `readonly string[] | "*"`
+
+  The allowlist: tool names of the server, or `"*"` for every tool. Required for a remote
+  server; absent for a stdio server.
+
+**Example**
+
+```ts
+import { agent } from "@jr2/orchestrator";
+
+export const triage = agent({
+  model: "anthropic/claude-haiku-5-5",
+  instructions: "You read the ticket and post a summary to the channel.",
+  workspace: "none",
+  mcp: [{ server: "slack-acme", tools: ["post_message", "read_channel"] }],
+});
+```
+
+**See also**
+
+- [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-anyframepath.md

@@ -5,7 +5,7 @@ description: "A Turn's Frame: a Worktree, or `/work`, stated."
 
 # `AnyFramePath`
 
-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 AnyFramePath = "/work" | `/work/${string}`;

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

@@ -5,7 +5,7 @@ description: "A Worktree of any Repo Slot: what a kit factory states, before `jr
 
 # `AnyWorktreePath`
 
-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 AnyWorktreePath = `/work/${string}/${string}`;

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

@@ -5,7 +5,7 @@ description: "The repository of a Repo Slot: `{ url, ref }`."
 
 # `Binding`
 
-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 Binding = {

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

@@ -0,0 +1,40 @@
+---
+title: Caller
+description: "A request's Caller (ADR-0078): who acts, through which authenticator, and what it may do."
+---
+
+# `Caller`
+
+Type, in `@jr2/orchestrator/src/tokens.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 Caller = {
+  via: "token" | "jwt" | "hook";
+  name: string;
+  shown?: string;
+  may: Scopes;
+  onBehalfOf?: string;
+};
+```
+
+A request's Caller ([ADR-0078](../decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): who acts, through which authenticator, and what it may do.
+
+**Fields**
+
+- `via`: `"token" | "jwt" | "hook"`
+
+  The authenticator that made the Caller: `token` (the Instance token or a named token), `jwt`
+  or `hook`.
+- `name`: `string`
+
+  The Caller's name for that authenticator: `instance`, a named token's name, a JWT's `sub`, a
+  Hook's name.
+- `shown` (optional): `string`
+
+  The name that jr2 shows, when it is not `name` (a JWT's `email`).
+- `may`: [`Scopes`](../config.md#callers-tokens-name-may)
+
+  What the Caller may do.
+- `onBehalfOf` (optional): `string`
+
+  The Caller's claim about the party it acts for. jr2 records it and never checks it.

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

@@ -0,0 +1,32 @@
+---
+title: CallerRecord
+description: "A Caller as a run records it (ADR-0078): who acted, and the party it says it acted for."
+---
+
+# `CallerRecord`
+
+Type, in `@jr2/orchestrator/src/callers.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 CallerRecord = {
+  via: Caller["via"];
+  name: string;
+  shown?: string;
+  onBehalfOf?: string;
+};
+```
+
+A Caller as a run records it ([ADR-0078](../decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): who acted, and the party it says it acted for. Never its
+scopes.
+
+**Fields**
+
+- `via`: `Caller["via"]`
+- `name`: `string`
+- `shown` (optional): `string`
+
+  The name that jr2 shows, when it is not `name` (a JWT's `email`).
+- `onBehalfOf` (optional): `string`
+
+  The Caller's claim about the party it acts for. jr2 records it and never checks it, except for
+  a Hook, whose signature covers it.

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

@@ -0,0 +1,19 @@
+---
+title: Carry
+description: What `carry(item)` gives.
+---
+
+# `Carry`
+
+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 Carry<T> = { readonly [VERDICT]: "carry"; readonly item: T };
+```
+
+What `carry(item)` gives. Only a push Source (one with an `item` schema) gives it.
+
+**Fields**
+
+- `[VERDICT]`: `"carry"`
+- `item`: `T`

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

@@ -1,6 +1,6 @@
 ---
 title: ChainLink
-description: "One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's pick — typed by the Machine's events."
+description: One reply since the pick, as the author reads it.
 ---
 
 # `ChainLink`
@@ -13,7 +13,7 @@ type ChainLink<TActor extends ProvidedActor, TEvent extends EventObject> =
   | { kind: "event"; event: Exclude<TEvent, { type: `${string}.${string}` }> };
 ```
 
-One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot
-(`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's
+One reply since the pick, as the author reads it. It is an invoked actor's output, typed by its
+slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's
 pick — typed by the Machine's events. A reply is from outside the Machine: the events it sends
 itself are not links.

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

@@ -5,7 +5,7 @@ description: "The output of a `command` Effect: what the `onDone` of its state g
 
 # `CommandOutput`
 
-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 CommandOutput = (ExecOutcome & { dirty?: boolean }) | Unknown | LaterOutcome;