@jr2/orchestrator 0.4.1 → 0.6.0

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

@@ -0,0 +1,478 @@
+---
+title: Agents and Turns
+description: What an Agent is, what one Turn of an Agent holds, how a Turn ends, and what jr2 does when a Turn fails.
+---
+
+# Agents and Turns
+
+An [Agent](../reference/glossary.md#agent) is a model with instructions, which a
+[Machine](../reference/glossary.md#machine) invokes to do the work of a state. Its definition tells who it is: its
+model, its instructions, and what it can do to the [Workspace](../reference/glossary.md#workspace). A
+[Turn](../reference/glossary.md#turn) is one answer of the Agent to one state. It holds the prompt of the state, the
+work of the Agent, and its pick from its [Menu](../reference/glossary.md#menu). This page tells what a definition holds,
+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 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.
+
+## The definition
+
+An Agent is an [`agent()`](../reference/authoring-surface/agent.md) under `actors` in
+[`jr2Setup`](../reference/authoring-surface/jr2setup.md): `actors: { coder: agent({ … }) }`. The key is the name of the
+Agent. A state invokes it with `src: "coder"`. The definition is plain data, and it has these fields:
+
+| Field           | What it tells                                                                          |
+| --------------- | -------------------------------------------------------------------------------------- |
+| `model`         | The model, as `<provider>/<model id>`. It is required.                                 |
+| `instructions`  | Who the Agent is and how it works. The model reads them on each Turn.                  |
+| `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.          |
+
+[`AgentDefinition`](../reference/authoring-surface/type-agentdefinition.md) gives each field.
+
+An Agent belongs to the Machine that holds it. Two Machines in one run can each hold an Agent named `coder`, and the two
+are different Agents. A Machine that you get from a package can leave its model
+[`open`](../reference/authoring-surface/open.md), for you to bind with
+[`customize()`](../reference/authoring-surface/customize.md). [Composition](composition.md) tells how.
+
+`instructions` and `workspace` are the identity of the Agent. Only the definition sets them. A state cannot change them
+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. 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
+  Turn whose `cwd` is the review [Worktree](../reference/glossary.md#worktree) cannot move the branch with a change.
+  [Workspaces](workspaces.md) tells how.
+- `"none"` gives no Working tools. The Agent reads its prompt and picks from its Menu. This is a Menu-only Agent.
+
+The field also tells where the Turn runs. An Agent with `"write"` or `"read"` works in the
+[Sandbox](../reference/glossary.md#sandbox) of a Workspace, so a state invokes it in the body of a
+[`workspace()`](../reference/authoring-surface/workspace.md). A Menu-only Agent has no Sandbox. Its Turn runs on the
+[Instance Harness](../reference/glossary.md#instance-harness), also when a `workspace()` holds it.
+[Architecture](architecture.md) shows where each Harness runs.
+
+## 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 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
+  [Continue a conversation](#continue-a-conversation).
+
+The state writes the input as a function of its context. Thus each Turn can have its own prompt and its own directory.
+
+## An example
+
+In this [Workflow](../reference/glossary.md#workflow), a coder fixes the tests of a
+[Repo](../reference/glossary.md#repo), and a Menu-only checker reads the coder's summary. When the checker asks for
+changes, the coder continues its conversation and thinks harder on that Turn:
+
+**Anthropic**
+
+```ts
+import { z } from "zod";
+import { assign } from "xstate";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
+
+const finish = defineEvent({
+  name: "finish",
+  description: "Call this when `node --test` passes and you committed the fix. Say what you changed.",
+  input: z.object({ summary: z.string() }),
+});
+const approve = defineEvent({
+  name: "approve",
+  description: "Call this when the summary shows a complete fix.",
+  input: z.object({}),
+});
+const requestChanges = defineEvent({
+  name: "request_changes",
+  description: "Call this when the fix is not complete. Say what is missing.",
+  input: z.object({ notes: z.string() }),
+});
+
+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],
+  actors: {
+    // The definition: who the Agent is. It is the same on every Turn.
+    coder: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You fix failing tests. You change no test.",
+    }),
+    // A Menu-only Agent: no Working tools. It reads its prompt and picks.
+    checker: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You read the summary of a fix, and you decide if the fix is complete.",
+      workspace: "none",
+      thinkingLevel: "low",
+    }),
+    cut: worktree(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix",
+  context: ({ input }) => ({ ...input, summary: "", notes: "" }),
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  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: fixTree(context),
+          continue: true,
+        }),
+      },
+      on: { finish: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
+    },
+    checking: {
+      invoke: { src: "checker", input: ({ context }) => ({ prompt: `Is this fix complete?\n\n${context.summary}` }) },
+      on: {
+        approve: "done",
+        request_changes: { target: "fixing", actions: assign({ notes: ({ event }) => event.notes }) },
+      },
+    },
+    fixing: {
+      invoke: {
+        src: "coder",
+        // 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: fixTree(context),
+          continue: true,
+          thinkingLevel: "high",
+        }),
+      },
+      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" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+**Local**
+
+```ts
+import { z } from "zod";
+import { assign } from "xstate";
+import { agent, defineEvent, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
+
+const finish = defineEvent({
+  name: "finish",
+  description: "Call this when `node --test` passes and you committed the fix. Say what you changed.",
+  input: z.object({ summary: z.string() }),
+});
+const approve = defineEvent({
+  name: "approve",
+  description: "Call this when the summary shows a complete fix.",
+  input: z.object({}),
+});
+const requestChanges = defineEvent({
+  name: "request_changes",
+  description: "Call this when the fix is not complete. Say what is missing.",
+  input: z.object({ notes: z.string() }),
+});
+
+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],
+  actors: {
+    // The definition: who the Agent is. It is the same on every Turn.
+    coder: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You fix failing tests. You change no test.",
+    }),
+    // A Menu-only Agent: no Working tools. It reads its prompt and picks.
+    checker: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You read the summary of a fix, and you decide if the fix is complete.",
+      workspace: "none",
+      thinkingLevel: "low",
+    }),
+    cut: worktree(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix",
+  context: ({ input }) => ({ ...input, summary: "", notes: "" }),
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  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: fixTree(context),
+          continue: true,
+        }),
+      },
+      on: { finish: { target: "checking", actions: assign({ summary: ({ event }) => event.summary }) } },
+    },
+    checking: {
+      invoke: { src: "checker", input: ({ context }) => ({ prompt: `Is this fix complete?\n\n${context.summary}` }) },
+      on: {
+        approve: "done",
+        request_changes: { target: "fixing", actions: assign({ notes: ({ event }) => event.notes }) },
+      },
+    },
+    fixing: {
+      invoke: {
+        src: "coder",
+        // 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: fixTree(context),
+          continue: true,
+          thinkingLevel: "high",
+        }),
+      },
+      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" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+The two Agents use the model of the tab. The `coding` and `fixing` states invoke the same Agent with different prompts,
+and only `fixing` sets a Dial. The checker's Turn has no `cwd`, because it has no Working tools.
+
+## One Turn
+
+**One Turn, from the state that invokes the Agent to the answer to its pick**
+
+- **Orchestrator**: the state that invokes the Agent
+- **Harness**: runs the Turn
+- **model provider**: the model of the Agent
+- Orchestrator → Harness: the definition, the Frame and the Dials
+- Harness → model provider: the instructions, the prompt and the Briefing
+- zero or more times
+  - model provider → Harness: a Working tool call
+  - Harness → model provider: its result
+- model provider → Harness: a pick from the Menu
+- Harness → Orchestrator: the pick, as an event
+- Orchestrator → Harness: the answer to the pick
+- Harness → model provider: the answer
+
+The [Briefing](../reference/glossary.md#briefing) is the text that jr2 itself adds. The loop can run zero times: a
+Menu-only Agent has no Working tools. The answer to the pick tells the model if its Turn is over.
+
+## How a Turn ends
+
+A Turn belongs to the state that invoked the Agent. When that state exits, the Turn is over, for any cause: a pick of
+the Agent, a [Gate](../reference/glossary.md#gate), a timer, or a `CANCEL`. jr2 then stops the work of the Agent on that
+Turn, and it does not prompt that Turn again.
+
+Usually, a pick of the Agent moves the Machine out of the state, and that ends the Turn. A pick whose target stays in
+the state does not end the Turn. Then the Agent can pick again, one pick at a time. [The Menu](the-menu.md) tells which
+picks an Agent can make, and when.
+
+An `agent()` actor never finishes, so an `onDone` on its invoke never runs. Give the Agent a pick, such as `finish`, and
+route on it.
+
+## Continue a conversation
+
+Without `continue`, each Turn starts a new conversation. The model knows only the instructions, the prompt and the
+Briefing. Thus the prompt must give all that the Agent needs to know.
+
+With `continue: true`, the Turn continues the one conversation of this Agent in this Machine instance. Each state of the
+Machine that invokes the Agent with `continue: true` uses the same conversation. A Turn without `continue` does not join
+it. Thus, in the example, `coding` sets `continue: true` too, so that `fixing` continues the conversation of `coding`.
+
+A Turn can join only a conversation that an earlier Turn started with `continue: true`. Thus, in a retry loop, put
+`continue: true` on each Turn, also on the first. If the first Turn has no `continue`, attempt 2 does not see attempt 1.
+A first Turn with `continue: true` gets no second start on a Runaway (see [When a Turn fails](#when-a-turn-fails)). jr2
+accepts this, so that attempt 2 sees attempt 1.
+
+`continue` is the literal `true`, not a `boolean`, so `continue: context.attempts > 0` is a type error. A state that
+always starts a clean conversation leaves `continue` off. Spread it into the input only when a state must start a clean
+conversation on some Turns only: `...(context.clean ? {} : { continue: true as const })`. A clean Turn does not start
+the continued conversation again: the next Turn with `continue: true` joins the earlier one.
+
+The conversation has no name that you write. jr2 makes its id from the run, the Machine instance and the Agent. Thus two
+Agents never share a conversation. Two workers of a [Pool](../reference/glossary.md#pool) never share one either,
+because each worker is a Machine instance of its own.
+
+When jr2 sends [`agent.fault`](../reference/mechanism-events.md#agent-fault) for a continued conversation, it does not
+continue that conversation again. The next Turn with `continue: true` starts a new one. Its prompt must then give the
+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 Briefing
+
+The Briefing is the text that jr2 itself gives the model. It tells facts that a correct Agent needs and cannot find for
+itself. It tells nothing about the task: the prompt tells the task. It has two parts:
+
+- **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.
+- **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)).
+
+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.
+
+## 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,
+`agent.fault`, to the Machine. The Machine decides what to do next: the state that invokes the Agent, or a state above
+it, routes `agent.fault`. `jr2 check` refuses a Machine without that route. In a [Chart](charts.md) the route is
+optional. jr2 recovers from these failures:
+
+- **The Harness or the model provider fails.** The Harness tries the model provider again during the Turn. When the Turn
+  still fails, jr2 sends `agent.fault`. When a Harness restarts while the state is busy, jr2 starts the Turn again on
+  the same conversation, and it sends no fault. If the restarted Harness cannot read the conversation, the Turn starts a
+  new one, and the Briefing tells the model.
+- **The Agent stops with no pick.** When the model stops and its Turn can still make a pick, jr2 prompts it again. It
+  does this two times at most. Then it sends `agent.fault`.
+- **The Turn is a [Runaway](../reference/glossary.md#runaway).**
+
+A Runaway is a Turn that does not end by itself. The Harness ends a Turn when it makes the same tool call four times in
+sequence, with the same arguments. It also ends a Turn of more than 256 [steps](../reference/glossary.md#step) on one
+prompt. A step is one tool call that starts while the Turn is live: a call of a Working tool, or a pick. A call that
+does not run is a step too, for example a call of a tool that does not exist. A call after a pick that ended the Turn is
+not a step. Then jr2 starts the Turn again one time, with the same prompt, on a new conversation. When that Turn is also
+a Runaway, jr2 sends `agent.fault`. jr2 does not start the Turn again when it continues a conversation, or when the
+Agent already made a pick in it. Then it sends `agent.fault` immediately.
+
+You cannot change these limits. They are a part of jr2.
+
+## Compaction
+
+A long Turn can fill the context window of the model. Then the model cannot answer, and the Turn fails. To prevent this,
+the Harness takes a [Compaction](../reference/glossary.md#compaction) during the Turn. Before it sends the conversation
+to the model, it examines the size of the context. When the context is near its limit, the Harness replaces the earlier
+part of the conversation with a summary. The recent part stays. The Turn continues with the smaller context.
+
+The summary comes from the model and the thinking level of the Turn. A Compaction changes only what the model sees. The
+history of the conversation keeps all that was said.
+
+You do not set when a Compaction occurs. jr2 calculates it from the context window and the output limit of the model. A
+model of a catalog provider, such as `anthropic`, has a known context window. A custom provider gets it from
+[`harness.provider.contextWindow`](../reference/config.md#harness-provider-contextwindow) or from the `contextWindow` of
+the model in `models`. A model with no context window gets no Compaction.
+
+## Rules
+
+- `model` is required in each definition. `jr2 up` refuses a model that is still `open`.
+- The input of a Turn has only `prompt`, `cwd`, `model`, `thinkingLevel` and `continue`. jr2 refuses a Turn with a
+  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 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.
+
+[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)
+- [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),
+  [`ThinkingLevel`](../reference/authoring-surface/type-thinkinglevel.md),
+  [`agent.fault`](../reference/mechanism-events.md#agent-fault) and
+  [`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-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
+  Frame, its Dials, and `continue`
+- [ADR-0024](../reference/decisions/0024-an-agents-turn-ends-with-the-state-that-asked-for-it.md): a Turn ends with the
+  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-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