@jr2/orchestrator 0.4.1 → 0.5.1

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

@@ -0,0 +1,45 @@
+---
+title: EventDef
+description: "A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere."
+---
+
+# `EventDef`
+
+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 EventDef<Name extends string = string, Input extends z.ZodObject = z.ZodObject> = {
+  readonly name: Name;
+  readonly description?: string;
+  readonly input: Input;
+  readonly semantics: EventSemantics;
+  readonly audience?: EventAudience;
+};
+```
+
+A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to
+import anywhere. Give it to `jr2Setup({ events })`. A Machine accepts only the events in that
+list.
+
+**Fields**
+
+- `name`: `Name`
+
+  The event's name: its xstate event `type`, and the name of its tool on the Agent's Menu.
+- `description` (optional): `string`
+
+  What the event means. An Agent's model reads it as the tool's description.
+- `input`: `Input`
+
+  The schema of the event's payload: a flat `z.object`, never a union.
+- `semantics`: [`EventSemantics`](type-eventsemantics.md)
+
+  How the sender gets its answer: always `"ack"` on an event that `createMachine` accepts.
+- `audience` (optional): [`EventAudience`](type-eventaudience.md)
+
+  Who may send the event. Absent: the state of each `on` key decides (see [`EventAudience`](type-eventaudience.md)).
+
+**See also**
+
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [ADR-0011: Control events are workflow-defined and delivered by closure, not routed](../decisions/0011-workflow-defined-events.md)

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

@@ -0,0 +1,16 @@
+---
+title: EventFrom
+description: A type that the Authoring surface names.
+---
+
+# `EventFrom`
+
+Type, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. 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 EventFrom<D extends EventDef> =
+  D extends EventDef<infer N, infer I>
+    ?
+      { type: N } & (z.infer<I> extends Record<string, never> ? unknown : z.infer<I>)
+    : never;
+```

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

@@ -0,0 +1,26 @@
+---
+title: EventSemantics
+description: How the party that sends an event gets its answer.
+---
+
+# `EventSemantics`
+
+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 EventSemantics = "ack" | "poll";
+```
+
+How the party that sends an event gets its answer.
+
+- `"ack"`, the default: jr2 delivers the event and answers the sender. When the event starts
+  work inside the Agent's state, the answer comes when that work is done.
+- `"poll"`: reserved. `createMachine` refuses it: ``machine "<id>": event "<name>" is `poll`,
+  which is reserved but NOT IMPLEMENTED (ADR-0013). Only `ack` events can be delivered today;
+  nothing drains a steer inbox, and degrading it to `ack` would hand the Agent a lying tool
+  contract.``
+
+**See also**
+
+- [The Menu](../../concepts/the-menu.md)
+- [ADR-0006: The agent picks from a Machine-defined, schema-backed menu; it does not drive the workflow](../decisions/0006-agent-control-surface.md)

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

@@ -0,0 +1,34 @@
+---
+title: ExecOutcome
+description: How an exec ended.
+---
+
+# `ExecOutcome`
+
+Type, in `@jr2/orchestrator/src/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 ExecOutcome =
+  | { outcome: "exited"; code: number; tail: string }
+  | { outcome: "timeout"; tail: string }
+  | { outcome: "killed"; signal: string; tail: string };
+```
+
+How an exec ended. Every one is output; none is a fault.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `code`, `tail`
+
+  - `outcome`: `"exited"`
+  - `code`: `number`
+  - `tail`: `string`
+- Form 2: `outcome`, `tail`
+
+  - `outcome`: `"timeout"`
+  - `tail`: `string`
+- Form 3: `outcome`, `signal`, `tail`
+
+  - `outcome`: `"killed"`
+  - `signal`: `string`
+  - `tail`: `string`

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

@@ -0,0 +1,14 @@
+---
+title: FailSlot
+description: "The logic `fail()` returns: `failLogic` with the brand the walk reads."
+---
+
+# `FailSlot`
+
+Type, in `@jr2/orchestrator/src/fail.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 FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL_SLOT]: true };
+```
+
+The logic `fail()` returns: `failLogic` with the brand the walk reads.

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

@@ -0,0 +1,19 @@
+---
+title: Failure
+description: "A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself."
+---
+
+# `Failure`
+
+Type, in `@jr2/orchestrator/src/fail.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 Failure = { readonly reason: string; readonly detail?: unknown };
+```
+
+A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
+
+**Fields**
+
+- `reason`: `string`
+- `detail` (optional): `unknown`

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

@@ -0,0 +1,20 @@
+---
+title: FailureInput
+description: "What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader."
+---
+
+# `FailureInput`
+
+Type, in `@jr2/orchestrator/src/fail.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 FailureInput = { reason: string; detail?: unknown };
+```
+
+What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine
+reader. The input of `fail()` and the output of a run that ends `failed`.
+
+**Fields**
+
+- `reason`: `string`
+- `detail` (optional): `unknown`

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

@@ -0,0 +1,41 @@
+---
+title: FileBody
+description: "`file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body."
+---
+
+# `FileBody`
+
+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 FileBody<S extends z.ZodType | undefined = undefined> = {
+  readonly file: {
+    readonly path: FromInput<S, string>;
+    readonly slot?: string;
+    readonly segments?: FromInput<S, readonly string[]>;
+    readonly contentType?: string;
+  };
+};
+```
+
+`file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
+
+**Fields**
+
+- `file`: `object`
+
+  - `path`: `FromInput<S, string>`
+
+    The file, relative to the Repo Slot's Worktree, or to `/work` in a Workspace with no Repo
+    Slot.
+  - `slot` (optional): `string`
+
+    The Repo Slot whose Worktree holds it. Write it only when the Workspace has more than one.
+  - `segments` (optional): `FromInput<S, readonly string[]>`
+
+    Path segments that jr2 adds to the end of the url, as `path` of `request` does for a json
+    or text body.
+  - `contentType` (optional): `string`
+
+    The content type of the body. Write it or a `content-type` header, not both. With neither,
+    it is `application/octet-stream`.

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

