@jr2/orchestrator 0.6.0 → 0.7.0

package/console/style.css

@@ -91,9 +91,25 @@ button:hover {
   color: var(--phosphor);
 }
 
+/* The page under the nav: the work row above, the bottom drawer across the full width below. */
 main {
   flex: 1;
   display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+/* The work row: the rail, then the Machine and the right drawer. */
+#work {
+  flex: 1;
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+}
+#upper {
+  flex: 1;
+  display: flex;
+  min-width: 0;
   min-height: 0;
 }
 
@@ -270,6 +286,199 @@ main {
   font-family: var(--mono);
 }
 
+/* A run on an older Assembly (ADR-0069): the graph is the run's own Machine. */
+.notice-line {
+  color: var(--amber);
+  font-family: var(--mono);
+}
+.older-assembly {
+  font-size: 11px;
+  margin-right: 6px;
+}
+.run-reason {
+  flex-basis: 100%;
+  font-size: 11px;
+  white-space: normal;
+}
+.runs-head {
+  font-size: 10px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  cursor: default;
+}
+
+/* ---- The bottom drawer: the selected run's conversations (ADR-0023, ADR-0032) ---- */
+
+#bottom-drawer {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  min-height: 0;
+  background: var(--ink-2);
+  border-top: 1px solid var(--line);
+}
+/* A window made shorter after the height was set: the Machine keeps at least 160px. */
+#bottom-drawer.bottom--open {
+  max-height: max(120px, calc(100vh - 160px));
+}
+.bottom-resize {
+  touch-action: none; /* a drag on a touch screen moves the edge, not the page */
+  position: absolute;
+  top: -3px;
+  left: 0;
+  right: 0;
+  height: 6px;
+  cursor: ns-resize;
+  z-index: 1;
+}
+.bottom-tabs {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 6px 12px;
+  overflow-x: auto;
+  flex-shrink: 0;
+}
+.bottom-title {
+  font-size: 11px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--text-dim);
+  margin: 0 8px 0 4px;
+}
+.slot-tab {
+  font-size: 12px;
+  color: var(--text-dim);
+  border-color: transparent;
+  white-space: nowrap;
+}
+.slot-tab.tab--active {
+  color: var(--text);
+  border-color: var(--line);
+}
+.live-dot {
+  display: inline-block;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--phosphor);
+  margin-right: 6px;
+  vertical-align: middle;
+}
+.bottom-body {
+  flex: 1;
+  display: flex;
+  min-height: 0;
+  border-top: 1px solid var(--line-soft);
+}
+.conversation-pane {
+  flex: 1;
+  min-width: 0;
+  /* In a column (a narrow screen), the pane's own minimum would be the whole conversation: it
+     would spill out of the drawer, and push the Steering box off the screen. */
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+#conversation {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px 16px 16px;
+}
+.conversation-block + .conversation-block {
+  margin-top: 16px;
+  border-top: 1px dashed var(--line);
+  padding-top: 8px;
+}
+.conversation-head {
+  font-size: 11px;
+  margin-bottom: 6px;
+}
+.conv-text,
+.conv-body {
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.conv-text {
+  margin: 6px 0;
+}
+#conversation details {
+  margin: 4px 0;
+}
+#conversation summary {
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.conv-body {
+  margin: 4px 0 4px 16px;
+  padding: 6px 10px;
+  border-left: 2px solid var(--line);
+}
+.conv-label {
+  font-size: 10px;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--text-dim);
+}
+.conv-thinking {
+  color: var(--text-dim);
+}
+.conv-steering .conv-label,
+.conv-steering .conv-body {
+  color: var(--blue);
+}
+.conv-notice .conv-label,
+.conv-notice .conv-body {
+  color: var(--amber);
+}
+.conv-call .conv-label {
+  color: var(--phosphor);
+}
+.conv-answer {
+  border-left-color: var(--phosphor);
+}
+.conv-refused .conv-label,
+.conv-refused .conv-answer {
+  color: var(--red);
+  border-left-color: var(--red);
+}
+.conv-mark {
+  margin: 6px 0;
+  font-size: 11px;
+  color: var(--text-dim);
+}
+.conv-cut,
+.conv-swept {
+  color: var(--orange);
+}
+.steering-box {
+  width: 300px;
+  flex-shrink: 0;
+  padding: 8px 12px;
+  border-left: 1px solid var(--line-soft);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.steering-box textarea {
+  flex: 1;
+  min-height: 60px;
+}
+/* A narrow screen: the Steering box goes under the conversation, not beside it. */
+@media (max-width: 720px) {
+  .bottom-body {
+    flex-direction: column;
+  }
+  .steering-box {
+    width: auto;
+    border-left: 0;
+    border-top: 1px solid var(--line-soft);
+  }
+}
+
 /* ---- Machine (SVG) ---- */
 
 /* Every box is click-to-select (outline only — the click is reserved beyond that). */
@@ -490,6 +699,27 @@ marker.arrow--error path {
   outline: none;
   border-color: var(--phosphor);
 }
+#caller {
+  font-family: var(--mono);
+  color: var(--text);
+  max-width: 260px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+#login-note {
+  color: var(--red);
+  max-width: 260px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+#caller[hidden],
+#sign-out[hidden],
+#token[hidden],
+#login-note[hidden] {
+  display: none;
+}
 .token-state {
   font-size: 11px;
   letter-spacing: 0.04em;
@@ -611,6 +841,7 @@ ul {
   display: flex;
   gap: 8px;
   align-items: baseline;
+  flex-wrap: wrap;
 }
 .wf-runs li:hover {
   border-color: var(--line);

package/docs/agents-block.md

@@ -1,5 +1,5 @@
-jr2 is newer than your training data. Before you write a Machine or change jr2.config.ts, read the bundled docs in node_modules/@jr2/orchestrator/docs/. They are the docs of this Instance's Kit version, 0.6.0. Start with guides/write-a-workflow.md and with reference/authoring-surface.md, the contents page of the Authoring surface. Read one page with each call of your file tool, because a file tool cuts off a long output. Before you give a change to the user, run `npx --no jr2 check` in the Instance folder. It does the typecheck and the load of each Workflow that `jr2 up` does first, with no cluster, and it gives the same refusals.
+jr2 is newer than your training data. Before you write a Machine or change jr2.config.ts, read the bundled docs in node_modules/@jr2/orchestrator/docs/. They are the docs of this Instance's Kit version, 0.7.0. Start with guides/write-a-workflow.md and with reference/authoring-surface.md, the contents page of the Authoring surface. Read one page with each call of your file tool, because a file tool cuts off a long output. Before you give a change to the user, run `npx --no jr2 check` in the Instance folder. It does the typecheck and the load of each Workflow that `jr2 up` does first, with no cluster, and it gives the same refusals.
 
 A final state means that the work succeeded: the run ends `done`. When the work did not succeed, invoke `fail()` from a state (reference/authoring-surface/fail.md), and the run ends `failed`. Do not throw to fail: a throw is a defect, and the run ends `error`.
 
-[jr2 docs index]|root: ./node_modules/@jr2/orchestrator/docs|reference:{authoring-surface.md,machines.md,config.md,cli.md,http-api.md,mechanism-events.md,glossary.md,decisions.md}|reference/authoring-surface:{one file per export and type; reference/authoring-surface.md lists them}|guides:{iterate-on-a-machine-on-kind.md,write-a-workflow.md,bind-open-parts.md,set-an-agents-access-and-dials.md,cut-a-worktree.md,run-a-command-or-call-a-url.md,push-and-sign-a-branch.md,start-a-run-from-a-run.md,add-tools-to-the-sandbox.md,size-a-workspace.md,run-one-worker-per-item.md,publish-a-machine-as-an-npm-package.md,let-an-agent-write-a-chart.md,run-a-chart-by-name.md,start-a-run.md,answer-a-gate.md,watch-a-run.md,look-inside-a-sandbox.md,cancel-a-run.md,open-the-console.md,use-a-local-model.md,use-a-hosted-provider.md,give-the-cluster-git-credentials.md,move-from-kind-to-a-shared-cluster.md,mirror-the-kit-images.md,upgrade-the-kit-version.md,clean-up.md,fix-a-failed-converge.md}|concepts:{machines-and-workflows.md,agents-and-turns.md,the-menu.md,gates.md,effects.md,workspaces.md,composition.md,charts.md,pools-and-sources.md,architecture.md,secrets-and-trust.md,converge.md,durable-runs.md}|.:{index.md,why.md}|get-started:{install.md,create-an-instance.md,connect-a-model.md,a-model-decides.md,an-agent-in-a-sandbox.md,have-your-assistant-write-a-machine.md}|reference/decisions:{one file per ADR; reference/decisions.md lists them}
+[jr2 docs index]|root: ./node_modules/@jr2/orchestrator/docs|reference:{authoring-surface.md,machines.md,hooks.md,config.md,cli.md,http-api.md,mechanism-events.md,glossary.md,decisions.md}|reference/authoring-surface:{one file per group, export and type; reference/authoring-surface.md lists them}|guides:{iterate-on-a-machine-on-kind.md,write-a-workflow.md,bind-open-parts.md,set-an-agents-access-and-dials.md,give-an-agent-mcp-tools.md,cut-a-worktree.md,run-a-command-or-call-a-url.md,call-an-mcp-tool-from-a-machine.md,push-and-sign-a-branch.md,start-a-run-from-a-run.md,add-tools-to-the-sandbox.md,write-a-tool-as-an-mcp-server.md,size-a-workspace.md,run-one-worker-per-item.md,start-a-run-for-each-alert.md,write-a-hook-kind.md,publish-a-machine-as-an-npm-package.md,let-an-agent-write-a-chart.md,run-a-chart-by-name.md,start-a-run.md,answer-a-gate.md,answer-a-gate-from-a-forge.md,steer-an-agent.md,watch-a-run.md,read-a-conversation.md,look-inside-a-sandbox.md,cancel-a-run.md,open-the-console.md,use-a-local-model.md,use-a-hosted-provider.md,give-the-cluster-git-credentials.md,give-a-caller-a-scope.md,move-from-kind-to-a-shared-cluster.md,mirror-the-kit-images.md,upgrade-the-kit-version.md,clean-up.md,fix-a-failed-converge.md}|concepts:{machines-and-workflows.md,agents-and-turns.md,the-menu.md,gates.md,effects.md,workspaces.md,composition.md,charts.md,pools-and-sources.md,architecture.md,secrets-and-trust.md,callers-and-hooks.md,converge.md,durable-runs.md}|.:{index.md,why.md}|get-started:{install.md,create-an-instance.md,connect-a-model.md,a-model-decides.md,an-agent-in-a-sandbox.md,have-your-assistant-write-a-machine.md}|reference/decisions:{one file per ADR; reference/decisions.md lists them}

package/docs/concepts/agents-and-turns.md

@@ -14,10 +14,10 @@ what a state sets for one Turn, and how a Turn ends.
 
 ## Why the work is in Turns
 
-A long conversation in which a model decides all the work is difficult to review and difficult to control. In jr2, each
-state of the Machine asks the Agent for one thing. The Agent does that thing, then picks an event. The Machine decides
-where the run goes next. Thus the Agent does one thing at a time, and the [Console](../reference/glossary.md#console)
-shows the state of each Turn.
+A long [Conversation](../reference/glossary.md#conversation) in which a model decides all the work is difficult to
+review and difficult to control. In jr2, each state of the Machine asks the Agent for one thing. The Agent does that
+thing, then picks an event. The Machine decides where the run goes next. Thus the Agent does one thing at a time, and
+the [Console](../reference/glossary.md#console) shows the state of each Turn.
 
 A model cannot correctly control some parts of a Turn, so jr2 controls them. jr2 sets where the Agent works and how its
 Turn ends. It also decides what to do when a Turn does not end. You do not write that code, so you cannot forget it.
@@ -35,6 +35,8 @@ Agent. A state invokes it with `src: "coder"`. The definition is plain data, and
 | `workspace`     | What the Agent can do to the Workspace: `"write"` (the default), `"read"` or `"none"`. |
 | `thinkingLevel` | How hard the model thinks, when the state sets no other level. The default is `"off"`. |
 | `description`   | A short text for the people who read the Machine. The model does not read it.          |
+| `steerable`     | `false` refuses a Steering message from a Caller. The default is `true`.               |
+| `mcp`           | The MCP servers whose tools the Agent can call, each with its allowlist.               |
 
 [`AgentDefinition`](../reference/authoring-surface/type-agentdefinition.md) gives each field.
 
@@ -66,6 +68,30 @@ The field also tells where the Turn runs. An Agent with `"write"` or `"read"` wo
 [Instance Harness](../reference/glossary.md#instance-harness), also when a `workspace()` holds it.
 [Architecture](architecture.md) shows where each Harness runs.
 
+## The MCP tools
+
+The [MCP tools](../reference/glossary.md#mcp-tools) of an Agent are the tools of the MCP servers that its definition
+names. They let the Agent act on a service, such as a chat or a ticket tracker, with a credential that it never reads.
+The `mcp` block of `jr2.config.ts` declares each server by a name of yours, and the `mcp` field of the definition names
+the servers and the tools:
+
+- A remote server needs an allowlist: a list of tool names, or `"*"`. The Harness gives the model only those tools. The
+  token of the server is a [Held secret](../reference/glossary.md#held-secret), so the model and the code of the
+  Workspace never read it. Thus the list is a guarantee, except where Workspace code can also spend the token. There,
+  `jr2 up` takes only `"*"`.
+- A stdio server is a program of the [Sandbox Image](../reference/glossary.md#sandbox-image). It runs as Workspace code,
+  inside the confinement of the Sandbox, so it takes no list. A Menu-only Agent cannot name one.
+
+A call of an MCP tool is not a pick. It changes nothing in the Machine, and the Turn goes on after it. The model reads
+the text of the result. The Harness reads the tools of each server at the first Turn of a conversation, and keeps the
+same tools until the conversation ends. The tools block has the Working tools first, then the MCP tools, then the Menu.
+A server that does not answer at the first Turn fails the Turn.
+
+An MCP tool runs when the model calls it, with no approval. A call that needs the approval of a person is the work of
+the Machine: the Agent picks, a [Gate](../reference/glossary.md#gate) waits for the approval, and an `mcp`
+[Effect](../reference/glossary.md#effect) makes the call (see [Effects](effects.md#mcp)).
+[Give an Agent MCP tools](../guides/give-an-agent-mcp-tools.md) gives the fields and the refusals.
+
 ## What a state sets for one Turn
 
 The `input` of the invoke is the Turn. It has five keys, and no other:
@@ -368,6 +394,16 @@ continue that conversation again. The next Turn with `continue: true` starts a n
 full task again, because jr2 cannot write that prompt for you. A Harness restart is the only exception: the restarted
 Harness keeps the conversation, so the next Turn continues it.
 
+### The record of a conversation
+
+The Harness prints each conversation to its pod log. It also sends each entry to the
+[Orchestrator](../reference/glossary.md#orchestrator) during the Turn: each prompt, the text and the thinking of the
+model, each call and the answer of each pick. The Orchestrator keeps these entries for as long as it keeps the run, so
+you can read the conversation after the Sandbox is gone. The record holds no result of a Working tool or of an MCP tool,
+because such a result is the text that the Agent read, which can hold a secret. The record is for a person to read. The
+model never reads it, and a Turn never continues from it. `jr2 logs` and the bottom drawer of the Console show it. See
+[Read a conversation](../guides/read-a-conversation.md).
+
 ## The Briefing
 
 The Briefing is the text that jr2 itself gives the model. It tells facts that a correct Agent needs and cannot find for
@@ -375,12 +411,13 @@ itself. It tells nothing about the task: the prompt tells the task. It has two p
 
 - **The standing part** comes after the instructions, and it is the same on each Turn. It tells how the Agent acts on
   the run: with a pick from its Menu. It also tells the CPUs and the [Size](../reference/glossary.md#size) of the
-  Sandbox, or that a Menu-only Agent has no Working tools.
+  Sandbox, or that a Menu-only Agent has no Working tools. To an Agent with MCP tools, it tells that a call of an MCP
+  tool acts on a service outside the workflow, is not a pick, and does not end the Turn.
 - **The Turn part** comes after the prompt. It tells the directory of the Turn, its
-  [Allowed picks](../reference/glossary.md#allowed-picks), and the notices. [The Menu](the-menu.md) tells what the
-  Allowed picks are. When they change during the Turn, the Harness tells them to the model again. When an Allowed pick
-  carries a [Chart](../reference/glossary.md#chart), the Turn part also tells how a Chart runs (see
-  [Charts](charts.md)).
+  [Allowed picks](../reference/glossary.md#allowed-picks), the notices, and the [Steering messages](#steering-messages).
+  [The Menu](the-menu.md) tells what the Allowed picks are. When they change during the Turn, the Harness tells them to
+  the model again. When an Allowed pick carries a [Chart](../reference/glossary.md#chart), the Turn part also tells how
+  a Chart runs (see [Charts](charts.md)).
 
 A notice tells a Turn what happened before it. For example: the conversation is new and the earlier context is gone, or
 the processes of the Sandbox stopped at its memory limit. A notice about a conversation goes to the next Turn of that
@@ -398,6 +435,34 @@ Turn the stop cut.
 You cannot turn the Briefing off. It contains only facts that make the Agent work better. An `instructions` that tells
 the same fact again does no harm.
 
+## Steering messages
+
+A [Steering message](../reference/glossary.md#steering-message) is free text to one Agent of a run. The Agent hears it
+one time, and nothing interrupts the Agent. A [Caller](../reference/glossary.md#caller) sends one with `jr2 steer`, and
+the Machine sends one with the [`steer`](../reference/authoring-surface/steer.md) action. A message is not a pick and
+not an event: no guard reads it, and no Gate takes it. The Agent decides what to do with it, and it acts on the run only
+with its picks.
+
+A message goes to an Agent slot: the path of the Machine and the name of the Agent, such as `root/coder`. The slot of an
+Agent in a child Machine starts with the path of that Machine, such as `review/reviewer`. `jr2 steer <run id>` lists the
+slots of a run.
+
+- When a Turn of the slot is open, the Harness adds the message to the Turn before the next model request.
+- When the Turn ends with a pick before its next model request, the message waits for the next Turn of the slot.
+- When no Turn of the slot is open, the message waits for the next Turn of the slot in the same Machine instance.
+- When that Machine instance ends first, the message is not delivered. The run records it as `not-delivered`.
+
+The Harness puts the message in the Turn part, after the notices and before the Allowed picks. It tells the model who
+wrote the message:
+
+- A Caller's message is an instruction from outside the run, with the name of the Caller.
+- A message that the Machine relays from another Agent is information from a peer. The workflow did not write it. A line
+  after the text says that it is not an instruction, and that the Agent does what the workflow asked.
+- A message that the Machine relays from a Gate is what the Gate received, not an order. The workflow did not write it.
+- A message from the Machine that relays no one is the text of the workflow.
+
+[Steer an Agent](../guides/steer-an-agent.md) tells how to send one.
+
 ## When a Turn fails
 
 jr2 tries to recover a Turn before it tells the Machine. When it cannot recover the Turn, it sends one event,
@@ -452,12 +517,19 @@ the model in `models`. A model with no context window gets no Compaction.
   refuses a model that it cannot find when the Turn starts.
 - A Turn ends when the state that invoked the Agent exits.
 - After `agent.fault` for a conversation, jr2 does not continue it, except after a Harness restart.
+- `jr2 up` refuses an MCP server that the `mcp` block does not declare, a remote server with no allowlist, and a stdio
+  server on a Menu-only Agent.
+- A Steering message is at most 16 KiB. `steerable: false` refuses a Caller's message, and the Machine can still send
+  one.
 
 [Set an Agent's access and Dials](../guides/set-an-agents-access-and-dials.md) gives the exact text of each refusal.
 
 ## Read next
 
 - [Set an Agent's access and Dials](../guides/set-an-agents-access-and-dials.md)
+- [Read a conversation](../guides/read-a-conversation.md)
+- [Give an Agent MCP tools](../guides/give-an-agent-mcp-tools.md) and
+  [Write a tool as an MCP server](../guides/write-a-tool-as-an-mcp-server.md)
 - [The Menu](the-menu.md), [Workspaces](workspaces.md) and [Architecture](architecture.md)
 - Reference: [`agent`](../reference/authoring-surface/agent.md),
   [`AgentDefinition`](../reference/authoring-surface/type-agentdefinition.md),
@@ -466,6 +538,8 @@ the model in `models`. A model with no context window gets no Compaction.
   [`harness.provider`](../reference/config.md#harness-provider)
 - [ADR-0018](../reference/decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md): an Agent is a
   definition, and a Turn can set its Dials
+- [ADR-0023](../reference/decisions/0023-the-harness-prints-the-conversation.md): the Harness prints the conversation,
+  and the Orchestrator keeps it
 - [ADR-0028](../reference/decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md): what an
   Agent can do to the Workspace is a part of its definition
 - [ADR-0057](../reference/decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md): a Turn is its
@@ -474,5 +548,8 @@ the model in `models`. A model with no context window gets no Compaction.
   state that asked for it
 - [ADR-0016](../reference/decisions/0016-agent-turn-mechanics-are-internal.md): jr2 owns the mechanics of a Turn
 - [ADR-0062](../reference/decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md): the Briefing
+- [ADR-0002](../reference/decisions/0002-duplex-streaming-actor.md): Steering messages
+- [ADR-0079](../reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md):
+  the MCP tools of an Agent
 - [ADR-0035](../reference/decisions/0035-a-runaway-turn-is-ended-rerolled-once-then-a-fault.md): a Runaway
 - [ADR-0036](../reference/decisions/0036-a-turn-compacts-its-own-context-mid-flight.md): Compaction

package/docs/concepts/architecture.md

@@ -46,7 +46,7 @@ its pod can reach. Thus jr2 puts each thing that the Agent must not touch in a d
     - **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
@@ -84,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
@@ -116,9 +123,11 @@ 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. Each program that a Working tool starts runs confined with Landlock. 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.
+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:
 
@@ -128,8 +137,8 @@ The Harness has two placements:
   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
@@ -141,14 +150,14 @@ connect to a Harness pod, and that stop each Harness pod at the cloud metadata a
 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 five 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, and the fetch asks. It sends the first four
-  with the control token of the Sandbox, and the fetch asks with its fetch token. These five routes are all that it
-  forwards. It refuses all other routes. The Harness sends the first four 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. 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
@@ -156,8 +165,8 @@ 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:
 
@@ -165,12 +174,16 @@ where. It has two placements:
   `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.
-
-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,
-and confined in the same way.
+  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.
+
+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.