@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/concepts/callers-and-hooks.md

@@ -0,0 +1,205 @@
+---
+title: Callers and Hooks
+description: Who acts on an Instance from outside its Machines, what each one may do, and what a Hook does.
+---
+
+# Callers and Hooks
+
+A [Caller](../reference/glossary.md#caller) is the holder of a credential that acts on an
+[Instance](../reference/glossary.md#instance) from outside its [Machines](../reference/glossary.md#machine). A person, a
+CI job, a bridge to a chat service and an outside service are Callers. A Caller can start a run, read it, answer a
+[Gate](../reference/glossary.md#gate), send a [Steering message](../reference/glossary.md#steering-message) or cancel a
+run, for the [Workflows](../reference/glossary.md#workflow) that its scopes name. A
+[Hook](../reference/glossary.md#hook) is the door of an Instance for one outside service, such as a forge. It is a
+Caller that can only answer a Gate or bring items to a Source. Its [Hook kind](../reference/glossary.md#hook-kind) is
+the protocol of the service.
+
+## Why it exists
+
+One Instance token can do everything on each run. A CI job that starts runs, a bridge that answers Gates, and a teammate
+with a browser need less than that. If each one holds the Instance token, each one can do each act on each run, and the
+run cannot say who acted. Thus jr2 knows each Caller by its credential, gives it only its scopes, and records it on each
+act.
+
+An outside service sends a delivery, such as a review on a forge. It does not send a bearer token, and each service has
+its own signature, its own body and its own handshake. A Hook checks that a delivery comes from its service, and decides
+nothing. The Gate or the Source that hears it decides what the delivery means for its run.
+
+## How a Caller is known
+
+The Orchestrator has an ordered list of authenticators. Each one looks at the credential of a request. It gives a
+Caller, or it says that the credential is not its credential. The first one that claims the credential decides. When it
+finds the credential bad, the answer is 401, and the next authenticator does not look at it. A credential that no
+authenticator claims also gets 401.
+
+| Authenticator     | The credential                                                                                            | The Caller                                          |
+| ----------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| Instance token    | The token in the `jr2-instance` Secret. The CLI reads it over the Kubernetes API.                         | `token/instance`, with each scope for each Workflow |
+| Named token       | A value that starts with `jr2c_`, for a name in [`callers.tokens`](../reference/config.md#callers-tokens) | `token/<name>`, with the scopes of its entry        |
+| JWT               | A JWT of an issuer in [`callers.issuers`](../reference/config.md#callers-issuers)                         | `jwt/<sub>`, with the scopes that its groups give   |
+| A Hook's verifier | A delivery at `POST /hooks/<name>`, with no bearer token                                                  | `hook/<name>`, with `answer` only                   |
+
+The tokens of a Sandbox and the publish token are not Callers, and no authenticator makes a Caller from them. Thus an
+Agent cannot answer a Gate. [Secrets and trust](secrets-and-trust.md#the-tokens) tells where each token is kept.
+
+For a JWT, jr2 checks the signature with the published keys of the issuer, and the issuer, the audience and the expiry.
+The name of the Caller is the `sub` claim, and the name that jr2 shows is the `email` claim. The `groups` map of the
+issuer entry gives scopes for the values of a claim, such as the groups of a person. A JWT that gets no scope from the
+map can do nothing. An issuer with `login: true` also lets a person log in to the
+[Console](../reference/glossary.md#console) ([Open the Console](../guides/open-the-console.md#log-in)).
+
+[`jr2 whoami`](../reference/cli.md#whoami) and [`GET /whoami`](../reference/http-api.md#get-whoami) show the Caller of a
+credential, with its scopes. Use them to see what a credential can do before a request fails.
+
+## Scopes
+
+A scope is one act of a Caller. Its value is `"all"`, or a list of the names of the Workflows that it opens:
+
+| Scope    | The act                                                                                   |
+| -------- | ----------------------------------------------------------------------------------------- |
+| `start`  | Start a run.                                                                              |
+| `read`   | Read the full state of a run, follow its feed, list the runs, and read its conversations. |
+| `answer` | Answer a Gate, and read the open Gates and their meta.                                    |
+| `cancel` | Cancel a run.                                                                             |
+| `steer`  | Send a Steering message to an Agent of a run.                                             |
+
+For a route that addresses a run, jr2 checks the scope against the Workflow of that run. The name of a Chart wrapper
+also opens each named Chart of that wrapper. A request without the scope gets 403, which names the scope and the
+Workflow. [`GET /runs`](../reference/http-api.md#get-runs) shows only the runs of the Workflows that the Caller can
+read. A few routes, such as a runtime Chart and the log of a Hook, need the Instance token: no scope opens them. The
+[HTTP API](../reference/http-api.md#band-guarded) gives the scope of each route.
+
+The `answer` scope can also name single Gates of a Workflow, with an item `{ workflow, gates }` beside the names of
+Workflows. The name of a Gate is its invoke id. A Caller with such an item answers only those Gates of that Workflow,
+and it sees only those Gates, in [`GET /gates`](../reference/http-api.md#get-gates) and in `GET /runs/:runId`. A gate
+POST to another open Gate of that Workflow gets 403, which names the scope, the Workflow and the Gate. `jr2 up` refuses
+a Gate name that the Machines of the Workflow do not have. The other scopes, and the `may.answer` of a Hook, name only
+Workflows.
+
+A scope does not limit what a run does. A run that a Caller starts can start a run of a different Workflow with a
+[`dispatch`](../reference/authoring-surface/dispatch.md) Effect. The Machine is the limit of what its run does.
+
+## On behalf of
+
+A Caller can say that it acts on behalf of a different party, in the header `jr2-on-behalf-of`. The CLI sends the name
+of your Kubernetes user. A bridge can send the name of the person in the chat service. jr2 records this name and shows
+it, but it does not check it. The one exception is a Hook: the name comes from the body of the delivery, and the
+signature of the service covers the body.
+
+## The record of each act
+
+The run records the Caller of each act on a guarded route: its `via`, its `name`, the name that jr2 shows, and
+`onBehalfOf`. It does not record the scopes.
+
+- `startedBy`: the Caller that started the run. A run that a local `dispatch` started records that run and the slot. A
+  run that jr2 started, such as the run of a standing Pool, records `jr2` and why: `boot`, `publish`, `hand-over` or
+  `resume`.
+- `cancelledBy`: the Caller that cancelled the run.
+- `answers`: the last 100 answers to the Gates of the run, each with the Caller that answered.
+
+The [Sender](../reference/glossary.md#sender) of an event that a Gate delivers also holds the Caller, and `checked`
+names the fields of it that jr2 checked. [`jr2 status`](../reference/cli.md#status) follows `startedBy` from run to run,
+to the first Caller, and prints it as `started by:`. The open routes do not show these records.
+
+## How a Hook behaves
+
+The `hooks` block of `jr2.config.ts` declares each Hook by its name, with its kind. The address of the Hook is
+`POST /hooks/<name>`. The kind makes the Hook from two things: the credential, and `may.answer`, the Workflows whose
+Gates the Hook can answer. The default is every Workflow. A Hook never starts a run. To bring items to a
+[Pool](../reference/glossary.md#pool), it answers the `source` Gate of the Pool, so `may.answer` must name the Workflow
+of the Pool.
+
+**One delivery at a Hook**
+
+- **Service**: a forge or a chat service
+- **Door**: the Hook's address in the Orchestrator
+- **Instance Effector**: holds a mac secret
+- **Kind**: the protocol of the service
+- **Handlers**: of the open Gates and Sources
+- Service → Door: a delivery
+- Door → Instance Effector: the signed bytes, for mac only
+- Instance Effector → Door: match, or no match
+- Door → Kind: the request, without a token header
+- Kind → Door: a handshake, or the event key, the id and the payload
+- Door → Handlers: the parsed payload
+- Door → Service: the outcome, or a text for a person
+
+The door does the same steps for each kind:
+
+1. **It verifies the delivery.** The kind tells what the service signed. The door runs one of three verifiers:
+   - `mac`: a shared secret signs the bytes, such as on GitHub and Slack. The
+     [Instance Effector](../reference/glossary.md#instance-effector) holds the secret, and it answers only "match" or
+     "no match". The Orchestrator never holds the secret, because a secret that verifies a delivery can also make one.
+   - `token`: the service sends a shared token in a header, such as on GitLab. The Orchestrator keeps only the SHA-256
+     digest of the token, and removes the header before the kind reads the request.
+   - `ed25519`: a key pair signs the delivery, such as on Discord. The config holds the public key, which cannot sign.
+
+   When the service signs a time, the door refuses a time that is more than 300 seconds from its clock. A delivery that
+   fails gets 401, and nothing more occurs.
+
+   Before the verifier, the door refuses a body that is larger than 2 MiB with 413. It reads no more of the body than
+   this limit.
+
+2. **The kind reads the delivery.** A handshake, such as a GitHub `ping`, gets the answer of the kind, and goes to no
+   Gate. Otherwise the kind gives the event key, the id of the delivery, `onBehalfOf` and the payload.
+3. **The schema of the event key parses the payload.** A payload that the schema refuses goes to no Gate.
+4. **The door looks for a repeat.** A delivery whose id or body the Hook got before goes to no Gate. The door does this
+   check after the parse, so a payload that the schema refused is parsed again when the service sends it again.
+5. **The delivery goes to each handler that hears it**: each open Gate and each Source, in each live run of a Workflow
+   that the Hook can answer, whose handlers name the kind and the event key. [Gates](gates.md#a-gate-that-hears-a-hook)
+   and [Pools and Sources](pools-and-sources.md#a-hook-reaches-a-source) tell what a handler gives.
+
+The answer is the outcome of the delivery, as JSON: where it went, and what each Gate or Source did with it. For a chat
+command or a click, the person who acted reads one text in the envelope of the kind
+([The answer that a person reads](gates.md#the-answer-that-a-person-reads)).
+
+The log of the Hook keeps each delivery and its outcome for `runs.retain`, 30 days by default. The repeat check reads
+it. Print it with [`jr2 hooks <name>`](../reference/cli.md#hooks).
+
+## Hook kinds
+
+A Hook kind is code that `jr2.config.ts` imports. It tells what the service signed, how to read a delivery and its
+payloads, the handshake of the service, and the envelope of a text that a person reads. A workflow module imports the
+same kind for the types of its handlers. Thus a handler for an event key that the kind does not give does not compile.
+
+- `@jr2/orchestrator/hooks` ships the kinds `github`, `gitlab`, `slack` and `discord`.
+- [`webhook()`](../reference/hooks.md#webhook) makes a kind from data, for a service that sends JSON, signs only the
+  body, and has no handshake.
+- [`defineHookKind()`](../reference/hooks.md#definehookkind) makes a kind for any other service, in a module of the
+  Instance or in a package of its own.
+
+A kind never gets the credential: jr2 makes the constructor of the kind, so the credential goes from the config to the
+door. A kind is pure and synchronous. It does no I/O, and it does not read a clock. The door does the verify, the time
+window, the repeat check and the follow-up post. When a kind gives a follow-up post, such as the reply to a Slack click,
+it declares the hosts of its posts, and `jr2 up` adds them to the targets of the Instance Effector.
+
+## Rules
+
+- The first authenticator that claims a credential decides. A credential that it finds bad gets 401.
+- A Sandbox token, a control token and the publish token are not Callers.
+- A request without the scope for the Workflow gets 403. A JWT that gets no scope gets 403 on each route that needs a
+  scope.
+- `onBehalfOf` is a claim. jr2 checks it only for a Hook, where the signature covers it.
+- A named token's value is in a Secret of its own. The Orchestrator keeps only its SHA-256 digest.
+- `cors` lists the origins of the browser apps on a different origin that can call the Orchestrator. The Console needs
+  no entry.
+- A Hook can only answer a Gate or bring items to a Source, of the Workflows in its `may.answer`. It never starts a run.
+- The door refuses a signed time that is more than 300 seconds from its clock. No config changes the window.
+- Two kinds with one id fail the typecheck and `jr2 up`.
+
+## Read next
+
+- [Give a Caller a scope](../guides/give-a-caller-a-scope.md)
+- [Answer a Gate from a forge](../guides/answer-a-gate-from-a-forge.md)
+- [Start a run for each alert](../guides/start-a-run-for-each-alert.md)
+- [Write a Hook kind](../guides/write-a-hook-kind.md)
+- [Open the Console](../guides/open-the-console.md)
+- [Secrets and trust](secrets-and-trust.md), [Gates](gates.md) and [Pools and Sources](pools-and-sources.md)
+- Reference: [`callers`](../reference/config.md#callers), [`hooks`](../reference/config.md#hooks),
+  [`cors`](../reference/config.md#cors), [`@jr2/orchestrator/hooks`](../reference/hooks.md),
+  [`jr2 whoami`](../reference/cli.md#whoami), [`jr2 hooks`](../reference/cli.md#hooks), and the
+  [HTTP API](../reference/http-api.md)
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): the
+  Callers, the scopes, the Hooks and the Hook kinds
+- [ADR-0014](../reference/decisions/0014-observation-is-open-run-state-is-not.md): which scope opens which route
+- [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): a Gate hears a Hook

package/docs/concepts/charts.md

@@ -30,9 +30,11 @@ it bad text.
 [Open](../reference/glossary.md#open) part that a run binds, not a composer. Its declaration has three parts:
 
 - **`lends`**: the parts of the Chart wrapper that a Chart can use, by their slot keys. These are Agents, Effects,
-  Machines, guards, actions and delays. `gate: true` lends the [Gate](../reference/glossary.md#gate), so that a Chart
-  can wait for a person. `fail: true` lends [`fail()`](../reference/authoring-surface/fail.md), so that a Chart can end
-  its run as a [Failure](../reference/glossary.md#failure) with `invoke: { src: "fail", input: { reason } }`.
+  Machines, Gate slots (`gates`), guards, actions and delays. `gate: true` lends the
+  [Gate](../reference/glossary.md#gate), so that a Chart can wait for a person. A lent Gate slot hears a
+  [Hook](../reference/glossary.md#hook), and the door refuses a Chart whose `events` do not hold each event of the
+  slot's `delivers`. `fail: true` lends [`fail()`](../reference/authoring-surface/fail.md), so that a Chart can end its
+  run as a [Failure](../reference/glossary.md#failure) with `invoke: { src: "fail", input: { reason } }`.
 - **`allows`**: what the Agents that a Chart adds can have. `models` lists the models, and `workspace` lists the
   Workspace accesses. With no model, a Chart cannot add an Agent.
 - **`ceilings`**: the limits of one Chart: the Agent Turns, the wall clock, the transitions, the children at one time,
@@ -107,8 +109,8 @@ wrapper only. It comes from one of two places:
 - A **runtime Chart**: `PUT /workflows/<wrapper>/charts/<name>`, with the Instance token. The Orchestrator keeps it on
   its volume. `DELETE` on the same path removes it.
 
-[`jr2 runs`](../reference/cli.md#runs) lists each named Chart under its wrapper. When a publish removes a part that a
-runtime Chart uses, the Chart stays, and it is unrunnable until a publish gives the part back.
+[`jr2 workflows`](../reference/cli.md#workflows) lists each named Chart under its wrapper. When a publish removes a part
+that a runtime Chart uses, the Chart stays, and it is unrunnable until a publish gives the part back.
 
 ## A run keeps its Chart
 

package/docs/concepts/composition.md

@@ -250,7 +250,7 @@ show.
 | Key         | What it changes                                                                       |
 | ----------- | ------------------------------------------------------------------------------------- |
 | `agents`    | The definition of an Agent, by slot, field by field. `{ model }` keeps the rest.      |
-| `effects`   | The Open url, argv or secret of an Effect, by slot.                                   |
+| `effects`   | The Open url, argv, secret, MCP server or tool of an Effect, by slot.                 |
 | `actors`    | A Machine that this Machine composes, by slot. The value has the same keys, one down. |
 | `repos`     | The Repo Slots of the [`workspace()`](../reference/authoring-surface/workspace.md).   |
 | `image`     | The Sandbox Image of the `workspace()`.                                               |
@@ -272,6 +272,7 @@ A Machine marks a part Open with [`open`](../reference/authoring-surface/open.md
 - a Repo Slot with no url, or the whole Repo Slot map (`repos: open`)
 - the model of an Agent (`agent({ model: open, … })`)
 - the url of an `http` Effect, the argv of a `command`, or the name of the secret of an Effect (`secret(open)`)
+- the server or the tool of an `mcp` Effect (`mcp.call(open, open, { input })`)
 
 An Open part has no default. You bind it with `customize()`. Each Open part has two checks:
 
@@ -280,6 +281,14 @@ An Open part has no default. You bind it with `customize()`. Each Open part has
 - At run time, the part refuses too. An Agent does not start a [Turn](../reference/glossary.md#turn) with an Open model.
   An Effect does not run while it is Open.
 
+One Open part only warns: the look of a Gate slot (`look: open`). `jr2 up` prints a warning for a look that nobody
+bound, because a person can still answer the Gate with `jr2 send`.
+
+The MCP servers of an Agent are not Open. A packaged Machine's Agent names the servers that it needs, such as
+`slack-acme`. When the `mcp` block of your `jr2.config.ts` does not declare that name, `jr2 up` refuses the Workflow and
+prints the `customize()` line that binds the Agent to a server that you declare:
+`customize(machine, { agents: { <slot>: { mcp: [...] } } })`. The list replaces the Agent's whole `mcp` list.
+
 [Bind a shipped Machine's Open parts](../guides/bind-open-parts.md) shows each binding.
 
 ## @jr2/machines

package/docs/concepts/converge.md

@@ -40,7 +40,7 @@ The diagram shows what `jr2 up` makes, and what [`jr2 run`](../reference/cli.md#
       - **Assembly**: your Workflows and your config
     - **jr2-instance Secret**: holds the Instance token
     - **Instance Harness**: when an Agent is Menu-only
-    - **Instance Effector**: when an Effect runs there
+    - **Instance Effector**: when an Effect runs there, or a Hook needs it
     - **Repo cache**: when a Machine has a Sandbox
   - ↓ the Orchestrator asks for each Sandbox · ↑ the operator makes its pod
   - **jr2-system**: one for each cluster
@@ -79,7 +79,9 @@ the cluster, see [Architecture](architecture.md).
     Until each check passes, `jr2 up` writes nothing that the Instance or the operator reads. The pod has up to 5
     minutes to start, and each model has up to 6 minutes. `jr2 up` writes each model's result as it comes. With
     `--skip-provider-preflight`, no pod checks the models, and `jr2 up` writes a warning that names each model that it
-    did not check.
+    did not check. The same pod asks each remote MCP server that an Agent names for its tools, through its Custodian.
+    `jr2 up` refuses an allowlisted tool that the server does not list, and a server that refuses the token. The flag
+    skips this check too.
 12. It applies the operator. For a Repo with an ssh url, it asks where the deploy key comes from.
 13. It applies the Secrets and the Orchestrator, and waits for the rollout. When the Machines need them, it also waits
     for the Repo cache, the Instance Harness and the [Instance Effector](../reference/glossary.md#instance-effector).

package/docs/concepts/durable-runs.md

@@ -7,7 +7,8 @@ description: How a run survives a restart of the Orchestrator, what ends it, and
 
 A run is durable. The [Orchestrator](../reference/glossary.md#orchestrator) saves each run after each transition of its
 [Machine](../reference/glossary.md#machine). When the Orchestrator starts again, it continues each run that did not end,
-from the state that it saved. A run that ended stays readable for one week.
+from the state that it saved. A run that ended stays readable for [`runs.retain`](../reference/config.md#runs), 30 days
+by default.
 
 ## Why runs are durable
 
@@ -78,7 +79,7 @@ A run that the Orchestrator does not continue gets one of these results:
 
 | Result    | When                                                                                                        | What stays                                         |
 | --------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `lost`    | No Workflow has the name of the run's file, or the row holds no snapshot.                                   | The row and the reason, for one week.              |
+| `lost`    | No Workflow has the name of the run's file, or the row holds no snapshot.                                   | The row and the reason, for `runs.retain`.         |
 | `drifted` | The Orchestrator cannot read the Assembly of the run, or the Machine of the Workflow has a different shape. | The row and the snapshot.                          |
 | `failed`  | The restore of the run stopped with an error.                                                               | The run stays live. The next start tries it again. |
 
@@ -112,8 +113,9 @@ Orchestrator cannot read the Assembly that the run holds:
 
 The Orchestrator keeps a drifted run, and you can read it. [`jr2 status`](../reference/cli.md#status) shows its status,
 `drifted`, with the reason. The reason names the Workflow and the two digests, or the Assembly and why it cannot load.
-[`jr2 runs`](../reference/cli.md#runs) does not show it, because `jr2 runs` shows only the runs that run now. jr2 cannot
-move a drifted run to a new Machine. Thus, before you change the Kit version, let the runs end, or cancel them.
+By default, [`jr2 runs`](../reference/cli.md#runs) shows only the live runs, so it does not show a drifted run.
+`jr2 runs --status drifted`, `--status ended` or `--status all` shows it with its reason. jr2 cannot move a drifted run
+to a new Machine. Thus, before you change the Kit version, let the runs end, or cancel them.
 
 ## CANCEL and stop
 
@@ -137,18 +139,40 @@ The operator removes them after the same idle timeout. A run that a Machine fail
 
 `jr2 status` shows a cancelled run with the status `cancelled` and the state that it was in.
 
-## One week of history
+## History
 
-jr2 keeps the row of a run that ended for 7 days after its last write. This is true for each status that is not live:
-`done`, `failed`, `error`, `cancelled`, `lost` and `drifted`. The Orchestrator deletes the older rows when it starts,
-and one time each hour after that. A live run stays, whatever its age. A run that waits at a Gate for a month is still
-there.
+jr2 keeps the row of a run that ended for 30 days after its last write. `runs.retain` in `jr2.config.ts` changes this
+time, for example `runs: { retain: "90d" }`. It is a number and `m`, `h`, `d` or `w`, and it is at least `1h`. This is
+true for each status that is not live: `done`, `failed`, `error`, `cancelled`, `lost` and `drifted`. The Orchestrator
+deletes the older rows when it starts, and one time each hour after that. A live run stays, whatever its age. A run that
+waits at a Gate for a month is still there.
 
-You cannot change the 7 days. jr2 is not the record of the results of a run. A Machine sends its results where they
-belong, such as a pull request. `jr2 status` on a run that ended is for debugging. After the 7 days, `jr2 status` says
-that the run does not exist, and a prefix of its id no longer finds it.
+`jr2 runs --status ended` lists the runs that ended, newest first. `--workflow` and `--since` make the list shorter. jr2
+is not the record of the results of a run. A Machine sends its results where they belong, such as a pull request.
+`jr2 status` on a run that ended is for debugging. After `runs.retain`, `jr2 status` says that the run does not exist,
+and a prefix of its id no longer finds it.
 
-The week of a drifted run starts at the restart or the publish that refused it, not at its last transition.
+The time of a drifted run starts at the restart or the publish that refused it, not at its last transition.
+
+The same time applies to the [Conversations](../reference/glossary.md#conversation) of a run and to the log of each
+[Hook](../reference/glossary.md#hook). The Orchestrator keeps each conversation of an Agent while the run is kept, and
+deletes it with the row of the run. Thus `jr2 logs` reads the conversations of a run that ended, also after its
+[Sandbox](../reference/glossary.md#sandbox) is gone. [Read a conversation](../guides/read-a-conversation.md) gives the
+commands.
+
+### The state volume
+
+The Orchestrator keeps the rows of the runs, the conversations, the Assemblies and the
+[Charts](../reference/glossary.md#chart) on its state volume. A new volume claim is `5Gi` by default, and `jr2 up` keeps
+the size of a claim that exists. `runs.volume` in `jr2.config.ts` sets its size, such as `runs: { volume: "20Gi" }`.
+`jr2 up` makes the claim larger when its StorageClass allows expansion, and refuses otherwise. It never makes a claim
+smaller, because Kubernetes cannot.
+
+A space guard keeps the volume from becoming full. When the volume is more than 80% full, the Orchestrator deletes the
+conversations of the runs that ended, the oldest run first, until the volume is less than 80% full. The rows of the runs
+stay, and each one shows that its conversations went for space. The guard never deletes a conversation of a live run.
+When the volume is more than 95% full and no ended run has a conversation left, the Orchestrator keeps no more entries
+of the open conversations. One conversation also has a limit of 8 MiB, after which the Orchestrator keeps no more of it.
 
 [`jr2 down`](../reference/cli.md#down) deletes the namespace of the Instance, and the store with it. The live runs go
 too.
@@ -162,7 +186,9 @@ too.
 - The Orchestrator never continues a drifted run, and never moves it to a new Machine.
 - The Orchestrator never continues a cancelled run.
 - `CANCEL` is the only run event that `jr2 send` sends without `--gate`. `--keep` goes only with `CANCEL`.
-- jr2 keeps a run that ended for 7 days. The hourly sweep never deletes a live run.
+- jr2 keeps a run that ended for `runs.retain`, 30 days by default. The hourly sweep never deletes a live run.
+- jr2 keeps the conversations of a run for as long as it keeps the run, unless the space guard deletes them first. The
+  space guard never deletes a conversation of a live run.
 
 [Cancel a run](../guides/cancel-a-run.md) and [Watch a run](../guides/watch-a-run.md) give the commands and their
 output.
@@ -170,6 +196,7 @@ output.
 ## Read next
 
 - [Watch a run](../guides/watch-a-run.md)
+- [Read a conversation](../guides/read-a-conversation.md)
 - [Cancel a run](../guides/cancel-a-run.md)
 - [Iterate on a Machine on kind](../guides/iterate-on-a-machine-on-kind.md)
 - [Effects](effects.md), [Workspaces](workspaces.md) and [Converge](converge.md)
@@ -183,7 +210,7 @@ output.
 - [ADR-0025](../reference/decisions/0025-cancel-ends-a-run-stop-parks-it.md): `CANCEL` ends a run, and a stop parks it
 - [ADR-0030](../reference/decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md): a snapshot names the
   Machine that wrote it
-- [ADR-0065](../reference/decisions/0065-a-persist-survives-a-crash-and-history-is-a-week.md): a save survives a crash,
-  and jr2 keeps a week of history
+- [ADR-0065](../reference/decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md): a save
+  survives a crash, and jr2 keeps history for `runs.retain`
 - [ADR-0069](../reference/decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md): a
   run holds the Assembly that it started under

package/docs/concepts/effects.md

@@ -1,14 +1,14 @@
 ---
 title: Effects
-description: How a Machine runs a command, calls a URL, pushes a branch or starts a run, at most once.
+description: How a Machine runs a command, calls a URL or an MCP tool, pushes a branch or starts a run.
 ---
 
 # Effects
 
 An [Effect](../reference/glossary.md#effect) is work that a [Machine](../reference/glossary.md#machine) does outside
-itself. jr2 has four kinds: `command` runs a program in the [Workspace](../reference/glossary.md#workspace), `http`
-calls a URL, `push` pushes the branch of a [Worktree](../reference/glossary.md#worktree), and `dispatch` starts a run of
-a [Workflow](../reference/glossary.md#workflow). The Kit also gives
+itself. jr2 has five kinds: `command` runs a program in the [Workspace](../reference/glossary.md#workspace), `http`
+calls a URL, `push` pushes the branch of a [Worktree](../reference/glossary.md#worktree), `dispatch` starts a run of a
+[Workflow](../reference/glossary.md#workflow), and `mcp` calls a tool of an MCP server. The Kit also gives
 [`worktree()`](../reference/authoring-surface/worktree.md), an Effect on the `command` machinery that cuts a Worktree.
 You write an Effect as an actor slot, beside the [Agents](../reference/glossary.md#agent) of the Machine.
 
@@ -293,7 +293,7 @@ failures: workflow "test-and-push" — the states that fail the run (ADR-0073)
   test-and-push.lost: invokes fail
 ```
 
-## The four kinds
+## The five kinds
 
 ### `command`
 
@@ -483,8 +483,9 @@ Worktree is, and [Cut a Worktree](../guides/cut-a-worktree.md) tells how to use
 [`dispatch`](../reference/authoring-surface/dispatch.md) starts a run of a Workflow. The new run is a run of its own: it
 has its own line in [`jr2 runs`](../reference/cli.md#runs), its own Workspaces and its own `CANCEL`. Its record names
 the run that started it: it is **dispatched by** that run. Use `dispatch` when a Machine waits for work, for example at
-a [Gate](../reference/glossary.md#gate) that a webhook answers, and each item of work needs a run of a Workflow that you
-have. To use a Machine as a part of one run, invoke it in the run instead (see [Composition](composition.md)).
+a [Gate](../reference/glossary.md#gate) that a [Hook](../reference/glossary.md#hook) answers, and each item of work
+needs a run of a Workflow that you have. To use a Machine as a part of one run, invoke it in the run instead (see
+[Composition](composition.md)).
 
 - The name of the Workflow is a constant of the definition, as `jr2 run` writes it: `"triage"`, or `"<wrapper>/<name>"`
   for a named [Chart](../reference/glossary.md#chart). An Agent cannot choose it.
@@ -496,12 +497,27 @@ have. To use a Machine as a part of one run, invoke it in the run instead (see [
   minutes with `wait`.
 - With no `target`, the new run starts in the same Orchestrator. With
   `target: { url: "https://<host>", token: secret("<name>") }`, it starts on a different Orchestrator. `url` is the
-  origin of that Orchestrator, and the secret holds its Instance token.
+  origin of that Orchestrator, and the secret holds the token of a [Caller](../reference/glossary.md#caller) of that
+  Orchestrator with the `start` scope for the Workflow, and also `read` when `wait` is `true`.
 - The new run starts under the current [Assembly](../reference/glossary.md#assembly), as a run of `jr2 run` does.
 
 The two runs are independent. A `CANCEL` of one run does not cancel the other. When the run that dispatched ends, the
 new run continues.
 
+### `mcp`
+
+[`mcp`](../reference/authoring-surface/mcp.md) calls an MCP server: `mcp.call(server, tool, { input })` calls a tool,
+`mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a prompt. `server` is a name of
+the [`mcp`](../reference/config.md#mcp) block of `jr2.config.ts`, which holds the URL and the secret of the server. Thus
+the definition holds no URL and no credential, and an Agent's word can reach only the arguments, through the input.
+
+An Agent can also hold the tools of a server as [MCP tools](../reference/glossary.md#mcp-tools), and call them in its
+Turn with no approval (see [Agents and Turns](agents-and-turns.md#the-mcp-tools)). Use an `mcp` Effect when the call
+needs the approval of a person, or when the Machine makes the call with no model. The Agent picks, a Gate waits for the
+approval, and the Effect calls the tool. The output of the Effect is the answer to the pick. Thus the approval is in the
+record of the run, and the Machine routes on it. The default timeout is the `timeout` of the server: 60 seconds when it
+sets none. [Call an MCP tool from a Machine](../guides/call-an-mcp-tool-from-a-machine.md) has an example.
+
 ## Where an Effect runs
 
 You do not choose where an Effect runs. The kind, and what the Effect names, decide it. Each
@@ -518,6 +534,7 @@ commands in it:
 | A `push`                                | The Sandbox Effector                                                                |
 | A `dispatch` with no `target`           | The Orchestrator, in its own process                                                |
 | A `dispatch` with a `target`            | The Instance Effector                                                               |
+| An `mcp` Effect                         | The Instance Effector                                                               |
 
 A `command` that names no Effect secret runs beside the Agent's [Working tools](../reference/glossary.md#working-tools).
 It runs as the Agent's user, with the tools of the [Sandbox Image](../reference/glossary.md#sandbox-image). The Harness
@@ -537,17 +554,19 @@ Effector is, and [Secrets and trust](secrets-and-trust.md) tells how an Effector
 
 An Effect gives each outcome to `onDone`, a failure too. Route on the `outcome` field:
 
-| Kind       | The outcomes                                              | The output type                                                           |
-| ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `worktree` | `ready`, `refused`, `unknown`                             | [`WorktreeOutput`](../reference/authoring-surface/type-worktreeoutput.md) |
-| `command`  | `exited`, `timeout`, `killed`, `unknown`                  | [`CommandOutput`](../reference/authoring-surface/type-commandoutput.md)   |
-| `http`     | `response`, `unreachable`, `refused`, `unknown`           | [`HttpOutput`](../reference/authoring-surface/type-httpoutput.md)         |
-| `push`     | `pushed`, `rejected`, `diverged`, `unknown`               | [`PushOutput`](../reference/authoring-surface/type-pushoutput.md)         |
-| `dispatch` | `started`, `settled`, `refused`, `unreachable`, `unknown` | [`DispatchOutput`](../reference/authoring-surface/type-dispatchoutput.md) |
+| Kind       | The outcomes                                                      | The output type                                                           |
+| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `worktree` | `ready`, `refused`, `unknown`                                     | [`WorktreeOutput`](../reference/authoring-surface/type-worktreeoutput.md) |
+| `command`  | `exited`, `timeout`, `killed`, `unknown`                          | [`CommandOutput`](../reference/authoring-surface/type-commandoutput.md)   |
+| `http`     | `response`, `unreachable`, `refused`, `unknown`                   | [`HttpOutput`](../reference/authoring-surface/type-httpoutput.md)         |
+| `push`     | `pushed`, `rejected`, `diverged`, `unknown`                       | [`PushOutput`](../reference/authoring-surface/type-pushoutput.md)         |
+| `dispatch` | `started`, `settled`, `refused`, `unreachable`, `unknown`         | [`DispatchOutput`](../reference/authoring-surface/type-dispatchoutput.md) |
+| `mcp`      | `returned`, `refused`, `unreachable`, `input-required`, `unknown` | [`McpCallOutput`](../reference/authoring-surface/type-mcpcalloutput.md)   |
 
 A test that fails is `exited` with a code that is not 0. A program that the container does not have is `exited` with
 code 127. An HTTP 4xx or 5xx status is a `response`. A Workflow that refuses the run input of a `dispatch` is `refused`,
-with the status code and the report of the refusal. `unknown` means that jr2 cannot tell what the Effect did.
+with the status code and the report of the refusal. A tool of an `mcp` Effect that ran and failed is `returned` with
+`isError: true`. `unknown` means that jr2 cannot tell what the Effect did.
 
 Each union is open: it holds a stand-in member, `LaterOutcome`, so a later release can add an outcome and your Machine
 still works. Route on what you know, and give the rest a last arm with no guard. With no match, the run stays in that
@@ -576,6 +595,7 @@ jr2 records its output. After an Orchestrator restart, jr2 reads the record:
 | A `worktree()`                          | jr2 attaches to it again. When the Harness does not know it, jr2 sends it again: a cut is idempotent.                                                        |
 | A `push`                                | jr2 follows it. When the Sandbox Effector lost it, jr2 pushes the same commit again, and no other commit. With no commit recorded, the outcome is `unknown`. |
 | An `http` Effect                        | jr2 follows it. When no Effector holds it, jr2 sends it again only if it is `idempotent`. Else the outcome is `unknown`.                                     |
+| An `mcp` Effect                         | As an `http` Effect. jr2 does not read the `idempotentHint` of a tool: only your `idempotent` mark counts.                                                   |
 | A `dispatch`                            | jr2 sends the start again, with the same key. The Orchestrator answers with the run that the key started, and it starts no second run.                       |
 
 A `command` that names no Effect secret runs the code of the Worktree, and that code can spend a Stand-in. Thus jr2 does
@@ -583,7 +603,8 @@ not run it two times. A `push`, and a `command` that names an Effect secret, run
 jr2 can send them again with that commit.
 
 To try again, write it in the Machine: a route from the outcome back into the state. Mark an `http` Effect `idempotent`
-only when a second call is safe: the call has its own idempotency key, or it only reads.
+only when a second call is safe: the call has its own idempotency key, or it only reads. The same rule is true for an
+`mcp` Effect.
 
 ## When the state exits
 
@@ -592,8 +613,8 @@ When the run leaves the state, the Effect stops:
 - jr2 kills the process group of a `command` that names no Effect secret.
 - The Sandbox Effector stops a `command` that names an Effect secret. It sends `SIGTERM`, waits 5 seconds, then sends
   `SIGKILL`.
-- An `http` Effect and a `push` have no stop. jr2 stops waiting for the output, but the Effector can still finish the
-  work.
+- An `http` Effect, an `mcp` Effect and a `push` have no stop. jr2 stops waiting for the output, but the Effector can
+  still finish the work.
 - A `dispatch` with `wait` stops its wait. The run that it started continues.
 
 jr2 records the stop, and the Machine gets no output. There is no "finally" in a Machine: cleanup is a state. Put an
@@ -633,11 +654,14 @@ pick waits for its answer.
   a `committer` field there.
 - Each param of a pick that enters an Effect's state has a reader: the Effect's input, `fill`, a guard or an `assign`.
   `createMachine` refuses a param that nothing reads, and a `fill` key that is also a param.
-- A packaged Machine can leave an `http` URL, a `command` argv, one Effect secret name or the `target` of a `dispatch`
-  Open. The composer binds it one time with `customize()`. `jr2 up` refuses an Open part that nobody bound.
+- A packaged Machine can leave an `http` URL, a `command` argv, one Effect secret name, the `target` of a `dispatch`, or
+  the server and the tool of an `mcp` Effect Open. The composer binds it one time with `customize()`. `jr2 up` refuses
+  an Open part that nobody bound.
 - A `dispatch` with no `target` names a Workflow that the Assembly has. `jr2 up` refuses a name that it does not have,
   and an `input` schema that the input of that Workflow does not take.
 - The `url` of a `dispatch` target is an origin only: a scheme, a host and a port, with no path, no query and no user.
+- An `mcp` Effect names a remote server that the `mcp` block declares. `jr2 up` refuses a server that the block does not
+  declare, and a stdio server.
 
 The guides give the refusal text of each rule.
 
@@ -646,13 +670,17 @@ The guides give the refusal text of each rule.
 - [Run a command or call a URL with an Effect](../guides/run-a-command-or-call-a-url.md)
 - [Push and sign a branch](../guides/push-and-sign-a-branch.md)
 - [Start a run from a run](../guides/start-a-run-from-a-run.md)
+- [Call an MCP tool from a Machine](../guides/call-an-mcp-tool-from-a-machine.md)
 - [Workspaces](workspaces.md), [The Menu](the-menu.md), [Secrets and trust](secrets-and-trust.md)
 - Reference: [`command`](../reference/authoring-surface/command.md), [`http`](../reference/authoring-surface/http.md),
   [`push`](../reference/authoring-surface/push.md), [`dispatch`](../reference/authoring-surface/dispatch.md),
-  [`fromPick`](../reference/authoring-surface/frompick.md), [`answer`](../reference/authoring-surface/answer.md)
+  [`mcp`](../reference/authoring-surface/mcp.md), [`fromPick`](../reference/authoring-surface/frompick.md),
+  [`answer`](../reference/authoring-surface/answer.md)
 - [ADR-0067](../reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md):
   an Effect is an actor slot, and runs at most once unless marked idempotent
 - [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md): an Effector holds
   an Effect's secrets and signs its wire
 - [ADR-0071](../reference/decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md): a run starts a run through a
   `dispatch` Effect
+- [ADR-0079](../reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md):
+  a Machine calls an MCP server as an Effect, and the Machine is the approval