@jr2/orchestrator 0.4.1 → 0.6.0

package/README.md

@@ -1,8 +1,26 @@
 # @jr2/orchestrator
 
 The jr2 Orchestrator: the runtime that executes Machines — xstate actors driving Agents in Kubernetes Sandboxes — plus
-the HTTP API, the Console it serves, and the kit pieces a Workflow imports (`agent()`, `workspace()`, `gate()`,
-`customize()`, …).
+the HTTP API, the Console it serves, and the Authoring surface.
+
+The Authoring surface is what this package exports from its root: the names that an author writes in a workflow module
+or in `jr2.config.ts`, and no other names.
+
+- **Machine and events:** `jr2Setup()`, `defineEvent()`, `sentBy()`, and the type `HostInjectedInput`.
+- **Agents:** `agent()`, and the types `AgentDefinition` and `ThinkingLevel`.
+- **Workspaces and Repos:** `workspace()`, and the types `Workspaced`, `RepoSlot` and `Binding`.
+- **Effects:** `command()`, `arg()`, `http()`, `secret()`, `bearer()`, `basic()`, `text()`, `file()`, `push()`,
+  `dispatch()`, `fromPick()`, `paramsOf()`, `answer()`, and the types `CommandOutput`, `HttpOutput`, `PushOutput` and
+  `DispatchOutput`.
+- **Composition:** `open`, `customize()`, `pool()`, `source()`, and the types `Customize`, `EffectBinding`, `Size` and
+  `UserContainer`.
+- **Charts:** `openBody()`, `chartSchema`, `chartSchemaFor()`, and the types `OpenBodyDeclaration` and `OpenBodyOutput`.
+- **Config:** `defineConfig()`, and the type `JR2Config`.
+
+A state that needs outside input invokes the Gate as `src: "gate"`. You do not import it: `jr2Setup()` registers it.
+
+The kit's own packages import `@jr2/orchestrator/internal`. It is not for workflow authors. It has no stability promise,
+and any name in it can change in any release.
 
 An Instance depends on it and its `workflows/` import from it; `jr2 up` bakes the engine and those workflows into one
 image, so this package is run in-cluster, never on the host. Its version is the kit's version: the Kit images an

package/console/components/app.ts

