auxilo-mcp 0.2.0 → 0.8.1

package/README.md

@@ -2,7 +2,7 @@
 
 Agent capability discovery and knowledge marketplace. Find the right tool for any task. Learn from what other agents already figured out.
 
-**Live API**: `https://3000-725fa3fea775ba39db5a2e3703fa4557.life.conway.tech`
+**Live API**: `https://api.auxilo.io`
 
 ## What it does
 
@@ -18,13 +18,13 @@ Auxilo solves two problems for AI agents:
 
 ```bash
 # Free — check what's available
-curl https://3000-725fa3fea775ba39db5a2e3703fa4557.life.conway.tech/categories
+curl https://api.auxilo.io/categories
 
 # Free — marketplace stats
-curl https://3000-725fa3fea775ba39db5a2e3703fa4557.life.conway.tech/knowledge/stats
+curl https://api.auxilo.io/knowledge/stats
 
 # Free — submit a learning
-curl -X POST https://3000-725fa3fea775ba39db5a2e3703fa4557.life.conway.tech/learn \
+curl -X POST https://api.auxilo.io/learn \
   -H "Content-Type: application/json" \
   -d '{
     "title": "E2B sessions timeout after 5 min idle",
@@ -36,11 +36,11 @@ curl -X POST https://3000-725fa3fea775ba39db5a2e3703fa4557.life.conway.tech/lear
     "contributor_wallet": "0xYOUR_WALLET"
   }'
 
-# Paid endpoints require x402 payment header (USDC on Base)
-# /discover  — $0.001 per query
-# /skill/:id — $0.001 per lookup
-# /knowledge — $0.0005 per search
-# /knowledge/:id — dynamic price set by contributor (min $0.005, 70% to contributor)
+# Discovery and search are FREE — no payment required
+# /discover  — Free
+# /skill/:id — Free
+# /knowledge — Free
+# /knowledge/:id — dynamic price set by algorithm (min $0.005, 70% to contributor)
 ```
 
 ### MCP Server (Claude Desktop)
@@ -60,7 +60,9 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
 
 Then ask Claude: *"Search Auxilo for an email API"* or *"Find knowledge about Firecrawl rate limits"*
 
-**MCP Tools:**
+**MCP Tools (v0.7.0):**
+
+*Auxilo Core*
 - `auxilo_discover` — Search the skills registry
 - `auxilo_skill` — Get full details for a specific skill
 - `auxilo_categories` — List all categories
@@ -70,6 +72,23 @@ Then ask Claude: *"Search Auxilo for an email API"* or *"Find knowledge about Fi
 - `auxilo_unlock` — Read full learning content
 - `auxilo_rate` — Rate a learning after using it
 - `auxilo_contributor` — Check contributor earnings
+- `auxilo_verify_wallet` — Wallet ownership verification flow
+- `auxilo_withdraw` — Request withdrawal of earned USDC
+- `auxilo_settlements` — Check settlement history for a wallet
+- `auxilo_link_wallet` — Link a verified wallet to your account
+- `auxilo_account_earnings` — View earnings for your authenticated account
+
+*Renderly (v0.7.0 — new)*
+- `renderly_markdown` — Convert any public URL to clean markdown ($0.001)
+- `renderly_extract` — Extract structured data from any URL ($0.001)
+- `renderly_readable` — Get plain readable text from any URL ($0.0005)
+- `renderly_llms_txt` — Get the LLM-readable Renderly service description (free)
+- `renderly_health` — Check Renderly service health (free)
+- `renderly_pricing` — Get Renderly pricing info (free)
+
+*Stats (v0.7.0 — new)*
+- `get_stats` — Registry statistics (alias, free)
+- `get_knowledge_stats` — Knowledge marketplace statistics (free)
 
 ## Skill categories
 
@@ -90,7 +109,7 @@ Agents learn things the hard way — rate limits, undocumented behavior, workaro
 
 **How it works:**
 1. **Contribute** (free) — Submit what you learned. Set your own unlock price (min $0.005).
