@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/concepts/architecture.md

@@ -0,0 +1,243 @@
+---
+title: Architecture
+description: What runs on your computer, in the cluster and in a Sandbox, and which part does what.
+---
+
+# Architecture
+
+Most parts of an [Instance](../reference/glossary.md#instance) run in one Kubernetes namespace. The
+[Orchestrator](../reference/glossary.md#orchestrator) runs your [Machines](../reference/glossary.md#machine). A
+[Harness](../reference/glossary.md#harness) runs each [Agent](../reference/glossary.md#agent)'s
+[Turn](../reference/glossary.md#turn). A [Custodian](../reference/glossary.md#custodian) holds the credentials of a
+Harness pod. An [Effector](../reference/glossary.md#effector) runs each `http` and `push`
+[Effect](../reference/glossary.md#effect), each `command` that names an
+[Effect secret](../reference/glossary.md#effect-secret), and each `dispatch` to a different Orchestrator. The operator
+makes the pod of each [Sandbox](../reference/glossary.md#sandbox). One operator serves each cluster. The Repo cache
+keeps a copy of each [Repo](../reference/glossary.md#repo) on each node that needs it. This page tells where each part
+runs and what it does.
+
+## Why the parts are separate
+
+An Agent that works on a Repo runs code. Its [Working tools](../reference/glossary.md#working-tools) give it a shell.
+With the shell, it can run each program of its image on the files in `/work`. It can also connect to each address that
+its pod can reach. Thus jr2 puts each thing that the Agent must not touch in a different place:
+
+- The control of a run is in the Orchestrator. An Agent cannot change its own Machine. It can only pick from its
+  [Menu](../reference/glossary.md#menu), and the Orchestrator decides what each pick does.
+- Each [Workspace](../reference/glossary.md#workspace) has its own Sandbox: a pod with its own filesystem, network and
+  processes. Agents in two Workspaces share no files and no ports. [Workspaces](workspaces.md) tells more.
+- The credentials are in containers in which the Agent executes nothing: the Custodian, the Effector and the Repo cache.
+  [Secrets and trust](secrets-and-trust.md) tells how.
+- The Harness holds one secret value, with which it sends the picks. Each program that it starts runs confined with
+  Landlock, so the code of an Agent cannot read that value.
+
+## What runs where
+
+**What runs where, from your computer to the world outside the cluster**
+
+- **You**: your computer, where no part of a run executes
+  - jr2 CLI
+  - **Console**: in a browser
+  - **Assistant**: writes your Machines
+- ↓ the HTTP API, through a port forward
+- **the cluster**
+  - **Instance**: in the namespace of the Instance, one of each
+    - **Orchestrator**: runs your Machines, and keeps each run
+    - **Instance Harness**: runs the Turns of the Menu-only Agents
+      - Harness
+      - Custodian
+    - **Instance Effector**: runs the Effects that read no Worktree file
+    - **Repo cache**: one pod on each Sandbox node
+  - ↓ a Turn, an Effect · ↑ a pick, through the Custodian · ↓ the Repo cache gives each Repo
+  - **Sandbox**: one pod for each Workspace, in the same namespace
+    - **Harness**: runs the Turns of the Agents that work on a Repo
+    - **Custodian**: holds the Held secrets of the pod
+    - **Sandbox Effector**: runs the Effects that work on the Worktree
+    - **User Container**: when the Workspace names one
+  - ↑ the operator makes the pod of each Sandbox
+  - **jr2-system**: one for each cluster
+    - **operator**: makes each Sandbox pod, and removes it when its Lease lapses
+- ↓ the Custodians call the model provider · ↓ the Repo cache fetches from the git host
+- **Outside**: what the work uses
+  - model provider
+  - git host
+
+The [Instance Harness](../reference/glossary.md#instance-harness), the
+[Instance Effector](../reference/glossary.md#instance-effector), the Repo cache and the
+[Sandbox Effector](../reference/glossary.md#sandbox-effector) exist only when a Machine of the Instance needs them. The
+sections below tell when.
+
+A Sandbox pod can also have a [User Container](../reference/glossary.md#user-container), when its `workspace()` names
+one. It runs its own image, and it mounts `/work`, with each [Worktree](../reference/glossary.md#worktree), read-write.
+[Workspaces](workspaces.md) tells more.
+
+## On your computer
+
+The [jr2 CLI](../reference/glossary.md#jr2-cli) runs on your computer, in the Instance folder. The
+[Assistant](../reference/glossary.md#assistant) works there too, and writes Machines and config in that folder. Nothing
+of a run executes on your computer.
+
+[`jr2 up`](../reference/cli.md#up) reads the folder and converges the cluster of the current kubectl context.
+[Converge](converge.md) tells what it makes. By default, each other command that talks to the Orchestrator, such as
+[`jr2 run`](../reference/cli.md#run), reads the Instance token from the cluster. Then it opens a `kubectl port-forward`
+to the Orchestrator's Service, for the life of the command. The [global options](../reference/cli.md#global-options)
+tell how to give a URL and a token instead. The CLI keeps no local state about the cluster.
+
+The [Console](../reference/glossary.md#console) is a page that the Orchestrator serves. You open it in a browser,
+through a port forward that you start. [Open the Console](../guides/open-the-console.md) gives the commands.
+
+## The Orchestrator
+
+The Orchestrator is one pod for each Instance (`replicas: 1`), with the Service `jr2-orchestrator` on port 4000. It
+hosts all the [Workflows](../reference/glossary.md#workflow) of the Instance and many runs of each Workflow. It keeps
+the snapshot of each run on its own volume, so a run continues after a restart. [Durable runs](durable-runs.md) tells
+how.
+
+The pod runs the `jr2-orchestrator` [Kit image](../reference/glossary.md#kit-image), which holds no code of yours. The
+Orchestrator loads your Workflows and your config from the [Assembly](../reference/glossary.md#assembly) that `jr2 up`
+publishes to it, and it keeps each Assembly on its volume. [Converge](converge.md#the-assembly) tells how.
+
+The Orchestrator does these things:
+
+- It runs each Machine as an [xstate](https://xstate.js.org) actor, and holds the state of each run.
+- It serves the HTTP API that the CLI, the Console, a webhook and the Custodians call. See the
+  [HTTP API](../reference/http-api.md).
+- It sends each Turn to a Harness, and judges each pick that comes back.
+- It writes a Sandbox resource when a run enters a Workspace. Then it watches the Sandbox resource until the Workspace
+  ends.
+- It sends each Effect to the place where it runs. It runs a `dispatch` with no target itself: the Effect starts a run
+  of a Workflow of the same Instance.
+
+The Orchestrator does no work of an Agent. It runs no model and no Working tools. That work runs in the pods that the
+cluster places.
+
+To isolate two sets of Workflows, use two Instances. Each Instance has its own namespace and its own Orchestrator.
+
+## The Harness
+
+The Harness is jr2's own server for the Turns of Agents. It speaks to the model provider. It gives the model the Agent's
+Menu and its Working tools. It executes each Working tool that the model calls, and sends each pick through the
+Custodian. Each program that a Working tool starts runs confined with Landlock. The Harness holds no Agents of its own.
+Each Turn brings the Agent's definition with it. [Agents and Turns](agents-and-turns.md) tells what happens in a Turn.
+
+The Harness has two placements:
+
+- **In each Sandbox.** The Harness is the primary container of the Sandbox pod, named `harness`. It runs in the
+  [Sandbox Image](../reference/glossary.md#sandbox-image), and jr2 mounts the Harness into the pod at `/opt/jr2`. Thus
+  the Working tools of the Agent reach the tools of that image. Each Agent that works on a Repo has its Turns here: one
+  Harness serves all the Agents of the Sandbox.
+- **As the Instance Harness.** The Instance Harness is one StatefulSet for each Instance, `jr2-instance-harness`. Each
+  Turn of a Menu-only Agent (`workspace: "none"`) runs here. Its pod has a Harness and a Custodian, and no Worktree. It
+  keeps each conversation on its volume while a run can continue it. `jr2 up` converges it when a Machine of the
+  Instance has a Menu-only Agent.
+
+A Harness answers only the Orchestrator. The Orchestrator sends a bearer token on each call, and the Harness accepts no
+call without it, except its health check. `jr2 up` also converges NetworkPolicies that let only the Orchestrator's pods
+connect to a Harness pod, and that stop each Harness pod at the cloud metadata addresses
+([Secrets and trust](secrets-and-trust.md#what-a-held-secret-does-not-stop)).
+
+## The Custodian
+
+Each Harness pod has a Custodian: each Sandbox, and the Instance Harness. The Custodian is a container beside the
+Harness. The Agent executes no code in it. It does two things:
+
+- It carries five kinds of call from the pod to the Orchestrator: the Menu reads, the picks, the polls for the answer to
+  a pick, the reports that a step boundary gave its notices to the model, and the fetch asks. It sends the first four
+  with the control token of the Sandbox, and the fetch asks with its fetch token. These five routes are all that it
+  forwards. It refuses all other routes. The Harness sends the first four on a Unix socket in `/run/jr2`. A confined
+  program cannot make a socket there, and the Custodian refuses a request on it that does not have the control Stand-in.
+  The fetch asks go to port `8081` on loopback.
+- It holds the [Held secrets](../reference/glossary.md#held-secret) of its pod, such as a model API key. It puts the
+  value into the requests that go to the hosts of each Held secret.
+
+The Custodian runs Envoy, from a [Pinned image](../reference/glossary.md#pinned-image). The Orchestrator writes its
+config for a Sandbox, and `jr2 up` writes it for the Instance Harness. [Secrets and trust](secrets-and-trust.md) tells
+how the Custodian holds a credential.
+
+## The Effector
+
+The Effector runs each `http` and `push` Effect, each `command` that names an Effect secret, and each `dispatch` that
+names a target. Thus a credential that an Effect uses stays out of the Harness container. The Effector is jr2's own
+program, and it runs in a container in which the Agent executes nothing. [Effects](effects.md) tells which Effect runs
+where. It has two placements:
+
+- **The Sandbox Effector** is a container in a Sandbox pod, named `effector`. It mounts `/work` read-only. It runs a
+  `push`, an `http` Effect whose body is a Worktree file, and a `command` that names an Effect secret. Its image is the
+  Sandbox Image, unless the `workspace()` names a different image.
+- **The Instance Effector** is one pod for each Instance, `jr2-instance-effector`. It runs each `http` Effect that reads
+  no Worktree file, and each `dispatch` that starts a run on a different Orchestrator. It holds the Instance token of
+  that Orchestrator as an Effect secret. It runs in the `jr2-harness` Kit image.
+
+Each placement exists only when a Machine of the Instance puts an Effect there. A `command` that names no Effect secret
+does not use an Effector. It runs in the Harness container of its Sandbox, with the same tools and access as the Agent,
+and confined in the same way.
+
+The Orchestrator signs each request that it sends to an Effector, and the Effector signs each answer. The Orchestrator
+only asks, and the Effector holds the credentials.
+
+## The operator
+
+The operator is a Kubernetes operator. One copy serves the whole cluster: it runs in the namespace `jr2-system`, and
+each Instance on the cluster shares it. By default, `jr2 up` converges it. With `operator.manage: false`, you run it
+yourself.
+
+The operator reconciles two custom resources:
+
+- A **Sandbox resource** becomes one pod and a Service. The Orchestrator writes the Sandbox resource, and the operator
+  makes the pod and reports its state. The operator never makes a second pod for a Sandbox. When the pod ends, the
+  Sandbox is lost.
+- A **Repo** names one git repository that the Repo cache keeps.
+
+The operator knows nothing about Agents, Turns or Worktrees. The Orchestrator does that work after the Sandbox is ready.
+The operator also removes a Sandbox resource when its [Lease](../reference/glossary.md#lease) lapses, for example after
+the Orchestrator stopped for longer than the Lease allows. [Workspaces](workspaces.md) tells how the Lease works.
+
+## The Repo cache
+
+The Repo cache keeps one bare clone of each Repo on each node that needs it. It is a DaemonSet, `jr2-repo-cache`, in the
+namespace of the Instance. It has one pod on each [Sandbox node](../reference/glossary.md#sandbox-node). `jr2 up`
+converges it when a Machine of the Instance uses a Sandbox. Each pod also checks that the kernel of its node has
+Landlock. On a node without Landlock, the pod is not ready, and `jr2 up` names that node and refuses to converge.
+
+The operator mounts the cache of each Repo into a Sandbox, read-only, at `/repos`. The clone in the Sandbox gets its
+objects from that cache. A `git fetch origin` in the Sandbox asks the Repo cache for a fetch. Then the Repo cache
+fetches from the host of the Repo, with the clone credential of the cluster. Thus the Harness container needs no git
+credential to fetch.
+
+## Rules
+
+- An Instance has exactly one Orchestrator, and the Orchestrator always runs in the cluster.
+- A namespace holds one Instance. `jr2 up` refuses a namespace that a different Instance owns.
+- By default, the CLI reaches the cluster of the current kubectl context. Kubernetes RBAC decides who can read the
+  Instance token.
+- A Harness accepts a call only from the Orchestrator, with the bearer of its own pod. Only its health check needs no
+  bearer.
+- The Agent executes code only in the Harness container. It executes nothing in the Custodian or in the Effector.
+- In the Harness container, each program that the Harness starts runs confined. It cannot read what the Harness holds.
+- Each Sandbox node needs Landlock in its kernel. `jr2 up` refuses to converge while a Sandbox node has none.
+- The Orchestrator watches the Sandbox resources and never reads a pod. The operator puts the facts of the pod on the
+  status of the Sandbox resource.
+- A Sandbox has one pod for its life. A lost pod is never made again.
+
+## Read next
+
+- [Open the Console](../guides/open-the-console.md)
+- [Look inside a Sandbox](../guides/look-inside-a-sandbox.md)
+- [Watch a run](../guides/watch-a-run.md)
+- [Workspaces](workspaces.md), [Secrets and trust](secrets-and-trust.md) and [Converge](converge.md)
+- The [HTTP API](../reference/http-api.md) and the [`operator`](../reference/config.md#operator) and
+  [`sandbox`](../reference/config.md#sandbox) fields of `jr2.config.ts`
+- [ADR-0001](../reference/decisions/0001-operator-owned-generic-sandbox.md),
+  [ADR-0005](../reference/decisions/0005-sandbox-pod-composition.md),
+  [ADR-0008](../reference/decisions/0008-orchestrator-as-deployed-app.md),
+  [ADR-0013](../reference/decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md),
+  [ADR-0019](../reference/decisions/0019-one-converging-command-against-the-current-context.md),
+  [ADR-0031](../reference/decisions/0031-menu-only-agents-run-on-the-instance-harness.md),
+  [ADR-0051](../reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md),
+  [ADR-0053](../reference/decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md),
+  [ADR-0058](../reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md),
+  [ADR-0059](../reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md),
+  [ADR-0063](../reference/decisions/0063-the-orchestrator-watches-the-cluster.md),
+  [ADR-0068](../reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md),
+  [ADR-0076](../reference/decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md) and
+  [ADR-0077](../reference/decisions/0077-jr2-requires-landlock-on-every-sandbox-node.md)

package/docs/concepts/charts.md

@@ -0,0 +1,146 @@
+---
+title: Charts
+description: How an Agent writes a Machine as data at run time, which cannot reach the process of the Orchestrator.
+---
+
+# Charts
+
+A [Chart](../reference/glossary.md#chart) is a [Machine](../reference/glossary.md#machine) that is written as data, in
+JSON, with no code. An [Agent](../reference/glossary.md#agent) writes it while a run runs, or you keep it in a file. A
+Chart runs only under a [Chart wrapper](../reference/glossary.md#chart-wrapper): a Machine that declares an
+[Open body](../reference/glossary.md#open-body). The Open body names the parts that a Chart can use.
+
+## Why Charts exist
+
+Some work has a shape that nobody knows before the run. A planner Agent reads the task and decides the steps: first a
+coder, then a reviewer, then a person. You cannot write that Machine before the run.
+
+An Agent cannot write code for the [Orchestrator](../reference/glossary.md#orchestrator). Only
+[`jr2 up`](../reference/cli.md#up) publishes code, because the Orchestrator holds the credentials of the
+[Instance](../reference/glossary.md#instance). Code that an Agent wrote could reach them. A Chart is data: the
+Orchestrator reads it, but it cannot reach the process of the Orchestrator or its credentials. It can only name parts
+that your code gives it, and jr2 checks each name before the Chart runs. Thus an Agent can make a Machine while a run
+runs, and it can do only what the Open body lets it do. A Chart becomes a Workflow only when it is kept under a name
+(see [Four ways to run a Chart](#four-ways-to-run-a-chart)). This is true also when the model is wrong or someone gives
+it bad text.
+
+## The Open body
+
+[`openBody()`](../reference/authoring-surface/openbody.md) makes the actor slot that a Chart binds. It is the one
+[Open](../reference/glossary.md#open) part that a run binds, not a composer. Its declaration has three parts:
+
+- **`lends`**: the parts of the Chart wrapper that a Chart can use, by their slot keys. These are Agents, Effects,
+  Machines, guards, actions and delays. `gate: true` lends the [Gate](../reference/glossary.md#gate), so that a Chart
+  can wait for a person. `fail: true` lends [`fail()`](../reference/authoring-surface/fail.md), so that a Chart can end
+  its run as a [Failure](../reference/glossary.md#failure) with `invoke: { src: "fail", input: { reason } }`.
+- **`allows`**: what the Agents that a Chart adds can have. `models` lists the models, and `workspace` lists the
+  Workspace accesses. With no model, a Chart cannot add an Agent.
+- **`ceilings`**: the limits of one Chart: the Agent Turns, the wall clock, the transitions, the children at one time,
+  and the size of the Chart in bytes.
+
+A Chart gets nothing else. A lent Effect keeps its url, its argv and its secrets, so a Chart fills only its input. A
+lent [`worktree()`](../reference/authoring-surface/worktree.md) must state `expect`, because a Chart cannot state it. A
+Chart reads the cut with the kit guard `jr2.ready`, then gives the same literal path as `cwd` and `worktree`. A Chart
+has no url, no secret, no image and no Repo of its own. The Open body also decides where each Turn of the Chart runs: in
+the Sandbox of its `workspace()`, or on the [Instance Harness](../reference/glossary.md#instance-harness).
+
+## What a Chart holds
+
+A Chart is [xstate](https://xstate.js.org)'s own JSON config, with these limits:
+
+- States, transitions, `after` delays, and nested and parallel states. A Chart has 200 states at most, 8 levels deep.
+- Each `invoke.src` is a lent slot key or an Agent of the Chart. Each guard, action and delay is a lent name. Each Chart
+  also has the guard `jr2.failure`, which is true on an `onError` when the error is a Failure, and the guard
+  `jr2.ready`, which is true on an `onDone` when the cut is `ready`.
+- A state that invokes an Agent can route [`agent.fault`](../reference/mechanism-events.md#agent-fault) in its `on`, but
+  it does not have to. When no transition of the Chart takes `agent.fault`, the Open body sends it, unchanged, to the
+  Chart wrapper. The wrapper's own `agent.fault` route takes it, as for an Agent of the wrapper, so one route on the
+  wrapper's root is the route for each Agent of each Chart.
+- Its events, with a JSON Schema for the input of each. An Agent of the Chart picks these events.
+- Its own Agents, under `agents`, each with a model that the Open body allows.
+- Its `context`, and the `output` of its final state. A Chart reads that `output`. A Machine that you write in
+  TypeScript does not: it needs a root `output`. `createMachine` refuses an `output` on a final state directly below the
+  root when the root has none (see [Write a Workflow](../guides/write-a-workflow.md#give-the-run-an-output)).
+
+A Chart moves data with a [Reference](../reference/glossary.md#reference): a path that jr2 reads when the state starts.
+`{{input.topic}}` reads the input of the Chart, `{{context.notes}}` reads its context, and `{{event.summary}}` reads the
+pick that a transition handles. `{ "$ref": "event.summary" }` is the same. A Reference is a path, not an expression:
+`{{context.round + 1}}` is refused. Four actions write the context: `set`, `append`, `increment` and `clear`.
+
+A placeholder in data stays text. When a ticket holds `{{context.notes}}`, the prompt gets those characters, not the
+notes.
+
+## The door
+
+jr2 checks each Chart before it runs. The door reads the whole Chart, and gives one line for each problem:
+
+- each name that is not lent, or not declared by the Chart
+- each event that no state handles, and each payload schema that uses a part that jr2 does not check
+- each model that the Open body does not allow
+- each loop with no guard, and each Agent state that nothing can end
+- each Reference that nothing supplies, such as `{{context.summary}}` when no `set` writes `summary`
+
+A refusal is the output of the Open body: `{ outcome: "refused", report }`. The Chart wrapper routes it. Usually it goes
+back to the planner as the answer to its pick, and the planner sends a corrected Chart. The other outputs are
+`{ outcome: "done", output }` when the Chart ends, and `{ outcome: "ceiling", ceiling }` when it gets to a ceiling.
+
+The pick of a planner carries the Chart as its parameter. Its schema is
+[`chartSchemaFor(declaration)`](../reference/authoring-surface/chartschemafor.md): the Chart grammar with the lent names
+of this Open body. Thus the model gets the grammar as the parameters of its tool. On each Turn where the pick is an
+[Allowed pick](../reference/glossary.md#allowed-picks), the [Briefing](../reference/glossary.md#briefing) also tells the
+Agent how a Chart runs.
+
+## Four ways to run a Chart
+
+| Who                  | One time                                                      | By name                                                             |
+| -------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------- |
+| You, a tool or a CLI | The Chart in the run input of the Chart wrapper               | A Chart file, or a runtime Chart, run as `jr2 run <wrapper>/<name>` |
+| An Agent             | Its pick carries the Chart, and a state invokes the Open body | The Open body gets `{ chart: { name } }`                            |
+
+A Chart wrapper takes a Chart in its run input when a field of its input is
+[`chartSchema`](../reference/authoring-surface/chartschema.md). Only such a wrapper keeps Charts under a name. A named
+Chart is a [Workflow](../reference/glossary.md#workflow), with the name `<wrapper>/<name>`, and it runs under that
+wrapper only. It comes from one of two places:
+
+- A **Chart file** in the Assembly: `workflows/<wrapper>/<name>.chart.json`. `jr2 up` checks it at the door before it
+  converges, and refuses a Chart file that the door refuses.
+- A **runtime Chart**: `PUT /workflows/<wrapper>/charts/<name>`, with the Instance token. The Orchestrator keeps it on
+  its volume. `DELETE` on the same path removes it.
+
+[`jr2 runs`](../reference/cli.md#runs) lists each named Chart under its wrapper. When a publish removes a part that a
+runtime Chart uses, the Chart stays, and it is unrunnable until a publish gives the part back.
+
+## A run keeps its Chart
+
+The run keeps the text of its Chart in its snapshot. Thus a run continues when its named Chart changes or goes. After a
+restart, jr2 checks the text at the door again. A Chart that the door refuses then makes the run `drifted`.
+
+The [Console](../reference/glossary.md#console) draws the Machine that the run binds, with its Chart in it. Thus you see
+the states of the Chart while it runs.
+
+## Rules
+
+- A Chart runs only under a Chart wrapper.
+- A Chart names only the parts that the Open body lends, its own Agents, and the four generic actions.
+- An Agent of a Chart has a model that the Open body allows, and a Workspace access that it allows.
+- A Reference starts at `context`, `event` or `input`, and something must supply it.
+- The door refuses the whole Chart when it finds one problem, and it lists each problem.
+- A Chart cannot go past a ceiling. The Open body then stops it.
+- Only a wrapper with a `chartSchema` field in its input takes a Chart in the run input, and keeps named Charts.
+- A Chart file and a runtime Chart with the same name: the Chart file wins, and the runtime Chart is unrunnable.
+
+[Let an Agent write a Chart](../guides/let-an-agent-write-a-chart.md) and
+[Run a Chart by name](../guides/run-a-chart-by-name.md) give the refusal text of each rule.
+
+## Read next
+
+- [Let an Agent write a Chart](../guides/let-an-agent-write-a-chart.md)
+- [Run a Chart by name](../guides/run-a-chart-by-name.md)
+- [Composition](composition.md), [The Menu](the-menu.md), [Agents and Turns](agents-and-turns.md)
+- Reference: [`openBody`](../reference/authoring-surface/openbody.md),
+  [`OpenBodyDeclaration`](../reference/authoring-surface/type-openbodydeclaration.md),
+  [`OpenBodyOutput`](../reference/authoring-surface/type-openbodyoutput.md),
+  [`chartSchema`](../reference/authoring-surface/chartschema.md),
+  [`chartSchemaFor`](../reference/authoring-surface/chartschemafor.md),
+  [`PUT /workflows/:wrapper/charts/:name`](../reference/http-api.md#put-workflows-wrapper-charts-name)
+- [ADR-0070](../reference/decisions/0070-a-machine-lends-its-parts-to-a-chart.md): a Machine lends its parts to a Chart