@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/authoring-surface/type-sandboxoptions.md

@@ -0,0 +1,84 @@
+---
+title: SandboxOptions
+description: The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
+---
+
+# `SandboxOptions`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SandboxOptions<TSlots extends string, TInput = unknown> = {
+  image?: string;
+  workGroup?: number;
+  user?: string | UserContainer;
+  resources?: Size;
+  repos: Record<TSlots, RepoSlot<TInput>> | typeof open;
+  secrets?: readonly string[];
+  effector?: { image: string };
+};
+```
+
+The options of a `workspace()` that say what its Sandbox is made of and which Repos it
+clones. They are the same for each run.
+
+**Fields**
+
+- `image` (optional): `string`
+
+  The Sandbox Image: the image of the container where the Agent's Working tools and
+  `command` Effects run. A `file:` URL to a docker context that your module ships
+  (`import.meta.resolve("./image")`), which `jr2 up` builds, or a registry ref. Its floor is
+  glibc and git; jr2 adds its own runtime at `/opt/jr2`. Default: the Instance's
+  `images/default`, then jr2's Harness image.
+- `workGroup` (optional): `number`
+
+  The group id that owns the files in `/work`. Default: 2000. A non-negative integer.
+- `user` (optional): `string | UserContainer`
+
+  The User Container: a third container in the Sandbox, for a service that must run beside the
+  Agent, such as an sshd. Its image, in the same two forms as `image`, or `{ image, resources }`
+  to give it a part of the Size. It runs its own entrypoint, with `/work` mounted. jr2 adds
+  nothing to it. Default: none. Without `resources`, it has no limit of its own and shares the
+  Size of the Sandbox.
+- `resources` (optional): [`Size`](type-size.md)
+
+  The Size: the memory and cpu limit of the whole Sandbox, `{ limits: { memory, cpu } }`, such as
+  `{ limits: { memory: "4Gi", cpu: "2" } }`. jr2 reserves all of it on the node: each request
+  equals its limit. jr2 also enforces the cpu limit. Only `limits`,
+  and in it only `memory` and `cpu`, are accepted. Default: the Instance's `sandbox.resources`,
+  then 2Gi and 1 cpu. Under a Size that you give, a field you leave out takes the kit's value,
+  not the Instance's. The Instance that registers the Machine can change it with
+  `customize(machine, { resources })`.
+- `repos`: `Record<TSlots, RepoSlot<TInput>> | typeof open`
+
+  The Repo Slots: the repositories that the Sandbox clones, each under a name of your Machine's
+  choice. The name is the key of `workspace.repos` in the body and the directory under `/work`.
+  At least one slot. Leave `repos` out for a Workspace with no Repo Slot (see
+  [`NoSlotWorkspaceOptions`](type-noslotworkspaceoptions.md)). Each value is one of:
+  - a url, or `{ url, ref }`, where `ref` is the branch, the tag or the commit that the clone
+    stays on, and that a new branch starts from (default: the Repo's default branch);
+  - `open`, for the Instance that registers the Machine to bind with `customize()`;
+  - a function of the run input, `({ input }) => url` or `{ url, ref }`, when each run chooses.
+
+  Or `repos: open` for the whole map: the Machine names no slot, and the Instance that registers
+  it names each one with `customize()`. The body's input is then `Workspaced<RunInput, string>`.
+- `secrets` (optional): `readonly string[]`
+
+  The Held secrets that this Sandbox can use: names from the `secrets` list in `jr2.config.ts`.
+  The Sandbox's Custodian holds each value and puts it into requests to the hosts of that Held
+  secret. Listing a name also gives its Stand-in to the Agent's programs — each `bash` call, test,
+  build and `command` — in their env under that name, so code in `/work` can spend it ([ADR-0076](../decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
+  You need not list the model key of an Agent that runs here: its provider claims it, and the
+  Harness gives it to the model calls alone. List the model key only when code in `/work` must
+  call the model itself: such a call is outside the Turn's usage record. Each name once.
+- `effector` (optional): `object`
+
+  The image of the Sandbox Effector. This container runs three kinds of Effect for this
+  Workspace: a `push`, an `http` Effect with a Worktree file as its body, and a `command` with an
+  Effect secret in its `env`. It gets the Effect secrets that those Effects name. Give an image
+  when those Effects need tools or credentials that you keep out of the Sandbox Image, such as
+  `terraform`. A `file:` URL or a registry ref, as for `image`. Default: the Sandbox Image,
+  which already holds `git`.
+
+  - `image`: `string`

package/docs/reference/authoring-surface/type-secret.md

@@ -0,0 +1,25 @@
+---
+title: Secret
+description: "What `secret(\"name\")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`."
+---
+
+# `Secret`
+
+Type, in `@jr2/orchestrator/src/http-effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Secret = { readonly secret: string; readonly path: { readonly secret: string; readonly path: true } };
+```
+
+What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of
+`jr2.config.ts`. Put it in an Effect's `auth`, a header, a `text` or a command's `env`. Its
+`.path` is the path of a file that holds the value. The value stays in the Effector, so the
+Machine and the Agent never see it.
+
+**Fields**
+
+- `secret`: `string`
+- `path`: `object`
+
+  - `secret`: `string`
+  - `path`: `true`

package/docs/reference/authoring-surface/type-sender.md

@@ -0,0 +1,19 @@
+---
+title: Sender
+description: "Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015)."
+---
+
+# `Sender`
+
+Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Sender = { readonly party: "agent" | "gate"; readonly id: string };
+```
+
+Who delivered an event: an Agent by its slot, or a Gate by its invoke id ([ADR-0015](../decisions/0015-authoring-surface-absorbs-the-mechanism.md)).
+
+**Fields**
+
+- `party`: `"agent" | "gate"`
+- `id`: `string`

package/docs/reference/authoring-surface/type-sentbyguards.md

@@ -0,0 +1,12 @@
+---
+title: SentByGuards
+description: A type that the Authoring surface names.
+---
+
+# `SentByGuards`
+
+Type, in `@jr2/orchestrator/src/setup.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type SentByGuards = { [SENT_BY]: { id: string } };
+```

package/docs/reference/authoring-surface/type-size.md

@@ -0,0 +1,85 @@
+---
+title: Size
+description: "The Size of a Workspace: the most memory and cpu that its whole Sandbox can use."
+---
+
+# `Size`
+
+Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+type Size = {
+  limits: {
+    memory?: Quantity;
+    cpu?: Quantity;
+  };
+};
+```
+
+The Size of a Workspace: the most memory and cpu that its whole Sandbox can use. jr2 reserves
+all of it on the node. Thus a Sandbox never gets less than its Size and never uses more.
+
+Write it as `{ limits: { memory, cpu } }`. You can write it in three places: the `resources`
+option of `workspace()`, `customize(machine, { resources })`, and `sandbox.resources` in
+`jr2.config.ts`. The Size is a fact of the Machine. The Instance's `sandbox.resources` applies
+only to a Workspace that states no Size. A field that neither states comes from the kit default:
+memory `2Gi`, cpu `1`.
+
+The same shape is the User Container's part of the Size, in `user: { image, resources }`. There,
+a field you leave out gives the User Container no limit of its own: it shares the pod's budget.
+
+It refuses any key but `limits.memory` and `limits.cpu`, where you write it. The message names
+the field: `<where>` is where you wrote the Size, for example `workspace(): resources`.
+
+- `<where>.requests is not accepted — jr2 reserves the whole Size, so every request equals its
+  limit — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template
+  size (ADR-0060)`
+- `<where>.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing else —
+  Agent Substrate's template size (ADR-0060)`
+- `<where>.limits.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing
+  else — Agent Substrate's template size (ADR-0060)`
+- `<where>.limits.memory: <value> is not a positive quantity (e.g. "2Gi", "512Mi")`, and for
+  cpu, `<where>.limits.cpu: <value> is not a positive quantity (e.g. "2", "1500m")`
+
+`jr2 up` also refuses a Size that leaves the Harness container less than its floor. The message
+starts with `the Size leaves the Harness container <memory> memory, below its 256Mi floor:` or
+with `the Size leaves the Harness container no cpu:`. The text that follows names each number
+and where it came from.
+
+**Fields**
+
+- `limits`: `object`
+
+  The two limits. Write `limits: {}` to state no field: each field then comes from the next
+  source.
+
+  - `memory` (optional): [`Quantity`](type-quantity.md)
+
+    The memory limit, as a Kubernetes quantity: `"4Gi"`, `"512Mi"`, or a number of bytes.
+    It must be more than zero. When you leave it out, it comes from the next source, as above.
+  - `cpu` (optional): [`Quantity`](type-quantity.md)
+
+    The cpu limit, as a Kubernetes quantity: `"2"`, `"1500m"`, or a number of cpus. It must be
+    more than zero. jr2 enforces it. When you leave it out, it comes from the next source, as
+    above.
+
+**Example**
+
+```ts
+import { customize, type Size } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const size: Size = { limits: { memory: "4Gi", cpu: "2" } };
+
+export const machine = customize(task, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+  resources: size,
+});
+```
+
+**See also**
+
+- [Size a Workspace](../../guides/size-a-workspace.md)
+- [Workspaces](../../concepts/workspaces.md)
+- [ADR-0060: A Workspace states its Size, and jr2 reserves all of it](../decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)

package/docs/reference/authoring-surface/type-slothandles.md

@@ -0,0 +1,24 @@
+---
+title: SlotHandles
+description: The handles of a Workspace that declares Repo Slots.
+---
+
+# `SlotHandles`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SlotHandles<TSlots extends string> = {
+  repos: { [K in TSlots]: `/work/${K}` };
+};
+```
+
+The handles of a Workspace that declares Repo Slots. @internal
+
+**Fields**
+
+- `repos`: ``{ [K in TSlots]: `/work/${K}`; }``
+
+  The folder of each Repo Slot, `/work/<slot>`, in the order that `repos` declares the slots.
+  `${handle}/default` is the clone, on the Binding's base. Any other Worktree is one the Machine
+  cut with `worktree()`.

package/docs/reference/authoring-surface/type-sourcenextresult.md

@@ -0,0 +1,17 @@
+---
+title: SourceNextResult
+description: "What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready now; or `{ item, open }`, where `open` is the number of items that exist but are not ready."
+---
+
+# `SourceNextResult`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SourceNextResult<T> = T | null | { item: T | null; open: number };
+```
+
+What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready
+now; or `{ item, open }`, where `open` is the number of items that exist but are not ready.
+When no worker runs and `next` gives no item, the Pool ends: `drained` when `open` is 0 or
+absent, `deadlocked` when `open` is more than 0.

