agentic-relay 4.3.1 → 5.0.1

package/bin/lib/commands.mjs

@@ -2,22 +2,17 @@
  * Command implementations for the agentrelay CLI. Each returns an envelope payload
  * (the entry adds `ok`/`errors` and chooses the exit code).
  *
- * `session start|send|pay|end` are thin api_v1 wrappers; the caller (a host
- * subagent, or the main agent in direct mode) drives the conversation and
- * reads the agent's RAW turns. Compact specs get banked in the on-disk cache
- * (`cache put`/`ls`/`show`) so transcripts stay out of the main context.
+ * `session start|send|end` are thin api_v1 wrappers; the caller (a host subagent,
+ * or the main agent in direct mode) drives the conversation and reads the agent's
+ * RAW turns. Search results are cached on disk so a repeat search is near-free.
  */
 
-import { readFileSync } from "fs";
 import {
   search as apiSearch,
   sessionStart,
   sessionMessage,
   sessionEnd,
-  sessionPay,
   feedback as apiFeedback,
-  getPaymentPolicy,
-  patchPaymentPolicy,
 } from "./api.mjs";
 import { slugify } from "./config.mjs";
 import { Cache } from "./cache.mjs";
@@ -30,7 +25,6 @@ function normalizeCapability(c) {
   return {
     slug: slugify(name),
     name,
-    type: "dynamic_capability", // single type now; kept for the --dynamic-only filter
     agent_id: c.agent_id || null,
     relevance: typeof c.relevance_score === "number" ? c.relevance_score : null,
     reputation: typeof c.reputation_score === "number" ? c.reputation_score : null,
@@ -60,13 +54,9 @@ export async function cmdSearch(query, opts) {
   const cache = new Cache(opts.cacheDir, { enabled: !opts.noCache });
   const maxResults = opts.max || 25;
 
-  // The buyer-side spend policy snapshot the search API returns alongside the
-  // menu — the agent decides auto-pay-vs-bubble against it (SKILL.md Pay). Pass
-  // it through here so it survives to the CLI's JSON output and gets cached.
-  // On a cache hit the snapshot can be up to the search TTL (1h) stale, so the
-  // payload carries from_cache/cached_at for the caller's pay decision.
+  // A repeat search inside the cache TTL (1h) is served from disk; the payload
+  // carries from_cache/cached_at so the caller knows how fresh the menu is.
   const cachedEntry = opts.refresh ? null : cache.readSearchEntry(query);
-  let paymentContext = cachedEntry ? (cachedEntry.payment_context ?? null) : null;
   let capabilities = cachedEntry ? cachedEntry.capabilities : null;
   const fromCache = Boolean(cachedEntry);
   const cachedAt = cachedEntry ? (cachedEntry.ts ?? null) : null;
@@ -74,13 +64,11 @@ export async function cmdSearch(query, opts) {
   if (!capabilities) {
     const data = await apiSearch(query, {
       apiKey: opts.apiKey,
-      userContext: opts.userContext,
       maxResults,
       timeoutMs: opts.timeoutMs,
     });
-    paymentContext = data.payment_context ?? null;
     capabilities = dedupeSlugs((data.capabilities || []).map(normalizeCapability));
-    cache.writeSearch(query, capabilities, paymentContext);
+    cache.writeSearch(query, capabilities);
     // Seed the index so session start can resolve agent_id without re-searching.
     for (const c of capabilities) {
       if (c.agent_id) {
@@ -93,9 +81,6 @@ export async function cmdSearch(query, opts) {
     }
   }
 
-  if (opts.dynamicOnly) {
-    capabilities = capabilities.filter((c) => c.type === "dynamic_capability");
-  }
   capabilities = capabilities.slice(0, maxResults);
 
   return {
@@ -104,15 +89,13 @@ export async function cmdSearch(query, opts) {
     from_cache: fromCache,
     cached_at: cachedAt,
     capabilities,
-    payment_context: paymentContext,
   };
 }
 
 /**
- * Resolve a slug (or agent_id) to { agentId, slug, name }. Order: cache index →
- * banked spec file → fresh search keyed on the de-kebabed slug. The spec-file
- * fallback lets a depth session resolve even when the cache was filled only by
- * `cache put` during the breadth pass (which doesn't write the index).
+ * Resolve a slug (or agent_id) to { agentId, slug, name }. Order: cache index (seeded
+ * by a prior `search`) → fresh live search keyed on the de-kebabed slug. A cold
+ * `session start` with no prior search still resolves via the live search below.
  * agent_id is the only id needed — the ad_unit + price are resolved server-side.
  */
 export async function resolveCapability(slugOrId, opts) {
@@ -124,14 +107,6 @@ export async function resolveCapability(slugOrId, opts) {
     return { agentId: entry.agent_id, slug, name: entry.name || slug };
   }
 
-  // Banked spec fallback — a breadth subagent stored the agent_id here via `cache put`.
-  if (!opts.refresh) {
-    const spec = cache.readSpec(slug, { ttlMs: Infinity });
-    if (spec && spec.agent_id) {
-      return { agentId: spec.agent_id, slug, name: spec.name || slug };
-    }
-  }
-
   // Fresh search keyed on the human form of the slug.
   const queryGuess = String(slugOrId).replace(/-/g, " ");
   const found = await cmdSearch(queryGuess, { ...opts, refresh: true, max: 25 });
@@ -260,18 +235,7 @@ export async function cmdSession(sub, positionals, opts) {
     return sessionEnd({ sessionId }, net);
   }
 
-  if (sub === "pay") {
-    const sessionId = positionals[0];
-    if (!sessionId) {
-      const e = new Error("usage: agentrelay session pay <session_id> [--credential <mpp_credential>]");
-      e.usage = true;
-      throw e;
-    }
-    // Server-side grant when no --credential; client-side MPP wallet when provided.
-    return sessionPay({ sessionId, paymentCredential: opts.credential || null }, net);
-  }
-
-  const e = new Error(`unknown session subcommand "${sub}" (start|send|end|pay)`);
+  const e = new Error(`unknown session subcommand "${sub}" (start|send|end)`);
   e.usage = true;
   throw e;
 }
@@ -320,140 +284,3 @@ export async function cmdFeedback(sessionId, opts) {
     { apiKey: opts.apiKey, timeoutMs: opts.timeoutMs },
   );
 }
-
-/** Convert a dollar string/number to integer cents; throws a usage error on garbage. */
-export function dollarsToCents(label, value) {
-  const n = Number(value);
-  if (!Number.isFinite(n) || n < 0) {
-    const e = new Error(`${label} must be a non-negative dollar amount (e.g. 5 or 2.50)`);
-    e.usage = true;
-    throw e;
-  }
-  return Math.round(n * 100);
-}
-
-/**
- * Read or update the account's server-canonical autonomous-spend policy.
- * No flags → GET (print current policy). Any flag → PATCH then return the new policy.
- * Dollar flags are converted to cents; the server is canonical (nothing stored locally).
- */
-export async function cmdBudget(opts) {
-  const patch = {};
-  if (opts.autoApprove != null) patch.auto_approve_under_cents = dollarsToCents("--auto-approve", opts.autoApprove);
-  if (opts.dailyCap != null) patch.daily_cap_cents = dollarsToCents("--daily-cap", opts.dailyCap);
-  if (opts.requireHumanOver != null) patch.require_human_over_cents = dollarsToCents("--require-human-over", opts.requireHumanOver);
-  if (opts.perSessionCap != null) patch.per_session_cap_cents = dollarsToCents("--per-session-cap", opts.perSessionCap);
-  if (opts.enable && opts.disable) {
-    const e = new Error("pass only one of --enable / --disable");
-    e.usage = true;
-    throw e;
-  }
-  if (opts.enable) patch.autonomous_enabled = true;
-  if (opts.disable) patch.autonomous_enabled = false;
-
-  const policy = Object.keys(patch).length > 0
-    ? await patchPaymentPolicy(patch, { apiKey: opts.apiKey, timeoutMs: opts.timeoutMs })
-    : await getPaymentPolicy({ apiKey: opts.apiKey, timeoutMs: opts.timeoutMs });
-  return { policy };
-}
-
-/**
- * Stub: real wallet connection is the (deferred) dashboard OAuth flow. The CLI can't
- * provision a wallet, so this just points the user at the dashboard.
- */
-export function cmdConnectWallet() {
-  return {
-    connected: false,
-    message:
-      "Wallet connection is set up from the AttentionMarket dashboard (OAuth flow). " +
-      "The CLI can't provision a wallet yet. Once a wallet is connected, run " +
-      "`agentrelay budget --enable --auto-approve=<$>` so the agent can auto-pay within your limits.",
-  };
-}
-
-export function cmdCache(sub, slug, opts) {
-  const cache = new Cache(opts.cacheDir, { enabled: true });
-  if (sub === "ls" || !sub) {
-    // Triage view read from the spec files themselves (race-safe under the
-    // parallel breadth pass; includes each summary so the main agent can pick
-    // what to `cache show` without opening every file).
-    return {
-      cache_dir: opts.cacheDir,
-      specs: cache.listSpecHeadlines(),
-    };
-  }
-  if (sub === "show") {
-    if (!slug) {
-      const e = new Error("usage: agentrelay cache show <slug>");
-      e.usage = true;
-      throw e;
-    }
-    const spec = cache.readSpec(slug, { ttlMs: Infinity });
-    if (!spec) throw new Error(`no cached spec for "${slug}"`);
-    return { deliverable: spec };
-  }
-  if (sub === "put") {
-    // Persist a distilled result a subagent/main agent produced, so it can be
-    // reviewed (`cache show`) or reused later. JSON from --file or stdin.
-    if (!slug) {
-      const e = new Error("usage: agentrelay cache put <slug> (--file f.json | JSON on stdin)");
-      e.usage = true;
-      throw e;
-    }
-    let raw;
-    try {
-      raw = opts.file ? readFileSync(opts.file, "utf-8") : readFileSync(0, "utf-8");
-    } catch (err) {
-      throw new Error(`could not read deliverable input: ${err.message}`);
-    }
-    let deliverable;
-    try {
-      deliverable = JSON.parse(raw);
-    } catch (err) {
-      const e = new Error(`deliverable must be valid JSON: ${err.message}`);
-      e.usage = true;
-      throw e;
-    }
-    if (!deliverable || typeof deliverable !== "object") {
-      const e = new Error("deliverable must be a JSON object");
-      e.usage = true;
-      throw e;
-    }
-    deliverable.slug = deliverable.slug || slug;
-    deliverable.ts = deliverable.ts || new Date().toISOString();
-    // Soft contract check (schema/deliverable.json spine). Warn-only: a spec
-    // with gaps is still worth banking, and concurrent breadth subagents must
-    // never be blocked by validation.
-    const warnings = [];
-    if (!deliverable.session_id || !String(deliverable.session_id).trim()) {
-      warnings.push("no session_id — build-outcome feedback can't be filed against this consult later");
-    }
-    if (!deliverable.summary || !String(deliverable.summary).trim()) {
-      warnings.push("no summary — `cache ls` triage will show a blank line for this spec");
-    }
-    if (!Array.isArray(deliverable.features) || deliverable.features.length === 0) {
-      warnings.push("no features[] — build-time has no surface map; depth sessions will have to rediscover it");
-    } else {
-      const missingStatus = deliverable.features.filter(
-        (f) => !f || (f.status !== "coded" && f.status !== "surface_only"),
-      ).length;
-      if (missingStatus > 0) {
-        warnings.push(
-          `${missingStatus} feature(s) missing status ("coded"|"surface_only") — build-time can't tell banked code from surface-only`,
-        );
-      }
-    }
-    // Write ONLY the per-slug spec file — no shared index.json mutation — so N
-    // breadth subagents can `cache put` concurrently without clobbering each
-    // other. `cache ls` reads the spec files directly.
-    cache.writeSpec(slug, deliverable);
-    return { stored: true, slug, cache_dir: opts.cacheDir, warnings };
-  }
-  if (sub === "clear") {
-    cache.clear();
-    return { cleared: true, cache_dir: opts.cacheDir };
-  }
-  const e = new Error(`unknown cache subcommand "${sub}" (ls|show|put|clear)`);
-  e.usage = true;
-  throw e;
-}

package/bin/lib/config.mjs

@@ -58,7 +58,7 @@ export function resolveApiKey(flagKey) {
   return readKeyFile(CREDENTIALS_PATH) || readKeyFile(LEGACY_CREDENTIALS_PATH);
 }
 
-/** kebab-case a capability name into a stable slug used for cache + consult. */
+/** kebab-case a capability name into a stable slug (search cache key + session resolution). */
 export function slugify(name) {
   return String(name || "")
     .toLowerCase()

package/bin/lib/sysenv.mjs

@@ -1,60 +1,19 @@
 /**
- * System-environment probes shared by the installer and `agentrelay doctor`.
+ * System-environment probes used by the installer's global-CLI linking.
  *
  * These exist because the failure modes they detect are exactly the ones that
  * made "successful" installs produce `command not found` in the field:
- *  - npx prepends its ephemeral cache .bin to PATH, shadowing (or faking) a
- *    real global install for the lifetime of the npx process
  *  - npm's global prefix may not be writable (system Node → EACCES)
  *  - ~/.npm may contain root-owned files (old sudo npm) which kills BOTH
  *    `npm install -g` and npx itself
  *  - npm's global bin dir may not be on the user's PATH
  */
 
-import { existsSync, realpathSync, accessSync, statSync, constants } from "fs";
+import { existsSync, accessSync, statSync, constants, readdirSync, rmSync } from "fs";
 import { homedir } from "os";
-import { join, sep, dirname } from "path";
+import { join, dirname } from "path";
 import { execSync } from "child_process";
 
-/** Where a command actually resolves on this PATH, or null. */
-export function resolveCommandPath(cmd) {
-  try {
-    const probe = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`;
-    const out = execSync(probe, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
-    return out.split("\n")[0].trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-export function realpathSafe(p) {
-  try {
-    return realpathSync(p);
-  } catch {
-    return p;
-  }
-}
-
-/**
- * True when a resolved bin path is an ephemeral npx/npm-exec shim (or a copy
- * inside the running package itself), not a real install. A dangling symlink
- * also counts as not-a-usable-install.
- */
-export function isEphemeralBin(binPath, pkgRoot) {
-  if (!binPath) return false;
-  let real = binPath;
-  try {
-    real = realpathSync(binPath);
-  } catch {
-    return true;
-  }
-  return (
-    real.includes(`${sep}_npx${sep}`) ||
-    binPath.includes(`${sep}_npx${sep}`) ||
-    (pkgRoot ? real.startsWith(realpathSafe(pkgRoot)) : false)
-  );
-}
-
 /** npm's global prefix (e.g. /opt/homebrew, %AppData%\npm), or null. */
 export function npmGlobalPrefix() {
   try {
@@ -140,6 +99,32 @@ export function dirOnPath(dir, pathVar = process.env.PATH || "") {
   return pathVar.split(delim).map(norm).includes(norm(dir));
 }
 
+/**
+ * Remove ONLY this package's entries from npm's npx cache, so the next
+ * `npx <pkg>` re-resolves from the registry instead of replaying a stale cached
+ * copy (npx reuses its cache for a bare name and won't auto-upgrade). Scoped to
+ * `<npm cache>/_npx/<hash>` dirs whose node_modules contains pkgName — other
+ * tools' npx caches are left alone. Best-effort; never throws.
+ */
+export function clearNpxCacheFor(pkgName) {
+  try {
+    const cacheDir = execSync("npm config get cache", {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!cacheDir) return;
+    const npxDir = join(cacheDir, "_npx");
+    if (!existsSync(npxDir)) return;
+    for (const entry of readdirSync(npxDir)) {
+      if (existsSync(join(npxDir, entry, "node_modules", pkgName))) {
+        try {
+          rmSync(join(npxDir, entry), { recursive: true, force: true });
+        } catch {}
+      }
+    }
+  } catch {}
+}
+
 /** The official npm user-level-prefix recipe for EACCES on the global prefix. */
 export const USER_PREFIX_RECIPE = [
   "mkdir -p ~/.npm-global",

package/bin/relay-core.mjs

@@ -1,18 +1,17 @@
 #!/usr/bin/env node
 
 /**
- * agentrelay (CLI core) — live agent sessions, payments, and deliverable fetch.
+ * agentrelay (CLI core) — live agent sessions and deliverable fetch.
  *
  * Wraps the AttentionMarket REST API so a coding agent can converse with expert
  * "solutions-engineer" capability agents. The caller (a host subagent, or the
- * main agent directly) drives the conversation via the session primitives and
- * banks compact specs in the on-disk cache; raw transcripts stay out of the
- * main context.
+ * main agent directly) drives the conversation via the session primitives; raw
+ * transcripts stay out of the main context.
  *
  * Commands:
  *   agentrelay search <query>          broad discovery (cheap; safe in main context)
- *   agentrelay session start|send|pay|end   drive a live consult
- *   agentrelay cache ls|show|put|clear inspect/manage the on-disk spec cache
+ *   agentrelay session start|send|end  drive a live consult
+ *   agentrelay feedback <id>           rate a session
  *   agentrelay fetch                   download + verify + unpack a paid deliverable
  *
  * Output: a `{ ok, ...payload, errors: [] }` envelope. --json forces machine
@@ -29,13 +28,9 @@ import {
   cmdSearch,
   cmdSession,
   cmdFeedback,
-  cmdCache,
-  cmdBudget,
-  cmdConnectWallet,
   cmdFetchSession,
 } from "./lib/commands.mjs";
 import { cmdFetch } from "./lib/fetch.mjs";
-import { cmdDoctor, fmtDoctor } from "./lib/doctor.mjs";
 import { maybeNotifyUpdate } from "./lib/update-check.mjs";
 
 const EXIT = { OK: 0, PARTIAL: 1, USAGE: 2, AUTH: 3 };
@@ -54,7 +49,6 @@ const FLAGS_WITH_VALUE = new Set([
   "--cache-dir",
   "--timeout",
   "--max",
-  "--user-context",
   "--initial",
   "--task-context",
   "--message",
@@ -62,11 +56,6 @@ const FLAGS_WITH_VALUE = new Set([
   "--score",
   "--text",
   "--file",
-  "--auto-approve",
-  "--daily-cap",
-  "--require-human-over",
-  "--per-session-cap",
-  "--credential",
   "--checksum",
   "--filename",
   "--session",
@@ -155,54 +144,19 @@ const fmtSearch = (e) => {
       lines.push(`        offers paid deliverable${dp}`);
     }
   }
-  // Surface the spend policy in human output too — agents reading --json get
-  // the full payment_context object; humans shouldn't be blind to it.
-  const p = e.payment_context;
-  if (p) {
-    const dol = (c) => (c == null ? "—" : `$${(c / 100).toFixed(2)}`);
-    lines.push(
-      `pay policy: autonomous ${p.autonomous_enabled ? "ON" : "off"}, auto-approve under ${dol(p.auto_approve_under_cents)},` +
-        ` daily cap left ${dol(p.daily_cap_remaining_cents)}, wallet: ${p.wallet?.methods?.length ? p.wallet.methods.join(",") : "none"}` +
-        `${e.from_cache ? " (cached snapshot — `agentrelay budget` for live)" : ""}`,
-    );
-  }
   return lines.join("\n");
 };
 
-const fmtBudget = (e) => {
-  const p = e.policy || {};
-  const dol = (c) => (c == null ? "—" : `$${(c / 100).toFixed(2)}`);
-  return [
-    `autonomous pay: ${p.autonomous_enabled ? "ENABLED" : "disabled (ask every time)"}`,
-    `  auto-approve under:  ${dol(p.auto_approve_under_cents)}`,
-    `  require human over:  ${dol(p.require_human_over_cents)}`,
-    `  daily cap:           ${dol(p.daily_cap_cents)}`,
-    `  per-session cap:     ${dol(p.per_session_cap_cents)}`,
-    `  wallet methods:      ${(p.wallet_methods && p.wallet_methods.length) ? p.wallet_methods.join(", ") : "none connected"}`,
-  ].join("\n");
-};
-
 const HELP = `agentrelay — converse with capability agents while you build.
 
 Conversation (LLM-driven — drive these from a subagent, or directly when you're stuck):
-  agentrelay session start <slug>     [--initial json] [--message "<first msg>"]
+  agentrelay session start <slug>     [--initial json] [--task-context <s>] [--message "<m>"]
   agentrelay session send <id> "<m>"  [--data json]
-  agentrelay session pay <id>         [--credential <mpp>]  settle a payment_required
   agentrelay session end <id>
   agentrelay feedback <id>            --score <0-100> --text "<s>"
 
-Discovery + cache:
-  agentrelay search <query>           [--max 25] [--user-context <s>] [--dynamic-only]
-  agentrelay cache ls | show <slug> | put <slug> [--file f.json] | clear
-
-Payments (autonomous spend policy — server-canonical):
-  agentrelay budget                   show current policy
-  agentrelay budget --enable|--disable  [--auto-approve=<$>] [--daily-cap=<$>]
-                                     [--require-human-over=<$>] [--per-session-cap=<$>]
-  agentrelay connect-wallet           (wallet connect is set up in the dashboard)
-
-Diagnostics:
-  agentrelay doctor                  check node/key/API/npm-prefix/PATH health (--json)
+Discovery:
+  agentrelay search <query>           [--max 25]
 
 Deliverables (after a paid session returns a delivery object):
   agentrelay fetch --session <id>    [--message "<m>"] [dest]   ONE-STEP after payment:
@@ -226,14 +180,6 @@ async function main() {
     process.stdout.write(HELP + "\n");
     process.exit(cmd ? EXIT.OK : EXIT.USAGE);
   }
-  if (cmd === "consult" || cmd === "consult-batch") {
-    return fail(
-      `"${cmd}" was removed in v4 — drive a live session instead: ` +
-        "`agentrelay session start <slug>` → `session send` → `session end` (see SKILL.md)",
-      EXIT.USAGE,
-      Boolean(flags.json) || !process.stdout.isTTY,
-    );
-  }
   if (cmd === "version" || flags.version) {
     process.stdout.write(`agentrelay ${packageVersion()}\n`);
     process.exit(EXIT.OK);
@@ -254,9 +200,12 @@ async function main() {
   }
   const json = shared.json;
 
-  // cache, raw-URL fetch, and doctor don't need a key (doctor resolves and
-  // reports on the key itself). `fetch --session` calls the session API.
-  const keylessCmd = cmd === "cache" || cmd === "doctor" || (cmd === "fetch" && !flags.session);
+  // Raw-URL fetch downloads a signed URL directly and needs no key. Everything
+  // else (including `fetch --session`, which calls the session API) does. An
+  // UNKNOWN command needs no key either — it should get the clean "unknown
+  // command" error below, not a misleading "no API key" one.
+  const KNOWN_COMMANDS = new Set(["search", "session", "feedback", "fetch"]);
+  const keylessCmd = (cmd === "fetch" && !flags.session) || !KNOWN_COMMANDS.has(cmd);
   if (!keylessCmd && !shared.apiKey) {
     return fail(
       "no API key — set --api-key, $AGENT_RELAY_API_KEY, or ~/.config/agent-relay/credentials.json",
@@ -273,8 +222,6 @@ async function main() {
         const payload = await cmdSearch(query, {
           ...shared,
           max: Number(flags.max) || 25,
-          userContext: flags["user-context"] || null,
-          dynamicOnly: Boolean(flags["dynamic-only"]),
         });
         return emit(payload, { json, human: fmtSearch });
       }
@@ -286,7 +233,6 @@ async function main() {
           taskContext: flags["task-context"] || null,
           message: flags.message || null,
           data: flags.data || null,
-          credential: flags.credential || null,
         });
         return emit(payload, { json });
       }
@@ -300,24 +246,6 @@ async function main() {
         return emit(payload, { json });
       }
 
-      case "budget": {
-        const payload = await cmdBudget({
-          ...shared,
-          autoApprove: flags["auto-approve"] != null ? flags["auto-approve"] : null,
-          dailyCap: flags["daily-cap"] != null ? flags["daily-cap"] : null,
-          requireHumanOver: flags["require-human-over"] != null ? flags["require-human-over"] : null,
-          perSessionCap: flags["per-session-cap"] != null ? flags["per-session-cap"] : null,
-          enable: Boolean(flags.enable),
-          disable: Boolean(flags.disable),
-        });
-        return emit(payload, { json, human: fmtBudget });
-      }
-
-      case "connect-wallet": {
-        const payload = cmdConnectWallet();
-        return emit(payload, { json, human: (e) => e.message });
-      }
-
       case "fetch": {
         // --session: one-step deliverable retrieval for a PAID session — drive a turn
         // to mint a fresh signed download_url, then download+unpack. Needs the key.
@@ -353,28 +281,9 @@ async function main() {
         });
       }
 
-      case "doctor": {
-        const payload = await cmdDoctor({ ...shared, apiKey: flags["api-key"] || null });
-        const exitCode = payload.exit_code;
-        return emit(payload, { json, ok: payload.doctor_ok, exitCode, human: fmtDoctor });
-      }
-
-      case "cache": {
-        const payload = cmdCache(positionals[0], positionals[1], { ...shared, file: flags.file || null });
-        const human = Array.isArray(payload.specs)
-          ? (e) =>
-              [`${e.specs.length} banked specs (${e.cache_dir})`, ...e.specs.map((s) => {
-                const feat = s.features != null ? ` (${s.features} features)` : "";
-                const sum = s.summary ? ` — ${s.summary.length > 100 ? s.summary.slice(0, 100) + "…" : s.summary}` : "";
-                return `  ${s.slug}${feat}${sum}`;
-              })].join("\n")
-          : undefined;
-        return emit(payload, { json, human });
-      }
-
       default:
         return fail(
-          `unknown command "${cmd}" (session|search|feedback|cache|budget|connect-wallet|fetch|doctor)`,
+          `unknown command "${cmd}" (search|session|feedback|fetch)`,
           EXIT.USAGE,
           json,
         );

package/bin/test/session.test.mjs

@@ -1,15 +1,10 @@
 /**
- * Tests for the session-primitive output shaping and the cache put/show
- * round-trip (the LLM-driven path's transport). No network. Run:
- * `node --test bin/test/session.test.mjs`.
+ * Tests for the session-primitive output shaping (the LLM-driven path's
+ * transport). No network. Run: `node --test bin/test/session.test.mjs`.
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { shapeSessionTurn, deliveryToFetchArgs } from "../lib/commands.mjs";
-import { Cache } from "../lib/cache.mjs";
 import { slugify } from "../lib/config.mjs";
 
 test("shapeSessionTurn: passes the agent message through verbatim + surfaces flags", () => {
@@ -81,27 +76,7 @@ test("deliveryToFetchArgs: maps a delivery object to cmdFetch args (tolerant of
   assert.equal(deliveryToFetchArgs(null), null);
 });
 
-test("cache: put/show round-trip preserves an arbitrary LLM-chosen structure", () => {
-  const dir = mkdtempSync(join(tmpdir(), "agent-relay-cache-"));
-  try {
-    const cache = new Cache(dir);
-    // A non-dev shape an agent's distillation might use — must survive verbatim.
-    const distilled = {
-      summary: "Quote obtained",
-      quote_usd: 1240,
-      coverages: ["liability", "collision"],
-      next_steps: ["sign", "pay deposit"],
-    };
-    cache.writeSpec("acme-insurance", distilled);
-    const got = cache.readSpec("acme-insurance", { ttlMs: Infinity });
-    assert.deepEqual(got, distilled);
-    assert.deepEqual(cache.listSpecs(), ["acme-insurance"]);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test("slugify: stable kebab-case keys for cache/consult", () => {
+test("slugify: stable kebab-case keys for slugs", () => {
   assert.equal(slugify("Open-Meteo Weather API Solutions Engineer"), "open-meteo-weather-api-solutions-engineer");
   assert.equal(slugify("Acme Insurance ✨ (Auto)"), "acme-insurance-auto");
   assert.equal(slugify(""), "capability");

package/bin/test/sysenv.test.mjs

@@ -0,0 +1,30 @@
+/**
+ * Tests for the pure sysenv probes used by the installer's global-CLI linking.
+ * No network, no real npm install. Run: `node --test bin/test/sysenv.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { dirOnPath, npmGlobalBinDir, globalBinShimPath } from "../lib/sysenv.mjs";
+
+test("dirOnPath: exact component match, trailing-slash tolerant", () => {
+  const delim = process.platform === "win32" ? ";" : ":";
+  const pathVar = ["/usr/bin", "/opt/homebrew/bin/"].join(delim);
+  assert.equal(dirOnPath("/opt/homebrew/bin", pathVar), true);
+  assert.equal(dirOnPath("/usr/bin", pathVar), true);
+  assert.equal(dirOnPath("/usr/local/bin", pathVar), false);
+  assert.equal(dirOnPath(null, pathVar), false);
+});
+
+test("npmGlobalBinDir/globalBinShimPath shape per platform", () => {
+  const prefix = process.platform === "win32" ? "C:\\npm" : "/opt/homebrew";
+  const binDir = npmGlobalBinDir(prefix);
+  const shim = globalBinShimPath(prefix, "agentrelay");
+  if (process.platform === "win32") {
+    assert.equal(binDir, prefix);
+    assert.ok(shim.endsWith("agentrelay.cmd"));
+  } else {
+    assert.equal(binDir, `${prefix}/bin`);
+    assert.ok(shim.endsWith("/bin/agentrelay"));
+  }
+  assert.equal(npmGlobalBinDir(null), null);
+});