robot-resources 1.10.6 → 1.11.1

package/README.md

@@ -1,88 +1,90 @@
-# Robot Resources
+# robot-resources
 
-> Tools for AI agents. Humans have HR. Agents have RR.
-
-Two products for any software that makes LLM API calls — chatbots, RAG pipelines, AI-powered apps, agent runtimes. Both run locally, both free.
-
-**Router** — Intelligent LLM routing proxy. Classifies each prompt by task type, routes to the cheapest model that qualifies. 60-90% cost savings with zero quality loss.
-
-**Scraper** — Token compression for web content. Fetches any URL, strips noise, returns clean markdown. Median 91% token reduction.
-
-## Install
+> One command to install Robot Resources tools for any agent stack.
 
 ```bash
 npx robot-resources
 ```
 
-One command: installs Router as an always-on system service, registers Scraper as an MCP tool, configures your agent automatically.
+The wizard detects what you're building and walks you through the right setup — OpenClaw plugin install, JS library path, Python SDK path, MCP config for Cursor / Claude Code, or just the docs URL.
 
-## What It Does
+## What the wizard does
 
-1. **Installs Router** — Python venv + system service on localhost:3838
-2. **Registers Scraper** — MCP tool `scraper_compress_url(url)` in your agent
-3. **Configures OpenClaw** — Plugin auto-installed if OpenClaw is detected
-4. **Provisions API key** — For telemetry and dashboard access
-5. **Health check** — Verifies everything is running after install
+1. **Provisions an anonymous API key** via `POST /v1/auth/signup` (saved to `~/.robot-resources/config.json`). Optional — routing works without it; the key just lights up the dashboard at robotresources.ai/dashboard.
+2. **Detects your stack**:
+   - OpenClaw installed (`~/.openclaw/`) → installs the router plugin (in-process HTTP server) + scraper OC plugin, patches `openclaw.json`, restarts the gateway. **No Python, no daemon, no system service.**
+   - Non-OC + cwd has `package.json` with LangChain/LangGraph/Mastra → preselects "JS/TS agent."
+   - Non-OC + cwd has `requirements.txt` / `pyproject.toml` → preselects "Python agent."
+   - Non-OC + Cursor or Claude Code installed → preselects "MCP tool."
+3. **Runs the chosen path**:
+   - **JS/TS agent** → prints `npm install @robot-resources/router` + `import { routePrompt }` example
+   - **Python agent** → prints `pip install robot-resources` + `from robot_resources.router import route` example, plus an httpx fallback if you'd rather skip the SDK
+   - **Cursor / Claude Code** → writes the scraper MCP config into `~/.cursor/mcp.json` / `~/.claude/settings.json`
+   - **Docs** → prints the URL + exits
+   - **Install OpenClaw first** → redirect message + exits
 
-## Router
+## Flags
 
-Transparent proxy on localhost:3838. Your LLM calls pass through, Router selects the cheapest capable model:
-
-- Hybrid classification: keyword detection (~5ms) + LLM fallback (~200ms)
-- Dynamic thresholds: simple tasks → cheap models, complex tasks → top models
-- Models across OpenAI, Anthropic, Google — routes within your available providers
-- Your API keys pass through via headers — never stored by Router
-- OpenAI-compatible API — change `base_url` to `http://localhost:3838`
+```
+--for=<target>      langchain | python | cursor | claude-code | docs
+                    Skip the prompt and run that path directly.
+                    Required for non-TTY contexts (CI, piped, etc.)
+--non-interactive   Treat as CI run regardless of TTY state
+--yes / -y          Same as --non-interactive
+```
 
-## Scraper
+Without flags in a non-TTY context, the wizard prints the `--for=` hint and exits cleanly — never blocks waiting for stdin.
 
-Available as MCP tool after install:
+## Pre-set the API key
 
-- Mozilla Readability extraction (0.97 F1 accuracy)
-- Content-aware token estimation
-- 3-tier fetch: fast, stealth (TLS fingerprint), render (headless browser)
-- Multi-page BFS crawl with robots.txt compliance
-- Median 91% token reduction per page
+For fleets or CI:
 
