@jr2/cli 0.6.0 → 0.7.0

package/src/commands/runs.ts

@@ -1,96 +1,35 @@
-// `jr2 runs` (ADR-0009): list the live runs as JSON on stdout. (Settled runs leave the live registry;
-// read a specific one through to the store with `jr2 status <runId>`.)
+// `jr2 runs` (ADR-0009): list runs as JSON on stdout, newest start first: the live runs by default,
+// the history with `--status ended|all|<list>`, one Workflow with `--workflow`, and the runs that
+// started in a time with `--since` (`2h`, `7d`, or an ISO-8601 time). An ended run is listed while
+// its row is kept (`runs.retain`, ADR-0065); a `drifted` run is listed with its reason (ADR-0030).
+// Each item is the Orchestrator's summary, and the verb reads every page of `GET /runs`.
 //
 // A run with a Workspace in `placing` (ADR-0064) carries `placing`: the child paths of those
 // Workspaces, in `RunWaiting.child`'s form. It is the at-a-glance marker for a run that waits for
 // capacity — why it waits is `jr2 status <runId>`'s `waiting`. A run with none has no `placing` key.
-// A dispatched run (ADR-0071) carries `dispatchedBy` after its id, as the Orchestrator sends it: the
-// run that started it, the caller's slot and the chain's depth, so the chain reads off the listing.
+// A dispatched run (ADR-0071) carries `dispatchedBy`, as the Orchestrator sends it: the run that
+// started it, the caller's slot and the chain's depth, so the chain reads off the listing.
 //
-// The verb also lists the Workflows a run can start (ADR-0070), from `GET /workflows`, as activity on
-// stderr so the result on stdout stays the live runs: one line per Workflow with its origin
-// (`machine`, `chart file`, `chart`), a Chart wrapper's Charts indented under it, and `unrunnable`
-// with its reason. `--workflows` prints that listing as the result instead. No verb puts or deletes
-// a runtime Chart in this step: `PUT`/`DELETE /workflows/<wrapper>/charts/<name>` is for an MCP or curl.
+// The Workflows that a run can start are `jr2 workflows`, not this verb.
 
-import type { RunChild } from "@jr2/orchestrator/internal";
-import { JR2Client, type RunStatus, type WorkflowListing, type WorkflowOrigin } from "../client.ts";
+import { JR2Client } from "../client.ts";
 import { resolveTarget, targetOptions } from "../instance.ts";
-import { activity, result, type Io } from "../output.ts";
+import { result, type Io } from "../output.ts";
 import { parseCommand } from "../command-table.ts";
 
 export async function runs(args: string[], io: Io): Promise<number> {
   const { values } = parseCommand("runs", args);
   const target = await resolveTarget(io, targetOptions(values));
   try {
-    const client = new JR2Client(target.url, io.fetch, target.token);
-    if (values.workflows) {
-      result(io, await client.workflows());
-      return 0;
-    }
-    const live = (await client.list()).map(markListed);
-    // A report beside the result: a listing that cannot be read says why, and the runs still print.
-    try {
-      activity(io, renderWorkflows(await client.workflows()));
-    } catch (e) {
-      activity(io, `workflows: unknown — ${e instanceof Error ? e.message : String(e)}`);
-    }
-    result(io, live);
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
+    const listed = await client.allRuns({
+      ...(typeof values.status === "string" ? { status: values.status } : {}),
+      ...(typeof values.workflow === "string" ? { workflow: values.workflow } : {}),
+      ...(typeof values.since === "string" ? { since: values.since } : {}),
+    });
+    result(io, listed);
     return 0;
   } finally {
     target.close?.();
   }
 }
