---
title: Authoring surface
description: "Every name that @jr2/orchestrator exports from its root, by group, with a link to its page: its signature, its TSDoc, and an example."
---

# Authoring surface

The [Authoring surface](glossary.md#authoring-surface) is every name that `@jr2/orchestrator` exports from its root, and nothing else: a workflow module and `jr2.config.ts` import only these names. The groups and their order are those of the root's `src/index.ts`. This page gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in `authoring-surface/`, with the file that declares it, its signature, and its TSDoc.

## Machine and events

The setup a workflow writes its Machine with, the events its parties send, and the guard that makes a writing decline other senders ([ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0015](decisions/0015-authoring-surface-absorbs-the-mechanism.md)).

- [`defineEvent`](authoring-surface/defineevent.md) (function): Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine.
- [`jr2Setup`](authoring-surface/jr2setup.md) (function): Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`.
- [`sentBy`](authoring-surface/sentby.md) (function): A guard that is true for an event that one party sent, and false for an event that another party sent: `guard: sentBy("coder")`.
- [`HostInjectedInput`](authoring-surface/type-hostinjectedinput.md) (type): The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.

## Failure

The Part a Machine invokes to fail its run, and the guard that tells a Failure from a defect in an `onError` ([ADR-0073](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md)).

- [`fail`](authoring-surface/fail.md) (function): Fail the run: the Part a Machine invokes to end work that did not succeed.
- [`isFailure`](authoring-surface/isfailure.md) (function): Is this error a Failure, which a state invoked `fail` to make?

## Agents

An Agent slot and the definition it carries ([ADR-0028](decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md), [ADR-0049](decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)).

- [`agent`](authoring-surface/agent.md) (function): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
- [`AgentDefinition`](authoring-surface/type-agentdefinition.md) (type): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
- [`ThinkingLevel`](authoring-surface/type-thinkinglevel.md) (type): How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` or `"xhigh"`.

## Workspaces and Repos

A Sandbox and the Repo Slots it binds ([ADR-0012](decisions/0012-workspace-wrapper-machine.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)).

- [`workspace`](authoring-surface/workspace.md) (function): Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one branch.
- [`Workspaced`](authoring-surface/type-workspaced.md) (type): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, `workspace.branch`, `workspace.review`).
- [`Binding`](authoring-surface/type-binding.md) (type): The repository of a Repo Slot: `{ url, ref }`.
- [`RepoSlot`](authoring-surface/type-reposlot.md) (type): The value of one Repo Slot in `workspace({ repos })`.

## Effects

Work a Machine does outside itself, as an actor slot ([ADR-0067](decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md), [ADR-0068](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md), [ADR-0071](decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md)), and what an author writes between a pick and that work.

