callx402 0.0.0-stage → 1.0.0

package/bin/callx402.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * bin/callx402.js — CLI for the callx402 universal action layer (stdlib only).
+ *
+ *   callx402 <command> [args] [options]
+ *   callx402 "natural language intent"      # intent mode -> execute
+ *   callx402 --help | --version
+ *
+ * Global: --json, --timeout <ms>. Exit codes: 0 ok, 1 failure, 2 usage,
+ * 3 subsystem disabled/unreachable, 4 budget refused, 5 settlement unknown.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const core = require(path.join(ROOT, 'core'));
+const { loadConfig, getConfig, setConfig, listConfig } = require(path.join(ROOT, 'core', 'config'));
+const { EXIT } = require(path.join(ROOT, 'core', 'envelope'));
+
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const VERSION = PKG.version || '1.0.0';
+
+const COMMANDS = ['diagnose', 'rescue', 'route', 'resolve', 'doctor', 'execute', 'monitor', 'status', 'preflight', 'inspect', 'config'];
+
+const HELP = `callx402 ${VERSION} — universal action layer for x402 infrastructure.
+callx402 is the ACTION, not the product name; every command dispatches into
+the existing v2.0.0 subsystems. Nothing here executes payments by itself.
+
+Usage:
+  callx402 <command> [args] [options]
+  callx402 "natural language intent"        intent mode (plans, never executes blindly)
+  callx402 --help | --version
+
+Commands:
+  diagnose    run the x402 doctor over supplied evidence        [--target ...]
+  rescue      incident triage (auth-gated; read-only without auth) --incident <id>
+  route       select a tool/route for a goal                   --goal <text>
+  resolve     resolve settlement state from evidence           --evidence <json|@file>
+  doctor      alias of diagnose
+  execute     run the intent pipeline                          --intent <text> [--max-budget N] [--dry-run] [--idempotency-key K]
+  monitor     sentinel snapshot [--once] or stream [--watch]
+  status      per-subsystem reachable/enabled/version report
+  preflight   run MCP preflight checks
+  inspect     capability-graph lookup/stats                    [--query <text>]
+  config      list | get <key> | set <key> <value>
+
+Options:
+  --json                 print the full result envelope as JSON
+  --timeout <ms>         fail the action if it exceeds <ms>
+  --approve              authorize costs above the approval threshold
+  --force-retry          explicit retry flag (REFUSED when prior settlement is UNKNOWN)
+  --dry-run              plan only; no execution side effects
+  --speed fast|balanced|cheap   routing policy hint
+  --max-budget <usd>     cap for execute
+  --idempotency-key <k>  dedupe key for execute
+  -h, --help             this help
+  -v, --version          version
+
+Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`;
+
+function parseArgv(argv) {
+  const out = { flags: {}, positionals: [], errors: [] };
+  const SHORT = { h: 'help', v: 'version' };
+  // Unknown --flags are usage errors, never silently ignored: a typo like
+  // --dry-runn must not silently change what the command does.
+  const KNOWN_FLAGS = new Set([
+    'help', 'version', 'json', 'timeout', 'maxBudget', 'approvalThreshold',
+    'idempotencyKey', 'evidence', 'incident', 'goal', 'intent', 'query',
+    'target', 'speed', 'interval', 'network', 'networks', 'asset', 'assets',
+    'providers', 'deadline', 'risk',
+    'dryRun', 'approve', 'forceRetry', 'retry', 'auth', 'watch', 'once',
+  ]);
+  let i = 0;
+  while (i < argv.length) {
+    const t = argv[i];
+    if (t === '--') { out.positionals.push(...argv.slice(i + 1)); break; }
+    if (t.startsWith('--')) {
+      const eq = t.indexOf('=');
+      const rawName = eq === -1 ? t.slice(2) : t.slice(2, eq);
+      const name = rawName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const val = eq === -1 ? null : t.slice(eq + 1);
+      if (!KNOWN_FLAGS.has(name)) {
+        out.errors.push(`unknown flag --${rawName}`);
+        i += 1;
+        continue;
+      }
+      const NEEDS_VALUE = new Set(['timeout', 'maxBudget', 'approvalThreshold', 'idempotencyKey', 'evidence', 'incident', 'goal', 'intent', 'query', 'target', 'speed', 'interval', 'network', 'networks', 'asset', 'assets', 'providers', 'deadline', 'risk']);
+      if (NEEDS_VALUE.has(name)) {
+        if (val !== null) out.flags[name] = val;
+        else if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) out.flags[name] = argv[++i];
+        else out.errors.push(`flag --${t.slice(2)} requires a value`);
+      } else {
+        out.flags[name] = val === null ? true : val;
+      }
+    } else if (t.startsWith('-') && t.length === 2) {
+      const name = SHORT[t[1]];
+      if (!name) out.errors.push(`unknown flag ${t}`);
+      else out.flags[name] = true;
+    } else if (t.startsWith('-')) {
+      out.errors.push(`unknown flag ${t}`);
+    } else {
+      out.positionals.push(t);
+    }
+    i += 1;
+  }
+  return out;
+}
+
+function usageError(message) {
+  console.error(`callx402: ${message}\nValid commands: ${COMMANDS.join(', ')}\nRun 'callx402 --help' for usage.`);
+  process.exit(EXIT.USAGE);
+}
+
+/** Concise human-readable summary for non-JSON output. */
+function summarize(envelope) {
+  const lines = [];
+  lines.push(`${envelope.ok ? 'ok' : 'FAILED'} [${envelope.action || '?'}]${envelope.subsystem ? ` via ${envelope.subsystem}` : ''}`);
+  if (envelope.disposition) lines.push(envelope.disposition);
+  if (envelope.subsystemStatus && envelope.subsystemStatus !== 'ok') lines.push(`subsystemStatus: ${envelope.subsystemStatus}`);
+  if (envelope.settlement) lines.push(`settlement: ${envelope.settlement}`);
+  if (envelope.txHash) lines.push(`txHash: ${envelope.txHash}`);
+  if (envelope.idempotencyKey) lines.push(`idempotencyKey: ${envelope.idempotencyKey}${envelope.deduped ? ' (deduped)' : ''}`);
+  if (envelope.error) lines.push(`error [${envelope.error.code}]: ${envelope.error.message}`);
+  return lines.join('\n');
+}
+
+function statusSummary(envelope) {
+  const lines = [envelope.disposition || 'status'];
+  const subs = (envelope.data && envelope.data.subsystems) || {};
+  for (const [name, s] of Object.entries(subs)) {
+    const mark = !s.reachable ? 'UNREACHABLE' : s.enabled ? 'enabled' : `disabled (${s.flag || 'no FLAG export'})`;
+    lines.push(`  ${name.padEnd(12)} ${mark}${s.version ? `  v${s.version}` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+async function main() {
+  const { flags, positionals, errors } = parseArgv(process.argv.slice(2));
+
+  if (flags.help) { process.stdout.write(HELP); process.exit(EXIT.OK); }
+  if (flags.version) { process.stdout.write(`callx402 ${VERSION}\n`); process.exit(EXIT.OK); }
+  if (errors.length > 0) usageError(errors[0]);
+
+  const [first, ...rest] = positionals;
+
+  // Bare quoted string -> intent mode: anything not a known command AND looking
+  // like natural language (more than one word). A single unknown word is an
+  // unknown command (exit 2), per the CLI contract.
+  const isCommand = first && COMMANDS.includes(first);
+  if (!isCommand && first && first.startsWith('-')) usageError(`unknown input '${first}'`);
+  if (!isCommand && positionals.length === 1 && !/\s/.test(first)) usageError(`unknown command '${first}'`);
+  const command = isCommand ? first : (first === undefined ? null : '__intent__');
+
+  // config handled directly (not a subsystem dispatch)
+  if (command === 'config') {
+    const sub = rest[0];
+    try {
+      if (sub === 'list' || sub === undefined) {
+        const cfg = listConfig();
+        if (flags.json) console.log(JSON.stringify(cfg, null, 2));
+        else for (const [k, v] of Object.entries(cfg)) console.log(`${k}=${v}`);
+        process.exit(EXIT.OK);
+      }
+      if (sub === 'get') {
+        if (!rest[1]) usageError('config get <key>');
+        const v = getConfig(rest[1]);
+        if (flags.json) console.log(JSON.stringify({ [rest[1]]: v }));
+        else console.log(`${rest[1]}=${v}`);
+        process.exit(EXIT.OK);
+      }
+      if (sub === 'set') {
+        if (!rest[1] || rest[2] === undefined) usageError('config set <key> <value>');
+        const cfg = setConfig(rest[1], rest[2]);
+        if (flags.json) console.log(JSON.stringify({ [rest[1]]: cfg[rest[1]] }));
+        else console.log(`${rest[1]}=${cfg[rest[1]]}`);
+        process.exit(EXIT.OK);
+      }
+      usageError(`unknown config subcommand '${sub}' (use list|get|set)`);
+    } catch (err) {
+      console.error(`callx402: ${err.message}`);
+      process.exit(EXIT.USAGE);
+    }
+  }
+
+  if (!command) usageError('no command given');
+
+  const toNum = (v) => (v === undefined ? undefined : Number(v));
+  // Comma-separated list flags (also used by the Python SDK: --networks a,b).
+  const toList = (v) => (v === undefined ? undefined : String(v).split(',').map((s) => s.trim()).filter(Boolean));
+  const args = {
+    json: !!flags.json,
+    timeoutMs: toNum(flags.timeout),
+    evidence: flags.evidence,
+    target: flags.target,
+    incident: flags.incident,
+    goal: flags.goal,
+    intent: flags.intent,
+    query: flags.query,
+    speed: flags.speed,
+    maxBudget: toNum(flags.maxBudget),
+    approvalThreshold: toNum(flags.approvalThreshold),
+    idempotencyKey: flags.idempotencyKey,
+    dryRun: flags.dryRun === true || flags.dryRun === 'true',
+    approve: flags.approve === true || flags.approve === 'true',
+    forceRetry: flags.forceRetry === true || flags.forceRetry === 'true',
+    retry: flags.retry === true || flags.retry === 'true',
+    auth: flags.auth === true || flags.auth === 'true' || flags.auth === '1' ? true : undefined,
+    watch: !!flags.watch,
+    once: !!flags.once,
+    interval: toNum(flags.interval),
+    network: flags.network,
+    deadline: flags.deadline,
+    risk: flags.risk,
+    networks: toList(flags.networks) || (flags.network ? [flags.network] : undefined),
+    assets: toList(flags.assets) || (flags.asset ? [flags.asset] : undefined),
+    providers: toList(flags.providers),
+  };
+
+  let actionName = command;
+  if (command === '__intent__') {
+    actionName = 'execute';
+    args.intent = positionals.join(' ');
+  } else {
+    // positional fallbacks
+    if ((command === 'diagnose' || command === 'doctor') && !args.target && rest.length > 0) args.target = rest.join(' ');
+    if (command === 'route' && !args.goal && rest.length > 0) args.goal = rest.join(' ');
+    if (command === 'execute' && !args.intent && rest.length > 0) args.intent = rest.join(' ');
+    if (command === 'inspect' && !args.query && rest.length > 0) args.query = rest.join(' ');
+    if (command === 'rescue' && !args.incident && rest.length > 0) args.incident = rest[0];
+  }
+
+  if (Number.isNaN(args.timeoutMs)) usageError('--timeout must be a number (ms)');
+  if (args.maxBudget !== undefined && Number.isNaN(args.maxBudget)) usageError('--max-budget must be a number');
+  if (args.approvalThreshold !== undefined && Number.isNaN(args.approvalThreshold)) usageError('--approval-threshold must be a number');
+
+  try {
+    const { result, exitCode } = await core.runAction(actionName, args, { version: VERSION });
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (actionName === 'status') {
+      console.log(statusSummary(result));
+    } else {
+      console.log(summarize(result));
+    }
+    process.exit(exitCode);
+  } catch (err) {
+    console.error(`callx402: ${err.message}`);
+    process.exit(EXIT.FAIL);
+  }
+}
+
+main();

package/core/config.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * core/config.js — config file (~/.config/callx402/config.json, overridable by
+ * $CALLX402_CONFIG) + CALLX402_* env overrides + safe defaults.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DEFAULTS = {
+  mode: 'local',                 // local | remote
+  remoteUrl: null,
+  authToken: null,
+  v2Root: null,                  // null => default relative to v2.0.0 tree
+  defaultNetwork: 'base',
+  defaultAsset: 'USDC',
+  defaultBudgetUsd: 1.00,
+  approvalThresholdUsd: 5.00,    // above this: require explicit approval, fail closed
+  rescueAuth: false,             // rescue execute requires explicit auth enable
+};
+
+// env name -> [config key, coerce]
+const ENV_MAP = {
+  CALLX402_V2_ROOT: ['v2Root', String],
+  CALLX402_MODE: ['mode', String],
+  CALLX402_REMOTE_URL: ['remoteUrl', String],
+  CALLX402_AUTH_TOKEN: ['authToken', String],
+  CALLX402_DEFAULT_NETWORK: ['defaultNetwork', String],
+  CALLX402_DEFAULT_ASSET: ['defaultAsset', String],
+  CALLX402_DEFAULT_BUDGET_USD: ['defaultBudgetUsd', Number],
+  CALLX402_APPROVAL_THRESHOLD_USD: ['approvalThresholdUsd', Number],
+};
+
+const NUMERIC_KEYS = new Set(['defaultBudgetUsd', 'approvalThresholdUsd']);
+
+function configPath() {
+  if (process.env.CALLX402_CONFIG) return process.env.CALLX402_CONFIG;
+  return path.join(os.homedir(), '.config', 'callx402', 'config.json');
+}
+
+function readFileConfig() {
+  const p = configPath();
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') {
+      throw new Error(`callx402: config file ${p} is not valid JSON (${err.message})`);
+    }
+  }
+  return {};
+}
+
+function applyEnvOverrides(cfg) {
+  const out = { ...cfg };
+  for (const [envName, [key, coerce]] of Object.entries(ENV_MAP)) {
+    const v = process.env[envName];
+    if (v === undefined || v === null || v === '') continue;
+    if (coerce === Number) {
+      const n = Number(v);
+      if (!Number.isFinite(n)) continue;
+      out[key] = n;
+    } else {
+      out[key] = String(v);
+    }
+  }
+  return out;
+}
+
+/** Merged effective config: defaults < file < env. */
+function loadConfig() {
+  return applyEnvOverrides({ ...DEFAULTS, ...readFileConfig() });
+}
+
+function getConfig(key) {
+  const cfg = loadConfig();
+  if (!(key in DEFAULTS)) throw new Error(`callx402: unknown config key '${key}'`);
+  return cfg[key];
+}
+
+function listConfig() {
+  return loadConfig();
+}
+
+/** Persist one key to the config file (env overrides are never persisted). */
+function setConfig(key, value) {
+  if (!(key in DEFAULTS)) throw new Error(`callx402: unknown config key '${key}' (valid: ${Object.keys(DEFAULTS).join(', ')})`);
+  let v = value;
+  if (NUMERIC_KEYS.has(key)) {
+    v = Number(value);
+    if (!Number.isFinite(v)) throw new Error(`callx402: config key '${key}' requires a number`);
+  }
+  const p = configPath();
+  const current = readFileConfig();
+  current[key] = v;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(current, null, 2) + '\n', 'utf8');
+  return loadConfig();
+}
+
+module.exports = { DEFAULTS, configPath, loadConfig, getConfig, setConfig, listConfig };

package/core/envelope.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * core/envelope.js — result envelope builders + CLI exit codes.
+ *
+ * Every dispatch (CLI, SDKs, HTTP) returns the envelope shape from SPEC section 4.
+ * `error` is null on success; ok:false whenever error is set.
+ */
+
+const EXIT = {
+  OK: 0,               // ok
+  FAIL: 1,             // generic failure
+  USAGE: 2,            // usage/validation error
+  UNAVAILABLE: 3,      // subsystem disabled or unreachable
+  BUDGET_REFUSED: 4,   // SpendGuard budget refusal
+  SETTLEMENT_UNKNOWN: 5, // settlement UNKNOWN: never auto-retry, never repay
+};
+
+const VALID_STATUSES = new Set(['ok', 'disabled', 'unreachable', 'prototype']);
+
+function envelope(partial = {}) {
+  const env = {
+    ok: partial.ok === true,
+    action: partial.action ?? null,
+    disposition: partial.disposition ?? null,
+    subsystem: partial.subsystem ?? null,
+    subsystemStatus: partial.subsystemStatus ?? null,
+    data: partial.data ?? {},
+    settlement: partial.settlement ?? null,
+    txHash: partial.txHash ?? null,
+    receipt: partial.receipt ?? {},
+    idempotencyKey: partial.idempotencyKey ?? null,
+    deduped: partial.deduped === true,
+    error: partial.error ?? null,
+  };
+  if (env.subsystemStatus && !VALID_STATUSES.has(env.subsystemStatus)) {
+    env.subsystemStatus = null;
+  }
+  // Invariant: ok:false whenever error is set; ok:true implies error null.
+  if (env.error) env.ok = false;
+  if (env.ok) env.error = null;
+  return env;
+}
+
+function ok(action, { subsystem = null, subsystemStatus = 'ok', disposition = null, data = {}, settlement = null, txHash = null, receipt = {}, idempotencyKey = null, deduped = false } = {}) {
+  return envelope({ ok: true, action, subsystem, subsystemStatus, disposition, data, settlement, txHash, receipt, idempotencyKey, deduped, error: null });
+}
+
+function fail(action, { subsystem = null, subsystemStatus = null, code = 'failed', message = 'failed', disposition = null, data = {}, settlement = null, idempotencyKey = null, deduped = false } = {}) {
+  return envelope({ ok: false, action, subsystem, subsystemStatus, disposition, data, settlement, idempotencyKey, deduped, error: { code, message } });
+}
+
+/** Map an envelope to a CLI exit code (budget/settlement refusals are explicit). */
+function exitCodeFor(result) {
+  if (!result) return EXIT.FAIL;
+  if (result.ok) return EXIT.OK;
+  const code = result.error && result.error.code;
+  switch (code) {
+    case 'usage':
+    case 'validation':
+    case 'unknown_action':
+      return EXIT.USAGE;
+    case 'subsystem_disabled':
+    case 'subsystem_unreachable':
+    case 'auth_required':
+    case 'no_executable_route':
+    case 'remote_unreachable':
+      return EXIT.UNAVAILABLE;
+    case 'budget_refused':
+    case 'approval_required':
+      return EXIT.BUDGET_REFUSED;
+    case 'settlement_unknown':
+    case 'unsafe_retry_refused':
+      return EXIT.SETTLEMENT_UNKNOWN;
+    default:
+      return EXIT.FAIL;
+  }
+}
+
+module.exports = { EXIT, VALID_STATUSES, envelope, ok, fail, exitCodeFor };