@jr2/orchestrator 0.3.0 → 0.5.1

package/docs/guides/upgrade-the-kit-version.md

@@ -0,0 +1,240 @@
+---
+title: Upgrade the Kit version
+description: Move an Instance to a new Kit version. jr2 up converges it and updates the jr2 block in AGENTS.md.
+---
+
+# Upgrade the Kit version
+
+Move your [Instance](../reference/glossary.md#instance) to a new [Kit version](../reference/glossary.md#kit-version),
+and converge it.
+
+An Instance has one Kit version: the version of `@jr2/orchestrator` that it installs. `package.json` pins
+`@jr2/orchestrator` and `@jr2/cli` to that one exact version. To upgrade, you change the two pins to the new version,
+install, and run [`jr2 up`](../reference/cli.md#up). Each upgrade ends in `jr2 up`. It converges the cluster to the new
+version, and it updates the jr2 block in `AGENTS.md`, which your [Assistant](../reference/glossary.md#assistant) reads.
+
+In the commands on this page, `<version>` is the new Kit version, such as `0.4.1`, and `<old version>` is the version
+that the Instance has now.
+
+## Before you start
+
+- An Instance that you made with `jr2 init`, with its dependencies installed with npm.
+- The new version. To see the latest release, run `npm view @jr2/cli version`.
+- If the Instance sets [`kitRegistry`](../reference/config.md#kitregistry), write access to that registry. See
+  [Mirror the Kit images](mirror-the-kit-images.md).
+
+## See the Kit version now
+
+Run this command in the Instance folder:
+
+```sh
+jr2 version --local
+```
+
+```text
+…
+cli:       <old version>    <instance folder>/node_modules/@jr2/cli
+global:    <global version>    <global folder>
+kit:       <old version>    <instance folder>/node_modules/@jr2/orchestrator  ok
+instance:  my-instance  <instance folder>  (installed kit → ghcr.io/snapwich)
+node:      v24.18.0
+```
+
+- `cli` is the CLI that runs: the Instance's own `@jr2/cli`.
+- `global` is your global `jr2`. In an Instance folder, it runs the Instance's own `@jr2/cli`. This is the
+  [Handoff](../reference/glossary.md#handoff). Thus the version of the global `jr2` does not change what the Instance
+  runs.
+- `kit` is the Kit version. `ok` means that the CLI and the Instance use the same copy of `@jr2/orchestrator`, and that
+  this copy has the version of the CLI.
+
+`<global version>` is the version of your global `jr2`. `<instance folder>` and `<global folder>` are paths on your
+computer, and `node` gives your version of Node.js. The first line (`…`) is the `.env` line, when `.env` sets a variable
+that your shell does not set.
+
+## Install the new version
+
+Change the two pins in one command:
+
+```sh
+npm install --save-exact @jr2/orchestrator@<version> @jr2/cli@<version>
+```
+
+npm keeps `@jr2/orchestrator` in `dependencies` and `@jr2/cli` in `devDependencies`. `--save-exact` writes the version
+with no range, as `jr2 init` does.
+
+When the Instance also uses [`@jr2/machines`](../reference/machines.md), upgrade it in the same command. It must have
+the same version:
+
+```sh
+npm install --save-exact @jr2/orchestrator@<version> @jr2/cli@<version> @jr2/machines@<version>
+```
+
+> **Caution**
+>
+> Do not upgrade one of the packages alone. If you upgrade only `@jr2/orchestrator`, npm shows
+> `npm warn ERESOLVE overriding peer dependency` and installs it. The CLI and the Kit then have different versions, and
+> each command that reads the Instance, other than `jr2 version`, refuses. See the Rules.
+
+Then check the result:
+
+```sh
+jr2 version --local
+```
+
+```text
+…
+cli:       <version>    <instance folder>/node_modules/@jr2/cli
+global:    <global version>    <global folder>
+kit:       <version>    <instance folder>/node_modules/@jr2/orchestrator  ok
+instance:  my-instance  <instance folder>  (installed kit → ghcr.io/snapwich)
+node:      v24.18.0
+```
+
+The `cli` line and the `kit` line must show the same version, and the `kit` line must end in `ok`. When you upgraded
+only `@jr2/orchestrator`, the `kit` line gives the version of the `jr2` that runs:
+
+```text
+kit:       <version>    <instance folder>/node_modules/@jr2/orchestrator  MISMATCH — this jr2 (<old version>) runs against <version> (<instance folder>/node_modules/@jr2/orchestrator)
+```
+
+Then install the two packages again, with one version.
+
+Your global `jr2` can stay at its version. Its version matters only for `jr2 init` and for commands outside an Instance.
+In an Instance, it runs the Instance's own `@jr2/cli`. To upgrade it too, run `npm i -g @jr2/cli@<version>`.
+
+## Mirror the new images
+
+Do this step only when the Instance sets `kitRegistry`. The mirror does not have the images of the new version yet, and
+`jr2 up` never pushes them. In the Instance folder, run:
+
+```sh
+jr2 kit push <registry>
+```
+
+`<registry>` is the value of `kitRegistry`. The Instance's own `@jr2/cli` runs, so the command copies the images of the
+new version. [Mirror the Kit images](mirror-the-kit-images.md) shows its output.
+
+## Compare with the cluster
+
+`jr2 version`, with no `--local`, also reads what the cluster runs. Before the converge, it tells you that the cluster
+is at the old version:
+
+```sh
+jr2 version
+```
+
+```text
+…
+orchestrator:  <old version>  assembly 87cddbde1271  ghcr.io/snapwich/jr2-orchestrator:<old version>
+operator:      <old version>  ghcr.io/snapwich/jr2-operator:<old version>
+…
+skew:          deployed <old version> predates this kit <version> — `jr2 up` converges it
+```
+
+`87cddbde1271` is the hash of the current [Assembly](../reference/glossary.md#assembly), and your hash is different. The
+`orchestrator` line also gives the image of the [Orchestrator](../reference/glossary.md#orchestrator) that runs in the
+cluster.
+
+When the Orchestrator in the cluster is newer than the Kit version of the Instance, the `skew` line says
+``deployed <deployed version> is newer than this kit <version> — `jr2 up` would roll the orchestrator back; the operator is never downgraded``.
+`<deployed version>` is the version in the cluster.
+
+`jr2 version` does not refuse a Kit version mismatch. It shows `MISMATCH` on the `kit` line. When `package.json` pins a
+version that is not installed, the `kit` line ends in `; package.json pins <version> — reinstall`.
+
+## Converge
+
+```sh
+jr2 up
+```
+
+```text
+…
+AGENTS.md: jr2 block updated for <version>
+jr2 up — instance "my-instance" → context <context> / namespace my-instance
+typecheck: tsc --noEmit (the instance's own compiler)
+…
+images: installed kit — the published v<version> Harness, operator and Orchestrator, pulled from ghcr.io/snapwich
+…
+operator: applying v<version> (ghcr.io/snapwich/jr2-operator:<version>) over v<old version>
+…
+orchestrator: applying (image ghcr.io/snapwich/jr2-orchestrator:<version>)
+orchestrator: waiting for rollout
+orchestrator: verified — 1 pod(s) running ghcr.io/snapwich/jr2-orchestrator:<version>
+…
+assembly: publishing 36b7afe19f88 (no current Assembly)
+assembly: 36b7afe19f88 is current — workflows: <workflows>
+converged — `jr2 run <workflow>` when ready
+```
+
+`<context>` is the kubectl context of the cluster. `36b7afe19f88` is the hash of the Assembly for the new version, and
+your hash is different. The new Orchestrator does not load the Assembly of the old version, so the publish line says
+`no current Assembly`.
+
+`jr2 up` does these things for the upgrade:
+
+- **`AGENTS.md`.** Before the cluster work, it writes the docs index of the new Kit version between the two `jr2-docs`
+  markers. It changes nothing outside the markers. A converge that fails still updates the block. `jr2 up` does not
+  change an `AGENTS.md` that has no markers. When the markers are not a correct pair, `jr2 up` does not change the file,
+  and the converge continues: `warning: AGENTS.md: <reason>, so the jr2 block was not updated`.
+- **The typecheck.** It typechecks the Instance against the new Kit. A [Workflow](../reference/glossary.md#workflow)
+  that the new version does not accept stops the converge before the cluster changes. See the Rules.
+- **The images.** The nodes pull the [Kit images](../reference/glossary.md#kit-image) at the tag of the new version, the
+  image of the Orchestrator too. The pod of the Orchestrator starts again on it. A
+  [Sandbox Image](../reference/glossary.md#sandbox-image) does not change, because the runtime of jr2 is not in it.
+- **The Assembly.** The Assembly records its Kit version, so the hash changes. `jr2 up` publishes the Assembly after the
+  new Orchestrator runs. Until the publish, the new Orchestrator has no current Assembly, and it starts no run.
+- **The operator.** All the Instances on the cluster share one operator. `jr2 up` upgrades an older operator, so the
+  upgrade of one Instance upgrades the operator for each Instance on the cluster. `jr2 up` never downgrades the
+  operator. When a different Instance upgraded the operator to a later version, `jr2 up` keeps it:
+  `operator: leaving v<deployed version> (newer than this kit's v<version> — never downgraded)`.
+
+## What happens to the runs
+
+A live run holds the Assembly that it started under, and that Assembly is for the old Kit version. The new Orchestrator
+cannot load it. Thus the publish of the new Assembly marks each live run `drifted`, also a run that waits at a
+[Gate](../reference/glossary.md#gate). `jr2 status <run id>` gives the reason, with the hash of the Assembly and the two
+versions:
+`workflow "<workflow>": Assembly <hash> was published for Kit version <old version>; this Orchestrator is <version>`. To
+keep the result of a run, let it end before you converge, or cancel it. See
+[Machine shape and drift](../concepts/durable-runs.md#machine-shape-and-drift).
+
+A [Sandbox](../reference/glossary.md#sandbox) that runs keeps its pod, with the
+[Harness](../reference/glossary.md#harness) of the old version. `jr2 up` does not replace the pod, because the new pod
+would lose the commits that nobody pushed. A Sandbox that starts after the converge uses the new version.
+
+## Rules
+
+- `jr2 up` refuses an Instance that does not typecheck against the new Kit. It builds nothing and applies nothing. The
+  lines after the refusal are the errors of the compiler:
+  `refusing: this instance does not typecheck — nothing was built and nothing was applied`
+- Each verb that reads the Instance, other than `jr2 version`, refuses when the Instance and the CLI do not use the same
+  copy of `@jr2/orchestrator`, or when that copy does not have the version of the CLI. The refusal gives the two copies,
+  and its last line gives the fix:
+
+  ```text
+  error: Kit version mismatch — an Instance has one (ADR-0056):
+    @jr2/orchestrator resolves to <instance kit version> (<path>)
+    this jr2 (<cli version>) runs against <cli kit version> (<path>)
+    pin "@jr2/orchestrator" and "@jr2/cli" at ONE exact version in <instance folder>/package.json and reinstall
+  ```
+
+  `<instance kit version>` is the version of `@jr2/orchestrator` that the Instance installs. `<cli version>` is the
+  version of the `jr2` that runs, and `<cli kit version>` is the version of the `@jr2/orchestrator` beside that `jr2`.
+  When the Instance has no `@jr2/cli` of its own, the last line is
+  `add "@jr2/cli": "<instance kit version>" to devDependencies in <instance folder>/package.json and reinstall — the Instance's own jr2 then runs`.
+  When nothing is installed, the refusal says `@jr2/orchestrator does not resolve from <instance folder>`.
+
+## Read next
+
+- [Converge](../concepts/converge.md)
+- [Durable runs](../concepts/durable-runs.md)
+- [ADR-0056](../reference/decisions/0056-a-global-jr2-hands-off-to-the-instances-own-and-an-instance-has-one-kit-version.md):
+  the Handoff, and one Kit version for each Instance.
+- [ADR-0072](../reference/decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md): the
+  docs in the Kit, and the block in `AGENTS.md`.
+- [ADR-0069](../reference/decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md): an
+  Assembly names its Kit version, and the Orchestrator refuses any other.
+- [ADR-0030](../reference/decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md): a run whose Machine has
+  a different shape.
+- [Mirror the Kit images](mirror-the-kit-images.md)

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

@@ -0,0 +1,208 @@
+---
+title: Use a hosted provider or a gateway
+description: Give your Agents a model from a hosted provider, directly or through a gateway.
+---
+
+# Use a hosted provider or a gateway
+
+Give the [Agents](../reference/glossary.md#agent) of your [Instance](../reference/glossary.md#instance) a model from a
+hosted provider, such as Anthropic, directly or through a gateway.
+
+The [Harness](../reference/glossary.md#harness) has a model catalog. The catalog knows the providers, their models, and
+the limits of each model. An Agent names a catalog model as `<provider>/<modelId>`, such as `anthropic/<modelId>`. The
+config needs no provider entry for it. It needs only the key.
+
+## Hold the provider's key
+
+Add the key to the `secrets` list of `jr2.config.ts`:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  git: {
+    // The credentials that the cluster uses to clone and push. The token comes from JR2_GIT_TOKEN in .env.
+    credentials: [{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }],
+  },
+  // The model key. jr2 up gives it only to the Custodian of each pod whose Agents use Anthropic.
+  secrets: [{ name: "ANTHROPIC_API_KEY", value: process.env.ANTHROPIC_API_KEY }],
+});
+```
+
+Put the value in `.env`:
+
+```sh
+ANTHROPIC_API_KEY=<your key>
+```
+
+The `name` of the entry is the env var that the provider reads. When an Agent names a model of that provider, the key is
+a [Held secret](../reference/glossary.md#held-secret) in the pod of the Agent. The Harness container holds only its
+[Stand-in](../reference/glossary.md#stand-in). The [Custodian](../reference/glossary.md#custodian) of the pod puts the
+key into the requests to the provider.
+
+You do not say which pods get the key. jr2 finds them from the models that the Agents of each pod name.
+
+The name tells jr2 the provider and its host. For a key that goes to one host, `hosts` can stay out: the key then goes
+to that host only. Some of these names are:
+
+| Name                 | Provider     | Host                                |
+| -------------------- | ------------ | ----------------------------------- |
+| `ANTHROPIC_API_KEY`  | `anthropic`  | `api.anthropic.com`                 |
+| `OPENAI_API_KEY`     | `openai`     | `api.openai.com`                    |
+| `GEMINI_API_KEY`     | `google`     | `generativelanguage.googleapis.com` |
+| `MISTRAL_API_KEY`    | `mistral`    | `api.mistral.ai`                    |
+| `OPENROUTER_API_KEY` | `openrouter` | `openrouter.ai`                     |
+
+Some providers have no single host, because the address has a region or an account in it. Examples are
+`AWS_BEARER_TOKEN_BEDROCK`, `AZURE_OPENAI_API_KEY` and `GOOGLE_CLOUD_API_KEY`. For these, add the hosts to the entry,
+such as `hosts: ["<resource host>"]`.
+
+To keep the value in a Kubernetes Secret that you manage, write `valueFrom` in place of `value`:
+`valueFrom: { secretKeyRef: { name: "<secret>", key: "<key>" } }`. See [`secrets`](../reference/config.md#secrets) for
+each field.
+
+Run `jr2 up`:
+
+```sh
+jr2 up
+```
+
+For an Instance whose Agent has only the [Menu](../reference/glossary.md#menu) and uses Anthropic, you see these lines:
+
+```text
+…
+secret ANTHROPIC_API_KEY: Held in the Instance Harness
+the Instance Harness: Custodian holds ANTHROPIC_API_KEY (provider)
+held secret ANTHROPIC_API_KEY → api.anthropic.com (literal)
+provider: checking anthropic/claude-haiku-5-5 on the Instance Harness, through a Custodian that holds ANTHROPIC_API_KEY for api.anthropic.com
+provider: the check pod has up to 5 min to start, then up to 6 min for its model
+provider: the check pod is not running yet — custodian: PodInitializing
+provider: anthropic/claude-haiku-5-5 reachable, and it completed a tool call
+…
+```
+
+For an Agent in a [Workspace](../reference/glossary.md#workspace), the line names its
+[Workflow](../reference/glossary.md#workflow): `Workspace of workflow "<workflow>"`. For a Workspace inside a different
+Machine, the label continues with its route, such as ` → "<state>"`.
+
+Before `jr2 up` applies the operator and the Instance, it checks each catalog model that an Agent names. A pod in the
+cluster asks the provider for one tool call, through a Custodian that holds the key, as a
+[Turn](../reference/glossary.md#turn) asks. When the model id or the key is wrong, `jr2 up` stops with
+`error: provider preflight failed for model "<model>"`. The Instance, its Assembly and the operator do not change.
+[Fix a failed converge](fix-a-failed-converge.md#rules) gives the full error.
+
+## Send the calls through a gateway
+
+A gateway, such as LiteLLM, serves the API of a provider at a different address. The catalog keeps every fact about the
+models. Only the address of the calls changes.
+
+Change the `secrets` entry: read its value from `GATEWAY_API_KEY`, and add `paths`. Then add the gateway to
+[`harness.catalog`](../reference/config.md#harness-catalog), under the id of the provider:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  git: {
+    // The credentials that the cluster uses to clone and push. The token comes from JR2_GIT_TOKEN in .env.
+    credentials: [{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }],
+  },
+  // The gateway's key, held under the name that the provider reads. With no hosts, it goes to the host of the
+  // gateway below. paths keeps it away from the gateway's other routes.
+  secrets: [{ name: "ANTHROPIC_API_KEY", value: process.env.GATEWAY_API_KEY, paths: ["/v1/messages"] }],
+  harness: {
+    // Each call of an anthropic/<model> Agent goes to the gateway, not to api.anthropic.com.
+    catalog: { anthropic: { baseUrl: process.env.GATEWAY_URL ?? "" } },
+  },
+});
+```
+
+Put the address and the key of the gateway in `.env`:
+
+```sh
+GATEWAY_URL=https://<gateway>
+GATEWAY_API_KEY=<gateway key>
+```
+
+Obey these conditions:
+
+- `baseUrl` is the whole base URL that the provider's API adds its paths to. For `anthropic`, it is `https://<gateway>`,
+  and the API adds `/v1/messages`. For `openai`, it is `https://<gateway>/v1`.
+- `baseUrl` is `https://`, because the Custodian sends a key over TLS only.
+- The gateway serves each model under its catalog id. The Harness sends the catalog id, not a name that you choose.
+- The key has the name that the provider reads, here `ANTHROPIC_API_KEY`. With no `hosts`, the key goes to the host of
+  `baseUrl`, not to `api.anthropic.com`.
+
+`paths` limits the key to the path prefixes that the Agents use. A gateway key can often reach admin routes too, such as
+a route that makes new keys. An Agent could take a new key out of the pod. Thus give a gateway key `paths`.
+
+When the certificate of the gateway comes from a private CA, name the CA in
+[`harness.caBundle`](../reference/config.md#harness-cabundle). The guide
+[Use a local model](use-a-local-model.md#change-the-provider) shows `caBundle`.
+
+Run `jr2 up` again:
+
+```sh
+jr2 up
+```
+
+The key now goes to the gateway:
+
+```text
+…
+held secret ANTHROPIC_API_KEY → <gateway> (literal)
+provider: checking anthropic/claude-haiku-5-5 on the Instance Harness, through a Custodian that holds ANTHROPIC_API_KEY for <gateway>
+…
+provider: anthropic/claude-haiku-5-5 reachable, and it completed a tool call
+…
+```
+
+`<gateway>` is the host of `GATEWAY_URL`. When its port is not 443, the port follows the host, such as `<gateway>:8443`.
+
+A gateway that serves its own model names, or only `/v1/chat/completions`, is not a catalog provider. Declare it as a
+custom provider, with `harness.provider` and `apiKey`. The guide
+[Use a local model](use-a-local-model.md#serve-over-tls-with-a-key) shows how.
+
+## Rules
+
+`jr2 up` prints each refusal after `error: `.
+
+- `jr2 up` refuses an empty value: `secrets[<i>].value is empty — set <NAME> in .env (ADR-0059)`.
+- `jr2 up` refuses a key that a pod gets, but that has no value. A `.env` variable that is not set reads as no value:
+  `secrets[<i>] needs exactly one of value or valueFrom — <NAME> has neither, which is what an unset .env variable reads as: set <NAME> in .env, or reference a Secret with valueFrom: { secretKeyRef: { name, key } } (ADR-0059)`.
+- `jr2 up` refuses a key with no `hosts` when its name has no single host:
+  `secrets[<i>].hosts is absent, and <NAME> has no single default host — name where the value may go: hosts: ["gateway.example.com"] (ADR-0059)`.
+- `jr2 up` refuses `hosts` that leave out the host to which an Agent's calls go:
+  `secrets[<i>].hosts leaves out <host>, where pi sends every "<provider>/…" turn an Agent here names — each would arrive with the Stand-in and fail with 401. Add it, or drop hosts to take that default (ADR-0059)`.
+- `jr2 up` refuses a model key in `harness.env`, because the Agent can read that env:
+  `harness.env[<i>] sets <NAME>, a model key the Agent could read and take out of the pod — hold it instead: secrets: [<entry>] (ADR-0059)`.
+- `jr2 up` refuses a Secret or a ConfigMap that `harness.envFrom` names, when it carries a model key. `<kind>` is
+  `Secret` or `ConfigMap`:
+  `harness.envFrom[<i>] loads <kind> "<name>", which carries <NAME> — a model key the Agent could read. Hold it instead: secrets: [{ name: "<NAME>", valueFrom: { secretKeyRef: { name: "<secret>", key: "<NAME>" } } }], and drop the key from that <kind> (ADR-0059)`.
+- `jr2 up` refuses a `valueFrom` that names a Secret that does not exist:
+  `secrets[<i>].valueFrom names Secret "<name>", which does not exist in the instance's namespace — create it first: kubectl create secret generic <name> --from-literal=<key>=... (ADR-0019, ADR-0059)`.
+- `jr2 up` refuses a `harness.catalog` key that is not a catalog provider with a known key:
+  `harness.catalog.<id>: "<id>" is not a pi catalog provider jr2 knows a key for — the catalog ids are <ids> (ADR-0059)`.
+- `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)`.
+- 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)`.
+- The Harness refuses a model that is not in the catalog when it admits the Turn:
+  `harness admission failed (400): agent "<agent>": model "<provider>/<modelId>" resolves to nothing — not in pi's catalog, and no custom provider "<provider>" is configured (ADR-0018)`.
+
+## Read next
+
+- [Secrets and trust](../concepts/secrets-and-trust.md): Held secrets, Stand-ins and the Custodian.
+- [Connect a model](../get-started/connect-a-model.md): the tutorial step that adds the Anthropic key.
+- [Use a local model](use-a-local-model.md): a model that you serve yourself.
+- [`secrets`](../reference/config.md#secrets) and [`harness.catalog`](../reference/config.md#harness-catalog) in the
+  `jr2.config.ts` Reference.
+- [ADR-0059](../reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md): the Custodian
+  holds the keys, and a catalog provider can move to a gateway.
+- [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md): one `secrets`
+  list, and a secret goes where something names it.
+- [ADR-0018](../reference/decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md): an Agent names
+  its model.