- [`arg`](authoring-surface/arg.md) (constant): Mark one argv entry of a `command` that the input of the Effect fills.
- [`CommandOutput`](authoring-surface/type-commandoutput.md) (type): The output of a `command` Effect: what the `onDone` of its state gets as `event.output`.
- [`command`](authoring-surface/command.md) (function): Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
- [`basic`](authoring-surface/basic.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`.
- [`bearer`](authoring-surface/bearer.md) (function): Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret.
- [`file`](authoring-surface/file.md) (function): Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`.
- [`http`](authoring-surface/http.md) (function): Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads.
- [`secret`](authoring-surface/secret.md) (function): Name an Effect secret: `secret("jira")`.
- [`text`](authoring-surface/text.md) (function): Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret("x")}` ``.
- [`HttpOutput`](authoring-surface/type-httpoutput.md) (type): The output of an `http` Effect: what the `onDone` of its state gets as `event.output`.
- [`push`](authoring-surface/push.md) (function): Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
- [`PushOutput`](authoring-surface/type-pushoutput.md) (type): The output of a `push` Effect: what the `onDone` of its state gets as `event.output`.
- [`dispatch`](authoring-surface/dispatch.md) (function): Make a `dispatch` Effect: it starts a run of a Workflow.
- [`DispatchOutput`](authoring-surface/type-dispatchoutput.md) (type): The output of a `dispatch` Effect.
- [`answer`](authoring-surface/answer.md) (function): Set what the Agent reads when jr2 answers its pick.
- [`fromPick`](authoring-surface/frompick.md) (function): Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the input of the invoked actor by name.
- [`paramsOf`](authoring-surface/paramsof.md) (function): Read the params of a pick from the event that entered the state.

## Composition

A part left Open, a Machine's parts retuned, a Pool over a Source ([ADR-0017](decisions/0017-pool-over-a-source-port.md), [ADR-0049](decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md), [ADR-0054](decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md), [ADR-0060](decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)).

- [`open`](authoring-surface/open.md) (constant): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`.
- [`customize`](authoring-surface/customize.md) (function): Retune the parts that a Machine carries, without a change to the module that exports it.
- [`Customize`](authoring-surface/type-customize.md) (type): The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the Machines it composes, and the Sandbox of its `workspace()`.
- [`EffectBinding`](authoring-surface/type-effectbinding.md) (type): The values that bind the Open parts of one Effect.
- [`Size`](authoring-surface/type-size.md) (type): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
- [`UserContainer`](authoring-surface/type-usercontainer.md) (type): The User Container in its object form: its image, and its part of the Workspace's Size.
- [`pool`](authoring-surface/pool.md) (function): Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once.
- [`source`](authoring-surface/source.md) (function): Declare a Source: where a `pool()` gets its work items, one at a time.

## Charts

The Open body a Chart wrapper places in `actors`, and the grammar a planner's pick declares, whole or narrowed to one wrapper ([ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md)).

- [`openBody`](authoring-surface/openbody.md) (function): Make an Open body: the actor slot that a Chart binds.
- [`OpenBodyDeclaration`](authoring-surface/type-openbodydeclaration.md) (type): What an Open body declares: the parts that it lends a Chart, what the Agents of a Chart can have, and the limits of a Chart.
- [`OpenBodyOutput`](authoring-surface/type-openbodyoutput.md) (type): The output of an Open body.
- [`chartSchema`](authoring-surface/chartschema.md) (constant): The Chart grammar, as a zod schema.
- [`chartSchemaFor`](authoring-surface/chartschemafor.md) (function): The Chart grammar for one Open body, as a zod schema.

## Config

`jr2.config.ts`, the deployment facts a Machine cannot carry ([ADR-0050](decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)).

- [`defineConfig`](authoring-surface/defineconfig.md) (function): Declare the config of an Instance: the default export of `jr2.config.ts`.
- [`JR2Config`](authoring-surface/type-jr2config.md) (type): The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.

## Types these signatures name

The signature of an export, or a type here, names each of these types. They are not exports of `@jr2/orchestrator`, so a workflow module does not import them by name.