@@ -0,0 +1,14 @@
+---
+title: FromInput
+description: "A value of a file body's part: as written, or from the Effect's input."
+---
+
+# `FromInput`
+
+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 FromInput<S, T> = T | ((input: S extends z.ZodType ? z.infer<S> : void) => T);
+```
+
+A value of a file body's part: as written, or from the Effect's input.

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

@@ -0,0 +1,58 @@
+---
+title: HostInjectedInput
+description: The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.
+---
+
+# `HostInjectedInput`
+
+Type, in `@jr2/orchestrator/src/vocabulary.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+
+```ts
+type HostInjectedInput = { instanceId: string };
+```
+
+The fields that jr2 adds to the input of the Machine that a run starts, beside the input that
+the caller sent. Today it is one field: `instanceId`, an id that jr2 makes for the run.
+
+Add it to the type of your root Machine's input when the Machine reads it:
+`HostInjectedInput & RunInput`. Do not put it in the `input` schema that a run starts with. No
+caller sends it. jr2 writes it over any value that a caller sends.
+
+Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
+that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
+`workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`.
+
+The `spec` of a root `workspace()` also gets it, and the type of its input shows it:
+``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``.
+
+It is not the run id. Use it, for example, to give each run a branch of its own.
+
+**Fields**
+
+- `instanceId`: `string`
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { jr2Setup, type HostInjectedInput } from "@jr2/orchestrator";
+
+const runInput = z.object({ ticket: z.string() });
+type Input = HostInjectedInput & z.infer<typeof runInput>;
+
+export const machine = jr2Setup({
+  types: {} as { input: Input; context: Input; output: { run: string; ticket: string } },
+}).createMachine({
+  id: "ticket",
+  input: runInput,
+  context: ({ input }) => input,
+  initial: "done",
+  states: { done: { type: "final" } },
+  output: ({ context }) => ({ run: context.instanceId, ticket: context.ticket }),
+});
+```
+
+**See also**
+
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [ADR-0033: A Machine declares the input that starts it](../decisions/0033-a-machine-declares-the-input-that-starts-it.md)

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

@@ -0,0 +1,101 @@
+---
+title: HttpDefinition
+description: "An `http` Effect's definition."
+---
+
+# `HttpDefinition`
+
+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 HttpDefinition<S extends z.ZodType | undefined = undefined> = {
+  method: HttpMethod;
+  url: string | Text | typeof open;
+  headers?: Readonly<Record<string, string | Text>>;
+  auth?: { readonly bearer: Secret } | { readonly basic: { user: Text; password: Text } } | Text;
+  input?: S;
+  request?: (input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts;
+  body?: FileBody<S>;
+  timeout?: Duration;
+  maxBody?: number;
+  idempotent?: boolean;
+};
+```
+
+An `http` Effect's definition.
+
+**Fields**
+
+- `method`: [`HttpMethod`](type-httpmethod.md)
+
+  The HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. It refuses
+  another: `http({ method: "<method>" }): the method is one of GET, HEAD, POST, PUT, PATCH,
+  DELETE, OPTIONS`.
+- `url`: `string | Text | typeof open`
+
+  The url: `http://` or `https://`, then a literal host. No input, param or Effect secret can
+  change where the call goes. An Effect secret can be only in the path:
+  `` text`https://api.telegram.org/bot${secret("tg")}/sendMessage` ``.
+
+  Or `open`: a packaged Machine that cannot know the host leaves the url Open, and the composer
+  binds it one time with `customize(machine, { effects: { <slot>: { url } } })`.
+
+  It refuses:
+  - a scheme or host that is not literal: `` http({ url }): the url is an http:// or https:// url
+    whose scheme and host are literal — a secret may sit only in its path, after a "/":
+    text`https://api.example.com/bot${secret("tg")}/send` (ADR-0068) ``
+  - an Effect secret after `?` or `#`: `` http({ url }): secret("<name>") sits in the url's query
+    or fragment — a secret may sit only in its path; send it in `auth` or a header instead:
+    headers: { "x-api-key": text`${secret("...")}` } (ADR-0068) ``
+  - a host that is not a host: `http({ url }): "<scheme>://<host>" is not a host`
+  - a user name or password in the url: ``http({ url }): the url carries userinfo — use `auth` ``
+- `headers` (optional): `Readonly<Record<string, string | Text>>`
+
+  Headers that are the same for each run. Each name is lowercase. A value is a string, or a
+  `text` with an Effect secret.
+
+  It refuses:
+  - a name that is not lowercase, or that frames or routes the request (`host`,
+    `content-length`, `transfer-encoding`, `connection`, `upgrade`, `te`, `trailer`,
+    `keep-alive`, `proxy-*`): `http({ headers }): "<name>" is not a header an Effect sets — a
+    lowercase name that does not frame or route the request (ADR-0068)`
+  - an `authorization` header beside `auth`: ``http({ headers }): "authorization" is set by
+    `auth` — write one of them``
+- `auth` (optional): `{ readonly bearer: Secret; } | { readonly basic: { user: Text; password: Text; }; } | Text`
+
+  The `Authorization` header: `bearer(secret("x"))`, `basic(user, password)`, or a `text` that
+  is the whole value.
+- `input` (optional): `S`
+
+  The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+  gives it. jr2 parses the input with it before the call. When it starts, input that does not
+  agree with it makes the Effect fail (its `onError` route): `http "<slot>": its input does not
+  match the definition's input schema — <path>: <message>`, one `<path>: <message>` for each
+  problem, joined by `; `.
+- `request` (optional): `(input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts`
+
+  A function that makes the part of the request that changes for each run, from the input:
+  `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
+  Effect secret. Do not write it beside `body`.
+- `body` (optional): `FileBody<S>`
+
+  A Worktree file as the body: `file(path, { slot?, segments?, contentType? })`. The Effect then
+  runs in the Sandbox Effector of its Workspace. Do not write `request` beside it: the `segments`
+  of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
+  slot?, segments?, contentType? }) — json and text come from `request` ``.
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
+  `"30s"`. With no answer in that time, the output is `unknown`. It refuses a value that is not
+  a positive duration: `http: timeout "<timeout>" is not a positive duration (like "30s",
+  "2m")`.
+- `maxBody` (optional): `number`
+
+  The largest number of bytes of a text response body that the output keeps. Default 65536.
+  When jr2 cuts the body, `truncated` is `true`. It refuses a value that is not a positive whole
+  number: `http({ maxBody }): a positive number of bytes`.
+- `idempotent` (optional): `boolean`
+
+  `true` when it is safe to send the call two times: it has its own idempotency key, or it only
+  reads. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the call went
+  out. Then it sends an idempotent call again, and gives any other call the output `unknown`.

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

@@ -0,0 +1,12 @@
+---
+title: HttpInput
+description: A type that the Authoring surface names.
+---
+
+# `HttpInput`
+
+Type, in `@jr2/orchestrator/src/http-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 HttpInput<S> = S extends z.ZodType ? z.infer<S> : void;
+```

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

@@ -0,0 +1,14 @@
+---
+title: HttpMethod
+description: "The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`."
+---
+
+# `HttpMethod`
+
+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 HttpMethod = z.infer<typeof HttpMethodShape>;
+```
+
+The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.

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

@@ -0,0 +1,12 @@
+---
+title: HttpOpenParts
+description: A type that the Authoring surface names.
+---
+
+# `HttpOpenParts`
+
+Type, in `@jr2/orchestrator/src/http-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 HttpOpenParts<U, A, H> = (U extends typeof open ? "url" : never) | OpenSecretIn<A | ValuesOf<H>>;
+```

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

@@ -0,0 +1,89 @@
+---
+title: HttpOutput
+description: "The output of an `http` Effect: what the `onDone` of its state gets as `event.output`."
+---
+
+# `HttpOutput`
+
+Type, in `@jr2/orchestrator/src/effector-wire.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type HttpOutput = {
+  outcome: "response";
+  status: number;
+  headers: Record<string, string>;
+  contentType: string;
+  size: number;
+  body?: string | undefined;
+  truncated?: boolean | undefined;
+} | {
+  outcome: "unknown" | "unreachable" | "refused";
+  reason: string;
+};
+```
+
+The output of an `http` Effect: what the `onDone` of its state gets as `event.output`. Every
+outcome is output. A 4xx or 5xx status is output too. Route on `outcome`:
+
+- `response`: an answer came back. `status` is its HTTP status. `headers`, `contentType` and
+  `size` tell about the body. `body` is there when the body is text: at most `maxBody` bytes
+  (`truncated` is `true` when jr2 cut it). A body that is not text gives only its size and
+  content type. jr2 replaces each value of an Effect secret that the Effector holds, and its
+  usual encodings, with `[secret:<name>]`, in the body and the headers.
+- `unreachable`: the call did not go out, for example because the name did not resolve, or the
+  connection or TLS failed. `reason` tells why.
+- `refused`: jr2 or the Effector refused the call, and nothing was sent. For example, a path
+  segment that is `.`, `..` or empty, or a request that is too large. `reason` tells why.
+- `unknown`: the call can have gone out, but no answer came, or jr2 cannot tell after a restart.
+  `reason` tells why. jr2 does not send it again unless it is marked `idempotent`.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `status`, `headers`, `contentType`, `size`, `body`, `truncated`
+
+  - `outcome`: `"response"`
+  - `status`: `number`
+  - `headers`: `Record<string, string>`
+  - `contentType`: `string`
+  - `size`: `number`
+  - `body` (optional): `string`
+  - `truncated` (optional): `boolean`
+- Form 2: `outcome`, `reason`
+
+  - `outcome`: `"unknown" | "unreachable" | "refused"`
+  - `reason`: `string`
+
+**Example**
+
+```ts
+import { fail, http, jr2Setup, type HttpOutput } from "@jr2/orchestrator";
+
+const ok = (output: HttpOutput): boolean => output.outcome === "response" && output.status < 300;
+
+export const machine = jr2Setup({
+  actors: { health: http({ method: "GET", url: "https://app.example.com/healthz" }), fail: fail() },
+}).createMachine({
+  id: "health",
+  initial: "checking",
+  states: {
+    checking: {
+      invoke: {
+        src: "health",
+        onDone: [
+          { guard: ({ event }) => ok(event.output), target: "healthy" },
+          { target: "unhealthy" },
+        ],
+      },
+    },
+    healthy: { type: "final" },
+    // Not a final state: the run ends `failed`, and `jr2 run` exits 1.
+    unhealthy: { invoke: { src: "fail", input: { reason: "the app is not healthy" } } },
+  },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.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)

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

@@ -0,0 +1,33 @@
+---
+title: HttpRequestParts
+description: "What the `request` of an `http` definition returns: the part of the request that changes for each run."
+---
+
+# `HttpRequestParts`
+
+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 HttpRequestParts = {
+  path?: readonly string[];
+  json?: unknown;
+  text?: string;
+};
+```
+
+What the `request` of an `http` definition returns: the part of the request that changes for
+each run. The definition fixes the rest.
+
+**Fields**
+
+- `path` (optional): `readonly string[]`
+
+  Path segments that jr2 adds to the end of the url. jr2 encodes each segment. A segment that
+  is `.`, `..` or empty gives the output `refused`, and nothing is sent.
+- `json` (optional): `unknown`
+
+  A JSON body. Do not give `text` too. When it starts, the Effect refuses both: ``http:
+  `request` returned both json and text``.
+- `text` (optional): `string`
+
+  A text body.