agentproc 0.2.1 → 0.4.0

package/src/runner.js

@@ -4,7 +4,7 @@
  * protocol-compliant agent invocation.
  *
  * This module is the canonical implementation of the AgentProc bridge-side
- * contract (spec/protocol.md). The CLI (cli.js) is a thin wrapper around it.
+ * contract (spec/protocol.md, wire protocol 0.1). The CLI (cli.js) is a thin wrapper around it.
  *
  * Responsibilities:
  *   - Parse and validate a profile object
@@ -26,6 +26,7 @@
  */
 
 const { spawn } = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
@@ -74,17 +75,43 @@ function normalizeProfile(raw) {
     throw new Error('profile.command must be a non-empty string');
   }
 
-  // Split command into argv on whitespace, no shell (per spec).
-  const argv = p.command.trim().split(/\s+/);
-  if (argv.length === 0) {
+  // Per spec: `command` is argv[0]; `args` is argv[1..]. Two mutually
+  // exclusive forms:
+  //   (a) `args` absent + command has whitespace → split command into argv
+  //       (the legacy shorthand: `command: python3 ./bridge.py`)
+  //   (b) `args` present (even empty `[]`) → command is a single token,
+  //       never split. Lets paths with spaces stay whole:
+  //         command: "/path with spaces/my agent"
+  //         args: []
+  // `args: []` (explicit empty array) is DISTINCT from "args absent": the
+  // explicit form means "do not split command"; the absent form falls back
+  // to the whitespace-splitting shorthand.
+  const argsFieldPresent = raw.agentproc
+    ? (Object.prototype.hasOwnProperty.call(raw.agentproc, 'args') && raw.agentproc.args != null)
+    : (Object.prototype.hasOwnProperty.call(raw, 'args') && raw.args != null);
+  const argv = argsFieldPresent ? [p.command.trim()] : p.command.trim().split(/\s+/);
+  if (argv.length === 0 || argv[0] === '') {
     throw new Error('profile.command produced empty argv');
   }
 
+  // env_allowlist (optional): when present, ${VAR} references in the env
+  // block whose name is NOT in the list expand to empty + a stderr warning.
+  // Absent ⇒ current behaviour (expand against the full bridge environment).
+  // Opt-in: existing profiles keep working unchanged.
+  let envAllowlist = null;
+  if (p.env_allowlist !== undefined && p.env_allowlist !== null) {
+    if (!Array.isArray(p.env_allowlist)) {
+      throw new Error('profile.env_allowlist must be a list');
+    }
+    envAllowlist = new Set(p.env_allowlist.map(String));
+  }
+
   return {
     argv,
     args: Array.isArray(p.args) ? p.args.map(String) : [],
     cwd: p.cwd ? expandPath(String(p.cwd)) : undefined,
     env: p.env && typeof p.env === 'object' ? p.env : {},
+    env_allowlist: envAllowlist,
     stdin: p.stdin === 'message' ? 'message' : 'none',
     timeout_secs: Number.isFinite(p.timeout_secs) ? p.timeout_secs : DEFAULT_TIMEOUT_SECS,
     kill_grace_secs: Number.isFinite(p.kill_grace_secs) ? p.kill_grace_secs : DEFAULT_KILL_GRACE_SECS,
@@ -100,22 +127,147 @@ function expandPath(p) {
 }
 
 /**
- * Substitute {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}} placeholders
- * in a string value. Per spec, no shell is involved.
+ * Best-effort pattern check against the agent's accumulated stderr to spot
+ * common "bridge file not found" / "module not found" failures that the
+ * wrapped interpreter writes to its own stderr before exiting non-zero.
+ * Returns a human-friendly hint, or '' if nothing recognizable.
+ *
+ * This is intentionally narrow — we only flag high-confidence patterns to
+ * avoid mis-diagnosing genuine agent errors.
+ */
+function diagnoseStderrFailure(stderrText, { argv }) {
+  if (!stderrText) return '';
+  const lower = stderrText.toLowerCase();
+
+  // python3: "can't open file '/path/x.py': [Errno 2] No such file or directory"
+  // Also covers "cannot open file" (localized variants).
+  const pyMatch = stderrText.match(/(?:can'?t|cannot) open file '([^']+)': \[Errno 2\] No such file or directory/);
+  if (pyMatch) {
+    const file = pyMatch[1];
+    return `agent script not found: ${file}. Check the profile's command path (likely a {{PROFILE_DIR}} issue or a typo).`;
+  }
+
+  // node: "Error: Cannot find module '/path/x.js'"
+  const nodeMatch = stderrText.match(/Cannot find module '([^']+)'/);
+  if (nodeMatch) {
+    const mod = nodeMatch[1];
+    return `agent script not found: ${mod}. Check the profile's command path (likely a {{PROFILE_DIR}} issue or a typo).`;
+  }
+
+  // bash: "bash: line N: ./x.sh: No such file or directory"
+  const bashMatch = stderrText.match(/(?:^|\n)[^:]+: line \d+: ([^:]+): No such file or directory/);
+  if (bashMatch) {
+    const file = bashMatch[1];
+    return `agent script not found: ${file}. Check the profile's command path.`;
+  }
+
+  // Generic Errno 2 sentinel, in case the interpreter phrasing differs.
+  if (/errno 2|enoent|no such file or directory/.test(lower)) {
+    return `agent reported a missing file. Check the profile's command and cwd.`;
+  }
+
+  return '';
+}
+
+/**
+ * Produce a human-friendly hint for a spawn ENOENT-style error.
+ *
+ * Node's spawn attributes the error to argv[0] regardless of whether it was
+ * the command itself or a referenced file (e.g. `./bridge.py`) that wasn't
+ * found, which is very confusing. We inspect cwd + argv to give a better
+ * diagnosis. Returns '' when nothing useful can be said.
+ */
+function diagnoseSpawnError(err, { argv, cwd, env }) {
+  const code = err && err.code;
+  const message = (err && err.message) || '';
+  if (code !== 'ENOENT' && !/ENOENT/.test(message)) return '';
+
+  // (a) cwd doesn't exist or isn't a directory
+  if (cwd) {
+    try {
+      const stat = fs.statSync(cwd);
+      if (!stat.isDirectory()) {
+        return `profile.cwd is not a directory: ${cwd}`;
+      }
+    } catch (e) {
+      if (e && (e.code === 'EACCES' || e.code === 'EPERM')) {
+        return `profile.cwd is not accessible (permission denied): ${cwd}`;
+      }
+      return `profile.cwd does not exist: ${cwd}. Pass --cwd <path> to point at a real directory.`;
+    }
+  }
+
+  // (b) the command (argv[0]) is not on PATH
+  const cmd = argv[0];
+  const isPathed = /[\\/]/.test(cmd);
+  if (!isPathed) {
+    // Bare command like 'python3' or 'claude' — check PATH ourselves.
+    const PATH = (env && env.PATH) || '';
+    if (PATH) {
+      const found = PATH.split(path.delimiter).some(d => {
+        try {
+          const p = path.join(d, cmd);
+          fs.accessSync(p, fs.constants.X_OK);
+          return true;
+        } catch { return false; }
+      });
+      if (!found) {
+        return `'${cmd}' not found on PATH. Install it, or if it's installed, make sure PATH is set correctly when the bridge spawns the agent.`;
+      }
+    }
+    return `'${cmd}' could not be executed. Verify it is installed and on PATH.`;
+  }
+
+  // (c) argv[0] looks like a path — check whether the file itself exists
+  try {
+    fs.accessSync(cmd, fs.constants.X_OK);
+  } catch {
+    return `command path does not exist or is not executable: ${cmd}`;
+  }
+
+  // (d) Command exists; suspect an argv file argument (e.g. python3 ./bridge.py).
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('-') && (a.includes('/') || a.includes('\\'))) {
+      // Resolve relative to cwd (mirrors spawn's resolution)
+      const resolved = path.isAbsolute(a) ? a : (cwd ? path.resolve(cwd, a) : path.resolve(a));
+      try {
+        fs.accessSync(resolved, fs.constants.R_OK);
+      } catch {
+        return `argument file not found: ${a} (resolved to ${resolved}). The profile likely needs --cwd or the bundled script path is wrong.`;
+      }
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Substitute {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}}, {{PROFILE_DIR}}
+ * placeholders in a string value. Per spec, no shell is involved.
  */
 function substitute(value, ctx) {
   return String(value)
     .replace(/\{\{MESSAGE\}\}/g, ctx.message || '')
     .replace(/\{\{SESSION_ID\}\}/g, ctx.sessionId || '')
-    .replace(/\{\{SESSION_NAME\}\}/g, ctx.sessionName || '');
+    .replace(/\{\{SESSION_NAME\}\}/g, ctx.sessionName || '')
+    .replace(/\{\{PROFILE_DIR\}\}/g, ctx.profileDir || '');
 }
 
 /**
- * Expand ${VAR} references against process.env, like a typical shell would.
+ * Expand ${VAR} references against `env`, like a typical shell would.
  * Unknown variables expand to empty string (POSIX sh behavior).
+ *
+ * When `allowlist` is a Set of names, references to names NOT in the set
+ * expand to empty and `onBlocked` (if given) is called with each blocked
+ * name. When `allowlist` is null, all references expand normally.
  */
-function expandEnvRef(value, env) {
+function expandEnvRef(value, env, allowlist = null, onBlocked = null) {
   return String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+    if (allowlist && !allowlist.has(name)) {
+      if (onBlocked) onBlocked(name);
+      return '';
+    }
     const v = env[name];
     return v !== undefined ? v : '';
   });
@@ -132,13 +284,18 @@ function expandEnvRef(value, env) {
 function decodeJsonValue(raw) {
   const text = raw.trim();
   if (text === '') return '';
+  let v;
   try {
-    const v = JSON.parse(text);
-    return typeof v === 'string' ? v : String(v);
+    v = JSON.parse(text);
   } catch {
     // Lenient: treat as plain string.
     return text;
   }
+  // Only JSON strings are meaningful payloads — a sentinel's value is text
+  // for the user. Non-string JSON (number/bool/null/array/object) means the
+  // agent misused the API; fall back to the raw text so the result is
+  // language-independent (String(true) != str(True) across runtimes).
+  return typeof v === 'string' ? v : text;
 }
 
 /**
@@ -211,17 +368,28 @@ async function run(profileRaw, options) {
   const sessionName = options.sessionName || 'default';
   const streaming = options.streaming !== undefined ? !!options.streaming : profile.streaming;
   const timeoutSecs = options.timeoutSecs !== undefined ? options.timeoutSecs : profile.timeout_secs;
-  const cwd = options.cwd || profile.cwd;
+  let cwd = options.cwd || profile.cwd;
+  // Resolve relative cwd against the profile's directory (if known) so that
+  // profiles written as `cwd: .` work no matter where the user invokes from.
+  // Absolute paths and `~`-prefixed paths are already absolute post-expand.
+  if (cwd && !path.isAbsolute(cwd) && options.profileDir) {
+    cwd = path.resolve(options.profileDir, cwd);
+  }
 
   // Build the substitution context for {{MESSAGE}} etc.
+  // {{PROFILE_DIR}} resolves to the directory the profile YAML lives in
+  // (passed by the CLI; undefined when run programmatically without it),
+  // letting profiles reference bundled scripts via absolute paths while
+  // still allowing the agent's cwd to be anywhere.
   const substCtx = {
     message: options.message,
     sessionId,
     sessionName,
+    profileDir: options.profileDir || '',
   };
 
   // Build argv: command + args (with placeholders substituted).
-  const argv = [...profile.argv];
+  const argv = profile.argv.map(a => substitute(a, substCtx));
   for (const a of profile.args) {
     argv.push(substitute(a, substCtx));
   }
@@ -229,8 +397,13 @@ async function run(profileRaw, options) {
   // Build env: start with process.env (so PATH etc. work), add profile.env
   // (with ${VAR} refs expanded against process.env), then add AGENT_* vars.
   const env = { ...process.env };
+  const allowlist = profile.env_allowlist;
   for (const [k, v] of Object.entries(profile.env)) {
-    env[k] = expandEnvRef(substitute(v, substCtx), process.env);
+    env[k] = expandEnvRef(substitute(v, substCtx), process.env, allowlist, (name) => {
+      if (options.onStderr) {
+        options.onStderr(`[agentproc runner] env_allowlist blocked \${${name}} (not in allowlist); expanded to empty`);
+      }
+    });
   }
   if (options.extraEnv) {
     for (const [k, v] of Object.entries(options.extraEnv)) {
@@ -303,8 +476,23 @@ async function run(profileRaw, options) {
 
   // ---- stderr: forward as debug ----
   let stderrBuf = '';
+  // Two views on stderr:
+  //   - stderrWindow: bounded sliding window (8 KB) — reserved for future
+  //     UI/display use so a noisy agent cannot exhaust memory.
+  //   - stderrFull:   unbounded capture used for post-mortem pattern
+  //     diagnosis. Without the full text, a chatty agent can push the real
+  //     error out of the window and the friendly hint goes missing.
+  let stderrWindow = '';
+  let stderrFull = '';
+  const STDERR_CAP = 8192;
   child.stderr.on('data', chunk => {
-    stderrBuf += chunk.toString();
+    const text = chunk.toString();
+    stderrBuf += text;
+    stderrFull += text;
+    stderrWindow += text;
+    if (stderrWindow.length > STDERR_CAP) {
+      stderrWindow = stderrWindow.slice(stderrWindow.length - STDERR_CAP);
+    }
     let nl;
     while ((nl = stderrBuf.indexOf('\n')) >= 0) {
       const line = stderrBuf.slice(0, nl);
@@ -320,6 +508,11 @@ async function run(profileRaw, options) {
   }
 
   // ---- timeout handling per spec: SIGTERM → grace → SIGKILL ----
+  // On POSIX, child.kill('SIGTERM') is a real signal the agent can trap and
+  // flush; on Windows, Node translates any signal name to TerminateProcess,
+  // so the grace period is effectively a no-op there. The two-step shape is
+  // preserved so POSIX behaviour is correct; Windows callers get a hard kill
+  // at the deadline (acceptable per the spec's Windows caveat).
   let timer = null;
   if (timeoutSecs > 0) {
     timer = setTimeout(() => {
@@ -340,8 +533,20 @@ async function run(profileRaw, options) {
   const exitCode = await new Promise(resolve => {
     child.on('close', code => resolve(code));
     child.on('error', err => {
-      // spawn error (ENOENT etc.)
-      if (options.onStderr) options.onStderr(`[agentproc runner] spawn error: ${err.message}`);
+      // spawn error — usually ENOENT. Node attributes it to argv[0]
+      // regardless of whether it was the command or a referenced file that
+      // wasn't found, so disambiguate for the user.
+      const tip = diagnoseSpawnError(err, { argv, cwd, env });
+      if (options.onStderr) {
+        options.onStderr(`[agentproc runner] spawn error: ${err.message}`);
+        if (tip) options.onStderr(`[agentproc runner] hint: ${tip}`);
+      }
+      // Surface as an AGENT_ERROR so the user sees it on the bridge too.
+      if (options.onError) {
+        const msg = tip || err.message;
+        options.onError(`failed to start agent: ${msg}`);
+      }
+      if (!result.error) result.error = tip || err.message;
       resolve(EXIT_ERROR);
     });
   });
@@ -353,7 +558,23 @@ async function run(profileRaw, options) {
     handleLine(stdoutBuf.replace(/\r$/, ''));
   }
 
-  // Compose reply body.
+  // Flush any remaining stderr (the chunk handler only emits on newlines).
+  if (stderrBuf.length > 0) {
+    if (options.onStderr) options.onStderr(stderrBuf.replace(/\r$/, ''));
+  }
+
+  // If the agent exited non-zero with no AGENT_ERROR, peek at its stderr for
+  // common "command/file not found" patterns and surface a friendly hint.
+  // Uses the FULL stderr — a noisy agent can fill the 8 KB window with
+  // progress junk before the real error lands at the end.
+  if (!killed && !result.error && exitCode !== 0) {
+    const hint = diagnoseStderrFailure(stderrFull, { argv });
+    if (hint) {
+      result.error = hint;
+      if (options.onError) options.onError(hint);
+    }
+  }
+
   result.reply = bodyLines.join('\n');
   if (result.reply.length > profile.max_reply_chars) {
     const suffix = profile.max_reply_chars === DEFAULT_MAX_REPLY_CHARS