@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/guides/write-a-hook-kind.md

@@ -0,0 +1,238 @@
+---
+title: Write a Hook kind
+description: Write the kind of a service that jr2 ships no kind for, declare a Hook of it, and hear it at a Gate.
+---
+
+# Write a Hook kind
+
+Write a [Hook kind](../reference/glossary.md#hook-kind) for an outside service that jr2 ships no kind for, and that
+[`webhook()`](../reference/hooks.md#webhook) cannot read.
+
+`webhook()` reads a service that sends JSON and signs only the raw body. Write a kind with
+[`defineHookKind()`](../reference/hooks.md#definehookkind) when the service does one of these:
+
+- It signs more than the body, such as a time and the body.
+- It sends a body that is not JSON, such as a form.
+- It sends a handshake that needs an answer.
+- A person reads the answer, as in a chat command.
+
+The example is a kind for Stripe. Stripe signs `<t>.<raw body>` with the signing secret of the endpoint, and sends the
+time `t` and the signature in the header `Stripe-Signature: t=<seconds>,v1=<hex>`. The type of the event is the event
+key, and the id of the event is the id of the delivery.
+
+The interface of a kind is `@jr2/orchestrator/hooks`. It is part of `@jr2/orchestrator`, so your
+[Instance](../reference/glossary.md#instance) installs nothing more.
+
+## Write the kind
+
+Save the kind as `hooks/stripe.ts`, beside `workflows/`. A kind is not a Workflow, so it does not go in `workflows/`:
+
+```ts
+import { z } from "zod";
+import { defineHookKind, json } from "@jr2/orchestrator/hooks";
+
+// The payload of each event key that a handler hears. Name only the fields that the handlers read:
+// a loose object keeps the other fields, so a new field from Stripe breaks nothing.
+const invoice = z.looseObject({
+  data: z.looseObject({ object: z.looseObject({ id: z.string(), customer: z.string() }) }),
+});
+
+export const stripeEvents = {
+  "invoice.paid": invoice,
+  "invoice.payment_failed": invoice,
+};
+
+export const stripe = defineHookKind({
+  api: 1,
+  id: "stripe",
+  events: stripeEvents,
+  verify: {
+    mac: {
+      alg: "sha256",
+      // Stripe-Signature: t=<seconds>,v1=<hex>. Stripe signs "<t>.<raw body>". The door checks t
+      // against its clock, and the Instance Effector checks the HMAC.
+      signed: (req) => {
+        const fields = (req.headers["stripe-signature"] ?? "").split(",").map((f) => f.split("="));
+        const t = fields.find(([name]) => name === "t")?.[1];
+        const v1 = fields.find(([name]) => name === "v1")?.[1];
+        if (!t || !/^\d+$/.test(t) || !v1) return { unsigned: "no t and v1 in the Stripe-Signature header" };
+        return { bytes: [t, ".", req.body], signature: { hex: v1 }, at: Number(t) };
+      },
+    },
+  },
+  // The event's type is the event key, and the event's id is the id of the delivery.
+  read: (req) => {
+    const event = json(req) as { readonly id?: unknown; readonly type?: unknown } | null;
+    if (typeof event?.id !== "string" || typeof event.type !== "string") {
+      throw new Error("the body is not a Stripe event");
+    }
+    return { key: event.type, id: event.id, payload: event };
+  },
+});
+
+// The kind's id and payloads, for the types of the handlers.
+declare module "@jr2/orchestrator/hooks" {
+  interface HookKinds {
+    stripe: typeof stripe;
+  }
+}
+```
+
+A kind has these parts:
+
+- `api: 1`: the version of the interface of a kind.
+- `id`: the key of the kind in the `hooks` of a Gate or a Source. It is lowercase letters, digits and `-`, and it starts
+  with a letter. One id is one kind in an Assembly.
+- `events`: a zod schema for each event key that a handler can hear. The door parses each payload with the schema of its
+  key before a handler gets it. Use `z.looseObject`, and name only the fields that the handlers read. A key that ends in
+  `.*` gives the schema of each key with that prefix.
+- `verify`: one of `mac`, `token` or `ed25519`. For `mac` and `ed25519`, `signed` gives the bytes that the service
+  signed, the signature without its prefix, and `at`, the time of the delivery in seconds. Give `at` only when the
+  signature covers it. The door refuses a time that is more than 300 seconds from its clock. When the request does not
+  have a signature, give `{ unsigned: "<why>" }`. For `token`, give the header of the token.
+- `read`: the request after the verifier, as a delivery or as a handshake. A delivery has the event key, the id, the
+  payload, and `onBehalfOf` when the service names the party that acted. A handshake is `{ handshake: { body } }`, and
+  goes to no handler. A throw is the status 400.
+
+A kind whose answer a person reads also has `answer`, the envelope of the text, and `maxText`, the limit of the service
+on its length. Its `read` gives `readBy: "person"`. When the answer gives a follow-up post, `posts` lists the URLs that
+the post can go to. See the [`slack` kind](../reference/hooks.md#slack).
+
+A kind is pure and synchronous: it does no I/O, gives no Promise, and reads no clock. It never gets the secret. The
+`declare module` block adds the kind to `HookKinds`, so that the handlers of a Gate or a Source get the types of its
+payloads.
+
+## Declare a Hook of the kind
+
+Add the Hook to `jr2.config.ts`, and its secret to the `secrets` list:
+
+```ts
+import { defineConfig, secret } from "@jr2/orchestrator";
+import { stripe } from "./hooks/stripe.ts";
+
+export default defineConfig({
+  // The signing secret of the Stripe endpoint. jr2 up places it in the Instance Effector.
+  secrets: [{ name: "STRIPE_HOOK", value: process.env.STRIPE_HOOK }],
+  hooks: {
+    // POST /hooks/billing. The Hook may answer the Gates of dunning alone.
+    billing: stripe({ secret: secret("STRIPE_HOOK"), may: { answer: ["dunning"] } }),
+  },
+});
+```
+
+The kind is also the constructor of its Hooks. It takes the credential and `may.answer`. For a `mac` kind,
+[`jr2 up`](../reference/cli.md#up) puts the secret in the
+[Instance Effector](../reference/glossary.md#instance-effector) only, which checks each signature. Put the value in
+`.env`:
+
+```sh
+STRIPE_HOOK=<signing secret>
+```
+
+`<signing secret>` is the signing secret that Stripe shows for the endpoint. Give the endpoint the URL
+`https://<host>/hooks/billing`.
+
+## Hear it at a Gate
+
+Import the kind's types in the workflow module, and give the Gate slot a handler for each event key that it hears:
+
+```ts
+import { z } from "zod";
+import { defineEvent, fail, gate, jr2Setup } from "@jr2/orchestrator";
+import type {} from "../hooks/stripe.ts";
+
+const paid = defineEvent({
+  name: "paid",
+  description: "The customer paid the invoice.",
+  input: z.object({}),
+});
+
+// The Gate hears the stripe kind. A payment of another invoice is not for this Gate.
+const payment = gate({
+  meta: z.object({ invoice: z.string() }),
+  delivers: [paid],
+  hooks: {
+    stripe: {
+      "invoice.paid": ({ payload, meta }) => (payload.data.object.id === meta.invoice ? { type: "paid" } : undefined),
+    },
+  },
+});
+
+export const machine = jr2Setup({
+  types: {} as { input: { invoice: string }; context: { invoice: string } },
+  events: [paid],
+  actors: { payment, fail: fail() },
+}).createMachine({
+  id: "dunning",
+  input: z.object({ invoice: z.string() }),
+  context: ({ input }) => ({ invoice: input.invoice }),
+  initial: "waiting",
+  states: {
+    waiting: {
+      invoke: { src: "payment", input: ({ context }) => ({ meta: { invoice: context.invoice } }) },
+      on: { paid: "paid" },
+      // After seven days with no payment, the run stops waiting. A lost delivery cannot stop the
+      // run for longer than that.
+      after: { 604800000: "unpaid" },
+    },
+    paid: { type: "final" },
+    // Not a final state: the run ends `failed`, with the reason.
+    unpaid: { invoke: { src: "fail", input: () => ({ reason: "the invoice is not paid after seven days" }) } },
+  },
+});
+```
+
+A handler for a key that the kind does not give does not compile, and a handler reads only the fields that the schema
+names. [Answer a Gate from a forge](answer-a-gate-from-a-forge.md) tells the other parts of a Gate slot, such as the
+look. A Source hears a kind in the same way ([Start a run for each alert](start-a-run-for-each-alert.md)).
+
+## Put the kind in a package
+
+A kind in a package of its own uses the same interface. Its package has a peer dependency on `@jr2/orchestrator` and
+states `api: 1`, and its `jr2.config.ts` and its workflow modules import it as they import a local file. `jr2 up`
+bundles the kind into the [Assembly](../reference/glossary.md#assembly). jr2 finds no kind in a folder, and loads none
+while the Instance runs.
+
+## Rules
+
+- `defineHookKind()` refuses an `id` of another form:
+  `a Hook kind's id is lowercase letters, digits and "-", and starts with a letter: <id>`
+- `defineHookKind()` refuses an `api` that it does not know:
+  `Hook kind <id> states api <api>; this @jr2/orchestrator/hooks knows api 1 only`
+- `defineHookKind()` refuses an event key with no zod schema: `Hook kind <id>: the event key <key> has no zod schema`
+- `defineHookKind()` refuses a `verify` that is not one of the three:
+  `Hook kind <id>: verify is one of mac, ed25519 or token`
+- `defineHookKind()` refuses a `mac` verifier without an algorithm or a `signed` function:
+  `Hook kind <id>: a mac verifier has an alg (sha256, sha1, sha512) and a signed function`
+- `defineHookKind()` refuses a `token` header that is not lowercase:
+  `Hook kind <id>: a token verifier names its header in lowercase`
+- `defineHookKind()` refuses a `posts` entry that is not an `https://` URL that ends in `/`:
+  `Hook kind <id>: a posts entry is an https:// url that ends in "/": <entry>`
+- `defineHookKind()` refuses a `maxText` that is not a positive integer: `Hook kind <id>: maxText is a positive integer`
+- The constructor of a `mac` or `token` kind refuses a credential that is not a named secret:
+  `a <id> Hook takes secret: a named secret, secret("NAME")`
+- The constructor of an `ed25519` kind refuses a public key that is not 64 hex characters:
+  `a <id> Hook takes publicKey: the Ed25519 public key in hex (64 characters)`
+- The constructor refuses a `may.answer` that is not `"all"` or a list of Workflow names:
+  `a <id> Hook's may.answer is "all" or a list of Workflow names`
+- Two kinds with one id do not compile (`Subsequent property declarations must have the same type`), and the config load
+  refuses them:
+  `<file> at hooks: two different Hook kinds have the id <id>: one id is one kind in an Assembly (ADR-0078)`
+- The type of `read` refuses `readBy: "person"` in a kind that has no `answer`.
+- A request that `signed` gives `unsigned` for, or whose signature does not match, gets 401. A request that `read`
+  throws for gets 400: `the <kind> kind cannot read the delivery: <error>`
+- `jr2 up` refuses a `mac` Hook whose secret is not in the `secrets` list:
+  ``hooks.<name> names secret("<NAME>"), which the `secrets` list does not hold — add it: secrets: [{ name: "<NAME>", value: process.env.<NAME> }] (ADR-0068)``
+
+## Read next
+
+- [Callers and Hooks](../concepts/callers-and-hooks.md)
+- [Answer a Gate from a forge](answer-a-gate-from-a-forge.md) and
+  [Start a run for each alert](start-a-run-for-each-alert.md)
+- Reference: [`@jr2/orchestrator/hooks`](../reference/hooks.md), [`HookKind`](../reference/hooks.md#type-hookkind),
+  [`Signed`](../reference/hooks.md#type-signed), [`Delivery`](../reference/hooks.md#type-delivery) and the
+  [`hooks`](../reference/config.md#hooks) field of `jr2.config.ts`
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): a
+  Hook kind, the three verifiers, and the window
+- [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md): the Instance
+  Effector holds a `mac` secret

package/docs/guides/write-a-tool-as-an-mcp-server.md

@@ -0,0 +1,351 @@
+---
+title: Write a tool as an MCP server
+description: Write a small MCP server in TypeScript, put it in the Sandbox Image, and give its tool to an Agent.
+---
+
+# Write a tool as an MCP server
+
+Write a tool for your [Agents](../reference/glossary.md#agent) as a small MCP server in TypeScript, put it in the
+[Sandbox Image](../reference/glossary.md#sandbox-image), and give it to an Agent as a stdio server.
+
+jr2 has no tool API of its own. A tool that you write is an MCP server: a remote server that you run yourself, or a
+stdio server, which is a program in the Sandbox Image. An Agent in a [Sandbox](../reference/glossary.md#sandbox) gets
+each tool of a stdio server as one of its [MCP tools](../reference/glossary.md#mcp-tools).
+
+The server on this page has one tool, `next_version`. It gives the next version number after a release. It uses only the
+modules of Node, so it needs no package. Save it as `images/default/semver-mcp.ts` in your
+[Instance](../reference/glossary.md#instance), beside the `Dockerfile` that `jr2 init` wrote:
+
+```ts
+// A stdio MCP server with one tool, next_version. It reads one JSON-RPC message on each line of
+// stdin, and writes each answer as one line on stdout. Node runs this file as it is.
+import { createInterface } from "node:readline";
+
+type Message = { id?: number | string; method?: string; params?: { name?: string; arguments?: unknown } };
+
+const tools = [
+  {
+    name: "next_version",
+    description: "The next version number after a release. Give the current version and the kind of change.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        version: { type: "string", description: "The current version, such as 1.4.2." },
+        change: { type: "string", enum: ["major", "minor", "patch"] },
+      },
+      required: ["version", "change"],
+    },
+  },
+];
+
+// The tool itself: a function of its arguments.
+function nextVersion(version: string, change: string): string {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (match === null) throw new Error(`${version} is not a version such as 1.4.2`);
+  const [major, minor, patch] = match.slice(1).map(Number) as [number, number, number];
+  if (change === "major") return `${major + 1}.0.0`;
+  if (change === "minor") return `${major}.${minor + 1}.0`;
+  if (change === "patch") return `${major}.${minor}.${patch + 1}`;
+  throw new Error(`${change} is not major, minor or patch`);
+}
+
+function call(name: string | undefined, args: unknown): object {
+  const { version, change } = (args ?? {}) as { version?: unknown; change?: unknown };
+  if (name !== "next_version") return { error: { code: -32602, message: `Unknown tool: ${name}` } };
+  try {
+    const text = nextVersion(String(version), String(change));
+    return { result: { content: [{ type: "text", text }] } };
+  } catch (err) {
+    // A tool's own error: the model reads the text, and the call is an error.
+    return { result: { content: [{ type: "text", text: (err as Error).message }], isError: true } };
+  }
+}
+
+function handle(message: Message): object {
+  switch (message.method) {
+    case "initialize":
+      return {
+        result: {
+          protocolVersion: "2025-11-25",
+          capabilities: { tools: {} },
+          serverInfo: { name: "semver", version: "1.0.0" },
+        },
+      };
+    case "tools/list":
+      return { result: { tools } };
+    case "tools/call":
+      return call(message.params?.name, message.params?.arguments);
+    default:
+      return { error: { code: -32601, message: `Method not found: ${message.method}` } };
+  }
+}
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  if (line.trim() === "") return;
+  const message = JSON.parse(line) as Message;
+  // A notification has no id, and gets no answer.
+  if (message.id === undefined) return;
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, ...handle(message) })}\n`);
+});
+```
+
+## What the server does
+
+A stdio server reads one JSON-RPC message on each line of its stdin. It writes each answer as one line on its stdout. It
+answers these methods:
+
+- `initialize`: the revision of MCP that it speaks, `2025-11-25`, and `capabilities: { tools: {} }`.
+- `tools/list`: its tools. Each tool has a `name`, a `description` and an `inputSchema`, which is JSON Schema. The model
+  reads the description and the schema.
+- `tools/call`: the result of one call, as `content`. A tool that fails gives a result with `isError: true` and the
+  reason as text. The model reads the reason.
+
+A message with no `id` is a notification, such as `notifications/initialized`, and gets no answer. A method that the
+server does not have gets the JSON-RPC error `-32601`. Write only messages on stdout: the Harness reads each line as a
+message, and drops a line that is not one. The Harness does not read stderr.
+
+## Try the server on your computer
+
+Send it the messages that the Harness sends, with Node 24 or later:
+
+```sh
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"next_version","arguments":{"version":"1.4.2","change":"minor"}}}' \
+  '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"next_version","arguments":{"version":"x","change":"minor"}}}' \
+  | node images/default/semver-mcp.ts
+```
+
+```text
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"semver","version":"1.0.0"}}}
+{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"next_version","description":"The next version number after a release. Give the current version and the kind of change.","inputSchema":{"type":"object","properties":{"version":{"type":"string","description":"The current version, such as 1.4.2."},"change":{"type":"string","enum":["major","minor","patch"]}},"required":["version","change"]}}]}}
+{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"1.5.0"}]}}
+{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"x is not a version such as 1.4.2"}],"isError":true}}
+```
+
+The notification gets no line. The last call is the tool's own error.
+
+## Put the server in the Sandbox Image
+
+Copy the file into the image. The folder of the `Dockerfile` is the context of the build, so `COPY` finds the file
+there:
+
+```dockerfile
+FROM node:24-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends git ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+# Your agents' toolchain goes here — compilers, CLIs, language servers, dotfiles.
+
+# The MCP server. Node 24 runs a .ts file as it is, so the image needs no build step.
+COPY semver-mcp.ts /opt/tools/semver-mcp.ts
+```
+
+The example does not show the comments at the start of the file. Keep them in your file. Node 24 runs a `.ts` file that
+has only types that it can remove, so the image needs no build step. For an MCP server from a package, install the
+package at a fixed version in the `Dockerfile` instead, such as `RUN npm install -g <package>@<version>`.
+
+[`jr2 up`](../reference/cli.md#up) builds the image, because a file in its folder changed.
+[Add tools to the Sandbox](add-tools-to-the-sandbox.md) tells how `jr2 up` builds and loads it.
+
+## Declare the server and give it to an Agent
+
+Declare the server in the [`mcp`](../reference/config.md#mcp) block of `jr2.config.ts`, beside the fields that are
+there. `command` and `args` are the program and its arguments in the image:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  // A stdio server: a program of the Sandbox Image. The Harness starts it for each conversation.
+  mcp: { semver: { command: "node", args: ["/opt/tools/semver-mcp.ts"] } },
+});
+```
+
+Then name the server in the `mcp` list of an Agent that works in a Sandbox. In this
+[Workflow](../reference/glossary.md#workflow), a releaser reads the changes of a release, asks `next_version` for the
+next version, and picks `decided`. Save the file as `workflows/next-version.ts`:
+
+**Anthropic**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+
+const decided = defineEvent({
+  name: "decided",
+  description: "Call this with the next version, after the next_version tool gave it.",
+  input: z.object({ version: z.string().describe("The next version, such as 1.5.0.") }),
+});
+
+const runInput = z.object({
+  version: z.string().describe("The current version, such as 1.4.2."),
+  changes: z.string().describe("The changes since that version, one on each line."),
+});
+// `never`: the Workspace has no Repo Slot.
+type BodyInput = Workspaced<z.infer<typeof runInput>, never>;
+type Ctx = BodyInput & { next?: string };
+
+const body = jr2Setup({
+  types: {} as { context: Ctx; input: BodyInput; output: { version: string } },
+  events: [decided],
+  actors: {
+    releaser: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You decide how large a release is: major, minor or patch. You use semantic versioning.",
+      workspace: "read",
+      // A stdio server takes no tools list: the Agent gets every tool of the server.
+      mcp: [{ server: "semver" }],
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "next-version",
+  context: ({ input }) => input,
+  on: { "agent.fault": ".failed", "workspace.lost": ".failed" },
+  initial: "deciding",
+  states: {
+    // The Turn frames no `cwd`, so it works in /work. The server starts there too.
+    deciding: {
+      invoke: {
+        src: "releaser",
+        input: ({ context }) => ({
+          prompt: `The current version is ${context.version}. The changes are:\n${context.changes}`,
+        }),
+      },
+      on: { decided: { target: "done", actions: assign({ next: ({ event }) => event.version }) } },
+    },
+    done: { type: "final" },
+    // Not a final state: the run ends `failed`, with the reason.
+    failed: { invoke: { src: "fail", input: { reason: "the releaser could not decide" } } },
+  },
+  output: ({ context }) => ({ version: context.next ?? "" }),
+});
+
+// No `repos`: the Workspace clones nothing. The Sandbox Image holds the server.
+export const machine = workspace(body, { input: runInput });
+```
+
+**Local**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+
+const decided = defineEvent({
+  name: "decided",
+  description: "Call this with the next version, after the next_version tool gave it.",
+  input: z.object({ version: z.string().describe("The next version, such as 1.5.0.") }),
+});
+
+const runInput = z.object({
+  version: z.string().describe("The current version, such as 1.4.2."),
+  changes: z.string().describe("The changes since that version, one on each line."),
+});
+// `never`: the Workspace has no Repo Slot.
+type BodyInput = Workspaced<z.infer<typeof runInput>, never>;
+type Ctx = BodyInput & { next?: string };
+
+const body = jr2Setup({
+  types: {} as { context: Ctx; input: BodyInput; output: { version: string } },
+  events: [decided],
+  actors: {
+    releaser: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You decide how large a release is: major, minor or patch. You use semantic versioning.",
+      workspace: "read",
+      // A stdio server takes no tools list: the Agent gets every tool of the server.
+      mcp: [{ server: "semver" }],
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "next-version",
+  context: ({ input }) => input,
+  on: { "agent.fault": ".failed", "workspace.lost": ".failed" },
+  initial: "deciding",
+  states: {
+    // The Turn frames no `cwd`, so it works in /work. The server starts there too.
+    deciding: {
+      invoke: {
+        src: "releaser",
+        input: ({ context }) => ({
+          prompt: `The current version is ${context.version}. The changes are:\n${context.changes}`,
+        }),
+      },
+      on: { decided: { target: "done", actions: assign({ next: ({ event }) => event.version }) } },
+    },
+    done: { type: "final" },
+    // Not a final state: the run ends `failed`, with the reason.
+    failed: { invoke: { src: "fail", input: { reason: "the releaser could not decide" } } },
+  },
+  output: ({ context }) => ({ version: context.next ?? "" }),
+});
+
+// No `repos`: the Workspace clones nothing. The Sandbox Image holds the server.
+export const machine = workspace(body, { input: runInput });
+```
+
+The releaser uses the model of the tab. The model reads the tool as `mcp__semver__next_version`. A stdio server takes no
+`tools` list: the Agent gets each tool of the server. Run `jr2 up`, then start a run:
+
+```sh
+jr2 run next-version --input '{"version":"1.4.2","changes":"Add the --json flag.\nFix the help text."}'
+```
+
+## What the server can reach
+
+A stdio server is [Workspace code](../reference/glossary.md#workspace-code), as the Agent's shell is:
+
+- The Harness starts it through the spawner, inside the Landlock confinement of the Sandbox, in the directory of the
+  [Turn](../reference/glossary.md#turn). It cannot read `/run/jr2`, and it cannot read the control Stand-in of the
+  Harness.
+- Its env is the env of the confined programs. It holds only the [Stand-ins](../reference/glossary.md#stand-in) of the
+  [Held secrets](../reference/glossary.md#held-secret) that the
+  [`workspace()`](../reference/authoring-surface/workspace.md) lists under `secrets`. A server that calls an API sends
+  the Stand-in, and the [Custodian](../reference/glossary.md#custodian) puts the value in its place.
+- It runs as one process for each conversation of the Agent, from the first Turn to the end of the conversation. When it
+  stops, its call fails, and the next call starts it again.
+
+The Agent's other programs run in the same confinement. They can trace the server and write to its stdin. Thus trust the
+result of the server as much as the output of a command that the Agent runs, and no more.
+[Secrets and trust](../concepts/secrets-and-trust.md#confined-programs) tells what the confinement stops.
+
+A Menu-only Agent cannot use a stdio server: its Turns run on the
+[Instance Harness](../reference/glossary.md#instance-harness), where no Workspace code runs. An `mcp` Effect cannot use
+one either. To use a tool from those, run it as a remote server, and declare its `url`.
+
+## Rules
+
+- At the first Turn of a conversation, the server must answer `initialize` and `tools/list`. When it fails, the Turn
+  fails before the model reads anything, and the Machine gets
+  [`agent.fault`](../reference/mechanism-events.md#agent-fault) with the reason `<server> did not answer: <reason>`.
+- A line on stdout that is longer than 16 MiB stops the server.
+- `jr2 up` refuses a `tools` list on a stdio server:
+  `refusing: workflow "<workflow>": Agent "<slot>" gives a tools list for the stdio MCP server "<server>" — a stdio server takes none: the Agent gets every tool, because the server runs as Workspace code, and a list would guard nothing. Write { server: "<server>" } (ADR-0079)`
+- `jr2 up` refuses a stdio server on a Menu-only Agent:
+  `refusing: workflow "<workflow>": Agent "<slot>" has workspace: "none" and names the stdio MCP server "<server>" — a stdio server runs as Workspace code, inside a Sandbox's confinement, and a "none" Agent's Turns run on the Instance Harness, which has none: name a remote server, or give the Agent a Workspace (ADR-0079, ADR-0031)`
+- `jr2 up` does not check the tools of a stdio server, because the program runs only in a Sandbox.
+- A tool whose name, as `mcp__<server>__<tool>`, has a character other than letters, digits, `_` and `-`, or more than
+  128 characters, is not given to the model. The Harness writes one line in its log:
+  `the MCP server <server> lists the tool "<tool>", and "mcp__<server>__<tool>" does not match ^[A-Za-z0-9_-]{1,128}$: the tool is not offered (ADR-0079)`
+
+[Give an Agent MCP tools](give-an-agent-mcp-tools.md#rules) gives the refusals of the `mcp` block.
+
+## Read next
+
+- [Agents and Turns](../concepts/agents-and-turns.md#the-mcp-tools): the MCP tools of an Agent.
+- [Workspaces](../concepts/workspaces.md): the Sandbox Image.
+- [Give an Agent MCP tools](give-an-agent-mcp-tools.md): remote servers, and the allowlist.
+- Reference: [`mcp`](../reference/config.md#mcp) and
+  [`AgentMcpServer`](../reference/authoring-surface/type-agentmcpserver.md).
+- [ADR-0079](../reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md):
+  MCP is the one contract for tools, and a stdio server is Workspace code.
+- [ADR-0076](../reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md): the
+  confinement of Workspace code.

package/docs/guides/write-a-workflow.md

@@ -184,7 +184,7 @@ jr2 run rollout --input '{"service":"billing","version":"1.4.0"}'
 
 ```text
 → context kind-jr2 / namespace my-instance
-run b7c3d871-e3ae-46af-8bb3-774913bcd6cc (rollout) — attached
+run a5bafe11-80bf-426b-905f-6fb19952c093 (rollout) — attached
   → active "canary"
 ```
 
@@ -198,7 +198,7 @@ jr2 send <run id> --gate canary --event roll_back --input '{"reason":"The error
 
 ```text
 → context kind-jr2 / namespace my-instance
-delivered roll_back to gate "canary" on b7c3d871-e3ae-46af-8bb3-774913bcd6cc
+delivered roll_back to gate "canary" on a5bafe11-80bf-426b-905f-6fb19952c093
 ```
 
 In the first terminal, the run ends. A `roll_back` ends the rollout, so the run ends `failed`, with the reason of the
@@ -210,7 +210,7 @@ that jr2 added, and the `reason`:
   → active "rolledBack"
   → failed "rolledBack"
 failed: The error rate went up.
-{"runId":"b7c3d871-e3ae-46af-8bb3-774913bcd6cc","workflow":"rollout","instanceId":"b79e7e8b-6289-4dbc-a9a3-be945f8b1173","status":"failed","value":"rolledBack","context":{"service":"billing","version":"1.4.0","canaryPercent":10,"instanceId":"b79e7e8b-6289-4dbc-a9a3-be945f8b1173","reason":"The error rate went up."},"children":[],"waiting":[],"held":[],"assembly":"83858e28b054","output":{"reason":"The error rate went up."}}
+{"runId":"a5bafe11-80bf-426b-905f-6fb19952c093","workflow":"rollout","instanceId":"f779766e-49c3-49ad-92bd-10208710843b","startedAt":"2026-11-06T19:17:57.979Z","startedBy":{"kind":"caller","via":"token","name":"instance","onBehalfOf":"kubernetes-admin"},"status":"failed","value":"rolledBack","context":{"service":"billing","version":"1.4.0","canaryPercent":10,"instanceId":"f779766e-49c3-49ad-92bd-10208710843b","reason":"The error rate went up."},"children":[],"waiting":[],"held":[],"answers":[{"gate":"canary","type":"roll_back","at":"2026-11-06T19:18:06.269Z","answeredBy":{"via":"token","name":"instance","onBehalfOf":"kubernetes-admin"}}],"assembly":"bedde6f8c51c","output":{"reason":"The error rate went up."}}
 ```
 
 Your instance id and your `assembly` hash are different.
@@ -218,12 +218,22 @@ Your instance id and your `assembly` hash are different.
 [Start a run](start-a-run.md) gives the other ways to start a run. [Answer a Gate](answer-a-gate.md) gives the other
 ways to answer one.
 
-## Put shared code in a file that jr2 does not register
+## Lay out the Instance
+
+jr2 finds the Workflows in `workflows/`, and `jr2.config.ts` declares the rest. Other code goes in folders of your own
+choice. `jr2 up` bundles the whole folder of the Instance, so a Workflow and the config can import from each folder:
+
+```
+my-instance/
+  jr2.config.ts    the config: secrets, Hooks, Callers, the Harness
+  workflows/       one .ts file is one Workflow
+  hooks/           your Hook kinds
+  lib/             code that two Workflows share
+```
 
 jr2 registers each `.ts` file in `workflows/`, also a file that a different Workflow imports. It does not register a
-file whose name starts with `_`, or a `.d.ts` file. Thus put the code that two Workflows share in a file such as
-`workflows/_events.ts`, or outside `workflows/`. Import it with its `.ts` extension:
-`import { promote } from "./_events.ts";`.
+file whose name starts with `_`, or a `.d.ts` file. Thus put the code that two Workflows share outside `workflows/`,
+such as in `lib/events.ts`. Import it with its `.ts` extension: `import { promote } from "../lib/events.ts";`.
 
 ## Rules