agentic-relay 3.8.5 → 4.1.0

package/CLAUDE.md

@@ -6,7 +6,7 @@ Expert "solutions-engineer" agents for real third-party tools (APIs, SDKs, libra
 
 On any non-trivial build that touches a third-party tool, **load the `agent-relay` skill before doing Agent Relay work.** This file is a map, not the manual — the skill holds the real procedure. Load it because the workflow has paid actions and a feedback loop you will get wrong from memory: when a charge fires, how to react, who fetches a paid deliverable, and what feedback to file when code survives (or fails) contact with production. Don't reconstruct that from this file.
 
-Lightweight exception: a one-off lookup ("find me X", "how do I install X") doesn't need the full breadth→build→depth ceremony. A single inline consult is fine — but still settle payments by the rules below.
+Lightweight exception: a one-off lookup ("find me X", "how do I install X") doesn't need the full breadth→build→depth ceremony. A single inline session (`session start` → a send or two → `session end`) is fine — but still settle payments by the rules below.
 
 ## Commands
 

package/README.md

@@ -134,12 +134,22 @@ gotchas}], capability_id, ad_unit_id }` (+ any extra keys) — see `schema/deliv
 | `agentrelay session end <id>` | Close + summary. |
 | `agentrelay feedback <id>` | `--score <0-100> --text "<s>"`. |
 | `agentrelay cache ls\|show <slug>\|put <slug>\|clear` | Persist/review distillations (`.agent-relay/`). |
-| `agentrelay consult <slug>` / `consult-batch` | **Fallback** code-driven template loop (fixed shape, generic). `--want`, `--context`. |
+| `agentrelay session pay <id>` / `fetch` / `budget` | Settle an in-policy charge, fetch a paid deliverable, read/set the spend policy. |
+| `agentrelay doctor` | Diagnose the install: Node version, API key + connectivity, npm prefix writability, `~/.npm` ownership, global bin + PATH. `--json` for machines. |
 
 Output is a `{ ok, ...payload, errors: [] }` envelope (`--json` auto-on when piped). Key resolution:
 `--api-key` → `$AGENT_RELAY_API_KEY` → `~/.config/agent-relay/credentials.json` (with a read-only fallback to the
 legacy `~/.config/penguin/credentials.json`). The key is never printed.
 
+**Staying current:** interactive runs print a one-line stderr notice when a newer version is on npm
+(checked in the background at most once per 24h; never blocks a command, never fires when piped, in CI,
+or under `npx`). Opt out with `AGENT_RELAY_NO_UPDATE_CHECK=1`. Deliverable zips are extracted by a
+built-in pure-JS extractor — no system `unzip` needed, so `fetch` works on Windows too.
+
+**Future work (not in this release):** standalone binaries, a Homebrew tap, winget/scoop manifests, and
+code signing. The package uses no npm lifecycle scripts (no postinstall), so npm v12's
+scripts-blocked-by-default change does not affect installs.
+
 ## What is Agent Relay?
 
 AI-native search for software, tools, services, and business solutions. Returns verified results from real businesses through semantic matching — more current and relevant than web search or training knowledge.

package/bin/cli.mjs

@@ -15,16 +15,19 @@
 
 const CLI_COMMANDS = new Set([
   "search",
-  "consult",
-  "consult-batch",
   "session",
   "feedback",
   "cache",
   "budget",
   "connect-wallet",
   "fetch",
+  "doctor",
   "version",
   "help",
+  // Removed commands — still routed to the CLI core so they fail with a clear
+  // error (exit 2) instead of falling through to the interactive installer.
+  "consult",
+  "consult-batch",
 ]);
 
 const sub = process.argv[2];

package/bin/install.mjs

