@livx.cc/agentx 0.99.20 → 0.99.21

package/README.md

@@ -114,6 +114,7 @@ agentx --resume <id> "…"    # resume a specific session
 - **Project instructions** — `./AGENTS.md` (or `CLAUDE.md`) auto-loads into every run; `/init` scaffolds one.
 - **Any provider** — set `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `GROQ_API_KEY`; choose with `-m provider/model`. Env files load with precedence: CWD `.env` (bun) → install-dir `.env` → `~/.agent/.env` (user-wide). **Bodify secrets**: set `BODIFY_API_KEY` + `BODIFY_APP_ID` (e.g. in `~/.agent/.env`) to pull provider keys from a Bodify app at startup — no local key management needed.
 - **@-file mentions & headless JSON** — reference files inline in a prompt with `@path` (e.g. `explain @src/Agent.ts`; `~/` expands to the home directory; quote paths with spaces as `@"…"` — drag-dropped files, e.g. macOS screenshots, quote themselves automatically); script with `-p --output-format json` to get one machine-readable result object on stdout (activity stays on stderr).
+- **Raise, don't guess** (`AskUserQuestion` + `finishReason: 'needs_input'`) — when a decision is genuinely the user's, the agent asks. Interactively that's an arrow-select prompt. **Headless** (`-p`, piped, no TTY) there's nobody to prompt, so instead of blocking on a prompt no one can see — or, worse, "proceeding with best judgment" — the run **stops and hands the question to its caller**: exit code `2`, a yellow `? needs input` footer, and `{finishReason:'needs_input', question:{…}, sessionId}` in `--output-format json`. The transcript is preserved, so the caller answers and continues (`--resume <id> -p "<answer>"`) instead of re-running. A delegated agent silently deciding something that was never its to decide is the failure this closes.
 - **Tab-completion** — `Tab` completes `/<command>` names and `@<path>` file/dir references (descends subdirs, dotfiles hidden unless typed) straight from the working tree.
 - **Duplex mode** — `agentx --duplex` runs the full standard REPL (slash commands, sessions, postures, rewind, MCP) with the three-tier engine driving turns: a fast voice model (`--voice-model`, default `groq/openai/gpt-oss-120b`) answers every line instantly and delegates real work to background workers built with the same wiring as a normal run (fs mode, permissions, MCP); worker activity shows as dim chrome and results are re-voiced when ready. Switch any tier live with `/model` (opens a reflex/act/think picker), or the `/voice-model` · `/think-model` shortcuts. `/tasks` lists background tasks, inspects a task's live output tail, and cancels a running one from a picker (Esc mid-turn cancels the foreground turn; Esc again at the idle prompt cancels running workers).
 - **MCP servers** — declare `mcpServers: { name: { command, args } | { url } }` in config and they're auto-mounted at startup (in parallel, with an optional `mountTimeoutMs` deadline so one slow/dead server never blocks the rest): the client does the JSON-RPC handshake (stdio or HTTP) + `tools/list`, and the discovered tools appear as `mcp__<name>__<tool>` in `/tools` (inspect with `/mcp`). A bad server is logged and skipped, never blocking the agent. For large tool sets, **deferred mode** (`makeMcpToolSearch` / `mountMcpDeferred`) exposes just two bounded tools (`ToolSearch` + `McpCall`) instead of N defs — dodging the provider tool-cap and improving selection accuracy; the CLI applies this automatically past 12 mounted tools (a 42-tool server was costing ~80k tok/turn in schema alone), and permission rules written against the real `mcp__<name>__<tool>` names still match through `McpCall`. **`mountMcpCatalog`** goes further: a cached, hash-keyed catalog + lazy connect means a turn that uses no MCP tool opens **zero** connections, and one that uses a tool connects exactly that server — latency scales with tools-used, not servers-configured. A down server is **negative-cached** (`failureCooldownMs`) so it never re-floors a later turn at the deadline. For zero turn-path latency even on a cold process, call **`warmMcpCatalog`** at boot + on a timer (off-turn discovery) and mount with **`{ discover: 'cache-only' }`** — the turn then never synchronously connects: it serves the warmed catalog and discovers any miss in the background.

package/dist/{Agent-Cn9BxS8h.d.ts → Agent-CM7HL95r.d.ts}

@@ -1,5 +1,5 @@
 import { IFilesystem } from '@livx.cc/wcli/core';
-import { M as Message, H as HostBridge, A as AgentTool, C as ChatLike, e as MessageContent } from './tools-DKf3hN4M.js';
+import { M as Message, H as HostBridge, A as AgentTool, C as ChatLike, e as MessageContent, U as UserQuestion } from './tools-ClgFZjUr.js';
 
 /**
  * Hooks — deterministic interception points around tool execution, run by the
@@ -180,9 +180,14 @@ declare function reasoningToChatFragment(model: string, effort?: ReasoningEffort
 interface RunResult {
     text: string;
     steps: number;
-    /** Why the loop ended. The middle group are automatic kill-switches (budget/abuse guards). */
-    finishReason: 'stop' | 'max_steps' | 'budget' | 'timeout' | 'loop' | 'max_tool_calls' | 'aborted' | 'error';
+    /** Why the loop ended. The middle group are automatic kill-switches (budget/abuse guards).
+     *  `needs_input` is NOT a failure: the agent hit a decision that was the user's to make with no
+     *  human reachable, so it stopped and raised the question (see `question`) instead of guessing.
+     *  Answer it and resume the session to continue. */
+    finishReason: 'stop' | 'max_steps' | 'budget' | 'timeout' | 'loop' | 'max_tool_calls' | 'aborted' | 'error' | 'needs_input';
     messages: Message[];
+    /** The parked question — present iff `finishReason === 'needs_input'`. */
+    question?: UserQuestion;
     /** Accumulated token usage across all turns (non-stream path). With prompt caching,
      *  promptTokens includes cached reads/writes; the cache splits ride along for exact pricing. */
     usage?: {

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { H as Hooks, h as RunResult, R as ReasoningEffort, A as Agent } from './Agent-Cn9BxS8h.js';
+import { H as Hooks, h as RunResult, R as ReasoningEffort, A as Agent } from './Agent-CM7HL95r.js';
 import { IFilesystem } from '@livx.cc/wcli/core';
-import { M as Message, H as HostBridge, c as ContentPart, e as MessageContent } from './tools-DKf3hN4M.js';
+import { M as Message, U as UserQuestion, H as HostBridge, c as ContentPart, e as MessageContent } from './tools-ClgFZjUr.js';
 
 /**
  * On-disk session store for the CLI: each conversation is one JSON file at
@@ -236,7 +236,8 @@ interface PermMode {
  * Default permission posture — CC-inspired: **ask when a human can answer, allow when unattended.**
  * Pure + exported so the decision is unit-testable without a TTY. Precedence:
  *   --yes  → allow (explicit trust, no prompts)
- *   --ask  → ask   (explicit gate, even headless)
+ *   --ask  → ask   (explicit gate; parseArgs rejects it up front when no terminal is attached,
+ *                   so this branch always has a human behind it)
  *   interactive (TTY & not json) → ask  (the safe default)
  *   else (headless/piped) → allow, with a one-line notice so it's never silent.
  */
@@ -271,8 +272,9 @@ declare function expandMentions(fs: IFilesystem, line: string): Promise<{
 /** The headless `--output-format json` result object for a turn. */
 declare function jsonResult(res: RunResult, session: SessionData): {
     error?: any;
+    question?: UserQuestion | undefined;
     ok: boolean;
-    finishReason: "error" | "budget" | "stop" | "max_steps" | "timeout" | "loop" | "max_tool_calls" | "aborted";
+    finishReason: "error" | "budget" | "stop" | "max_steps" | "timeout" | "loop" | "max_tool_calls" | "aborted" | "needs_input";
     text: string;
     steps: number;
     tools: number;

package/dist/cli.js

@@ -2152,7 +2152,7 @@ ${out.replace(/\n+$/, "") || "(no output yet)"}`;
 // src/host.ts
 var askUserQuestionTool = {
   name: "AskUserQuestion",
-  description: "Ask the user a multiple-choice question when a decision is genuinely theirs to make (ambiguous requirement, a fork you cannot resolve from context). Returns their selection.",
+  description: 'Ask the user a multiple-choice question when a decision is genuinely theirs to make: an ambiguous or under-specified requirement, a fork you cannot resolve from context, a premise of the task that the evidence contradicts, or a risky/irreversible next step. Prefer this over guessing, "proceeding with best judgment", or quietly widening scope to make an unclear brief fit \u2014 a wrong silent decision is far more costly than a question. Returns their selection if a human is reachable; otherwise the run pauses and the question is handed to whoever delegated the task (you do not need to know which \u2014 just ask).',
   parameters: {
     type: "object",
     required: ["question", "options"],
@@ -2168,8 +2168,8 @@ var askUserQuestionTool = {
   },
   async run(args, ctx) {
     if (!ctx.host?.ask) {
-      const fallback = args.options?.[0]?.label ?? "";
-      return `No interactive user is available \u2014 proceed using your best judgment.${fallback ? ` (Closest default: "${fallback}")` : ""}`;
+      ctx.needsInput = args;
+      return "PAUSED \u2014 no interactive user is reachable from this run, so your question has been raised to the caller that delegated this task. The run stops here; do not guess and do not continue. Their answer will arrive as the next user message when the run resumes.";
     }
     const answer = ctx.host.ask(args);
     return ctx.parkHuman ? ctx.parkHuman(answer) : answer;
@@ -3617,6 +3617,7 @@ var Agent = class _Agent {
     let usageEstimated = false;
     const start = Date.now();
     this.parkedMs = 0;
+    this.ctx.needsInput = void 0;
     let toolCallsTotal = 0;
     let lastFp = "";
     let repeats = 0;
@@ -3750,6 +3751,17 @@ var Agent = class _Agent {
         }
         this.transcript.push({ role: "tool", tool_call_id: tc.id, name: tc.function.name, content });
       }
+      if (this.ctx.needsInput) {
+        const question = this.ctx.needsInput;
+        this.ctx.needsInput = void 0;
+        log4.warn(`needs_input: ${question.question} (steps=${steps})`);
+        await this.ctx.jobs?.drain();
+        const text = [
+          `OPEN QUESTION (run paused \u2014 no human was reachable): ${question.question}`,
+          ...question.options.map((o2) => `  \u2022 ${o2.label}${o2.description ? ` \u2014 ${o2.description}` : ""}`)
+        ].join("\n");
+        return { text, steps, finishReason: "needs_input", messages: this.transcript, usage, usageEstimated, question };
+      }
       this.drainInjections();
     }
   }
@@ -12070,6 +12082,8 @@ function parseArgs(argv) {
   if (a.duplex && a.plan) throw new Error("--plan is not supported in --duplex (workers are non-interactive; a plan could never be approved)");
   if (a.voiceModel && !a.duplex) throw new Error("--voice-model only applies with --duplex");
   if (a.thinkModel !== void 0 && !a.duplex) throw new Error("--think-model/--no-think only apply with --duplex");
+  if (!canPrompt && (a.ask || a.plan))
+    throw new Error(`${a.ask ? "--ask" : "--plan"} needs an interactive terminal to approve on \u2014 none is attached (stdin/stderr are not a TTY). For an unattended run use --yes, or pre-authorize with rules in .agent/permissions.json.`);
   return a;
 }
 var HELP = `agentx \u2014 agent runtime CLI
@@ -12097,7 +12111,8 @@ Flags:
   --harden             OS-sandbox the real shell (sandbox-exec/bwrap): writes confined to cwd+tmp,
                        outbound network blocked; --harden-net keeps network allowed
   --plan               plan mode: edits blocked until you approve a plan
-  --ask                confirm each mutating tool (bash/Shell/Write/Edit/\u2026)
+  --ask                confirm each mutating tool (bash/Shell/Write/Edit/\u2026) \u2014 needs a terminal to
+                       approve on; rejected up front when detached (use --yes / permissions rules)
   --yes, -y            auto-approve mutating tools (no prompts) \u2014 for trusted/unattended runs
   --update             check for updates and install if available (no keys needed)
   --no-update-check    skip the automatic update check on startup
@@ -12129,6 +12144,10 @@ Flags:
 
 Prompts may reference files with @path (e.g. "explain @src/Agent.ts") \u2014 they're inlined.
 
+Exit codes (-p): 0 = done \xB7 1 = failed \xB7 2 = needs input \u2014 the agent hit a decision that was yours
+to make and paused rather than guess. The question is on stderr (and in --output-format json under
+"question"); answer it with: agentx --resume <sessionId> -p "<your answer>".
+
 Providers: set any of ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY / GROQ_API_KEY.
 Env files: .env (CWD, bun auto-loads) > install-dir .env > ~/.agent/.env (user-wide).
 Bodify secrets: set BODIFY_API_KEY + BODIFY_APP_ID (in ~/.agent/.env) to pull keys from a Bodify app.
@@ -12330,21 +12349,28 @@ function makeHost(format = "text", opts) {
         io.close();
       }
     },
-    async ask(q2) {
-      const title = `? ${q2.header ? "[" + q2.header + "] " : ""}${q2.question}`;
-      const v = await selectMenu(process.stderr, { title, items: q2.options.map((o) => ({ label: o.label, value: o.label, desc: o.description })) });
-      if (v !== null) return v;
-      const io = createInterface({ input: keyInput, output: process.stderr });
-      try {
-        const lines = [yellow("  " + title)];
-        q2.options.forEach((o, i) => lines.push(`     ${i + 1}) ${o.label}${o.description ? dim(" \u2014 " + o.description) : ""}`));
-        const ans = (await io.question(lines.join("\n") + "\n  > ")).trim();
-        const n = Number(ans);
-        return Number.isInteger(n) && q2.options[n - 1] ? q2.options[n - 1].label : ans;
-      } finally {
-        io.close();
+    // Only offer `ask` when a human can actually SEE the prompt. Headless/piped (`-p`, redirected,
+    // no TTY) → omit it: AskUserQuestion then parks the question and ends the run with
+    // `needs_input`, handing it to the caller. Prompting into a void instead blocks forever —
+    // parkHuman excludes the wait from --timeout, so only an external timeout ever reaps it, and
+    // the whole turn is lost. A question nobody can answer must travel UP, not stall.
+    ...canPrompt ? {
+      async ask(q2) {
+        const title = `? ${q2.header ? "[" + q2.header + "] " : ""}${q2.question}`;
+        const v = await selectMenu(process.stderr, { title, items: q2.options.map((o) => ({ label: o.label, value: o.label, desc: o.description })) });
+        if (v !== null) return v;
+        const io = createInterface({ input: keyInput, output: process.stderr });
+        try {
+          const lines = [yellow("  " + title)];
+          q2.options.forEach((o, i) => lines.push(`     ${i + 1}) ${o.label}${o.description ? dim(" \u2014 " + o.description) : ""}`));
+          const ans = (await io.question(lines.join("\n") + "\n  > ")).trim();
+          const n = Number(ans);
+          return Number.isInteger(n) && q2.options[n - 1] ? q2.options[n - 1].label : ans;
+        } finally {
+          io.close();
+        }
       }
-    }
+    } : {}
   };
 }
 function summarizeResult(name, text) {
@@ -12707,6 +12733,11 @@ function resolvePermMode(args, interactiveCapable) {
 }
 function makeAskResolver(cwd) {
   return async (call) => {
+    if (!canPrompt) {
+      err(dim(`  \u26A0 ${call.name} needs approval but no terminal is attached \u2014 denied. Use --yes, or an allow rule in .agent/permissions.json.
+`));
+      return { decision: "deny" };
+    }
     const name = call.name === "McpCall" && typeof call.args?.name === "string" ? String(call.args.name) : call.name;
     const tgt = call.args?.path ? ` on ${call.args.path}` : call.args?.command ? `: ${String(call.args.command).slice(0, 60)}` : "";
     const interactive = !!(process.stderr.isTTY && process.stdin.isTTY);
@@ -12937,6 +12968,8 @@ function jsonResult(res, session) {
     tools: res.messages.slice(lastUser).filter((m) => m.role === "tool").length,
     usage: res.usage,
     sessionId: session.meta.id,
+    // The parked question, machine-readable — the caller answers it and resumes `sessionId`.
+    ...res.finishReason === "needs_input" && res.question ? { question: res.question } : {},
     ...res.finishReason === "error" && res.error ? { error: res.error?.message ?? String(res.error) } : {}
   };
 }
@@ -13024,7 +13057,7 @@ async function runTurn(agent, store, session, task, cp, cwd = process.cwd(), sen
   const didWork = agent.transcript.slice(msgsBefore).some((m2) => m2.role === "assistant" || m2.role === "tool");
   const silentAbort = res.finishReason === "aborted" && !res.usage?.totalTokens && !didWork;
   if (!silentAbort)
-    err("\n" + (process.stderr.isTTY ? "\r\x1B[0J" : "") + (ok ? green("  \u2713 done") : red(`  \u2717 ${res.finishReason}`)) + dim(` \xB7 ${res.steps} steps \xB7 ${tools} tools \xB7 ${tok}${secs}s \xB7 ${shortId}
+    err("\n" + (process.stderr.isTTY ? "\r\x1B[0J" : "") + (ok ? green("  \u2713 done") : res.finishReason === "needs_input" ? yellow("  ? needs input") : red(`  \u2717 ${res.finishReason}`)) + dim(` \xB7 ${res.steps} steps \xB7 ${tools} tools \xB7 ${tok}${secs}s \xB7 ${shortId}
 `));
   if (!silentAbort && process.stderr.isTTY && Date.now() - t0 > 1e4) err("\x07");
   if (res.finishReason === "error" && res.error) {
@@ -15480,7 +15513,7 @@ async function main() {
     const session = startSession(args, store, agent, cwd);
     process.once("SIGINT", () => activeTurn?.abort());
     const { ok, res } = await runTurn(agent, store, session, args.task, void 0, cwd);
-    if (cfg.reflectOnFailure && !ok && res && agent.options.memoryDir) {
+    if (cfg.reflectOnFailure && !ok && res?.finishReason !== "needs_input" && res && agent.options.memoryDir) {
       const _fsBase = agent.options.fs.getCwd() === "/" ? "" : agent.options.fs.getCwd();
       const slug2 = await reflectOnRun({ ai, model: agent.options.model, fs: agent.options.fs, dir: primaryMemDir(agent.options.memoryDir, `${_fsBase}/.agent/memory`), result: res });
       if (slug2) err(dim(`  \u270E learned a lesson \u2192 ${slug2}
@@ -15492,7 +15525,7 @@ async function main() {
       process.stdout.write(JSON.stringify(args.outputFormat === "stream-json" ? { type: "result", ...obj } : obj) + "\n");
     }
     worktreeCleanup?.();
-    process.exit(ok ? 0 : 1);
+    process.exit(ok ? 0 : res?.finishReason === "needs_input" ? 2 : 1);
   }
   await repl(args, ai, cfg, cwd);
   worktreeCleanup?.();