@evomap/evolver 1.69.16 → 1.69.19

package/assets/gep/candidates.jsonl

@@ -1,3 +1,6 @@
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-22T11:22:20.060Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-22T11:22:21.928Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-22T11:22:23.784Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:00:44.714Z","signals":["bounty_task","external_task","human","new","very","grow","how","memory_missing","user_missing","session_logs_missing"],"tags":["bounty_task","external_task","human","new","very","grow","how","memory_missing","user_missing","session_logs_missing","area:orchestration","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: bounty_task, external_task, human, new, very, grow, how, memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:00:46.677Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:00:48.536Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:01:00.086Z","signals":["bounty_task","external_task","mismatch","components","server","react","troubleshooting","dynamic routes","hydration","React Server Components","memory_missing","user_missing","session_logs_missing"],"tags":["bounty_task","external_task","mismatch","components","server","react","troubleshooting","dynamic routes","hydration","React Server Components","memory_missing","user_missing","session_logs_missing","area:orchestration","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: bounty_task, external_task, mismatch, components, server, react, troubleshooting, dynamic routes, hydration, React Server Components, memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:01:02.498Z","signals":["bounty_task","external_task","mismatch","components","server","react","troubleshooting","dynamic routes","hydration","React Server Components","memory_missing","user_missing","session_logs_missing"],"tags":["bounty_task","external_task","mismatch","components","server","react","troubleshooting","dynamic routes","hydration","React Server Components","memory_missing","user_missing","session_logs_missing","area:orchestration","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: bounty_task, external_task, mismatch, components, server, react, troubleshooting, dynamic routes, hydration, React Server Components, memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:01:04.594Z","signals":["bounty_task","external_task","what","understand","really","dont","explanation.","memory_missing","user_missing","session_logs_missing"],"tags":["bounty_task","external_task","what","understand","really","dont","explanation.","memory_missing","user_missing","session_logs_missing","area:orchestration","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: bounty_task, external_task, what, understand, really, dont, explanation., memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}

package/index.js

@@ -248,6 +248,26 @@ async function main() {
           console.warn('[ATP] Auto-init failed: ' + (atpInitErr && atpInitErr.message || atpInitErr));
         }
 
+        // ATP: opt-in capability-gap auto-buyer (default OFF, must be explicitly enabled).
+        try {
+          const autoBuyRaw = (process.env.EVOLVER_ATP_AUTOBUY || 'off').toLowerCase().trim();
+          const autoBuyOn = autoBuyRaw === 'on' || autoBuyRaw === '1' || autoBuyRaw === 'true';
+          if (autoBuyOn) {
+            const hubUrl = process.env.A2A_HUB_URL || process.env.EVOMAP_HUB_URL || '';
+            if (hubUrl) {
+              const { autoBuyer } = require('./src/atp');
+              autoBuyer.start({
+                dailyCap: Number(process.env.ATP_AUTOBUY_DAILY_CAP_CREDITS) || undefined,
+                perOrderCap: Number(process.env.ATP_AUTOBUY_PER_ORDER_CAP_CREDITS) || undefined,
+              });
+            } else {
+              console.warn('[ATP-AutoBuyer] EVOLVER_ATP_AUTOBUY=on but no hub URL configured, skipping.');
+            }
+          }
+        } catch (autoBuyInitErr) {
+          console.warn('[ATP-AutoBuyer] Init failed: ' + (autoBuyInitErr && autoBuyInitErr.message || autoBuyInitErr));
+        }
+
         // Hoist module refs used inside the loop to avoid repeated module lookups per cycle
         const idleScheduler = require('./src/gep/idleScheduler');
         const { shouldDistillFromFailures: shouldDF, autoDistillFromFailures: autoDF } = require('./src/gep/skillDistiller');
@@ -932,8 +952,36 @@ async function main() {
       process.exit(1);
     }
 
