agentproc 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentproc",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "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",
@@ -8,7 +8,7 @@
     "agentproc": "src/cli.js"
   },
   "scripts": {
-    "test": "node --test src/index.test.js src/runner.test.js"
+    "test": "node --test src/index.test.js src/runner.test.js src/hub.test.js src/conformance.test.js"
   },
   "keywords": ["agentproc", "agent", "bridge", "protocol", "cli", "ai", "runner"],
   "license": "MIT",

package/src/cli.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 'use strict';
 /**
- * agentproc CLI — run any AgentProc profile against a message.
+ * agentproc CLI — drive any AgentProc profile against a message.
  *
- * Usage:
+ * Quick start (hub):
+ *   agentproc hub list
+ *   agentproc hub run echo-agent -p "hello"
+ *   cd ~/projects/my-app && agentproc hub run claude-code -p "explain this"
+ *
+ * Advanced (local profile YAML, no hub fetch):
  *   agentproc --profile <path.yaml> --prompt "hello" [options]
  *
- * Options:
+ * Options (local-profile mode):
  *   --profile, -p <path>      Profile YAML path (required)
  *   --prompt <text>           User message (required, unless --stdin)
  *   --session <id>            Previous session id for multi-turn
@@ -41,6 +46,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const runner = require('./runner.js');
+const hub = require('./hub.js');
 const { PROTOCOL_VERSION } = runner;
 
 const PKG_VERSION = require('../package.json').version;
@@ -57,7 +63,7 @@ function parseArgs(argv) {
     sessionName: 'default',
     from: '',
     cwd: null,
-    env: {},
+    env: [],  // array of "KEY=VALUE" strings; --env can repeat
     timeout: null,
     stream: true,
     verbose: true,
@@ -83,20 +89,21 @@ function parseArgs(argv) {
       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);
+      case '--env':
+        opts.env.push(next());
         break;
-      }
       case '--timeout': opts.timeout = parseInt(next(), 10); break;
-      case '--no-stream': opts.stream = false; break;
+      case '--no-stream': opts.noStream = true; 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 === 'hub' && extras.length === 0) {
+          opts.hub = true;
+          opts.hubArgs = argv.slice(i + 1);
+          return { opts, extras };
+        }
         if (a.startsWith('--')) throw new Error(`unknown option: ${a}`);
         extras.push(a);
     }
@@ -104,9 +111,288 @@ function parseArgs(argv) {
   return { opts, extras };
 }
 
+// ---------------------------------------------------------------------------
+// Hub subcommand dispatcher
+// ---------------------------------------------------------------------------
+
+async function runHubSubcommand(args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    showHubHelp();
+    return 0;
+  }
+
+  // Any subcommand with --help/-h shows the hub help (covers `hub run --help`,
+  // `hub install --help`, etc. — useful for muscle-memory discovery).
+  if (rest.includes('--help') || rest.includes('-h')) {
+    showHubHelp();
+    return 0;
+  }
+
+  // Parse hub args. We can't reuse parseArgs() here because it throws on
+  // any unknown `--flag`, and hub supports `--refresh` which the runner
+  // parser doesn't know about. Instead, walk the args ourselves, separating
+  // hub-level flags (--refresh, --help) from runner-level flags (-p/--prompt,
+  // --cwd, --env, ...) and positional args (the profile name).
+  const refresh = rest.includes('--refresh');
+  const positional = [];
+  const runnerArgs = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--refresh' || a === '-h' || a === '--help') continue;
+    // Runner flags that take a value (next arg): match both long and short.
+    // In the `hub run` context, `-p` means `--prompt` (the profile name is
+    // positional, not a path), so we normalize it before handing off.
+    const takesValue =
+      a === '--prompt' || a === '-p' ||
+      a === '--session' || a === '--session-name' || a === '--from' ||
+      a === '--cwd' || a === '--env' || a === '--timeout';
+    if (takesValue) {
+      runnerArgs.push(a === '-p' ? '--prompt' : a);
+      if (i + 1 < rest.length) runnerArgs.push(rest[++i]);
+      continue;
+    }
+    // Other known runner flags (boolean).
+    if (a === '--no-stream' || a === '--verbose' || a === '--quiet' ||
+        a === '--raw' || a === '--stdin') {
+      runnerArgs.push(a);
+      continue;
+    }
+    // Anything else starting with - or -- is unknown to us — surface it
+    // as an explicit error instead of silently treating it as a positional.
+    if (a.startsWith('-')) {
+      process.stderr.write(`error: unknown option: ${a}\n\n`);
+      showHubHelp();
+      return 2;
+    }
+    positional.push(a);
+  }
+
+  if (sub === 'list') {
+    const profiles = await hub.listProfiles({
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    process.stdout.write('Available profiles in the official hub:\n\n');
+    for (const p of profiles) {
+      process.stdout.write(
+        `  ${p.name.padEnd(15)} ${p.tested.padEnd(12)} ${p.description.slice(0, 60)}\n`
+      );
+    }
+    process.stdout.write(`\nRun \`agentproc hub run <name> -p "hi"\` to use one.\n`);
+    return 0;
+  }
+
+  if (sub === 'show') {
+    if (!positional[0]) {
+      process.stderr.write('error: hub show requires a profile name\n');
+      return 2;
+    }
+    const readme = await hub.showReadme(positional[0], {
+      refresh,
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    process.stdout.write(readme);
+    if (!readme.endsWith('\n')) process.stdout.write('\n');
+    return 0;
+  }
+
+  if (sub === 'install') {
+    if (!positional[0]) {
+      process.stderr.write('error: hub install requires a profile name\n');
+      return 2;
+    }
+    const target = process.cwd();
+    const dest = await hub.installProfile(positional[0], target, {
+      refresh,
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    // After-the-fact hint: tell the user exactly what they got and how to
+    // run it. Without this, "installed to: ./echo-agent/" leaves them
+    // guessing what to type next.
+    process.stderr.write(`\n`);
+    process.stderr.write(`Next: edit ${path.relative(target, path.join(dest, 'profile.yaml'))} if you want, then run:\n`);
+    process.stderr.write(`  agentproc --profile ${path.relative(target, path.join(dest, 'profile.yaml'))} --prompt "hi" --cwd <your-project>\n`);
+    return 0;
+  }
+
+  if (sub === 'run') {
+    if (!positional[0]) {
+      process.stderr.write('error: hub run requires a profile name\n');
+      return 2;
+    }
+    const profileName = positional[0];
+    const cacheDir = await hub.fetchProfile(profileName, {
+      refresh,
+      onLog: m => process.stderr.write(m + '\n'),
+    });
+    const profilePath = path.join(cacheDir, 'profile.yaml');
+
+    // Parse the runner-level flags we separated out above.
+    const { opts: runOpts } = parseArgs(runnerArgs);
+    if (!runOpts.prompt && !runOpts.stdin) {
+      process.stderr.write('error: hub run requires --prompt <text> or --stdin\n');
+      return 2;
+    }
+
+    // hub run uses the user's current directory as the agent's cwd when
+    // --cwd is not given. This matches the hub docs ("uses your current
+    // directory as cwd") and is the right default for AI-CLI profiles
+    // where the agent should operate on the user's project.
+    if (!runOpts.cwd) {
+      runOpts.cwd = process.cwd();
+    }
+
+    return await runAgent(profilePath, runOpts);
+  }
+
+  process.stderr.write(`error: unknown hub subcommand: ${sub}\n\n`);
+  showHubHelp();
+  return 2;
+}
+
+function showHubHelp() {
+  process.stdout.write(`agentproc hub — manage profiles from the official Hub
+
+Usage:
+  agentproc hub list                       List all profiles in the hub
+  agentproc hub show <name>                Show a profile's README
+  agentproc hub install <name>             Copy a profile to the current directory
+  agentproc hub run <name> [run-options]   Fetch (if needed) and run a profile
+
+Hub run options (same as the regular --profile runner):
+  -p, --prompt <text>          User message (or use --stdin)
+  --cwd <path>                 Override profile.cwd (default: current dir)
+  --env KEY=VALUE              Extra env var (repeatable)
+  --session <id>               Previous session id for multi-turn
+  --timeout <secs>             Override profile.timeout_secs
+  --no-stream                  Disable streaming
+  --verbose / --quiet          Protocol line visibility (default: verbose)
+  --stdin                      Read prompt from stdin
+
+Common options:
+  --refresh                    Force re-fetch from GitHub (ignore cache)
+  -h, --help                   Show this help
+
+Examples:
+  agentproc hub list
+  agentproc hub run echo-agent -p "hello"
+  cd ~/projects/my-app && agentproc hub run claude-code -p "explain this" --env ANTHROPIC_API_KEY=$KEY
+  agentproc hub show codex
+  agentproc hub install agy
+
+Profiles are cached at ~/.agentproc/cache/hub/<name>/ (24h TTL).
+`);
+}
+
+/**
+ * Shared runner logic used by both `agentproc --profile` and `agentproc hub run`.
+ * Kept here for the hub subcommand to reuse; the legacy main() path also calls it.
+ */
+async function runAgent(profilePath, opts) {
+  let profileRaw;
+  const profileDir = path.dirname(path.resolve(profilePath));
+  try {
+    const yamlText = fs.readFileSync(path.resolve(profilePath), 'utf8');
+    profileRaw = parseYaml(yamlText);
+  } catch (e) {
+    process.stderr.write(`error: failed to read profile ${profilePath}: ${e.message}\n`);
+    return 2;
+  }
+
+  // Read prompt.
+  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');
+    return 2;
+  }
+
+  // opts.env is an array of "KEY=VALUE" strings (from repeated --env flags)
+  const extraEnv = {};
+  for (const kv of opts.env || []) {
+    const eq = kv.indexOf('=');
+    if (eq < 0) {
+      process.stderr.write(`error: --env expects KEY=VALUE, got: ${kv}\n`);
+      return 2;
+    }
+    extraEnv[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+
+  const streaming = opts.noStream ? false : null;
+
+  if (opts.raw) {
+    const r = await runner.run(profileRaw, {
+      message: prompt,
+      sessionId: opts.session || '',
+      sessionName: opts.sessionName || 'default',
+      fromUser: opts.from || '',
+      streaming,
+      cwd: opts.cwd,
+      profileDir,
+      extraEnv,
+      timeoutSecs: opts.timeout,
+    });
+    process.stdout.write(r.reply);
+    if (r.reply && !r.reply.endsWith('\n')) process.stdout.write('\n');
+    return r.exitCode === 0 ? 0 : 1;
+  }
+
+  // verbose: default true, --verbose keeps it true, --quiet sets it false.
+  const verbose = opts.verbose !== false;
+
+  const r = await runner.run(profileRaw, {
+    message: prompt,
+    sessionId: opts.session || '',
+    sessionName: opts.sessionName || 'default',
+    fromUser: opts.from || '',
+    streaming,
+    cwd: opts.cwd,
+    profileDir,
+    extraEnv,
+    timeoutSecs: opts.timeout,
+    onPartial: (t) => { if (verbose) process.stderr.write(`AGENT_PARTIAL:${JSON.stringify(t)}\n`); },
+    onSession: (id) => { if (verbose) process.stderr.write(`AGENT_SESSION:${id}\n`); },
+    onError: (msg) => { if (verbose) process.stderr.write(`AGENT_ERROR:${JSON.stringify(msg)}\n`); },
+    onStderr: (line) => { if (verbose) process.stderr.write(`[agent stderr] ${line}\n`); },
+  });
+
+  if (r.reply) {
+    process.stdout.write(r.reply);
+    if (!r.reply.endsWith('\n')) process.stdout.write('\n');
+  }
+  if (r.sessionId) process.stderr.write(`agentproc:session:${r.sessionId}\n`);
+  if (r.error) process.stderr.write(`agentproc:error:${r.error}\n`);
+  return r.exitCode === 0 ? 0 : 1;
+}
+
 function showHelp() {
   process.stdout.write(`agentproc v${PKG_VERSION} (protocol ${PROTOCOL_VERSION})
 
+The fastest way in:
+  agentproc hub list                          # see what's available
+  agentproc hub run echo-agent -p "hello"     # smoke test (no API key)
+  cd ~/projects/my-app && agentproc hub run claude-code -p "explain this"
+
+The CLI fetches the profile from the GitHub hub on first use, caches it at
+~/.agentproc/cache/hub/<name>/ (24h TTL), and uses your current directory as
+the agent's cwd. Set GITHUB_TOKEN to raise the rate limit (see \`agentproc hub --help\`).
+
+Hub subcommands:
+  hub list                          List all profiles in the hub
+  hub show <name>                   Show a profile's README
+  hub run <name> [run-options]      Fetch (if needed) and run a profile
+  hub install <name>                Copy a profile to the current directory
+
+Run \`agentproc hub --help\` for the full hub reference.
+
+───────────────────────────────────────────────────────────────────────────────
+
+Advanced: run a local profile YAML directly (no hub fetch)
+
 Usage:
   agentproc --profile <path.yaml> --prompt "hello" [options]
 
@@ -120,7 +406,8 @@ Session:
   --from <user>             Sender identifier
 
 Execution:
-  --cwd <path>              Override profile.cwd
+  --cwd <path>              Override profile.cwd (relative paths resolve
+                            against the profile.yaml's directory)
   --env KEY=VALUE           Extra env var (repeatable)
   --timeout <secs>          Override profile.timeout_secs
   --no-stream               Set AGENT_STREAMING=0
@@ -143,9 +430,16 @@ Output semantics:
 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
+  # Local profile (relative cwd resolves next to profile.yaml):
+  agentproc --profile ./hub/echo-agent/profile.yaml --prompt "hi"
+
+  # Local claude-code profile, claude runs against your project:
+  agentproc --profile ./hub/claude-code/profile.yaml \\
+            --prompt "explain this codebase" \\
+            --cwd /path/to/your/project
+
+  # Prompt from stdin:
+  cat prompt.txt | agentproc --profile prof.yaml --stdin
 `);
 }
 
@@ -392,6 +686,11 @@ async function main() {
   if (opts.help) { showHelp(); process.exit(0); }
   if (opts.version) { showVersion(); process.exit(0); }
 
+  // `agentproc hub <subcommand>` — defer to hub dispatcher.
+  if (opts.hub) {
+    return await runHubSubcommand(opts.hubArgs);
+  }
+
   if (!opts.profile) {
     process.stderr.write('error: --profile is required\n\n');
     showHelp();
@@ -408,98 +707,46 @@ async function main() {
     process.exit(2);
   }
 
-  // Read & parse profile YAML.
-  let profileRaw;
+  // Read & parse profile YAML, then delegate to the shared runner path.
   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);
+    return await runAgent(opts.profile, opts);
   } catch (e) {
     process.stderr.write(`error: ${e.message}\n`);
-    process.exit(1);
+    return 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);
-  });
+  main().then(
+    (code) => {
+      // main() returns an explicit exit code from its various return paths;
+      // honor it so shell scripts can distinguish success from failure.
+      process.exit(typeof code === 'number' ? code : 0);
+    },
+    (e) => {
+      // Friendly handling for known hub errors: print the message + remediation
+      // hint, never a raw Node stack trace.
+      if (e && e.name === 'HubError') {
+        process.stderr.write(`error: ${e.message}\n`);
+        if (e.hint) process.stderr.write(`\n${e.hint}\n`);
+        process.exit(1);
+        return;
+      }
+      // For fetch() network errors wrapped by hub.js (also HubError, but be
+      // defensive in case some path throws a plain TypeError from fetch).
+      if (e && typeof e.message === 'string' && /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET/.test(e.message)) {
+        process.stderr.write(`error: network error talking to GitHub: ${e.message}\n`);
+        process.stderr.write(`\nThis is usually transient. Re-run the command, or run against a local checkout:\n`);
+        process.stderr.write(`  agentproc --profile ./hub/<name>/profile.yaml --prompt "hi"\n`);
+        process.exit(1);
+        return;
+      }
+      // Everything else: still avoid dumping the stack. Show the message only.
+      process.stderr.write(`error: ${e && (e.message || e)}\n`);
+      process.exit(1);
+    }
+  );
 }
 
 module.exports = { parseArgs, parseYaml, showHelp, main };

package/src/conformance.test.js

@@ -0,0 +1,29 @@
+'use strict';
+/**
+ * Cross-implementation conformance tests.
+ *
+ * Drives the shared `spec/conformance/cases.json` fixture through the Node
+ * runner's `classifyLine` and asserts the result matches the expected
+ * {kind, value}. The Python SDK runs the same fixture through its
+ * `classify_line` in `sdk/python/tests/test_conformance.py` — together they
+ * guarantee the two reference implementations classify stdout identically.
+ *
+ * When you change the spec's line-recognition rules, add a case to the JSON
+ * file first; both SDKs will fail until they agree.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { classifyLine } = require('./runner.js');
+
+const CASES_PATH = path.resolve(__dirname, '../../../spec/conformance/cases.json');
+const data = JSON.parse(fs.readFileSync(CASES_PATH, 'utf8'));
+
+for (const c of data.cases) {
+  test(`classifyLine: ${c.line.slice(0, 60)}`, () => {
+    assert.deepStrictEqual(classifyLine(c.line), c.expect);
+  });
+}