-2. **Search** ($0.0005) — Find relevant learnings. Returns titles, snippets, and unlock prices.
+2. **Search** (free) — Find relevant learnings. Returns titles, snippets, and unlock prices.
 3. **Unlock** (dynamic) — Read the full learning. Price set by contributor. 70% goes to them.
 4. **Rate** (free) — Rate helpfulness 1-5. Higher-rated learnings rank higher.
 
@@ -126,14 +145,30 @@ GET /.well-known/agent.json
 | GET | `/health` | Free | Health check |
 | GET | `/categories` | Free | Skill categories with counts |
 | GET | `/stats` | Free | Registry statistics |
-| POST | `/discover` | $0.001 | Search skills registry |
-| GET | `/skill/:id` | $0.001 | Full skill details |
+| POST | `/discover` | Free | Search skills registry |
+| GET | `/skill/:id` | Free | Full skill details |
 | POST | `/learn` | Free | Submit a learning |
-| POST | `/knowledge` | $0.0005 | Search knowledge (snippets) |
+| POST | `/knowledge` | Free | Search knowledge (snippets) |
 | GET | `/knowledge/stats` | Free | Marketplace statistics |
 | GET | `/knowledge/:id` | Dynamic (min $0.005) | Unlock full learning (price set by contributor) |
 | POST | `/knowledge/:id/rate` | Free | Rate a learning |
 | GET | `/contributor/:wallet` | Free | Contributor earnings |
+| POST | `/auth/magic-link` | Free | Request magic link login |
+| GET | `/auth/verify` | Free | Verify magic link token, returns JWT |
+| GET | `/account/dashboard` | Free | Account overview (requires JWT) |
+| POST | `/account/api-keys` | Free | Create API key (requires JWT) |
+| GET | `/account/earnings` | Free | Earnings with pending balance (requires JWT) |
+| POST | `/admin/stage-key` | Free | Stage new wallet key for rotation (admin) |
+
+## Production infrastructure
+
+The live API runs on Conway Cloud with PM2 process management:
+
+- **Health monitoring** — `/health` returns uptime, catalog size, and timestamp
+- **Graceful shutdown** — In-flight requests complete before exit; new requests get 503
+- **Auto-restart** — PM2 restarts the process on crash with exponential backoff
+- **Rate limiting** — Persistent across restarts (state saved to disk)
+- **Key rotation** — Zero-downtime wallet key staging via `/admin/stage-key`
 
 ## Running locally
 

