Appearance

Authoring surface ​

The 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, ADR-0015).

  • defineEvent (function): Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine.
  • jr2Setup (function): Set up a Machine that takes workflow events: the jr2 form of xstate's setup().
  • sentBy (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 (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).

  • fail (function): Fail the run: the Part a Machine invokes to end work that did not succeed.
  • isFailure (function): Is this error a Failure, which a state invoked fail to make?

Agents ​

An Agent slot and the definition it carries (ADR-0028, ADR-0049).

  • agent (function): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
  • AgentDefinition (type): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
  • ThinkingLevel (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, ADR-0051).

  • workspace (function): Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one branch.
  • Workspaced (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 (type): The repository of a Repo Slot: { url, ref }.
  • RepoSlot (type): The value of one Repo Slot in workspace({ repos }).

Effects ​

Work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071), and what an author writes between a pick and that work.

  • arg (constant): Mark one argv entry of a command that the input of the Effect fills.
  • CommandOutput (type): The output of a command Effect: what the onDone of its state gets as event.output.
  • command (function): Make a command Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
  • basic (function): Make the auth of an http Effect that sends Authorization: Basic <value>, where the value is the base64 of user:password.
  • bearer (function): Make the auth of an http Effect that sends Authorization: Bearer <value>, with the value of an Effect secret.
  • file (function): Make a Worktree file the body of an http Effect: body: file("dist/report.pdf").
  • http (function): Make an http Effect: a call to a URL, with Effect secrets that the Agent never reads.
  • secret (function): Name an Effect secret: secret("jira").
  • text (function): Make a string from literal text and Effect secrets, as a tagged template: text`Token ${secret("x")}`.
  • HttpOutput (type): The output of an http Effect: what the onDone of its state gets as event.output.
  • push (function): Make a push Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
  • PushOutput (type): The output of a push Effect: what the onDone of its state gets as event.output.
  • dispatch (function): Make a dispatch Effect: it starts a run of a Workflow.
  • DispatchOutput (type): The output of a dispatch Effect.
  • answer (function): Set what the Agent reads when jr2 answers its pick.
  • fromPick (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 (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, ADR-0049, ADR-0054, ADR-0060).

  • open (constant): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with customize().
  • customize (function): Retune the parts that a Machine carries, without a change to the module that exports it.
  • Customize (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 (type): The values that bind the Open parts of one Effect.
  • Size (type): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
  • UserContainer (type): The User Container in its object form: its image, and its part of the Workspace's Size.
  • pool (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 (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).

  • openBody (function): Make an Open body: the actor slot that a Chart binds.
  • OpenBodyDeclaration (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 (type): The output of an Open body.
  • chartSchema (constant): The Chart grammar, as a zod schema.
  • chartSchemaFor (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).

  • defineConfig (function): Declare the config of an Instance: the default export of jr2.config.ts.
  • JR2Config (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: How the party that sends an event gets its answer.
  • EventAudience: Who may send an event: "agent" (an Agent, as a pick from its Menu), "external" (the caller of a Gate), or "any" (both).
  • EventDef: A workflow event, as defineEvent gives it back: plain, frozen data and a zod schema, safe to import anywhere.
  • WorkflowEvent: The type of event in a Machine that jr2Setup makes: each workflow event in its events, and each Mechanism event.
  • FailSlot: The logic fail() returns: failLogic with the brand the walk reads.
  • Failure: A Failure as isFailure narrows an error to it: the payload's fields, on the error itself.
  • AgentDeclaration: What agent() takes: an AgentDefinition, except that model can also be open.
  • WorkspaceAccess: What an Agent may do to the Workspace: "write", "read" or "none".
  • WorkspaceOptions: The options of a workspace() that declares the input that starts a run.
  • NoSlotWorkspaceOptions: The options of a workspace() with no Repo Slot that declares the input that starts a run.
  • WithoutEmptyIndex: The fields of the run input T.
  • PermissiveWorkspaceOptions: The options of a workspace() with no input: it starts with any input.
  • PermissiveNoSlotWorkspaceOptions: The options of a workspace() with no Repo Slot and no input: it starts with any input.
  • WorkspaceHandles: What the body of a workspace() gets as input.workspace: the path of each Worktree, and the branch.
  • ExecOutcome: How an exec ended.
  • Unknown: The output { outcome: "unknown", reason }: the Effect may have acted, and jr2 cannot tell.
  • Arg: One entry of a command's argv that the input of the Effect fills, as arg("name") makes it.
  • CommandOptions: 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: A command's input: one string per argv slot, and with pin the approved commit ({ sha }); none when there is neither.
  • OpenCommandInput: 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: What secret("name") gives: an Effect secret, by its name in the secrets list of jr2.config.ts.
  • Text: What the text template gives: a string of literal text and Effect secrets, in order.
  • FromInput: A value of a file body's part: as written, or from the Effect's input.
  • FileBody: file(path, { slot?, segments?, contentType? }): a Worktree file as an http body.
  • HttpDefinition: An http Effect's definition.
  • OpenSecret: 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: The options of push().
  • PushInput: The input of a push Effect: { sha } with pin, and { message } with squash.
  • DispatchDefinition: The definition of a dispatch Effect (ADR-0071).
  • DispatchInput: A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
  • DispatchOpenParts: The Open part a dispatch definition states: its target, when it is open.
  • ChainLink: 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: A Kubernetes quantity: "2Gi", "1500m", "2", or a plain number (2 cpus, bytes of memory).
  • PoolSpec: What you pass to pool(): where the items come from, how many workers run at once, and what each worker gets.
  • SourceSpec: Where a Pool gets its work items: the Source.
  • OpenBodyLogic: The logic openBody() returns: actor logic that carries the brand.
  • Lends: The parts of the Chart wrapper that a Chart can use, by their keys in actors, guards, actions and delays.
  • Ceilings: The limits that an Open body sets on its Chart.
  • ChartText: The Chart text (ADR-0070).
  • Sender: Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
  • FailureInput: What a Failure carries: reason, text for a person, and detail, optional JSON for a machine reader.
  • SandboxOptions: The options of a workspace() that say what its Sandbox is made of and which Repos it clones.
  • WorkspaceSpec: What the spec of a workspace() returns: the branch that the Workspace works on, and two optional fields.
  • NoSlotSpec: What the spec of a workspace() with no Repo Slot returns: only workGroup.
  • SlotHandles: The handles of a Workspace that declares Repo Slots.
  • Duration: A length of time: a positive number and a unit, s, m or h.
  • CommandEnv: 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: One part of a Text: { text }, literal text, or { secret }, the name of an Effect secret.
  • HttpMethod: The method of an http Effect: GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS.
  • HttpRequestParts: What the request of an http definition returns: the part of the request that changes for each run.
  • NamedSecret: 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: 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: The brand an Open body slot carries, as definition marks an Agent slot (ADR-0049).
  • ChartJson: Plain JSON.
  • ChartEvent: An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
  • ChartAgent: An Agent a Chart mints: the plain fields of an Agent definition (ADR-0049).
  • ChartState: A state node.
  • ChartValue: A value whose strings may hold {{<root>.<path>}} placeholders and whose objects may be { "$ref": "<root>.<path>" }.
  • ChartInvoke: An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's gate or fail.
  • ChartTransitions: One transition or a list, in xstate's order.
  • ChartAction: An action.
  • ChartTransition: A transition: a target alone, or the object form.
  • ChartGuard: 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:

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.

The docs of Kit version 0.5.1. Each page is also at its .md URL.