-
-/** How a listing names an origin (ADR-0070): a runtime Chart is plainly a `chart`. */
-const ORIGIN_LABEL: Record<WorkflowOrigin, string> = { machine: "machine", file: "chart file", runtime: "chart" };
-
-/**
- * The Workflow listing as lines: each Workflow with its origin, a Chart wrapper's Open body and
- * whether its door takes a Chart one-shot, its Charts indented under it, and `unrunnable` with the
- * reason. A Chart the listing also gives at the top level (or whose wrapper it does not list) prints
- * once: under its wrapper when the wrapper is listed, else at the top level.
- */
-export function renderWorkflows(listing: readonly WorkflowListing[]): string {
-  const underWrapper = new Set<string>();
-  for (const w of listing) for (const c of w.wrapper?.charts ?? []) underWrapper.add(chartFullName(w.name, c.name));
-  const line = (indent: string, name: string, label: string, unrunnable?: string): string =>
-    `${indent}${name} (${label})${unrunnable ? ` unrunnable: ${unrunnable}` : ""}`;
-  const out = ["workflows:"];
-  for (const w of listing) {
-    if (w.origin !== "machine" && underWrapper.has(w.name)) continue;
-    const wrapper = w.wrapper;
-    const label = wrapper
-      ? `${ORIGIN_LABEL[w.origin]}, Chart wrapper: body "${wrapper.body}"${wrapper.oneShot ? ", one-shot" : ""}`
-      : ORIGIN_LABEL[w.origin];
-    out.push(line("  ", w.name, label, w.unrunnable));
-    for (const c of wrapper?.charts ?? []) {
-      out.push(line("    ", chartFullName(w.name, c.name), ORIGIN_LABEL[c.origin], c.unrunnable));
-    }
-  }
-  if (out.length === 1) out.push("  none registered — `jr2 up` publishes the Assembly");
-  return out.join("\n");
-}
-
-/** A Chart's Workflow name, `<wrapper>/<name>` (ADR-0070), whether the listing gives it short or whole. */
-function chartFullName(wrapper: string, name: string): string {
-  return name.includes("/") ? name : `${wrapper}/${name}`;
-}
-
-/** The run as `jr2 runs` lists it: `dispatchedBy` after its id when a `dispatch` Effect started it
- * (ADR-0071), and `placing` after that when any Workspace in it is in `placing`. */
-export function markListed(run: RunStatus): RunStatus & { placing?: string[] } {
-  const placing = [...(run.value === "placing" ? [""] : []), ...placingIn(run.children ?? [], [])];
-  if (!placing.length && !run.dispatchedBy) return run;
-  const { runId, dispatchedBy, ...rest } = run;
-  return { runId, ...(dispatchedBy ? { dispatchedBy } : {}), ...(placing.length ? { placing } : {}), ...rest };
-}
-
-/** The paths of every child in `placing`, at any depth — read off the state values alone, which
- * are public (a Workspace's value is the flat state key). */
-function placingIn(children: RunChild[], path: string[]): string[] {
-  return children.flatMap((child) => {
-    const here = [...path, child.id];
-    return [...(child.value === "placing" ? [here.join("/")] : []), ...placingIn(child.children, here)];
-  });
-}

package/src/commands/send.ts

