@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/guides/steer-an-agent.md

@@ -0,0 +1,332 @@
+---
+title: Steer an Agent
+description: Send free text to one Agent of a live run, from the CLI, from HTTP, or from the Machine itself.
+---
+
+# Steer an Agent
+
+Send free text to one [Agent](../reference/glossary.md#agent) of a live run, from the CLI, from HTTP, or from the
+[Machine](../reference/glossary.md#machine) itself.
+
+A [Steering message](../reference/glossary.md#steering-message) is not a pick and not an event. No guard reads it, and
+no [Gate](../reference/glossary.md#gate) takes it. The Agent hears it one time, and nothing interrupts the Agent. Then
+the Agent decides what to do, and it acts on the run only with its picks. To move the run, answer a Gate:
+[Answer a Gate](answer-a-gate.md).
+
+The examples on this page use the [Workflow](../reference/glossary.md#workflow) `notes`. A writer writes release notes,
+and a reviewer reads them. When the reviewer sends a note, the Machine relays it to the writer as a Steering message.
+Save the file as `workflows/notes.ts` in your [Instance](../reference/glossary.md#instance). Then run `jr2 up`:
+
+**Anthropic**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, steer } from "@jr2/orchestrator";
+
+// The writer's pick: the draft is ready for review.
+const done = defineEvent({
+  name: "done",
+  description: "The draft is ready. Give the whole draft.",
+  input: z.object({ draft: z.string().min(1) }),
+});
+// The reviewer's two picks.
+const note = defineEvent({
+  name: "note",
+  description: "Send the draft back to the writer, with what to change.",
+  input: z.object({ text: z.string().min(1) }),
+});
+const approve = defineEvent({
+  name: "approve",
+  description: "The draft is good.",
+  input: z.object({}),
+});
+
+type Context = { version: string; draft?: string; fault?: string };
+
+export const machine = jr2Setup({
+  types: {} as { input: { version: string }; context: Context },
+  events: [done, note, approve],
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You write short release notes.",
+      workspace: "none",
+    }),
+    // A Caller cannot steer the reviewer. The Machine can.
+    reviewer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You review release notes for clear and correct words.",
+      workspace: "none",
+      steerable: false,
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "notes",
+  input: z.object({ version: z.string() }),
+  context: ({ input }) => ({ version: input.version }),
+  initial: "writing",
+  // A Turn that fails in either state ends the run `failed`, with the reason of the Turn.
+  on: { "agent.fault": { target: ".failed", actions: assign({ fault: ({ event }) => event.reason }) } },
+  states: {
+    writing: {
+      invoke: {
+        src: "writer",
+        // The writer continues its conversation, so it keeps its draft from Turn to Turn.
+        input: ({ context }) => ({ prompt: `Write the release notes for ${context.version}.`, continue: true }),
+      },
+      on: { done: { target: "reviewing", actions: assign({ draft: ({ event }) => event.draft }) } },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review these release notes:\n\n${context.draft ?? ""}` }),
+      },
+      on: {
+        // The reviewer's note goes to the writer's next Turn as a Steering message. `from` names the
+        // reviewer, so the writer reads it as information from a peer, not as an instruction.
+        note: {
+          target: "writing",
+          actions: steer("writer", ({ event }) => event.text, { from: ({ event }) => event.sender }),
+        },
+        approve: "published",
+      },
+    },
+    published: { type: "final" },
+    failed: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.fault ?? "the Turn failed" }) } },
+  },
+});
+```
+
+**Local**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, steer } from "@jr2/orchestrator";
+
+// The writer's pick: the draft is ready for review.
+const done = defineEvent({
+  name: "done",
+  description: "The draft is ready. Give the whole draft.",
+  input: z.object({ draft: z.string().min(1) }),
+});
+// The reviewer's two picks.
+const note = defineEvent({
+  name: "note",
+  description: "Send the draft back to the writer, with what to change.",
+  input: z.object({ text: z.string().min(1) }),
+});
+const approve = defineEvent({
+  name: "approve",
+  description: "The draft is good.",
+  input: z.object({}),
+});
+
+type Context = { version: string; draft?: string; fault?: string };
+
+export const machine = jr2Setup({
+  types: {} as { input: { version: string }; context: Context },
+  events: [done, note, approve],
+  actors: {
+    writer: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You write short release notes.",
+      workspace: "none",
+    }),
+    // A Caller cannot steer the reviewer. The Machine can.
+    reviewer: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You review release notes for clear and correct words.",
+      workspace: "none",
+      steerable: false,
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "notes",
+  input: z.object({ version: z.string() }),
+  context: ({ input }) => ({ version: input.version }),
+  initial: "writing",
+  // A Turn that fails in either state ends the run `failed`, with the reason of the Turn.
+  on: { "agent.fault": { target: ".failed", actions: assign({ fault: ({ event }) => event.reason }) } },
+  states: {
+    writing: {
+      invoke: {
+        src: "writer",
+        // The writer continues its conversation, so it keeps its draft from Turn to Turn.
+        input: ({ context }) => ({ prompt: `Write the release notes for ${context.version}.`, continue: true }),
+      },
+      on: { done: { target: "reviewing", actions: assign({ draft: ({ event }) => event.draft }) } },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({ prompt: `Review these release notes:\n\n${context.draft ?? ""}` }),
+      },
+      on: {
+        // The reviewer's note goes to the writer's next Turn as a Steering message. `from` names the
+        // reviewer, so the writer reads it as information from a peer, not as an instruction.
+        note: {
+          target: "writing",
+          actions: steer("writer", ({ event }) => event.text, { from: ({ event }) => event.sender }),
+        },
+        approve: "published",
+      },
+    },
+    published: { type: "final" },
+    failed: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.fault ?? "the Turn failed" }) } },
+  },
+});
+```
+
+The Agents use the model of the tab.
+
+In the commands, replace these values:
+
+- `<namespace>`: the namespace of your Instance. It is the [`name`](../reference/config.md#name) in `jr2.config.ts`.
+  When `jr2.config.ts` sets no `name`, it is the name of the Instance folder.
+- `<run id>`: the run id, or its first 4 characters or more. `jr2 run` prints the run id in the line
+  `run <run id> (<workflow>) — attached`.
+
+Give each `jr2` command in the Instance folder.
+
+## Start a run
+
+```sh
+jr2 run notes --input '{"version":"1.4.0"}'
+```
+
+```text
+→ context <context> / namespace <namespace>
+run 7058fde8-4c32-4513-82f0-e6c095d8707b (notes) — attached
+  → active "writing"
+  → active "writing"
+```
+
+Your run id is different. Give the commands in the next steps in a second terminal.
+
+## Find the Agent slot
+
+A message goes to an Agent slot: the path of the Machine and the name of the Agent. The Agents of the root Machine have
+the path `root`. An Agent in a child Machine has the path of that Machine, such as `review/reviewer`. Give
+[`jr2 steer`](../reference/cli.md#steer) the run id alone to list the slots:
+
+```sh
+jr2 steer 7058
+```
+
+```text
+→ context <context> / namespace <namespace>
+[{"agent":"root/writer","open":true,"steerable":true},{"agent":"root/reviewer","open":false,"steerable":false}]
+```
+
+- `open` is `true` when a [Turn](../reference/glossary.md#turn) of the slot is open now.
+- `steerable` is `false` when the definition of the Agent says `steerable: false`. A Caller cannot steer it.
+
+The list has each Agent of each Machine instance that is live now, also an Agent with no open Turn.
+
+## Send the message
+
+```sh
+jr2 steer 7058 root/writer "Put the breaking change first."
+```
+
+```text
+→ context <context> / namespace <namespace>
+sent a Steering message to root/writer on 7058fde8-4c32-4513-82f0-e6c095d8707b: its open Turn hears it at its next step boundary, or its next Turn hears it if this Turn ends first
+```
+
+Then one of these things occurs:
+
+- 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. The next Turn of the slot in the same Machine instance hears it,
+  and `jr2 steer` prints `its next Turn hears it`.
+- When that Machine instance ends first, the message is not delivered.
+
+## Read what became of the message
+
+[`jr2 status`](../reference/cli.md#status) prints the record of the messages of the run in its `steering` field. Each
+entry has the slot, the author, the text, the time, and the `outcome`: `held` while it waits, `heard` when a Turn heard
+it, or `not-delivered` when its Machine instance ended first.
+
+```sh
+jr2 status 7058
+```
+
+```text
+→ context <context> / namespace <namespace>
+{"runId":"7058fde8-4c32-4513-82f0-e6c095d8707b","workflow":"notes",…,"steering":[{"id":"c46a31f0-db82-4d80-b7f1-8908c2d9b121","agent":"root/writer","author":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"text":"Put the breaking change first.","at":"2026-11-06T20:56:33.005Z","outcome":"heard"},{"id":"f788b1f6-2b93-44be-a54e-e91f83685493","agent":"root/writer","author":{"kind":"machine","from":{"party":"agent","id":"reviewer"}},"text":"The release notes are well-structured, but I suggest a change for clarity in the **Notifications** section:\n\n\"Real-time notifications are now **persisted** across device logins.\"\n\n\"Persisted\" is technical jargon referring to data storage. If the intended meaning is that notifications appear on different devices, \"**synchronized**\" (or \"synced\") is the standard and clearer term for users.\n\nSuggested edit: \"Real-time notifications are now **synchronized** across devices.\"","at":"2026-11-06T20:57:35.442Z","outcome":"heard"}],…}
+started by: token/instance on behalf of kubernetes-admin
+```
+
+The model reads the message after the notices of the Turn and before its Allowed picks. The Harness tells the model that
+the message is an instruction from outside the run, and gives your name as a [Caller](../reference/glossary.md#caller).
+
+## Send the message from the Console
+
+With a credential that has the `steer` scope for the Workflow, the [Console](../reference/glossary.md#console) shows a
+box beside the conversation in the bottom drawer. Select the run, and click the tab of the Agent slot. Type the message
+in the box under `steer <slot>`, and click `send`. The box shows `<slot> cannot be steered now` when the definition of
+the Agent says `steerable: false`, or when the Machine instance of the slot ended. The conversation shows the message
+where the model read it. [Open the Console](open-the-console.md#read-a-conversation) tells how to open the drawer.
+
+## Send the message from HTTP
+
+A client that is not the CLI sends the message to
+[`POST /runs/:runId/steering`](../reference/http-api.md#post-runs-runid-steering), with the credential of a Caller that
+has the `steer` scope for the Workflow of the run. [Give a Caller a scope](give-a-caller-a-scope.md) makes such a token.
+The path takes the full run id, not a prefix.
+[`GET /runs/:runId/agents`](../reference/http-api.md#get-runs-runid-agents) lists the slots. This example reaches the
+Orchestrator through the port forward in [Open the Console](open-the-console.md):
+
+```sh
+curl -X POST http://localhost:4000/runs/<run id>/steering \
+  -H "authorization: Bearer <token>" \
+  -d '{"agent":"root/writer","text":"Put the breaking change first."}'
+```
+
+```text
+{"id":"29e54d63-e858-4249-a789-f7e5506f433a","agent":"root/writer","open":true}
+```
+
+The status is 202.
+
+## Steer from the Machine
+
+The Machine sends a Steering message with the [`steer`](../reference/authoring-surface/steer.md) action, in a
+transition. In `notes.ts`, the `note` pick of the reviewer sends the writer back to `writing`, and `steer` gives the
+reviewer's text to the writer's next Turn.
+
+`from` names the [Sender](../reference/glossary.md#sender) of the event: here, the reviewer. Then the writer reads the
+text as information from a peer, not as an instruction. When `from` is a Gate, the writer reads the text as what the
+Gate received, not as an order: the workflow did not write it. A `steer` with no `from` is the text of the workflow
+itself. Agents tell each other things only in this way: jr2 gives an Agent no tool to message another Agent.
+
+The Machine can steer an Agent whose definition says `steerable: false`. That refuses Callers only.
+
+## Rules
+
+- A message is at most 16 KiB of UTF-8. `POST /runs/:runId/steering` refuses a longer text with the status 413:
+  `the text is longer than 16384 bytes (16 KiB)`. The `steer` action cuts a longer text and adds
+  `[jr2 cut this message at 16 KiB]`.
+- A body with no `agent`, or no `text`, gets the status 400.
+- A slot that no live Machine instance of the run holds gets the status 409, with the slots of the run in `agents`:
+  `no live Machine instance of run "<run id>" holds the Agent slot "<agent>" (its slots: <slots>)`. A run that has ended
+  gets 409 too: `run "<run id>" is not live: no Agent of it can hear a message`.
+- A slot whose Agent says `steerable: false` gets the status 403:
+  `the Agent slot "<agent>" is not steerable: its definition says steerable: false`.
+- A Caller with no `steer` scope for the Workflow of the run gets the status 403:
+  `the Caller <via>/<name> needs the "steer" scope for Workflow "<workflow>" (ADR-0078)`.
+- An unknown run gets the status 404: `no run "<run id>"`.
+- The record keeps the newest 100 messages of a run, and each message that waits.
+
+## Read next
+
+- [Agents and Turns](../concepts/agents-and-turns.md#steering-messages)
+- [`jr2 steer`](../reference/cli.md#steer) and [`steer`](../reference/authoring-surface/steer.md)
+- [ADR-0002](../reference/decisions/0002-duplex-streaming-actor.md#steering-messages): Steering messages
+- [ADR-0062](../reference/decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md): one ledger for notices
+  and Steering messages

package/docs/guides/use-a-hosted-provider.md

@@ -186,7 +186,7 @@ custom provider, with `harness.provider` and `apiKey`. The guide
 - `jr2 up` refuses a gateway address that is not `https://`:
   `harness.catalog.<id>.baseUrl must be an https:// URL — the Custodian carries TLS only (ADR-0059). Read it from .env: catalog: { anthropic: { baseUrl: process.env.LITELLM_URL ?? "" } }`.
 - `jr2 up` warns about a key that no pod gets:
-  `warning: secrets[<i>] (<NAME>) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider reads it, and no Effect names it (ADR-0059, ADR-0068)`.
+  `warning: secrets[<i>] (<NAME>) is named by nothing; goes nowhere — no workspace() lists it, no Agent's provider reads it, and no Effect or Hook names it (ADR-0059, ADR-0068)`.
 - A credential that signs each request, such as `AWS_ACCESS_KEY_ID`, cannot be a Held secret. `jr2 up` warns when
   `harness.env` sets one. Send the calls through a gateway that holds the credential, and hold the key of the gateway:
   `warning: harness.env sets <NAME>: a signing credential cannot be held (a Stand-in cannot be swapped into a signature), so the Agent can read it — route the provider through a gateway that holds it, and hold the gateway's key instead (ADR-0059)`.