-## Agent Compatibility
+```bash
+export RR_API_KEY=rr_live_...        # skip signup, use this key
+npx robot-resources --for=cursor     # or whatever path applies
+```
 
-| Agent | Integration | Status |
-|-------|-------------|--------|
-| **OpenClaw** | Plugin (auto-install) | Verified |
-| **Claude Code** | MCP server | Verified |
-| **Any OpenAI client** | HTTP proxy (localhost:3838) | Compatible |
-| **Cursor** | MCP server | Compatible |
-| **Windsurf** | MCP server | Compatible |
+## Five paths, one wizard
 
-## MCP Servers
+| Path | What you get | Where |
+|---|---|---|
+| OpenClaw plugin | In-process router inside the OC gateway. Auto-routes Anthropic calls to the cheapest capable model. | `~/.openclaw/extensions/robot-resources-router/` |
+| JS/TS agent | `@robot-resources/router/routing` — pure ESM, zero deps, offline keyword classifier. | npm |
+| Python agent | `robot-resources` (singular) — thin httpx client over `/v1/route`. | PyPI |
+| HTTP API | Any language with curl/fetch. Authed by API key. | `POST https://api.robotresources.ai/v1/route` |
+| Cursor / Claude Code MCP | Scraper MCP wired into your tool's config (web fetches → 91% smaller markdown). | `~/.cursor/mcp.json` or `~/.claude/settings.json` |
 
-```bash
-npx -y @robot-resources/scraper-mcp   # Scraper compression
-```
+Full integration docs: https://robotresources.ai/docs
 
-## Dashboard
+## Architecture (post-PR-2.5)
 
-Usage dashboard at https://robotresources.ai/dashboard — real-time telemetry, cost savings, routing stats. Auth via GitHub OAuth.
+The router used to be a Python daemon on `localhost:3838`. **Not anymore.** It now runs in-process inside whichever surface consumes it:
 
-## Pricing
+- **OpenClaw** — the plugin's `register()` starts an HTTP server on `127.0.0.1:18790` inside OC's node process. Lifetime tied to OC. Zero daemon to keep alive.
+- **JS agents** — call `routePrompt()` directly. No HTTP at all. Pure function.
+- **Python / curl** — call `POST /v1/route` on `api.robotresources.ai`. Server-side classifier on Cloudflare Workers.
 
-Free. Unlimited. No tiers. Your API keys never leave your machine.
+User provider keys never leave the user's machine. The platform never receives, stores, or transmits them.
 
 ## Telemetry
 
-Anonymous usage telemetry (model selection, cost savings) to improve the product. No personal data, no request content, no API keys.
+Anonymous, fire-and-forget, opt-in via the wizard's API-key provisioning. Events: `wizard_started`, `wizard_path_chosen`, `install_complete`, `route_completed`, `route_via_api`, `route_via_lib`. No personal data, no request content, no provider keys.
 
-Opt out: `export RR_TELEMETRY=off`
+## Pricing
+
+Free. Unlimited. Your API keys never leave your machine.
 
 ## Links
 
 - Website: https://robotresources.ai
+- Docs: https://robotresources.ai/docs
 - Dashboard: https://robotresources.ai/dashboard
-- Agent docs: https://robotresources.ai/llms.txt
+- HTTP API: `POST https://api.robotresources.ai/v1/route`
 - npm: https://www.npmjs.com/package/robot-resources
 - GitHub: https://github.com/robot-resources/packages
 - Discord: https://robotresources.ai/discord
 - Contact: agent@robotresources.ai
+- Agent docs: https://robotresources.ai/llms.txt
 
 ## License
 

package/bin/setup.js

@@ -3,9 +3,18 @@
 import { runWizard } from '../lib/wizard.js';
 
 const args = process.argv.slice(2);
-const nonInteractive = args.includes('--non-interactive') || args.includes('--yes') || args.includes('-y');
+const explicitNonInteractive =
+  args.includes('--non-interactive') || args.includes('--yes') || args.includes('-y');
+const targetArg = args.find((a) => a.startsWith('--for='));
+const target = targetArg ? targetArg.slice('--for='.length) : null;
 
