@jr2/cli 0.6.0 → 0.7.0

package/src/command-table.ts

@@ -40,8 +40,9 @@ export type Arg = { readonly name: string; readonly optional?: boolean; readonly
 /** One env var the verb reads. */
 export type EnvVar = { readonly name: string; readonly description: string };
 
-/** The ADR-0009 output classes: one JSON result on stdout, a report table on stdout, or activity alone. */
-export type OutputKind = "result" | "report" | "activity";
+/** The ADR-0009 output classes: one JSON result on stdout, a report (a table or lines) on stdout,
+ * activity alone, or one value alone on stdout (a credential, for `$(…)`). */
+export type OutputKind = "result" | "report" | "activity" | "value";
 
 /** What a verb prints. `form` names the spelling that prints it, when that is not the whole verb. */
 export type Output = { readonly kind: OutputKind; readonly form?: string };
@@ -122,7 +123,7 @@ export const JR2_URL = {
 export const JR2_TOKEN = {
   name: "JR2_TOKEN",
   description:
-    "the Instance token to send: with `--url` / `JR2_URL` the only one, and otherwise used in place of the one read from the cluster",
+    "the Caller's credential to send, which makes the CLI that Caller: with `--url` / `JR2_URL` the only one, and otherwise used in place of the Instance token read from the cluster",
 } as const satisfies EnvVar;
 
 /** The addressing every run verb takes: a deployment by kube, or an orchestrator by url. */
@@ -187,7 +188,7 @@ const TABLE = [
     env: [],
     summary: "typecheck this instance and load its workflows, as `jr2 up` does first, with no cluster",
     lines: [
-      "runs the check that `jr2 up` runs before it stages the Assembly, and exits 1 with the same refusal: a type error, a module that refuses to load (a refusal of `createMachine`, `defineEvent` or `workspace()`), an Open part, a Chart file, a dispatch, an Effect secret or a Size",
+      "runs the check that `jr2 up` runs before it stages the Assembly, and exits 1 with its refusal: a type error, a module that refuses to load (`createMachine`, `defineEvent` or `workspace()`), an Open part, a Chart file, a dispatch, an Effect secret or a Size",
       "reads no kube context and writes no file, so an Assistant runs it before it gives a change to the user",
     ],
     output: ACTIVITY,
@@ -206,7 +207,7 @@ const TABLE = [
       {
         name: "skip-provider-preflight",
         description:
-          "do not run the provider preflight: no check pod checks the models, so a check that fails when the model works does not stop the converge",
+          "do not run the provider preflight: no check pod checks the models or reads an MCP server's tool list, so a check that fails while the model or server works does not stop the converge",
       },
       NAMESPACE_FLAG,
       CONTEXT_FLAG,
@@ -215,7 +216,7 @@ const TABLE = [
     summary: "converge the current kube context to this instance",
     lines: [
       "reads each `git.credentials` token from the env var it names, after the Instance's .env",
-      "before the cluster work, sets the text between the jr2-docs markers in AGENTS.md to the docs index of the Kit version, and changes nothing outside them; a folder with no markers is left alone",
+      "before the cluster work, sets the text between the jr2-docs markers in AGENTS.md to the docs index of the Kit version, and nothing else; a folder with no markers is left alone",
     ],
     output: ACTIVITY,
     adrs: ["0019", "0051", "0069", "0072"],
@@ -262,7 +263,7 @@ const TABLE = [
     env: [],
     summary: "mirror the published kit images into a registry",
     lines: [
-      `the v${KIT_VERSION} kit images (harness, operator, orchestrator) from their canonical home, and the Custodian's pinned Envoy from its own, for a cluster whose \`kitRegistry\` names the registry`,
+      `the v${KIT_VERSION} kit images (harness, operator, orchestrator) from their canonical home, and the Custodian's pinned Envoy from its own, for a cluster whose \`kitRegistry\` names it`,
     ],
     output: RESULT,
     adrs: ["0044", "0059", "0069"],
@@ -273,6 +274,10 @@ const TABLE = [
     flags: [
       { name: "input", value: "json", description: "the run's input, as a JSON object (default: {})" },
       { name: "detach", description: "print the runId and return, and do not stream" },
+      {
+        name: "drop-held",
+        description: "resume a paused standing Workflow with no held item: its held items are not carried",
+      },
       ...TARGET_FLAGS,
     ],
     env: TARGET_ENV,
@@ -281,25 +286,70 @@ const TABLE = [
       "--detach: just print the runId and return",
       "a Chart that the door refuses prints one line for each rule that it fails",
       "exits 0 only for a run that ended done, and 1 for every other end: failed, error, cancelled, lost, drifted, or parked before it settled; a failed run prints its reason",
+      "a standing Workflow: jr2 starts its run, so `jr2 run` only resumes a paused one, prints the new run, and returns",
     ],
     output: RESULT,
-    adrs: ["0009", "0070", "0073"],
+    adrs: ["0009", "0017", "0070", "0073"],
   },
   {
     verb: "runs",
     args: [],
     flags: [
-      { name: "workflows", description: "print the Workflow listing as the JSON result instead" },
+      {
+        name: "status",
+        value: "s",
+        description: "live (the default), ended, all, or a comma list such as done,failed,drifted",
+      },
+      { name: "workflow", value: "name", description: "only the runs of this Workflow" },
+      {
+        name: "since",
+        value: "when",
+        description: "only the runs that started since: a duration (2h, 7d) or an ISO-8601 time",
+      },
+      ...TARGET_FLAGS,
+    ],
+    env: TARGET_ENV,
+    summary:
+      'list runs, newest first (live by default); "placing" names the Workspaces that wait for capacity, and "status <runId>" says why',
+    lines: [
+      "each run is a summary: runId, workflow, status, reason, startedBy, startedAt, endedAt, assembly, openGates; an ended run is listed while jr2 keeps it (runs.retain)",
+      "`jr2 workflows` lists the Workflows that a run can start",
+    ],
+    output: RESULT,
+    adrs: ["0009", "0030", "0064", "0065"],
+  },
+  {
+    verb: "workflows",
+    args: [],
+    flags: [
+      { name: "json", description: "print the listing (GET /workflows) as the one report object instead of the tree" },
       ...TARGET_FLAGS,
     ],
     env: TARGET_ENV,
-    summary: 'list live runs; "placing" names the Workspaces that wait for capacity, and "status <runId>" says why',
+    summary: "list the Workflows that a run can start, each with its origin: machine, chart file or chart",
     lines: [
-      "the Workflows a run can start on stderr, each with its origin (machine, chart file, chart) and a Chart wrapper's Charts under it; --workflows prints that listing as the result",
+      "a Chart wrapper's named Charts indent under it; an unrunnable one says why",
       "a runtime Chart has no verb: PUT or DELETE /workflows/<wrapper>/charts/<name> with the Instance token (an MCP or curl), then `jr2 run <wrapper>/<name>` starts it",
     ],
+    output: [{ kind: "report" }],
+    adrs: ["0009", "0070"],
+  },
+  {
+    verb: "gates",
+    args: [],
+    flags: [
+      { name: "workflow", value: "name", description: "only the Gates of this Workflow's runs" },
+      ...TARGET_FLAGS,
+    ],
+    env: TARGET_ENV,
+    summary: "list the open Gates that this Caller may answer, across the live runs, oldest first",
+    lines: [
+      "each Gate is an entry: runId, workflow, gate, path, accepts, acceptsNow, meta, openedAt, and hook (the Hook kinds that it hears); never a run's context",
+      "needs the answer scope; a scope that names single Gates ({ workflow, gates }) lists only those Gates",
+      "`jr2 send <runId> --gate <gate> --event <name>` answers one",
+    ],
     output: RESULT,
-    adrs: ["0009", "0064", "0070"],
+    adrs: ["0009", "0011", "0078"],
   },
   {
     verb: "status",
@@ -315,14 +365,44 @@ const TABLE = [
     adrs: ["0048", "0051", "0073"],
   },
   {
-    verb: "logs",
+    verb: "watch",
     args: [RUN_ID],
-    flags: [{ name: "follow", short: "f", description: "follow until the run settles" }, ...TARGET_FLAGS],
+    flags: [
+      { name: "json", description: "print each status as one JSON line, and the other events on stderr" },
+      ...TARGET_FLAGS,
+    ],
     env: TARGET_ENV,
-    summary: "replay a run's status; -f to follow until it settles",
-    lines: [],
-    output: RESULT,
-    adrs: ["0009"],
+    summary: "follow a run's feed to its end, with the lines that `jr2 run` prints while it is attached",
+    lines: ["on attach it prints where the run is now; an ended run prints its last status once"],
+    output: [{ kind: "report" }],
+    adrs: ["0009", "0022"],
+  },
+  {
+    verb: "logs",
+    args: [
+      RUN_ID,
+      {
+        name: "agent",
+        optional: true,
+        description: "one Agent slot, as `jr2 steer <runId>` lists it, or an Agent name (default: every Agent)",
+      },
+    ],
+    flags: [
+      {
+        name: "follow",
+        short: "f",
+        description: "print each new entry as it is kept, until the run is not live and no conversation is open",
+      },
+      ...TARGET_FLAGS,
+    ],
+    env: TARGET_ENV,
+    summary: "print a run's conversations as the Harness prints them, every Agent interleaved by time, or one Agent",
+    lines: [
+      "each line is `[<agent>] [<instance id>] [<label>] <text>`; Menu-only Agents too; a Working tool's result is never in it",
+      "reads what the Orchestrator keeps of each conversation, so it works after the Sandbox is gone, while jr2 keeps the run (runs.retain); pod logs stay `kubectl logs`",
+    ],
+    output: [{ kind: "report" }],
+    adrs: ["0009", "0023", "0065"],
   },
   {
     verb: "send",
@@ -358,6 +438,174 @@ const TABLE = [
     output: ACTIVITY,
     adrs: ["0009", "0011", "0013", "0025"],
   },
+  {
+    verb: "steer",
+    args: [
+      RUN_ID,
+      { name: "agent", optional: true, description: "the Agent slot, as the run's list names it" },
+      { name: "text", optional: true, description: "the message, at most 16 KiB" },
+    ],
+    flags: [...TARGET_FLAGS],
+    env: TARGET_ENV,
+    summary: "send a Steering message to one Agent of a live run, or list the Agent slots that can hear one",
+    lines: [
+      "an open Turn of the slot hears it at its next step boundary; else, or when that Turn ends first, the slot's next Turn in its Machine instance hears it",
+      "with a runId alone it prints the run's Agent slots, each with open and steerable; `jr2 status` prints the messages sent to the run, in `steering`",
+      "needs the steer scope for the run's Workflow",
+    ],
+    output: [
+      { kind: "activity", form: "steer <runId> <agent> <text>" },
+      { kind: "result", form: "steer <runId>" },
+    ],
+    adrs: ["0002", "0062", "0078"],
+  },
+  {
+    verb: "whoami",
+    args: [],
+    flags: [...TARGET_FLAGS],
+    env: TARGET_ENV,
+    summary: "print the Caller this credential is: how jr2 knows it, its name, what it may do, and whom it acts for",
+    lines: [
+      "on a kube context the Caller is token/instance, on behalf of the kube user; with --url and JR2_TOKEN it is that token's Caller",
+      "needs no scope, so a credential that may do nothing still sees why",
+    ],
+    output: RESULT,
+    adrs: ["0078"],
+  },
+  {
+    verb: "hooks",
+    args: [{ name: "name", description: "the Hook, as `hooks` in jr2.config.ts names it" }],
+    flags: [
+      { name: "limit", value: "n", description: "how many lines, newest first (default 50, at most 1000)" },
+      ...TARGET_FLAGS,
+    ],
+    env: TARGET_ENV,
+    summary:
+      "print a Hook's log: each delivery that jr2 keeps (runs.retain), newest first, and what the door did with it",
+    lines: [
+      "a line is a handshake, a delivery and its outcome, a repeat (seen), a payload the parse refused (with zod's issues), a request the kind could not read, or a failed follow-up post",
+      "needs the Instance token: no scope opens it",
+    ],
+    output: RESULT,
+    adrs: ["0011", "0078"],
+  },
+  {
+    verb: "caller",
+    sub: "token",
+    args: [{ name: "name", description: "the named Caller token, as `callers.tokens` declares it" }],
+    flags: [NAMESPACE_FLAG, CONTEXT_FLAG],
+    env: [],
+    summary: "print a named Caller token's value, read from its Secret over the kube API",
+    lines: ["`jr2 up` makes the value once, for each name that `callers.tokens` declares"],
+    output: [{ kind: "value" }],
+    adrs: ["0078"],
+  },
+  {
+    verb: "caller",
+    sub: "rotate",
+    args: [{ name: "name", description: "the named Caller token, as `callers.tokens` declares it" }],
+    flags: [NAMESPACE_FLAG, CONTEXT_FLAG],
+    env: [],
+    summary: "make a new value for a named Caller token; the old value stops working",
+    lines: [
+      "returns when the Orchestrator has loaded the new digest (about a minute), so the old value is then refused; after 150s it fails, and the old value works until the load",
+      "prints no value: `jr2 caller token <name>` prints the new one",
+    ],
+    output: ACTIVITY,
+    adrs: ["0078"],
+  },
+  {
+    verb: "workspace",
+    sub: "ls",
+    args: [{ name: "run", optional: true, description: "only the Workspaces of this run, or of a prefix of its id" }],
+    flags: [JSON_REPORT, NAMESPACE_FLAG, CONTEXT_FLAG],
+    env: [],
+    summary: "list the Workspaces: handle, Sandbox name, Workflow, phase, age, and whether a run holds it",
+    lines: [
+      "reads the Sandbox CRs over the kube API, with no Orchestrator: kube RBAC is the gate",
+      "a handle is <run-prefix>/<workspace path>, or the Sandbox's name",
+      "held: the run's Lease marked it (a live run, or one that an Orchestrator crash left); released: its run is over; idle: no Lease renewed it for the idle timeout",
+    ],
+    output: [{ kind: "report" }],
+    adrs: ["0009", "0012", "0021"],
+  },
+  {
+    verb: "workspace",
+    sub: "shell",
+    args: [
+      { name: "ws", description: "the Workspace: <run-prefix>/<path>, or its Sandbox's name" },
+      { name: "-- cmd", optional: true, description: "one command to run in place of a shell" },
+    ],
+    flags: [
+      {
+        name: "user",
+        description: "a shell in the User Container (`kubectl exec -c user`), which needs a shell in its image",
+      },
+      NAMESPACE_FLAG,
+      CONTEXT_FLAG,
+    ],
+    env: [],
+    summary:
+      "a shell in the Workspace as its Agents work: started by the Harness's spawner in the Agents' Landlock domain, with the Workspace's granted Stand-ins and its folder",
+    lines: [
+      "it never reaches the control Stand-in or a Stand-in that the Workspace does not grant",
+      "`jr2 workspace shell <ws> -- git status` runs one command with no terminal: Ctrl-C ends jr2, and the command gets the end of its input but no signal, so one that ignores it (a dev server) runs on",
+    ],
+    output: ACTIVITY,
+    adrs: ["0009", "0076"],
+  },
+  {
+    verb: "workspace",
+    sub: "forward",
+    args: [
+      { name: "ws", description: "the Workspace: <run-prefix>/<path>, its Sandbox's name, or <name>.jr2" },
+      { name: "port", description: "the port in the Sandbox pod" },
+    ],
+    flags: [
+      {
+        name: "stdio",
+        description: "carry one connection on stdin and stdout, for an ssh ProxyCommand",
+      },
+      NAMESPACE_FLAG,
+      CONTEXT_FLAG,
+    ],
+    env: [],
+    summary: "forward a local port to a port in the Workspace's pod; prints 127.0.0.1:<port> and holds it until Ctrl-C",
+    lines: [
+      "ssh: Host *.jr2 with ProxyCommand jr2 workspace forward %h 22 --stdio -n <ns>, then ssh <sandbox name>.jr2",
+      "there is no Service for the User Container: the forward goes through the kube API",
+    ],
+    output: [{ kind: "value" }],
+    adrs: ["0005", "0009"],
+  },
+  {
+    verb: "workspace",
+    sub: "rm",
+    args: [{ name: "ws", description: "the Workspace: <run-prefix>/<path>, or its Sandbox's name" }],
+    flags: [NAMESPACE_FLAG, CONTEXT_FLAG],
+    env: [],
+    summary: "remove a Sandbox that no run holds: released, or idle past its idle timeout",
+    lines: [
+      "refuses the Sandbox of a live run: cancel the run first; there is no --force",
+      "the keepalive's age is read on the API server's clock",
+    ],
+    output: ACTIVITY,
+    adrs: ["0009", "0021"],
+  },
+  {
+    verb: "completion",
+    args: [{ name: "shell", description: "bash, zsh or fish" }],
+    flags: [],
+    env: [],
+    summary: "print the shell completion script",
+    lines: [
+      "the script asks this jr2 for each completion, so the verbs and flags are the command table's",
+      "it completes Workspace handles, live run ids, Workflow names and a run's Agent slots too; a lookup that takes more than 2 s offers nothing",
+      "bash: source <(jr2 completion bash); zsh: source <(jr2 completion zsh); fish: jr2 completion fish | source",
+    ],
+    output: [{ kind: "value" }],
+    adrs: ["0009"],
+  },
 ] as const satisfies readonly Command[];
 
 /** Every verb, in help order. */
@@ -403,8 +651,9 @@ export const SECTIONS: readonly Section[] = [
     title: "output",
     text:
       `result verbs (${printing("result").join(", ")}) print one JSON result on stdout and activity on stderr, ` +
-      `so \`jr2 run … | jq\` yields the result; report verbs (${printing("report").join(", ")}) print a table on ` +
-      `stdout, or the one object with --json; activity verbs (${printing("activity").join(", ")}) print activity alone`,
+      `so \`jr2 run … | jq\` yields the result; report verbs (${printing("report").join(", ")}) print a table or lines on ` +
+      `stdout, or their JSON with --json (watch: one JSON line for each status; logs has no --json); activity verbs (${printing("activity").join(", ")}) print activity alone; ` +
+      `value verbs (${printing("value").join(", ")}) print one value alone on stdout, for \`$(…)\`, and activity on stderr`,
   },
 ];
 

package/src/commands/caller.ts

@@ -0,0 +1,115 @@
+// `jr2 caller token <name>` and `jr2 caller rotate <name>` (ADR-0078): a named Caller token's value,
+// and a new one.
+//
+// Both read and write the values over the kube API and never through the Orchestrator, as the
+// Instance token's read does (ADR-0019): kube RBAC on the token's Secret is the gate. So they take
+// the deployment's addressing (`-n`, `--context`) and not `--url`: an Orchestrator holds only the
+// digests, and no route of it gives a value.
+//
+// `token` prints the value alone on stdout, so `JR2_TOKEN=$(jr2 caller token ci)` holds it. `rotate`
+// makes a new value and prints none. The old value stops working when the Orchestrator loads the
+// new digest, after the kubelet updates its mount. So `rotate` waits for that, as `jr2 up` does,
+// over a port-forward to the Orchestrator's open `GET /assembly`, which gives digests and no value.
+
+import { basename } from "node:path";
+import { callerTokenSecret, loadConfig, ORCHESTRATOR_PORT, ORCHESTRATOR_SERVICE } from "@jr2/orchestrator/internal";
+import { rotateCallerToken } from "../caller-tokens.ts";
+import { commandNamed, parseCommand, renderCommand, usageLine } from "../command-table.ts";
+import { CALLER_TOKEN_KEY } from "../deploy.ts";
+import { resolveRoot } from "../instance.ts";
+import { kubectlAdmin, kubectlKube } from "../kube.ts";
+import { awaitMounts, staleLine, type MountsView } from "../mount-wait.ts";
+import { activity, type Io } from "../output.ts";
+
+export async function caller(args: string[], io: Io): Promise<number> {
+  const sub = args[0];
+  if (sub !== "token" && sub !== "rotate") {
+    activity(io, sub === undefined ? "jr2 caller: no subcommand" : `unknown caller subcommand: ${sub}`);
+    activity(io, [commandNamed("caller token"), commandNamed("caller rotate")].map(renderCommand).join("\n\n"));
+    return 2;
+  }
+  const { values, positionals } =
+    sub === "token" ? parseCommand("caller token", args) : parseCommand("caller rotate", args);
+  const name = positionals[1];
+  if (!name) {
+    activity(io, `jr2 caller ${sub}: no token name`);
+    activity(io, usageLine(sub === "token" ? "caller token" : "caller rotate"));
+    return 2;
+  }
+
+  const root = resolveRoot(io.cwd);
+  const config = (await loadConfig(root)) ?? {};
+  const instance = config.name ?? basename(root);
+  const namespace = (values.namespace as string | undefined) ?? instance;
+  const ctx = values.context ? { context: values.context as string } : {};
+
+  if (sub === "token") {
+    const kube = io.kube ?? kubectlKube;
+    const context = (values.context as string | undefined) ?? (await kube.currentContext());
+    if (!context) throw new Error("no kube context — `kind create cluster` (or point kubectl at one), then `jr2 up`");
+    activity(io, `→ context ${context} / namespace ${namespace}`);
+    let value: string | undefined;
+    try {
+      value = await kube.readSecret({ namespace, name: callerTokenSecret(name), key: CALLER_TOKEN_KEY, ...ctx });
+    } catch (e) {
+      throw new Error(`cannot reach the cluster — context ${context}: ${(e as Error).message}`);
+    }
+    if (!value) {
+      throw new Error(
+        `no Caller token "${name}" here (context ${context}, namespace ${namespace}) — declare it in ` +
+          "callers.tokens of jr2.config.ts, then `jr2 up` makes it",
+      );
+    }
+    io.stdout(`${value}\n`);
+    return 0;
+  }
+
+  const kube = io.kubeAdmin ?? kubectlAdmin;
+  const context = (values.context as string | undefined) ?? (await kube.context());
+  if (!context) throw new Error("no kube context — `kind create cluster` (or point kubectl at one), then `jr2 up`");
+  activity(io, `→ context ${context} / namespace ${namespace}`);
+  const applied = await rotateCallerToken(kube, { instance, namespace, name, ctx });
+  const stale = await awaitLoaded(io, { namespace, ctx, want: applied, prefix: `caller token "${name}"` });
+  if (stale.length) {
+    activity(
+      io,
+      `caller token "${name}": rotated, but ${staleLine(stale)}; the old value still works until it does. ` +
+        `\`jr2 caller token ${name}\` prints the new one`,
+    );
+    return 1;
+  }
+  activity(
+    io,
+    `caller token "${name}": rotated — the old value no longer works; \`jr2 caller token ${name}\` prints the new one`,
+  );
+  return 0;
+}
+
+/**
+ * Wait until the Orchestrator has loaded the digests that `want` names (ADR-0078), over a
+ * port-forward of its Service, as `jr2 up` reaches it. Returns the names that were still older when
+ * the wait ended: none when it succeeded.
+ */
+async function awaitLoaded(
+  io: Io,
+  opts: { namespace: string; ctx: { context?: string }; want: Record<string, string>; prefix: string },
+): Promise<string[]> {
+  const fetchImpl = io.fetch ?? globalThis.fetch;
+  const fwd = await (io.kube ?? kubectlKube).portForward({
+    namespace: opts.namespace,
+    service: ORCHESTRATOR_SERVICE,
+    port: ORCHESTRATOR_PORT,
+    ...opts.ctx,
+  });
+  try {
+    const base = fwd.url.replace(/\/+$/, "");
+    const view = async (): Promise<MountsView> => {
+      const res = await fetchImpl(`${base}/assembly`);
+      if (!res.ok) throw new Error(`the Orchestrator answered GET /assembly with HTTP ${res.status}`);
+      return (await res.json()) as MountsView;
+    };
+    return (await awaitMounts(io, { seen: await view(), view, want: opts.want, prefix: opts.prefix })).stale;
+  } finally {
+    fwd.close();
+  }
+}