@junoflow/cli 0.14.0 → 0.17.0

package/src/commands/init.js

@@ -44,7 +44,7 @@ export async function init(argv, io) {
   io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
   io.log('npm test');
   io.log('npm run deploy');
-  await printAuthoringIndex('integration', client, target, io);
+  await printAuthoringIndex('integration', client, io);
   return 0;
 }
 

package/src/commands/permissions.js

@@ -0,0 +1,47 @@
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+
+export const PERMISSIONS_USAGE =
+  'juno permissions [--allow-change] [--working-copy] [--json]';
+
+/**
+ * `juno permissions` prints a Claude Code permission block on stdout,
+ * `{"permissions":{"allow":[…]}}`: every read command, plus every change
+ * command with --allow-change, plus the working copy's npm scripts of the same
+ * tiers with --working-copy. No act command is ever in it — the server
+ * (GET /api/agent-permissions) leaves them out, and the CLI adds nothing.
+ * Where to put the block goes to stderr, so stdout stays the JSON alone.
+ * `--json` prints the route's body instead.
+ */
+export async function permissions(args, io) {
+  if (args._.length > 0) {
+    throw new UsageError(
+      `juno permissions takes no argument; usage: ${PERMISSIONS_USAGE}`
+    );
+  }
+  const { client } = await connect(args, io);
+  const tiers = await client.getAgentPermissions();
+
+  if (args.json) return printJSON(tiers, io);
+
+  const pick = (t) => [
+    ...(t?.read ?? []),
+    ...(args['allow-change'] ? (t?.change ?? []) : []),
+  ];
+  const allow = pick(tiers);
+  if (args['working-copy']) allow.push(...pick(tiers.working_copy));
+
+  io.warn(
+    args['working-copy']
+      ? "Add these rules to this working copy's .claude/settings.json — not to user-wide settings, " +
+          "where they would also allow any other project's npm scripts:"
+      : 'Add these rules to .claude/settings.json (or ~/.claude/settings.json) to run them without a prompt:'
+  );
+  return printJSON({ permissions: { allow } }, io);
+}
+
+/** Compact off a TTY, indented on one, as every JSON the CLI prints. */
+function printJSON(value, io) {
+  io.log(io.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+  return 0;
+}

package/src/commands/run-follow.js

@@ -0,0 +1,68 @@
+import { connect } from '../api.js';
+import { UsageError, UserError } from '../errors.js';
+import { EXIT_INTERRUPTED } from '../exit.js';
+import { runTool } from './tool.js';
+
+/**
+ * `juno run get <run-id> --follow` follows a run as it happens, then prints
+ * what `juno run get` prints. It is a flag on the tool row rather than a row
+ * of its own because the answer is the tool's: the steps stream to stderr as
+ * they finish (`GET /api/flows/{id}/runs/{seq}/trace/stream`, the run page's
+ * live trace), and once the stream says the run is done, get_run's result is
+ * stdout, exactly as without the flag. A run already finished prints at once.
+ * A run waiting on something (an `ask`, a timer) has not finished, so the
+ * follow waits with it; Ctrl-C stops following and leaves the run alone.
+ */
+export async function runFollow(row, args, io) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) {
+    throw new UsageError(`usage: juno ${row.command} <run-id> --follow`);
+  }
+  const { client } = await connect(args, io);
+  const run = await client.rest(
+    'GET',
+    `/api/runs/${encodeURIComponent(id)}`,
+    undefined,
+    { notFound: `no run ${id}` }
+  );
+  const stream = `/api/flows/${encodeURIComponent(run.flow_id)}/runs/${run.seq}/trace/stream`;
+
+  const interrupt = new AbortController();
+  const off = io.onInterrupt?.(() => interrupt.abort()) ?? (() => {});
+  let done = false;
+  try {
+    for await (const { event, data } of client.events(stream, {
+      signal: interrupt.signal,
+    })) {
+      if (event === 'snapshot') {
+        io.warn(`following ${run.flow_id} run ${run.seq} (${data.status})`);
+        for (const step of data.steps ?? []) io.warn(stepLine(step));
+      } else if (event === 'step') {
+        io.warn(stepLine(data.step ?? {}));
+      } else if (event === 'done') {
+        io.warn(`run ${data.status}${data.error ? `: ${data.error}` : ''}`);
+        done = true;
+        break;
+      }
+    }
+  } finally {
+    off();
+  }
+  if (interrupt.signal.aborted) {
+    io.warn(`stopped following; the run goes on: juno run get ${id}`);
+    return EXIT_INTERRUPTED;
+  }
+  if (!done) {
+    throw new UserError(
+      `the trace stream of run ${id} ended before the run did; read it with: juno run get ${id}`
+    );
+  }
+  return runTool(row, { ...args, follow: undefined }, io);
+}
+
+/** stepLine is one step as a line of progress. */
+function stepLine(step) {
+  const took = step.duration_ms != null ? ` ${step.duration_ms}ms` : '';
+  const err = step.error ? `: ${step.error}` : '';
+  return `  ${step.step_id} ${step.step_type} ${step.status}${took}${err}`;
+}