package/docs/reference/authoring-surface/type-sourcespec.md

@@ -0,0 +1,44 @@
+---
+title: SourceSpec
+description: "Where a Pool gets its work items: the Source."
+---
+
+# `SourceSpec`
+
+Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type SourceSpec<T, TInput = unknown> = {
+  next:
+    | PromiseActorLogic<SourceNextResult<T>, PoolNextInput<TInput>>
+    | PromiseActorLogic<{ item: T | null; open: number }, PoolNextInput<TInput>>
+    | PromiseActorLogic<T | null, PoolNextInput<TInput>>
+    | PromiseActorLogic<null, PoolNextInput<TInput>>;
+  wake?: EventDef;
+  pollEvery?: number;
+};
+```
+
+Where a Pool gets its work items: the Source. Make one with [`source`](source.md).
+
+**Fields**
+
+- `next`: `PromiseActorLogic<SourceNextResult<T>, PoolNextInput<TInput>> | PromiseActorLogic<{ item: T | null; open: number; }, PoolNextInput<TInput>> | PromiseActorLogic<T | null, PoolNextInput<TInput>> | PromiseActorLogic<null, PoolNextInput<TInput>>`
+
+  Claim the next ready item. Write it as an xstate promise actor,
+  `fromPromise(async ({ input }) => …)`. Its input is [`PoolNextInput`](type-poolnextinput.md): `active`, the ids of
+  the items that workers have now, `settled`, the ids of the items that finished or failed, and
+  `input`, the Pool's input. It must not give again an item in `active` or `settled`. It resolves
+  to a [`SourceNextResult`](type-sourcenextresult.md). The Pool calls it when the run starts, after each claim, and when a worker settles. While workers run and no item is ready, it
+  also calls it on `wake` and every `pollEvery`.
+- `wake` (optional): [`EventDef`](type-eventdef.md)
+
+  An external event, made with `defineEvent`, that tells the Pool that new work is ready, for
+  example from a webhook or `jr2 send`. While workers run and no item is ready, it makes the Pool
+  call `next` at once. The Pool serves it as a Gate named `source` for the whole run
+  (`<path>.source` when the Pool is composed in another Machine). Default: none.
+- `pollEvery` (optional): `number`
+
+  While workers run and no item is ready, call `next` again after this many milliseconds. Use
+  it for a Source whose items change while the run waits. Default: none, so the Pool calls
+  `next` again only when a worker settles or `wake` comes.

package/docs/reference/authoring-surface/type-syncstate.md

@@ -0,0 +1,12 @@
+---
+title: SyncState
+description: A type that the Authoring surface names.
+---
+
+# `SyncState`
+
+Type, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type SyncState = SyncAnswer["sync"];
+```