-runWizard({ nonInteractive }).catch((err) => {
+// Treat piped/CI runs (no TTY on stdin OR stdout) as non-interactive so the
+// wizard never blocks on a prompt that can't be answered. The interactive
+// menu is only opened when both stdin and stdout are real terminals.
+const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+const nonInteractive = explicitNonInteractive || !hasTty;
+
+runWizard({ nonInteractive, target }).catch((err) => {
   console.error(`\n  ✗ Setup failed: ${err.message}\n`);
   process.exit(1);
 });

package/lib/non-oc-wizard.js

@@ -0,0 +1,241 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { select } from '@inquirer/prompts';
+import { isClaudeCodeInstalled, isCursorInstalled } from './detect.js';
+import { configureClaudeCode, configureCursor } from './tool-config.js';
+import { header, info, success, warn, blank } from './ui.js';
+import { readConfig } from './config.mjs';
+
+const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+
+const PATH_LABELS = {
+  js: 'JS/TS agent (LangChain, LangGraph, Mastra, etc.)',
+  python: 'Python agent (LangChain, LlamaIndex, CrewAI, etc.)',
+  mcp: 'Cursor / Claude Code / other MCP tool',
+  docs: "Just point me at docs, I'll integrate manually",
+  'install-oc': 'Install OpenClaw first — exit',
+};
+
+const VALID_TARGETS = new Set(Object.keys(PATH_LABELS).concat(['langchain', 'claude-code']));
+
+/**
+ * Inspect cwd to guess what the user is building. Returns one of the path
+ * keys, or null if we can't tell. Order matters: detect-by-file beats
+ * detect-by-installed-tool, since cwd evidence is stronger than "the user
+ * has Cursor installed somewhere on this machine."
+ */
+export function detectDefaultPath(cwd = process.cwd()) {
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const allDeps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+      };
+      const jsAgentMarkers = ['langchain', '@langchain/core', '@langchain/langgraph', '@mastra/core', 'crewai-js', 'llamaindex'];
+      if (jsAgentMarkers.some((m) => Object.prototype.hasOwnProperty.call(allDeps, m))) {
+        return 'js';
+      }
+      // Generic JS project still defaults to JS (cheaper than asking).
+      return 'js';
+    } catch {
+      // fall through
+    }
+  }
+
+  if (existsSync(join(cwd, 'requirements.txt')) || existsSync(join(cwd, 'pyproject.toml'))) {
+    return 'python';
+  }
+
+  if (isCursorInstalled() || isClaudeCodeInstalled()) {
+    return 'mcp';
+  }
+
+  return null;
+}
+
+function normalizeTarget(target) {
+  if (!target) return null;
+  const t = String(target).toLowerCase();
+  if (!VALID_TARGETS.has(t)) return null;
+  // Aliases — friendly synonyms map to canonical path keys.
+  if (t === 'langchain') return 'js';
+  if (t === 'claude-code') return 'mcp';
+  return t;
+}
+
+async function emitPathChosen(path) {
+  const config = readConfig();
+  if (!config.api_key) return; // wizard didn't get to provision; can't authenticate
+  try {
+    await fetch(`${PLATFORM_URL}/v1/telemetry`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${config.api_key}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        product: 'cli',
+        event_type: 'wizard_path_chosen',
+        payload: { path, platform: process.platform },
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    // Best-effort — never let telemetry break the install path.
+  }
+}
+
+function showJsPath() {
+  blank();
+  success('JS/TS integration');
+  blank();
+  info('Install:');
+  info('  npm install @robot-resources/router');
+  blank();
+  info('Use:');
+  info('  import { routePrompt } from \'@robot-resources/router/routing\';');
+  info('  const decision = routePrompt(\'write a python function\');');
+  info('  console.log(decision.selected_model); // e.g. \'claude-haiku-4-5\'');
+  blank();
+  info('Full docs: https://robotresources.ai/docs/langchain');
+  blank();
+}
+
+function showPythonPath() {
+  blank();
+  success('Python integration');
+  blank();
+  info('Install:');
+  info('  pip install robot-resources');
+  blank();
+  info('Use:');
+  info('  from robot_resources.router import route');
+  info('  decision = route(\'write a python function\')');
+  info('  print(decision[\'selected_model\'])  # e.g. \'claude-haiku-4-5\'');
+  blank();
+  info('Prefer no SDK? POST directly to https://api.robotresources.ai/v1/route');
+  info('with httpx / requests / any HTTP client. See docs.');
+  blank();
+  info('Full docs: https://robotresources.ai/docs/crewai');
+  blank();
+}
+
+function showMcpPath() {
+  blank();
+  success('MCP tool integration');
+  blank();
+  let cursorOk = false;
+  let claudeOk = false;
+  if (isCursorInstalled()) {
+    try {
+      const result = configureCursor();
+      cursorOk = result?.action === 'configured' || result?.action === 'already_configured';
+      info(`Cursor: ${cursorOk ? 'configured' : 'see manual instructions below'}`);
+    } catch {
+      warn('Cursor: failed to write ~/.cursor/mcp.json automatically');
+    }
+  }
+  if (isClaudeCodeInstalled()) {
+    try {
+      const result = configureClaudeCode();
+      claudeOk = result?.action === 'configured' || result?.action === 'already_configured';
+      info(`Claude Code: ${claudeOk ? 'configured' : 'see manual instructions below'}`);
+    } catch {
+      warn('Claude Code: failed to write ~/.claude/settings.json automatically');
+    }
+  }
+  if (!cursorOk && !claudeOk) {
+    info('We did not detect Cursor or Claude Code on this machine.');
+    info('Manual setup: https://robotresources.ai/docs/cursor-mcp');
+  }
+  blank();
+}
+
+function showDocsPath() {
+  blank();
+  success('Docs');
+  blank();
+  info('Integration guides: https://robotresources.ai/docs');
+  info('HTTP API:          https://robotresources.ai/docs/http-api');
+  info('GitHub:            https://github.com/robot-resources/packages');
+  blank();
+}
+
+function showInstallOcPath() {
+  blank();
+  info('OpenClaw is the easiest way to use Robot Resources.');
+  info('Install OpenClaw first (https://openclaw.dev), then re-run:');
+  info('  npx robot-resources');
+  blank();
+}
+
+function runPath(path) {
+  switch (path) {
+    case 'js': showJsPath(); break;
+    case 'python': showPythonPath(); break;
+    case 'mcp': showMcpPath(); break;
+    case 'docs': showDocsPath(); break;
+    case 'install-oc': showInstallOcPath(); break;
+    default: showInstallOcPath(); break;
+  }
+}
+
+/**
+ * Runs the non-OC wizard. Three modes:
+ * - target supplied (--for=<target>): run that path directly, no prompt
+ * - non-interactive AND no target: print hint with --for= options and exit
+ * - interactive: 5-option menu via @inquirer/prompts.select
+ */
+export async function runNonOcWizard({ nonInteractive = false, target = null } = {}) {
+  const normalized = normalizeTarget(target);
+
+  if (normalized) {
+    runPath(normalized);
+    await emitPathChosen(normalized);
+    return;
+  }
+
+  if (nonInteractive) {
+    info('Robot Resources requires OpenClaw, which we did not detect on this machine.');
+    info('To bypass this prompt in CI / non-TTY contexts, re-run with --for=<target>:');
+    info('  npx robot-resources --for=langchain      # JS/TS agent');
+    info('  npx robot-resources --for=python         # Python agent');
+    info('  npx robot-resources --for=cursor         # Cursor MCP config');
+    info('  npx robot-resources --for=claude-code    # Claude Code MCP config');
+    info('  npx robot-resources --for=docs           # docs URL');
+    blank();
+    return;
+  }
+
+  // Interactive menu.
+  header();
+  info('Robot Resources requires OpenClaw, which we did not detect on this machine.');
+  info('What are you building? Pick the closest match — we\'ll show the install steps.');
+  blank();
+
+  const defaultPath = detectDefaultPath() ?? 'js';
+
+  let chosen;
+  try {
+    chosen = await select({
+      message: 'What are you building?',
+      default: defaultPath,
+      choices: [
+        { name: PATH_LABELS.js, value: 'js' },
+        { name: PATH_LABELS.python, value: 'python' },
+        { name: PATH_LABELS.mcp, value: 'mcp' },
+        { name: PATH_LABELS.docs, value: 'docs' },
+        { name: PATH_LABELS['install-oc'], value: 'install-oc' },
+      ],
+    });
+  } catch (err) {
+    // User hit Ctrl-C or terminal closed — exit cleanly.
+    if (err && (err.name === 'ExitPromptError' || err.code === 'ABORT_ERR')) return;
+    throw err;
+  }
+
+  runPath(chosen);
+  await emitPathChosen(chosen);
+}

package/lib/tool-config.js

@@ -301,7 +301,7 @@ function configureOpenClaw() {
       );
     }
 
