agentic-relay 4.0.0 → 4.1.0

package/README.md

@@ -135,11 +135,21 @@ gotchas}], capability_id, ad_unit_id }` (+ any extra keys) — see `schema/deliv
 | `agentrelay feedback <id>` | `--score <0-100> --text "<s>"`. |
 | `agentrelay cache ls\|show <slug>\|put <slug>\|clear` | Persist/review distillations (`.agent-relay/`). |
 | `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

@@ -21,6 +21,7 @@ const CLI_COMMANDS = new Set([
   "budget",
   "connect-wallet",
   "fetch",
+  "doctor",
   "version",
   "help",
   // Removed commands — still routed to the CLI core so they fail with a clear

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

@@ -58,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,
@@ -90,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,
+  };
 }
 
 /**
@@ -183,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),
   };
 }
 
@@ -419,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();

package/bin/lib/doctor.mjs

@@ -0,0 +1,222 @@
+/**
+ * `agentrelay doctor` — diagnose the install/runtime environment.
+ *
+ * Every check maps to a failure mode seen in the field: stale global versions,
+ * EACCES on the npm prefix, root-owned ~/.npm (kills npx AND npm i -g), the
+ * global bin dir missing from PATH, a dead/misconfigured API key. Output is
+ * one line per check (✓ ok / ! warn / ✗ fail) or a --json envelope; exit 1
+ * only when a required check fails.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { resolveApiKey, CREDENTIALS_PATH, LEGACY_CREDENTIALS_PATH } from "./config.mjs";
+import { search as apiSearch } from "./api.mjs";
+import { compareSemver } from "./update-check.mjs";
+import {
+  npmGlobalPrefix,
+  npmGlobalBinDir,
+  globalBinShimPath,
+  globalPrefixWritable,
+  npmCacheOwnedByOther,
+  dirOnPath,
+  isDirWritable,
+  USER_PREFIX_RECIPE,
+  CACHE_CHOWN_RECIPE,
+} from "./sysenv.mjs";
+
+export const MIN_NODE_MAJOR = 18;
+
+/** Pure: ok/fail verdict for a Node version string. */
+export function checkNodeVersion(versionString) {
+  const major = Number(String(versionString).split(".")[0]);
+  return {
+    id: "node",
+    label: "Node.js version",
+    status: major >= MIN_NODE_MAJOR ? "ok" : "fail",
+    detail:
+      major >= MIN_NODE_MAJOR
+        ? `v${versionString}`
+        : `v${versionString} — agentrelay needs Node >= ${MIN_NODE_MAJOR}`,
+  };
+}
+
+/** Pure: aggregate checks → overall ok + exit code. */
+export function summarize(checks) {
+  const failed = checks.filter((c) => c.status === "fail");
+  return { ok: failed.length === 0, exitCode: failed.length === 0 ? 0 : 1 };
+}
+
+async function fetchLatestVersion(timeoutMs = 3000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch("https://registry.npmjs.org/agentic-relay/latest", {
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function apiKeySource(flagKey) {
+  if (flagKey && flagKey.trim()) return "--api-key flag";
+  if (process.env.AGENT_RELAY_API_KEY?.trim()) return "$AGENT_RELAY_API_KEY";
+  try {
+    const creds = JSON.parse(readFileSync(CREDENTIALS_PATH, "utf-8"));
+    if (creds.api_key) return CREDENTIALS_PATH;
+  } catch {
+    /* fall through */
+  }
+  try {
+    const creds = JSON.parse(readFileSync(LEGACY_CREDENTIALS_PATH, "utf-8"));
+    if (creds.api_key) return `${LEGACY_CREDENTIALS_PATH} (legacy)`;
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+export async function cmdDoctor(opts) {
+  const checks = [];
+
+  // 1. Node version
+  checks.push(checkNodeVersion(process.versions.node));
+
+  // 2. CLI version vs registry
+  let currentVersion = "unknown";
+  try {
+    currentVersion = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf-8"),
+    ).version;
+  } catch {
+    /* keep "unknown" */
+  }
+  const latest = await fetchLatestVersion();
+  const behind = latest !== null && compareSemver(latest, currentVersion) > 0;
+  checks.push({
+    id: "version",
+    label: "CLI version",
+    status: latest === null ? "warn" : behind ? "warn" : "ok",
+    detail:
+      latest === null
+        ? `${currentVersion} (couldn't reach the npm registry to compare)`
+        : behind
+          ? `${currentVersion} — ${latest} is available: npm i -g agentic-relay`
+          : `${currentVersion} (latest is ${latest})`,
+  });
+
+  // 3. API key presence
+  const key = resolveApiKey(opts.apiKey || null);
+  const source = key ? apiKeySource(opts.apiKey || null) : null;
+  checks.push({
+    id: "api_key",
+    label: "API key",
+    status: key ? "ok" : "warn",
+    detail: key
+      ? `configured via ${source}`
+      : `not found — set --api-key, $AGENT_RELAY_API_KEY, or ${CREDENTIALS_PATH}`,
+  });
+
+  // 4. API key live verification (skipped without a key)
+  if (key) {
+    try {
+      await apiSearch("doctor connectivity check", {
+        apiKey: key,
+        maxResults: 1,
+        timeoutMs: Math.min(opts.timeoutMs || 10000, 10000),
+      });
+      checks.push({ id: "api", label: "API connectivity", status: "ok", detail: "search responds" });
+    } catch (err) {
+      checks.push({
+        id: "api",
+        label: "API connectivity",
+        status: "fail",
+        detail: `search failed: ${err.message}`,
+      });
+    }
+  } else {
+    checks.push({ id: "api", label: "API connectivity", status: "warn", detail: "skipped (no key)" });
+  }
+
+  // 5. npm global prefix + writability
+  const prefix = npmGlobalPrefix();
+  if (!prefix) {
+    checks.push({ id: "prefix", label: "npm global prefix", status: "warn", detail: "npm not found on PATH" });
+  } else if (globalPrefixWritable(prefix)) {
+    checks.push({ id: "prefix", label: "npm global prefix", status: "ok", detail: `${prefix} (writable)` });
+  } else {
+    checks.push({
+      id: "prefix",
+      label: "npm global prefix",
+      status: "warn",
+      detail: `${prefix} is not writable — npm i -g will EACCES. Fix: ${USER_PREFIX_RECIPE.join("; ")}`,
+    });
+  }
+
+  // 6. ~/.npm cache ownership
+  checks.push(
+    npmCacheOwnedByOther()
+      ? {
+          id: "npm_cache",
+          label: "npm cache (~/.npm)",
+          status: "warn",
+          detail: `owned by another user — breaks npx AND npm i -g. Fix: ${CACHE_CHOWN_RECIPE}`,
+        }
+      : { id: "npm_cache", label: "npm cache (~/.npm)", status: "ok", detail: "owned by you" },
+  );
+
+  // 7 + 8. global bin shim exists + its dir is on PATH
+  const shim = globalBinShimPath(prefix, "agentrelay");
+  const binDir = npmGlobalBinDir(prefix);
+  const shimExists = Boolean(shim) && existsSync(shim);
+  checks.push({
+    id: "global_bin",
+    label: "global `agentrelay` bin",
+    status: shimExists ? "ok" : "warn",
+    detail: shimExists ? shim : `not found in ${binDir || "npm's global bin dir"} — run: npm i -g agentic-relay`,
+  });
+  checks.push({
+    id: "path",
+    label: "global bin dir on PATH",
+    status: dirOnPath(binDir) ? "ok" : "warn",
+    detail: dirOnPath(binDir)
+      ? binDir
+      : `${binDir || "npm's global bin dir"} is not on PATH — add it to your shell profile`,
+  });
+
+  // 9. working directory writable (cache + deliverables land here)
+  checks.push({
+    id: "cwd",
+    label: "working dir writable",
+    status: isDirWritable(process.cwd()) ? "ok" : "warn",
+    detail: process.cwd(),
+  });
+
+  // 10. zip capability (informational — pure-JS, no system unzip needed)
+  checks.push({
+    id: "zip",
+    label: "deliverable unzip",
+    status: "ok",
+    detail: "pure-JS extractor (no system `unzip` required)",
+  });
+
+  const { ok, exitCode } = summarize(checks);
+  return { checks, doctor_ok: ok, exit_code: exitCode, config_dir: join(homedir(), ".config", "agent-relay") };
+}
+
+const ICONS = { ok: "✓", warn: "!", fail: "✗" };
+
+export function fmtDoctor(envelope) {
+  const lines = (envelope.checks || []).map(
+    (c) => `${ICONS[c.status] || "?"} ${c.label.padEnd(26)} ${c.detail}`,
+  );
+  lines.push(envelope.doctor_ok ? "doctor: no blocking problems found" : "doctor: blocking problems found (✗)");
+  return lines.join("\n");
+}