@jr2/orchestrator 0.6.0 → 0.7.0

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

@@ -137,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
@@ -164,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>)`
@@ -189,6 +201,7 @@ 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>`:
@@ -201,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.