package/src/commands/session-approve.js

@@ -17,6 +17,10 @@ export const SESSION_APPROVE_USAGE =
  * It checks first that the session is awaiting an approval — anything else
  * sent to a question would be taken as the answer — then sends `approve` as
  * `juno ask` would, and prints and exits the same way.
+ *
+ * A destructive tool's approval (`pending_input.approval_id`) is refused: it
+ * is answered only by a person in Juno, on the page it names, and the server
+ * refuses an `approve` sent to it anyway.
  */
 export async function sessionApprove(args, io) {
   const [id, ...extra] = args._;
@@ -25,10 +29,10 @@ export async function sessionApprove(args, io) {
   }
   const wait = waitSeconds(args.wait);
 
-  const { client } = await connect(args, io);
+  const { client, target } = await connect(args, io);
   const session = await client.getAgentSession(id);
   if (!session) throw new UserError(`no assistant session ${id}`);
-  const refusal = notAwaitingApproval(session, id);
+  const refusal = notAwaitingApproval(session, id, target);
   if (refusal) throw new UserError(refusal);
 
   const body = {
@@ -48,8 +52,11 @@ export async function sessionApprove(args, io) {
 }
 
 /** What the session is doing instead of waiting on an approval, if it is. */
-function notAwaitingApproval(session, id) {
+function notAwaitingApproval(session, id, target) {
   const pending = session.pending_input;
+  if (session.status === 'awaiting_input' && pending?.approval_id) {
+    return `this approval can only be answered in Juno: ${approvalURL(pending, target)}`;
+  }
   if (session.status === 'awaiting_input' && pending?.kind === 'approval') {
     return null;
   }
@@ -71,3 +78,15 @@ function notAwaitingApproval(session, id) {
   }
   return `session ${id} has ended (status: ${session.status}); there is nothing to approve`;
 }
+
+/**
+ * The page an approval is decided on: the server's link, which is a bare path
+ * while the instance has no public URL — completed against the instance this
+ * CLI reached.
+ */
+function approvalURL(pending, target) {
+  const url = pending.approval_url ?? `/approvals/${pending.approval_id}`;
+  return url.startsWith('/')
+    ? `${String(target).replace(/\/+$/, '')}${url}`
+    : url;
+}

package/src/commands/session.js

@@ -0,0 +1,103 @@
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { EXIT_OK } from '../exit.js';
+import { json } from './approval-wait.js';
+
+// The assistant's sessions, over /api/agent… as the web UI's Assistant pages
+// read and drive them. They call no tool: a session is the in-app assistant's
+// conversation, not a resource the gateway serves. `session approve` (its own
+// file) is the fourth driving command; these never answer what a session
+// waits on.
+
+export const SESSION_LIST_USAGE =
+  'juno session list [--rating up|down|unaddressed|addressed|unrated] [--profile assistant|author|integration_author|app_author] [--limit <n>]';
+export const SESSION_GET_USAGE = 'juno session get <session-id> [--transcript]';
+export const SESSION_EXPORT_USAGE = 'juno session export <session-id>';
+export const SESSION_RATE_USAGE =
+  'juno session rate <session-id> --rating up|down|addressed|none';
+export const SESSION_CANCEL_USAGE = 'juno session cancel <session-id>';
+
+/** The words `--rating` takes on `session rate`, as the route's numbers. */
+const RATINGS = { up: 2, none: 0, addressed: -1, down: -2 };
+
+/** oneID is the single session id a command takes. */
+function oneID(args, usage) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) throw new UsageError(`usage: ${usage}`);
+  return id;
+}
+
+/** sessionPath is /api/agent/{id} plus suffix, and the 404 it answers. */
+function sessionPath(id, suffix = '') {
+  return [
+    `/api/agent/${encodeURIComponent(id)}${suffix}`,
+    { notFound: `no assistant session ${id}` },
+  ];
+}
+
+async function print(io, value) {
+  await json(io)(value);
+  return EXIT_OK;
+}
+
+/** `juno session list`: GET /api/agent, newest first. */
+export async function sessionList(args, io) {
+  if (args._.length) throw new UsageError(`usage: ${SESSION_LIST_USAGE}`);
+  const query = new URLSearchParams();
+  if (args.rating !== undefined) query.set('rating', args.rating);
+  if (args.profile !== undefined) query.set('profile', args.profile);
+  if (args.limit !== undefined) {
+    if (!/^\d+$/.test(args.limit)) {
+      throw new UsageError(`--limit takes a number, got "${args.limit}"`);
+    }
+    query.set('limit', args.limit);
+  }
+  const { client } = await connect(args, io);
+  const qs = query.size ? `?${query}` : '';
+  return print(io, await client.rest('GET', `/api/agent${qs}`));
+}
+
+/** `juno session get <id>`: GET /api/agent/{id}, with its transcript on request. */
+export async function sessionGet(args, io) {
+  const id = oneID(args, SESSION_GET_USAGE);
+  const { client } = await connect(args, io);
+  const [path, opts] = sessionPath(
+    id,
+    args.transcript ? '?transcript=true' : ''
+  );
+  return print(io, await client.rest('GET', path, undefined, opts));
+}
+
+/** `juno session export <id>`: GET /api/agent/{id}/export. */
+export async function sessionExport(args, io) {
+  const id = oneID(args, SESSION_EXPORT_USAGE);
+  const { client } = await connect(args, io);
+  const [path, opts] = sessionPath(id, '/export');
+  return print(io, await client.rest('GET', path, undefined, opts));
+}
+
+/** `juno session rate <id> --rating …`: PUT /api/agent/{id}/rating. */
+export async function sessionRate(args, io) {
+  const id = oneID(args, SESSION_RATE_USAGE);
+  if (!Object.hasOwn(RATINGS, args.rating ?? '')) {
+    throw new UsageError(
+      `--rating takes up, down, addressed or none; usage: ${SESSION_RATE_USAGE}`
+    );
+  }
+  const { client } = await connect(args, io);
+  const [path, opts] = sessionPath(id, '/rating');
+  return print(
+    io,
+    await client.rest('PUT', path, { rating: RATINGS[args.rating] }, opts)
+  );
+}
+
+/** `juno session cancel <id>`: POST /api/agent/{id}/cancel. */
+export async function sessionCancel(args, io) {
+  const id = oneID(args, SESSION_CANCEL_USAGE);
+  const { client } = await connect(args, io);
+  // The orchestrator's own words on a 404: an unknown session and one that
+  // has already ended are both refused there.
+  const [path] = sessionPath(id, '/cancel');
+  return print(io, await client.rest('POST', path));
+}

package/src/commands/skill.js

@@ -1,27 +1,25 @@
 import { connect } from '../api.js';
 import { UsageError } from '../errors.js';
-import { warnIfStale } from '../installed-skill.js';
 import { levenshtein } from '../suggest.js';
 
-export const SKILL_USAGE = 'juno skill [<name>] [--json]';
+export const SKILL_USAGE = 'juno skill [<name>...] [--json]';
 
 /**
  * `juno skill` prints the skills the instance serves: with no name, one line
- * per skill; with a name, that skill's body exactly as served. `--json`
- * prints the route's JSON instead. The server renders each tool reference as
- * the `juno` command in front of it; the CLI does not rewrite them. The index
- * also says when an installed agent skill is older than what the instance
- * serves (installed-skill.js).
+ * per skill; with names, those skills' bodies exactly as served — one name
+ * prints the body alone, several put a `===== <name> =====` line before
+ * each, so one call loads everything a task needs. `--json` prints the
+ * route's JSON instead: the index, one skill's detail, or an array of them.
+ * Every name is resolved before anything is printed, so an unknown one fails
+ * the call with nothing written. The server renders each tool reference as
+ * the `juno` command in front of it; the CLI does not rewrite them.
  */
 export async function skill(args, io) {
-  const [name, ...extra] = args._;
-  if (extra.length) throw new UsageError(`usage: ${SKILL_USAGE}`);
+  const names = args._;
+  const { client } = await connect(args, io);
 
-  const { target, client } = await connect(args, io);
-
-  if (name === undefined) {
+  if (names.length === 0) {
     const index = await client.listSkills();
-    await warnIfStale(index, target, io);
     if (args.json) return printJSON(index, io);
     for (const s of index?.skills ?? []) {
       io.log(`${s.name} — ${s.description}`);
@@ -29,17 +27,28 @@ export async function skill(args, io) {
     return 0;
   }
 
-  const detail = await client.getSkill(name);
-  if (!detail) {
+  const details = await Promise.all(names.map((n) => client.getSkill(n)));
+  const missing = names.find((_, i) => !details[i]);
+  if (missing !== undefined) {
     const { skills = [] } = (await client.listSkills()) ?? {};
     throw unknownSkill(
-      name,
+      missing,
       skills.map((s) => s.name)
     );
   }
-  if (args.json) return printJSON(detail, io);
-  // Verbatim: the body's own trailing newline is the last byte written.
-  io.write(detail.body);
+  if (args.json) {
+    return printJSON(details.length === 1 ? details[0] : details, io);
+  }
+  if (details.length === 1) {
+    // Verbatim: the body's own trailing newline is the last byte written.
+    io.write(details[0].body);
+    return 0;
+  }
+  details.forEach((d, i) => {
+    if (i > 0) io.write('\n');
+    io.write(`===== ${d.name} =====\n\n`);
+    io.write(d.body);
+  });
   return 0;
 }
 

package/src/commands/{job-run.js → task-run.js}

@@ -8,8 +8,8 @@ import { parseArgs } from 'node:util';
 import { UsageError } from '../errors.js';
 import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
 
-export const JOB_RUN_USAGE =
-  'juno job run [<url>] [--url-file <path>] [--verbose] -- <command> [args…]';
+export const TASK_RUN_USAGE =
+  'juno task run [<url>] [--url-file <path>] [--verbose] -- <command> [args…]';
 
 /** The tail of each stream a run reports; Juno keeps the same. */
 export const TAIL_BYTES = 64 << 10;
@@ -24,7 +24,7 @@ const DEFAULT_TIMEOUTS = {
 };
 
 /**
- * `juno job run` runs a command and reports it to an external job's ping URL
+ * `juno task run` runs a command and reports it to a task's ping URL
  * (plan-external-jobs-2-wrapper-and-tools.md, Decisions 3–5). Its first rule
  * is transparency: the command gets the same stdin, and the wrapper's stdout,
  * stderr and exit status are the command's, byte for byte — a scheduler such
@@ -34,11 +34,11 @@ const DEFAULT_TIMEOUTS = {
  * on its own, so the wrapper never queues and never fails the command.
  *
  * It reads no Juno config and no API key; the URL is all it needs. argv is
- * everything after `job run`, `--` included. The exit code is returned, not
+ * everything after `task run`, `--` included. The exit code is returned, not
  * passed to process.exit, so stdout is flushed before the process ends.
  * deps is injectable for the tests; the default binds the real ones.
  */
-export async function jobRun(argv, io, deps = {}) {
+export async function taskRun(argv, io, deps = {}) {
   const {
     spawn = nodeSpawn,
     fetch = globalThis.fetch,
@@ -65,20 +65,20 @@ export async function jobRun(argv, io, deps = {}) {
     });
   } catch (err) {
     throw new UsageError(
-      `juno job run: ${err.message}\nusage: ${JOB_RUN_USAGE}`
+      `juno task run: ${err.message}\nusage: ${TASK_RUN_USAGE}`
     );
   }
   if (command.length === 0) {
     throw new UsageError(
-      `juno job run: missing -- <command>\nusage: ${JOB_RUN_USAGE}`
+      `juno task run: missing -- <command>\nusage: ${TASK_RUN_USAGE}`
     );
   }
   if (parsed.positionals.length > 1) {
     throw new UsageError(
-      `juno job run: one URL before --, got ${parsed.positionals.length} arguments\nusage: ${JOB_RUN_USAGE}`
+      `juno task run: one URL before --, got ${parsed.positionals.length} arguments\nusage: ${TASK_RUN_USAGE}`
     );
   }
-  const url = await pingURL('job run', JOB_RUN_USAGE, {
+  const url = await pingURL('task run', TASK_RUN_USAGE, {
     positional: parsed.positionals[0],
     file: parsed.values['url-file'],
     env,
@@ -107,7 +107,11 @@ export async function jobRun(argv, io, deps = {}) {
   let suffix;
   let exitCode;
   if (outcome.startError) {
-    const line = `juno job run: ${command[0]}: ${outcome.startError.message}`;
+    // With no shell, `FOO=bar cmd` names an executable called "FOO=bar".
+    const line =
+      outcome.startError.code === 'ENOENT' && command[0].includes('=')
+        ? `juno task run: "${command[0]}" looks like an env assignment; write -- env ${command.join(' ')}`
+        : `juno task run: ${command[0]}: ${outcome.startError.message}`;
     io.error(line);
     err.push(Buffer.from(`${line}\n`));
     suffix = 'fail';
@@ -136,14 +140,14 @@ export async function jobRun(argv, io, deps = {}) {
     failure = await finish();
   }
   if (failure && verbose) {
-    io.error(`juno job run: could not report to Juno: ${failure}`);
+    io.error(`juno task run: could not report to Juno: ${failure}`);
   }
   return exitCode;
 }
 
 /**
  * pingURL is the URL from the first source that yields one: the positional,
- * then --url-file (its contents, trimmed), then $JUNO_JOB_URL. The two
+ * then --url-file (its contents, trimmed), then $JUNO_TASK_URL. The two
  * indirect sources keep the token off the command line, where `ps` and the
  * scheduler's job definition would show it. command and usage name the verb
  * in its refusals.
@@ -165,26 +169,26 @@ async function pingURL(
     }
     if (text.trim()) return text.trim();
   }
-  if (env.JUNO_JOB_URL?.trim()) return env.JUNO_JOB_URL.trim();
+  if (env.JUNO_TASK_URL?.trim()) return env.JUNO_TASK_URL.trim();
   throw new UsageError(
-    `juno ${command}: no ping URL — pass it, --url-file or JUNO_JOB_URL\nusage: ${usage}`
+    `juno ${command}: no ping URL — pass it, --url-file or JUNO_TASK_URL\nusage: ${usage}`
   );
 }
 
 /**
  * endpoint is `<url>/<suffix>?rid=<rid>`, used as given otherwise: no /ping/
- * check, so a Healthchecks URL works too. A query the URL already carries is
- * kept; without a rid there is no `rid` parameter.
+ * check, so a Healthchecks URL works too. An empty suffix is a success, which
+ * is the bare URL. A query the URL already carries is kept; without a rid
+ * there is no `rid` parameter.
  */
 export function endpoint(url, suffix, rid) {
   const q = url.indexOf('?');
-  const path = (q === -1 ? url : url.slice(0, q)).replace(/\/+$/, '');
+  const base = (q === -1 ? url : url.slice(0, q)).replace(/\/+$/, '');
+  const path = suffix ? `${base}/${suffix}` : base;
   const params = [];
   if (q !== -1 && q < url.length - 1) params.push(url.slice(q + 1));
   if (rid) params.push(`rid=${encodeURIComponent(rid)}`);
-  return params.length
-    ? `${path}/${suffix}?${params.join('&')}`
-    : `${path}/${suffix}`;
+  return params.length ? `${path}?${params.join('&')}` : path;
 }
 
 /**
@@ -291,24 +295,24 @@ export class Tail {
   }
 }
 
-export const JOB_PING_USAGE =
-  'juno job ping [<url>] [--url-file <path>] [--start | --fail | --exit <0-255> | --log] [--rid <id>]';
+export const TASK_PING_USAGE =
+  'juno task ping [<url>] [--url-file <path>] [--start | --fail | --exit <0-255> | --log] [--rid <id>]';
 
 const PING_KINDS = ['start', 'fail', 'exit', 'log'];
 
 /**
- * `juno job ping` sends one report to an external job's ping URL, for a task
- * `job run` cannot wrap — one whose scheduler runs no command, or whose start
+ * `juno task ping` sends one report to a task's ping URL, for a task
+ * `task run` cannot wrap — one whose scheduler runs no command, or whose start
  * and finish happen in different places. Without a flag it reports success;
  * `--start`, `--fail`, `--exit <n>` and `--log` send the other reports, and
  * `--rid` pairs a start with its finish. It sends no output.
  *
- * It finds the URL as `job run` does and, like it, reads no Juno config and no
- * API key. Unlike `job run` it has nothing else to do, so a report that still
+ * It finds the URL as `task run` does and, like it, reads no Juno config and no
+ * API key. Unlike `task run` it has nothing else to do, so a report that still
  * fails after one retry is exit 1 with the reason, not silence: the caller
  * asked for exactly this and can `|| true` it.
  */
-export async function jobPing(args, io, deps = {}) {
+export async function taskPing(args, io, deps = {}) {
   const {
     fetch = globalThis.fetch,
     env = process.env,
@@ -316,7 +320,7 @@ export async function jobPing(args, io, deps = {}) {
     timeouts = DEFAULT_TIMEOUTS,
   } = deps;
   const usage = (msg) =>
-    new UsageError(`juno job ping: ${msg}\nusage: ${JOB_PING_USAGE}`);
+    new UsageError(`juno task ping: ${msg}\nusage: ${TASK_PING_USAGE}`);
 
   if (args._.length > 1) {
     throw usage(`one URL, got ${args._.length} arguments`);
@@ -327,7 +331,8 @@ export async function jobPing(args, io, deps = {}) {
   if (kinds.length > 1) {
     throw usage(`--${kinds.join(' and --')} are different reports; pick one`);
   }
-  let suffix = 'success';
+  // A success is the bare URL: the protocol has no /success suffix.
+  let suffix = '';
   if (kinds[0] === 'exit') {
     const n = args.exit.trim();
     if (!/^\d{1,3}$/.test(n) || Number(n) > 255) {
@@ -337,7 +342,7 @@ export async function jobPing(args, io, deps = {}) {
   } else if (kinds[0]) {
     suffix = kinds[0];
   }
-  const url = await pingURL('job ping', JOB_PING_USAGE, {
+  const url = await pingURL('task ping', TASK_PING_USAGE, {
     positional: args._[0],
     file: args['url-file'],
     env,
@@ -356,7 +361,7 @@ export async function jobPing(args, io, deps = {}) {
     failure = await send();
   }
   if (failure) {
-    io.error(`juno job ping: could not report to Juno: ${failure}`);
+    io.error(`juno task ping: could not report to Juno: ${failure}`);
     return EXIT_FAILURE;
   }
   return EXIT_OK;

package/src/commands/tool.js

@@ -3,9 +3,10 @@ import { readFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
-import { connect } from '../api.js';
+import { connect, skillsPointer } from '../api.js';
 import { UsageError, UserError } from '../errors.js';
 import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
+import { approvalWaitSeconds, followApproval } from './approval-wait.js';
 
 /**
  * runTool runs one tool row of verbs.json: build the tool's input from the
@@ -16,9 +17,23 @@ import { EXIT_FAILURE, EXIT_OK } from '../exit.js';
  */
 export async function runTool(row, args, io) {
   const input = await buildInput(row, args, io);
+  const wait = approvalWaitSeconds(args.wait);
 
-  const { client } = await connect(args, io);
-  const { result, text } = await client.callTool(row.tool, input);
+  const { client, target } = await connect(args, io);
+  const { result, text, skills } = await client.callTool(row.tool, input);
+
+  // A destructive tool runs nothing until a person approves it in Juno: it
+  // answers approval_required, and the command waits for the decision
+  // (plan-cli-parity.md decision 11, the one result the CLI interprets).
+  const required = result?.approval_required;
+  if (required && typeof required === 'object' && required.id) {
+    const print = async (value) => {
+      const out = JSON.stringify(value);
+      if (args.jq !== undefined) io.log(await runJq(args.jq, out, io));
+      else io.log(io.isTTY ? JSON.stringify(value, null, 2) : out);
+    };
+    return followApproval(required, { client, target, wait, io, print });
+  }
 
   if (args.jq !== undefined) {
     io.log(await runJq(args.jq, text, io));
@@ -26,8 +41,11 @@ export async function runTool(row, args, io) {
     io.log(io.isTTY ? JSON.stringify(result, null, 2) : text.trimEnd());
   }
   // A tool reports a domain failure as a 200 with a top-level string error:
-  // it is printed like any result, and only the exit code says it failed.
-  return typeof result?.error === 'string' ? EXIT_FAILURE : EXIT_OK;
+  // it is printed like any result, and only the exit code says it failed —
+  // plus, on stderr, the skills the gateway says explain the tool.
+  if (typeof result?.error !== 'string') return EXIT_OK;
+  if (skills.length) io.warn(skillsPointer(skills));
+  return EXIT_FAILURE;
 }
 
 /**

package/src/commands/whoami.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { EXIT_OK } from '../exit.js';
+import { json } from './approval-wait.js';
+
+export const WHOAMI_USAGE = 'juno whoami';
+export const VERSION_USAGE = 'juno version';
+
+/** This CLI's own version, from the package it ships in. */
+const CLI_VERSION = JSON.parse(
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+
+/**
+ * `juno whoami`: GET /api/me — the principal the instance takes this CLI for
+ * (a key, a user behind the proxy, or local), its scope and the linked
+ * person. It is how an agent learns what its key may do before it tries.
+ */
+export async function whoami(args, io) {
+  if (args._.length) throw new UsageError(`usage: ${WHOAMI_USAGE}`);
+  const { client } = await connect(args, io);
+  await json(io)(await client.rest('GET', '/api/me'));
+  return EXIT_OK;
+}
+
+/**
+ * `juno version`: GET /api/version, the instance's build and schema version,
+ * with this CLI's version beside it as `cli_version`.
+ */
+export async function version(args, io) {
+  if (args._.length) throw new UsageError(`usage: ${VERSION_USAGE}`);
+  const { client } = await connect(args, io);
+  const body = await client.rest('GET', '/api/version');
+  await json(io)({ ...body, cli_version: CLI_VERSION });
+  return EXIT_OK;
+}

package/src/exit.js

@@ -10,10 +10,13 @@
  *   3  the instance is unreachable (the fetch itself failed)
  *   4  a deploy conflict: a working-copy deploy or check (any kind) got a
  *      409 because the active version is not the copy's base_version
- *   5  `juno ask` / `session approve`: the turn is still running (pending)
+ *   5  `juno ask` / `session approve`: the turn is still running (pending);
+ *      a destructive command or `approval wait`: nobody has decided the
+ *      approval when --wait ran out
  *   6  `juno ask` / `session approve`: the assistant is awaiting input
+ * 130  Ctrl-C while waiting for an approval; the request stays open
  *
- * `juno job run` is the exception once its own arguments are accepted: it
+ * `juno task run` is the exception once its own arguments are accepted: it
  * exits with the wrapped command's status, as a shell would report it.
  */
 export const EXIT_OK = 0;
@@ -23,3 +26,4 @@ export const EXIT_UNREACHABLE = 3;
 export const EXIT_CONFLICT = 4;
 export const EXIT_PENDING = 5;
 export const EXIT_AWAITING_INPUT = 6;
+export const EXIT_INTERRUPTED = 130;