@mutagent/cli 0.2.214 → 0.2.216

package/README.md

@@ -85,8 +85,8 @@ To run Helix on your own machine instead, install the Helix binary with `mutagen
   belong here.
 - **Helix session**: a cloud run of Helix, addressed by a reference (`hs1_...`) that is printed
   when the run starts. `mutagent helix session` lists sessions, attaches to them, sends input,
-  stops, checkpoints and restores them. A sandbox idle for 15 minutes is stopped, and an
-  interactive session in it is checkpointed first.
+  answers their questions, stops, checkpoints and restores them. A sandbox idle for 15 minutes is
+  stopped, and an interactive session in it is checkpointed first.
 - **Managed agent**: a folder whose entry file is `agent.md` (YAML frontmatter, then the standing
   prompt). `mutagent agent deploy` stores each change as a new revision. A slot is the agent in one
   Environment (`--env`).
@@ -201,6 +201,8 @@ mutagent helix session list
 mutagent helix session attach <reference>              # Watch it (--since <n> replays)
 mutagent helix session send <reference> "and now the tests"
 mutagent helix session send <reference> --type steer "stop and re-read the spec"
+mutagent helix session approvals <reference>           # What it is waiting on (a question it asked)
+mutagent helix session answer <reference> <id> --value 'an option'   # Answer it (--cancel denies)
 mutagent helix session signal <reference> --force      # Stop it; the sandbox stays up
 mutagent helix session close-input <reference>
 mutagent helix session checkpoint <reference>

package/dist/bin/cli.js

@@ -28750,6 +28750,16 @@ async function restoreSession(routes, reference, body) {
 async function endSession(routes, reference) {
   return onRoute(routes, (base) => requestJson(referencePath(base, reference) + "/end", { method: "POST", body: "{}" }));
 }
+async function listSessionApprovals(routes, reference, signal) {
+  return onRoute(routes, (base) => requestJson(referencePath(base, reference) + "/approvals", { signal }));
+}
+async function answerSessionApproval(routes, reference, id, answer, signal) {
+  await onRoute(routes, (base) => requestJson(`${referencePath(base, reference)}/approvals/${encodeURIComponent(id)}`, {
+    method: "POST",
+    body: JSON.stringify({ decision: answer.decision, ...answer.value === undefined ? {} : { value: answer.value } }),
+    signal
+  }));
+}
 async function onSessionRoute(routes, call) {
   return onRoute(routes, (base) => call(base));
 }
@@ -28762,6 +28772,215 @@ init_errors();
 import { createInterface as createInterface2 } from "node:readline";
 init_known_secrets();
 
+// src/lib/session-questions.ts
+var QUESTION_KINDS = ["select", "confirm", "input", "editor"];
+var isQuestionKind = (method) => typeof method === "string" && QUESTION_KINDS.includes(method);
+var str = (value) => typeof value === "string" ? value : null;
+function questionOfFrame(frameText) {
+  let frame;
+  try {
+    frame = JSON.parse(frameText);
+  } catch {
+    return null;
+  }
+  if (frame === null || typeof frame !== "object" || Array.isArray(frame))
+    return null;
+  const record = frame;
+  if (record.type !== "extension_ui_request")
+    return null;
+  const method = record.method;
+  if (!isQuestionKind(method))
+    return null;
+  const id = str(record.id);
+  if (id === null || id === "")
+    return null;
+  return {
+    id,
+    kind: method,
+    title: str(record.title) ?? "",
+    message: method === "confirm" ? str(record.message) : null,
+    options: method === "select" && Array.isArray(record.options) ? record.options.filter((option) => typeof option === "string") : null,
+    placeholder: method === "input" ? str(record.placeholder) : null
+  };
+}
+function shellQuote2(value) {
+  if (value !== "" && /^[A-Za-z0-9_@%+=:,./-]+$/.test(value))
+    return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function answerCommand(cli, reference, question) {
+  if (question.kind === "confirm")
+    return `${cli} session answer ${reference} ${question.id}`;
+  const example = question.options !== null && question.options.length > 0 ? question.options[0] ?? "<text>" : "<text>";
+  return `${cli} session answer ${reference} ${question.id} --value ${shellQuote2(example)}`;
+}
+function cancelCommand(cli, reference, id) {
+  return `${cli} session answer ${reference} ${id} --cancel`;
+}
+function questionDetail(question) {
+  if (question.kind === "select") {
+    return question.options === null || question.options.length === 0 ? "" : `options: ${question.options.join(" | ")}`;
+  }
+  if (question.kind === "confirm")
+    return question.message === null ? "" : `message: ${question.message}`;
+  if (question.kind === "input")
+    return question.placeholder === null ? "" : `placeholder: ${question.placeholder}`;
+  return "";
+}
+function questionLines(question, cli, reference) {
+  const lines = [`The session asks (${question.kind}, id ${question.id}): ${question.title === "" ? "(no title)" : question.title}`];
+  if (question.kind === "select" && question.options !== null && question.options.length > 0) {
+    lines.push(`  Options: ${question.options.join(" | ")}`);
+  }
+  if (question.kind === "confirm" && question.message !== null && question.message !== "") {
+    lines.push(`  Message: ${question.message}`);
+  }
+  if (question.kind === "input" && question.placeholder !== null && question.placeholder !== "") {
+    lines.push(`  Placeholder: ${question.placeholder}`);
+  }
+  lines.push(`  Answer: ${answerCommand(cli, reference, question)}`);
+  lines.push(`  Deny:   ${cancelCommand(cli, reference, question.id)}`);
+  return lines;
+}
+function pendingQuestionLines(approvals, cli, reference) {
+  if (approvals.length === 0)
+    return [];
+  const count = `${String(approvals.length)} question${approvals.length === 1 ? "" : "s"}`;
+  return [
+    `The session is waiting on ${count} asked before this attach — answer from any terminal:`,
+    ...approvals.flatMap((approval) => questionLines(approval, cli, reference))
+  ];
+}
+var TURN_ENDS = new Set(["turn_end", "agent_end"]);
+function questionSignalOfFrame(frameText) {
+  const question = questionOfFrame(frameText);
+  if (question !== null)
+    return { type: "ask", question };
+  if (!/(?:extension_ui_response|turn_end|agent_end)/.test(frameText))
+    return null;
+  let frame;
+  try {
+    frame = JSON.parse(frameText);
+  } catch {
+    return null;
+  }
+  if (frame === null || typeof frame !== "object" || Array.isArray(frame))
+    return null;
+  const record = frame;
+  if (record.type === "extension_ui_response") {
+    const id = str(record.id);
+    return id === null ? null : { type: "answer", id };
+  }
+  return typeof record.type === "string" && TURN_ENDS.has(record.type) ? { type: "turn-end" } : null;
+}
+
+class SessionQuestions {
+  #notice;
+  #cli;
+  #reference;
+  #fetchOpen;
+  #known = false;
+  #started = new Set;
+  #open = new Set;
+  #closed = new Set;
+  #printed = new Set;
+  #waiting = [];
+  #inFlight = null;
+  constructor(options) {
+    this.#notice = options.notice;
+    this.#cli = options.cli;
+    this.#reference = options.reference;
+    this.#fetchOpen = options.fetchOpen;
+  }
+  async start() {
+    if (this.#fetchOpen === undefined)
+      return;
+    let open;
+    try {
+      open = await this.#fetchOpen();
+    } catch {
+      return;
+    }
+    this.#known = true;
+    for (const approval of open) {
+      this.#started.add(approval.id);
+      this.#open.add(approval.id);
+    }
+    for (const line of pendingQuestionLines(open, this.#cli, this.#reference))
+      this.#notice(line);
+  }
+  frame(frameText) {
+    const signal = questionSignalOfFrame(frameText);
+    if (signal === null)
+      return;
+    if (signal.type === "answer") {
+      this.#closed.add(signal.id);
+      this.#open.delete(signal.id);
+      return;
+    }
+    if (signal.type === "turn-end") {
+      for (const id of this.#open)
+        this.#closed.add(id);
+      for (const question of this.#waiting)
+        this.#closed.add(question.id);
+      this.#open.clear();
+      this.#waiting = [];
+      return;
+    }
+    const question = signal.question;
+    if (this.#printed.has(question.id) || this.#closed.has(question.id))
+      return;
+    if (this.#started.has(question.id)) {
+      this.#printed.add(question.id);
+      return;
+    }
+    if (this.#fetchOpen === undefined || !this.#known) {
+      this.#render(question);
+      return;
+    }
+    this.#waiting.push(question);
+    this.#inFlight ??= this.#verify();
+  }
+  async settle() {
+    while (this.#inFlight !== null)
+      await this.#inFlight;
+  }
+  async#verify() {
+    try {
+      const open = await this.#fetchOpen?.() ?? [];
+      const openIds = new Set(open.map((approval) => approval.id));
+      for (const question of this.#drain()) {
+        if (openIds.has(question.id))
+          this.#render(question);
+        else {
+          this.#closed.add(question.id);
+          this.#open.delete(question.id);
+        }
+      }
+    } catch {
+      for (const question of this.#drain())
+        this.#render(question);
+    } finally {
+      this.#inFlight = null;
+      if (this.#waiting.length > 0)
+        this.#inFlight = this.#verify();
+    }
+  }
+  #drain() {
+    const waiting = this.#waiting;
+    this.#waiting = [];
+    return waiting;
+  }
+  #render(question) {
+    if (this.#closed.has(question.id))
+      return;
+    this.#printed.add(question.id);
+    this.#open.add(question.id);
+    for (const line of questionLines(question, this.#cli, this.#reference))
+      this.#notice(line);
+  }
+}
+
 // src/lib/sse.ts
 var DEFAULT_EVENT_NAME = "message";
 
@@ -29303,9 +29522,22 @@ async function runNativeSession(options) {
     notice("Session " + options.reference + (options.interrupt === undefined ? ". Ctrl-C detaches." : ". Ctrl-C stops the session (SIGINT)."));
     if (options.interruptRequested)
       onSigint();
+    const questions = new SessionQuestions({
+      notice,
+      cli: activeProduct().cli,
+      reference: options.reference,
+      ...options.openQuestions === undefined ? {} : { fetchOpen: options.openQuestions }
+    });
+    let attached = false;
     const result = await runStreamSession({
       open: async (request) => {
         const stream = await options.open(request);
+        if (!attached) {
+          attached = true;
+          try {
+            await questions.start();
+          } catch {}
+        }
         if (options.rpc && !startedInput && !inputController.signal.aborted) {
           startedInput = true;
           inputTask = pump().catch((error) => {
@@ -29328,6 +29560,7 @@ async function runNativeSession(options) {
           stdout(text.endsWith(`
 `) ? text : text + `
 `);
+          questions.frame(text);
         },
         banner: (text) => {
           stdout(text.endsWith(`
