@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/guides/start-a-run-from-a-run.md

@@ -0,0 +1,237 @@
+---
+title: Start a run from a run
+description: Use a dispatch Effect to start a run of a Workflow from a Machine, in this Instance or in a different one.
+---
+
+# Start a run from a run
+
+Start a run of a [Workflow](../reference/glossary.md#workflow) from a [Machine](../reference/glossary.md#machine), with
+a `dispatch` [Effect](../reference/glossary.md#effect).
+
+This example is `workflows/intake.ts`. It waits at a [Gate](../reference/glossary.md#gate). For each `report` event, it
+starts one run of `triage`, the Workflow of [A model decides](../get-started/a-model-decides.md). Then it waits for the
+next report:
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { defineEvent, dispatch, jr2Setup, type DispatchOutput } from "@jr2/orchestrator";
+
+// The run input of the triage Workflow, as this slot claims it. `jr2 up` compares it with the
+// input that triage declares.
+const triageInput = z.object({ request: z.string() });
+
+// The Gate takes these events. A person, a script or a webhook reports a request.
+const report = defineEvent({
+  name: "report",
+  description: "Report a request. A run of triage starts for it.",
+  input: triageInput,
+});
+const close = defineEvent({
+  name: "close",
+  description: "Stop the intake. The runs that it started continue.",
+  input: z.object({}),
+});
+
+type Context = { request?: string; started: string[]; last?: DispatchOutput };
+
+export const machine = jr2Setup({
+  types: {} as { context: Context },
+  events: [report, close],
+  actors: {
+    // Each invoke of this slot starts one run of triage. That run is a run of its own.
+    triage: dispatch("triage", { input: triageInput }),
+  },
+}).createMachine({
+  id: "intake",
+  context: { started: [] },
+  initial: "listening",
+  states: {
+    listening: {
+      invoke: { src: "gate" },
+      on: {
+        report: { target: "starting", actions: assign({ request: ({ event }) => event.request }) },
+        close: "closed",
+      },
+    },
+    starting: {
+      invoke: {
+        src: "triage",
+        input: ({ context }) => ({ request: context.request ?? "" }),
+        // Each outcome is output: started, refused, unreachable or unknown.
+        onDone: {
+          target: "listening",
+          actions: assign({
+            last: ({ event }) => event.output,
+            started: ({ context, event }) =>
+              event.output.outcome === "started" ? [...context.started, event.output.run] : context.started,
+          }),
+        },
+      },
+    },
+    closed: { type: "final" },
+  },
+});
+```
+
+The Instance must also have `workflows/triage.ts`. The example does not need a model of its own: the runs of `triage`
+use the model of `triage`.
+
+## Converge it
+
+Run [`jr2 up`](../reference/cli.md#up). Its `effects:` lines tell where the Effect runs:
+
+```sh
+jr2 up
+```
+
+```text
+…
+effects: workflow "intake" — what it runs outside itself (ADR-0067)
+  triage: dispatch triage → this Orchestrator — 30s, in the Orchestrator's own process
+…
+converged — `jr2 run <workflow>` when ready
+```
+
+`jr2 up` checks that the [Assembly](../reference/glossary.md#assembly) has a Workflow `triage`. It also compares the
+`input` schema of the slot with the input that `triage` declares. When they do not agree, it stops before it changes the
+cluster.
+
+## Start the runs
+
+Start the run of `intake` in one terminal. It stays at its Gate, `listening`, until you send `close`:
+
+```sh
+jr2 run intake
+```
+
+In a second terminal, send a report. `<run id>` is the id that `jr2 run` printed, or its first 4 characters or more:
+
+```sh
+jr2 send <run id> --gate listening --event report --input '{"request":"The greeting looks wrong sometimes."}'
+```
+
+The Effect starts a run of `triage` with the input `{"request":"The greeting looks wrong sometimes."}`. When the
+[Orchestrator](../reference/glossary.md#orchestrator) accepts the run, the Effect ends with `started`, and `intake` goes
+back to `listening`.
+
+## See the runs
+
+[`jr2 runs`](../reference/cli.md#runs) lists the two runs. The run of `triage` has `dispatchedBy` after its id:
+
+```sh
+jr2 runs
+```
+
+```text
+…
+→ context kind-jr2 / namespace my-instance
+workflows:
+  intake (machine)
+  ping (machine)
+  triage (machine)
+[{"runId":"91ca85e1-5092-4e10-9ec6-d14e37811ca1","workflow":"intake","instanceId":"e51d124b-88e5-461c-b464-6a3660ee13dc","status":"active","value":"listening","context":{"started":["45b52048-0848-4015-ad56-6ff8ae33d817"],"request":"The greeting looks wrong sometimes.","last":{"outcome":"started","run":"45b52048-0848-4015-ad56-6ff8ae33d817"}},"children":[],"waiting":[],"held":[],"assembly":"3229103a2952","dispatched":[{"slot":"triage","run":"45b52048-0848-4015-ad56-6ff8ae33d817","at":"2026-10-24T06:20:43.465Z"}]},{"runId":"45b52048-0848-4015-ad56-6ff8ae33d817","dispatchedBy":{"run":"91ca85e1-5092-4e10-9ec6-d14e37811ca1","slot":"triage","effect":"08423831-751f-41e5-9d93-1fa063faaf61","depth":1},"workflow":"triage","instanceId":"a2ad6e54-6a52-45c2-81f4-89f408a27d1f","status":"active","value":"triaging","context":{"request":"The greeting looks wrong sometimes.","exchange":[]},"children":[],"waiting":[],"held":[],"assembly":"3229103a2952"}]
+```
+
+The first line, `…`, is the line `→ .env:`, with the keys that the CLI took from `.env`. The lines on stderr list the
+Workflows of the Instance. In `dispatchedBy`, `run` is the run that started it, `slot` is the slot of the Effect, and
+`effect` is the id of that Effect in the record of the run that started it. jr2 uses it as the key of the start, so that
+a start that jr2 sends again starts no second run. `depth` is the number of runs before it in the chain. `dispatched` of
+`intake` lists each run that it started. Your ids, your time and your hash are different.
+
+[`jr2 status`](../reference/cli.md#status) prints the link in both directions, on stderr. For the run of `intake`:
+
+```text
+dispatched: 45b52048-0848-4015-ad56-6ff8ae33d817 (triage)
+```
+
+For the run of `triage`:
+
+```text
+dispatched by: 91ca85e1-5092-4e10-9ec6-d14e37811ca1 (triage), depth 1
+```
+
+The two runs are independent. A `CANCEL` of `intake` does not cancel the run of `triage`. Answer the `clarify` Gate of
+each run of `triage` as [Answer a Gate](answer-a-gate.md) tells.
+
+## Wait for the run to end
+
+To use the result of the run, add `wait: true` to the definition:
+`dispatch("triage", { input: triageInput, wait: true })`.
+
+The Effect then ends when the run of `triage` ends, with `{ outcome: "settled", run, status, output }`. `status` is
+`done`, `failed`, `error`, `cancelled`, `lost` or `drifted`. `output` is the output of the Machine of that run, and for
+`failed` it is the Failure, `{ reason, detail? }`. The default timeout is then 10 minutes. Set a different one with
+`timeout`, such as `timeout: "1h"`. When the timeout comes first, `status` is `live`, and the run continues. On a
+different Orchestrator, the Effect reads the run every 5 seconds. When its last read got no answer, the outcome is
+`unknown`, not `settled`.
+
+`wait` is fixed in the definition. A Machine that starts the same Workflow in the two ways has two slots.
+
+## Start a run on a different Instance
+
+To start a run on the Orchestrator of a different [Instance](../reference/glossary.md#instance), give a `target` in the
+definition: `target: { url: "https://ops.example.com", token: secret("ops-instance") }`.
+
+- `url` is the origin of the other Orchestrator: the scheme, the host and the port. It has no path.
+- `token` names a secret that holds the Instance token of the other Instance. Put the secret in the
+  [`secrets`](../reference/config.md#secrets) list of `jr2.config.ts`, as for an `http` Effect. See
+  [Run a command or call a URL with an Effect](run-a-command-or-call-a-url.md).
+- The Effect runs in the [Instance Effector](../reference/glossary.md#instance-effector), which holds the token.
+  `jr2 up` converges the Instance Effector for it.
+- `jr2 up` asks the other Orchestrator for `GET /workflows/<name>` with no token, and compares its input. Each problem
+  is a warning, not a refusal: the other Instance can be down, or you can converge it later.
+
+A Machine that you publish as a package can leave the target Open with `target: open`. The composer binds the url and
+the token together:
+`customize(<import>, { effects: { <slot>: { target: { url: "https://<host>", token: secret("<name>") } } } })`. See
+[Bind a shipped Machine's Open parts](bind-open-parts.md).
+
+## Rules
+
+- The name of the Workflow is a constant, as `jr2 run` writes it:
+  ``dispatch("<name>"): the Workflow is named as `jr2 run` names it — a Machine's filename stem ("review"), or "<wrapper>/<name>" for a named Chart: lowercase letters, digits and "-" (ADR-0071)``
+- `wait` is a boolean: `dispatch("<name>", { wait }): wait is true or false — a slot that needs both declares two`
+- The `input` option is a `z.object()`:
+  `dispatch("<name>", { input }): the input is a z.object(...) — the run's body is a JSON object (ADR-0071)`
+- `timeout` is a positive duration:
+  `dispatch("<name>"): timeout "<timeout>" is not a positive duration (like "30s", "10m", "1h")`
+- A target is an object with a `url` and a `token`, or `open`:
+  `dispatch("<name>", { target }): a target is { url: "https://<host>", token: secret("<name>") }, or open (ADR-0071)`
+- The `url` of a target is an origin. The refusal starts with
+  `dispatch("<name>", { target }): "<url>" is not an origin — write the scheme and the host, with a port if it is not the scheme's, and no path, query or userinfo`.
+- The `token` of a target is a secret:
+  `dispatch("<name>", { target }): the token is a secret("<name>") holding the target's Instance token (ADR-0071)`
+- An Open target is the whole target, not its secret:
+  ``dispatch("<name>", { target }): secret(open) in a target — the target is the Open part, not its secret: leave the whole target Open (`target: open`) and let the composer bind its url and token together (ADR-0071)``
+- With no target, the Assembly must have the Workflow. `jr2 up` stops:
+  `refusing: workflow "<workflow>" dispatches "<name>" which no Workflow in the Assembly has — add workflows/<name>.ts, or name one it registers: <workflows> (ADR-0071)`
+- With no target, the `input` schema of the slot must agree with the input that the Workflow declares. `jr2 up` stops,
+  with one line for each problem:
+  ``refusing: workflow "<workflow>" dispatches "<name>" with input its door does not take: <problem> — align the slot's `input` with the door (derive it from the door's schema, `door.pick({ ... })`) (ADR-0071)``
+- For a named Chart that `jr2 up` cannot see, it warns and continues. A runtime Chart is only on the volume of the
+  Orchestrator, and the Orchestrator checks it when `jr2 up` publishes. The warning starts with
+  `warning: workflow "<workflow>" dispatches "<wrapper>/<name>": the Assembly has no Chart file workflows/<wrapper>/<name>.chart.json`.
+- For a target, each problem that `jr2 up` finds is a warning. For example, when the other Orchestrator does not answer:
+  `warning: dispatch "<name>" at <url>: no answer from this host (<error>) — the other Instance may be down, or reached only from inside its cluster; while no door answers, the dispatch settles "unreachable" (ADR-0071)`
+- When the Orchestrator starts no run, the Effect ends with `refused`, not with an error. `report` holds the lines of
+  the refusal, and `status` is its status code:
+  - `400`: the Workflow does not take the input.
+  - `404`: the current Assembly has no Workflow of that name.
+  - `409`: the named Chart cannot run now, or a run of a different Workflow has the key of this start.
+  - `413`: the start is larger than the Effector reads.
+  - `422`: the door refuses the Chart in the input.
+  - `0`: the Effector refused the start before it sent it.
+
+## Read next
+
+- [Effects](../concepts/effects.md)
+- [Machines and Workflows](../concepts/machines-and-workflows.md)
+- [Durable runs](../concepts/durable-runs.md): `CANCEL`, and how long jr2 keeps a run.
+- Reference: [`dispatch`](../reference/authoring-surface/dispatch.md),
+  [`DispatchOutput`](../reference/authoring-surface/type-dispatchoutput.md),
+  [`POST /workflows/:name/runs`](../reference/http-api.md#post-workflows-name-runs)
+- [ADR-0071](../reference/decisions/0071-a-run-starts-a-run-through-a-dispatch-effect.md): a run starts a run through a
+  `dispatch` Effect.
+- [ADR-0049](../reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md): a Machine inside a run
+  is composed by invoke.

package/docs/guides/start-a-run.md

@@ -0,0 +1,207 @@
+---
+title: Start a run
+description: Start a run of a Workflow from the CLI, from the Console, or with a call to the HTTP API.
+---
+
+# Start a run
+
+Start a run of a [Workflow](../reference/glossary.md#workflow) from the CLI, from the
+[Console](../reference/glossary.md#console), or with a call to the HTTP API.
+
+A Workflow is a [Machine](../reference/glossary.md#machine) that your [Instance](../reference/glossary.md#instance)
+registers. Its name is the name of its file in `workflows/`, without `.ts`. Thus `workflows/ping.ts` is the Workflow
+`ping`. A named [Chart](../reference/glossary.md#chart) is a Workflow too, with the name `<wrapper>/<name>`: start it
+with `jr2 run <wrapper>/<name>`. See [Run a Chart by name](run-a-chart-by-name.md). A run is one execution of that
+Machine. The run input is a JSON object, and the Machine reads it when the run starts.
+
+The examples on this page start `ping`, the Workflow that `jr2 init` writes. In the commands, replace `<namespace>` with
+the namespace of your Instance. It is the [`name`](../reference/config.md#name) in `jr2.config.ts`. When `jr2.config.ts`
+sets no `name`, it is the name of the Instance folder.
+
+## Start a run from the CLI
+
+Run [`jr2 run`](../reference/cli.md#run) in the Instance folder, with the name of the Workflow. Give the run input in
+`--input`:
+
+```sh
+jr2 run ping --input '{"message":"hi"}'
+```
+
+```text
+→ context <context> / namespace <namespace>
+run e3972b4c-eef9-4e7d-9068-3556332d2ba6 (ping) — attached
+  → done "done"
+{"runId":"e3972b4c-eef9-4e7d-9068-3556332d2ba6","workflow":"ping","instanceId":"8e13475a-d325-45d4-bc64-0627086e97ba","status":"done","value":"done","context":{"message":"hi","reply":"pong: hi"},"children":[],"waiting":[],"held":[],"assembly":"16f4181d70d9"}
+```
+
+Your run id, your instance id and your `assembly` hash are different. When your Instance folder has a `.env` file, the
+output starts with one more line, `→ .env:`, with the keys that the CLI took from it.
+
+- `jr2 run` finds the [Orchestrator](../reference/glossary.md#orchestrator) in the current kubectl context, in the
+  namespace of the Instance. The first line names the two. To use a different context or namespace, add
+  `--context <ctx>` or `-n <ns>`.
+- The lines before the last are activity, on stderr. An indented line that starts with `→` is a change of the run's
+  status and its state. [Watch a run](watch-a-run.md) gives each kind of activity line.
+- The last line is the result, on stdout: the status of the run when it ends, as one JSON object. Thus
+  `jr2 run ping … | jq` gets only the result.
+- `jr2 run` stays attached until the run ends. A run that waits at a [Gate](../reference/glossary.md#gate) does not end,
+  so `jr2 run` waits too. To answer the Gate, use a second terminal. See [Answer a Gate](answer-a-gate.md).
+- When you stop `jr2 run`, for example with Ctrl-C, the run continues in the Orchestrator. To attach again, run
+  `jr2 logs -f <run id>`.
+- `jr2 run` exits with `0` only when the run ends with the status `done`. It exits with `1` for each other end:
+  `failed`, `error`, `cancelled`, `lost` and `drifted`, and also when the run stops before it ends. For a run that ends
+  `failed`, the line `failed: <reason>` on stderr gives the reason.
+
+### Start a run and return at once
+
+Add `--detach`. `jr2 run` starts the run, prints its run id on stdout, and returns:
+
+```sh
+jr2 run ping --input '{"message":"hi"}' --detach
+```
+
+```text
+→ context <context> / namespace <namespace>
+{"runId":"fc8b82d1-bd73-498d-9057-ef13cf962240"}
+```
+
+Use the run id, or its first 4 characters or more, with `jr2 status`, `jr2 logs` and `jr2 send`.
+
+## Start a run from the Console
+
+You need the Instance token to start a run from the Console. [Open the Console](open-the-console.md) tells how to open
+it and how to get the token.
+
+1. Open the Console.
+2. Type the Instance token in the `instance token` box in the nav.
+3. Push Enter. The badge beside the box shows `…`, then `live`.
+4. In the Fleet rail on the left, find the Workflow. Click `start` beside its name.
+5. Fill in the form. When the Machine declares its input, the form has one field for each property of the input. A field
+   that has `*` after its name is necessary. When the Machine declares no input, the form has a box for the run input as
+   JSON. An empty box starts the run with `{}`.
+6. Click `start run`.
+
+While the run continues, the number beside the name of the Workflow counts it. To see the run, click the name of the
+Workflow, or click `▸` beside it. When the Orchestrator refuses the input, the form shows the refusal text below the
+`start run` button, and no run starts.
+
+The form makes a text field for a property that is an object or an array. Thus the Orchestrator refuses the text,
+because it is a string. For such an input, start the run from the CLI or with the HTTP API.
+
+The `start` button shows only while the badge shows `live`. Without the token, the Console shows the runs, but you
+cannot start one.
+
+## Start a run with the HTTP API
+
+Send [`POST /workflows/:name/runs`](../reference/http-api.md#post-workflows-name-runs) to the Orchestrator, with the
+Instance token. The body is the run input. A script, a webhook handler or a CI job can start a run this way.
+
+`jr2 up` makes the Service `jr2-orchestrator` on port 4000, with no address outside the cluster. Thus a caller outside
+the cluster uses a port forward, or an address that you make for the Service.
+
+Forward a port to the Orchestrator. Keep this command open:
+
+```sh
+kubectl -n <namespace> port-forward svc/jr2-orchestrator 4000:4000
+```
+
+In a second terminal, get the Instance token into a variable:
+
+```sh
+TOKEN=$(kubectl -n <namespace> get secret jr2-instance -o jsonpath='{.data.JR2_INSTANCE_TOKEN}' | base64 -d)
+```
+
+Start the run:
+
+```sh
+curl -s -X POST http://localhost:4000/workflows/ping/runs \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message":"hi"}'
+```
+
+```text
+{"runId":"41cfa794-3501-43f3-8b0d-48c83d9fea88","instanceId":"4e334e60-c4ba-4f63-8560-d86d649675f6"}
+```
+
+The status code is `201`. `runId` is the id of the run. `instanceId` is the
+[Instance ID](../reference/glossary.md#instance-id) that the run starts with. It is not the run id.
+
+When the Machine declares its input, the run starts with the input as the schema reads it. A `z.object` schema removes a
+property that it does not name, and it adds each default that it sets. When the Machine declares no input, the run
+starts with the JSON object that you send.
+
+To find the input that a Workflow takes, send [`GET /workflows/:name`](../reference/http-api.md#get-workflows-name) with
+`Accept: application/json`. This route needs no token. `input` is the input schema of the Machine, as JSON Schema, or
+`null` when the Machine declares no input:
+
+```sh
+curl -s http://localhost:4000/workflows/ping -H "Accept: application/json"
+```
+
+```text
+{"name":"ping","machineId":"ping","input":null}
+```
+
+[`GET /workflows`](../reference/http-api.md#get-workflows) gives all the Workflows, each with where it comes from, and
+the named Charts of each Chart wrapper. It also needs no token. [`jr2 runs`](../reference/cli.md#runs) prints the same
+list on stderr.
+
+### Use the CLI without the Instance folder
+
+The CLI can also speak to an Orchestrator at a URL. Then it does not look for the Instance folder or for a kubectl
+context. Give the URL in `--url`, or in `JR2_URL`. Give the Instance token in `JR2_TOKEN`:
+
+```sh
+JR2_URL=http://localhost:4000 JR2_TOKEN=$TOKEN jr2 run ping --input '{"message":"hi"}' --detach
+```
+
+```text
+→ http://localhost:4000
+{"runId":"d28309a1-f8bc-4e15-b4c6-3f2b1642e826"}
+```
+
+## Rules
+
+- `jr2 run` with no Workflow name starts no run. It prints its usage and exits with `2`:
+  `usage: jr2 run <workflow> [--input <json>] [--detach] [--url <u>] [-n <ns>] [--context <ctx>]`
+- The Orchestrator refuses a name that no file in `workflows/` registers, with the status code `404`:
+  `no workflow registered as "<workflow>"`. `jr2 run` prints `error: no workflow registered as "<workflow>"` and exits
+  with `1`. It also prints the version of the Instance in one more line:
+  ``instance: <version> (<hash>) — if it predates this CLI, `jr2 up` converges the cluster to this kit``. `<hash>` is
+  the hash of the current [Assembly](../reference/glossary.md#assembly).
+- When the Machine declares its input, the Orchestrator checks each run input against it. It refuses an input that does
+  not agree, with the status code `400`: `invalid input for workflow "<workflow>": <issues>`. `<issues>` is the list of
+  the problems as JSON. The Console shows the same text below its form.
+- The Console form starts no run when its box holds text that is not a JSON object. It shows `not valid JSON` or
+  `the body must be a JSON object`.
+- `jr2 run` starts no run when `--input` is not valid JSON. It prints `error: <message>`, where `<message>` is the
+  message of the JSON parser, and exits with `1`.
+- The Orchestrator refuses a start without the Instance token, with the status code `401`: `unauthorized`.
+- The Orchestrator refuses a start with the token of a [Sandbox](../reference/glossary.md#sandbox), with the status code
+  `403`: `run state and control need the Instance token — a Sandbox token has neither`. Thus an
+  [Agent](../reference/glossary.md#agent) cannot start a run.
+- `jr2 run` outside an Instance folder, with no `--url` and no `JR2_URL`, starts no run:
+  `error: not inside a jr2 instance — no jr2.config.ts found walking up from cwd`
+- `jr2 run` starts no run when the namespace holds no Instance:
+  ``error: not deployed here — right context? (context <context>, namespace <namespace>; `jr2 up` deploys)``
+- `jr2 run` starts no run when kubectl has no current context:
+  ``error: no kube context — `kind create cluster` (or point kubectl at one), then `jr2 up` ``
+- When the connection to the Orchestrator ends before the run ends, for example when the Orchestrator stops, `jr2 run`
+  prints `error: <message>` and exits with `1`. The run continues when the Orchestrator starts again. To attach again,
+  run `jr2 logs -f <run id>`.
+- When the Orchestrator holds the run but did not continue it, `jr2 run` exits with `1`:
+  ``run <run id> is parked: stopped before it settled — `jr2 logs -f <run id>` follows it once restored``
+
+## Read next
+
+- [Machines and Workflows](../concepts/machines-and-workflows.md)
+- [ADR-0009](../reference/decisions/0009-cli-and-instance-interface.md): `jr2 run`, its output, and its exit codes.
+- [ADR-0019](../reference/decisions/0019-one-converging-command-against-the-current-context.md): how the CLI finds the
+  Orchestrator.
+- [ADR-0033](../reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md): the input that a Machine
+  declares.
+- [ADR-0058](../reference/decisions/0058-a-harness-answers-the-orchestrator-alone.md): why only the Instance token
+  starts a run.
+- [Answer a Gate](answer-a-gate.md)
+- [Watch a run](watch-a-run.md)