-    instructions.push('Docs: https://github.com/robot-resources/robot-resources');
+    instructions.push('Docs: https://github.com/robot-resources/packages');
 
     return {
       name: 'OpenClaw',
@@ -339,7 +339,7 @@ function printManualInstructions() {
       '  #   OpenAI(base_url="http://localhost:3838/v1")',
       '  #   model = "gemini-2.5-flash"',
       '',
-      'Docs: https://github.com/robot-resources/robot-resources',
+      'Docs: https://github.com/robot-resources/packages',
     ],
   };
 }

package/lib/wizard.js

@@ -7,6 +7,7 @@ import { getOrCreateMachineId } from './machine-id.js';
 import { configureToolRouting, registerScraperMcp, restartOpenClawGateway } from './tool-config.js';
 import { checkHealth } from './health-report.js';
 import { header, step, success, warn, error, info, blank, summary } from './ui.js';
+import { runNonOcWizard } from './non-oc-wizard.js';
 
 // Stamped onto every CLI telemetry payload so we can tell which `robot-resources`
 // version a user actually ran. Without this, npx-cached old installers look
@@ -41,33 +42,20 @@ const CLI_VERSION = (() => {
  *
  * No Python, no venv, no systemd, no port probe.
  */
-export async function runWizard({ nonInteractive = false } = {}) {
+export async function runWizard({ nonInteractive = false, target = null } = {}) {
   header();
 
-  // Non-OC interactive early-exit. Without this, a human running
-  // `npx robot-resources` on a machine without OpenClaw would still
-  // provision an api_key, fire wizard_started + install_complete
-  // telemetry, and write ~/.robot-resources/config.json — six no-op
-  // side effects against a machine that can't actually use the product.
-  // Non-interactive callers (CI, agents, scripts that pre-set RR_API_KEY)
-  // bypass: they explicitly chose to run the wizard.
-  if (!isOpenClawInstalled() && !nonInteractive) {
-    info('Robot Resources requires OpenClaw, which we did not detect on this machine.');
-    info('Install OpenClaw first (https://openclaw.dev), then re-run:');
-    info('  npx robot-resources');
-    blank();
-    info('If you are integrating Robot Resources into a non-OC agent, see PR 7 docs');
-    info('(coming soon — https://robotresources.ai/docs/integrations).');
-    return;
-  }
-
+  // Detect OC once up front. Used both to branch into the non-OC wizard and
+  // to tag the wizard_started payload, so the funnel can be segmented OC vs
+  // non-OC without a second event type.
+  const openclawDetected = isOpenClawInstalled();
   const wizardStartMs = Date.now();
 
   const results = {
     auth: false,
     authMethod: null, // 'config' | 'apikey' | 'auto'
     pluginInstalled: false,
-    openclawDetected: false,
+    openclawDetected,
     openclawConfigPatched: false,
     scraperMcpRegistered: false,
     scraper: false,
@@ -75,9 +63,11 @@ export async function runWizard({ nonInteractive = false } = {}) {
 
   // ── Step 0: Provision API key (before anything else) ────────────────────
   //
-  // Provision early so config.json exists before any tool installs.
-  // If the session dies later, telemetry still works for all tools.
-  // Single fetch() with 10s timeout — no prompts, no browser.
+  // Runs for BOTH the OC and non-OC paths. Provisioning before the non-OC
+  // hand-off closes the funnel blind spot where every non-OpenClaw install
+  // was invisible to telemetry (no api_keys row, no wizard_started, no
+  // agent_signup_meta). If the session dies later, telemetry still works
+  // for all tools. Single fetch() with 10s timeout — no prompts, no browser.
 
   {
     const config = readConfig();
@@ -121,10 +111,11 @@ export async function runWizard({ nonInteractive = false } = {}) {
 
   // ── Funnel marker: wizard_started ───────────────────────────────────────
   //
-  // Sent immediately after auth so we have proof the wizard reached this
-  // point even if any install step crashes. Pairs with install_complete at
-  // the end to give us a "started → completed" funnel for diagnosing silent
-  // signups. Fire-and-forget — never fatal.
+  // Sent immediately after auth, before either path branches, so we have
+  // proof the wizard reached this point even if a later step crashes. Pairs
+  // with install_complete (OC path) or wizard_path_chosen (non-OC path) to
+  // give us a "started → done" funnel. The openclaw_detected field lets us
+  // segment OC vs non-OC funnels without a second event type.
   //
   // Timeout asymmetry vs install_complete (5s, no retry vs 10s × 2 attempts):
   // wizard_started is a best-effort funnel marker — losing it just means we
@@ -149,6 +140,7 @@ export async function runWizard({ nonInteractive = false } = {}) {
             cli_version: CLI_VERSION,
             auth_method: results.authMethod,
             non_interactive: nonInteractive,
+            openclaw_detected: openclawDetected,
           },
         }),
         signal: AbortSignal.timeout(5_000),
@@ -158,6 +150,15 @@ export async function runWizard({ nonInteractive = false } = {}) {
     }
   }
 
+  // Non-OC branch. Hands off to the multi-agent compatibility wizard which
+  // routes the user to the right install path (npm install / pip install /
+  // MCP config / docs / install-OC). The non-OC wizard's wizard_path_chosen
+  // telemetry now fires too, since Step 0 above provisioned an api_key.
+  if (!openclawDetected) {
+    await runNonOcWizard({ nonInteractive, target });
+    return;
+  }
+
   // ── Step 1: Tool Routing Configuration ──────────────────────────────────
   //
   // Installs the OC plugin (which is @robot-resources/router — the router
@@ -171,7 +172,6 @@ export async function runWizard({ nonInteractive = false } = {}) {
   const toolResults = configureToolRouting();
   results.tools = toolResults;
 
-  results.openclawDetected = isOpenClawInstalled();
   const ocResult = toolResults.find((r) => r.name === 'OpenClaw');
   if (ocResult) {
     results.pluginInstalled =
@@ -389,7 +389,7 @@ export async function runWizard({ nonInteractive = false } = {}) {
   // Telegram survives this restart. If the session dies here, the agent
   // picks up on the next message with all tools loaded.
 
-  if (isOpenClawInstalled() && (results.tools?.some(r => r.action === 'installed') || scraperRegistered)) {
+  if (openclawDetected && (results.tools?.some(r => r.action === 'installed') || scraperRegistered)) {
     try {
       await restartOpenClawGateway();
       success('OpenClaw gateway restarted');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robot-resources",
-  "version": "1.10.6",
+  "version": "1.11.1",
   "description": "Robot Resources — AI agent tools. One command to install everything.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "README.md"
   ],
   "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
     "@robot-resources/router": "*",
     "@robot-resources/scraper": "*"
   },
@@ -45,7 +46,7 @@
   },
   "homepage": "https://robotresources.ai",
   "bugs": {
-    "url": "https://github.com/robot-resources/robot-resources/issues"
+    "url": "https://github.com/robot-resources/packages/issues"
   },
   "publishConfig": {
     "access": "public"