@@ -29347,6 +29580,9 @@ async function runNativeSession(options) {
       signal: controller.signal
     });
     finished = true;
+    try {
+      await questions.settle();
+    } catch {}
     const woke = result.session;
     if (woke?.reference !== undefined && (woke.status === "woken" || woke.status === "exited")) {
       stderr("[mutagent] " + JSON.stringify({ event: "woken", reference: woke.reference }) + `
@@ -31042,6 +31278,12 @@ Send does not wait for the reply. The reply arrives on the session's stream as a
 'response' event carrying the command id (in --json output). Watch it with:
   ${chalk29.dim("$")} mutagent helix session attach <reference>
 
+Questions are not sent to, they are answered: when the session asks (its ask tool —
+a select, confirm, input or editor dialog), 'mutagent helix session approvals
+<reference>' lists what is open and 'mutagent helix session answer <reference> <id>
+--value <text>' (or --cancel) answers it. Attach prints the same command when the
+question appears.
+
 AI Agent Directive:
   --json returns ONE object: { success, reference, type, id, line, accepted,
   _links }. 'accepted' means delivered, not answered: the answer is a 'response'
@@ -31049,7 +31291,10 @@ AI Agent Directive:
   command does not wait for it. wake.state 'waking' means queued: the session is
   being restored and the message is not delivered yet; the stream reports the
   delivery, or the failed restore and the message it lost. Use --type and a message; use --line only for a
-  command the four types cannot express.
+  command the four types cannot express. A question the session asks is never
+  answered by send: poll 'mutagent helix session approvals <reference> --json'
+  and answer with 'mutagent helix session answer <reference> <id> --value <text>'
+  (or --cancel).
       `)).action(async (id, messageParts, options) => {
     const isJson = getJsonFlag(jsonSource);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -31285,8 +31530,10 @@ Examples:
   ${chalk31.dim("$")} mutagent helix session checkpoint <reference>
 
 A session reference (hs1_...) is printed when a run starts and listed by 'session list'.
-attach, send, signal, close-input, checkpoint, checkpoints and restore take it.
-checkpoint saves a session's conversation; restore continues it in a rebuilt sandbox.
+attach, send, signal, close-input, checkpoint, checkpoints, approvals, answer and
+restore take it. checkpoint saves a session's conversation; restore continues it in
+a rebuilt sandbox. approvals lists the questions the session is waiting on a human
+for, and answer answers one — a session that asked blocks until it is answered.
 A sandbox idle for 15 minutes is stopped; an interactive session in it is checkpointed first.
 A send to that session wakes it from its last checkpoint; restore is the manual option.
 
@@ -31294,7 +31541,7 @@ AI Agent Directive:
   Start a steerable session with mutagent helix --mode rpc (or -p for one-shot)
   and keep the session reference it prints; 'mutagent helix session list --json'
   lists references too. Use the reference for attach, send, signal, close-input,
-  checkpoint, checkpoints and restore; never guess one. Only an interactive
+  checkpoint, checkpoints, approvals, answer and restore; never guess one. Only an interactive
   (--mode rpc) session accepts send. restore starts a NEW session and returns its
   reference. A managed agent's session cannot be restored yet (409).
       `));
@@ -31303,6 +31550,8 @@ AI Agent Directive:
   registerSessionList(session, parent, p);
   registerSessionAttach(session, p);
   registerSendCommand(session, { jsonSource: parent, product: p });
+  registerApprovals(session, parent, p);
+  registerAnswer(session, parent, p);
   registerSignalCommand(session, { jsonSource: parent, product: p });
   registerCloseInput(session, parent, p);
   registerCheckpoint(session, parent, p);
@@ -31470,7 +31719,10 @@ function registerSessionAttach(session, p) {
     "  A dropped stream reconnects at its cursor for up to 5 minutes; if it gives up, it prints the seq to resume from.",
     "  A reference names one session; after a restore, take the new reference from session list.",
     '  When a send wakes the session, stderr carries [mutagent] {"event":"woken","reference":"hs1_..."}:',
-    "  this stream ends there; attach to that reference with --since 0."
+    "  this stream ends there; attach to that reference with --since 0.",
+    "  A question the session asks (its ask tool: a select, confirm, input or editor dialog)",
+    "  prints on stderr with the command that answers it; a question replayed from",
+    "  history that has since closed prints nothing. session approvals lists what is open."
   ].join(`
 `))).action(async (reference, options) => {
     try {
@@ -31482,13 +31734,110 @@ function registerSessionAttach(session, p) {
         check: () => checkSession(reference, findRow),
         ...since === undefined ? {} : { since },
         open: (request) => openSessionStream(p, reference, request),
-        send: (line, signal) => sendSessionInput(p, reference, line, signal)
+        send: (line, signal) => sendSessionInput(p, reference, line, signal),
+        openQuestions: async () => {
+          const { approvals } = await listSessionApprovals(p, reference, AbortSignal.timeout(1e4));
+          return Array.isArray(approvals) ? approvals : [];
+        }
       });
     } catch (error) {
       handleError(sessionGoneGuidance(error, "stream", reference), false);
     }
   });
 }
+function registerApprovals(session, root, p) {
+  const t = (text) => productText(text, p);
+  session.command("approvals").description(t("List the questions a Helix session is waiting on")).argument("<reference>", t("Session reference (hs1_...) from 'mutagent helix' or 'session list'")).addHelpText("after", t(`
+Examples:
+  ${chalk31.dim("$")} mutagent helix session approvals <reference>
+  ${chalk31.dim("$")} mutagent helix session approvals <reference> --json
+
+The questions the session asked and is waiting on a human to answer: a select
+(its options), a confirm (yes or no), an input or an editor (text). While any
+is open the session is needs-input and its turn waits; a question whose timeout
+passes is resolved by the sandbox itself. Each row's id is what an answer
+names — answer it with 'mutagent helix session answer'; attach prints the same
+commands the moment a question appears.
+
+AI Agent Directive:
+  --json returns { success, reference, approvals: [{ id, kind, title, message,
+  options, placeholder, requestedAt, expiresAt }], count, _links }. Poll it to
+  find a session blocked on a person; answer with 'mutagent helix session answer
+  <reference> <id> --value <text>' (or --cancel), never with session send.
+      `)).action(async (reference) => {
+    const isJson = getJsonFlag(root);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const { approvals } = await listSessionApprovals(p, reference);
+      const open = Array.isArray(approvals) ? approvals : [];
+      if (isJson) {
+        output.output({
+          reference,
+          approvals: open,
+          count: open.length,
+          _links: { api: sessionPath(p, reference) + "/approvals" }
+        });
+        return;
+      }
+      if (open.length === 0) {
+        output.info(t("No open questions: the session is not waiting on anyone."));
+        return;
+      }
+      output.output(open.map((approval) => ({
+        id: approval.id,
+        kind: approval.kind,
+        title: approval.title,
+        detail: questionDetail(approval),
+        asked: new Date(approval.requestedAt).toLocaleString()
+      })));
+    } catch (error) {
+      handleError(withoutSandboxIds(error), isJson);
+    }
+  });
+}
+function registerAnswer(session, root, p) {
+  const t = (text) => productText(text, p);
+  session.command("answer").description(t("Answer a question a Helix session is waiting on")).argument("<reference>", t("Session reference (hs1_...) from 'mutagent helix' or 'session list'")).argument("<id>", "The question id, from session approvals or an attach notice").option("--value <text>", "Approve with this answer (a select option, or the text)").option("--cancel", "Deny the question instead of approving it").addHelpText("after", t(`
+Examples:
+  ${chalk31.dim("$")} mutagent helix session answer <reference> q1 --value 'Deploy to production'
+  ${chalk31.dim("$")} mutagent helix session answer <reference> q2            # approve a confirm
+  ${chalk31.dim("$")} mutagent helix session answer <reference> q2 --cancel   # deny it
+
+Approve answers the question; --cancel denies it. A select takes one of its
+options as --value, an input or editor takes the text, and a confirm needs no
+value at all. The id comes from 'session approvals' or from the block attach
+prints when the question appears; answering from any terminal reaches the
+session, and the turn continues on its stream, not in this output.
+
+AI Agent Directive:
+  --json returns { success, reference, id, decision, value?, _links }. Delivery
+  is not the continuation: watch the session's stream for it. APPROVAL_NOT_FOUND
+  means another terminal answered it or its timeout passed — list what is still
+  open with 'mutagent helix session approvals <reference> --json'.
+      `)).action(async (reference, id, options) => {
+    const isJson = getJsonFlag(root);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      if (options.cancel === true && options.value !== undefined) {
+        throw new MutagentError("INVALID_ARGUMENTS", "--cancel denies the question, so --value would be discarded.", "Send --value to approve the question, or --cancel to deny it — one of the two.");
+      }
+      const answer = options.cancel === true ? { decision: "deny" } : options.value === undefined ? { decision: "approve" } : { decision: "approve", value: options.value };
+      await answerSessionApproval(p, reference, id, answer);
+      if (isJson) {
+        output.output({
+          reference,
+          id,
+          ...answer,
+          _links: { api: sessionPath(p, reference) + "/approvals/" + encodeURIComponent(id) }
+        });
+      } else {
+        output.success(`Answered ${id} (${answer.decision}${answer.value === undefined ? "" : `: ${answer.value}`}) on ${reference}; the session continues on its stream.`);
+      }
+    } catch (error) {
+      handleError(withoutSandboxIds(error), isJson);
+    }
+  });
+}
 function registerCheckpoint(session, root, p) {
   const t = (text) => productText(text, p);
   session.command("checkpoint").description("Save a session's conversation as a checkpoint").argument("<reference>", "Session reference (hs1_...)").addOption(new Option4("--session <id>", "The session id, when the argument is a sandbox id").hideHelp()).addHelpText("after", t(`
@@ -37807,7 +38156,7 @@ function readBody(value) {
 function isInteractive(isJson) {
   return !isJson && process.env.MUTAGENT_NON_INTERACTIVE !== "true" && process.env.CI !== "true" && process.stdin.isTTY && process.stdout.isTTY;
 }
-function shellQuote2(value) {
+function shellQuote3(value) {
   return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function rerunWithYes(options) {
@@ -37823,7 +38172,7 @@ function rerunWithYes(options) {
   ];
   for (const [flag, value] of flags) {
     if (value !== undefined)
-      parts.push(`--${flag}`, shellQuote2(value));
+      parts.push(`--${flag}`, shellQuote3(value));
   }
   parts.push("--yes", "--json");
   return parts.join(" ");
@@ -39206,21 +39555,21 @@ init_sandbox_scope_error();
 // src/commands/integrations/secret-required.ts
 init_output();
 import chalk66 from "chalk";
-function shellQuote3(value) {
+function shellQuote4(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function rerunCommand(body) {
-  const parts = [`${SOURCES3} add ${shellQuote3(String(body.kind))}`, `--name ${shellQuote3(String(body.name))}`];
+  const parts = [`${SOURCES3} add ${shellQuote4(String(body.kind))}`, `--name ${shellQuote4(String(body.name))}`];
   if (typeof body.host === "string")
-    parts.push(`--host ${shellQuote3(body.host)}`);
+    parts.push(`--host ${shellQuote4(body.host)}`);
   if (typeof body.org === "string")
-    parts.push(`--openobserve-org ${shellQuote3(body.org)}`);
+    parts.push(`--openobserve-org ${shellQuote4(body.org)}`);
   if (typeof body.stream === "string")
-    parts.push(`--stream ${shellQuote3(body.stream)}`);
+    parts.push(`--stream ${shellQuote4(body.stream)}`);
   if (typeof body.signal === "string")
-    parts.push(`--signal ${shellQuote3(body.signal)}`);
+    parts.push(`--signal ${shellQuote4(body.signal)}`);
   if (typeof body.dataset === "string")
-    parts.push(`--dataset ${shellQuote3(body.dataset)}`);
+    parts.push(`--dataset ${shellQuote4(body.dataset)}`);
   return parts.join(" ");
 }
 function printSecretRequired(isJson, detail, rerun) {
@@ -45170,4 +45519,4 @@ if (process.env.CLI_VERSION) {
 }
 runCli(process.argv.slice(2), cliVersion);
 
-//# debugId=C84BBF9AA9B7837764756E2164756E21
+//# debugId=3B06A5F83D41F6E764756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/cli",
-  "version": "0.2.214",
+  "version": "0.2.216",
   "description": "Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.7.2",
-    "@mutagent/sdk": "0.12.25",
+    "@mutagent/sdk": "0.12.27",
     "@sinclair/typebox": "^0.34.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -94,5 +94,5 @@
   "bugs": {
     "url": "https://docs.mutagent.io/support"
   },
-  "gitHead": "485011daa8fbf26044dfa5e3f412222292afe3a4"
+  "gitHead": "c32ceb2e6b9127d247bccee7447ee0c9acf0e007"
 }