@@ -43,7 +43,7 @@ export async function send(args: string[], io: Io): Promise<number> {
   }
   const target = await resolveTarget(io, targetOptions(values));
   try {
-    const client = new JR2Client(target.url, io.fetch, target.token);
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
     const ref = await resolveRunId(client, given);
     if (!ref.ok) {
       activity(io, ref.message);

package/src/commands/status.ts

@@ -25,8 +25,17 @@
 //
 // A failed run (ADR-0073) says its reason beside the result: `failed: <reason>`. The result's
 // `output` holds the whole Failure, `{ reason, detail? }`.
+//
+// A run says beside the result who started it (ADR-0078): `started by: <via>/<name>`, with the
+// name jr2 shows and the party the Caller said it acts for. A run that a `dispatch` started names
+// its first Caller: the verb walks `startedBy` up the chain of runs to the first one that a Caller
+// started, and names the runs between. A run that jr2 started says why (`started by: jr2 (boot)`).
+// A cancelled run says who cancelled it: `cancelled by: <via>/<name>`. A standing run (ADR-0017)
+// says who resumed it (`resumed by:`) and, once a hand-over ended it, which run took over
+// (`handed over to:`). Bare `jr2 status` prints each standing Workflow: live, paused with the number
+// of items it holds, or waiting out a back-off.
 
-import type { AssemblyView, RepoStatus } from "@jr2/orchestrator/internal";
+import type { AssemblyView, CallerRecord, RepoStatus, StandingView } from "@jr2/orchestrator/internal";
 import { JR2Client, type FetchLike, type RunStatus, workflowPath } from "../client.ts";
 import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
@@ -41,7 +50,7 @@ export async function status(args: string[], io: Io): Promise<number> {
   const given = positionals.length === 0 ? undefined : positionals[0]!;
   const target = await resolveTarget(io, targetOptions(values));
   try {
-    const client = new JR2Client(target.url, io.fetch, target.token);
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
     if (given === undefined) return await instanceStatus(client, io, target.url, values.json === true);
     const ref = await resolveRunId(client, given);
     if (!ref.ok) {
@@ -55,6 +64,9 @@ export async function status(args: string[], io: Io): Promise<number> {
     }
     result(io, s);
     const notes = [
+      await startedByActivity(client, s),
+      cancelledByActivity(s),
+      ...standingRunLines(s),
       failureActivity(s),
       dispatchedActivity(s),
       ...dispatchedLines(s),
@@ -76,6 +88,70 @@ export function failureActivity(s: Pick<RunStatus, "status" | "output">): string
   return typeof reason === "string" ? `failed: ${reason}` : undefined;
 }
 
+/** A Caller as one line names it (ADR-0078): `<via>/<name>`, the name jr2 shows, and the party it
+ * said it acts for. */
+export function callerText(c: CallerRecord): string {
+  return (
+    `${c.via}/${c.name}` +
+    (c.shown !== undefined && c.shown !== c.name ? ` (${c.shown})` : "") +
+    (c.onBehalfOf !== undefined ? ` on behalf of ${c.onBehalfOf}` : "")
+  );
+}
+
+/** The most runs the `started by:` walk reads: a chain of dispatches longer than this is named as
+ * cut, never read without end. */
+const STARTED_BY_HOPS = 16;
+
+/**
+ * The `started by:` line (ADR-0078): the run's first Caller. A run that a `dispatch` started is
+ * walked up its `startedBy` chain, one read per run, to the first run that a Caller or jr2 started;
+ * the line names the runs between, nearest first. A run of the chain that the Caller may not read,
+ * or that is no longer known, ends the walk, and the line says so. Undefined for a run that records
+ * no starter.
+ */
+export async function startedByActivity(
+  client: Pick<JR2Client, "read">,
+  s: Pick<RunStatus, "startedBy">,
+): Promise<string | undefined> {
+  let by = s.startedBy;
+  if (!by) return undefined;
+  const through: string[] = [];
+  const via = () => (through.length ? `, through ${through.join(" ← ")}` : "");
+  while (by.kind === "run") {
+    if (through.length >= STARTED_BY_HOPS) {
+      return `started by: not read — the chain is longer than ${STARTED_BY_HOPS} runs${via()}`;
+    }
+    const hop = `run ${by.run} (${by.slot})`;
+    let next: RunStatus | undefined;
+    try {
+      next = await client.read(by.run);
+    } catch (e) {
+      return `started by: not read — ${hop}: ${e instanceof Error ? e.message : String(e)}${via()}`;
+    }
+    if (!next) return `started by: not known — ${hop} is no longer known${via()}`;
+    through.push(hop);
+    if (!next.startedBy) return `started by: not recorded${via()}`;
+    by = next.startedBy;
+  }
+  if (by.kind === "jr2") return `started by: jr2 (${by.why})${via()}`;
+  const { kind: _kind, ...caller } = by;
+  return `started by: ${callerText(caller)}${via()}`;
+}
+
+/** A standing run's lines (ADR-0017): the Caller whose `jr2 run` resumed it, and the run that took
+ * over from it at a hand-over. */
+export function standingRunLines(s: Pick<RunStatus, "resumedBy" | "handedOverTo">): string[] {
+  return [
+    ...(s.resumedBy ? [`resumed by: ${callerText(s.resumedBy)}`] : []),
+    ...(s.handedOverTo ? [`handed over to: ${s.handedOverTo}`] : []),
+  ];
+}
+
+/** The `cancelled by:` line for a run a Caller cancelled (ADR-0078). */
+export function cancelledByActivity(s: Pick<RunStatus, "cancelledBy">): string | undefined {
+  return s.cancelledBy ? `cancelled by: ${callerText(s.cancelledBy)}` : undefined;
+}
+
 /** The most `dispatched:` lines `jr2 status` prints: a watcher dispatches on every pass, and the
  * result carries the whole list. */
 const DISPATCHED_LINES = 10;
@@ -105,7 +181,16 @@ export function worktreeLines(s: RunStatus): string[] {
 export function dispatchedActivity(s: RunStatus): string | undefined {
   const by = s.dispatchedBy;
   if (!by) return undefined;
-  return `dispatched by: ${by.run} (${by.slot}), depth ${by.depth}${by.instance ? `, from Orchestrator ${by.instance}` : ""}`;
+  // A Pool of runs (ADR-0017) names the item's key, and the Hook delivery that carried it.
+  const pool =
+    by.key !== undefined
+      ? `, key ${by.key}${
+          by.hook
+            ? `, hook ${by.hook.name}, delivery ${by.hook.delivery}${by.hook.onBehalfOf ? `, on behalf of ${by.hook.onBehalfOf}` : ""}`
+            : ""
+        }`
+      : "";
+  return `dispatched by: ${by.run} (${by.slot}), depth ${by.depth}${by.instance ? `, from Orchestrator ${by.instance}` : ""}${pool}`;
 }
 
 /** The `chart: bound` line for a run that binds a Chart (ADR-0070), or undefined for one that binds
@@ -144,17 +229,19 @@ async function instanceStatus(client: JR2Client, io: Io, url: string, json: bool
 
 /** `GET /assembly` (ADR-0069): open, like `GET /workflows`, so it needs no token. An answer that
  * cannot be read is reported as the reason, never as a failure of the verb. */
-async function readAssembly(fetchImpl: FetchLike, url: string): Promise<AssemblyView | { error: string }> {
+async function readAssembly(fetchImpl: FetchLike, url: string): Promise<InstanceAssembly | { error: string }> {
   try {
     const res = await fetchImpl(`${url.replace(/\/+$/, "")}/assembly`);
     if (!res.ok) return { error: `GET /assembly answered HTTP ${res.status}` };
     // Read loosely: a `held` that is absent or not a list reads as none held, so a report never
     // fails on the shape of one field (ADR-0048: a report is not a failure of the asking).
     const view = (await res.json()) as Partial<AssemblyView>;
+    const standing = (view as { standing?: unknown }).standing;
     return {
       kitVersion: view.kitVersion ?? "",
       current: view.current ?? null,
       held: Array.isArray(view.held) ? view.held : [],
+      ...(Array.isArray(standing) ? { standing: standing as StandingView[] } : {}),
     };
   } catch (e) {
     return { error: e instanceof Error ? e.message : String(e) };
@@ -168,7 +255,7 @@ async function readAssembly(fetchImpl: FetchLike, url: string): Promise<Assembly
  * The current Assembly prints first, whatever order `held` uses; the other held Assemblies follow
  * in the server's order.
  */
-function assemblyLines(view: AssemblyView | { error: string } | undefined): string {
+function assemblyLines(view: InstanceAssembly | { error: string } | undefined): string {
   if (view === undefined) return "";
   if ("error" in view) return `assembly: unknown — ${view.error}\n`;
   const current = view.current;
@@ -187,9 +274,37 @@ function assemblyLines(view: AssemblyView | { error: string } | undefined): stri
     if (held.hash === current?.hash) continue;
     out += line(held.hash, held.kitVersion, held.runs.length, false);
   }
+  for (const s of view.standing ?? []) out += `${standingLine(s)}\n`;
   return out;
 }
 
+/** What `GET /assembly` answers, with its standing Workflows (ADR-0017). */
+export type InstanceAssembly = AssemblyView & { standing?: StandingView[] };
+
+/**
+ * One standing Workflow as one line (ADR-0017): its Pool's chain to its callee, and its state. A
+ * paused one says why, how many items it holds and how to resume it; one with no live run and no
+ * pause waits out the back-off of a hand-over.
+ */
+export function standingLine(s: StandingView): string {
+  const items = `${s.held} held item${s.held === 1 ? "" : "s"}`;
+  const head = `standing ${s.workflow} → ${s.callee}`;
+  if (s.state === "live") return `${head}: live, run ${s.run ?? "?"}, ${items}`;
+  if (s.state === "paused") {
+    const why =
+      s.why === "errors"
+        ? "4 runs in a row in which no item that the run took started a run; the last one ended error or failed"
+        : s.why === "bound"
+          ? "4 runs in a row in which no item that the run took started a run; the last one took its bound of items"
+          : "a cancel";
+    return (
+      `${head}: paused (${why}), ${items}${s.run ? ` in run ${s.run}` : ""} — \`jr2 run ${s.workflow}\` resumes it, ` +
+      "and `--drop-held` resumes it with no held item"
+    );
+  }
+  return `${head}: no live run — jr2 starts its next run after the back-off`;
+}
+
 /** The human table — the held Assemblies, current first, one line per Repo, one per node under it, then the
  * hints for what was seen. */
 export function renderInstanceStatus({
@@ -197,7 +312,7 @@ export function renderInstanceStatus({
   dataPlane,
   repos,
 }: {
-  assembly?: AssemblyView | { error: string };
+  assembly?: InstanceAssembly | { error: string };
   dataPlane: boolean;
   repos: RepoStatus[];
 }): string {

package/src/commands/steer.ts

@@ -0,0 +1,47 @@
+// `jr2 steer` (ADR-0002): a Caller's Steering message to one Agent of a live run.
+//
+//   jr2 steer <runId|abbrev> <agent> "<text>"   send the message
+//   jr2 steer <runId|abbrev>                     list the run's Agent slots
+//
+// The address is the Agent SLOT, as the run's list names it (`<machine path>/<agent>`), never an
+// Instance ID: jr2 computes those, and a fresh Turn gets a new one. An open Turn of the slot hears
+// the message at its next step boundary; otherwise the slot's next Turn in the same Machine
+// instance hears it. The run id resolves first, as for every write (ADR-0009).
+
+import { JR2Client } from "../client.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
+import { activity, result, type Io } from "../output.ts";
+import { resolveRunId } from "../run-id.ts";
+import { commandNamed, parseCommand, renderCommand } from "../command-table.ts";
+
+export async function steer(args: string[], io: Io): Promise<number> {
+  const { values, positionals } = parseCommand("steer", args);
+  const [given, agent, text] = positionals;
+  if (!given || (agent !== undefined && text === undefined) || positionals.length > 3) {
+    activity(io, renderCommand(commandNamed("steer")));
+    return 2;
+  }
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
+    const ref = await resolveRunId(client, given);
+    if (!ref.ok) {
+      activity(io, ref.message);
+      return ref.code;
+    }
+    if (agent === undefined || text === undefined) {
+      result(io, await client.agents(ref.runId));
+      return 0;
+    }
+    const sent = await client.steer(ref.runId, agent, text);
+    activity(
+      io,
+      sent.open
+        ? `sent a Steering message to ${sent.agent} on ${ref.runId}: its open Turn hears it at its next step boundary, or its next Turn hears it if this Turn ends first`
+        : `sent a Steering message to ${sent.agent} on ${ref.runId}: its next Turn hears it`,
+    );
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}