package/bin/auxilo-cli.js

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+
+'use strict';
+
+/**
+ * bin/auxilo-cli.js — Turnkey installer CLI (LW-12)
+ *
+ *   npx auxilo setup     Interactive: detect clients, register MCP, device-code
+ *                        login, install extraction runner + hook, record consent.
+ *   npx auxilo status    Show clients, auth, consent/mode, sentinel, hook, queue.
+ *   npx auxilo disable   Remove the local kill-switch sentinel (+ optional revoke).
+ *
+ * This file is the thin binding layer: real home directory, real fetch, real
+ * stdin. All logic lives in lib/installer.js (testable, fixture-driven).
+ * Supersedes `auxilo-mcp setup` and `auxilo-mcp login` (Change 3/4).
+ */
+
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+const { exec } = require('child_process');
+const installer = require('../lib/installer.js');
+const review = require('../lib/review.js');
+
+const HOME = os.homedir();
+
+// ─── Prompt helpers ─────────────────────────────────────────────────────────
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/** Yes/no prompt. defaultYes=false → consent-grade default-No (spec §LW-12 step 5). */
+async function askYesNo(question, defaultYes = false) {
+  const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] ';
+  const answer = (await ask(question + suffix)).toLowerCase();
+  if (answer === '') return defaultYes;
+  return answer === 'y' || answer === 'yes';
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start ""'
+    : 'xdg-open';
+  exec(`${cmd} "${url}"`, () => { /* best-effort; URL is printed regardless */ });
+}
+
+function resolveBaseUrl(flags) {
+  if (flags['base-url']) return flags['base-url'];
+  if (process.env.AUXILO_BASE_URL) return process.env.AUXILO_BASE_URL;
+  const creds = installer.readCredentials(HOME);
+  if (creds && creds.base_url) return creds.base_url;
+  return installer.DEFAULT_BASE_URL;
+}
+
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 3; i < argv.length; i++) {
+    const m = /^--([a-z-]+)(?:=(.*))?$/.exec(argv[i]);
+    if (!m) continue;
+    if (m[2] !== undefined) flags[m[1]] = m[2];
+    else if (argv[i + 1] && !argv[i + 1].startsWith('--')) flags[m[1]] = argv[++i];
+    else flags[m[1]] = true;
+  }
+  return flags;
+}
+
+// ─── auxilo setup ───────────────────────────────────────────────────────────
+
+const CONSENT_TEXT = `
+  Background extraction (optional)
+  --------------------------------
+  If you opt in, a SessionEnd hook runs after each Claude Code session and a
+  local runner:
+    • READS the session transcript from your machine,
+    • SCRUBS it locally (sensitivity filter: API keys, tokens, emails, PII —
+      redacted BEFORE anything leaves your machine),
+    • UPLOADS only the scrubbed transcript to Auxilo (${'POST /extract'}),
+      where reusable learnings are extracted, quality-gated, moderated, and
+      published to the marketplace under your account. You earn 70% of sales.
+  You can stop any time with \`auxilo disable\` (local kill-switch) and review
+  every run in ~/.auxilo/extract.log. Saying No installs the MCP server only.
+`;
+
+async function cmdSetup(flags) {
+  const baseUrl = resolveBaseUrl(flags);
+  console.log('\nAuxilo turnkey setup');
+  console.log('====================');
+  console.log(`Server: ${baseUrl}\n`);
+
+  // 1. Client detection ------------------------------------------------------
+  const detected = installer.detectClients(HOME);
+  if (detected.length === 0) {
+    console.log('No supported clients detected (Claude Code, Claude Desktop, Cursor, OpenClaw).');
+    console.log('Install one, then re-run `npx auxilo setup`.');
+    process.exit(1);
+  }
+
+  console.log('Detected clients:');
+  detected.forEach((c, i) => {
+    const extras = [c.mcp ? 'MCP' : 'poll-based source', c.hooks ? 'background extraction' : null]
+      .filter(Boolean).join(', ');
+    console.log(`  ${i + 1}. ${c.name} (${extras})`);
+  });
+
+  let chosen = detected;
+  const pick = await ask(`\nConfigure which clients? [all] (e.g. "1,3" or "all") `);
+  if (pick && pick.toLowerCase() !== 'all') {
+    const idx = pick.split(',').map((s) => parseInt(s.trim(), 10) - 1);
+    chosen = detected.filter((_, i) => idx.includes(i));
+    if (chosen.length === 0) {
+      console.log('Nothing selected — exiting without changes.');
+      process.exit(0);
+    }
+  }
+
+  // 2. MCP registration ------------------------------------------------------
+  console.log('');
+  for (const client of chosen.filter((c) => c.mcp)) {
+    try {
+      const result = installer.registerMcp(client);
+      console.log(result.changed
+        ? `  ✓ ${client.name}: registered Auxilo MCP server (${result.configPath})`
+        : `  ✓ ${client.name}: already registered (no changes)`);
+    } catch (err) {
+      // B15: malformed config — skip loudly, never overwrite.
+      console.error(`  ✗ ${client.name}: SKIPPED — ${err.message}`);
+    }
+  }
+  const openclaw = chosen.find((c) => c.id === 'openclaw');
+  if (openclaw) {
+    console.log('  ✓ OpenClaw: no MCP config needed — covered by the poll-based source adapter.');
+  }
+
+  // 3. Device-code auth ------------------------------------------------------
+  console.log('');
+  let creds = installer.readCredentials(HOME);
+  if (creds && creds.api_key && !flags['re-auth']) {
+    console.log(`  ✓ Already authenticated as ${creds.email || creds.account_id || 'existing account'}`);
+    console.log('    (use `auxilo setup --re-auth` to log in again)');
+  } else {
+    console.log('  Logging in to Auxilo (device code flow)...');
+    try {
+      const result = await installer.deviceLogin({
+        baseUrl,
+        onCode: (code, url) => {
+          console.log(`\n  Your device code: ${code}`);
+          console.log(`  Verify at: ${url}\n  Waiting for authorization (Ctrl-C to abort)...`);
+          openBrowser(url);
+        },
+      });
+      installer.writeCredentials(HOME, {
+        api_key: result.api_key,
+        base_url: result.base_url,
+        email: result.email,
+        account_id: result.account_id,
+      });
+      creds = installer.readCredentials(HOME);
+      console.log(`  ✓ Logged in as ${result.email || result.account_id}`);
+      console.log(`  ✓ Credentials saved to ~/.auxilo/credentials.json (mode 0600)`);
+    } catch (err) {
+      console.error(`  ✗ Login failed: ${err.message}`);
+      console.error('    MCP registration (above) is still in place. Re-run `auxilo setup` to retry login.');
+      process.exit(1);
+    }
+  }
+
+  // 4. Runner install + Claude Code hook --------------------------------------
+  console.log('');
+  try {
+    const { binRoot } = installer.installRunner(HOME);
+    console.log(`  ✓ Extraction runner installed to ${binRoot}`);
+  } catch (err) {
+    console.error(`  ✗ Runner install failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  const claudeCode = chosen.find((c) => c.id === 'claude-code');
+  if (claudeCode) {
+    try {
+      const hook = installer.registerClaudeCodeHook(HOME);
+      if (hook.changed) {
+        console.log(`  ✓ Claude Code SessionEnd hook registered (${hook.hookCmd})`);
+        if (hook.removedLegacy.length > 0) {
+          console.log(`    (replaced legacy hook entr${hook.removedLegacy.length === 1 ? 'y' : 'ies'}: ${hook.removedLegacy.join(', ')})`);
+        }
+      } else {
+        console.log('  ✓ Claude Code SessionEnd hook already registered (no changes)');
+      }
+    } catch (err) {
+      console.error(`  ✗ Hook registration SKIPPED — ${err.message}`);
+    }
+  }
+
+  // 5. Explicit consent (default No) ------------------------------------------
+  console.log(CONSENT_TEXT);
+  const consented = await askYesNo('  Enable background extraction?', false);
+  if (consented) {
+    try {
+      await installer.recordConsent({ action: 'grant', apiKey: creds.api_key, baseUrl });
+      installer.enableSentinel(HOME);
+      console.log('  ✓ Consent recorded; background extraction ENABLED (~/.auxilo/autonomous-enabled)');
+    } catch (err) {
+      console.error(`  ✗ Could not record consent on server: ${err.message}`);
+      console.error('    Background extraction NOT enabled (no sentinel created). Re-run `auxilo setup` to retry.');
+    }
+  } else {
+    console.log('  ✓ Background extraction left OFF (MCP-only install). Enable later by re-running `auxilo setup`.');
+  }
+
+  console.log('\nDone. Check `npx auxilo status` any time. Restart your client(s) to pick up the MCP server.\n');
+}
+
+// ─── auxilo status ──────────────────────────────────────────────────────────
+
+async function cmdStatus() {
+  const s = await installer.getStatus(HOME);
+
+  console.log('\nAuxilo status');
+  console.log('=============');
+
+  console.log('Clients:');
+  if (s.clients.length === 0) console.log('  (none detected)');
+  for (const c of s.clients) {
+    const reg = c.mcp
+      ? (c.registered ? 'MCP registered' : 'detected, MCP NOT registered')
+      : 'poll-based source (no MCP config)';
+    console.log(`  ${c.name}: ${reg}`);
+  }
+
+  console.log(`Auth: ${s.auth.credentialsFile
+    ? `credentials present (key ${s.auth.keyPrefix || 'unreadable'}${s.auth.email ? `, ${s.auth.email}` : ''})`
+    : 'NOT logged in (run `npx auxilo setup`)'}`);
+  console.log(`Account mode: ${s.accountMode}`);
+  console.log(`Kill-switch sentinel: ${s.sentinel ? 'present (extraction enabled)' : 'absent (extraction disabled)'}`);
+  console.log(`Runner installed: ${s.runnerInstalled ? 'yes (~/.auxilo/bin)' : 'no'}`);
+  console.log(`SessionEnd hook: ${s.hookInstalled ? 'installed' : 'not installed'}${s.hookRegistered ? ', registered in Claude Code settings' : ''}`);
+  console.log(`Last extraction sweep: ${s.lastSweep || 'never'}`);
+  console.log(`Pending upload queue: ${s.pendingCount} file(s)\n`);
+}
+
+// ─── auxilo disable ─────────────────────────────────────────────────────────
+
+async function cmdDisable(flags) {
+  const removed = installer.disableSentinel(HOME);
+  console.log(removed
+    ? '✓ Kill-switch sentinel removed — background extraction is now DISABLED locally.'
+    : '✓ Sentinel already absent — background extraction was not enabled.');
+
+  const creds = installer.readCredentials(HOME);
+  if (creds && creds.api_key) {
+    const revoke = await askYesNo('Also revoke extraction consent on the server?', false);
+    if (revoke) {
+      try {
+        await installer.recordConsent({
+          action: 'revoke',
+          apiKey: creds.api_key,
+          baseUrl: resolveBaseUrl(flags),
+        });
+        console.log('✓ Consent revoked on server (account mode set to off).');
+      } catch (err) {
+        console.error(`✗ Server revoke failed: ${err.message} — local kill-switch is still in effect.`);
+      }
+    }
+  }
+  console.log('Note: MCP server registrations are left in place (remove manually from client configs if desired).');
+}
+
+// ─── auxilo review ──────────────────────────────────────────────────────────
+//
+// The human gate that makes background extraction safe to re-enable:
+//   extract -> pending_review -> `auxilo review` -> approve the safe ones.
+// Operates ONLY on the caller's own pending learnings (account-scoped API key).
+
+/** Print one candidate's full detail for the interactive reviewer. */
+function printCandidate(l, n, total) {
+  console.log(`\n──────────────────────────────────────────────────────────────`);
+  console.log(`[${n}/${total}] ${l.title}`);
+  console.log(`  id:       ${l.id}`);
+  console.log(`  category: ${l.category}${l.outcome ? `   outcome: ${l.outcome}` : ''}`);
+  if (l.tags && l.tags.length) console.log(`  tags:     ${l.tags.join(', ')}`);
+  if (l.created_at) console.log(`  created:  ${l.created_at}`);
+  const flags = review.formatFlags(l);
+  if (flags) console.log(`  ⚠ flags:  ${flags}`);
+  console.log(`  ----------------------------------------------------------`);
+  console.log(l.body || '(no body)');
+  console.log(`  ----------------------------------------------------------`);
+}
+
+async function cmdReview(flags) {
+  const creds = installer.readCredentials(HOME);
+  if (!creds || !creds.api_key) {
+    console.error('Not logged in. Run `npx auxilo setup` first.');
+    process.exit(1);
+  }
+  const baseUrl = resolveBaseUrl(flags);
+  const apiKey = creds.api_key;
+
+  let res;
+  try {
+    res = await review.fetchPending({ apiKey, baseUrl, limit: 200 });
+  } catch (err) {
+    console.error(`Could not fetch pending review queue: ${err.message}`);
+    process.exit(1);
+  }
+
+  const items = res.learnings || [];
+  const total = res.pending_count != null ? res.pending_count : items.length;
+
+  if (items.length === 0) {
+    console.log('No learnings pending your review. Nothing to do.');
+    return;
+  }
+
+  // ── --list: non-interactive inspection, no mutations ──────────────────────
+  if (flags.list) {
+    console.log(`\n${total} learning(s) pending your review:\n`);
+    items.forEach((l, i) => {
+      const flagStr = review.formatFlags(l);
+      console.log(`  ${i + 1}. ${l.title}  [${l.id}]${flagStr ? `  ⚠ ${flagStr}` : ''}`);
+    });
+    console.log('');
+    return;
+  }
+
+  // ── --all-reject: bulk reject the whole batch (incident escape hatch) ─────
+  if (flags['all-reject']) {
+    const ok = flags.yes || await askYesNo(`Reject ALL ${items.length} pending learning(s)? This cannot be undone`, false);
+    if (!ok) { console.log('Aborted — nothing changed.'); return; }
+    let rejected = 0;
+    for (const l of items) {
+      try {
+        await review.submitDecision({ apiKey, baseUrl, id: l.id, decision: 'reject' });
+        rejected += 1;
+        console.log(`  ✗ rejected (${rejected}/${items.length}): ${l.title}`);
+      } catch (err) {
+        console.error(`  ! failed to reject ${l.id}: ${err.message}`);
+      }
+    }
+    console.log(`\nDone. Rejected ${rejected} of ${items.length}.`);
+    return;
+  }
+
+  // ── interactive (default) ─────────────────────────────────────────────────
+  console.log(`\n${total} learning(s) pending your review.`);
+  console.log('For each: [a]pprove (go live) · [r]eject (stays private) · [s]kip · [q]uit\n');
+
+  let approved = 0, rejected = 0, skipped = 0, seen = 0;
+  for (const l of items) {
+    seen += 1;
+    printCandidate(l, seen, items.length);
+    let choice = '';
+    while (!['a', 'r', 's', 'q'].includes(choice)) {
+      choice = (await ask('  approve / reject / skip / quit [a/r/s/q]? ')).toLowerCase().slice(0, 1);
+    }
+    if (choice === 'q') { console.log('  Stopping. Remaining items left pending.'); break; }
+    if (choice === 's') { skipped += 1; console.log('  → skipped (still pending)'); continue; }
+    try {
+      if (choice === 'a') {
+        await review.submitDecision({ apiKey, baseUrl, id: l.id, decision: 'approve' });
+        approved += 1; console.log('  ✓ approved — now live');
+      } else {
+        const reason = await ask('  reason (optional, Enter to skip): ');
+        await review.submitDecision({ apiKey, baseUrl, id: l.id, decision: 'reject', reason: reason || undefined });
+        rejected += 1; console.log('  ✗ rejected — stays private');
+      }
+    } catch (err) {
+      console.error(`  ! decision failed: ${err.message} (item left pending)`);
+    }
+  }
+
+  console.log(`\nReview complete: approved ${approved}, rejected ${rejected}, skipped ${skipped} of ${items.length}.`);
+}
+
+// ─── Entry point ────────────────────────────────────────────────────────────
+
+function usage() {
+  console.log(`
+Usage: auxilo <command>
+
+Commands:
+  setup     Interactive install: client detection, MCP registration,
+            device-code login, extraction runner + hook, consent.
+            Flags: --re-auth, --base-url <url>
+  status    Show install/auth/extraction status.
+  review    Review YOUR pending-review learnings (from background extraction)
+            and approve/reject each before it goes public.
+            Flags: --list (inspect only), --all-reject [--yes], --base-url <url>
+  disable   Turn off background extraction (local kill-switch; optional
+            server-side consent revoke).
+
+Docs: https://auxilo.io · API: ${installer.DEFAULT_BASE_URL}
+`);
+}
+
+async function main() {
+  const cmd = process.argv[2];
+  const flags = parseFlags(process.argv);
+  switch (cmd) {
+    case 'setup': return cmdSetup(flags);
+    case 'status': return cmdStatus(flags);
+    case 'review': return cmdReview(flags);
+    case 'disable': return cmdDisable(flags);
+    case 'help': case '--help': case '-h': case undefined: return usage();
+    default:
+      console.error(`Unknown command: ${cmd}`);
+      usage();
+      process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`auxilo: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { parseFlags, resolveBaseUrl };