@jr2/orchestrator 0.5.1 → 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.5.1. 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,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.
 
@@ -49,8 +51,10 @@ for one Turn, because then the name of the Agent would not tell what it is.
 ## The Working tools
 
 The [Working tools](../reference/glossary.md#working-tools) are the file and shell tools of an Agent: read, write, edit,
-bash, grep and glob. The [Harness](../reference/glossary.md#harness) runs them in its own container. The `workspace`
-field selects them:
+bash, grep and glob. The [Harness](../reference/glossary.md#harness) runs them in its own container. Each program that
+they start, and the file I/O of read, write and edit, runs confined with Landlock. It can do all that the user of the
+container can do, but it cannot read what the Harness holds. [Secrets and trust](secrets-and-trust.md) tells why. The
+`workspace` field selects the Working tools:
 
 - `"write"` gives all the Working tools.
 - `"read"` gives no write tool and no edit tool. The Agent keeps bash, so a command can still write a file. A review
@@ -64,14 +68,39 @@ 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:
 
 - **The [Frame](../reference/glossary.md#frame): `prompt` and `cwd`.** The prompt tells what this Turn is about. `cwd`
-  is the directory where the Working tools work. A definition cannot hold a `cwd`, because the Worktree of a run exists
-  only when the run starts. Under a Workspace with one [Repo Slot](../reference/glossary.md#repo-slot), the default
-  `cwd` is the Worktree of that slot.
+  is the directory where the Working tools work. A definition cannot hold a `cwd`, because a Worktree exists only after
+  a run cuts it. Under a Workspace with [Repo Slots](../reference/glossary.md#repo-slot), a Turn of an Agent with
+  Working tools states its `cwd`. A Turn that wants `/work` states it too. There is no default, because a search in
+  `/work` hits `default/`, and a relative write lands outside each Worktree.
 - **The [Dials](../reference/glossary.md#dials): `model` and `thinkingLevel`.** They tell how hard the Agent works on
   this Turn, and they replace the values of the definition for this Turn only. The Agent stays the same Agent.
 - **`continue`.** It tells if the Turn continues the conversation of the Agent. See
@@ -90,7 +119,7 @@ changes, the coder continues its conversation and thinks harder on that Turn:
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const finish = defineEvent({
   name: "finish",
@@ -112,6 +141,9 @@ const runInput = z.object({ branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { summary: string; notes: string };
 
+// The Worktree of each Turn of the coder.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [finish, approve, requestChanges],
@@ -128,21 +160,30 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "fix",
   context: ({ input }) => ({ ...input, summary: "", notes: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
         // The Frame (prompt and cwd) and continue. This Turn starts the coder's conversation.
         input: ({ context }) => ({
           prompt: "Make `node --test` pass, then commit.",
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
         }),
       },
@@ -161,7 +202,7 @@ const body = jr2Setup({
         // The same conversation as in coding, with a Dial: the coder thinks harder on this Turn.
         input: ({ context }) => ({
           prompt: `The fix is not complete: ${context.notes}\nFix it, then commit.`,
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
           thinkingLevel: "high",
         }),
@@ -169,6 +210,7 @@ const body = jr2Setup({
       on: { finish: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -177,7 +219,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -186,7 +227,7 @@ export const machine = workspace(body, {
 ```ts
 import { z } from "zod";
 import { assign } from "xstate";
-import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
 
 const finish = defineEvent({
   name: "finish",
@@ -208,6 +249,9 @@ const runInput = z.object({ branch: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
 type Context = BodyInput & { summary: string; notes: string };
 
+// The Worktree of each Turn of the coder.
+const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+
 const body = jr2Setup({
   types: {} as { input: BodyInput; context: Context },
   events: [finish, approve, requestChanges],
@@ -224,21 +268,30 @@ const body = jr2Setup({
       workspace: "none",
       thinkingLevel: "low",
     }),
+    cut: worktree(),
     fail: fail(),
   },
 }).createMachine({
   id: "fix",
   context: ({ input }) => ({ ...input, summary: "", notes: "" }),
   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
-  initial: "coding",
+  initial: "cutting",
   states: {
+    // The Workspace only clones. The Machine cuts the Worktree that the Agent works in.
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+      },
+    },
     coding: {
       invoke: {
         src: "coder",
         // The Frame (prompt and cwd) and continue. This Turn starts the coder's conversation.
         input: ({ context }) => ({
           prompt: "Make `node --test` pass, then commit.",
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
         }),
       },
@@ -257,7 +310,7 @@ const body = jr2Setup({
         // The same conversation as in coding, with a Dial: the coder thinks harder on this Turn.
         input: ({ context }) => ({
           prompt: `The fix is not complete: ${context.notes}\nFix it, then commit.`,
-          cwd: context.workspace.repos.app,
+          cwd: fixTree(context),
           continue: true,
           thinkingLevel: "high",
         }),
@@ -265,6 +318,7 @@ const body = jr2Setup({
       on: { finish: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
     },
     done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
@@ -273,7 +327,6 @@ const body = jr2Setup({
 export const machine = workspace(body, {
   input: runInput,
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: input.branch }),
 });
 ```
 
@@ -341,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
@@ -348,20 +411,58 @@ 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 the next 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. jr2 gives each notice one time, to the next Turn that
-it is for.
+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
+conversation. A notice about the Workspace goes to each conversation that was in the Workspace when the processes
+stopped:
+
+- A Turn that is open hears it before its next model request.
+- A continued conversation hears it at its next Turn.
+- The next Turn of the Agent whose Turn the stop cut hears it, also when that Turn is fresh.
+
+A conversation hears each notice one time. A conversation whose own bash call already told it about the stop does not
+hear the notice. A conversation that starts after the stop does not hear it, except the next Turn of the Agent whose
+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,
@@ -409,19 +510,26 @@ the model in `models`. A model with no context window gets no Compaction.
   different key.
 - A Turn cannot set `instructions` or `workspace`.
 - `cwd` is an absolute path. The Harness refuses a Turn with a relative `cwd`.
-- Under a Workspace with more than one Repo Slot, each Turn of an Agent with Working tools sets `cwd`. jr2 refuses the
-  Turn without it.
+- Under a Workspace with Repo Slots, each Turn of an Agent with Working tools sets `cwd`. jr2 refuses the Turn without
+  it.
 - An Agent with `"write"` or `"read"` runs in the body of a `workspace()`. jr2 refuses its Turn outside one.
 - `jr2 up` sees only the models of the definitions. It cannot see a model that a Turn sets as a Dial. The Harness
   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),
@@ -430,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
@@ -438,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