@@ -29,13 +29,26 @@
  *   deeplink         Print URL the agent registers (tome://, raycast://) — user clicks Install
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from "fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
 import { execSync } from "child_process";
+import { parseInstallArgs } from "./lib/install-args.mjs";
+import {
+  resolveCommandPath,
+  isEphemeralBin,
+  npmGlobalPrefix,
+  npmGlobalBinDir,
+  globalBinShimPath,
+  globalPrefixWritable,
+  npmCacheOwnedByOther,
+  dirOnPath,
+  USER_PREFIX_RECIPE,
+  CACHE_CHOWN_RECIPE,
+} from "./lib/sysenv.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOME = homedir();
@@ -266,39 +279,8 @@ function escapeRegex(str) {
 // ═══════════════════════════════════════════════════════════════════════
 
 function parseArgs() {
-  const args = process.argv.slice(2);
-  const flags = {
-    targets: null,
-    all: args.includes("--all"),
-    project: args.includes("--project"),
-    apiKey: null,
-    librechat: null,
-    // Legacy single-flag shortcuts (kept for backward compat)
-    legacyClaude: args.includes("--claude"),
-    legacyCodex: args.includes("--codex"),
-    legacyCursor: args.includes("--cursor"),
-  };
-
-  for (const arg of args) {
-    if (arg.startsWith("--target=")) {
-      flags.targets = arg
-        .slice("--target=".length)
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
-    } else if (arg.startsWith("--api-key=")) {
-      flags.apiKey = arg.slice("--api-key=".length);
-    } else if (arg.startsWith("--librechat=")) {
-      flags.librechat = arg.slice("--librechat=".length);
-    }
-  }
-
-  // Support `--api-key VALUE` (space-separated) too
-  const keyIdx = args.indexOf("--api-key");
-  if (keyIdx !== -1 && args[keyIdx + 1] && !args[keyIdx + 1].startsWith("--")) {
-    flags.apiKey = args[keyIdx + 1];
-  }
-
+  const { flags, warnings } = parseInstallArgs(process.argv.slice(2));
+  for (const w of warnings) warn(w);
   return flags;
 }
 
@@ -623,45 +605,10 @@ function getExistingKey() {
  * Prefers a registry install (`agentic-relay@<version>`) over the local path
  * (the npx cache dir is ephemeral; npm would link/copy from it). Falls back to
  * the path for unpublished checkouts. Surfaces npm's actual error (EACCES
- * etc.) instead of swallowing it, and verifies the command resolves afterwards
- * so a PATH mismatch is reported, not discovered later as `command not found`.
+ * etc.) instead of swallowing it, and verifies the global bin file landed so a
+ * PATH mismatch is reported, not discovered later as `command not found`.
+ * System probes live in lib/sysenv.mjs (shared with `agentrelay doctor`).
  */
-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;
-  }
-}
-
-/** True when a resolved bin path is an ephemeral npx/npm-exec shim (or this package's own copy), not a real install. */
-function isEphemeralBin(binPath, pkgRoot) {
-  if (!binPath) return false;
-  let real = binPath;
-  try {
-    real = realpathSync(binPath);
-  } catch {
-    // dangling symlink — definitely not a usable install
-    return true;
-  }
-  const sep = process.platform === "win32" ? "\\" : "/";
-  return (
-    real.includes(`${sep}_npx${sep}`) ||
-    binPath.includes(`${sep}_npx${sep}`) ||
-    real.startsWith(realpathSafe(pkgRoot))
-  );
-}
-
-function realpathSafe(p) {
-  try {
-    return realpathSync(p);
-  } catch {
-    return p;
-  }
-}
-
 function linkGlobalCli() {
   const pkgRoot = join(__dirname, "..");
   let version = null;
@@ -686,6 +633,21 @@ function linkGlobalCli() {
     }
   }
 
+  // Preflight: detect the two environment breakages PROACTIVELY instead of
+  // letting `npm install -g` fail with a buried stderr.
+  const prefix = npmGlobalPrefix();
+  if (npmCacheOwnedByOther()) {
+    warn("your ~/.npm cache contains files owned by another user (an old `sudo npm`).");
+    warn(`This breaks npx AND npm i -g. Fix it once, then re-run:  ${CACHE_CHOWN_RECIPE}`);
+    return;
+  }
+  if (prefix && !globalPrefixWritable(prefix)) {
+    warn(`npm's global prefix (${prefix}) isn't writable — npm i -g would fail with EACCES.`);
+    warn("Use a user-level prefix (the official npm fix):");
+    for (const line of USER_PREFIX_RECIPE) warn(`  ${line}`);
+    return;
+  }
+
   const attempts = version ? [`agentic-relay@${version}`, `"${pkgRoot}"`] : [`"${pkgRoot}"`];
   let lastErr = null;
   let installedFrom = null;