- [`EventSemantics`](authoring-surface/type-eventsemantics.md): How the party that sends an event gets its answer.
- [`EventAudience`](authoring-surface/type-eventaudience.md): Who may send an event: `"agent"` (an Agent, as a pick from its Menu), `"external"` (the caller of a Gate), or `"any"` (both).
- [`EventDef`](authoring-surface/type-eventdef.md): A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere.
- [`WorkflowEvent`](authoring-surface/type-workflowevent.md): The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event.
- [`FailSlot`](authoring-surface/type-failslot.md): The logic `fail()` returns: `failLogic` with the brand the walk reads.
- [`Failure`](authoring-surface/type-failure.md): A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
- [`AgentDeclaration`](authoring-surface/type-agentdeclaration.md): What `agent()` takes: an `AgentDefinition`, except that `model` can also be `open`.
- [`WorkspaceAccess`](authoring-surface/type-workspaceaccess.md): What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`.
- [`WorkspaceOptions`](authoring-surface/type-workspaceoptions.md): The options of a `workspace()` that declares the input that starts a run.
- [`NoSlotWorkspaceOptions`](authoring-surface/type-noslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
- [`WithoutEmptyIndex`](authoring-surface/type-withoutemptyindex.md): The fields of the run input `T`.
- [`PermissiveWorkspaceOptions`](authoring-surface/type-permissiveworkspaceoptions.md): The options of a `workspace()` with no `input`: it starts with any input.
- [`PermissiveNoSlotWorkspaceOptions`](authoring-surface/type-permissivenoslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
- [`WorkspaceHandles`](authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the branch.
- [`ExecOutcome`](authoring-surface/type-execoutcome.md): How an exec ended.
- [`Unknown`](authoring-surface/type-unknown.md): The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
- [`Arg`](authoring-surface/type-arg.md): One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it.
- [`CommandOptions`](authoring-surface/type-commandoptions.md): The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its output it keeps, its Effect secrets, and the commit it runs against.
- [`CommandInput`](authoring-surface/type-commandinput.md): A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`); none when there is neither.
- [`OpenCommandInput`](authoring-surface/type-opencommandinput.md): The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds, and with `pin`, the commit (`{ sha }`).
- [`Secret`](authoring-surface/type-secret.md): What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`.
- [`Text`](authoring-surface/type-text.md): What the `text` template gives: a string of literal text and Effect secrets, in order.
- [`FromInput`](authoring-surface/type-frominput.md): A value of a file body's part: as written, or from the Effect's input.
- [`FileBody`](authoring-surface/type-filebody.md): `file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
- [`HttpDefinition`](authoring-surface/type-httpdefinition.md): An `http` Effect's definition.
- [`OpenSecret`](authoring-surface/type-opensecret.md): `secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and leaves for its composer to name (ADR-0054).
- [`PushOptions`](authoring-surface/type-pushoptions.md): The options of `push()`.
- [`PushInput`](authoring-surface/type-pushinput.md): The input of a `push` Effect: `{ sha }` with `pin`, and `{ message }` with `squash`.
- [`DispatchDefinition`](authoring-surface/type-dispatchdefinition.md): The definition of a `dispatch` Effect (ADR-0071).
- [`DispatchInput`](authoring-surface/type-dispatchinput.md): A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
- [`DispatchOpenParts`](authoring-surface/type-dispatchopenparts.md): The Open part a dispatch definition states: its target, when it is `open`.
- [`ChainLink`](authoring-surface/type-chainlink.md): One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's pick — typed by the Machine's events.
- [`Quantity`](authoring-surface/type-quantity.md): A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory).
- [`PoolSpec`](authoring-surface/type-poolspec.md): What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets.
- [`SourceSpec`](authoring-surface/type-sourcespec.md): Where a Pool gets its work items: the Source.
- [`OpenBodyLogic`](authoring-surface/type-openbodylogic.md): The logic `openBody()` returns: actor logic that carries the brand.
- [`Lends`](authoring-surface/type-lends.md): The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`, `actions` and `delays`.
- [`Ceilings`](authoring-surface/type-ceilings.md): The limits that an Open body sets on its Chart.
- [`ChartText`](authoring-surface/type-charttext.md): The Chart text (ADR-0070).
- [`Sender`](authoring-surface/type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
- [`FailureInput`](authoring-surface/type-failureinput.md): What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader.
- [`SandboxOptions`](authoring-surface/type-sandboxoptions.md): The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
- [`WorkspaceSpec`](authoring-surface/type-workspacespec.md): What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields.
- [`NoSlotSpec`](authoring-surface/type-noslotspec.md): What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`.
- [`SlotHandles`](authoring-surface/type-slothandles.md): The handles of a Workspace that declares Repo Slots.
- [`Duration`](authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
- [`CommandEnv`](authoring-surface/type-commandenv.md): The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a file that holds it.
- [`TextPart`](authoring-surface/type-textpart.md): One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret.
- [`HttpMethod`](authoring-surface/type-httpmethod.md): The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.
- [`HttpRequestParts`](authoring-surface/type-httprequestparts.md): What the `request` of an `http` definition returns: the part of the request that changes for each run.
- [`NamedSecret`](authoring-surface/type-namedsecret.md): A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present.
- [`SourceNextResult`](authoring-surface/type-sourcenextresult.md): 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.
- [`OpenBodySlot`](authoring-surface/type-openbodyslot.md): The brand an Open body slot carries, as `definition` marks an Agent slot (ADR-0049).
- [`ChartJson`](authoring-surface/type-chartjson.md): Plain JSON.
- [`ChartEvent`](authoring-surface/type-chartevent.md): An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
- [`ChartAgent`](authoring-surface/type-chartagent.md): An Agent a Chart mints: the plain fields of an Agent definition (ADR-0049).
- [`ChartState`](authoring-surface/type-chartstate.md): A state node.
- [`ChartValue`](authoring-surface/type-chartvalue.md): A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be `{ "$ref": "<root>.<path>" }`.
- [`ChartInvoke`](authoring-surface/type-chartinvoke.md): An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`.
- [`ChartTransitions`](authoring-surface/type-charttransitions.md): One transition or a list, in xstate's order.
- [`ChartAction`](authoring-surface/type-chartaction.md): An action.
- [`ChartTransition`](authoring-surface/type-charttransition.md): A transition: a target alone, or the object form.
- [`ChartGuard`](authoring-surface/type-chartguard.md): A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or `not`/`and`/`or`.

**Type plumbing.** These types compute a type from the types of a Machine or of its parts. A workflow module does not write them. Each has a page with its declaration:

- [`ToProvidedActor`](authoring-surface/type-toprovidedactor.md)
- [`MergedActors`](authoring-surface/type-mergedactors.md)
- [`ToParameterizedObject`](authoring-surface/type-toparameterizedobject.md)
- [`SentByGuards`](authoring-surface/type-sentbyguards.md)
- [`AgentLogic`](authoring-surface/type-agentlogic.md)
- [`BodyAcceptsDoor`](authoring-surface/type-bodyacceptsdoor.md)
- [`WorkspaceMachine`](authoring-surface/type-workspacemachine.md)
- [`BodyAcceptsSlots`](authoring-surface/type-bodyacceptsslots.md)
- [`EffectLogic`](authoring-surface/type-effectlogic.md)
- [`OpenOf`](authoring-surface/type-openof.md)
- [`EnvOpenParts`](authoring-surface/type-envopenparts.md)
- [`OpenEffect`](authoring-surface/type-openeffect.md)
- [`MarkedIf`](authoring-surface/type-markedif.md)
- [`HttpInput`](authoring-surface/type-httpinput.md)
- [`HttpOpenParts`](authoring-surface/type-httpopenparts.md)
- [`PushWireOutput`](authoring-surface/type-pushwireoutput.md)
- [`SyncState`](authoring-surface/type-syncstate.md)
- [`AnswerAction`](authoring-surface/type-answeraction.md)
- [`AgentSlots`](authoring-surface/type-agentslots.md)
- [`Reached`](authoring-surface/type-reached.md)
- [`OpenEffectSlots`](authoring-surface/type-openeffectslots.md)
- [`BindingOf`](authoring-surface/type-bindingof.md)
- [`LogicAt`](authoring-surface/type-logicat.md)
- [`ChildSlots`](authoring-surface/type-childslots.md)
- [`ChildAt`](authoring-surface/type-childat.md)
- [`RepoSlotsOf`](authoring-surface/type-reposlotsof.md)
- [`WorkspaceOf`](authoring-surface/type-workspaceof.md)
- [`PoolMachine`](authoring-surface/type-poolmachine.md)
- [`EventFrom`](authoring-surface/type-eventfrom.md)
- [`ArgNames`](authoring-surface/type-argnames.md)
- [`OpenSecretMark`](authoring-surface/type-opensecretmark.md)

These names come from a dependency: from `zod`, `z.ZodObject`, `z.infer`, `z.ZodType`; from `xstate`, `MachineContext`, `UnknownActorLogic`, `ParameterizedObject`, `NonReducibleUnknown`, `EventObject`, `MetaObject`, `ActionFunction`, `GuardPredicate`, `DelayConfig`, `SetupReturn`, `AnyStateMachine`, `OutputFrom`, `ProvidedActor`, `AnyActorRef`, `InputFrom`, `PromiseActorLogic`.