robot-resources 1.11.1 → 1.12.0

package/bin/setup.js

@@ -1,20 +1,32 @@
 #!/usr/bin/env node
 
-import { runWizard } from '../lib/wizard.js';
+import { runWizard, runUninstallCommand } from '../lib/wizard.js';
 
 const args = process.argv.slice(2);
-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;
 
-// 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;
+// --uninstall ships in Phase 0 as the counterpart to install. --purge also
+// wipes ~/.robot-resources/config.json (api_key + claim_url); without it,
+// the api_key is preserved across a reinstall.
+if (args.includes('--uninstall')) {
+  const purge = args.includes('--purge');
+  runUninstallCommand({ purge }).catch((err) => {
+    console.error(`\n  ✗ Uninstall failed: ${err.message}\n`);
+    process.exit(1);
+  });
+} else {
+  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, target }).catch((err) => {
-  console.error(`\n  ✗ Setup failed: ${err.message}\n`);
-  process.exit(1);
-});
+  // 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/detect.js

@@ -125,3 +125,127 @@ export function isClaudeCodeInstalled() {
 export function isCursorInstalled() {
   return existsSync(join(homedir(), '.cursor'));
 }
+
+// ── Agent-runtime detection (Phase 3) ─────────────────────────────────────
+//
+// Used by the non-OC wizard to pick which shim to install: a NODE_OPTIONS
+// shell line for Node agents, or `pip install robot-resources` for Python.
+// Returns { kind: 'node'|'python'|null, evidence: string[] } so the wizard
+// can show the user WHY we picked a path (debuggable + builds trust).
+//
+// "Evidence" is the dep markers we found, in priority order. Empty string
+// means a generic project (e.g. just package.json, no LLM SDK deps yet) —
+// still picks the language but with low confidence.
+
+const NODE_AGENT_DEPS = [
+  '@anthropic-ai/sdk',
+  'openai',
+  '@google/generative-ai',
+  '@google-ai/generativelanguage',
+  'langchain',
+  '@langchain/core',
+  '@langchain/anthropic',
+  '@langchain/openai',
+  '@langchain/google-genai',
+  '@langchain/langgraph',
+  '@mastra/core',
+  'crewai-js',
+  'llamaindex',
+  'ai', // Vercel AI SDK
+];
+
+const PYTHON_AGENT_DEPS = [
+  'anthropic',
+  'openai',
+  'google-generativeai',
+  'langchain',
+  'langchain-anthropic',
+  'langchain-openai',
+  'langchain-google-genai',
+  'langgraph',
+  'crewai',
+  'llama-index',
+  'llama_index',
+];
+
+/**
+ * Inspect cwd for evidence of a Node agent project. Returns null if no
+ * package.json, or `{ evidence: [...] }` describing matched dep markers
+ * (empty list means "Node project but no LLM-SDK deps detected" — generic).
+ */
+export function detectNodeAgent(cwd = process.cwd()) {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const allDeps = {
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+      ...(pkg.peerDependencies ?? {}),
+    };
+    const evidence = NODE_AGENT_DEPS.filter(
+      (d) => Object.prototype.hasOwnProperty.call(allDeps, d),
+    );
+    return { evidence };
+  } catch {
+    // package.json unreadable but exists — call it Node, no evidence
+    return { evidence: [] };
+  }
+}
+
+/**
+ * Inspect cwd for evidence of a Python agent project. Looks at
+ * requirements.txt + pyproject.toml. Returns null if neither exists, or
+ * `{ evidence: [...] }`. Empty evidence still resolves to Python — many
+ * agent projects use ad-hoc deps not in our markers list.
+ */
+export function detectPythonAgent(cwd = process.cwd()) {
+  const reqPath = join(cwd, 'requirements.txt');
+  const pyProjPath = join(cwd, 'pyproject.toml');
+  const hasReq = existsSync(reqPath);
+  const hasPy = existsSync(pyProjPath);
+  if (!hasReq && !hasPy) return null;
+
+  const text = [
+    hasReq ? safeRead(reqPath) : '',
+    hasPy ? safeRead(pyProjPath) : '',
+  ].join('\n').toLowerCase();
+
+  const evidence = PYTHON_AGENT_DEPS.filter((d) => {
+    // Match `dep`, `dep==`, `dep>=`, `dep[extras]`, or `"dep"`/`'dep'` in
+    // pyproject's dependencies array. Word-boundary on the left, anything
+    // version-ish on the right.
+    const escaped = d.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(^|[\\s"'\\[])${escaped}(\\s|[<>=!~\\["',]|$)`, 'm');
+    return re.test(text);
+  });
+
+  return { evidence };
+}
+
+function safeRead(path) {
+  try { return readFileSync(path, 'utf-8'); } catch { return ''; }
+}
+
+/**
+ * Decide which shim to install when OpenClaw is NOT detected. Picks Node OR
+ * Python based on cwd shape. When BOTH are present (full-stack monorepo
+ * with package.json AND pyproject.toml) the caller is responsible for
+ * resolving the ambiguity (interactively, or default to JS in --yes mode
+ * per the team decision in the plan).
+ *
+ * Returns one of:
+ *   { kind: 'node',   evidence: [...] }
+ *   { kind: 'python', evidence: [...] }
+ *   { kind: 'both',   node: {...}, python: {...} }
+ *   { kind: null }     — unknown project shape, no clear path
+ */
+export function detectAgentRuntime(cwd = process.cwd()) {
+  const node = detectNodeAgent(cwd);
+  const python = detectPythonAgent(cwd);
+  if (node && python) return { kind: 'both', node, python };
+  if (node) return { kind: 'node', evidence: node.evidence };
+  if (python) return { kind: 'python', evidence: python.evidence };
+  return { kind: null };
+}

package/lib/install-node-shim.js

@@ -0,0 +1,142 @@
+import { writeShellLine, hasShellLine } from './shell-config.js';
+import { readConfig } from './config.mjs';
+import { detectNodeAgent } from './detect.js';
+
+const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+
+/**
+ * Install the Node shim into the user's shell config. Phase 3 entry for
+ * the non-OC Node path.
+ *
+ * Steps:
+ *   1. Append the marker block to detected rc files (zsh / bash / fish)
+ *      via shell-config.writeShellLine. Idempotent: re-running does nothing
+ *      if the block is already present.
+ *   2. Emit `node_shim_installed` telemetry with the shell list, sdks
+ *      detected, dry-run flag, plus per-file errors.
+ *
+ * The user has to start a new shell (or `source` the file) for the
+ * NODE_OPTIONS to take effect — we tell them this in the wizard's
+ * post-install message. For Phase 3 we don't try to mutate the running
+ * shell; that's a Phase 6 nice-to-have.
+ *
+ * Windows: shell-config.writeShellLine returns no rc files on Windows
+ * (we only support POSIX in P3). The wizard prints manual instructions
+ * for Windows users in `non-oc-wizard.js`.
+ *
+ * Returns a UI-friendly result the wizard can format and print.
+ */
+export async function installNodeShim({ cwd = process.cwd(), dryRun = false } = {}) {
+  if (process.platform === 'win32') {
+    await emit({
+      shell: 'unsupported',
+      shell_config_path: null,
+      sdks_detected: detectSdks(cwd),
+      dry_run: dryRun,
+      reason: 'windows_not_supported_yet',
+    });
+    return {
+      ok: false,
+      reason: 'windows_not_supported_yet',
+      message:
+        'Windows shell-config writing is not yet supported. Set ' +
+        'NODE_OPTIONS=--require @robot-resources/router/auto manually in your ' +
+        'system environment variables, or wait for Phase 6.',
+    };
+  }
+
+  const sdks = detectSdks(cwd);
+
+  if (dryRun) {
+    await emit({
+      shell: 'dryrun',
+      shell_config_path: null,
+      sdks_detected: sdks,
+      dry_run: true,
+      reason: null,
+    });
+    return { ok: true, message: 'Dry-run: would have written NODE_OPTIONS to shell rc.' };
+  }
+
+  const alreadyInstalled = hasShellLine();
+  const result = writeShellLine();
+
+  // Single shell value for the funnel even though we may have written to
+  // multiple rc files. Pick the dominant one for telemetry.
+  const dominant = pickDominantShell(result.written);
+
+  await emit({
+    shell: dominant,
+    shell_config_path: result.written.join(','),
+    sdks_detected: sdks,
+    dry_run: false,
+    already_installed: alreadyInstalled,
+    files_written: result.written.length,
+    files_with_errors: result.errors.length,
+    error_messages: result.errors.map((e) => `${e.path}: ${e.message}`).slice(0, 3),
+  });
+
+  if (alreadyInstalled && result.written.length === 0) {
+    return {
+      ok: true,
+      already: true,
+      message: 'NODE_OPTIONS auto-attach already installed. No changes made.',
+    };
+  }
+
+  if (result.written.length === 0 && result.errors.length > 0) {
+    return {
+      ok: false,
+      message: `Could not write to any shell rc file. Errors: ${result.errors.map((e) => e.message).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: true,
+    written: result.written,
+    errors: result.errors,
+    message:
+      `Installed NODE_OPTIONS auto-attach in ${result.written.length} shell file(s). ` +
+      'Open a new terminal (or source the file) for it to take effect.',
+  };
+}
+
+function detectSdks(cwd) {
+  const result = detectNodeAgent(cwd);
+  return result?.evidence ?? [];
+}
+
+function pickDominantShell(paths) {
+  // Use process.env.SHELL as the tiebreaker — that's the user's actual
+  // login shell. Fall back to the first written file's basename.
+  const shellEnv = (process.env.SHELL || '').toLowerCase();
+  if (shellEnv.includes('zsh')) return 'zsh';
+  if (shellEnv.includes('fish')) return 'fish';
+  if (shellEnv.includes('bash')) return 'bash';
+  if (paths[0]?.endsWith('.zshrc')) return 'zsh';
+  if (paths[0]?.endsWith('.bashrc') || paths[0]?.endsWith('.bash_profile')) return 'bash';
+  if (paths[0]?.endsWith('config.fish')) return 'fish';
+  return 'unknown';
+}
+
+async function emit(payload) {
+  const config = readConfig();
+  if (!config.api_key) return;
+  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: 'node_shim_installed',
+        payload: { ...payload, platform: process.platform },
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    // Best-effort — never let telemetry break the install path.
+  }
+}

package/lib/install-python-shim.js

@@ -0,0 +1,107 @@
+import { spawnSync } from 'node:child_process';
+import { detectVenv, runPipInstall } from './venv-detect.js';
+import { readConfig } from './config.mjs';
+import { detectPythonAgent } from './detect.js';
+
+const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+
+/**
+ * Install the Python shim into the user's active/cwd venv. Phase 3 entry
+ * for the non-OC Python path.
+ *
+ * Steps:
+ *   1. Resolve Python via detectVenv. Bail with `confidence: 'low'` if we
+ *      can't find a venv — we never `pip install` into system Python (can
+ *      break OS Python on Linux).
+ *   2. Run `pip install --upgrade robot-resources`. Captures exit code +
+ *      stderr tail for telemetry.
+ *   3. Emit `python_shim_installed` telemetry with venv kind, Python
+ *      version, detected SDK markers, pip exit code.
+ *
+ * Returns a UI-friendly result the wizard can format and print. Never
+ * throws — any unexpected error becomes a structured `{ ok: false, ... }`.
+ */
+export async function installPythonShim({ cwd = process.cwd() } = {}) {
+  const venv = detectVenv(cwd);
+
+  if (!venv.python) {
+    await emit({
+      kind: 'none',
+      python_version: null,
+      sdks_detected: detectSdks(cwd),
+      pip_exit_code: null,
+      reason: 'no_venv_found',
+    });
+    return {
+      ok: false,
+      reason: 'no_venv_found',
+      message:
+        'No active venv or ./.venv detected. Activate your venv first ' +
+        '(source .venv/bin/activate) or pass --python=/path/to/python, ' +
+        'then re-run.',
+    };
+  }
+
+  const pipResult = runPipInstall({
+    python: venv.python,
+    packageSpec: 'robot-resources>=0.2.0',
+  });
+
+  const pythonVersion = readPythonVersion(venv.python);
+  const sdks = detectSdks(cwd);
+
+  await emit({
+    kind: venv.kind,
+    python_version: pythonVersion,
+    sdks_detected: sdks,
+    pip_exit_code: pipResult.code,
+    pip_stderr_tail: pipResult.ok ? null : pipResult.stderr,
+  });
+
+  return {
+    ok: pipResult.ok,
+    venv,
+    pythonVersion,
+    sdks,
+    pipResult,
+    message: pipResult.ok
+      ? `Installed robot-resources into ${venv.kind} venv (${venv.python})`
+      : `pip install failed (exit ${pipResult.code}): ${pipResult.stderr.slice(0, 200)}`,
+  };
+}
+
+function detectSdks(cwd) {
+  const result = detectPythonAgent(cwd);
+  return result?.evidence ?? [];
+}
+
+function readPythonVersion(python) {
+  try {
+    const r = spawnSync(python, ['--version'], { encoding: 'utf-8' });
+    return (r.stdout || r.stderr || '').trim().replace(/^Python\s+/, '');
+  } catch {
+    return null;
+  }
+}
+
+async function emit(payload) {
+  const config = readConfig();
+  if (!config.api_key) return;
+  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: 'python_shim_installed',
+        payload: { ...payload, platform: process.platform },
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    // Best-effort — never let telemetry break the install path.
+  }
+}

package/lib/non-oc-wizard.js

@@ -5,6 +5,8 @@ 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';
+import { installNodeShim } from './install-node-shim.js';
+import { installPythonShim } from './install-python-shim.js';
 
 const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
 
@@ -87,38 +89,61 @@ async function emitPathChosen(path) {
   }
 }
 
-function showJsPath() {
+async 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\'');
+
+  const result = await installNodeShim();
+  if (result.ok) {
+    if (result.already) {
+      info(result.message);
+    } else {
+      success(result.message);
+      for (const path of result.written ?? []) {
+        info(`  • ${path}`);
+      }
+    }
+    blank();
+    info('Once your shell picks up the new NODE_OPTIONS, every Node agent on');
+    info('this machine routes Anthropic SDK calls through Robot Resources.');
+    info('Open a new terminal — or run:  source ~/.zshrc   (or your shell rc)');
+  } else {
+    warn(result.message);
+    blank();
+    info('Manual install (paste into ~/.zshrc or ~/.bashrc):');
+    info('  export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"');
+  }
   blank();
-  info('Full docs: https://robotresources.ai/docs/langchain');
+  info('Docs: https://robotresources.ai/docs/langchain');
   blank();
 }
 
-function showPythonPath() {
+async 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.');
+
+  const result = await installPythonShim();
+  if (result.ok) {
+    success(result.message);
+    if (result.sdks?.length) {
+      info(`  Detected SDKs: ${result.sdks.join(', ')}`);
+    }
+    blank();
+    info('Set RR_AUTOATTACH=1 in your shell, then run your Python agent.');
+    info('Every anthropic.Anthropic() instance routes through Robot Resources.');
+    info('  echo \'export RR_AUTOATTACH=1\' >> ~/.zshrc   # or your shell rc');
+  } else {
+    warn(result.message);
+    blank();
+    info('Manual install (run inside your venv):');
+    info('  pip install --upgrade robot-resources');
+    info('Then set:');
+    info('  export RR_AUTOATTACH=1');
+  }
   blank();
-  info('Full docs: https://robotresources.ai/docs/crewai');
+  info('Docs: https://robotresources.ai/docs/crewai');
   blank();
 }
 
@@ -171,10 +196,10 @@ function showInstallOcPath() {
   blank();
 }
 
-function runPath(path) {
+async function runPath(path) {
   switch (path) {
-    case 'js': showJsPath(); break;
-    case 'python': showPythonPath(); break;
+    case 'js': await showJsPath(); break;
+    case 'python': await showPythonPath(); break;
     case 'mcp': showMcpPath(); break;
     case 'docs': showDocsPath(); break;
     case 'install-oc': showInstallOcPath(); break;
@@ -192,7 +217,7 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
   const normalized = normalizeTarget(target);
 
   if (normalized) {
-    runPath(normalized);
+    await runPath(normalized);
     await emitPathChosen(normalized);
     return;
   }
@@ -206,6 +231,7 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
     info('  npx robot-resources --for=claude-code    # Claude Code MCP config');
     info('  npx robot-resources --for=docs           # docs URL');
     blank();
+    await emitPathChosen('noninteractive_no_target');
     return;
   }
 
@@ -231,11 +257,16 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
       ],
     });
   } catch (err) {
-    // User hit Ctrl-C or terminal closed — exit cleanly.
-    if (err && (err.name === 'ExitPromptError' || err.code === 'ABORT_ERR')) return;
+    // User hit Ctrl-C or terminal closed — exit cleanly, but mark the funnel
+    // so we can distinguish "agent shown the prompt and bailed" from
+    // "wizard never reached the prompt at all" in Supabase.
+    if (err && (err.name === 'ExitPromptError' || err.code === 'ABORT_ERR')) {
+      await emitPathChosen('aborted');
+      return;
+    }
     throw err;
   }
 
-  runPath(chosen);
+  await runPath(chosen);
   await emitPathChosen(chosen);
 }

package/lib/shell-config.js

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Idempotent writer for the NODE_OPTIONS auto-attach line in shell rc files.
+ *
+ * Phase 3 ships POSIX-only support: zsh, bash, fish. Windows ships a printed-
+ * instructions fallback (Phase 6 problem). Every write is wrapped in a
+ * marker block so `--uninstall` can find and remove cleanly without
+ * regex-matching against the user's actual shell content:
+ *
+ *     # >>> robot-resources: NODE_OPTIONS auto-attach >>>
+ *     export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"
+ *     # <<< robot-resources <<<
+ *
+ * Behavior decisions (see plan):
+ *   - If NODE_OPTIONS is already set with a different --require (rare; e.g.
+ *     dd-trace), append ours after theirs. Both load. The user keeps their
+ *     existing tooling. The shell expansion `${NODE_OPTIONS:-} ...` handles
+ *     this correctly — POSIX shells concat space-separated --require flags.
+ *   - Never clobber. If our marker block already exists, it's a no-op.
+ *   - Write to ALL detected rc files (e.g. user has both .zshrc + .bashrc),
+ *     so the user gets routing in whichever shell they actually open.
+ */
+
+const MARK_BEGIN = '# >>> robot-resources: NODE_OPTIONS auto-attach >>>';
+const MARK_END = '# <<< robot-resources <<<';
+
+const POSIX_LINE =
+  'export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"';
+
+// Fish has different syntax (no `export`, uses `set -x`). Detected separately.
+const FISH_LINE =
+  'set -x NODE_OPTIONS "$NODE_OPTIONS --require @robot-resources/router/auto"';
+
+/**
+ * Discover which rc files are present for this user. Returns a list of
+ * absolute paths in priority order (zsh first, bash second, fish third).
+ * The wizard writes to ALL of them — users frequently edit one shell's
+ * rc and forget another, and we'd rather over-cover than under-cover.
+ */
+export function listShellRcFiles(home = homedir()) {
+  const candidates = [
+    { kind: 'zsh', path: join(home, '.zshrc') },
+    { kind: 'bash', path: join(home, '.bashrc') },
+    { kind: 'bash', path: join(home, '.bash_profile') }, // macOS often uses this
+    { kind: 'fish', path: join(home, '.config', 'fish', 'config.fish') },
+  ];
+  return candidates.filter((c) => existsSync(c.path));
+}
+
+/**
+ * Returns true if at least one rc file already has our marker block.
+ * Used by both the wizard (skip-if-already-installed) and uninstall
+ * (gate the "remove" step).
+ */
+export function hasShellLine(home = homedir()) {
+  for (const { path } of listShellRcFiles(home)) {
+    try {
+      const text = readFileSync(path, 'utf-8');
+      if (text.includes(MARK_BEGIN)) return true;
+    } catch { /* unreadable rc, skip */ }
+  }
+  return false;
+}
+
+/**
+ * Idempotently append the marker block to every detected rc file. Returns
+ * a list of files actually modified (empty if everything already had it).
+ *
+ * Each rc file is treated independently: the writer never aborts the
+ * others on one failure. Per-file errors are returned as warnings the
+ * caller can surface.
+ */
+export function writeShellLine(home = homedir()) {
+  const rcs = listShellRcFiles(home);
+  const written = [];
+  const errors = [];
+
+  if (rcs.length === 0) {
+    // POSIX shells but no rc file yet — create ~/.zshrc on macOS (default
+    // since 10.15), ~/.bashrc on Linux. Better than silently no-op'ing.
+    const fallback = process.platform === 'darwin'
+      ? { kind: 'zsh', path: join(home, '.zshrc') }
+      : { kind: 'bash', path: join(home, '.bashrc') };
+    rcs.push(fallback);
+  }
+
+  for (const rc of rcs) {
+    try {
+      let text = '';
+      try { text = readFileSync(rc.path, 'utf-8'); } catch { /* file may not exist yet */ }
+
+      if (text.includes(MARK_BEGIN)) {
+        // Already installed. Skip silently.
+        continue;
+      }
+
+      const line = rc.kind === 'fish' ? FISH_LINE : POSIX_LINE;
+      const block =
+        (text && !text.endsWith('\n') ? '\n' : '') +
+        '\n' + MARK_BEGIN + '\n' + line + '\n' + MARK_END + '\n';
+
+      // Append, don't rewrite — preserves the user's content exactly.
+      appendFileSync(rc.path, block, { mode: 0o644 });
+      written.push(rc.path);
+    } catch (err) {
+      errors.push({ path: rc.path, message: err.message });
+    }
+  }
+
+  return { written, errors };
+}
+
+/**
+ * Idempotently REMOVE the marker block from every detected rc file.
+ * Mirror of writeShellLine. Returns a list of files actually modified.
+ *
+ * Removal is text-based (find MARK_BEGIN, find MARK_END, splice). If the
+ * block was tampered with — e.g. user manually deleted MARK_END — we leave
+ * the file alone and surface a warning. Never destructive on partial state.
+ */
+export function removeShellLine(home = homedir()) {
+  const rcs = listShellRcFiles(home);
+  const removed = [];
+  const errors = [];
+
+  for (const rc of rcs) {
+    try {
+      const text = readFileSync(rc.path, 'utf-8');
+      const startIdx = text.indexOf(MARK_BEGIN);
+      if (startIdx === -1) continue;
+      const endIdx = text.indexOf(MARK_END, startIdx);
+      if (endIdx === -1) {
+        errors.push({ path: rc.path, message: 'marker_end_missing' });
+        continue;
+      }
+
+      // Splice from MARK_BEGIN through end of MARK_END line + trailing newline.
+      const afterEnd = text.indexOf('\n', endIdx);
+      const sliceEnd = afterEnd === -1 ? text.length : afterEnd + 1;
+
+      // Walk back over the leading newline our writer added so we don't
+      // accumulate blank lines on repeated install/uninstall cycles.
+      let sliceStart = startIdx;
+      while (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart--;
+
+      const next = text.slice(0, sliceStart) +
+        (sliceStart > 0 ? '\n' : '') +
+        text.slice(sliceEnd);
+
+      writeFileSync(rc.path, next, { mode: getMode(rc.path) });
+      removed.push(rc.path);
+    } catch (err) {
+      errors.push({ path: rc.path, message: err.message });
+    }
+  }
+
+  return { removed, errors };
+}
+
+function getMode(path) {
+  try { return statSync(path).mode & 0o777; } catch { return 0o644; }
+}
+
+// Exported for tests + telemetry payloads.
+export { MARK_BEGIN, MARK_END, POSIX_LINE, FISH_LINE };

package/lib/uninstall.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { stripJson5 } from './json5.js';
+import { removeShellLine } from './shell-config.js';
+import { detectVenv } from './venv-detect.js';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Single source of truth for `npx robot-resources --uninstall`.
+ *
+ * Reverses every install path the wizard might have taken:
+ *   1. OC plugin directories under ~/.openclaw/extensions/ (Phase 0)
+ *   2. Our entries in openclaw.json (plugins.entries + plugins.allow +
+ *      mcp.servers) (Phase 0)
+ *   3. NODE_OPTIONS marker block in shell rc files (Phase 3 — Node shim)
+ *   4. `robot-resources` PyPI package in the resolved venv (Phase 3 —
+ *      Python shim)
+ *   5. With --purge: ~/.robot-resources/ config dir (api_key + claim_url)
+ *
+ * `~/.robot-resources/config.json` is preserved by default so a subsequent
+ * re-install reuses the same api_key (and the user's claim_url stays valid).
+ *
+ * Returns { components_removed: string[], errors: { component, message }[] }
+ * for telemetry. Failure to remove one component never aborts the others —
+ * a partial uninstall is still progress, and we want to record what worked.
+ */
+export function runUninstall({ purge = false } = {}) {
+  const components_removed = [];
+  const errors = [];
+
+  // 1. Plugin directories under ~/.openclaw/extensions/
+  const pluginDirs = [
+    { id: 'robot-resources-router', label: 'router_plugin_dir' },
+    { id: 'robot-resources-scraper-oc-plugin', label: 'scraper_plugin_dir' },
+  ];
+  for (const { id, label } of pluginDirs) {
+    const path = join(homedir(), '.openclaw', 'extensions', id);
+    if (!existsSync(path)) continue;
+    try {
+      rmSync(path, { recursive: true, force: true });
+      components_removed.push(label);
+    } catch (err) {
+      errors.push({ component: label, message: err.message });
+    }
+  }
+
+  // 2. openclaw.json — strip our entries from plugins.entries, plugins.allow,
+  //    and mcp.servers. Leave everything else (other plugins, user config) alone.
+  //    Idempotent: if openclaw.json is missing or malformed, skip silently —
+  //    that's the right behavior for "cleanup what you can find."
+  const ocConfigPath = join(homedir(), '.openclaw', 'openclaw.json');
+  if (existsSync(ocConfigPath)) {
+    try {
+      const config = JSON.parse(stripJson5(readFileSync(ocConfigPath, 'utf-8')));
+      let mutated = false;
+
+      if (config?.plugins?.entries) {
+        for (const id of ['robot-resources-router', 'robot-resources-scraper-oc-plugin']) {
+          if (config.plugins.entries[id]) {
+            delete config.plugins.entries[id];
+            mutated = true;
+          }
+        }
+      }
+
+      if (Array.isArray(config?.plugins?.allow)) {
+        const before = config.plugins.allow.length;
+        config.plugins.allow = config.plugins.allow.filter(
+          (id) => id !== 'robot-resources-router' && id !== 'robot-resources-scraper-oc-plugin',
+        );
+        if (config.plugins.allow.length !== before) mutated = true;
+      }
+
+      if (config?.mcp?.servers?.['robot-resources-scraper']) {
+        delete config.mcp.servers['robot-resources-scraper'];
+        mutated = true;
+      }
+
+      if (mutated) {
+        writeFileSync(ocConfigPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        components_removed.push('openclaw_config_entries');
+      }
+    } catch (err) {
+      errors.push({ component: 'openclaw_config_entries', message: err.message });
+    }
+  }
+
+  // 3. Shell config — remove the NODE_OPTIONS marker block from any rc
+  //    files Phase 3's wizard wrote to. Idempotent: no-op if not present.
+  try {
+    const result = removeShellLine();
+    if (result.removed.length > 0) {
+      components_removed.push('shell_config_node_options');
+    }
+    for (const e of result.errors) {
+      errors.push({ component: 'shell_config_node_options', message: `${e.path}: ${e.message}` });
+    }
+  } catch (err) {
+    errors.push({ component: 'shell_config_node_options', message: err.message });
+  }
+
+  // 4. Python shim — `pip uninstall -y robot-resources` against the resolved
+  //    venv. Skip silently if no venv detected (the user may have installed
+  //    via the wizard but already deleted the venv themselves).
+  try {
+    const venv = detectVenv();
+    if (venv.python) {
+      const result = spawnSync(venv.python, ['-m', 'pip', 'uninstall', '-y', 'robot-resources'], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      // pip exits 0 if removed, non-zero if package wasn't installed (also acceptable)
+      if (result.status === 0) {
+        components_removed.push('pip_robot_resources');
+      } else if (result.stderr && /not installed|skipping/i.test(result.stderr)) {
+        // Already gone — count as success silently.
+      } else if (result.status !== null) {
+        // Some other failure; record but don't abort
+        errors.push({
+          component: 'pip_robot_resources',
+          message: `pip exit ${result.status}: ${(result.stderr || '').slice(-200)}`,
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ component: 'pip_robot_resources', message: err.message });
+  }
+
+  // 5. Optionally wipe ~/.robot-resources/config.json (and any siblings)
+  if (purge) {
+    const rrDir = join(homedir(), '.robot-resources');
+    if (existsSync(rrDir)) {
+      try {
+        rmSync(rrDir, { recursive: true, force: true });
+        components_removed.push('rr_config_dir');
+      } catch (err) {
+        errors.push({ component: 'rr_config_dir', message: err.message });
+      }
+    }
+  }
+
+  return { components_removed, errors };
+}

package/lib/venv-detect.js

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/**
+ * Resolve the Python interpreter we'll use for `pip install robot-resources`.
+ *
+ * Resolution order (decided in the plan; never silently install into system
+ * Python — that can break OS Python on Linux):
+ *
+ *   1. $VIRTUAL_ENV — currently-active venv. Strongest signal.
+ *   2. ./.venv/bin/python — common cwd venv (uv, hatch, plain venv default).
+ *   3. ./venv/bin/python — alternative cwd venv name.
+ *   4. pyproject.toml [tool.uv]/[tool.poetry] hint — best effort.
+ *   5. Bail with confidence='low'. Caller prompts user or errors out with
+ *      a `--python=/path/to/python` instruction in non-interactive mode.
+ *
+ * Returns:
+ *   { python: string, kind: 'active'|'cwd-venv'|'pyproject', confidence: 'high' }
+ *   OR
+ *   { python: null,   kind: 'none',                          confidence: 'low' }
+ */
+export function detectVenv(cwd = process.cwd()) {
+  // 1. Active venv — strongest signal.
+  const activeVenv = process.env.VIRTUAL_ENV;
+  if (activeVenv) {
+    const candidate = join(activeVenv, binSubdir(), 'python');
+    const candidate3 = join(activeVenv, binSubdir(), 'python3');
+    if (existsSync(candidate)) {
+      return { python: candidate, kind: 'active', confidence: 'high' };
+    }
+    if (existsSync(candidate3)) {
+      return { python: candidate3, kind: 'active', confidence: 'high' };
+    }
+  }
+
+  // 2. ./.venv (uv default, hatch default, plain venv default)
+  for (const dirname of ['.venv', 'venv']) {
+    const venvDir = join(cwd, dirname);
+    const cands = [
+      join(venvDir, binSubdir(), 'python'),
+      join(venvDir, binSubdir(), 'python3'),
+    ];
+    for (const c of cands) {
+      if (existsSync(c)) {
+        return { python: c, kind: 'cwd-venv', confidence: 'high' };
+      }
+    }
+  }
+
+  // 4. Bail. Never silently install into system Python.
+  return { python: null, kind: 'none', confidence: 'low' };
+}
+
+function binSubdir() {
+  return process.platform === 'win32' ? 'Scripts' : 'bin';
+}
+
+/**
+ * Run `python -m pip install <package>` against the resolved interpreter.
+ * Captures exit code + stderr tail for telemetry. Never throws.
+ *
+ * Phase 3 ships with `--upgrade` so existing 0.1.0 installs migrate to
+ * the auto-attach-capable 0.2.0 transparently.
+ */
+export function runPipInstall({ python, packageSpec, timeoutMs = 120_000 }) {
+  if (!python) {
+    return { ok: false, code: -1, stderr: 'no python interpreter resolved' };
+  }
+  const args = ['-m', 'pip', 'install', '--upgrade', packageSpec];
+  const result = spawnSync(python, args, {
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  // Trim stderr to a sane size for telemetry — pip's full output is huge.
+  const stderr = (result.stderr || '').slice(-500);
+
+  return {
+    ok: result.status === 0,
+    code: result.status,
+    stderr,
+  };
+}

package/lib/wizard.js

@@ -8,6 +8,7 @@ import { configureToolRouting, registerScraperMcp, restartOpenClawGateway } from
 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';
+import { runUninstall } from './uninstall.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
@@ -141,6 +142,11 @@ export async function runWizard({ nonInteractive = false, target = null } = {})
             auth_method: results.authMethod,
             non_interactive: nonInteractive,
             openclaw_detected: openclawDetected,
+            // Phase 3: tags which install branch the wizard is about to take.
+            // 'oc' for the OpenClaw path, 'non-oc' covers everything the
+            // non-OC wizard handles (Node shim, Python shim, MCP, docs).
+            // Finer per-path attribution still comes from wizard_path_chosen.
+            entry: openclawDetected ? 'oc' : 'non-oc',
           },
         }),
         signal: AbortSignal.timeout(5_000),
@@ -398,3 +404,71 @@ export async function runWizard({ nonInteractive = false, target = null } = {})
     }
   }
 }
+
+/**
+ * Uninstall counterpart to runWizard. Removes the OC plugin install side
+ * (router + scraper plugin dirs, openclaw.json entries) via uninstall.js.
+ *
+ * config.json (and its api_key) is preserved by default so a later re-install
+ * keeps the same identity. `--purge` wipes ~/.robot-resources/ as well.
+ *
+ * Telemetry: emits `wizard_uninstalled` with the list of components actually
+ * removed plus any per-component errors. Fire-and-forget — never block the
+ * uninstall on telemetry latency or failure.
+ */
+export async function runUninstallCommand({ purge = false } = {}) {
+  header();
+  step(purge ? 'Uninstalling Robot Resources (purge)...' : 'Uninstalling Robot Resources...');
+
+  const result = runUninstall({ purge });
+
+  blank();
+  if (result.components_removed.length === 0 && result.errors.length === 0) {
+    info('Nothing to remove — Robot Resources was not installed in this account.');
+  } else {
+    if (result.components_removed.length > 0) {
+      success(`Removed: ${result.components_removed.join(', ')}`);
+    }
+    for (const e of result.errors) {
+      warn(`${e.component}: ${e.message}`);
+    }
+  }
+
+  // Preserve the api_key (unless --purge) so re-running `npx robot-resources`
+  // doesn't issue a second key. Tell the user explicitly so they can purge if
+  // they really want a clean slate.
+  if (!purge) {
+    blank();
+    info('Kept ~/.robot-resources/config.json (your api_key + claim_url).');
+    info('Re-run with --purge to wipe it.');
+  }
+
+  // Best-effort telemetry — same shape as the rest of the CLI's calls.
+  try {
+    const config = readConfig();
+    if (config.api_key) {
+      const platformUrl = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+      await fetch(`${platformUrl}/v1/telemetry`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${config.api_key}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          product: 'cli',
+          event_type: 'wizard_uninstalled',
+          payload: {
+            cli_version: CLI_VERSION,
+            purge,
+            components_removed: result.components_removed,
+            error_count: result.errors.length,
+            platform: process.platform,
+          },
+        }),
+        signal: AbortSignal.timeout(5_000),
+      });
+    }
+  } catch {
+    // Non-fatal — telemetry must never block the uninstall path.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robot-resources",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Robot Resources — AI agent tools. One command to install everything.",
   "type": "module",
   "bin": {