@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/concepts/architecture.md

@@ -19,8 +19,8 @@ runs and what it does.
 ## Why the parts are separate
 
 An Agent that works on a Repo runs code. Its [Working tools](../reference/glossary.md#working-tools) give it a shell.
-With the shell, it can read each file and each variable in its container. It can also connect to each address that its
-pod can reach. Thus jr2 puts each thing that the Agent must not touch in a different place:
+With the shell, it can run each program of its image on the files in `/work`. It can also connect to each address that
+its pod can reach. Thus jr2 puts each thing that the Agent must not touch in a different place:
 
 - The control of a run is in the Orchestrator. An Agent cannot change its own Machine. It can only pick from its
   [Menu](../reference/glossary.md#menu), and the Orchestrator decides what each pick does.
@@ -28,6 +28,8 @@ pod can reach. Thus jr2 puts each thing that the Agent must not touch in a diffe
   processes. Agents in two Workspaces share no files and no ports. [Workspaces](workspaces.md) tells more.
 - The credentials are in containers in which the Agent executes nothing: the Custodian, the Effector and the Repo cache.
   [Secrets and trust](secrets-and-trust.md) tells how.
+- The Harness holds one secret value, with which it sends the picks. Each program that it starts runs confined with
+  Landlock, so the code of an Agent cannot read that value.
 
 ## What runs where
 
@@ -44,7 +46,7 @@ pod can reach. Thus jr2 puts each thing that the Agent must not touch in a diffe
     - **Instance Harness**: runs the Turns of the Menu-only Agents
       - Harness
       - Custodian
-    - **Instance Effector**: runs the Effects that read no Worktree file
+    - **Instance Effector**: runs the Effects that read no Worktree file, and checks a Hook's signature
     - **Repo cache**: one pod on each Sandbox node
   - ↓ a Turn, an Effect · ↑ a pick, through the Custodian · ↓ the Repo cache gives each Repo
   - **Sandbox**: one pod for each Workspace, in the same namespace
@@ -66,7 +68,7 @@ The [Instance Harness](../reference/glossary.md#instance-harness), the
 sections below tell when.
 
 A Sandbox pod can also have a [User Container](../reference/glossary.md#user-container), when its `workspace()` names
-one. It runs its own image, and it mounts the [Worktree](../reference/glossary.md#worktree) read-write.
+one. It runs its own image, and it mounts `/work`, with each [Worktree](../reference/glossary.md#worktree), read-write.
 [Workspaces](workspaces.md) tells more.
 
 ## On your computer
@@ -82,23 +84,30 @@ to the Orchestrator's Service, for the life of the command. The [global options]
 tell how to give a URL and a token instead. The CLI keeps no local state about the cluster.
 
 The [Console](../reference/glossary.md#console) is a page that the Orchestrator serves. You open it in a browser,
-through a port forward that you start. [Open the Console](../guides/open-the-console.md) gives the commands.
+through a port forward that you start. It draws the Machine of each live run, and marks a run that started on an older
+[Assembly](../reference/glossary.md#assembly). With the credential of a [Caller](../reference/glossary.md#caller), it
+shows the open [Gates](../reference/glossary.md#gate) that you can answer. With the credential of a Caller that has
+`read`, it also lists the ended runs, and shows the [Conversations](../reference/glossary.md#conversation) of the Agents
+in a drawer at the bottom. [Open the Console](../guides/open-the-console.md) gives the commands.
+
+The `jr2 workspace` commands do not talk to the Orchestrator. They read the Sandbox resources with your kubectl
+credentials, and open a shell or a port forward into a Sandbox pod. Thus they work when the Orchestrator is down.
 
 ## The Orchestrator
 
 The Orchestrator is one pod for each Instance (`replicas: 1`), with the Service `jr2-orchestrator` on port 4000. It
 hosts all the [Workflows](../reference/glossary.md#workflow) of the Instance and many runs of each Workflow. It keeps
-the snapshot of each run on its own volume, so a run continues after a restart. [Durable runs](durable-runs.md) tells
-how.
+the snapshot of each run on its own volume, so a run continues after a restart. It also keeps there the conversation of
+each Agent, which each Harness sends during the Turn. [Durable runs](durable-runs.md) tells how, and for how long.
 
 The pod runs the `jr2-orchestrator` [Kit image](../reference/glossary.md#kit-image), which holds no code of yours. The
-Orchestrator loads your Workflows and your config from the [Assembly](../reference/glossary.md#assembly) that `jr2 up`
-publishes to it, and it keeps each Assembly on its volume. [Converge](converge.md#the-assembly) tells how.
+Orchestrator loads your Workflows and your config from the Assembly that `jr2 up` publishes to it, and it keeps each
+Assembly on its volume. [Converge](converge.md#the-assembly) tells how.
 
 The Orchestrator does these things:
 
 - It runs each Machine as an [xstate](https://xstate.js.org) actor, and holds the state of each run.
-- It serves the HTTP API that the CLI, the Console, a webhook and the Custodians call. See the
+- It serves the HTTP API that the CLI, the Console, the other Callers, the Hooks and the Custodians call. See the
   [HTTP API](../reference/http-api.md).
 - It sends each Turn to a Harness, and judges each pick that comes back.
 - It writes a Sandbox resource when a run enters a Workspace. Then it watches the Sandbox resource until the Workspace
@@ -114,34 +123,41 @@ To isolate two sets of Workflows, use two Instances. Each Instance has its own n
 ## The Harness
 
 The Harness is jr2's own server for the Turns of Agents. It speaks to the model provider. It gives the model the Agent's
-Menu and its Working tools. It executes each Working tool that the model calls, and sends each pick through the
-Custodian. It holds no Agents of its own. Each Turn brings the Agent's definition with it.
-[Agents and Turns](agents-and-turns.md) tells what happens in a Turn.
+Working tools, its [MCP tools](../reference/glossary.md#mcp-tools) and its Menu. It executes each Working tool that the
+model calls, and sends each pick through the Custodian. It is the MCP client of the Agent: it calls each MCP tool on its
+server, a remote one through the Custodian, or a stdio one that it starts. Each program that a Working tool starts runs
+confined with Landlock, and so does each stdio MCP server. The Harness holds no Agents of its own. Each Turn brings the
+Agent's definition with it. [Agents and Turns](agents-and-turns.md) tells what happens in a Turn.
 
 The Harness has two placements:
 
 - **In each Sandbox.** The Harness is the primary container of the Sandbox pod, named `harness`. It runs in the
   [Sandbox Image](../reference/glossary.md#sandbox-image), and jr2 mounts the Harness into the pod at `/opt/jr2`. Thus
-  the Working tools of the Agent reach the tools of that image. An Agent that works on a Repo has its Turns here.
+  the Working tools of the Agent reach the tools of that image. Each Agent that works on a Repo has its Turns here: one
+  Harness serves all the Agents of the Sandbox.
 - **As the Instance Harness.** The Instance Harness is one StatefulSet for each Instance, `jr2-instance-harness`. Each
   Turn of a Menu-only Agent (`workspace: "none"`) runs here. Its pod has a Harness and a Custodian, and no Worktree. It
-  keeps each conversation on its volume while a run can continue it. `jr2 up` converges it when a Machine of the
-  Instance has a Menu-only Agent.
+  runs no program of an Agent, so its Agents can use only remote MCP servers. It keeps each conversation on its volume
+  while a run can continue it. `jr2 up` converges it when a Machine of the Instance has a Menu-only Agent.
 
 A Harness answers only the Orchestrator. The Orchestrator sends a bearer token on each call, and the Harness accepts no
 call without it, except its health check. `jr2 up` also converges NetworkPolicies that let only the Orchestrator's pods
-connect to a Harness pod.
+connect to a Harness pod, and that stop each Harness pod at the cloud metadata addresses
+([Secrets and trust](secrets-and-trust.md#what-a-held-secret-does-not-stop)).
 
 ## The Custodian
 
 Each Harness pod has a Custodian: each Sandbox, and the Instance Harness. The Custodian is a container beside the
 Harness. The Agent executes no code in it. It does two things:
 
-- It carries four kinds of call from the pod to the Orchestrator: the Menu reads, the picks, the polls for the answer to
-  a pick, and the fetch asks. It sends each one with the pod's Sandbox token. These four routes are all that it
-  forwards. It refuses all other routes.
-- It holds the [Held secrets](../reference/glossary.md#held-secret) of its pod, such as a model API key. It puts the
-  value into the requests that go to the hosts of each Held secret.
+- It carries six kinds of call from the pod to the Orchestrator: the Menu reads, the picks, the polls for the answer to
+  a pick, the reports that a step boundary gave its notices to the model, the batches of the conversation's entries, and
+  the fetch asks. It sends the first five with the control token of the Sandbox, and the fetch asks with its fetch
+  token. These six routes are all that it forwards. It refuses all other routes. The Harness sends the first five on a
+  Unix socket in `/run/jr2`. A confined program cannot make a socket there, and the Custodian refuses a request on it
+  that does not have the control Stand-in. The fetch asks go to port `8081` on loopback.
+- It holds the [Held secrets](../reference/glossary.md#held-secret) of its pod, such as a model API key or the token of
+  an MCP server. It puts the value into the requests that go to the hosts of each Held secret.
 
 The Custodian runs Envoy, from a [Pinned image](../reference/glossary.md#pinned-image). The Orchestrator writes its
 config for a Sandbox, and `jr2 up` writes it for the Instance Harness. [Secrets and trust](secrets-and-trust.md) tells
@@ -149,20 +165,25 @@ how the Custodian holds a credential.
 
 ## The Effector
 
-The Effector runs each `http` and `push` Effect, each `command` that names an Effect secret, and each `dispatch` that
-names a target. Thus a credential that an Effect uses stays out of the Harness container. The Effector is jr2's own
+The Effector runs each `http`, `mcp` and `push` Effect, each `command` that names an Effect secret, and each `dispatch`
+that names a target. Thus a credential that an Effect uses stays out of the Harness container. The Effector is jr2's own
 program, and it runs in a container in which the Agent executes nothing. [Effects](effects.md) tells which Effect runs
 where. It has two placements:
 
-- **The Sandbox Effector** is a container in a Sandbox pod, named `effector`. It mounts the Worktree read-only. It runs
-  a `push`, an `http` Effect whose body is a Worktree file, and a `command` that names an Effect secret. Its image is
-  the Sandbox Image, unless the `workspace()` names a different image.
+- **The Sandbox Effector** is a container in a Sandbox pod, named `effector`. It mounts `/work` read-only. It runs a
+  `push`, an `http` Effect whose body is a Worktree file, and a `command` that names an Effect secret. Its image is the
+  Sandbox Image, unless the `workspace()` names a different image.
 - **The Instance Effector** is one pod for each Instance, `jr2-instance-effector`. It runs each `http` Effect that reads
-  no Worktree file, and each `dispatch` that starts a run on a different Orchestrator. It holds the Instance token of
-  that Orchestrator as an Effect secret. It runs in the `jr2-harness` Kit image.
+  no Worktree file, each `mcp` Effect, and each `dispatch` that starts a run on a different Orchestrator. It holds the
+  token of each MCP server that an `mcp` Effect calls, and the Caller token for that Orchestrator, as Effect secrets. It
+  also serves the [Hooks](../reference/glossary.md#hook): it holds the secret of each Hook that checks a signature with
+  a shared secret (`mac`) and checks the signature, and it sends the follow-up of a kind that posts one, such as the
+  reply to a Slack click. It runs in the `jr2-harness` Kit image.
 
-Each placement exists only when a Machine of the Instance puts an Effect there. A `command` that names no Effect secret
-does not use an Effector. It runs in the Harness container of its Sandbox, with the same tools and access as the Agent.
+A Sandbox Effector exists only when a Machine of the Instance puts an Effect there. The Instance Effector exists only
+when a Machine puts an Effect there or a Hook needs it. A `command` that names no Effect secret does not use an
+Effector. It runs in the Harness container of its Sandbox, with the same tools and access as the Agent, and confined in
+the same way.
 
 The Orchestrator signs each request that it sends to an Effector, and the Effector signs each answer. The Orchestrator
 only asks, and the Effector holds the credentials.
@@ -188,7 +209,8 @@ the Orchestrator stopped for longer than the Lease allows. [Workspaces](workspac
 
 The Repo cache keeps one bare clone of each Repo on each node that needs it. It is a DaemonSet, `jr2-repo-cache`, in the
 namespace of the Instance. It has one pod on each [Sandbox node](../reference/glossary.md#sandbox-node). `jr2 up`
-converges it when a Machine of the Instance uses a Sandbox.
+converges it when a Machine of the Instance uses a Sandbox. Each pod also checks that the kernel of its node has
+Landlock. On a node without Landlock, the pod is not ready, and `jr2 up` names that node and refuses to converge.
 
 The operator mounts the cache of each Repo into a Sandbox, read-only, at `/repos`. The clone in the Sandbox gets its
 objects from that cache. A `git fetch origin` in the Sandbox asks the Repo cache for a fetch. Then the Repo cache
@@ -204,6 +226,8 @@ credential to fetch.
 - A Harness accepts a call only from the Orchestrator, with the bearer of its own pod. Only its health check needs no
   bearer.
 - The Agent executes code only in the Harness container. It executes nothing in the Custodian or in the Effector.
+- In the Harness container, each program that the Harness starts runs confined. It cannot read what the Harness holds.
+- Each Sandbox node needs Landlock in its kernel. `jr2 up` refuses to converge while a Sandbox node has none.
 - The Orchestrator watches the Sandbox resources and never reads a pod. The operator puts the facts of the pod on the
   status of the Sandbox resource.
 - A Sandbox has one pod for its life. A lost pod is never made again.
@@ -226,5 +250,7 @@ credential to fetch.
   [ADR-0053](../reference/decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md),
   [ADR-0058](../reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md),
   [ADR-0059](../reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md),
-  [ADR-0063](../reference/decisions/0063-the-orchestrator-watches-the-cluster.md) and
-  [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
+  [ADR-0063](../reference/decisions/0063-the-orchestrator-watches-the-cluster.md),
+  [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md),
+  [ADR-0076](../reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md) and
+  [ADR-0077](../reference/decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md)

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,17 +30,21 @@ 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,
   and the size of the Chart in bytes.
 
 A Chart gets nothing else. A lent Effect keeps its url, its argv and its secrets, so a Chart fills only its input. A
-Chart has no url, no secret, no image and no Repo of its own. The Open body also decides where each Turn of the Chart
-runs: in the Sandbox of its `workspace()`, or on the [Instance Harness](../reference/glossary.md#instance-harness).
+lent [`worktree()`](../reference/authoring-surface/worktree.md) must state `expect`, because a Chart cannot state it. A
+Chart reads the cut with the kit guard `jr2.ready`, then gives the same literal path as `cwd` and `worktree`. A Chart
+has no url, no secret, no image and no Repo of its own. The Open body also decides where each Turn of the Chart runs: in
+the Sandbox of its `workspace()`, or on the [Instance Harness](../reference/glossary.md#instance-harness).
 
 ## What a Chart holds
 
@@ -48,7 +52,8 @@ A Chart is [xstate](https://xstate.js.org)'s own JSON config, with these limits:
 
 - States, transitions, `after` delays, and nested and parallel states. A Chart has 200 states at most, 8 levels deep.
 - Each `invoke.src` is a lent slot key or an Agent of the Chart. Each guard, action and delay is a lent name. Each Chart
-  also has the guard `jr2.failure`, which is true on an `onError` when the error is a Failure.
+  also has the guard `jr2.failure`, which is true on an `onError` when the error is a Failure, and the guard
+  `jr2.ready`, which is true on an `onDone` when the cut is `ready`.
 - A state that invokes an Agent can route [`agent.fault`](../reference/mechanism-events.md#agent-fault) in its `on`, but
   it does not have to. When no transition of the Chart takes `agent.fault`, the Open body sends it, unchanged, to the
   Chart wrapper. The wrapper's own `agent.fault` route takes it, as for an Agent of the wrapper, so one route on the
@@ -104,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,10 +79,15 @@ 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).
+    The Repo cache agent on each Sandbox node checks that the kernel of its node has Landlock, which jr2 needs. While a
+    Sandbox node has no Landlock, the converge fails. The error names each such node, the reason, and the fix: keep the
+    node out with `sandbox.nodeSelector` or a taint, or enable Landlock in its kernel. Then run `jr2 up` again.
 14. It publishes the Assembly to the Orchestrator. When the Orchestrator already has this Assembly, it publishes
     nothing.
 15. It removes the images that nothing uses now.