+  } else if (command === 'buy' || command === 'orders' || command === 'verify') {
+    try {
+      const atpCli = require('./src/atp/cli');
+      const subArgs = args.slice(); // args already exclude the command token
+      let parsed;
+      let runner;
+      if (command === 'buy') {
+        parsed = atpCli.parseBuyArgs(subArgs);
+        runner = atpCli.runBuy;
+      } else if (command === 'orders') {
+        parsed = atpCli.parseOrdersArgs(subArgs);
+        runner = atpCli.runOrders;
+      } else {
+        parsed = atpCli.parseVerifyArgs(subArgs);
+        runner = atpCli.runVerify;
+      }
+      if (!parsed.ok) {
+        console.error('[ATP] ' + parsed.error);
+        console.error(atpCli.printUsage());
+        process.exit(2);
+      }
+      const res = await runner(parsed.opts);
+      process.exit(res && typeof res.exitCode === 'number' ? res.exitCode : 0);
+    } catch (atpCliErr) {
+      console.error('[ATP] CLI error:', atpCliErr && atpCliErr.message || atpCliErr);
+      process.exit(1);
+    }
+
   } else {
-    console.log(`Usage: node index.js [run|/evolve|solidify|review|distill|fetch|asset-log|setup-hooks] [--loop]
+    console.log(`Usage: node index.js [run|/evolve|solidify|review|distill|fetch|asset-log|setup-hooks|buy|orders|verify] [--loop]
   - fetch flags:
     - --skill=<id> | -s <id>   (skill ID to download)
     - --out=<dir>              (output directory, default: ./skills/<skill_id>)
@@ -958,6 +1006,22 @@ async function main() {
     - --since=<ISO_date>       (entries after date)
     - --json                   (raw JSON output)
 
+  ATP (Agent Transaction Protocol) subcommands:
+  - buy <caps>                 (place an ATP order; caps is comma-separated)
+    - --budget=<N>             (credits to spend, default 10)
+    - --question="..."         (order description)
+    - --routing=<mode>         (fastest|cheapest|auction|swarm, default fastest)
+    - --verify=<mode>          (auto|ai_judge|bilateral, default auto)
+    - --no-wait                (return immediately after placing)
+    - --timeout=<seconds>      (lifecycle timeout, default 300)
+  - orders                     (list your recent ATP orders / deliveries)
+    - --role=consumer|merchant (default consumer)
+    - --status=pending|verified|disputed|settled
+    - --limit=<N>              (1..100, default 20)
+    - --json                   (raw JSON)
+  - verify <orderId>           (confirm delivery or trigger AI judge)
+    - --action=confirm|ai_judge (default confirm)
+
 Validator role (decentralized validation, default ON since v1.69.0):
   - EVOLVER_VALIDATOR_ENABLED=0    opt out (env beats persisted flag and default)
   - EVOLVER_VALIDATOR_ENABLED=1    explicitly opt in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver",
-  "version": "1.69.16",
+  "version": "1.69.19",
   "description": "A GEP-powered self-evolution engine for AI agents. Features automated log analysis and Genome Evolution Protocol (GEP) for auditable, reusable evolution assets.",
   "main": "index.js",
   "bin": {

package/src/atp/autoBuyer.js

@@ -0,0 +1,242 @@
+// ATP Auto-Buyer (opt-in)
+// Converts capability gaps into ATP orders with strict budget caps and
+// 24h question-level deduplication. Default OFF; enabled by setting
+// EVOLVER_ATP_AUTOBUY=on (also accepts 1/true). Budget caps:
+//   ATP_AUTOBUY_DAILY_CAP_CREDITS     (default 50)
+//   ATP_AUTOBUY_PER_ORDER_CAP_CREDITS (default 10)
+// Cold-start safety: the first 5 minutes after process start use a half-cap
+// to protect against misconfiguration loops on restart storms.
+//
+// Integration contract:
+//   1) Call start({ dailyCap, perOrderCap }) once when EVOLVER_ATP_AUTOBUY=on.
+//   2) Call considerOrder({ signals, question, capabilities, budget, ... })
+//      from the evolve loop whenever a capability gap is detected.
+//   3) Result shape: { ok, skipped?, reason?, data?, error? }.
+//
+// Failure modes are non-fatal; every external call is wrapped with a 3s
+// timeout race so loop cadence is never blocked by network issues.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { getMemoryDir } = require('../gep/paths');
+const hubClient = require('./hubClient');
+
+const DEFAULT_DAILY_CAP = 50;
+const DEFAULT_PER_ORDER_CAP = 10;
+const DEFAULT_ORDER_TIMEOUT_MS = 3000;
+const COLD_START_WINDOW_MS = 5 * 60 * 1000;
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const LEDGER_FILENAME = 'atp-autobuyer-ledger.json';
+
+let _started = false;
+let _startedAt = 0;
+let _config = {
+  dailyCap: DEFAULT_DAILY_CAP,
+  perOrderCap: DEFAULT_PER_ORDER_CAP,
+  timeoutMs: DEFAULT_ORDER_TIMEOUT_MS,
+};
+
+function _ledgerPath() {
+  return path.join(getMemoryDir(), LEDGER_FILENAME);
+}
+
+function _todayKey(now) {
+  const d = new Date(typeof now === 'number' ? now : Date.now());
+  return d.toISOString().slice(0, 10); // UTC YYYY-MM-DD
+}
+
+function _isEnabled() {
+  const raw = (process.env.EVOLVER_ATP_AUTOBUY || 'off').toLowerCase().trim();
+  return raw === 'on' || raw === '1' || raw === 'true';
+}
+
+function _emptyLedger() {
+  return { version: 1, dayKey: _todayKey(), spent: 0, dedup: {} };
+}
+
+function _readLedger() {
+  try {
+    const p = _ledgerPath();
+    if (!fs.existsSync(p)) return _emptyLedger();
+    const raw = fs.readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return _emptyLedger();
+    if (!parsed.dayKey || !parsed.dedup) return _emptyLedger();
+    return parsed;
+  } catch (_) {
+    return _emptyLedger();
+  }
+}
+
+function _writeLedger(ledger) {
+  try {
+    const dir = getMemoryDir();
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = _ledgerPath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(ledger, null, 2));
+    fs.renameSync(tmp, _ledgerPath());
+  } catch (_) {
+    // Non-fatal: ledger persistence failure means next process restart
+    // re-reads previous ledger (so existing caps still apply).
+  }
+}
+
+function _rotateIfNewDay(ledger, now) {
+  const today = _todayKey(now);
+  if (ledger.dayKey !== today) {
+    return { version: 1, dayKey: today, spent: 0, dedup: ledger.dedup || {} };
+  }
+  return ledger;
+}
+
+function _pruneDedup(ledger, now) {
+  const cutoff = (typeof now === 'number' ? now : Date.now()) - DEDUP_TTL_MS;
+  const out = {};
+  const src = ledger.dedup || {};
+  const keys = Object.keys(src);
+  for (let i = 0; i < keys.length; i++) {
+    const k = keys[i];
+    if (typeof src[k] === 'number' && src[k] >= cutoff) out[k] = src[k];
+  }
+  ledger.dedup = out;
+  return ledger;
+}
+
+function _questionHash(opts) {
+  const caps = Array.isArray(opts.capabilities) ? opts.capabilities.slice().sort().join(',') : '';
+  const q = (opts.question || '').slice(0, 2000);
+  return crypto.createHash('sha256').update(caps + '|' + q).digest('hex').slice(0, 24);
+}
+
+function _effectiveCap(value, now) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  const within = _startedAt > 0 && (now - _startedAt) < COLD_START_WINDOW_MS;
+  return within ? Math.floor(n / 2) : Math.floor(n);
+}
+
+function start(opts) {
+  if (_started) return;
+  if (!_isEnabled()) return;
+  _started = true;
+  _startedAt = Date.now();
+  const dailyCap = Math.max(0, Math.floor(Number((opts && opts.dailyCap) || process.env.ATP_AUTOBUY_DAILY_CAP_CREDITS) || DEFAULT_DAILY_CAP));
+  const perOrderCap = Math.max(0, Math.floor(Number((opts && opts.perOrderCap) || process.env.ATP_AUTOBUY_PER_ORDER_CAP_CREDITS) || DEFAULT_PER_ORDER_CAP));
+  const timeoutMs = Math.max(500, Math.floor(Number((opts && opts.timeoutMs) || DEFAULT_ORDER_TIMEOUT_MS)));
+  _config = { dailyCap, perOrderCap, timeoutMs };
+  let ledger = _readLedger();
+  ledger = _rotateIfNewDay(ledger, _startedAt);
+  ledger = _pruneDedup(ledger, _startedAt);
+  _writeLedger(ledger);
+  console.log('[ATP-AutoBuyer] Started (dailyCap=' + dailyCap + ', perOrderCap=' + perOrderCap + ', cold-start half-cap for ' + (COLD_START_WINDOW_MS / 1000) + 's)');
+}
+
+function stop() {
+  _started = false;
+  _startedAt = 0;
+}
+
+function isStarted() {
+  return _started;
+}
+
+function _withTimeout(promise, timeoutMs) {
+  return Promise.race([
+    promise,
+    new Promise(function (resolve) {
+      setTimeout(function () { resolve({ ok: false, error: 'autobuyer_timeout' }); }, timeoutMs);
+    }),
+  ]);
+}
+
+async function considerOrder(opts) {
+  if (!_started) return { ok: false, skipped: true, reason: 'not_started' };
+  if (!opts || !Array.isArray(opts.capabilities) || opts.capabilities.length === 0) {
+    return { ok: false, skipped: true, reason: 'no_capabilities' };
+  }
+  const now = Date.now();
+  let ledger = _readLedger();
+  ledger = _rotateIfNewDay(ledger, now);
+  ledger = _pruneDedup(ledger, now);
+
+  const hash = _questionHash(opts);
+  if (ledger.dedup[hash]) {
+    return { ok: false, skipped: true, reason: 'dedup_hit', hash: hash };
+  }
+
+  const dailyCap = _effectiveCap(_config.dailyCap, now);
+  const perOrderCap = _effectiveCap(_config.perOrderCap, now);
+  const remaining = Math.max(0, dailyCap - (ledger.spent || 0));
+  if (remaining <= 0) {
+    console.warn('[ATP-AutoBuyer] Daily cap reached, skipping order (spent=' + ledger.spent + ', cap=' + dailyCap + ')');
+    return { ok: false, skipped: true, reason: 'daily_cap_reached', spent: ledger.spent, cap: dailyCap };
+  }
+
+  const requested = Math.max(1, Math.floor(Number(opts.budget) || perOrderCap));
+  const budget = Math.min(requested, perOrderCap, remaining);
+  if (budget <= 0) {
+    return { ok: false, skipped: true, reason: 'budget_clamped_to_zero' };
+  }
+
+  const orderOpts = {
+    capabilities: opts.capabilities,
+    budget: budget,
+    routingMode: opts.routingMode || 'fastest',
+    verifyMode: opts.verifyMode || 'auto',
+    question: opts.question,
+    signals: opts.signals,
+    minReputation: opts.minReputation,
+  };
+
+  const result = await _withTimeout(hubClient.placeOrder(orderOpts), _config.timeoutMs);
+
+  if (result && result.ok) {
+    ledger.spent = (ledger.spent || 0) + budget;
+    ledger.dedup[hash] = now;
+    _writeLedger(ledger);
+    console.log('[ATP-AutoBuyer] Order placed: ' + (result.data && result.data.order_id) + ' budget=' + budget + ' remaining_today=' + Math.max(0, dailyCap - ledger.spent));
+    return { ok: true, data: result.data, spent: budget };
+  }
+
+  // On failure still record dedup so we don't hammer the hub for the same
+  // capability gap within the TTL window (but do NOT charge the spend).
+  ledger.dedup[hash] = now;
+  _writeLedger(ledger);
+  return { ok: false, error: (result && result.error) || 'unknown_error' };
+}
+
+// Test-only reset, not exported by default.
+function _resetForTests() {
+  _started = false;
+  _startedAt = 0;
+  _config = {
+    dailyCap: DEFAULT_DAILY_CAP,
+    perOrderCap: DEFAULT_PER_ORDER_CAP,
+    timeoutMs: DEFAULT_ORDER_TIMEOUT_MS,
+  };
+}
+
+module.exports = {
+  start,
+  stop,
+  isStarted,
+  considerOrder,
+  // Exposed for tests and diagnostics only; callers should not depend on
+  // these internals in production code paths.
+  __internals: {
+    readLedger: _readLedger,
+    writeLedger: _writeLedger,
+    questionHash: _questionHash,
+    effectiveCap: _effectiveCap,
+    resetForTests: _resetForTests,
+    constants: {
+      DEFAULT_DAILY_CAP,
+      DEFAULT_PER_ORDER_CAP,
+      COLD_START_WINDOW_MS,
+      DEDUP_TTL_MS,
+      LEDGER_FILENAME,
+    },
+  },
+};

package/src/atp/cli.js

@@ -0,0 +1,248 @@
+// ATP CLI: lightweight argument parsers and runners for the `buy`, `orders`,
+// and `verify` subcommands. Separated from index.js so they can be unit-tested
+// without booting the full evolver loop.
+//
+// Public API:
+//   parseBuyArgs(args)   -> { ok, opts?, error? }
+//   parseOrdersArgs(args)-> { ok, opts?, error? }
+//   parseVerifyArgs(args)-> { ok, opts?, error? }
+//   runBuy(opts, deps)
+//   runOrders(opts, deps)
+//   runVerify(opts, deps)
+//
+// `deps` is an object containing the ATP module (defaults to require('./index')),
+// injectable for tests. Each runner returns a Promise that resolves to
+// { exitCode: number, output?: string, data?: object }.
+
+function _parseNamed(args, longFlag, shortFlag) {
+  const long = args.findIndex(a => typeof a === 'string' && (a === longFlag || a.startsWith(longFlag + '=')));
+  if (long !== -1) {
+    const token = args[long];
+    if (token.startsWith(longFlag + '=')) return token.slice(longFlag.length + 1);
+    if (args[long + 1] && !String(args[long + 1]).startsWith('--')) return args[long + 1];
+  }
+  if (shortFlag) {
+    const short = args.indexOf(shortFlag);
+    if (short !== -1 && args[short + 1] && !String(args[short + 1]).startsWith('--')) return args[short + 1];
+  }
+  return null;
+}
+
+function _toBool(v) {
+  if (typeof v !== 'string') return false;
+  const s = v.toLowerCase();
+  return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+
+function parseBuyArgs(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    return { ok: false, error: 'buy requires <capabilities>: comma-separated list (e.g. code_review,bug_fix)' };
+  }
+
+  // First positional (not starting with --) is the capability list.
+  let capabilitiesRaw = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (typeof a === 'string' && !a.startsWith('--')) {
+      capabilitiesRaw = a;
+      break;
+    }
+  }
+  if (!capabilitiesRaw) {
+    return { ok: false, error: 'buy requires <capabilities>: comma-separated list' };
+  }
+
+  const capabilities = capabilitiesRaw.split(',').map(s => s.trim()).filter(Boolean);
+  if (capabilities.length === 0) {
+    return { ok: false, error: 'no valid capabilities parsed from: ' + capabilitiesRaw };
+  }
+
+  const budgetRaw = _parseNamed(args, '--budget', '-b');
+  const budget = Math.max(1, Math.round(Number(budgetRaw) || 10));
+
+  const question = _parseNamed(args, '--question', '-q') || '';
+  const routingMode = _parseNamed(args, '--routing', null) || 'fastest';
+  const verifyMode = _parseNamed(args, '--verify', null) || 'auto';
+  const noWait = args.includes('--no-wait');
+  const timeoutMsRaw = _parseNamed(args, '--timeout', null);
+  const timeoutMs = timeoutMsRaw ? Math.max(1000, Math.round(Number(timeoutMsRaw) * 1000)) : 300000;
+
+  return {
+    ok: true,
+    opts: {
+      capabilities,
+      budget,
+      question,
+      routingMode,
+      verifyMode,
+      noWait,
+      timeoutMs,
+    },
+  };
+}
+
+function parseOrdersArgs(args) {
+  const role = _parseNamed(args, '--role', null);
+  if (role && !['consumer', 'merchant'].includes(role)) {
+    return { ok: false, error: 'invalid --role: ' + role + ' (expected consumer|merchant)' };
+  }
+  const status = _parseNamed(args, '--status', null);
+  if (status && !['pending', 'verified', 'disputed', 'settled'].includes(status)) {
+    return { ok: false, error: 'invalid --status: ' + status };
+  }
+  const limitRaw = _parseNamed(args, '--limit', null);
+  const limit = limitRaw ? Math.max(1, Math.min(100, Math.round(Number(limitRaw)))) : 20;
+  const jsonOut = args.includes('--json');
+  return {
+    ok: true,
+    opts: { role: role || 'consumer', status: status || null, limit, jsonOut },
+  };
+}
+
+function parseVerifyArgs(args) {
+  let orderId = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (typeof a === 'string' && !a.startsWith('--')) {
+      orderId = a;
+      break;
+    }
+  }
+  if (!orderId) {
+    return { ok: false, error: 'verify requires <orderId>' };
+  }
+  const action = _parseNamed(args, '--action', null) || 'confirm';
+  if (!['confirm', 'ai_judge'].includes(action)) {
+    return { ok: false, error: 'invalid --action: ' + action + ' (expected confirm|ai_judge)' };
+  }
+  return { ok: true, opts: { orderId, action } };
+}
+
+async function runBuy(opts, deps) {
+  const atp = (deps && deps.atp) || require('./index');
+  const consumerAgent = atp.consumerAgent;
+  const log = (deps && deps.log) || console.log;
+  const err = (deps && deps.err) || console.error;
+
+  log('[ATP] Placing order: capabilities=' + opts.capabilities.join(',') + ' budget=' + opts.budget + ' mode=' + opts.routingMode);
+
+  try {
+    if (opts.noWait) {
+      const result = await consumerAgent.orderService({
+        capabilities: opts.capabilities,
+        budget: opts.budget,
+        routingMode: opts.routingMode,
+        verifyMode: opts.verifyMode,
+        question: opts.question,
+      });
+      if (!result.ok) {
+        err('[ATP] Order failed: ' + (result.error || 'unknown'));
+        return { exitCode: 1, data: result };
+      }
+      log('[ATP] Order placed: ' + result.data.order_id);
+      return { exitCode: 0, data: result.data };
+    }
+
+    const result = await consumerAgent.orderAndWait({
+      capabilities: opts.capabilities,
+      budget: opts.budget,
+      routingMode: opts.routingMode,
+      verifyMode: opts.verifyMode,
+      question: opts.question,
+      timeoutMs: opts.timeoutMs,
+    });
+
+    if (!result.ok) {
+      err('[ATP] Order lifecycle failed: ' + (result.error || 'unknown'));
+      return { exitCode: 1, data: result };
+    }
+    log('[ATP] Order settled: ' + (result.order && result.order.order_id));
+    if (result.finalStatus) {
+      log('[ATP] Final status: ' + JSON.stringify(result.finalStatus, null, 2));
+    }
+    return { exitCode: 0, data: result };
+  } catch (e) {
+    err('[ATP] buy error: ' + (e && e.message || e));
+    return { exitCode: 1, error: String(e) };
+  }
+}
+
+async function runOrders(opts, deps) {
+  const atp = (deps && deps.atp) || require('./index');
+  const hubClient = atp.hubClient;
+  const log = (deps && deps.log) || console.log;
+  const err = (deps && deps.err) || console.error;
+
+  try {
+    const result = await hubClient.listProofs({
+      role: opts.role,
+      status: opts.status || undefined,
+      limit: opts.limit,
+    });
+    if (!result.ok) {
+      err('[ATP] listProofs failed: ' + (result.error || 'unknown'));
+      return { exitCode: 1, data: result };
+    }
+
+    const proofs = (result.data && result.data.proofs) || result.data || [];
+    if (opts.jsonOut) {
+      log(JSON.stringify(proofs, null, 2));
+      return { exitCode: 0, data: proofs };
+    }
+    if (!Array.isArray(proofs) || proofs.length === 0) {
+      log('[ATP] No orders found for role=' + opts.role + (opts.status ? ' status=' + opts.status : ''));
+      return { exitCode: 0, data: [] };
+    }
+    log('[ATP] Showing ' + proofs.length + ' order(s):');
+    for (const p of proofs) {
+      const when = p.createdAt || p.created_at || 'unknown';
+      log('  - ' + (p.taskId || p.order_id || p.id) + ' | status=' + p.status + ' | created=' + when);
+    }
+    return { exitCode: 0, data: proofs };
+  } catch (e) {
+    err('[ATP] orders error: ' + (e && e.message || e));
+    return { exitCode: 1, error: String(e) };
+  }
+}
+
+async function runVerify(opts, deps) {
+  const atp = (deps && deps.atp) || require('./index');
+  const consumerAgent = atp.consumerAgent;
+  const log = (deps && deps.log) || console.log;
+  const err = (deps && deps.err) || console.error;
+
+  try {
+    const fn = opts.action === 'ai_judge' ? consumerAgent.requestAiJudge : consumerAgent.confirmDelivery;
+    const result = await fn(opts.orderId);
+    if (!result.ok) {
+      err('[ATP] verify failed: ' + (result.error || 'unknown'));
+      return { exitCode: 1, data: result };
+    }
+    log('[ATP] verify ok (' + opts.action + '): ' + JSON.stringify(result.data));
+    return { exitCode: 0, data: result.data };
+  } catch (e) {
+    err('[ATP] verify error: ' + (e && e.message || e));
+    return { exitCode: 1, error: String(e) };
+  }
+}
+
+function printUsage() {
+  return [
+    'ATP subcommands:',
+    '  evolver buy <caps> [--budget=N] [--question "..."] [--routing=fastest|cheapest|auction|swarm]',
+    '              [--verify=auto|ai_judge|bilateral] [--no-wait] [--timeout=<seconds>]',
+    '  evolver orders [--role=consumer|merchant] [--status=pending|verified|disputed|settled]',
+    '                 [--limit=N] [--json]',
+    '  evolver verify <orderId> [--action=confirm|ai_judge]',
+  ].join('\n');
+}
+
+module.exports = {
+  parseBuyArgs,
+  parseOrdersArgs,
+  parseVerifyArgs,
+  runBuy,
+  runOrders,
+  runVerify,
+  printUsage,
+};

package/src/atp/index.js

@@ -7,12 +7,16 @@
 //   consumerAgent   - ready-to-use consumer agent template
 //   serviceHelper   - service publishing helper
 //   defaultHandler  - default order handler + config helpers for auto-ATP
+//   autoBuyer       - opt-in capability-gap auto order helper with budget caps
+//   cli             - parsers and runners for the `buy`/`orders`/`verify` subcommands
 
 const hubClient = require('./hubClient');
 const merchantAgent = require('./merchantAgent');
 const consumerAgent = require('./consumerAgent');
 const serviceHelper = require('./serviceHelper');
 const defaultHandler = require('./defaultHandler');
+const autoBuyer = require('./autoBuyer');
+const cli = require('./cli');
 
 module.exports = {
   hubClient,
@@ -20,4 +24,6 @@ module.exports = {
   consumerAgent,
   serviceHelper,
   defaultHandler,
+  autoBuyer,
+  cli,
 };