@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/guides/answer-a-gate-from-a-forge.md

@@ -0,0 +1,304 @@
+---
+title: Answer a Gate from a forge
+description: Make a Gate that a review on GitHub or GitLab answers, and that looks for the review it waits for.
+---
+
+# Answer a Gate from a forge
+
+Make a [Gate](../reference/glossary.md#gate) that a review on a forge, such as GitHub, answers through a
+[Hook](../reference/glossary.md#hook), and that looks for the review when no delivery comes.
+
+A Gate slot is a Gate that hears a Hook. You declare it with `gate({ … })` in `actors`, and a state invokes it by its
+key. It is the same Gate as `src: "gate"`: it has the same id, the same events, the same card in the
+[Console](../reference/glossary.md#console), and `jr2 send` can answer it too. It adds four parts:
+
+- `meta`: a zod object of the data that the state gives the Gate. The Gate checks the data when it opens.
+- `delivers`: the events that the Gate can give from a delivery or from its look.
+- `hooks`: a handler for each [Hook kind](../reference/glossary.md#hook-kind) and event key. A handler reads the payload
+  of a delivery, and gives one event of `delivers`, or `undefined` when the delivery is not for this Gate.
+- `look`: a read of the fact that the Gate waits for, with an `http` Effect that is marked `idempotent: true`.
+
+The example is the [Workflow](../reference/glossary.md#workflow) `review`. A run waits for a review of one commit of one
+pull request. The `github` kind is `@jr2/orchestrator/hooks/github`, so your
+[Instance](../reference/glossary.md#instance) installs nothing more.
+
+Save the file as `workflows/review.ts`:
+
+```ts
+// workflows/review.ts: a run that waits for a review of one pull request on GitHub. A review on
+// GitHub answers the Gate, through a Hook of the `github` kind. The look reads the reviews of the
+// pull request, so a review that came before the Gate opened, or while the Orchestrator was down,
+// also answers it.
+
+import { z } from "zod";
+import type {} from "@jr2/orchestrator/hooks/github";
+import { bearer, defineEvent, gate, http, jr2Setup, secret, type HttpOutput } from "@jr2/orchestrator";
+
+const approve = defineEvent({
+  name: "approve",
+  description: "A reviewer approved the commit.",
+  input: z.object({ by: z.string() }),
+});
+const changes = defineEvent({
+  name: "changes",
+  description: "A reviewer asked for changes.",
+  input: z.object({ by: z.string(), notes: z.string() }),
+});
+
+type Meta = { owner: string; repo: string; pr: number; url: string; sha: string };
+
+// The reviews of the pull request, from the GitHub API. The look reads them again, so the call is
+// marked idempotent.
+const reviews = http({
+  method: "GET",
+  url: "https://api.github.com",
+  auth: bearer(secret("github-token")),
+  headers: { accept: "application/vnd.github+json" },
+  idempotent: true,
+  input: z.object({ owner: z.string(), repo: z.string(), pr: z.number() }),
+  request: ({ owner, repo, pr }) => ({ path: ["repos", owner, repo, "pulls", String(pr), "reviews"] }),
+});
+
+/** The last verdict on the commit, from the API's answer. */
+function verdictOf(output: HttpOutput, meta: Meta) {
+  if (output.outcome !== "response" || output.status !== 200 || output.body === undefined) return undefined;
+  const list = JSON.parse(output.body) as Array<{
+    state: string;
+    commit_id: string;
+    body: string | null;
+    user: { login: string };
+  }>;
+  const last = list.filter((r) => r.commit_id === meta.sha && r.state !== "COMMENTED").at(-1);
+  if (last?.state === "APPROVED") return { type: "approve" as const, by: last.user.login };
+  if (last?.state === "CHANGES_REQUESTED")
+    return { type: "changes" as const, by: last.user.login, notes: last.body ?? "" };
+  return undefined;
+}
+
+const review = gate({
+  meta: z.object({ owner: z.string(), repo: z.string(), pr: z.number(), url: z.string(), sha: z.string() }),
+  delivers: [approve, changes],
+  hooks: {
+    github: {
+      "pull_request_review.submitted": ({ payload, meta }) => {
+        // A review of another pull request, or of an older commit, is not for this Gate.
+        if (payload.pull_request.html_url !== meta.url || payload.review.commit_id !== meta.sha) return undefined;
+        if (payload.review.state === "approved") return { type: "approve", by: payload.review.user.login };
+        if (payload.review.state === "changes_requested") {
+          return { type: "changes", by: payload.review.user.login, notes: payload.review.body ?? "" };
+        }
+        return undefined;
+      },
+    },
+  },
+  look: {
+    read: reviews,
+    input: (meta) => ({ owner: meta.owner, repo: meta.repo, pr: meta.pr }),
+    every: "10m",
+    until: verdictOf,
+  },
+});
+
+type Input = Meta;
+
+export const machine = jr2Setup({
+  types: {} as { context: Input & { notes?: string }; input: Input },
+  events: [approve, changes],
+  actors: { review },
+}).createMachine({
+  id: "review",
+  input: z.object({ owner: z.string(), repo: z.string(), pr: z.number(), url: z.string(), sha: z.string() }),
+  context: ({ input }) => input,
+  initial: "inReview",
+  states: {
+    inReview: {
+      invoke: {
+        src: "review",
+        input: ({ context }) => ({
+          meta: { owner: context.owner, repo: context.repo, pr: context.pr, url: context.url, sha: context.sha },
+        }),
+      },
+      on: { approve: "approved", changes: "changesAsked" },
+    },
+    approved: { type: "final" },
+    changesAsked: { type: "final" },
+  },
+});
+```
+
+The `import type {} from "@jr2/orchestrator/hooks/github"` line gives the handlers their types: the event key
+`pull_request_review.submitted` and its payload. A key that no kind in scope gives does not compile. A handler reads
+only the fields that the kind's schema names.
+
+## The handler
+
+A delivery of the kind and the event key goes to each open Gate whose handlers hear them. Thus each handler compares the
+payload with the Gate's `meta`. In the example, the handler gives `undefined` for a review of another pull request or of
+an older commit. A handler is pure and synchronous: it does no I/O and reads no clock.
+
+The event of a handler has the Gate as its [Sender](../reference/glossary.md#sender), with the Hook as its
+[Caller](../reference/glossary.md#caller). The run takes the event only when it takes it from this Gate now, as for
+`jr2 send`.
+
+## The look
+
+A delivery can come before the Gate opens, or it can be lost while the
+[Orchestrator](../reference/glossary.md#orchestrator) is down. The look reads the fact, so these cases come to the same
+read:
+
+- The look reads once after the Gate opens, again after each restart of the Orchestrator, and every `every` while the
+  Gate is open. The default `every` is `"10m"`.
+- `until` gives one event of `delivers` from the read's output, or `undefined` for "not yet".
+- When the run takes the event, the look stops until the Gate opens again. The run's feed shows `looked`. A looked event
+  has the Gate as its Sender and no Caller.
+- The `http` Effect of the look is an Effect, so the secret that it names is an entry of the `secrets` list, as
+  `github-token` is in the example's `jr2.config.ts`. Put its value in `.env` as `GITHUB_TOKEN`.
+
+A state that goes back to its own Gate must change the `meta`, for example to a new `sha`. If not, the look reads the
+same verdict again.
+
+Give `look: "none"` to a Gate that hears a command, such as a `/retry` comment. A command is not a fact that a read can
+find, so a lost delivery of a command stays lost.
+
+## The Hook
+
+The Gate hears a delivery only when the [Instance](../reference/glossary.md#instance) declares a Hook of its kind. Each
+Hook is a name in the `hooks` block of `jr2.config.ts`, and its address is `POST /hooks/<name>`. Set up the service with
+this address one time:
+
+```ts
+import { defineConfig, secret } from "@jr2/orchestrator";
+import { github } from "@jr2/orchestrator/hooks/github";
+import { gitlab } from "@jr2/orchestrator/hooks/gitlab";
+
+export default defineConfig({
+  // Each Hook's secret is an entry of the list. jr2 up places GH_HOOK in the Instance Effector, and
+  // gives the Orchestrator only the sha-256 of GL_HOOK.
+  secrets: [
+    { name: "GH_HOOK", value: process.env.GH_HOOK },
+    { name: "GL_HOOK", value: process.env.GL_HOOK },
+    // The look of review reads the reviews with this token. jr2 up places it in the Instance Effector.
+    { name: "github-token", value: process.env.GITHUB_TOKEN },
+  ],
+  hooks: {
+    // POST /hooks/forge: GitHub signs each delivery with the secret GH_HOOK. The Hook may answer
+    // the Gates of review alone.
+    forge: github({ secret: secret("GH_HOOK"), may: { answer: ["review"] } }),
+    // POST /hooks/lab: GitLab sends the secret GL_HOOK as a token in a header.
+    lab: gitlab({ secret: secret("GL_HOOK"), may: { answer: ["review"] } }),
+  },
+});
+```
+
+A Hook takes a credential and `may.answer`. `may.answer` is the list of Workflows whose Gates the Hook can answer. The
+default is every Workflow. A Hook never starts a run. The kind tells how the service signs:
+
+- `github` and `slack` sign with a shared secret (`mac`). The
+  [Instance Effector](../reference/glossary.md#instance-effector) holds the secret and checks the signature. The
+  Orchestrator does not hold the secret.
+- `gitlab` sends a shared token in a header (`token`). The Orchestrator keeps only the sha-256 of the token, and removes
+  the header before the kind reads the delivery.
+- `discord` signs with a key pair (`ed25519`). The config holds the public key, which cannot sign.
+
+Each secret that a Hook names is an entry of the `secrets` list. For a `mac` Hook, [`jr2 up`](../reference/cli.md#up)
+places the secret in the Instance Effector alone, as it places an
+[Effect secret](../reference/glossary.md#effect-secret), and it converges the Instance Effector for the Hook. For a
+`token` Hook, `jr2 up` writes the sha-256 of the secret into the Secret `jr2-hook-digests`, which the Orchestrator
+mounts. The Orchestrator reads it again when it changes, so a new value needs no restart. The kubelet updates the mount
+in about one minute, and `jr2 up` waits for it before it says `converged`. A kind that posts a follow-up, such as the
+reply to a Slack click, declares the hosts of the post. `jr2 up` adds these hosts to the Instance Effector's list of
+targets, with no secret. The output of `jr2 up` names the Hook as `hook forge`, in the line of the secret and in the
+line of the Instance Effector.
+
+When a delivery comes, the door does these steps in this sequence:
+
+1. The door refuses a body that is larger than 2 MiB. It reads no more of the body than this limit.
+2. The verifier checks the delivery. A signed time that is more than 300 seconds from the Orchestrator's clock fails the
+   check.
+3. The kind reads the delivery. A handshake (a GitHub `ping`, a Discord `PING`, a Slack `url_verification`) gets the
+   kind's answer and goes to no Gate.
+4. The kind's schema parses the payload.
+5. The door looks for a repeat: a delivery whose id or body this Hook got before.
+6. The delivery goes to each open Gate, in each live run of a Workflow that the Hook may answer, whose handlers hear its
+   kind and event key.
+
+The answer is the outcome:
+`{ delivery, seen, delivered: [{ run, workflow, gate, event }], refused: [{ run, gate, event?, reason }], ignored, sources }`.
+`ignored` counts the open Gates whose handler gave `undefined`. A Gate whose handler throws, or gives an event that the
+run does not take now, is in `refused`, and the run's feed shows `hook-refused`. The run continues.
+
+To see what the door did, print the Hook's log. It keeps each delivery for `runs.retain` (30 days by default), newest
+first:
+
+```sh
+jr2 hooks forge
+```
+
+## A Gate in a package
+
+A [packaged Machine](publish-a-machine-as-an-npm-package.md) writes its handlers, because a forge's payload is public.
+It leaves its look `open`, because the look needs a url and a token. The composer binds the look with `customize()`, and
+can add, replace or remove a handler by kind and event key, where `null` removes one:
+`customize(machine, { gates: { review: { look, hooks: { gitlab: { "note.MergeRequest": null } } } } })`.
+
+## Rules
+
+- The door refuses a delivery that fails the verifier, or whose signed time is more than 300 seconds from the
+  Orchestrator's clock, with 401. Nothing else occurs, and the Hook's log keeps no line.
+- The door refuses a body that is larger than 2 MiB with 413, before the verifier:
+  `the delivery's body is larger than 2097152 bytes, the most the door reads` The Hook's log keeps a `too-large` line,
+  which does not claim the delivery's id.
+- The door refuses a name that the config does not declare with 404:
+  `no Hook named "<name>" in the current Assembly's config`
+- With no current Assembly, the door answers 503:
+  `the Orchestrator has no current Assembly, so no Hook is declared now — ask again`
+- `jr2 up` refuses a `mac` Hook whose secret is not in the `secrets` list:
+  ``hooks.<name> names secret("<NAME>"), which the `secrets` list does not hold — add it: secrets: [{ name: "<NAME>", value: process.env.<NAME> }] (ADR-0068)``
+  It refuses a `token` Hook whose secret is not in the list with the same text, which ends with `(ADR-0078)`.
+- `jr2 up` names the secret of a `token` Hook: `secret <NAME>: a digest in the Orchestrator (hook <name>)`
+- A `mac` Hook whose check the Instance Effector cannot answer gets 503:
+  `the Hook's signature cannot be checked now: no Instance Effector (ADR-0068)`
+- A request that the kind cannot read gets 400: `the <kind> kind cannot read the delivery: <error>`
+- A payload that the kind's schema refuses gets 200, with `payloadRefused: { kind, key, issues }`. It goes to no Gate.
+  When the service sends it again, the door parses it again.
+- A delivery whose id or body the Hook got before gets 200 with `seen: true`, and goes to no Gate.
+- The config load refuses a Hook's name that is not lowercase letters, digits and `-`, at most 40 characters:
+  `<file> at hooks.<name>: a Hook's name is lowercase letters, digits and -, at most 40, starts with a letter and ends with a letter or digit (ADR-0078)`
+- The config load refuses a value that no kind made:
+  `<file> at hooks.<name>: not a Hook — make it with its kind, such as github({ secret: secret("GH_HOOK") }) (ADR-0078)`
+- `jr2 hooks <name>` needs the Instance token.
+
+- `gate()` refuses a part that it does not know:
+  `gate(): "<key>" is not a part of a Gate slot (meta, delivers, hooks, look, reply) (ADR-0011)`
+- `gate()` refuses an empty `delivers`: `gate(): its delivers lists at least one event that defineEvent made (ADR-0011)`
+- `gate()` refuses a look whose read is a different Effect:
+  ``gate(): its look reads with <an http Effect that is not marked idempotent: true | a <kind> Effect> — a look reads again after each restore and every `every`, so its read is an http Effect marked idempotent: true, or a promise (ADR-0067) (ADR-0011)``
+- `gate()` refuses an `every` that is not a duration:
+  `gate(): its look's every "<every>" is not a positive duration (like "90s", "10m", "2h") (ADR-0011)`
+- `createMachine` refuses an event of `delivers` that the Machine does not declare:
+  `machine "<id>": Gate slot "<slot>" delivers "<event>", which no def in jr2Setup({ events }) declares (declared: <events>) — list it in events (ADR-0011)`
+- `createMachine` refuses an event of `delivers` that the Gate does not take at the state that invokes it:
+  `machine "<id>": state "<state>" invokes Gate slot "<slot>", which delivers "<event>", and its Gate does not accept it (accepts: <events>) — no handler or look could deliver it: handle it on that state, a state above it or a plain child, or drop it from delivers (ADR-0011)`
+- The Gate does not open when its `meta` does not agree with the schema, and the invoke fails:
+  `gate "<gate>": its meta does not match the Gate slot's meta schema — <path>: <message>`
+- `customize()` refuses a slot that holds no Gate slot:
+  `customize(): machine "<id>" carries no Gate slot "<slot>" — its Gate slots are: <slots> (ADR-0011). Only declared parts can be bound.`
+- `customize()` refuses `open` as a look:
+  ``customize(): Gate slot "<slot>"'s look is bound once, to a look or "none" — not `open` again (ADR-0054)``
+- The Chart door refuses a Chart that invokes a lent Gate slot whose `delivers` holds an event that is not in the
+  Chart's `events`:
+  ``<path>: the Gate slot "<slot>" delivers "<event>", which is not in the Chart's `events` (events: <events>); declare it in `events` and handle it on this state``
+- `jr2 up` and `jr2 check` warn, and do not refuse, about a Gate slot that hears a Hook and has no look and no `after`
+  on its state:
+  ``warning: workflow "<workflow>": Gate slot "<slot>" on "<state>" hears a Hook and has no look and no `after` on its state — a delivery lost in an outage stops the run until a person answers the Gate: give it a look, or look: "none" for a Gate that hears a command (ADR-0011)``
+- `jr2 up` and `jr2 check` warn about a look that a package left `open` and that nobody bound:
+  `warning: workflow "<workflow>": Gate slot "<slot>" on "<state>" leaves its look open — a delivery lost in an outage stops the run until a person answers the Gate: bind it with customize(machine, { gates: { <slot>: { look } } }), or give it look: "none" (ADR-0011, ADR-0054)`
+
+## Read next
+
+- [Gates](../concepts/gates.md) and [Callers and Hooks](../concepts/callers-and-hooks.md)
+- [Write a Hook kind](write-a-hook-kind.md), for a service that jr2 ships no kind for
+- [Answer a Gate](answer-a-gate.md) and [Bind Open parts](bind-open-parts.md)
+- [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): a Gate hears a Hook, and looks before it waits
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): a
+  Hook is a Caller that can only answer a Gate or bring items to a Source

package/docs/guides/answer-a-gate.md

@@ -84,7 +84,7 @@ jr2 run release --input '{"version":"1.4.0"}'
 
 ```text
 → context <context> / namespace <namespace>
-run 2319932e-02c1-4f9d-98db-3c5a410395da (release) — attached
+run 0c948d65-fd6f-453a-87fa-71ec00c7fe68 (release) — attached
   → active "review"
 ```
 
@@ -96,12 +96,13 @@ next steps in a second terminal. [Start a run](start-a-run.md) gives the other w
 Run [`jr2 status`](../reference/cli.md#status) with the run id:
 
 ```sh
-jr2 status 2319
+jr2 status 0c94
 ```
 
 ```text
 → context <context> / namespace <namespace>
-{"runId":"2319932e-02c1-4f9d-98db-3c5a410395da","workflow":"release","instanceId":"c898d8c7-e48b-4a56-8101-7148905b6aed","status":"active","value":"review","context":{"version":"1.4.0"},"children":[],"waiting":[],"held":[],"assembly":"83858e28b054","gates":[{"gate":"review","path":["review"],"accepts":[{"name":"approve","description":"Release this version.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"reject","description":"Do not release this version. Say why.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"],"additionalProperties":false}}],"acceptsNow":["approve","reject"],"meta":{"version":"1.4.0"}}]}
+{"runId":"0c948d65-fd6f-453a-87fa-71ec00c7fe68","workflow":"release","instanceId":"6db54032-0b87-4005-9583-049f7335b75f","startedAt":"2026-11-06T19:15:39.018Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"active","value":"review","context":{"version":"1.4.0"},"children":[],"waiting":[],"held":[],"assembly":"19d0bf0cbe10","gates":[{"gate":"review","path":["review"],"accepts":[{"name":"approve","description":"Release this version.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"reject","description":"Do not release this version. Say why.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"],"additionalProperties":false}}],"acceptsNow":["approve","reject"],"meta":{"version":"1.4.0"}}]}
+started by: token/instance on behalf of kubernetes-admin
 ```
 
 `gates` holds each open Gate of the run, as a [`GateView`](../reference/http-api.md#type-gateview):
@@ -114,18 +115,37 @@ jr2 status 2319
 
 A run that has no open Gate has `"gates":[]`.
 
+To find the open Gates of all the live runs, run [`jr2 gates`](../reference/cli.md#gates). It prints the Gates that you
+can answer, the oldest first. Give `--workflow <name>` to see only the Gates of the runs of one Workflow:
+
+```sh
+jr2 gates --workflow release
+```
+
+```text
+→ context <context> / namespace <namespace>
+[{"runId":"0c948d65-fd6f-453a-87fa-71ec00c7fe68","workflow":"release","gate":"review","path":["review"],"accepts":[{"name":"approve","description":"Release this version.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}},{"name":"reject","description":"Do not release this version. Say why.","input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"],"additionalProperties":false}}],"acceptsNow":["approve","reject"],"meta":{"version":"1.4.0"},"openedAt":"2026-11-06T19:15:39.019Z"}]
+```
+
+Each entry has the fields of a Gate in `gates`, and also `runId`, `workflow` and `openedAt`, the time when the Gate
+opened. When the Gate hears a [Hook](../reference/glossary.md#hook), `hook` gives the
+[Hook kinds](../reference/glossary.md#hook-kind). An entry never holds the `context` of the run. A Gate that takes no
+event from a [Caller](../reference/glossary.md#caller), such as the `source` Gate of a
+[Pool](../reference/glossary.md#pool) that hears only Hooks, is not in the list. `jr2 gates` reads
+[`GET /gates`](../reference/http-api.md#get-gates), and it needs the `answer` scope.
+
 ## Answer from the CLI
 
 Run [`jr2 send`](../reference/cli.md#send). Give the Gate in `--gate`, the event in `--event`, and the input of the
 event as a JSON object in `--input`:
 
 ```sh
-jr2 send 2319 --gate review --event reject --input '{"reason":"The changelog is not ready."}'
+jr2 send 0c94 --gate review --event reject --input '{"reason":"The changelog is not ready."}'
 ```
 
 ```text
 → context <context> / namespace <namespace>
-delivered reject to gate "review" on 2319932e-02c1-4f9d-98db-3c5a410395da
+delivered reject to gate "review" on 0c948d65-fd6f-453a-87fa-71ec00c7fe68
 ```
 
 `jr2 send` prints `delivered` only when the run took the event. In the first terminal, the run ends. A `reject` ends the
@@ -136,7 +156,7 @@ ends `failed`. Its output is the [Failure](../reference/glossary.md#failure), an
   → active "rejected"
   → failed "rejected"
 failed: The changelog is not ready.
-{"runId":"2319932e-02c1-4f9d-98db-3c5a410395da","workflow":"release","instanceId":"c898d8c7-e48b-4a56-8101-7148905b6aed","status":"failed","value":"rejected","context":{"version":"1.4.0","reason":"The changelog is not ready."},"children":[],"waiting":[],"held":[],"assembly":"83858e28b054","output":{"reason":"The changelog is not ready."}}
+{"runId":"0c948d65-fd6f-453a-87fa-71ec00c7fe68","workflow":"release","instanceId":"6db54032-0b87-4005-9583-049f7335b75f","startedAt":"2026-11-06T19:15:39.018Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"failed","value":"rejected","context":{"version":"1.4.0","reason":"The changelog is not ready."},"children":[],"waiting":[],"held":[],"answers":[{"gate":"review","type":"reject","at":"2026-11-06T19:15:52.901Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}],"assembly":"19d0bf0cbe10","output":{"reason":"The changelog is not ready."}}
 ```
 
 The run ended, so its Gate closed. Each example below answers a run that waits. Before each example, start a new run in
@@ -154,24 +174,25 @@ jr2 send <run id> --gate review --event approve
 
 ```text
 → context <context> / namespace <namespace>
-delivered approve to gate "review" on c099e2dc-6dd2-45da-9358-0723c8b83c68
+delivered approve to gate "review" on 342fef91-53a1-4640-87bf-6fb4395beebf
 ```
 
 `jr2 send` prints the full run id, also when you give a prefix.
 
 ## Answer from the Console
 
-You need the Instance token to answer a Gate from the Console. [Open the Console](open-the-console.md) tells how to open
-it and how to get the token.
+You need a credential with the `answer` scope for the Workflow, such as the Instance token, to answer a Gate from the
+Console. [Open the Console](open-the-console.md) tells how to open it, how to get the token and how to log in.
 
 1. Open the Console.
-2. Type the Instance token in the `instance token` box in the nav.
+2. Type the token in the `Caller token` box in the nav, or click `log in`.
 3. Push Enter. The badge beside the box shows `…`, then `live`.
 4. Click the `Attention` tab in the drawer on the right. It shows a card for each open Gate of the Workflow that you
-   selected. To see the Gates of all the Workflows, select `all workflows`. When you select no Workflow, it shows them
-   all.
-5. Find the card. Its top line shows `⚑` and the id of the Gate at the left. At the right, it shows the Workflow and the
-   first 8 characters of the run id. Below it, the card shows the `meta` of the Gate.
+   selected and that your credential can answer, the oldest first. To see the Gates of all the Workflows, select
+   `all workflows`. When you select no Workflow, it shows them all. The Console reads the cards from
+   [`GET /gates`](../reference/http-api.md#get-gates).
+5. Find the card. Its top line shows `⚑` and the id of the Gate at the left. At the right, it shows the Workflow, the
+   first 8 characters of the run id and `open since <time>`. Below it, the card shows the `meta` of the Gate.
 6. The card has a form for each event that the Gate accepts. Fill in the form of the event that you send. A field that
    has `*` after its name is necessary.
 7. Click `send` in that form.
@@ -184,9 +205,13 @@ The `⚑` badge in the nav gives the number of open Gates in all the Workflows.
 ## Answer from a webhook or CI
 
 A webhook handler or a CI job answers a Gate with
-[`POST /runs/:runId/gates/:gate/events`](../reference/http-api.md#post-runs-runid-gates-gate-events) and the Instance
-token. jr2 has no webhook receiver of its own. Your handler or job reads its own event, finds the run and the Gate, and
-sends the call. The body is the event: `type` is the name of the event, and the other properties are its input.
+[`POST /runs/:runId/gates/:gate/events`](../reference/http-api.md#post-runs-runid-gates-gate-events) and the token of a
+named Caller with the `answer` scope for the Workflow. A CI job has no access to the cluster, so it cannot read the
+Instance token, and it must not have it: the Instance token can do everything.
+[Give a Caller a scope](give-a-caller-a-scope.md) makes the Caller token. A service that a Hook kind covers, such as a
+forge, sends its webhook to a Hook: see [Answer a Gate from a forge](answer-a-gate-from-a-forge.md). Any other handler
+or CI job uses the Gate route. It reads its own event, finds the run and the Gate, and sends the call. The body is the
+event: `type` is the name of the event, and the other properties are its input.
 
 `jr2 up` makes the Service `jr2-orchestrator` on port 4000, with no address outside the cluster. Thus a caller outside
 the cluster uses a port forward, or an address that you make for the Service.
@@ -197,7 +222,8 @@ In a new terminal, forward a port to the Orchestrator. Keep this command open:
 kubectl -n <namespace> port-forward svc/jr2-orchestrator 4000:4000
 ```
 
-In a different terminal, get the Instance token into a variable:
+In a different terminal, put a token into a variable. A CI job uses its Caller token. To try the route from your own
+terminal, you can use the Instance token:
 
 ```sh
 TOKEN=$(kubectl -n <namespace> get secret jr2-instance -o jsonpath='{.data.JR2_INSTANCE_TOKEN}' | base64 -d)
@@ -217,9 +243,9 @@ curl -s -X POST http://localhost:4000/runs/<run id>/gates/review/events \
 ```
 
 A webhook handler often knows a fact, such as a version, but not the run id. It can find the run from the `meta` of the
-Gate. [`GET /runs`](../reference/http-api.md#get-runs) gives the live runs, and
-[`GET /runs/:runId`](../reference/http-api.md#get-runs-runid) gives the open Gates of one run. This script approves the
-`release` run that waits for one version. It needs `curl` and `jq`. Save it as `approve-release.sh`:
+Gate. [`GET /gates`](../reference/http-api.md#get-gates) gives the open Gates of all the live runs that the token can
+answer, each with its run id and its `meta`. It needs only the `answer` scope. This script approves the `release` run
+that waits for one version. It needs `curl` and `jq`. Save it as `approve-release.sh`:
 
 ```sh
 #!/bin/sh
@@ -229,15 +255,13 @@ set -eu
 
 auth="Authorization: Bearer $JR2_TOKEN"
 
-# The live runs of the release Workflow.
-for run in $(curl -fsS -H "$auth" "$JR2_URL/runs" | jq -r '.[] | select(.workflow == "release") | .runId'); do
-  # The open Gates of the run, with their meta.
-  version=$(curl -fsS -H "$auth" "$JR2_URL/runs/$run" | jq -r '.gates[] | select(.gate == "review") | .meta.version')
-  if [ "$version" = "$VERSION" ]; then
-    curl -fsS -X POST -H "$auth" -H "Content-Type: application/json" \
-      -d '{"type":"approve"}' "$JR2_URL/runs/$run/gates/review/events"
-    echo
-  fi
+# The open Gates of the live release runs that this token can answer, with their meta.
+runs=$(curl -fsS -H "$auth" "$JR2_URL/gates?workflow=release" |
+  jq -r --arg v "$VERSION" '.gates[] | select(.gate == "review" and .meta.version == $v) | .runId')
+for run in $runs; do
+  curl -fsS -X POST -H "$auth" -H "Content-Type: application/json" \
+    -d '{"type":"approve"}' "$JR2_URL/runs/$run/gates/review/events"
+  echo
 done
 ```
 
@@ -258,15 +282,15 @@ JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN jr2 send <run id> --gate review -
 
 ```text
 → http://localhost:4000
-delivered approve to gate "review" on c44c6e49-452d-4150-8ce4-4d036363d2a0
+delivered approve to gate "review" on cad78069-0d8d-4c04-9cf4-3f771693274f
 ```
 
 ## Rules
 
 - The Orchestrator refuses a Gate that is not open on the run, with the status code `404`:
   `no open gate "<gate>" on run "<run id>" (open: <gates>)`. The part `(open: <gates>)` shows only when the run has an
-  open Gate. When an event takes the run out of the state of the Gate, the Gate closes. Thus a second answer gets this
-  refusal.
+  open Gate that the Caller can answer. When an event takes the run out of the state of the Gate, the Gate closes. Thus
+  a second answer gets this refusal.
 - The Orchestrator refuses an event that the Gate does not accept, with the status code `400`:
   `"<gate>" does not accept "<event>" (accepts: <events>)`
 - The Orchestrator refuses an input that does not agree with the schema of the event, with the status code `400`:
@@ -278,10 +302,23 @@ delivered approve to gate "review" on c44c6e49-452d-4150-8ce4-4d036363d2a0
   `event body must carry a string "type" (one of the gate's accepted names)`
 - The Orchestrator refuses a body that holds `sender`, with the status code `400`:
   `` `sender` is written by the Orchestrator on every delivered event; a caller cannot send it ``
-- The Orchestrator refuses an event without the Instance token, with the status code `401`: `unauthorized`.
+- The Orchestrator refuses an event with no valid credential, with the status code `401`: `unauthorized`. A credential
+  is the Instance token, or that of a [Caller](../reference/glossary.md#caller) with the `answer` scope.
+  [Give a Caller a scope](give-a-caller-a-scope.md) makes one.
 - The Orchestrator refuses an event with the token of a [Sandbox](../reference/glossary.md#sandbox), with the status
-  code `403`: `a Sandbox token cannot deliver to a gate — gates are not on the Agent's surface`. Thus an Agent cannot
-  answer a Gate.
+  code `403`:
+  `this route needs a Caller, and a Sandbox token is not one: no Agent reaches run state, run control or a Gate`. Thus
+  an Agent cannot answer a Gate.
+- The Orchestrator refuses an event from a Caller that has the `answer` scope for no Workflow, with the status code
+  `403`, before it reads the run: `the Caller <via>/<name> has no "answer" scope for any Workflow (ADR-0078)`. The body
+  also holds `scope`.
+- The Orchestrator refuses an event from a Caller that does not have the `answer` scope for the Workflow of the run,
+  with the status code `403`: `the Caller <via>/<name> needs the "answer" scope for Workflow "<workflow>" (ADR-0078)`
+- The Orchestrator refuses an event to an open Gate from a Caller whose `answer` scope names other Gates of the
+  Workflow, with the status code `403`:
+  `the Caller <via>/<name> needs the "answer" scope for Gate "<name>" of Workflow "<workflow>" (ADR-0078)`. `<name>` is
+  the name of the Gate, its invoke id. The body also holds `scope`, `workflow` and `gate`.
+  [Give a Caller a scope](give-a-caller-a-scope.md) tells how a scope names single Gates.
 - `jr2 send` prints each refusal of the Orchestrator as `error: <refusal>`, and exits with `1`. After a `404` refusal,
   it also prints the version of the Instance in one more line:
   ``instance: <version> (<hash>) — if it predates this CLI, `jr2 up` converges the cluster to this kit``. `<hash>` is
@@ -298,7 +335,7 @@ delivered approve to gate "review" on c44c6e49-452d-4150-8ce4-4d036363d2a0
 - [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): a Gate, its events, and its `meta`.
 - [ADR-0013](../reference/decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md): why an
   Agent cannot answer a Gate, and why a refused event is not delivered.
-- [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-the-instance-token.md): the Instance token in the
+- [ADR-0032](../reference/decisions/0032-the-console-unlocks-with-a-callers-credential.md): a Caller's credential in the
   Console.
 - [Start a run](start-a-run.md)
 - [Watch a run](watch-a-run.md)

package/docs/guides/bind-open-parts.md

@@ -121,9 +121,10 @@ jr2 run fix-app --input '{"prompt":"Make the failing test in test/greet.test.ts
 The key of each Repo Slot is the name of the slot, and the directory `/work/<slot>` in the
 [Sandbox](../reference/glossary.md#sandbox). The value is one of these:
 
-- a url: `"https://github.com/<you>/handbook.git"`. The [Worktree](../reference/glossary.md#worktree) starts from the
-  default branch of the Repo.
-- a [Binding](../reference/glossary.md#binding): `{ url, ref }`. The Worktree starts from `ref`, a branch or a commit.
+- a url: `"https://github.com/<you>/handbook.git"`. The clone stays on the default branch of the Repo, and a new
+  [Worktree](../reference/glossary.md#worktree) branch starts from it.
+- a [Binding](../reference/glossary.md#binding): `{ url, ref }`. The clone stays on `ref`, a branch, a tag or a commit,
+  and a new branch starts from it.
 - a function of the run input: `({ input }) => url`, or `({ input }) => ({ url, ref })`. Each run chooses its Repo. The
   url must agree with an entry of [`git.credentials`](../reference/config.md#git-credentials) in `jr2.config.ts`.
 - `open`, to leave the slot Open for the Instance that registers your Machine.
@@ -136,7 +137,9 @@ others. A Machine that names its slots, such as `repos: { app: open }`, takes on
 
 `agents` takes the fields of the definition of an Agent, by slot. Each field goes over the field that the author wrote.
 Thus `{ model }` changes only the model, and the coder keeps the instructions of `task`. You can also change other
-fields, such as `thinkingLevel` or `instructions`.
+fields, such as `thinkingLevel` or `instructions`. `{ mcp }` replaces the whole list of the MCP servers of the Agent.
+`jr2 up` refuses a server name that the `mcp` block of `jr2.config.ts` does not declare, and prints the line with `mcp`
+(see [Give an Agent MCP tools](give-an-agent-mcp-tools.md#bind-the-servers-of-a-packaged-machine)).
 [`AgentDefinition`](../reference/authoring-surface/type-agentdefinition.md) gives the fields.
 
 ## Bind the parts of a Machine that you compose
@@ -163,19 +166,29 @@ When `task` is a child of your Machine, give it `branch` in its input. Only the
 
 ## Bind the Open parts of an Effect
 
-A packaged Machine can leave the url of an `http` [Effect](../reference/glossary.md#effect), the argv of a `command`, or
-the name of a secret Open. Bind them with `effects`, by the slot of the Effect:
-`customize(machine, { effects: { notify: { url } } })`. One object binds all the Open parts of one Effect. You bind each
-part one time, to a value. No run chooses it. [`EffectBinding`](../reference/authoring-surface/type-effectbinding.md)
-gives the values, and [Run a command or call a URL with an Effect](run-a-command-or-call-a-url.md) shows an Effect.
+A packaged Machine can leave the url of an `http` [Effect](../reference/glossary.md#effect), the argv of a `command`,
+the name of a secret, or the server and the tool of an `mcp` Effect Open. Bind them with `effects`, by the slot of the
+Effect: `customize(machine, { effects: { notify: { url } } })`, or
+`customize(machine, { effects: { post: { server: "slack-acme", tool: "post_message" } } })`. One object binds all the
+Open parts of one Effect. You bind each part one time, to a value. No run chooses it.
+[`EffectBinding`](../reference/authoring-surface/type-effectbinding.md) gives the values, and
+[Run a command or call a URL with an Effect](run-a-command-or-call-a-url.md) shows an Effect. A bound server is a name
+of the `mcp` block. Its secret comes from that block, so an `mcp` Effect has no Open secret.
+
+## Bind the look of a Gate
+
+A packaged Machine can leave the look of a Gate slot Open: `look: open`. Bind it with `gates`, by the slot of the Gate:
+`customize(machine, { gates: { review: { look } } })`. The same key adds, replaces or removes a handler of the Gate, by
+Hook kind and event key, where `null` removes one. `jr2 up` does not refuse an Open look. It warns, because a person can
+still answer the Gate with `jr2 send`. [Answer a Gate from a forge](answer-a-gate-from-a-forge.md) shows a Gate slot.
 
 ## Rules
 
 - `jr2 up` refuses a registered Machine that leaves a part Open. It changes nothing in the cluster:
   `refusing: workflow "<name>" leaves <part> open — bind it where the Machine is registered: export const machine = customize(<import>, <binding>)  (<adr>)`.
   `<part>` is one of `its Repo Slots`, `Repo Slot "<slot>"`, `Agent "<slot>"`, or `the <parts> of Effect "<slot>"`,
-  where `<parts>` is such as `url` or `url and secret`. For a child Machine, `(on the Machine composed as "<slot>")`
-  comes after `open`.
+  where `<parts>` is such as `url`, `url and secret`, `server` or `server and tool`. For a child Machine,
+  `(on the Machine composed as "<slot>")` comes after `open`.
 - `jr2 up` refuses an Open part on a Machine that a state writes in its `invoke.src`, because no `customize()` gets to
   it. Put that Machine under `actors`:
   `refusing: workflow "<name>" leaves <part> open on a Machine invoked inline — no customize() reaches an actor without a slot key; declare that Machine under setup({ actors }) and bind it there  (ADR-0049, <adr>)`
@@ -188,10 +201,11 @@ gives the values, and [Run a command or call a URL with an Effect](run-a-command
   - `customize(): machine "<id>" composes no Machine under "<slot>" — the Machines it composes are: <slots> (ADR-0049).`
   - `customize(): machine "<id>" declares no Repo Slot "<slot>" — its slots are: <slots> (ADR-0051)`
   - `customize(): machine "<id>" carries no Effect slot "<slot>" — its Effects are: <slots> (ADR-0067). Only declared parts can be bound.`
+  - `customize(): machine "<id>" carries no Gate slot "<slot>" — its Gate slots are: <slots> (ADR-0011). Only declared parts can be bound.`
 - `customize()` refuses an Open map that you bind with no slot:
   ``customize(): machine "<id>" declares its Repo Slots open as a map — name at least one: `repos: { app: "https://…" }` (ADR-0051).``
 - `customize()` refuses a Repo Slot key that is not a directory name. The key becomes `/work/<slot>`:
-  ``customize(): Repo Slot key "<slot>" is not a directory name — a slot becomes `/work/<slot>` and its order matters, so it starts with a letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051).``
+  ``customize(): Repo Slot key "<slot>" is not a directory name — a slot becomes `/work/<slot>`, `/work/.jr2/` is reserved for jr2, and its order matters, so it starts with a letter and matches /^[A-Za-z][A-Za-z0-9._-]*$/ (ADR-0051, ADR-0075).``
 - `customize()` refuses an empty url:
   ``customize(): Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot is `open`, a url, `{ url, ref? }`, or a mapper `({ input }) => url | { url, ref? }` over the door (ADR-0051).``
   For an empty `ref`, the text says `bound with an empty ref`.
@@ -200,6 +214,9 @@ gives the values, and [Run a command or call a URL with an Effect](run-a-command
 - `customize()` refuses `open` or a function as the value of an Effect's part:
   ``customize(): the <kind> Effect "<slot>"'s <part> is bound once, to a value — not `open` again: no run chooses an Effect's <part> (ADR-0054)``.
   For a function, the text says `a function of the run` in place of `` `open` again ``.
+- `jr2 up` refuses an Agent that names an MCP server that the `mcp` block does not declare:
+  `refusing: workflow "<name>": Agent "<slot>" names the MCP server "<server>", which the mcp block declares "<names>" — bind the Agent to a declared server where the Machine is registered: export const machine = customize(<import>, { agents: { <slot>: { mcp: [<entries>] } } }); or declare it in jr2.config.ts: mcp: { "<server>": { url: "https://<host>/mcp", secret: "<SECRET>" } } (ADR-0079)`.
+  For a child Machine, the line names the child, and `customize()` goes through `actors`.
 - An Agent does not start a [Turn](../reference/glossary.md#turn) while its model is Open:
   ``agent "<slot>" has an Open model — nobody bound it; bind it where the Machine is registered (`customize(<machine>, { agents: { <slot>: { model: "<provider>/<model>" } } })`), because a packaged Machine cannot pick a model on your behalf (ADR-0054)``.
   `jr2 up` refuses this case first.