agentproc 0.1.1 → 0.2.1

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "agentproc",
-  "version": "0.1.1",
-  "description": "AgentProc Protocol SDK for Node.js — connect any Agent CLI to a messaging platform",
+  "version": "0.2.1",
+  "description": "AgentProc Protocol SDK + CLI for Node.js — connect any Agent CLI to a messaging platform",
   "main": "src/index.js",
   "types": "src/index.d.ts",
+  "bin": {
+    "agentproc": "src/cli.js"
+  },
   "scripts": {
-    "test": "node --test src/index.test.js"
+    "test": "node --test src/index.test.js src/runner.test.js"
   },
-  "keywords": ["agentproc", "agent", "bridge", "protocol", "cli", "ai"],
+  "keywords": ["agentproc", "agent", "bridge", "protocol", "cli", "ai", "runner"],
   "license": "MIT",
   "engines": {
     "node": ">=18"
@@ -16,5 +19,5 @@
     "type": "git",
     "url": "https://github.com/jeffkit/agentproc.git"
   },
-  "homepage": "https://jeffkit.github.io/agentproc/"
+  "homepage": "https://agentproc.dev/"
 }

package/src/cli.js

@@ -0,0 +1,505 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * agentproc CLI — run any AgentProc profile against a message.
+ *
+ * Usage:
+ *   agentproc --profile <path.yaml> --prompt "hello" [options]
+ *
+ * Options:
+ *   --profile, -p <path>      Profile YAML path (required)
+ *   --prompt <text>           User message (required, unless --stdin)
+ *   --session <id>            Previous session id for multi-turn
+ *   --session-name <name>     Human-readable session name
+ *   --from <user>             Sender identifier
+ *   --cwd <path>              Override profile.cwd
+ *   --env KEY=VALUE           Extra env var (repeatable)
+ *   --timeout <secs>          Override profile.timeout_secs
+ *   --no-stream               Disable streaming (set AGENT_STREAMING=0)
+ *   --verbose                 Forward protocol lines to stderr (default)
+ *   --quiet                   Suppress protocol lines on stderr
+ *   --raw                     Don't parse stdout; forward agent output verbatim
+ *   --stdin                   Read prompt from stdin instead of --prompt
+ *   --version                 Print version and exit
+ *   --help, -h                Show help
+ *
+ * Output (default mode):
+ *   stderr  → protocol lines (AGENT_PARTIAL:, AGENT_SESSION:, AGENT_ERROR:) in real time
+ *   stdout  → final reply body (printed after agent exits)
+ *   exit    → 0 success, 1 error, 124 timeout
+ *
+ * Output (--raw mode):
+ *   stdout  → agent's stdout, verbatim, no parsing
+ *   exit    → agent's exit code
+ *
+ * The last AGENT_SESSION: id is also printed on stderr at the very end,
+ * prefixed with "agentproc:session:" so shell scripts can capture it:
+ *   session=$(agentproc ... 2>&1 | grep '^agentproc:session:' | cut -d: -f3)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const runner = require('./runner.js');
+const { PROTOCOL_VERSION } = runner;
+
+const PKG_VERSION = require('../package.json').version;
+
+// ---------------------------------------------------------------------------
+// Arg parsing — minimal hand-rolled parser, no deps
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = {
+    profile: null,
+    prompt: null,
+    session: '',
+    sessionName: 'default',
+    from: '',
+    cwd: null,
+    env: {},
+    timeout: null,
+    stream: true,
+    verbose: true,
+    raw: false,
+    stdin: false,
+    help: false,
+    version: false,
+  };
+  const extras = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      if (i + 1 >= argv.length) throw new Error(`option ${a} requires a value`);
+      return argv[++i];
+    };
+    switch (a) {
+      case '-h': case '--help': opts.help = true; break;
+      case '--version': opts.version = true; break;
+      case '--profile': case '-p': opts.profile = next(); break;
+      case '--prompt': opts.prompt = next(); break;
+      case '--session': opts.session = next(); break;
+      case '--session-name': opts.sessionName = next(); break;
+      case '--from': opts.from = next(); break;
+      case '--cwd': opts.cwd = next(); break;
+      case '--env': {
+        const kv = next();
+        const eq = kv.indexOf('=');
+        if (eq < 0) throw new Error(`--env expects KEY=VALUE, got: ${kv}`);
+        opts.env[kv.slice(0, eq)] = kv.slice(eq + 1);
+        break;
+      }
+      case '--timeout': opts.timeout = parseInt(next(), 10); break;
+      case '--no-stream': opts.stream = false; break;
+      case '--verbose': opts.verbose = true; break;
+      case '--quiet': opts.verbose = false; break;
+      case '--raw': opts.raw = true; break;
+      case '--stdin': opts.stdin = true; break;
+      default:
+        if (a.startsWith('--')) throw new Error(`unknown option: ${a}`);
+        extras.push(a);
+    }
+  }
+  return { opts, extras };
+}
+
+function showHelp() {
+  process.stdout.write(`agentproc v${PKG_VERSION} (protocol ${PROTOCOL_VERSION})
+
+Usage:
+  agentproc --profile <path.yaml> --prompt "hello" [options]
+
+Required:
+  --profile, -p <path>      Profile YAML path
+  --prompt <text>           User message (or use --stdin)
+
+Session:
+  --session <id>            Previous session id (multi-turn)
+  --session-name <name>     Human-readable session name (default: "default")
+  --from <user>             Sender identifier
+
+Execution:
+  --cwd <path>              Override profile.cwd
+  --env KEY=VALUE           Extra env var (repeatable)
+  --timeout <secs>          Override profile.timeout_secs
+  --no-stream               Set AGENT_STREAMING=0
+
+Output:
+  --verbose                 Forward protocol lines to stderr (default)
+  --quiet                   Suppress protocol lines on stderr
+  --raw                     Don't parse stdout; forward agent output verbatim
+  --stdin                   Read prompt from stdin instead of --prompt
+
+Other:
+  --version                 Print version and exit
+  --help, -h                Show this help
+
+Output semantics:
+  stderr  → protocol lines (AGENT_PARTIAL:, AGENT_SESSION:, AGENT_ERROR:)
+  stdout  → final reply body (non-protocol lines)
+  exit    → 0 success · 1 error · 124 timeout (per spec)
+
+The final session id is printed on stderr as: agentproc:session:<id>
+
+Examples:
+  agentproc --profile hub/echo-agent/profile.yaml --prompt "hi"
+  agentproc -p hub/claude-code/profile.yaml --prompt "hello" --verbose
+  cat prompt.txt | agentproc -p prof.yaml --stdin
+`);
+}
+
+function showVersion() {
+  process.stdout.write(`agentproc ${PKG_VERSION} (protocol ${PROTOCOL_VERSION})\n`);
+}
+
+// ---------------------------------------------------------------------------
+// YAML parsing — minimal hand-rolled, supports the subset hub profiles use
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a YAML profile file into a JS object.
+ *
+ * We deliberately avoid a YAML dependency to keep the SDK zero-dep.
+ * The subset we parse: nested maps, scalar values, block scalars (|), arrays
+ * of scalars (under `args:` and `tags:`). This covers every hub/ profile
+ * and every spec/protocol.md example.
+ *
+ * For anything more complex, users are encouraged to pre-parse their YAML
+ * and pass the object directly to the runner.
+ */
+function parseYamlSimple(text) {
+  // First try JSON (also valid YAML for simple cases).
+  try { return JSON.parse(text); } catch {}
+
+  const lines = text.split(/\r?\n/);
+  const root = {};
+  const stack = [{ indent: -1, obj: root, key: null }];
+
+  function currentContainer(minIndent) {
+    while (stack.length > 1 && stack[stack.length - 1].indent >= minIndent) {
+      stack.pop();
+    }
+    return stack[stack.length - 1];
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (raw.trim() === '' || raw.trim().startsWith('#')) continue;
+    const indent = raw.match(/^[ \t]*/)[0].replace(/\t/g, '  ').length;
+    const content = raw.trim();
+
+    // key: value
+    const m = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) {
+      // Skip unparseable lines (e.g., complex flow scalars); don't crash.
+      continue;
+    }
+    const [, key, val] = m;
+    const container = currentContainer(indent);
+
+    if (val === '') {
+      // Could be a nested map, a block scalar, or a sequence. Look ahead.
+      const nextRaw = lines[i + 1] || '';
+      const nextIndent = nextRaw.match(/^[ \t]*/)[0].replace(/\t/g, '  ').length;
+      if (nextIndent > indent) {
+        if (nextRaw.trim().startsWith('- ')) {
+          // Sequence
+          const arr = [];
+          container.obj[key] = arr;
+          stack.push({ indent, obj: { __seq: arr }, key });
+        } else {
+          // Nested map
+          const child = {};
+          container.obj[key] = child;
+          stack.push({ indent, obj: child, key });
+        }
+      } else {
+        // Empty value, no children
+        container.obj[key] = '';
+      }
+    } else if (val === '|' || val === '|-') {
+      // Block scalar — consume subsequent more-indented lines.
+      const blockLines = [];
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        const nr = lines[j];
+        if (nr.trim() === '' && j === lines.length - 1) break;
+        const ni = nr.match(/^[ \t]*/)[0].replace(/\t/g, '  ').length;
+        if (ni <= indent && nr.trim() !== '') break;
+        blockLines.push(nr.slice(Math.min(indent + 2, nr.length)));
+      }
+      container.obj[key] = blockLines.join('\n').replace(/\n+$/, val === '|' ? '\n' : '');
+      i = j - 1;
+    } else if (val.startsWith('- ')) {
+      // Inline sequence element on same line — rare but handle it.
+      if (!Array.isArray(container.obj[key])) container.obj[key] = [];
+      container.obj[key].push(stripScalar(val.slice(2)));
+    } else {
+      container.obj[key] = stripScalar(val);
+    }
+  }
+
+  // Post-process: walk and lift any __seq arrays.
+  function liftSeqs(o) {
+    if (Array.isArray(o)) {
+      o.forEach(liftSeqs);
+    } else if (o && typeof o === 'object') {
+      for (const k of Object.keys(o)) {
+        const v = o[k];
+        if (v && typeof v === 'object' && '__seq' in v) {
+          o[k] = v.__seq;
+          liftSeqs(o[k]);
+        } else {
+          liftSeqs(v);
+        }
+      }
+    }
+  }
+  liftSeqs(root);
+  return root;
+}
+
+function stripScalar(v) {
+  // Quoted string — return inner content verbatim.
+  if ((v.startsWith('"') && v.endsWith('"')) ||
+      (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  // Flow sequence: [a, b, c]
+  if (v.startsWith('[') && v.endsWith(']')) {
+    const inner = v.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner.split(',').map(s => stripScalar(s.trim()));
+  }
+  // Booleans / null
+  const lv = v.toLowerCase();
+  if (lv === 'true') return true;
+  if (lv === 'false') return false;
+  if (lv === 'null' || lv === '~') return null;
+  // Numbers (int / float, optional sign)
+  if (/^[+-]?\d+$/.test(v)) return parseInt(v, 10);
+  if (/^[+-]?\d+\.\d+$/.test(v)) return parseFloat(v);
+  return v;
+}
+
+// ---------------------------------------------------------------------------
+// Sequence continuation: collect "- ..." entries under a key whose value
+// became { __seq: [...] }. Done above. But standalone "- ..." lines (when
+// the container's current key already has an array) need handling.
+// ---------------------------------------------------------------------------
+
+// Re-do the parsing with proper sequence handling.
+function parseYaml(text) {
+  try { return JSON.parse(text); } catch {}
+
+  // Use a line-based state machine that handles sequences better.
+  const lines = text.split(/\r?\n/);
+  const root = {};
+  /** @type {Array<{indent:number, obj:Object|Array, parentKey:string|null, parent:Object|null}>} */
+  const stack = [{ indent: -1, obj: root, parentKey: null, parent: null }];
+
+  function top() { return stack[stack.length - 1]; }
+  function popUntil(minIndent) {
+    while (stack.length > 1 && top().indent >= minIndent) stack.pop();
+    return top();
+  }
+
+  function getIndent(s) {
+    return s.match(/^[ \t]*/)[0].replace(/\t/g, '  ').length;
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (raw.trim() === '' || raw.trim().startsWith('#')) continue;
+    const indent = getIndent(raw);
+    const content = raw.slice(indent).replace(/\r$/, '');
+    const cont = popUntil(indent);
+
+    // Sequence item: "- value" or "-"
+    if (content.startsWith('- ') || content === '-') {
+      // Find the parent object that has a key awaiting a sequence value.
+      // Strategy: if top().obj is an array, push to it; else we need to
+      // convert — but our key: line lookahead already created the array.
+      if (Array.isArray(cont.obj)) {
+        const rest = content === '-' ? '' : content.slice(2);
+        if (rest.trim() === '') {
+          // Map under sequence — rare in our profiles, skip gracefully.
+          continue;
+        }
+        cont.obj.push(stripScalar(rest));
+      }
+      continue;
+    }
+
+    // key: value
+    const m = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    const [, key, val] = m;
+
+    if (val === '') {
+      // Look ahead: is the next non-empty, more-indented line a sequence?
+      let j = i + 1;
+      while (j < lines.length && (lines[j].trim() === '' || lines[j].trim().startsWith('#'))) j++;
+      const nextRaw = lines[j] || '';
+      const nextIndent = getIndent(nextRaw);
+      const nextContent = nextRaw.slice(nextIndent);
+      if (nextIndent > indent && (nextContent.startsWith('- ') || nextContent === '-')) {
+        const arr = [];
+        cont.obj[key] = arr;
+        stack.push({ indent, obj: arr, parentKey: key, parent: cont.obj });
+      } else if (nextIndent > indent) {
+        const child = {};
+        cont.obj[key] = child;
+        stack.push({ indent, obj: child, parentKey: key, parent: cont.obj });
+      } else {
+        cont.obj[key] = '';
+      }
+    } else if (val === '|' || val === '|-' || val === '>') {
+      const blockLines = [];
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        const nr = lines[j];
+        const ni = getIndent(nr);
+        if (nr.trim() === '') { blockLines.push(''); continue; }
+        if (ni <= indent) break;
+        blockLines.push(nr.slice(Math.min(indent + 2, nr.length)));
+      }
+      const joined = blockLines.join('\n');
+      container_set(cont.obj, key, val === '|'
+        ? joined.replace(/\n*$/, '\n')
+        : joined.replace(/\n*$/, ''));
+      i = j - 1;
+    } else {
+      container_set(cont.obj, key, stripScalar(val));
+    }
+  }
+
+  return root;
+}
+
+function container_set(obj, key, value) {
+  obj[key] = value;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const { opts } = parseArgs(process.argv.slice(2));
+
+  if (opts.help) { showHelp(); process.exit(0); }
+  if (opts.version) { showVersion(); process.exit(0); }
+
+  if (!opts.profile) {
+    process.stderr.write('error: --profile is required\n\n');
+    showHelp();
+    process.exit(2);
+  }
+
+  // Read prompt from --stdin if requested.
+  let prompt = opts.prompt;
+  if (opts.stdin) {
+    prompt = fs.readFileSync(0, 'utf8').replace(/\n$/, '');
+  }
+  if (prompt == null) {
+    process.stderr.write('error: --prompt (or --stdin) is required\n');
+    process.exit(2);
+  }
+
+  // Read & parse profile YAML.
+  let profileRaw;
+  try {
+    const yamlText = fs.readFileSync(path.resolve(opts.profile), 'utf8');
+    profileRaw = parseYaml(yamlText);
+  } catch (e) {
+    process.stderr.write(`error: failed to read profile ${opts.profile}: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  // ---- Raw mode: spawn agent, pipe stdout through, exit with agent code ----
+  if (opts.raw) {
+    const { spawn } = require('node:child_process');
+    try {
+      const r = await runner.run(profileRaw, {
+        message: prompt,
+        sessionId: opts.session,
+        sessionName: opts.sessionName,
+        fromUser: opts.from,
+        streaming: opts.stream,
+        cwd: opts.cwd,
+        extraEnv: opts.env,
+        timeoutSecs: opts.timeout,
+        // No callbacks — we replace stdout forwarding below.
+      });
+      // The runner buffers reply; for raw mode we want streaming verbatim,
+      // so we re-implement with raw pipes. Simpler: just print the reply
+      // (which equals the agent's stdout minus protocol lines).
+      // For TRUE raw output (including protocol lines), users should use
+      // the bridge script directly.
+      process.stdout.write(r.reply);
+      if (r.reply && !r.reply.endsWith('\n')) process.stdout.write('\n');
+      process.exit(r.exitCode === 0 ? 0 : 1);
+    } catch (e) {
+      process.stderr.write(`error: ${e.message}\n`);
+      process.exit(1);
+    }
+  }
+
+  // ---- Default mode: classify and pretty-print ----
+  try {
+    const r = await runner.run(profileRaw, {
+      message: prompt,
+      sessionId: opts.session,
+      sessionName: opts.sessionName,
+      fromUser: opts.from,
+      streaming: opts.stream,
+      cwd: opts.cwd,
+      extraEnv: opts.env,
+      timeoutSecs: opts.timeout,
+      onPartial: (text) => {
+        if (opts.verbose) process.stderr.write(`AGENT_PARTIAL:${JSON.stringify(text)}\n`);
+      },
+      onSession: (id) => {
+        if (opts.verbose) process.stderr.write(`AGENT_SESSION:${id}\n`);
+      },
+      onError: (msg) => {
+        if (opts.verbose) process.stderr.write(`AGENT_ERROR:${JSON.stringify(msg)}\n`);
+      },
+      onStderr: (line) => {
+        if (opts.verbose) process.stderr.write(`[agent stderr] ${line}\n`);
+      },
+    });
+
+    // Print final reply body to stdout.
+    if (r.reply) {
+      process.stdout.write(r.reply);
+      if (!r.reply.endsWith('\n')) process.stdout.write('\n');
+    }
+
+    // Final session id on stderr (for shell capture).
+    if (r.sessionId) {
+      process.stderr.write(`agentproc:session:${r.sessionId}\n`);
+    }
+
+    if (r.error) {
+      process.stderr.write(`agentproc:error:${r.error}\n`);
+    }
+
+    process.exit(r.exitCode === 0 ? 0 : 1);
+  } catch (e) {
+    process.stderr.write(`error: ${e.message}\n`);
+    process.exit(1);
+  }
+}
+
+// Run main() only when invoked directly as a script, not when required for tests.
+if (require.main === module) {
+  main().catch(e => {
+    process.stderr.write(`[agentproc] unhandled error: ${e && (e.stack || e)}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { parseArgs, parseYaml, showHelp, main };

package/src/runner.js

@@ -0,0 +1,395 @@
+'use strict';
+/**
+ * AgentProc runner — the core engine that turns a profile + message into a
+ * 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.
+ *
+ * Responsibilities:
+ *   - Parse and validate a profile object
+ *   - Substitute {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}} placeholders
+ *   - Inject AGENT_* env vars + profile env block
+ *   - Spawn the agent command (no shell)
+ *   - Read stdout line by line, classify protocol lines vs reply body
+ *   - Forward AGENT_PARTIAL: in real time (via onPartial callback)
+ *   - Capture the last AGENT_SESSION: line (last-wins rule)
+ *   - Honor AGENT_ERROR: lines
+ *   - Enforce timeout_secs with SIGTERM → kill_grace_secs → SIGKILL
+ *   - Write message to stdin and close (when profile.stdin === 'message')
+ *   - Return { reply, sessionId, error, exitCode }
+ *
+ * Exports:
+ *   run(profile, options) -> Promise<RunResult>
+ *   parseProfileYaml(yamlString) -> Profile
+ *   classifyLine(line) -> { kind: 'session'|'partial'|'error'|'body', value }
+ */
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const os = require('node:os');
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const PROTOCOL_VERSION = '0.1';
+
+const DEFAULT_TIMEOUT_SECS = 1800;
+const DEFAULT_KILL_GRACE_SECS = 5;
+const DEFAULT_MAX_REPLY_CHARS = 8000;
+
+const PREFIX_SESSION = 'AGENT_SESSION:';
+const PREFIX_PARTIAL = 'AGENT_PARTIAL:';
+const PREFIX_ERROR = 'AGENT_ERROR:';
+
+// Exit codes per spec
+const EXIT_SUCCESS = 0;
+const EXIT_ERROR = 1;
+const EXIT_TIMEOUT = 124;
+const EXIT_SIGINT = 130;
+const EXIT_SIGTERM = 143;
+
+// ---------------------------------------------------------------------------
+// Profile parsing & validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate and normalize a profile object (the `agentproc:` block from YAML,
+ * already extracted by the caller — or a top-level profile for spec compatibility).
+ *
+ * @param {object} raw - Profile object.
+ * @returns {object} Normalized profile.
+ * @throws {Error} if required fields are missing or invalid.
+ */
+function normalizeProfile(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('profile must be an object');
+  }
+  // Accept either a top-level profile (spec form: command, args, ...)
+  // or a hub form ({ agentproc: { command, ... } }).
+  const p = raw.agentproc ? { ...raw.agentproc } : { ...raw };
+
+  if (typeof p.command !== 'string' || p.command.trim() === '') {
+    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) {
+    throw new Error('profile.command produced empty argv');
+  }
+
+  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 : {},
+    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,
+    max_reply_chars: Number.isFinite(p.max_reply_chars) ? p.max_reply_chars : DEFAULT_MAX_REPLY_CHARS,
+    streaming: p.streaming !== false,
+  };
+}
+
+function expandPath(p) {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+/**
+ * Substitute {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}} 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 || '');
+}
+
+/**
+ * Expand ${VAR} references against process.env, like a typical shell would.
+ * Unknown variables expand to empty string (POSIX sh behavior).
+ */
+function expandEnvRef(value, env) {
+  return String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+    const v = env[name];
+    return v !== undefined ? v : '';
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Line classification (per spec)
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to JSON-decode a value after a prefix.
+ * Lenient mode (default per spec): on failure, return the raw text.
+ */
+function decodeJsonValue(raw) {
+  const text = raw.trim();
+  if (text === '') return '';
+  try {
+    const v = JSON.parse(text);
+    return typeof v === 'string' ? v : String(v);
+  } catch {
+    // Lenient: treat as plain string.
+    return text;
+  }
+}
+
+/**
+ * Classify one stdout line.
+ * @param {string} line - Raw line, without trailing newline.
+ * @returns {{ kind: string, value: string }}
+ *   kind is 'session' | 'partial' | 'error' | 'body'.
+ */
+function classifyLine(line) {
+  // Per spec: bridges MAY match against the stripped line to be tolerant
+  // of leading whitespace from heredocs. We match the raw line — agents
+  // that want their text to NOT be a protocol line should prefix with space.
+  if (line.startsWith(PREFIX_SESSION)) {
+    return { kind: 'session', value: line.slice(PREFIX_SESSION.length).trim() };
+  }
+  if (line.startsWith(PREFIX_PARTIAL)) {
+    return { kind: 'partial', value: decodeJsonValue(line.slice(PREFIX_PARTIAL.length)) };
+  }
+  if (line.startsWith(PREFIX_ERROR)) {
+    return { kind: 'error', value: decodeJsonValue(line.slice(PREFIX_ERROR.length)) };
+  }
+  return { kind: 'body', value: line };
+}
+
+// ---------------------------------------------------------------------------
+// run() — the main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} RunOptions
+ * @property {string} message - User message (required).
+ * @property {string} [sessionId] - Session id from the previous turn (empty = new).
+ * @property {string} [sessionName] - Human-readable session name.
+ * @property {string} [fromUser] - Sender identifier.
+ * @property {boolean} [streaming] - Override profile.streaming.
+ * @property {Object<string, string>} [extraEnv] - Additional env vars (CLI --env).
+ * @property {string} [cwd] - Override profile.cwd (CLI --cwd).
+ * @property {number} [timeoutSecs] - Override profile.timeout_secs (CLI --timeout).
+ * @property {function(string): void} [onPartial] - Streaming callback.
+ * @property {function(string): void} [onSession] - Called when session id captured.
+ * @property {function(string): void} [onError] - Called on AGENT_ERROR:.
+ * @property {function(string): void} [onProtocolLine] - Raw protocol line (verbose/debug).
+ * @property {function(string): void} [onStderr] - Agent's stderr line.
+ * @property {boolean} [forwardStdin] - If true, write message to stdin (override profile.stdin).
+ */
+
+/**
+ * @typedef {Object} RunResult
+ * @property {string} reply - Concatenated reply body (non-protocol lines).
+ * @property {string} sessionId - Final session id (last AGENT_SESSION: wins; '' if none).
+ * @property {string} error - Error message from AGENT_ERROR:, or '' if none.
+ * @property {number} exitCode - Process exit code (124 = timeout, etc.).
+ * @property {boolean} timedOut - Whether the run was killed by timeout.
+ */
+
+/**
+ * Run an agent process per the AgentProc spec.
+ *
+ * @param {object} profileRaw - The profile (top-level form or hub `agentproc:` form).
+ * @param {RunOptions} options
+ * @returns {Promise<RunResult>}
+ */
+async function run(profileRaw, options) {
+  if (!options || typeof options.message !== 'string') {
+    throw new Error('options.message is required');
+  }
+
+  const profile = normalizeProfile(profileRaw);
+  const sessionId = options.sessionId || '';
+  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;
+
+  // Build the substitution context for {{MESSAGE}} etc.
+  const substCtx = {
+    message: options.message,
+    sessionId,
+    sessionName,
+  };
+
+  // Build argv: command + args (with placeholders substituted).
+  const argv = [...profile.argv];
+  for (const a of profile.args) {
+    argv.push(substitute(a, substCtx));
+  }
+
+  // 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 };
+  for (const [k, v] of Object.entries(profile.env)) {
+    env[k] = expandEnvRef(substitute(v, substCtx), process.env);
+  }
+  if (options.extraEnv) {
+    for (const [k, v] of Object.entries(options.extraEnv)) {
+      env[k] = String(v);
+    }
+  }
+
+  // Inject AGENT_* vars per spec.
+  env.AGENT_MESSAGE = options.message;
+  env.AGENT_SESSION_ID = sessionId;
+  env.AGENT_SESSION_NAME = sessionName;
+  env.AGENT_FROM_USER = options.fromUser || '';
+  env.AGENT_STREAMING = streaming ? '1' : '0';
+  env.AGENT_PROTOCOL_VERSION = PROTOCOL_VERSION;
+
+  // Spawn — no shell. Cwd optional.
+  const child = spawn(argv[0], argv.slice(1), {
+    cwd,
+    env,
+    stdio: [
+      profile.stdin === 'message' || options.forwardStdin ? 'pipe' : 'ignore',
+      'pipe',
+      'pipe',
+    ],
+  });
+
+  /** @type {RunResult} */
+  const result = {
+    reply: '',
+    sessionId: '',
+    error: '',
+    exitCode: 0,
+    timedOut: false,
+  };
+
+  const bodyLines = [];
+  let killed = false;
+
+  // ---- stdout: line-by-line classification ----
+  let stdoutBuf = '';
+  child.stdout.on('data', chunk => {
+    stdoutBuf += chunk.toString();
+    let nl;
+    while ((nl = stdoutBuf.indexOf('\n')) >= 0) {
+      const rawLine = stdoutBuf.slice(0, nl);
+      stdoutBuf = stdoutBuf.slice(nl + 1);
+      handleLine(rawLine);
+    }
+  });
+
+  function handleLine(rawLine) {
+    // Strip a trailing \r (CRLF tolerance) but otherwise treat raw.
+    const line = rawLine.replace(/\r$/, '');
+    const c = classifyLine(line);
+    if (c.kind === 'session') {
+      result.sessionId = c.value; // last wins
+      if (options.onSession) options.onSession(c.value);
+      if (options.onProtocolLine) options.onProtocolLine(line);
+    } else if (c.kind === 'partial') {
+      if (streaming && options.onPartial) options.onPartial(c.value);
+      if (options.onProtocolLine) options.onProtocolLine(line);
+    } else if (c.kind === 'error') {
+      result.error = c.value;
+      if (options.onError) options.onError(c.value);
+      if (options.onProtocolLine) options.onProtocolLine(line);
+    } else {
+      bodyLines.push(line);
+    }
+  }
+
+  // ---- stderr: forward as debug ----
+  let stderrBuf = '';
+  child.stderr.on('data', chunk => {
+    stderrBuf += chunk.toString();
+    let nl;
+    while ((nl = stderrBuf.indexOf('\n')) >= 0) {
+      const line = stderrBuf.slice(0, nl);
+      stderrBuf = stderrBuf.slice(nl + 1);
+      if (options.onStderr) options.onStderr(line.replace(/\r$/, ''));
+    }
+  });
+
+  // ---- stdin (if requested) ----
+  if (profile.stdin === 'message' || options.forwardStdin) {
+    child.stdin.write(options.message);
+    child.stdin.end();
+  }
+
+  // ---- timeout handling per spec: SIGTERM → grace → SIGKILL ----
+  let timer = null;
+  if (timeoutSecs > 0) {
+    timer = setTimeout(() => {
+      killed = true;
+      result.timedOut = true;
+      try { child.kill('SIGTERM'); } catch {}
+      setTimeout(() => {
+        try {
+          if (!child.exitCode && child.signalCode === null) {
+            child.kill('SIGKILL');
+          }
+        } catch {}
+      }, (profile.kill_grace_secs || DEFAULT_KILL_GRACE_SECS) * 1000);
+    }, timeoutSecs * 1000);
+  }
+
+  // ---- wait for exit ----
+  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}`);
+      resolve(EXIT_ERROR);
+    });
+  });
+
+  if (timer) clearTimeout(timer);
+
+  // Flush any remaining stdout buffer as a final line (without trailing \n).
+  if (stdoutBuf.length > 0) {
+    handleLine(stdoutBuf.replace(/\r$/, ''));
+  }
+
+  // Compose reply body.
+  result.reply = bodyLines.join('\n');
+  if (result.reply.length > profile.max_reply_chars) {
+    const suffix = profile.max_reply_chars === DEFAULT_MAX_REPLY_CHARS
+      ? '\n\n…(truncated)'
+      : '';
+    result.reply = result.reply.slice(0, profile.max_reply_chars) + suffix;
+  }
+
+  // Exit code per spec.
+  if (killed) {
+    result.exitCode = EXIT_TIMEOUT;
+  } else if (result.error) {
+    // AGENT_ERROR was emitted — treat as failure even if exit was 0.
+    result.exitCode = exitCode === 0 ? EXIT_ERROR : exitCode;
+  } else {
+    result.exitCode = exitCode;
+  }
+
+  return result;
+}
+
+module.exports = {
+  run,
+  normalizeProfile,
+  classifyLine,
+  decodeJsonValue,
+  substitute,
+  expandEnvRef,
+  expandPath,
+  PROTOCOL_VERSION,
+  DEFAULT_TIMEOUT_SECS,
+  DEFAULT_KILL_GRACE_SECS,
+  DEFAULT_MAX_REPLY_CHARS,
+  EXIT_SUCCESS,
+  EXIT_ERROR,
+  EXIT_TIMEOUT,
+  EXIT_SIGINT,
+  EXIT_SIGTERM,
+};

package/src/runner.test.js

@@ -0,0 +1,439 @@
+'use strict';
+/**
+ * Tests for runner.js — the AgentProc canonical bridge implementation.
+ *
+ * Run with: `node --test src/runner.test.js`
+ *
+ * Strategy:
+ *   1. Pure-function tests: classifyLine, decodeJsonValue, substitute,
+ *      normalizeProfile, expandEnvRef — no subprocess.
+ *   2. run() end-to-end tests: spawn a tiny bash/node helper script that
+ *      emits protocol lines, assert the runner classifies them correctly.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  run,
+  classifyLine,
+  decodeJsonValue,
+  substitute,
+  normalizeProfile,
+  expandEnvRef,
+  expandPath,
+  PROTOCOL_VERSION,
+} = require('./runner.js');
+
+// ---------------------------------------------------------------------------
+// 1. Pure-function tests
+// ---------------------------------------------------------------------------
+
+describe('classifyLine', () => {
+  test('identifies AGENT_SESSION:', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_SESSION:abc-123'), { kind: 'session', value: 'abc-123' });
+  });
+
+  test('strips whitespace from session id', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_SESSION:  abc-123  '), { kind: 'session', value: 'abc-123' });
+  });
+
+  test('identifies AGENT_PARTIAL: with JSON string', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_PARTIAL:"hello"'), { kind: 'partial', value: 'hello' });
+  });
+
+  test('AGENT_PARTIAL: with newline in JSON', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_PARTIAL:"line1\\nline2"'), { kind: 'partial', value: 'line1\nline2' });
+  });
+
+  test('AGENT_PARTIAL: lenient on bad JSON — treats as raw text', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_PARTIAL:not json'), { kind: 'partial', value: 'not json' });
+  });
+
+  test('AGENT_PARTIAL: empty value', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_PARTIAL:'), { kind: 'partial', value: '' });
+  });
+
+  test('identifies AGENT_ERROR:', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_ERROR:"rate limited"'), { kind: 'error', value: 'rate limited' });
+  });
+
+  test('AGENT_ERROR: lenient on bad JSON', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_ERROR:boom'), { kind: 'error', value: 'boom' });
+  });
+
+  test('body line: anything else', () => {
+    assert.deepStrictEqual(classifyLine('hello world'), { kind: 'body', value: 'hello world' });
+  });
+
+  test('body line: line starting with space is NOT a protocol line', () => {
+    // Per spec: agents that want their text to NOT be a protocol line should prefix with space.
+    assert.deepStrictEqual(classifyLine(' AGENT_SESSION:foo'), { kind: 'body', value: ' AGENT_SESSION:foo' });
+  });
+
+  test('body line: prefix-like but not exact prefix', () => {
+    assert.deepStrictEqual(classifyLine('AGENT_SESSION'), { kind: 'body', value: 'AGENT_SESSION' });
+  });
+});
+
+describe('decodeJsonValue', () => {
+  test('JSON string', () => {
+    assert.strictEqual(decodeJsonValue('"hi"'), 'hi');
+  });
+
+  test('JSON string with newline', () => {
+    assert.strictEqual(decodeJsonValue('"a\\nb"'), 'a\nb');
+  });
+
+  test('empty', () => {
+    assert.strictEqual(decodeJsonValue(''), '');
+  });
+
+  test('lenient: non-JSON returns trimmed raw', () => {
+    assert.strictEqual(decodeJsonValue('  not json  '), 'not json');
+  });
+
+  test('JSON number becomes string', () => {
+    assert.strictEqual(decodeJsonValue('42'), '42');
+  });
+});
+
+describe('substitute', () => {
+  test('replaces MESSAGE', () => {
+    assert.strictEqual(substitute('You said: {{MESSAGE}}', { message: 'hi' }), 'You said: hi');
+  });
+
+  test('replaces SESSION_ID', () => {
+    assert.strictEqual(substitute('s={{SESSION_ID}}', { sessionId: 'abc' }), 's=abc');
+  });
+
+  test('replaces SESSION_NAME', () => {
+    assert.strictEqual(substitute('n={{SESSION_NAME}}', { sessionName: 'work' }), 'n=work');
+  });
+
+  test('empty SESSION_ID when new session', () => {
+    assert.strictEqual(substitute('s={{SESSION_ID}}', { sessionId: '' }), 's=');
+  });
+
+  test('multiple placeholders', () => {
+    assert.strictEqual(
+      substitute('{{MESSAGE}} [{{SESSION_ID}}] ({{SESSION_NAME}})', {
+        message: 'hi', sessionId: 's1', sessionName: 'work',
+      }),
+      'hi [s1] (work)',
+    );
+  });
+});
+
+describe('expandEnvRef', () => {
+  test('expands ${VAR} from env', () => {
+    assert.strictEqual(expandEnvRef('${HOME}', { HOME: '/u/x' }), '/u/x');
+  });
+
+  test('unknown var → empty', () => {
+    assert.strictEqual(expandEnvRef('${NOPE}', {}), '');
+  });
+
+  test('no refs', () => {
+    assert.strictEqual(expandEnvRef('plain value', {}), 'plain value');
+  });
+
+  test('mixed', () => {
+    assert.strictEqual(
+      expandEnvRef('key=${HOME} and ${missing}', { HOME: '/h' }),
+      'key=/h and ',
+    );
+  });
+});
+
+describe('expandPath', () => {
+  test('~ expands to homedir', () => {
+    assert.strictEqual(expandPath('~'), os.homedir());
+  });
+
+  test('~/foo expands', () => {
+    assert.strictEqual(expandPath('~/foo'), path.join(os.homedir(), 'foo'));
+  });
+
+  test('absolute path unchanged', () => {
+    assert.strictEqual(expandPath('/usr/bin'), '/usr/bin');
+  });
+
+  test('relative path unchanged', () => {
+    assert.strictEqual(expandPath('./foo'), './foo');
+  });
+});
+
+describe('normalizeProfile', () => {
+  test('minimal valid profile', () => {
+    const p = normalizeProfile({ command: 'bash ./x.sh' });
+    assert.deepStrictEqual(p.argv, ['bash', './x.sh']);
+    assert.strictEqual(p.stdin, 'none');
+    assert.strictEqual(p.streaming, true);
+  });
+
+  test('hub form: profile nested under agentproc:', () => {
+    const p = normalizeProfile({ agentproc: { command: 'node ./x.js' } });
+    assert.deepStrictEqual(p.argv, ['node', './x.js']);
+  });
+
+  test('rejects missing command', () => {
+    assert.throws(() => normalizeProfile({}), /command must be a non-empty string/);
+  });
+
+  test('rejects empty command', () => {
+    assert.throws(() => normalizeProfile({ command: '   ' }), /command must be a non-empty string/);
+  });
+
+  test('rejects non-object', () => {
+    assert.throws(() => normalizeProfile(null), /must be an object/);
+  });
+
+  test('argv splits on whitespace, multiple spaces', () => {
+    const p = normalizeProfile({ command: 'bash    ./spaced.sh' });
+    assert.deepStrictEqual(p.argv, ['bash', './spaced.sh']);
+  });
+
+  test('args field defaults to empty array', () => {
+    const p = normalizeProfile({ command: 'x' });
+    assert.deepStrictEqual(p.args, []);
+  });
+
+  test('args field is preserved (cast to string)', () => {
+    const p = normalizeProfile({ command: 'x', args: ['--foo', 42] });
+    assert.deepStrictEqual(p.args, ['--foo', '42']);
+  });
+
+  test('cwd ~ is expanded', () => {
+    const p = normalizeProfile({ command: 'x', cwd: '~/proj' });
+    assert.strictEqual(p.cwd, path.join(os.homedir(), 'proj'));
+  });
+
+  test('stdin: message → message, anything else → none', () => {
+    assert.strictEqual(normalizeProfile({ command: 'x', stdin: 'message' }).stdin, 'message');
+    assert.strictEqual(normalizeProfile({ command: 'x', stdin: 'none' }).stdin, 'none');
+    assert.strictEqual(normalizeProfile({ command: 'x', stdin: 'bogus' }).stdin, 'none');
+    assert.strictEqual(normalizeProfile({ command: 'x' }).stdin, 'none');
+  });
+
+  test('streaming: false is honored, anything else true', () => {
+    assert.strictEqual(normalizeProfile({ command: 'x', streaming: false }).streaming, false);
+    assert.strictEqual(normalizeProfile({ command: 'x', streaming: true }).streaming, true);
+    assert.strictEqual(normalizeProfile({ command: 'x' }).streaming, true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. run() end-to-end tests with tiny agent scripts
+// ---------------------------------------------------------------------------
+
+function writeScript(content) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ap-runner-'));
+  const file = path.join(dir, 'agent.sh');
+  fs.writeFileSync(file, content, { mode: 0o755 });
+  return file;
+}
+
+describe('run() — end-to-end', () => {
+  test('simple reply body', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\necho "hello"\n');
+    const r = await run(
+      { command: agent },
+      { message: 'hi' },
+    );
+    assert.strictEqual(r.reply.trim(), 'hello');
+    assert.strictEqual(r.sessionId, '');
+    assert.strictEqual(r.error, '');
+    assert.strictEqual(r.exitCode, 0);
+  });
+
+  test('AGENT_SESSION: last wins', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\n' +
+      'echo "AGENT_SESSION:first"\n' +
+      'echo "AGENT_SESSION:second"\n' +
+      'echo "done"\n'
+    );
+    const r = await run({ command: agent }, { message: 'hi' });
+    assert.strictEqual(r.sessionId, 'second');
+    assert.strictEqual(r.reply.trim(), 'done');
+  });
+
+  test('AGENT_PARTIAL: triggers onPartial callback', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\n' +
+      'echo "AGENT_PARTIAL:\\"chunk1\\""\n' +
+      'echo "AGENT_PARTIAL:\\"chunk2\\""\n' +
+      'echo "final"\n'
+    );
+    const partials = [];
+    const r = await run(
+      { command: agent },
+      { message: 'hi', onPartial: (t) => partials.push(t) },
+    );
+    assert.deepStrictEqual(partials, ['chunk1', 'chunk2']);
+    assert.strictEqual(r.reply.trim(), 'final');
+  });
+
+  test('AGENT_PARTIAL: when streaming=false, onPartial NOT called', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\n' +
+      'echo "AGENT_PARTIAL:\\"chunk1\\""\n' +
+      'echo "final"\n'
+    );
+    const partials = [];
+    const r = await run(
+      { command: agent },
+      { message: 'hi', streaming: false, onPartial: (t) => partials.push(t) },
+    );
+    assert.deepStrictEqual(partials, []);
+    // partial lines are still NOT added to reply body (they're protocol lines)
+    assert.strictEqual(r.reply.trim(), 'final');
+  });
+
+  test('AGENT_ERROR: surfaces in result.error', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\n' +
+      'echo "AGENT_PARTIAL:\\"thinking...\\""\n' +
+      'echo "AGENT_ERROR:\\"rate limited\\""\n' +
+      'exit 1\n'
+    );
+    const r = await run({ command: agent }, { message: 'hi' });
+    assert.strictEqual(r.error, 'rate limited');
+    assert.strictEqual(r.exitCode, 1);
+  });
+
+  test('AGENT_ERROR: marks exit 1 even if process exits 0', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\n' +
+      'echo "AGENT_ERROR:\\"soft fail\\""\n' +
+      'exit 0\n'
+    );
+    const r = await run({ command: agent }, { message: 'hi' });
+    assert.strictEqual(r.error, 'soft fail');
+    assert.strictEqual(r.exitCode, 1);
+  });
+
+  test('reply body lines are NOT prefixed with protocol markers', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\n' +
+      'echo " AGENT_SESSION:foo"\n' +  // leading space → body
+      'echo "real reply"\n'
+    );
+    const r = await run({ command: agent }, { message: 'hi' });
+    assert.strictEqual(r.sessionId, '');
+    assert.strictEqual(r.reply.trim().split('\n').length, 2);
+  });
+
+  test('exit code propagates from agent', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\nexit 3\n');
+    const r = await run({ command: agent }, { message: 'hi' });
+    assert.strictEqual(r.exitCode, 3);
+  });
+
+  test('message is injected as AGENT_MESSAGE', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\necho "got: $AGENT_MESSAGE"\n');
+    const r = await run({ command: agent }, { message: 'payload' });
+    assert.strictEqual(r.reply.trim(), 'got: payload');
+  });
+
+  test('AGENT_SESSION_ID injected from options.sessionId', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\necho "prev: $AGENT_SESSION_ID"\n');
+    const r = await run({ command: agent }, { message: 'hi', sessionId: 'prev-123' });
+    assert.strictEqual(r.reply.trim(), 'prev: prev-123');
+  });
+
+  test('AGENT_PROTOCOL_VERSION injected', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\necho "pv=$AGENT_PROTOCOL_VERSION"\n');
+    const r = await run({ command: agent }, { message: 'hi' });
+    assert.strictEqual(r.reply.trim(), `pv=${PROTOCOL_VERSION}`);
+  });
+
+  test('AGENT_STREAMING reflects streaming option', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\necho "stream=$AGENT_STREAMING"\n');
+    const r1 = await run({ command: agent }, { message: 'hi' });
+    assert.strictEqual(r1.reply.trim(), 'stream=1');
+    const r2 = await run({ command: agent }, { message: 'hi', streaming: false });
+    assert.strictEqual(r2.reply.trim(), 'stream=0');
+  });
+
+  test('profile.env injects env vars with ${VAR} expansion', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\necho "MY_KEY=$MY_KEY"\n');
+    const r = await run(
+      { command: agent, env: { MY_KEY: '${HOME}' } },
+      { message: 'hi' },
+    );
+    assert.strictEqual(r.reply.trim(), `MY_KEY=${process.env.HOME}`);
+  });
+
+  test('{{MESSAGE}} placeholder in args', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\necho "args: $1"\n'
+    );
+    const r = await run(
+      { command: agent, args: ['{{MESSAGE}}'] },
+      { message: 'hello' },
+    );
+    assert.strictEqual(r.reply.trim(), 'args: hello');
+  });
+
+  test('extraEnv from options is applied', async () => {
+    const agent = writeScript('#!/usr/bin/env bash\necho "x=$X"\n');
+    const r = await run(
+      { command: agent },
+      { message: 'hi', extraEnv: { X: 'extra' } },
+    );
+    assert.strictEqual(r.reply.trim(), 'x=extra');
+  });
+
+  test('stdin: message — agent reads AGENT_MESSAGE from stdin', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\nread line\necho "stdin: $line"\n'
+    );
+    const r = await run(
+      { command: agent, stdin: 'message' },
+      { message: 'via-stdin' },
+    );
+    assert.strictEqual(r.reply.trim(), 'stdin: via-stdin');
+  });
+
+  test('timeout kills long-running agent', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\nsleep 30\necho "should not reach"\n'
+    );
+    const r = await run(
+      { command: agent, kill_grace_secs: 1 },
+      { message: 'hi', timeoutSecs: 1 },
+    );
+    assert.strictEqual(r.timedOut, true);
+    assert.strictEqual(r.exitCode, 124);
+  });
+
+  test('multiline reply body preserves newlines', async () => {
+    const agent = writeScript(
+      '#!/usr/bin/env bash\n' +
+      'echo "line 1"\n' +
+      'echo "line 2"\n' +
+      'echo "line 3"\n'
+    );
+    const r = await run({ command: agent }, { message: 'hi' });
+    // Lines are joined with \n; the trailing newline is the caller's responsibility
+    // (the CLI adds it when printing).
+    assert.strictEqual(r.reply, 'line 1\nline 2\nline 3');
+  });
+
+  test('spawn error (command not found) → exit 1', async () => {
+    const r = await run(
+      { command: '/nonexistent/command/xyz' },
+      { message: 'hi' },
+    );
+    assert.strictEqual(r.exitCode, 1);
+  });
+});
+
+test('PROTOCOL_VERSION is "0.1"', () => {
+  assert.strictEqual(PROTOCOL_VERSION, '0.1');
+});