package/docs/reference/authoring-surface/type-text.md

@@ -0,0 +1,19 @@
+---
+title: Text
+description: "What the `text` template gives: a string of literal text and Effect secrets, in order."
+---
+
+# `Text`
+
+Type, in `@jr2/orchestrator/src/http-effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Text = { readonly text: readonly TextPart[] };
+```
+
+What the `text` template gives: a string of literal text and Effect secrets, in order. The
+Effector builds the string, so the Machine never sees the value of a secret.
+
+**Fields**
+
+- `text`: `readonly TextPart[]`

package/docs/reference/authoring-surface/type-textpart.md

@@ -0,0 +1,24 @@
+---
+title: TextPart
+description: "One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret."
+---
+
+# `TextPart`
+
+Type, in `@jr2/orchestrator/src/effector-wire.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type TextPart = z.infer<typeof TextPartShape>;
+```
+
+One part of a [`Text`](type-text.md): `{ text }`, literal text, or `{ secret }`, the name of an Effect
+secret. The `text` template makes the parts.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `text`
+
+  - `text`: `string`
+- Form 2: `secret`
+
+  - `secret`: `string`

package/docs/reference/authoring-surface/type-thinkinglevel.md

@@ -0,0 +1,39 @@
+---
+title: ThinkingLevel
+description: "How hard the model thinks before it answers: `\"off\"`, `\"minimal\"`, `\"low\"`, `\"medium\"`, `\"high\"` or `\"xhigh\"`."
+---
+
+# `ThinkingLevel`
+
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+
+```ts
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+```
+
+How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`,
+`"high"` or `"xhigh"`. Set it on an Agent's definition (`thinkingLevel`), or for one Turn in the
+invoke's `input`.
+
+A model can lack a level. Claude Sonnet 5.5 has no `"off"`, and at `"off"` the Harness's request
+then sends effort `"high"`. The Harness does not refuse such a level: it runs the Turn, and the
+printed conversation names the level that the model ran at.
+
+**Example**
+
+```ts
+import { agent, type ThinkingLevel } from "@jr2/orchestrator";
+
+const effort: ThinkingLevel = "high";
+
+export const reviewer = agent({
+  model: "anthropic/claude-haiku-5-5",
+  instructions: "You review diffs for correctness.",
+  thinkingLevel: effort,
+});
+```
+
+**See also**
+
+- [Set an Agent's access and Dials](../../guides/set-an-agents-access-and-dials.md)
+- [ADR-0018: The instance authors Agent definitions; jr2 assembles the Harness](../decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)

package/docs/reference/authoring-surface/type-toparameterizedobject.md

@@ -0,0 +1,14 @@
+---
+title: ToParameterizedObject
+description: A type that the Authoring surface names.
+---
+
+# `ToParameterizedObject`
+
+Type, in `@jr2/orchestrator/src/setup.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type ToParameterizedObject<T extends Record<string, ParameterizedObject["params"] | undefined>> = {
+  [K in keyof T & string]: { type: K; params: T[K] };
+}[keyof T & string];
+```

package/docs/reference/authoring-surface/type-toprovidedactor.md

@@ -0,0 +1,14 @@
+---
+title: ToProvidedActor
+description: A type that the Authoring surface names.
+---
+
+# `ToProvidedActor`
+
+Type, in `@jr2/orchestrator/src/setup.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
+  [K in keyof TActors & string]: { src: K; logic: TActors[K]; id: string | undefined };
+}[keyof TActors & string];
+```

package/docs/reference/authoring-surface/type-unknown.md

@@ -0,0 +1,21 @@
+---
+title: Unknown
+description: "The output `{ outcome: \"unknown\", reason }`: the Effect may have acted, and jr2 cannot tell."
+---
+
+# `Unknown`
+
+Type, in `@jr2/orchestrator/src/effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Unknown = { outcome: "unknown"; reason: string };
+```
+
+The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
+For example, the Harness lost the exec, or its state exited while it ran. Route on it. jr2 does
+not run the Effect again.
+
+**Fields**
+
+- `outcome`: `"unknown"`
+- `reason`: `string`

package/docs/reference/authoring-surface/type-usercontainer.md

@@ -0,0 +1,77 @@
+---
+title: UserContainer
+description: "The User Container in its object form: its image, and its part of the Workspace's Size."
+---
+
+# `UserContainer`
+
+Type, in `@jr2/orchestrator/src/size.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+type UserContainer = {
+  image: string;
+  resources?: Size;
+};
+```
+
+The User Container in its object form: its image, and its part of the Workspace's Size. The User
+Container is an optional container of your own in the Sandbox pod. It runs its own entrypoint
+with `/work` mounted, and jr2 never builds into it, probes it or sends it commands. Use it for a
+service that must run without an Agent, such as an sshd.
+
+Write it in the `user` option of `workspace()` or of `customize()`. That option also takes the
+image as a string; use this object form only to give the User Container a part of the Size. A
+`customize()` that names `user` replaces the whole User Container, its part of the Size
+included.
+
+It refuses, where you write it. `<where>` is `workspace()` or `customize()`:
+
+- an image that is not a non-empty string. The message starts with
+  `` <where>: `user` must be a non-empty string (an image), or { image, resources? } ``.
+- `<where>: user.<key> is not accepted — the User Container is { image, resources? } (ADR-0005,
+  ADR-0060)`
+
+`resources` is checked as a [`Size`](type-size.md), with the same refusals.
+
+`jr2 up` refuses a part that leaves the Harness container less than its floor. The message starts
+with `the Size leaves the Harness container <memory> memory, below its 256Mi floor:` or with
+`the Size leaves the Harness container no cpu:`. The text that follows names each number and
+where it came from.
+
+**Fields**
+
+- `image`: `string`
+
+  The image: a `file:` URL to a docker context that your module ships
+  (`import.meta.resolve("./sshd")`), which `jr2 up` builds, or a registry ref. It must not be
+  empty.
+- `resources` (optional): [`Size`](type-size.md)
+
+  This container's part of the Workspace's Size, as a Size. jr2 takes it from the Harness
+  container's part. A field you leave out gives this container no limit of its own for it: it
+  shares the pod's budget. Default: no part.
+
+**Example**
+
+```ts
+import { customize, type UserContainer } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const sshd: UserContainer = {
+  image: "registry.example.com/sshd:1.0",
+  resources: { limits: { memory: "256Mi", cpu: "250m" } },
+};
+
+export const machine = customize(task, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+  user: sshd,
+});
+```
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [Size a Workspace](../../guides/size-a-workspace.md)
+- [ADR-0005: The Sandbox pod's containers: Harness, Custodian, an optional User Container, and an optional Sandbox Effector](../decisions/0005-sandbox-pod-composition.md)
+- [ADR-0060: A Workspace states its Size, and jr2 reserves all of it](../decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)

package/docs/reference/authoring-surface/type-withoutemptyindex.md

@@ -0,0 +1,20 @@
+---
+title: WithoutEmptyIndex
+description: The fields of the run input `T`.
+---
+
+# `WithoutEmptyIndex`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type WithoutEmptyIndex<T> = string extends keyof T
+  ? [T[string & keyof T]] extends [never]
+    ? { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] }
+    : T
+  : T;
+```
+
+The fields of the run input `T`. A string index signature whose value is `never` is not one of
+them: `z.infer` gives `Record<string, never>` for `z.object({})`, and this type makes it `{}`. The
+named fields of `T` stay. A different `T` does not change.

package/docs/reference/authoring-surface/type-workflowevent.md

@@ -0,0 +1,46 @@
+---
+title: WorkflowEvent
+description: "The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event."
+---
+
+# `WorkflowEvent`
+
+Type, in `@jr2/orchestrator/src/setup.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type WorkflowEvent<TDefs extends readonly EventDef[]> =
+  | (EventFrom<TDefs[number]> & { readonly sender?: Sender })
+  | MechanismEvent;
+```
+
+The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`,
+and each Mechanism event. A workflow event that an Agent or a Gate sent has `event.sender`. An
+event that the Machine sent to itself (`raise`, `sendTo`) has no `sender`.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `type`, `sender`
+
+  - `type`: `N`
+  - `sender` (optional): [`Sender`](type-sender.md)
+- Form 2: `type`, `instanceId`, `reason`
+
+  - `type`: `"agent.fault"`
+  - `instanceId`: `string`
+
+    The Instance ID of the Agent's conversation that failed: the same id on each Turn that
+    continues it.
+  - `reason`: `string`
+
+    Why the Turn failed, as text for a person or a log: the Harness's error, or that the Agent
+    ended its Turns without a pick after every nudge. Route on the event, not on this text.
+- Form 3: `type`, `reason`, `message`
+
+  - `type`: `"workspace.lost"`
+  - `reason` (optional): `string`
+
+    Why the Sandbox is gone, for a person or a log: the pod's reason (`Evicted`, `NodeShutdown`),
+    the operator's (`PodDeleted`, `NodeLost`), or `Deleted`. A body can act without it.
+  - `message` (optional): `string`
+
+    More text about the loss, when jr2 has it.

package/docs/reference/authoring-surface/type-workspaceaccess.md

@@ -0,0 +1,16 @@
+---
+title: WorkspaceAccess
+description: "What an Agent may do to the Workspace: `\"write\"`, `\"read\"` or `\"none\"`."
+---
+
+# `WorkspaceAccess`
+
+Type, in `@jr2/orchestrator/src/agent.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type WorkspaceAccess = "write" | "read" | "none";
+```
+
+What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`. With `"none"`, its Turn
+runs on the Instance Harness, not in a Sandbox. The `workspace` field of [`AgentDefinition`](type-agentdefinition.md)
+tells what each value gives.