@@ -8,6 +8,7 @@ import { Fragment, h, type JSX } from "preact";
 import { useState } from "preact/hooks";
 import {
   selectedRun,
+  selectedRunFailure,
   selectedRunGates,
   selectedRunHeld,
   selectedRunWaiting,
@@ -80,6 +81,7 @@ export function App(props: {
         gates: selectedRunGates(store),
         waiting: selectedRunWaiting(store),
         held: selectedRunHeld(store),
+        failure: selectedRunFailure(store),
         api,
       }),
       h(Drawer, { store, chosenTab, onChooseTab: setChosenTab, api }),

package/console/components/fleet.ts

@@ -7,7 +7,7 @@
 // (`chart file` or `chart`) and, when a publish no longer admits it, `unrunnable` with the reason.
 
 import { h, type JSX } from "preact";
-import { fleetEntries, fleetRuns, type FleetEntry, type ObservedRun, type Store } from "../store.ts";
+import { dispatchBadge, fleetEntries, fleetRuns, type FleetEntry, type ObservedRun, type Store } from "../store.ts";
 import { SchemaForm } from "./schema-form.ts";
 import type { AppApi } from "./app.ts";
 
@@ -131,6 +131,8 @@ function runRows(
 function runRow(name: string, run: ObservedRun, settled: boolean, store: Store, api: AppApi): JSX.Element {
   const gates = store.gates.get(run.runId)?.gates.length ?? 0;
   const selected = name === store.workflow && run.runId === store.selectedRunId;
+  // A dispatched run names its caller on the row (ADR-0071), off the open observation.
+  const badge = dispatchBadge(run);
   return h(
     "li",
     {
@@ -142,6 +144,17 @@ function runRow(name: string, run: ObservedRun, settled: boolean, store: Store,
       },
     },
     h("span", { class: "run-id" }, run.runId.slice(0, 8)),
+    badge && run.dispatchedBy
+      ? h(
+          "span",
+          {
+            class: "dispatch-badge dim",
+            title: `dispatched by ${run.dispatchedBy.run} (${run.dispatchedBy.slot}), depth ${run.dispatchedBy.depth}`,
+            style: { fontSize: "11px", marginRight: "6px" },
+          },
+          badge,
+        )
+      : null,
     gates
       ? h("span", { class: "gate-badge", title: `${gates} open gate${gates === 1 ? "" : "s"}` }, `⚑${gates}`)
       : null,

package/console/components/machine-pane.ts

@@ -5,7 +5,15 @@
 
 import { h, type JSX } from "preact";
 import { useEffect, useRef } from "preact/hooks";
-import { docSeats, type GateCard, type HeldLine, type ObservedRun, type WaitingLine } from "../store.ts";
+import {
+  dispatchStrip,
+  dispatchedStrip as dispatchedStripText,
+  docSeats,
+  type GateCard,
+  type HeldLine,
+  type ObservedRun,
+  type WaitingLine,
+} from "../store.ts";
 import {
   clearCanvas,
   initCanvas,
@@ -23,9 +31,10 @@ export function MachinePane(props: {
   gates: GateCard[];
   waiting: WaitingLine[];
   held: HeldLine[];
+  failure: string | null;
   api: AppApi;
 }): JSX.Element {
-  const { view, run, selectedNodeId, gates, waiting, held, api } = props;
+  const { view, run, selectedNodeId, gates, waiting, held, failure, api } = props;
   const canvasRef = useRef<HTMLElement>(null);
   const svgRef = useRef<SVGSVGElement>(null);
 
@@ -58,14 +67,37 @@ export function MachinePane(props: {
     { id: "canvas", ref: canvasRef },
     h("div", { id: "placeholder", hidden: !view.placeholder }, view.placeholder ?? ""),
     h("div", { id: "error", hidden: !view.note, class: view.note?.notice ? "notice" : "" }, view.note?.text ?? ""),
+    dispatchedStrip(run),
+    startedStrip(run),
     rootTransitionStrip(view.doc),
     seatsPanel(view.doc),
+    failureStrip(failure),
     waitingStrip(waiting),
     heldStrip(held),
     h("svg", { id: "machine-svg", ref: svgRef }),
   );
 }
 
+/** Who dispatched the selected run (ADR-0071): its caller's run, slot and the chain's depth. Read
+ *  off the open observation the pane already holds, so it shows for every viewer, with no fetch. */
+function dispatchedStrip(run: ObservedRun | null): JSX.Element | null {
+  const text = dispatchStrip(run);
+  if (!text) return null;
+  return h(
+    "div",
+    { id: "dispatched-by", class: "dim", style: { margin: "28px 28px 0", fontFamily: "var(--mono)" } },
+    text,
+  );
+}
+
+/** The runs the selected run dispatched (ADR-0071): the chain's other direction, off the same
+ *  open observation, with no fetch. */
+function startedStrip(run: ObservedRun | null): JSX.Element | null {
+  const text = dispatchedStripText(run);
+  if (!text) return null;
+  return h("div", { id: "dispatched", class: "dim", style: { margin: "8px 28px 0", fontFamily: "var(--mono)" } }, text);
+}
+
 /** Machine-level transitions ("from any state") as the strip above the Machine — an edge from the
  *  root would lie, because the root has no box (it renders as the page). */
 function rootTransitionStrip(doc: MachineDoc | null): JSX.Element {
@@ -130,6 +162,13 @@ function seatsPanel(doc: MachineDoc | null): JSX.Element | null {
   );
 }
 
+/** Why the selected run failed (ADR-0073): the reason that the Machine gave to `fail`, as `jr2 status`
+ *  prints it. The rail colors a `failed` run for every viewer; the reason is in the run's output,
+ *  which is guarded, so it is here only with a live token. */
+function failureStrip(failure: string | null): JSX.Element {
+  return h("div", { id: "failure", hidden: failure === null }, failure === null ? "" : `failed: ${failure}`);
+}
+
 /** Why the selected run's Workspaces in `placing` wait (ADR-0064), one line each, in the
  *  scheduler's or the quota's own words. The diagram lights `placing` for every viewer; this reason
  *  is guarded, so it is here only with a live token. */

package/console/main.ts

@@ -37,6 +37,7 @@ import { h, render } from "preact";
 import {
   applyFrame,
   emptyStore,
+  failureReason,
   machineDocSource,
   selectedRun,
   type Frame,
@@ -158,10 +159,21 @@ async function refreshRun(runId: string, workflow: string): Promise<void> {
   const res = await gfetch(`/runs/${encodeURIComponent(runId)}`);
   if (!res) return; // 401 already dropped the page to observer
   // !ok: settled + evicted — no gates, and nothing waits.
-  const body = res.ok ? ((await res.json()) as { gates?: GateCard[]; waiting?: WaitingLine[]; held?: HeldLine[] }) : {};
+  const body = res.ok
+    ? ((await res.json()) as {
+        status?: string;
+        output?: unknown;
+        gates?: GateCard[];
+        waiting?: WaitingLine[];
+        held?: HeldLine[];
+      })
+    : {};
   if (runFetchSerial.get(runId) !== serial) return; // superseded — a newer re-fetch owns the answer
   dispatch({ kind: "gates", runId, workflow, gates: body.gates ?? [] });
   dispatch({ kind: "waiting", runId, workflow, waiting: body.waiting ?? [], held: body.held ?? [] });
+  // The reason of a run that ended `failed` (ADR-0073). A 404 says nothing about it, so a reason
+  // the page has stays.
+  if (res.ok) dispatch({ kind: "failure", runId, reason: failureReason(body) });
 }
 
 // ---- The two writes (start-run + gate delivery — ADR-0033) --------------------------------------

package/console/store.ts

@@ -30,8 +30,20 @@ export type ObservedRun = {
   /** The hashes of the Charts the run binds now, distinct and sorted. A run can bind a second Chart
    *  in its life, so these, with the run id, key its doc. Absent from an older Orchestrator. */
   chartHashes?: string[];
+  /** The run that dispatched this one, the caller's slot, and this run's depth in the chain
+   *  (ADR-0071). Routing, on the open band (ADR-0014): the page reads it off the observation it
+   *  already holds, with no fetch and no token. `instance` is set for a foreign caller, opaque text.
+   *  Absent for a run nobody dispatched, and from an Orchestrator older than ADR-0071. */
+  dispatchedBy?: DispatchedByView;
+  /** The runs this run's `dispatch` Effects started, oldest first, by slot (ADR-0071): the chain's
+   *  other direction, the same routing on the same band. Absent when it started none. */
+  dispatched?: Array<{ slot: string; run: string }>;
 };
 
+/** {@link ObservedRun.dispatchedBy} — mirrors `RunObservation.dispatchedBy` in run-host.ts. The
+ *  idempotency key is not on the open band: it names the caller's ledger. */
+export type DispatchedByView = { run: string; slot: string; depth: number; instance?: string };
+
 /** Where a Workflow came from (ADR-0070): a Machine or a Chart file in the Assembly, or a runtime
  *  Chart put on the Instance. */
 export type WorkflowOrigin = "machine" | "file" | "runtime";
@@ -100,6 +112,7 @@ export type Frame =
   | { kind: "token"; state: TokenState }
   | { kind: "gates"; runId: string; workflow: string; gates: GateCard[] }
   | { kind: "waiting"; runId: string; workflow: string; waiting: WaitingLine[]; held?: HeldLine[] }
+  | { kind: "failure"; runId: string; reason: string | null }
   | { kind: "inboxScope"; all: boolean }
   | { kind: "startForm"; workflow: string | null };
 
@@ -129,6 +142,11 @@ export type Frame =
  * `waiting`  why each run's Workspaces in `placing` wait (ADR-0064): runId -> { workflow, waiting },
  *            off the SAME `GET /runs/:id` re-fetch as `gates`, under the same rules — guarded, whole
  *            per run, gone with the credential. The open band sees `placing` lit and nothing more.
+ * `failures` the reason of each run this page knows that ended `failed` (ADR-0073): runId -> reason,
+ *            off the SAME `GET /runs/:id` re-fetch, under the same rules — guarded (the open band
+ *            sees the `failed` status and its color, never the output), gone with the credential.
+ *            A failed run is a settled run, so `gone` keeps it; it goes with the run when the run
+ *            leaves both `runs` and `settled`.
  * `inboxAll` the widen control: false = the inbox follows the selection, true = every workflow.
  * `startFormFor` which workflow's start-run form is open, if any.
  * `selectedNodeId` the diagram node the reader clicked — an elk node id (scope + state id), one at
@@ -152,6 +170,7 @@ export type Store = {
   token: TokenState;
   gates: Map<string, { workflow: string; gates: GateCard[] }>;
   waiting: Map<string, { workflow: string; waiting: WaitingLine[]; held: HeldLine[] }>;
+  failures: Map<string, string>;
   inboxAll: boolean;
   startFormFor: string | null;
 };
@@ -180,6 +199,7 @@ export function emptyStore(): Store {
     token: "none",
     gates: new Map(),
     waiting: new Map(),
+    failures: new Map(),
     inboxAll: false,
     startFormFor: null,
   };
@@ -189,17 +209,24 @@ export function emptyStore(): Store {
  *  that learns a new frame type does not break a page still running yesterday's script. */
 export function applyFrame(store: Store, frame: Frame): Store {
   switch (frame.kind) {
-    case "runs":
+    case "runs": {
       // The server's whole truth about what is live. Runs that ended during a disconnect are simply
       // ABSENT — no `gone` was delivered for them and none is needed; they were never ours to settle.
       // The same wholeness settles the inbox: a selected-workflow run the frame does not mention can
-      // never be re-fetched again, so its card leaves with it.
+      // never be re-fetched again, so its card leaves with it. A failure stays while its run is live
+      // or settled here.
+      const runs = new Map(frame.runs.map((r): [string, ObservedRun] => [r.runId, r]));
+      const orphans = [...store.failures.keys()].filter((id) => !runs.has(id) && !store.settled.has(id));
+      let failures = store.failures;
+      for (const id of orphans) failures = mapWithout(failures, id);
       return select({
         ...store,
-        runs: new Map(frame.runs.map((r): [string, ObservedRun] => [r.runId, r])),
+        runs,
         gates: dropAbsent(store.gates, store.workflow, new Set(frame.runs.map((r) => r.runId))),
         waiting: dropAbsent(store.waiting, store.workflow, new Set(frame.runs.map((r) => r.runId))),
+        failures,
       });
+    }
 
     case "status":
       return select({ ...store, runs: new Map(store.runs).set(frame.status.runId, frame.status) });
@@ -216,8 +243,13 @@ export function applyFrame(store: Store, frame: Frame): Store {
       const runs = new Map(store.runs);
       runs.delete(frame.runId);
       const settled = new Map(store.settled).set(frame.runId, departing);
-      while (settled.size > SETTLED_CAP) settled.delete(settled.keys().next().value!);
-      return select({ ...store, runs, settled, gates, waiting });
+      let failures = store.failures;
+      while (settled.size > SETTLED_CAP) {
+        const evicted = settled.keys().next().value!;
+        settled.delete(evicted);
+        failures = mapWithout(failures, evicted);
+      }
+      return select({ ...store, runs, settled, gates, waiting, failures });
     }
 
     case "emit":
@@ -253,6 +285,8 @@ export function applyFrame(store: Store, frame: Frame): Store {
         selectedRunId: null,
         selectedNodeId: null,
         connection: "connecting",
+        // Each failure belongs to a run of the old selection's `runs` or `settled`, which go.
+        failures: new Map(),
       };
     }
 
@@ -287,7 +321,7 @@ export function applyFrame(store: Store, frame: Frame): Store {
       // "invalid" (the any-later-401 drop of ADR-0032) empties the inbox. "checking" keeps it — a
       // re-validation of a token that turns out fine should not flash the inbox empty.
       if (frame.state === "none" || frame.state === "invalid") {
-        return { ...store, token: frame.state, gates: new Map(), waiting: new Map() };
+        return { ...store, token: frame.state, gates: new Map(), waiting: new Map(), failures: new Map() };
       }
       return { ...store, token: frame.state };
 
@@ -322,6 +356,20 @@ export function applyFrame(store: Store, frame: Frame): Store {
       return { ...store, waiting };
     }
 
+    case "failure": {
+      // The same guarded re-fetch's third half (ADR-0073): the reason of a run that ended `failed`.
+      // Nothing folded without the credential, and nothing for a run that the page does not hold:
+      // the re-fetch can come back after a `select` moved on. `null` says the run did not fail.
+      if (store.token !== "live") return store;
+      if (frame.reason === null) {
+        const failures = mapWithout(store.failures, frame.runId);
+        return failures === store.failures ? store : { ...store, failures };
+      }
+      if (!store.runs.has(frame.runId) && !store.settled.has(frame.runId)) return store;
+      if (store.failures.get(frame.runId) === frame.reason) return store;
+      return { ...store, failures: new Map(store.failures).set(frame.runId, frame.reason) };
+    }
+
     case "inboxScope":
       return { ...store, inboxAll: frame.all };
 
@@ -464,6 +512,38 @@ export function machineDocSource(
   return { key: `workflow:${workflow}`, path: `${base}/machine` };
 }
 
+/** The fleet row's badge for a dispatched run (ADR-0071): `↳ <run8>`, the caller's run id cut as
+ *  the row cuts its own. Null for a run nobody dispatched. */
+export function dispatchBadge(run: ObservedRun): string | null {
+  const by = run.dispatchedBy;
+  return by ? `↳ ${by.run.slice(0, 8)}` : null;
+}
+
+/** The Machine pane's strip for a dispatched run (ADR-0071): `dispatched by <run8> · <slot> ·
+ *  depth n`, and `· from Orchestrator <name>` when the caller is on another Orchestrator (its
+ *  name as it sent it, never an Instance ID). Null for a run
+ *  nobody dispatched. */
+export function dispatchStrip(run: ObservedRun | null): string | null {
+  const by = run?.dispatchedBy;
+  if (!by) return null;
+  const from = by.instance ? ` · from Orchestrator ${by.instance}` : "";
+  return `dispatched by ${by.run.slice(0, 8)} · ${by.slot} · depth ${by.depth}${from}`;
+}
+
+/** The most runs the pane's `dispatched` strip names: a watcher dispatches on every pass. */
+const DISPATCHED_SHOWN = 5;
+
+/** The Machine pane's strip for a run that dispatched (ADR-0071): `dispatched <run8> (<slot>) · …`,
+ *  newest last, the older ones counted. Null for a run that started none. */
+export function dispatchedStrip(run: ObservedRun | null): string | null {
+  const all = run?.dispatched ?? [];
+  if (all.length === 0) return null;
+  const shown = all.slice(-DISPATCHED_SHOWN);
+  const older = all.length - shown.length;
+  const named = shown.map((d) => `${d.run.slice(0, 8)} (${d.slot})`).join(" · ");
+  return `dispatched ${older > 0 ? `${older} more · ` : ""}${named}`;
+}
+
 /** The inbox as the Attention tab draws it: every card, or the selection's slice. The inbox itself
  *  is GLOBAL (every workflow the fleet knows) — the filter is presentation, which is why it lives
  *  in a selector and not in `applyFrame`. */
@@ -488,6 +568,22 @@ export function selectedRunWaiting(store: Store): WaitingLine[] {
   return store.waiting.get(store.selectedRunId)?.waiting ?? [];
 }
 
+/** The reason of a run that ended `failed`, off a `GET /runs/:id` answer (ADR-0073): the Failure's
+ *  `reason` in the run's output. Null for every other status, and for an output with no reason
+ *  text — the same reading as `jr2 status`'s `failed:` line. */
+export function failureReason(body: { status?: string; output?: unknown }): string | null {
+  if (body.status !== "failed") return null;
+  const reason = (body.output as { reason?: unknown } | null | undefined)?.reason;
+  return typeof reason === "string" ? reason : null;
+}
+
+/** Why the SELECTED run failed (ADR-0073): the reason of its Failure, or null when it did not fail
+ *  or the page has no live token to read it with. */
+export function selectedRunFailure(store: Store): string | null {
+  if (store.selectedRunId === null) return null;
+  return store.failures.get(store.selectedRunId) ?? null;
+}
+
 /** The SELECTED run's outstanding picks, each with since when it is held (ADR-0024) — empty in
  *  observer mode. */
 export function selectedRunHeld(store: Store): HeldLine[] {

package/console/style.css

@@ -12,6 +12,8 @@
   --phosphor-soft: rgba(78, 240, 167, 0.12);
   --amber: #f0c04e;
   --red: #f06a5f;
+  /* A Failure (ADR-0073): an end the Machine chose, so not the red of a fault. */
+  --orange: #f0954e;
   --blue: #6aa7f0;
   --mono: ui-monospace, "SF Mono", "Cascadia Code", Menlo, Consolas, monospace;
 }
@@ -229,6 +231,22 @@ main {
   color: var(--text-dim);
 }
 
+/* A failed run (ADR-0073): the reason of its Failure. Orange like the rail's `failed` status — the
+   Machine chose this end, so it is not the red of an `error`. */
+#failure {
+  margin: 0 28px 16px;
+  max-width: 720px;
+  border: 1px solid var(--orange);
+  border-radius: 4px;
+  padding: 8px 12px;
+  color: var(--orange);
+  font-family: var(--mono);
+}
+
+#failure[hidden] {
+  display: none;
+}
+
 /* An outstanding pick (ADR-0024): an Agent's Turn held while the workflow runs its pick. */
 #held {
   list-style: none;
@@ -615,6 +633,9 @@ ul {
 .wf-runs .run-status.status--error {
   color: var(--red);
 }
+.wf-runs .run-status.status--failed {
+  color: var(--orange);
+}
 .wf-runs .run-status.status--done {
   color: var(--phosphor);
 }

package/docs/agents-block.md

@@ -0,0 +1,5 @@
+jr2 is newer than your training data. Before you write a Machine or change jr2.config.ts, read the bundled docs in node_modules/@jr2/orchestrator/docs/. They are the docs of this Instance's Kit version, 0.6.0. Start with guides/write-a-workflow.md and with reference/authoring-surface.md, the contents page of the Authoring surface. Read one page with each call of your file tool, because a file tool cuts off a long output. Before you give a change to the user, run `npx --no jr2 check` in the Instance folder. It does the typecheck and the load of each Workflow that `jr2 up` does first, with no cluster, and it gives the same refusals.
+
+A final state means that the work succeeded: the run ends `done`. When the work did not succeed, invoke `fail()` from a state (reference/authoring-surface/fail.md), and the run ends `failed`. Do not throw to fail: a throw is a defect, and the run ends `error`.
+
+[jr2 docs index]|root: ./node_modules/@jr2/orchestrator/docs|reference:{authoring-surface.md,machines.md,config.md,cli.md,http-api.md,mechanism-events.md,glossary.md,decisions.md}|reference/authoring-surface:{one file per export and type; reference/authoring-surface.md lists them}|guides:{iterate-on-a-machine-on-kind.md,write-a-workflow.md,bind-open-parts.md,set-an-agents-access-and-dials.md,cut-a-worktree.md,run-a-command-or-call-a-url.md,push-and-sign-a-branch.md,start-a-run-from-a-run.md,add-tools-to-the-sandbox.md,size-a-workspace.md,run-one-worker-per-item.md,publish-a-machine-as-an-npm-package.md,let-an-agent-write-a-chart.md,run-a-chart-by-name.md,start-a-run.md,answer-a-gate.md,watch-a-run.md,look-inside-a-sandbox.md,cancel-a-run.md,open-the-console.md,use-a-local-model.md,use-a-hosted-provider.md,give-the-cluster-git-credentials.md,move-from-kind-to-a-shared-cluster.md,mirror-the-kit-images.md,upgrade-the-kit-version.md,clean-up.md,fix-a-failed-converge.md}|concepts:{machines-and-workflows.md,agents-and-turns.md,the-menu.md,gates.md,effects.md,workspaces.md,composition.md,charts.md,pools-and-sources.md,architecture.md,secrets-and-trust.md,converge.md,durable-runs.md}|.:{index.md,why.md}|get-started:{install.md,create-an-instance.md,connect-a-model.md,a-model-decides.md,an-agent-in-a-sandbox.md,have-your-assistant-write-a-machine.md}|reference/decisions:{one file per ADR; reference/decisions.md lists them}