@jr2/orchestrator 0.4.1 → 0.5.1

package/docs/reference/authoring-surface/pool.md

@@ -0,0 +1,186 @@
+---
+title: pool
+description: "Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once."
+---
+
+# `pool`
+
+Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+## Overload 1
+
+```ts
+function pool<
+  TWorker extends AnyStateMachine,
+  TSchema extends z.ZodObject,
+>(
+  worker: TWorker,
+  spec: PoolSpec<any, z.infer<TSchema>> & { input: TSchema },
+): PoolMachine<TWorker, z.infer<TSchema>>
+```
+
+Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at
+most `cap` workers at once. Use it as the root of a Workflow (`export const machine = pool(…)`),
+or compose it in another Machine.
+
+The run ends when the Source has no item ready and no worker runs. Its output is
+`{ status, items, failures }`: `status` is `"drained"` when no item is left, or `"deadlocked"`
+when items exist but none can start; `items` holds the output of each worker that got to a final
+state, by item id; `failures` holds the Failure of each worker that failed, by item id. A worker's
+Failure stops only that worker: the other workers and their Sandboxes stay. When the Pool ends
+with one or more failures, `drained` or `deadlocked`, it fails the run by default: the reason is
+`"<n> of <m> items failed"`, and the detail is `{ status, items, failures }`. With
+`failures: "report"`, it ends `done` with that output. A worker's defect ends the whole run
+`error`. While workers wait on Gates, the run stays open.
+
+`customize()` reaches through a Pool to its worker: `customize(pool, { agents })` retunes the
+worker's Agents. The events that the Pool accepts are its `wake` event only; each worker keeps
+its own.
+
+**Parameters**
+
+- `worker`: The Machine to run for each item. It gets the item, or what `itemInput` makes
+  of it, as its input. It does not get the run input.
+- `spec`: The Source, the item id, the cap, and the worker's input. See [`PoolSpec`](type-poolspec.md).
+
+  - `id` (optional): `string`
+
+    The Machine id: the name of the Pool in the Console. Default: `"pool"`.
+  - `input`: `z.ZodObject`
+
+    The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
+    `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
+    none, and then their `input` is `unknown`.
+  - `source`: `SourceSpec<T>`
+
+    Where the items come from. Make it with [`source`](source.md).
+  - `itemId`: `(item: T) => string`
+
+    The id of an item. The Pool uses it as the id of the item's worker and in the `active` list
+    that `next` gets. It is also the key of that worker's output in `items`. Give each item an id
+    of its own, and the same id every time.
+  - `cap` (optional): `number | ((args: { input: TInput; }) => number)`
+
+    The most workers that run at once: a number, or a function of the run input. Default: `1`.
+  - `itemInput` (optional): `(item: T, args: { input: TInput; }) => unknown`
+
+    Make a worker's input from its item and the run input. Default: the item itself.
+  - `onDrained` (optional): `"final"`
+
+    What the Pool does when the Source has no more items and every worker has settled. Only
+    `"final"`: the run ends. Default: `"final"`.
+  - `failures` (optional): `"fail" | "report"`
+
+    What the Pool does at the end when one or more workers failed. The Pool catches each worker's
+    Failure either way, so one failed item does not stop the other workers. `"fail"`: when the Pool
+    ends with failures, `drained` or `deadlocked`, it fails the run with the reason
+    `"<n> of <m> items failed"` and the detail `{ status, items, failures }`. `"report"`: the Pool
+    ends `done`, with the failures in its output. Default: `"fail"`.
+
+**Returns**: The Pool, as a Machine.
+
+**Example**
+
+```ts
+import { fromPromise } from "xstate";
+import { customize, pool, source } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+type Issue = { id: string; title: string };
+
+const backlog: Issue[] = [
+  { id: "ISSUE-1", title: "Fix the greeting." },
+  { id: "ISSUE-2", title: "Add a --name flag." },
+];
+
+const issues = source<Issue>({
+  next: fromPromise(async ({ input }: { input: { active: string[] } }) => {
+    const issue = backlog.find((i) => !input.active.includes(i.id)) ?? null;
+    if (issue) backlog.splice(backlog.indexOf(issue), 1);
+    return issue;
+  }),
+});
+
+const fixer = customize(task, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+});
+
+export const machine = pool(fixer, {
+  id: "issues",
+  source: issues,
+  itemId: (issue: Issue) => issue.id,
+  cap: 2,
+  itemInput: (issue: Issue) => ({ prompt: issue.title, branch: `fix/${issue.id}` }),
+});
+```
+
+**See also**
+
+- [Run one worker per item](../../guides/run-one-worker-per-item.md)
+- [Pools and Sources](../../concepts/pools-and-sources.md)
+- [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)
+
+## Overload 2
+
+```ts
+function pool<
+  TWorker extends AnyStateMachine,
+  TInput = unknown,
+>(
+  worker: TWorker,
+  spec: PoolSpec<any, TInput> & { input?: never },
+): PoolMachine<TWorker, TInput>
+```
+
+Make a Pool with no `input` schema. A Pool is a Machine that runs one worker Machine for each
+item that a Source gives, with at most `cap` workers at once. See `pool` for the full description and
+an example.
+
+**Parameters**
+
+- `worker`: The Machine to run for each item. It gets the item, or what `itemInput` makes
+  of it, as its input. It does not get the run input.
+- `spec`: The Source, the item id, the cap, and the worker's input. See [`PoolSpec`](type-poolspec.md).
+
+  - `id` (optional): `string`
+
+    The Machine id: the name of the Pool in the Console. Default: `"pool"`.
+  - `input` (optional): `z.ZodObject`
+
+    The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
+    `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
+    none, and then their `input` is `unknown`.
+  - `source`: `SourceSpec<T>`
+
+    Where the items come from. Make it with [`source`](source.md).
+  - `itemId`: `(item: T) => string`
+
+    The id of an item. The Pool uses it as the id of the item's worker and in the `active` list
+    that `next` gets. It is also the key of that worker's output in `items`. Give each item an id
+    of its own, and the same id every time.
+  - `cap` (optional): `number | ((args: { input: TInput; }) => number)`
+
+    The most workers that run at once: a number, or a function of the run input. Default: `1`.
+  - `itemInput` (optional): `(item: T, args: { input: TInput; }) => unknown`
+
+    Make a worker's input from its item and the run input. Default: the item itself.
+  - `onDrained` (optional): `"final"`
+
+    What the Pool does when the Source has no more items and every worker has settled. Only
+    `"final"`: the run ends. Default: `"final"`.
+  - `failures` (optional): `"fail" | "report"`
+
+    What the Pool does at the end when one or more workers failed. The Pool catches each worker's
+    Failure either way, so one failed item does not stop the other workers. `"fail"`: when the Pool
+    ends with failures, `drained` or `deadlocked`, it fails the run with the reason
+    `"<n> of <m> items failed"` and the detail `{ status, items, failures }`. `"report"`: the Pool
+    ends `done`, with the failures in its output. Default: `"fail"`.
+
+**Returns**: The Pool, as a Machine.
+
+**See also**
+
+- [Run one worker per item](../../guides/run-one-worker-per-item.md)
+- [Pools and Sources](../../concepts/pools-and-sources.md)
+- [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)