@@ -702,31 +664,24 @@ function linkGlobalCli() {
     const stderr = String((lastErr && lastErr.stderr) || "");
     const detail =
       stderr.split("\n").find((l) => /EACCES|EEXIST|E404|ERR!|error/i.test(l)) || "";
-    warn(
-      `could not auto-link the global CLI${detail ? ` — ${detail.trim()}` : ""}.` +
-        ` Run once:  npm i -g agentic-relay` +
-        (/EACCES/.test(stderr) ? "  (npm's global prefix isn't writable — fix permissions or use a user-level prefix)" : ""),
-    );
+    warn(`could not auto-link the global CLI${detail ? ` — ${detail.trim()}` : ""}. Run once:  npm i -g agentic-relay`);
+    if (/EACCES/.test(stderr)) {
+      warn("EACCES — use a user-level prefix (the official npm fix):");
+      for (const line of USER_PREFIX_RECIPE) warn(`  ${line}`);
+    }
     return;
   }
 
   // Verify the global bin actually landed. Don't probe the bare command here:
   // in this process it resolves to the ephemeral npx shim (which shadows the
   // global install), so check the file in npm's global prefix directly.
-  let binDir = null;
-  let globalBin = null;
-  try {
-    const prefix = execSync("npm prefix -g", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-    binDir = process.platform === "win32" ? prefix : join(prefix, "bin");
-    const cand = join(binDir, process.platform === "win32" ? "agentrelay.cmd" : "agentrelay");
-    if (existsSync(cand)) globalBin = cand;
-  } catch {
-    // can't resolve the prefix — fall through to the warn
-  }
-  if (globalBin) {
+  const binDir = npmGlobalBinDir(prefix);
+  const shim = globalBinShimPath(prefix, "agentrelay");
+  if (shim && existsSync(shim)) {
     success(`linked global \`agentrelay\` CLI (${installedFrom})`);
-    const onPath = (process.env.PATH || "").split(process.platform === "win32" ? ";" : ":").includes(binDir);
-    if (!onPath) warn(`note: ${binDir} doesn't appear to be on your PATH — add it to use \`agentrelay\` directly`);
+    if (!dirOnPath(binDir)) {
+      warn(`note: ${binDir} doesn't appear to be on your PATH — add it to use \`agentrelay\` directly`);
+    }
   } else {
     warn(`installed, but no global \`agentrelay\` found in ${binDir || "npm's global bin directory"} — run once:  npm i -g agentic-relay`);
   }
@@ -739,6 +694,13 @@ async function setupApiKeyInteractive() {
     return true;
   }
 
+  // Scripted/CI runs have no TTY — don't hang on a prompt nobody will answer.
+  if (!stdin.isTTY) {
+    warn("no API key configured and stdin is not a terminal — skipping the prompt.");
+    warn("Pass --api-key=<am_live_...> or write ~/.config/agent-relay/credentials.json");
+    return false;
+  }
+
   console.log("");
   log("API key setup");
   console.log("");

package/bin/lib/cache.mjs

@@ -69,24 +69,18 @@ export class Cache {
     return join(this.searchDir, `${h}.json`);
   }
 
-  readSearch(query) {
-    if (!this.enabled) return null;
-    const entry = this._readJson(this._searchPath(query));
-    if (!entry) return null;
-    if (Date.now() > entry.expires) return null;
-    return entry.capabilities || null;
-  }
-
-  // The buyer-side spend policy snapshot the search API returns alongside the
-  // menu. Cached with the search so a cache hit still hands the agent a policy
-  // to decide auto-pay-vs-bubble against (see SKILL.md Pay). Null on older
-  // cache files written before this field existed.
-  readSearchPaymentContext(query) {
+  /**
+   * Whole unexpired search entry — `{ts, capabilities, payment_context}` — or
+   * null. Returning the entry (not just capabilities) lets the caller surface
+   * how stale the cached payment_context snapshot is (see SKILL.md Pay).
+   */
+  readSearchEntry(query) {
     if (!this.enabled) return null;
     const entry = this._readJson(this._searchPath(query));
     if (!entry) return null;
     if (Date.now() > entry.expires) return null;
-    return entry.payment_context || null;
+    if (!entry.capabilities) return null;
+    return entry;
   }
 
   writeSearch(query, capabilities, paymentContext = null) {

package/bin/lib/commands.mjs

@@ -2,12 +2,10 @@
  * Command implementations for the agentrelay CLI. Each returns an envelope payload
  * (the entry adds `ok`/`errors` and chooses the exit code).
  *
- * Two modes (see SKILL.md):
- *  - `session start|send|end` — 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. This is the primary, LLM-driven path.
- *  - `consult` / `consult-batch` — the code-driven TEMPLATE fallback for
- *    no-LLM/scripted use; returns a distilled result, transcript stays out.
+ * `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.
  */
 
 import { readFileSync } from "fs";
@@ -23,7 +21,6 @@ import {
 } from "./api.mjs";
 import { slugify } from "./config.mjs";
 import { Cache } from "./cache.mjs";
-import { consultOne } from "./driver.mjs";
 import { cmdFetch } from "./fetch.mjs";
 
 /** Normalize one upstream capability into the spec §4 menu shape. */
@@ -61,9 +58,14 @@ export async function cmdSearch(query, opts) {
   // 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.
-  let paymentContext = opts.refresh ? null : cache.readSearchPaymentContext(query);
+  // 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.
+  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;
 
-  let capabilities = opts.refresh ? null : cache.readSearch(query);
   if (!capabilities) {
     const data = await apiSearch(query, {
       apiKey: opts.apiKey,
@@ -74,7 +76,7 @@ export async function cmdSearch(query, opts) {
     paymentContext = data.payment_context ?? null;
     capabilities = dedupeSlugs((data.capabilities || []).map(normalizeCapability));
     cache.writeSearch(query, capabilities, paymentContext);
-    // Seed the index so consult can resolve ids without re-searching.
+    // Seed the index so session start can resolve ids without re-searching.
     for (const c of capabilities) {
       if (c.capability_id && c.ad_unit_id) {
         cache.updateIndex(c.slug, {
@@ -93,7 +95,14 @@ export async function cmdSearch(query, opts) {
   }
   capabilities = capabilities.slice(0, maxResults);
 
-  return { query, count: capabilities.length, capabilities, payment_context: paymentContext };
+  return {
+    query,
+    count: capabilities.length,
+    from_cache: fromCache,
+    cached_at: cachedAt,
+    capabilities,
+    payment_context: paymentContext,
+  };
 }
 
 /**
@@ -153,116 +162,6 @@ export async function resolveCapability(slugOrId, opts) {
   };
 }
 
-async function consultResolved(resolved, want, opts) {
-  const cache = new Cache(opts.cacheDir, { enabled: !opts.noCache });
-
-  // Cache hit: return the stored spec unless --refresh.
-  if (!opts.refresh) {
-    const cached = cache.readSpec(resolved.slug);
-    if (cached) return { ...cached, cached: true };
-  }
-
-  const { deliverable, sessionId, turns } = await consultOne(resolved, {
-    want,
-    context: opts.context,
-    deliverNow: opts.deliverNow,
-    raw: opts.raw,
-    maxTurns: opts.maxTurns,
-    timeoutMs: opts.timeoutMs,
-    apiKey: opts.apiKey,
-  });
-  deliverable.turns = turns;
-  cache.writeSpec(resolved.slug, deliverable);
-  cache.updateIndex(resolved.slug, {
-    last_session_id: sessionId,
-    capability_id: resolved.capabilityId,
-    ad_unit_id: resolved.adUnitId,
-    clearing_price_cents: resolved.clearingPriceCents,
-    name: resolved.name,
-  });
-  return deliverable;
-}
-
-/**
- * `consult`/`consult-batch` only run the code-driven TEMPLATE driver. The
- * LLM-driven path is a host subagent driving the `session` primitives — there's
- * no CLI-internal LLM. Reject `--driver llm` with a pointer rather than
- * silently degrading.
- */
-function assertTemplateDriver(opts) {
-  const d = opts.driver || "template";
-  if (d !== "template") {
-    const e = new Error(
-      `--driver "${d}" is not available. consult runs the template driver only; ` +
-        "for LLM-driven conversation, drive `agentrelay session start|send|end` from a subagent (see SKILL.md).",
-    );
-    e.usage = true;
-    throw e;
-  }
-}
-
-export async function cmdConsult(slugOrId, opts) {
-  assertTemplateDriver(opts);
-  if (!opts.want) {
-    const e = new Error("--want is required");
-    e.usage = true;
-    throw e;
-  }
-  const resolved = await resolveCapability(slugOrId, opts);
-  const deliverable = await consultResolved(resolved, opts.want, opts);
-  return { deliverable };
-}
-
-function loadWantFile(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch (err) {
-    throw new Error(`could not read --want-file ${path}: ${err.message}`);
-  }
-}
-
-export async function cmdConsultBatch(opts) {
-  assertTemplateDriver(opts);
-  if (!opts.agents || opts.agents.length === 0) {
-    const e = new Error("--agents <a,b,c> is required");
-    e.usage = true;
-    throw e;
-  }
-  const wantMap = opts.wantFile ? loadWantFile(opts.wantFile) : null;
-  if (!wantMap && !opts.want) {
-    const e = new Error("provide --want <str> or --want-file <map.json>");
-    e.usage = true;
-    throw e;
-  }
-
-  const { pool } = await import("./pool.mjs");
-  const t0 = Date.now();
-
-  const results = await pool(opts.agents, opts.concurrency || 5, async (slug) => {
-    const want = (wantMap && wantMap[slug]) || opts.want;
-    if (!want) throw new Error(`no want for "${slug}" (missing from --want-file)`);
-    const resolved = await resolveCapability(slug, opts);
-    return consultResolved(resolved, want, opts);
-  });
-
-  const deliverables = [];
-  const failures = [];
-  results.forEach((r, i) => {
-    if (r.ok) deliverables.push(r.value);
-    else failures.push({ slug: opts.agents[i], reason: String(r.error.message || r.error) });
-  });
-
-  const totals = {
-    consulted: opts.agents.length,
-    ok: deliverables.length,
-    failed: failures.length,
-    wall_seconds: Math.round((Date.now() - t0) / 1000),
-    tokens_estimate: deliverables.reduce((s, d) => s + (d.tokens_estimate || 0), 0),
-  };
-
-  return { deliverables, failures, totals };
-}
-
 // ── session primitives (thin api_v1 wrappers — the LLM-driven path) ─────────
 function parseJsonFlag(s, name) {
   if (!s) return undefined;
@@ -296,17 +195,20 @@ export function shapeSessionTurn(r) {
 
 /**
  * Map a `delivery` object (from a paid session turn) to cmdFetch args. Tolerant of
- * minor key variants so it survives small upstream shape differences.
+ * minor key variants so it survives small upstream shape differences. The dest
+ * defaults to ./<delivery.slug>/ (slugified — a hostile slug can't traverse);
+ * an explicit dest always wins.
  */
 export function deliveryToFetchArgs(d, { dest = null } = {}) {
   if (!d || typeof d !== "object") return null;
   const url = d.download_url || d.url || null;
   if (!url) return null;
+  const slug = d.slug ? slugify(String(d.slug)) : null;
   return {
     url,
     checksum: d.checksum_sha256 || d.checksum || null,
     filename: d.filename || null,
-    dest,
+    dest: dest || (slug ? `./${slug}` : null),
   };
 }
 
@@ -421,13 +323,13 @@ export async function cmdFetchSession(sessionId, opts) {
 }
 
 export async function cmdFeedback(sessionId, opts) {
-  if (!sessionId || opts.score == null) {
+  if (!sessionId || opts.score == null || !opts.text || !String(opts.text).trim()) {
     const e = new Error("usage: agentrelay feedback <session_id> --score <0-100> --text <str>");
     e.usage = true;
     throw e;
   }
   return apiFeedback(
-    { sessionId, feedbackText: opts.text || "", score: Number(opts.score) },
+    { sessionId, feedbackText: String(opts.text), score: Number(opts.score) },
     { apiKey: opts.apiKey, timeoutMs: opts.timeoutMs },
   );
 }
@@ -532,11 +434,24 @@ export function cmdCache(sub, slug, opts) {
     }
     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");
+    }
     // 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 };
+    return { stored: true, slug, cache_dir: opts.cacheDir, warnings };
   }
   if (sub === "clear") {
     cache.clear();