nuabase 3.0.1 → 3.1.1

package/dist/cjs/local-agent.cjs

@@ -65,6 +65,9 @@ const SYSTEM_PROMPT$1 = [
 const claudeCodeAdapter = {
   id: "claude-code",
   binaryName: "claude",
+  // Prints as it works (stream-json with --include-partial-messages; see
+  // buildInvocation), so a long silence means it is stuck.
+  idleTimeoutMs: 12e4,
   apiKeyEnvVars: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
   modelAliases: { haiku: "haiku", sonnet: "sonnet", opus: "opus" },
   // Claude Code accepts any JSON Schema with an object root.
@@ -75,7 +78,13 @@ const claudeCodeAdapter = {
     const args = [
       "-p",
       "--output-format",
-      "json",
+      "stream-json",
+      // Required: with -p, stream-json is refused without --verbose.
+      "--verbose",
+      // Prints the reply in pieces as it is generated, not each message once it is done.
+      // Without it a long, healthy reply is silent until it ends, and
+      // idleTimeoutMs stops it.
+      "--include-partial-messages",
       "--tools",
       "",
       "--setting-sources",
@@ -97,10 +106,8 @@ const claudeCodeAdapter = {
     return { args, stdin: request.prompt };
   },
   readResult(result, request) {
-    let json;
-    try {
-      json = JSON.parse(result.stdout);
-    } catch {
+    const json = lastResultLine(result.stdout);
+    if (!json) {
       return {
         kind: "failed",
         failure: classifyAgentFailure(
@@ -180,12 +187,28 @@ const claudeCodeAdapter = {
     ];
   }
 };
+function lastResultLine(stdout) {
+  const lines = stdout.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line.startsWith("{")) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed?.type === "result") return parsed;
+    } catch {
+    }
+  }
+  return void 0;
+}
 
 const SCHEMA_FILE = "output-schema.json";
 const LAST_MESSAGE_FILE = "last-message.txt";
+const DISABLED_FEATURES = ["shell_tool", "unified_exec", "apps", "plugins", "view_image"];
 const codexAdapter = {
   id: "codex",
   binaryName: "codex",
+  // Prints nothing while it reasons, so silence says nothing about whether it is stuck.
+  idleTimeoutMs: null,
   apiKeyEnvVars: ["OPENAI_API_KEY", "CODEX_API_KEY"],
   // Codex's models have no equivalent among the aliases; set one with localAgent({ model }).
   modelAliases: {},
@@ -203,6 +226,9 @@ const codexAdapter = {
       "--ignore-rules",
       "--sandbox",
       "read-only",
+      ...DISABLED_FEATURES.flatMap((feature) => ["--disable", feature]),
+      "-c",
+      "web_search=disabled",
       "--json",
       "-o",
       LAST_MESSAGE_FILE
@@ -316,6 +342,8 @@ const SYSTEM_PROMPT = [
 const piAdapter = {
   id: "pi",
   binaryName: "pi",
+  // Streams as it works (--mode json), so a long silence means it is stuck.
+  idleTimeoutMs: 12e4,
   // Every environment credential Pi's providers recognize. Under `auth:
   // "subscription"` these are removed so Pi bills its own `auth.json` login.
   apiKeyEnvVars: [
@@ -511,31 +539,58 @@ function spawnAndCollect(options, cwd) {
       stdio: ["pipe", "pipe", "pipe"],
       windowsHide: true
     });
+    const startedAt = Date.now();
     const stdout = [];
     const stderr = [];
-    let timedOut = false;
+    let stopped = null;
+    let lastOutputAtMs = null;
     let killTimer;
-    const timeoutTimer = setTimeout(() => {
-      timedOut = true;
+    let idleTimer;
+    const stop = (cause) => {
+      if (stopped) return;
+      stopped = { ...cause, afterMs: Date.now() - startedAt, lastOutputAtMs };
+      clearTimers();
       child.kill("SIGINT");
       killTimer = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
-    }, options.timeoutMs);
-    child.stdout.on("data", (chunk) => stdout.push(chunk));
-    child.stderr.on("data", (chunk) => stderr.push(chunk));
-    child.on("error", (error) => {
+    };
+    const resetIdleTimer = () => {
+      const idleTimeoutMs = options.idleTimeoutMs;
+      if (idleTimeoutMs === null || stopped) return;
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => stop({ by: "idle", limitMs: idleTimeoutMs }), idleTimeoutMs);
+    };
+    const timeoutTimer = setTimeout(() => stop({ by: "total", limitMs: options.timeoutMs }), options.timeoutMs);
+    resetIdleTimer();
+    const onAbort = () => stop({ by: "signal" });
+    const clearTimers = () => {
       clearTimeout(timeoutTimer);
+      clearTimeout(idleTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted) onAbort();
+    const collect = (stream, chunks) => (chunk) => {
+      chunks.push(chunk);
+      lastOutputAtMs = Date.now() - startedAt;
+      resetIdleTimer();
+      options.onOutput?.(chunk, stream);
+    };
+    child.stdout.setEncoding("utf8").on("data", collect("stdout", stdout));
+    child.stderr.setEncoding("utf8").on("data", collect("stderr", stderr));
+    child.on("error", (error) => {
+      clearTimers();
       clearTimeout(killTimer);
       const reason = error.code === "ENOENT" ? "not found" : error.message;
       reject(new Error(`Could not start ${options.binaryPath}: ${reason}`));
     });
     child.on("close", (exitCode) => {
-      clearTimeout(timeoutTimer);
+      clearTimers();
       clearTimeout(killTimer);
       resolve({
         exitCode,
-        stdout: Buffer.concat(stdout).toString("utf8"),
-        stderr: Buffer.concat(stderr).toString("utf8"),
-        timedOut,
+        stdout: stdout.join(""),
+        stderr: stderr.join(""),
+        stopped,
         outputFiles: {}
       });
     });
@@ -581,12 +636,14 @@ async function detectAgent(adapter, binaryPathOverride) {
       runInvocation({
         binaryPath,
         invocation: { args: ["--version"], stdin: "" },
-        timeoutMs: STATUS_TIMEOUT_MS
+        timeoutMs: STATUS_TIMEOUT_MS,
+        idleTimeoutMs: null
       }),
       runInvocation({
         binaryPath,
         invocation: { args: adapter.loginStatusArgs, stdin: "" },
         timeoutMs: STATUS_TIMEOUT_MS,
+        idleTimeoutMs: null,
         // Report the CLI's own login, not an API key that happens to be set.
         unsetEnv: adapter.apiKeyEnvVars
       })
@@ -626,12 +683,17 @@ class LocalAgentEngine {
   nativeSchema(envelopeSchema) {
     return this.runner.adapter.nativeSchema(envelopeSchema);
   }
-  attempt(request) {
-    return this.runner.limiter.run(() => this.runAgent(request));
+  async attempt(request, controls = {}) {
+    try {
+      return await this.runner.limiter.run(() => this.runAgent(request, controls), controls.signal);
+    } catch (error) {
+      if (controls.signal?.aborted) return CANCELLED;
+      throw error;
+    }
   }
-  async runAgent(request) {
+  async runAgent(request, { onOutput, signal }) {
     const { adapter, binaryPath, logger, unsetEnv } = this.runner;
-    const { model, effort, timeoutMs } = this.call;
+    const { model, effort, timeoutMs, idleTimeoutMs } = this.call;
     const spanId = strictJsonSchema.generateSpanId();
     const startTime = Date.now();
     const method = request.enforcement.kind;
@@ -653,13 +715,20 @@ class LocalAgentEngine {
         binaryPath,
         invocation: adapter.buildInvocation(request, { model, effort }),
         timeoutMs,
+        idleTimeoutMs,
+        onOutput: onOutput && guardListener(onOutput, logger, spanId),
+        signal,
         unsetEnv
       });
     } catch (error) {
       return failed({ kind: "fatal", message: error instanceof Error ? error.message : String(error) });
     }
-    if (result.timedOut) {
-      return failed({ kind: "fatal", message: `did not finish within ${timeoutMs}ms` });
+    if (result.stopped?.by === "signal") {
+      logger.info("LLM call cancelled", { span_id: spanId, duration_ms: Date.now() - startTime });
+      return CANCELLED;
+    }
+    if (result.stopped) {
+      return failed({ kind: "fatal", message: stopMessage(result.stopped, result) });
     }
     const reply = adapter.readResult(result, request);
     if (reply.kind === "failed") {
@@ -687,29 +756,73 @@ class LocalAgentEngine {
     };
   }
 }
+const CANCELLED = {
+  kind: "failed",
+  failure: { kind: "cancelled", message: "The call was cancelled." }
+};
+function guardListener(onOutput, logger, spanId) {
+  let failed = false;
+  return (chunk, stream) => {
+    try {
+      onOutput(chunk, stream);
+    } catch (error) {
+      if (failed) return;
+      failed = true;
+      logger.warn("The onOutput listener threw; the agent runs on", {
+        span_id: spanId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  };
+}
+function stopMessage(stopped, result) {
+  const ran = `was stopped after ${seconds(stopped.afterMs)}`;
+  const chars = result.stdout.length + result.stderr.length;
+  let reason;
+  if (stopped.by === "idle") {
+    const before = stopped.lastOutputAtMs === null ? "It had printed nothing." : `It had printed ${chars} characters before that.`;
+    reason = `${ran}: it printed nothing for ${seconds(stopped.limitMs)} (idleTimeoutMs ${stopped.limitMs}). ${before} Raise idleTimeoutMs, or set it to null for no limit.`;
+  } else {
+    const before = stopped.lastOutputAtMs === null ? "It had printed nothing." : `It had printed ${chars} characters, the last ${seconds(stopped.afterMs - stopped.lastOutputAtMs)} before it was stopped.`;
+    reason = `${ran}, its limit (timeoutMs ${stopped.limitMs}). ${before} Raise timeoutMs.`;
+  }
+  const stderr = stderrTail(result, 500);
+  return stderr ? `${reason} Its stderr ended: ${stderr}` : reason;
+}
+function seconds(ms) {
+  return ms < 1e4 ? `${(ms / 1e3).toFixed(1)} s` : `${Math.round(ms / 1e3)} s`;
+}
 
+const DEFAULT_TIMEOUT_MS = 6e5;
+const MAX_LIMIT_MS = 2 ** 31 - 1;
 class LocalAgent {
-  constructor(runner, call) {
+  constructor(runner, options) {
     this.runner = runner;
-    this.call = call;
     this.agent = runner.adapter.id;
     this.logger = runner.logger;
+    this.call = {
+      model: options.model,
+      effort: options.effort,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      idleTimeoutMs: options.idleTimeoutMs === void 0 ? runner.adapter.idleTimeoutMs : options.idleTimeoutMs
+    };
+    if (this.call.model !== void 0 && this.call.model.trim() === "") {
+      throw new TypeError("model must be a non-empty string, or undefined for the agent's default model");
+    }
+    if (!isLimit(this.call.timeoutMs)) {
+      throw new TypeError(`timeoutMs must be from 1 to ${MAX_LIMIT_MS} milliseconds`);
+    }
+    if (this.call.idleTimeoutMs !== null && !isLimit(this.call.idleTimeoutMs)) {
+      throw new TypeError(`idleTimeoutMs must be from 1 to ${MAX_LIMIT_MS} milliseconds, or null for no limit`);
+    }
   }
   /**
    * The same agent with other call options, sharing this one's executable,
    * environment, logger and limit on processes running at once. Options left
-   * out keep this agent's; a model or effort given as undefined is the CLI's
-   * default.
+   * out keep this agent's; an option given as undefined takes its default.
    */
   with(options) {
-    if (options.model !== void 0 && options.model.trim() === "") {
-      throw new TypeError("model must be a non-empty string; pass undefined to use the agent's default model");
-    }
-    return new LocalAgent(this.runner, {
-      ...this.call,
-      ...options,
-      timeoutMs: options.timeoutMs ?? this.call.timeoutMs
-    });
+    return new LocalAgent(this.runner, { ...this.call, ...options });
   }
   /**
    * No model choice runs the default model. An alias runs the CLI's equivalent
@@ -735,6 +848,9 @@ class LocalAgent {
     return { kind: "routed", engine: new LocalAgentEngine(this.runner, call) };
   }
 }
+function isLimit(ms) {
+  return ms >= 1 && ms <= MAX_LIMIT_MS;
+}
 
 class Semaphore {
   constructor(limit) {
@@ -742,9 +858,11 @@ class Semaphore {
     this.active = 0;
     this.waiting = [];
   }
-  async run(task) {
+  /** Rejects with the signal's reason, without running `task`, when `signal` aborts while it waits. */
+  async run(task, signal) {
+    signal?.throwIfAborted();
     if (this.active >= this.limit) {
-      await new Promise((resolve) => this.waiting.push(resolve));
+      await this.waitForTurn(signal);
     } else {
       this.active++;
     }
@@ -759,71 +877,131 @@ class Semaphore {
       }
     }
   }
+  /** Resolves once a finishing task hands over its place. */
+  waitForTurn(signal) {
+    return new Promise((resolve, reject) => {
+      const take = () => {
+        signal?.removeEventListener("abort", leave);
+        resolve();
+      };
+      const leave = () => {
+        this.waiting.splice(this.waiting.indexOf(take), 1);
+        reject(signal.reason);
+      };
+      this.waiting.push(take);
+      signal?.addEventListener("abort", leave, { once: true });
+    });
+  }
 }
 
-const DEFAULT_TIMEOUT_MS = 18e4;
 const DEFAULT_CONCURRENCY = 2;
 function localAgent(config) {
   if (!isLocalAgentId(config.agent)) {
     throw new TypeError(`Unknown local agent: ${String(config.agent)}`);
   }
-  const settings = parseOptions(config);
   const adapter = AGENT_ADAPTERS[config.agent];
   const binaryPath = config.binaryPath ?? findOnPath(adapter.binaryName);
   if (!binaryPath) {
     throw new Error(`${adapter.binaryName} was not found on PATH. Install ${config.agent} or set binaryPath.`);
   }
-  return setUpLocalAgent(adapter, binaryPath, settings);
+  return setUpLocalAgent(adapter, binaryPath, config);
 }
 async function findLocalAgent(options = {}) {
-  const settings = parseOptions(options);
   const statuses = await detectLocalAgents();
   for (const status of statuses) {
     if (status.installed && status.loggedIn) {
-      return setUpLocalAgent(AGENT_ADAPTERS[status.agent], status.binaryPath, settings);
+      return setUpLocalAgent(AGENT_ADAPTERS[status.agent], status.binaryPath, options);
     }
   }
   const summary = statuses.map((s) => `${s.agent}: ${s.installed ? "not logged in" : "not installed"}`).join(", ");
   throw new Error(`No logged-in coding agent found (${summary})`);
 }
-function parseOptions(options) {
-  const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
-  if (!Number.isInteger(concurrency) || concurrency < 1) {
-    throw new TypeError("concurrency must be a positive integer");
-  }
-  if (options.model !== void 0 && options.model.trim() === "") {
-    throw new TypeError("model must be a non-empty string; omit it to use the agent's default model");
-  }
-  return {
-    model: options.model,
-    effort: options.effort,
-    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-    concurrency,
-    auth: options.auth ?? "subscription",
-    logger: options.logger ?? new strictJsonSchema.ConsoleLogger()
-  };
-}
-function setUpLocalAgent(adapter, binaryPath, settings) {
+function setUpLocalAgent(adapter, binaryPath, options) {
   if (/\.(cmd|bat)$/i.test(binaryPath)) {
     throw new Error(
       `${binaryPath} is a .cmd shim, which local agents cannot run safely. Set binaryPath to the agent's native executable.`
     );
   }
+  const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new TypeError("concurrency must be a positive integer");
+  }
   const runner = {
     adapter,
     binaryPath,
-    unsetEnv: settings.auth === "subscription" ? adapter.apiKeyEnvVars : [],
-    limiter: new Semaphore(settings.concurrency),
-    logger: settings.logger
+    unsetEnv: (options.auth ?? "subscription") === "subscription" ? adapter.apiKeyEnvVars : [],
+    limiter: new Semaphore(concurrency),
+    logger: options.logger ?? new strictJsonSchema.ConsoleLogger()
+  };
+  return new LocalAgent(runner, options);
+}
+
+const AGENTS = {
+  "claude-code": {
+    name: "Claude Code",
+    worksWith: "Claude Pro or Max, or an Anthropic Console account",
+    install: {
+      macos: "brew install --cask claude-code",
+      linux: "curl -fsSL https://claude.ai/install.sh | bash",
+      other: "npm install -g @anthropic-ai/claude-code"
+    },
+    signIn: "Run `claude`",
+    docsUrl: "https://code.claude.com/docs/en/setup"
+  },
+  codex: {
+    name: "Codex",
+    worksWith: "ChatGPT Plus, Pro or Business, or an OpenAI API key",
+    install: {
+      macos: "brew install --cask codex",
+      linux: "curl -fsSL https://chatgpt.com/codex/install.sh | sh",
+      other: "npm install -g @openai/codex"
+    },
+    signIn: "Run `codex login`",
+    docsUrl: "https://learn.chatgpt.com/docs/codex/cli"
+  },
+  pi: {
+    name: "Pi",
+    worksWith: "Many providers, including a Claude or ChatGPT plan",
+    install: {
+      macos: "npm install -g --ignore-scripts @earendil-works/pi-coding-agent",
+      linux: "curl -fsSL https://pi.dev/install.sh | sh",
+      other: "npm install -g --ignore-scripts @earendil-works/pi-coding-agent"
+    },
+    signIn: "Run `pi`, then type `/login`",
+    docsUrl: "https://pi.dev/docs/latest/quickstart"
+  }
+};
+function installCommand(commands, platform) {
+  if (platform === "darwin") return commands.macos;
+  return platform === "linux" ? commands.linux : commands.other;
+}
+function setupPrompt(agents) {
+  return [
+    "I use an app that runs a coding agent's command-line program (CLI) on this computer. Please install one of these CLIs here and help me sign in to it:",
+    "",
+    ...agents.map(
+      (setup) => `- ${setup.name}. Works with: ${setup.worksWith}. Install: \`${setup.install}\`. Sign in, in a terminal: ${setup.signIn}.`
+    ),
+    "",
+    "Pick the one that works with the plan or account I already have, and ask me if you can't tell. Signing in is interactive, so if you can't do it yourself, tell me the command to run in a terminal. Once the CLI runs and is signed in, tell me, so I can check again in the app."
+  ].join("\n");
+}
+function localAgentSetupGuide(platform = process.platform) {
+  const agents = LOCAL_AGENT_IDS.map((agent) => ({
+    agent,
+    ...AGENTS[agent],
+    install: installCommand(AGENTS[agent].install, platform)
+  }));
+  return {
+    missing: "No coding agent is set up on this computer.",
+    cliOnly: "This app runs the agent's command-line program (CLI). A desktop app, browser chat or editor extension, such as the Claude or ChatGPT app, isn't enough on its own.",
+    agents,
+    setupPrompt: setupPrompt(agents)
   };
-  return new LocalAgent(runner, {
-    model: settings.model,
-    effort: settings.effort,
-    timeoutMs: settings.timeoutMs
-  });
 }
 
 const LINUX_MAX_ARGUMENT_BYTES = 131072;
+const SHELL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function agentSessionMode(platform = process.platform) {
   if (platform === "win32") return "none";
   return platform === "darwin" ? "terminal" : "command";
@@ -832,6 +1010,10 @@ async function startAgentSession(config) {
   if (!isLocalAgentId(config.agent)) {
     throw new TypeError(`Unknown local agent: ${String(config.agent)}`);
   }
+  const badName = config.unsetEnv?.find((name) => !SHELL_NAME.test(name));
+  if (badName !== void 0) {
+    throw new TypeError(`Not a shell variable name in unsetEnv: ${JSON.stringify(badName)}`);
+  }
   const platform = config.platform ?? process.platform;
   const mode = agentSessionMode(platform);
   if (mode === "none") {
@@ -851,7 +1033,7 @@ async function startAgentSession(config) {
   const files = writeSessionFiles(config, binaryPath, adapter.sessionArgs(config.model, config.approval ?? "ask"));
   if (mode === "command") return { kind: "command", files };
   try {
-    await node_util.promisify(node_child_process.execFile)("open", [files.launcherPath]);
+    await node_util.promisify(node_child_process.execFile)("open", [files.launcherPath], { env: config.env ?? process.env });
   } catch (error) {
     return { kind: "open_failed", files, error: error instanceof Error ? error.message : String(error) };
   }
@@ -866,7 +1048,7 @@ function writeSessionFiles(config, binaryPath, agentArgs) {
   const promptPath = path__namespace.join(config.dir, `${name}.md`);
   const launcherPath = path__namespace.join(config.dir, `${name}.command`);
   fs__namespace.writeFileSync(promptPath, config.prompt, { mode: 384, flag: "wx" });
-  fs__namespace.writeFileSync(launcherPath, sessionLauncher({ cwd: config.cwd, binaryPath, agentArgs, promptPath }), {
+  fs__namespace.writeFileSync(launcherPath, sessionLauncher({ cwd: config.cwd, binaryPath, agentArgs, promptPath, unsetEnv: config.unsetEnv }), {
     mode: 448,
     flag: "wx"
   });
@@ -876,10 +1058,17 @@ function defaultSessionName(agent) {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replaceAll(":", "-");
   return `${stamp}-${agent}-${node_crypto.randomBytes(2).toString("hex")}`;
 }
-function sessionLauncher({ cwd, binaryPath, agentArgs, promptPath }) {
+function sessionLauncher({
+  cwd,
+  binaryPath,
+  agentArgs,
+  promptPath,
+  unsetEnv = []
+}) {
   const command = [binaryPath, ...agentArgs].map(shellQuote).join(" ");
   return [
     "#!/bin/sh",
+    ...unsetEnv.length > 0 ? [`unset ${unsetEnv.map(shellQuote).join(" ")}`] : [],
     `cd ${shellQuote(cwd)} || exit 1`,
     `exec ${command} -- "$(cat ${shellQuote(promptPath)})"`,
     ""
@@ -895,5 +1084,6 @@ exports.detectLocalAgents = detectLocalAgents;
 exports.findLocalAgent = findLocalAgent;
 exports.isLocalAgentId = isLocalAgentId;
 exports.localAgent = localAgent;
+exports.localAgentSetupGuide = localAgentSetupGuide;
 exports.sessionLauncher = sessionLauncher;
 exports.startAgentSession = startAgentSession;