package/docs/reference/authoring-surface/push.md

@@ -0,0 +1,112 @@
+---
+title: push
+description: "Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot."
+---
+
+# `push`
+
+Function, in `@jr2/orchestrator/src/sandbox-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function push<
+  const O extends PushOptions,
+>(
+  options?: O,
+): EffectLogic<PushInput<O> | void, PushOutput>
+```
+
+Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
+Put it in `actors`, and invoke it from the body of a `workspace()`: `actors: { publish: push({
+sign: true }) }`.
+
+It runs in the Sandbox Effector of the Workspace, with the push credential of the
+`git.credentials` entry that the Binding matches. The Agent never reads that credential. It
+pushes one commit: the tip of the Agent's branch when the Effect starts, or, with `pin`, the
+commit that the input names. After an Orchestrator restart, jr2 pushes only that same commit
+again. With `sign` or `squash`, the commit on the remote is not the Agent's own. Then jr2 moves
+the Agent's branch to it.
+
+Every outcome is output (`PushOutput`): `pushed`, `rejected`, `diverged` or `unknown`. Each
+field of [`PushOptions`](type-pushoptions.md) tells what it refuses. When it starts, it also refuses a push
+outside a Workspace: `push "<slot>" runs in the Sandbox Effector of a Workspace, and its state is
+not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`.
+
+**Parameters**
+
+- `options` ([`PushOptions`](type-pushoptions.md)): Optional. Each field tells what it does.
+
+**Returns**: An Effect, for `actors`.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  agent,
+  defineEvent,
+  fail,
+  jr2Setup,
+  push,
+  workspace,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const committed = defineEvent({
+  name: "committed",
+  description: "Say that the fix is committed.",
+  input: z.object({}),
+});
+
+type Input = Workspaced<{}, "app">;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  events: [committed],
+  actors: {
+    coder: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You are a careful engineer.",
+    }),
+    publish: push({ sign: true }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "fix-test",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".failed", "agent.fault": ".failed" },
+  initial: "coding",
+  states: {
+    coding: {
+      invoke: { src: "coder", input: { prompt: "Fix the failing test, and commit the fix." } },
+      // The Agent moves the Machine on with a pick. An Agent's actor never ends, so `onDone`
+      // never fires.
+      on: { committed: "publishing" },
+    },
+    publishing: {
+      invoke: {
+        src: "publish",
+        onDone: [
+          { guard: ({ event }) => event.output.outcome === "pushed", target: "done" },
+          { target: "failed" },
+        ],
+      },
+    },
+    done: { type: "final" },
+    // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
+    failed: { invoke: { src: "fail", input: { reason: "the fix was not pushed" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  spec: () => ({ branch: "fix-test" }),
+});
+```
+
+**See also**
+
+- [Push and sign a branch](../../guides/push-and-sign-a-branch.md)
+- [Effects](../../concepts/effects.md)
+- [Give the cluster git credentials](../../guides/give-the-cluster-git-credentials.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)
+- [ADR-0051: A Repo is a slot on the `workspace()` and a cache on the node](../decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)

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

@@ -0,0 +1,118 @@
+---
+title: secret
+description: "Name an Effect secret: `secret(\"jira\")`."
+---
+
+# `secret`
+
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+## Overload 1
+
+```ts
+function secret(name: string): Secret
+```
+
+Name an Effect secret: `secret("jira")`. The name is the `name` of an entry in the `secrets`
+list of `jr2.config.ts`. The Effector reads the value and puts it into the call, or into the env
+of a `command`. The Agent never reads it, and the Orchestrator never holds it.
+
+Use it in `bearer`, `basic` or `text`, or in the `env` of a `command`. In an `env`,
+`secret("x")` gives the value, and `secret("x").path` gives the path of a file that holds the
+value.
+
+`secret(open)` leaves the name to the composer of a packaged Machine, who binds it one time:
+`customize(machine, { effects: { <slot>: { secret: "<name>" } } })`. An Effect can have one Open
+secret, in its `auth`, a header or its `env`. A url cannot have one: leave the whole url Open
+(`url: open`) instead.
+
+It refuses, when you call it:
+- a name that is not letters, digits, `.`, `_` and `-`, that starts with `.`, or that is longer
+  than 253 characters: `secret("<name>"): a secret's name is letters, digits, ".", "_" and "-",
+  and does not start with "." — it is the file the Effector reads it from (ADR-0068)`
+- an Effect that names `secret(open)` in two places that are two secrets: `an Effect takes one
+  Open secret — it names secret(open) in two places that are two secrets; name one secret(open)
+  and use it in each place, or name the others with secret("<name>") (ADR-0054)`
+- `secret(open)` in a url: ``secret(open) in a url: a url's secret is not an Open part — leave
+  the whole url Open (`url: open`) and let the composer bind it with its secret in its path
+  (ADR-0054)``
+
+And at `jr2 up`:
+- a name that the `secrets` list does not have: ``workflow "<workflow>": the <kind> Effect
+  "<slot>" names secret("<name>"), which the `secrets` list does not hold — add it: secrets: [{
+  name: "<name>", value: process.env.<NAME> }] (ADR-0068)``
+- a value of fewer than 8 characters: `secrets[<i>] (<name>) is an Effect secret shorter than 8
+  characters — the Effector replaces every match of a secret in what it returns, and a value
+  this short would match ordinary text. Use the whole credential; the value itself is not shown
+  (ADR-0068)`
+
+**Parameters**
+
+- `name`: The name of an entry in the `secrets` list.
+
+**Returns**: The Effect secret, for an Effect. Its `.path` names the file of the secret, for the
+`env` of a `command`.
+
+**Example**
+
+```ts
+import { command, fail, jr2Setup, secret, workspace, type Workspaced } from "@jr2/orchestrator";
+
+type Input = Workspaced<{}, "app">;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  actors: {
+    // The command reads the file at $KUBECONFIG. The Agent never reads the secret.
+    deploy: command(["kubectl", "apply", "-f", "k8s/"], {
+      env: { KUBECONFIG: secret("kube").path },
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "deploy",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "deploying",
+  states: {
+    deploying: { invoke: { src: "deploy", onDone: "done" } },
+    done: { type: "final" },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+  spec: () => ({ branch: "deploy" }),
+});
+```
+
+**See also**
+
+- [Secrets and trust](../../concepts/secrets-and-trust.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
+- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)
+
+## Overload 2
+
+```ts
+function secret(name: typeof open): OpenSecret
+```
+
+Leave an Effect secret Open: `secret(open)`, in a Machine that you publish as a package. The
+composer binds its name one time: `customize(machine, { effects: { <slot>: { secret: "<name>"
+} } })`. `secret` tells the rest, and what it refuses.
+
+**Parameters**
+
+- `name`: `open`.
+
+**Returns**: The Open secret, for an Effect. Its `.path` names the file of the secret, for the `env`
+of a `command`.
+
+**See also**
+
+- [Secrets and trust](../../concepts/secrets-and-trust.md)
+- [Bind a shipped Machine's Open parts](../../guides/bind-open-parts.md)
+- [ADR-0054: The kit ships Machines, and a shipped Machine leaves its parts Open](../decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md)

package/docs/reference/authoring-surface/sentby.md

@@ -0,0 +1,83 @@
+---
+title: sentBy
+description: "A guard that is true for an event that one party sent, and false for an event that another party sent: `guard: sentBy(\"coder\")`."
+---
+
+# `sentBy`
+
+Function, in `@jr2/orchestrator/src/party.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+
+```ts
+function sentBy<const Id extends string>(id: Id): { type: typeof SENT_BY; params: { id: Id } }
+```
+
+A guard that is true for an event that one party sent, and false for an event that another party
+sent: `guard: sentBy("coder")`. Use it where two parties may send the same event to one state,
+and the transition must run for one of them only. It is also true for an event that the Machine
+sends itself, which has no sender.
+
+It can only make a transition decline the events of other parties. It never lets a party send
+an event that the party may not send at that state: the position of the `on` key decides that.
+When the guard is false, xstate tries the next transition for the event, as for any guard. Use
+it alone, or inside `and([…])`.
+
+`createMachine` refuses an id that is not a party of the Machine: ``machine "<id>":
+sentBy("<party>") on "<event>" at "<state>" names no party of this Machine (Agent slots:
+<slots>; Gate invoke ids: <ids>)``
+
+**Parameters**
+
+- `id`: The party: the slot key of an Agent of this Machine, or the invoke `id` of one of its
+  Gates.
+
+**Returns**: A named guard object, for a transition's `guard`.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, sentBy } from "@jr2/orchestrator";
+
+const done = defineEvent({
+  name: "done",
+  description: "Call this when the draft is ready for review.",
+  input: z.object({}),
+});
+
+export const machine = jr2Setup({
+  events: [done],
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You write release notes.",
+      workspace: "none",
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "notes",
+  on: { "agent.fault": ".failed" },
+  initial: "drafting",
+  states: {
+    drafting: {
+      invoke: [
+        { src: "writer", input: { prompt: "Draft the release notes." } },
+        { src: "gate", id: "editor" },
+      ],
+      on: {
+        // The writer's `done` goes to review; the editor's `done` skips it.
+        done: [{ guard: sentBy("writer"), target: "review" }, { target: "published" }],
+      },
+    },
+    review: { invoke: { src: "gate" }, on: { done: "published" } },
+    published: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**See also**
+
+- [The Menu](../../concepts/the-menu.md)
+- [Gates](../../concepts/gates.md)
+- [ADR-0015: Workflows are authored through `jr2Setup`; vocabulary and agent menus derive from the machine](../decisions/0015-authoring-surface-absorbs-the-mechanism.md)

package/docs/reference/authoring-surface/source.md

@@ -0,0 +1,51 @@
+---
+title: source
+description: "Declare a Source: where a `pool()` gets its work items, one at a time."
+---
+
+# `source`
+
+Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+
+```ts
+function source<T>(spec: SourceSpec<T>): SourceSpec<T>
+```
+
+Declare a Source: where a `pool()` gets its work items, one at a time. It gives back the spec
+that you pass. The item type `T` types what `next` gives. `pool()` does not carry `T` to
+`itemId` and `itemInput`, so write the item type on their parameter, as the `pool()` example does.
+
+**Parameters**
+
+- `spec`: How to claim the next item, and when to look again. See [`SourceSpec`](type-sourcespec.md).
+
+**Returns**: The same spec.
+
+**Example**
+
+```ts
+import { fromPromise } from "xstate";
+import { source } from "@jr2/orchestrator";
+
+type Issue = { id: string; title: string };
+
+const backlog: Issue[] = [
+  { id: "ISSUE-1", title: "Fix the greeting." },
+  { id: "ISSUE-2", title: "Add a --name flag." },
+];
+
+export const issues = source<Issue>({
+  next: fromPromise(async ({ input }: { input: { active: string[] } }) => {
+    const issue = backlog.find((i) => !input.active.includes(i.id)) ?? null;
+    if (issue) backlog.splice(backlog.indexOf(issue), 1);
+    return issue;
+  }),
+  pollEvery: 60_000,
+});
+```
+
+**See also**
+
+- [Run one worker per item](../../guides/run-one-worker-per-item.md)
+- [Pools and Sources](../../concepts/pools-and-sources.md)
+- [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)

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

@@ -0,0 +1,62 @@
+---
+title: text
+description: "Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret(\"x\")}` ``."
+---
+
+# `text`
+
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function text<
+  const V extends Array<Secret | OpenSecret | string>,
+>(
+  strings: TemplateStringsArray,
+  ...values: V,
+): MarkedIf<V[number], Text>
+```
+
+Make a string from literal text and Effect secrets, as a tagged template:
+`` text`Token ${secret("x")}` ``. The Effector puts in the value of each secret when it makes
+the call. Use it for a url with a secret in its path, or for a header value. Use it also for
+`auth`, where it is the whole `Authorization` header, or for a part of `basic`.
+
+It refuses a `${…}` that is not a `secret(...)` or a string: `` text`…`: a value is a
+secret("name") or a string, got <value> ``.
+
+**Parameters**
+
+- `strings`: The literal text of the template.
+- `values`: The `${…}` values, each a `secret(...)` or a string.
+
+**Returns**: The string, which the Effector makes.
+
+**Example**
+
+```ts
+import { http, jr2Setup, secret, text } from "@jr2/orchestrator";
+
+export const machine = jr2Setup({
+  actors: {
+    notify: http({
+      method: "POST",
+      url: text`https://api.telegram.org/bot${secret("telegram")}/sendMessage`,
+      headers: { "x-run-source": text`jr2` },
+      request: () => ({ json: { chat_id: "12345", text: "The run is done." } }),
+    }),
+  },
+}).createMachine({
+  id: "notify",
+  initial: "notifying",
+  states: {
+    notifying: { invoke: { src: "notify", onDone: "done" } },
+    done: { type: "final" },
+  },
+});
+```
+
+**See also**
+
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [Secrets and trust](../../concepts/secrets-and-trust.md)
+- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)

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

@@ -0,0 +1,27 @@
+---
+title: AgentDeclaration
+description: "What `agent()` takes: an `AgentDefinition`, except that `model` can also be `open`."
+---
+
+# `AgentDeclaration`
+
+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 AgentDeclaration = Omit<AgentDefinition, "model"> & {
+  model: string | typeof open;
+};
+```
+
+What `agent()` takes: an [`AgentDefinition`](type-agentdefinition.md), except that `model` can also be `open`.
+
+**Fields**: each field of [`AgentDefinition`](type-agentdefinition.md), except `model`, and these:
+
+- `model`: `string | typeof open`
+
+  The model, as `<provider>/<modelId>`: for example `anthropic/claude-haiku-5-5`. Required:
+  there is no default model. The provider must be one that `jr2.config.ts` can reach.
+
+  Or `open`, in a Machine that you publish as a package. Then the Instance that registers the
+  Machine binds the model with `customize()`. One Turn may set another model in the invoke's
+  `input`.