agentic-relay 4.3.0 → 5.0.0

package/README.md

@@ -25,7 +25,9 @@ npx agentic-relay --all --api-key=am_live_xxx
 
 `--target=...` accepts a comma-separated list of agent IDs. `--all` installs for every agent in the matrix below. `--api-key=...` skips the prompt.
 
-> One package, one command. `agentrelay` with no subcommand runs the installer; `agentrelay <cmd>` (e.g. `search`, `session`, `cache`) runs the CLI. If the global link can't be created (e.g. an unwritable npm prefix), run `npm i -g agentic-relay` once yourself.
+> One package, one command. `agentrelay` with no subcommand runs the installer; `agentrelay <cmd>` (e.g. `search`, `session`, `fetch`) runs the CLI. If the global link can't be created (e.g. an unwritable npm prefix), run `npm i -g agentic-relay` once yourself.
+>
+> **Reinstalling is always a clean, fresh install:** it removes the old global command and reinstalls the current code (from your local checkout when you're developing), rewrites the skill files, and re-checks your cached API key — replacing it only if it's no longer valid. Nothing stale is left behind.
 
 Don't run `npm install` (as a dependency) — this is a CLI installer, not a library.
 
@@ -103,7 +105,7 @@ The installer puts `agentrelay` on your PATH (or run `npm i -g agentic-relay` on
 
 ```bash
 # 1. discover
-agentrelay search "weather dashboard tools" --dynamic-only --json
+agentrelay search "weather dashboard tools" --json
 
 # 2. converse (drive this loop from a subagent, or directly)
 agentrelay session start open-meteo-weather-api-solutions-engineer \
@@ -118,24 +120,22 @@ non-empty), answer the agent's question from your context and `session send` aga
 Sessions are short-lived (~60 min); start a fresh one per consult.
 
 **Breadth → build → depth.** For real builds: spawn one **subagent per agent** to drive it to full
-coverage and **bank** the result (`agentrelay cache put <slug>`) while returning only a compact `summary`
-to the orchestrator (breadth, parallel, transcripts stay isolated); the main agent then builds from the
-bank (`agentrelay cache ls` to triage summaries, `agentrelay cache show <slug>` for a feature's full detail)
-and opens a **direct** session only when the bank lacks something (depth), appending the answer back.
-A banked spec follows a light contract — `{ slug, name, summary, features:[{feature, how, snippets,
-gotchas}], capability_id, ad_unit_id }` (+ any extra keys) — see `schema/deliverable.json`. Concurrent
-`cache put`s from parallel subagents are safe (per-slug files).
+coverage in parallel (transcripts stay isolated), each returning only a compact `summary` to the
+orchestrator; the main agent builds from those summaries and opens a **direct** session only when it
+needs deeper detail (depth). Search results are cached on disk (`.agent-relay/`) so a repeat search is
+near-free, and the index lets `session start` resolve a slug without re-searching.
 
 | Command | What it does |
 |---|---|
-| `agentrelay search <query>` | Discovery (default 25, relevance-sorted). `--dynamic-only`, `--user-context`, `--max`. |
-| `agentrelay session start <slug>` | Begin a conversation. `--initial '<json>'`, `--message "<first msg>"`. |
+| `agentrelay search <query>` | Discovery (default 25, relevance-sorted). `--max`. |
+| `agentrelay session start <slug>` | Begin a conversation. `--initial '<json>'`, `--task-context "<s>"`, `--message "<first msg>"`. |
 | `agentrelay session send <id> "<m>"` | Send a turn; returns the agent's raw reply + flags. `--data '<json>'`. |
 | `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 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. |
+| `agentrelay fetch --session <id>` | After payment, fetch + verify + unpack a paid deliverable into `./<slug>/`. |
+
+Payments go through a link — when a session returns a `payment_required`, surface its `payment_url` to
+the user; the CLI never charges programmatically.
 
 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

package/bin/cli.mjs

@@ -5,8 +5,11 @@
  *
  * Routing:
  *   - A recognised CLI subcommand  →  the CLI core (relay-core.mjs)
- *   - Anything else (no args, or install flags like --all/--target/--api-key)
- *                                  →  the installer (install.mjs)
+ *   - An UNrecognised bare word (a typo or removed command)
+ *                                  →  the CLI core too, so it prints a clean
+ *                                     "unknown command" error (exit 2)
+ *   - No args, an install flag (--all/--target/--api-key/…), or a bare
+ *     `am_live_…` key            →  the installer (install.mjs)
  *
  * Both modules read process.argv directly and self-run on import, so we just
  * dynamically import the right one. argv is untouched, so e.g.
@@ -17,23 +20,22 @@ const CLI_COMMANDS = new Set([
   "search",
   "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];
 
-if (sub && CLI_COMMANDS.has(sub)) {
-  await import("./relay-core.mjs");
-} else {
+// The installer is for: no args, an install flag (starts with "-"), or a bare
+// API key pasted as the first arg. Any other first token is treated as a CLI
+// command — known ones run; unknown ones get a clean error from relay-core,
+// NOT a surprise interactive installer.
+const isInstallerInvocation =
+  !sub || sub.startsWith("-") || sub.startsWith("am_live_");
+
+if (isInstallerInvocation) {
   await import("./install.mjs");
+} else {
+  await import("./relay-core.mjs");
 }

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * Agent Relay Installer v3 — multi-agent (skill, MCP, deeplink modes)
+ * Agent Relay Installer — multi-agent (skill, MCP, deeplink modes)
  *
  * Usage:
  *
@@ -29,7 +29,7 @@
  *   deeplink         Print URL the agent registers (tome://, raycast://) — user clicks Install
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from "fs";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -38,8 +38,6 @@ import { stdin, stdout } from "process";
 import { execSync } from "child_process";
 import { parseInstallArgs } from "./lib/install-args.mjs";
 import {
-  resolveCommandPath,
-  isEphemeralBin,
   npmGlobalPrefix,
   npmGlobalBinDir,
   globalBinShimPath,
@@ -294,6 +292,9 @@ function parseArgs() {
 
 function installSkill(skillContent, instructionsContent, agent) {
   try {
+    // Wipe the skill dir first so a reinstall can't leave behind stale files a
+    // previous version dropped here — we own skills/agent-relay/ entirely.
+    rmSync(agent.skillDir, { recursive: true, force: true });
     mkdirSync(agent.skillDir, { recursive: true });
     writeFileSync(join(agent.skillDir, "SKILL.md"), skillContent);
     success(`${agent.label}: skill → ${agent.skillDir}/SKILL.md`);
@@ -583,6 +584,38 @@ function saveApiKey(key) {
   success(`API key saved → ${CREDENTIALS_PATH}`);
 }
 
+/** Remove any cached credential files (new + legacy). Best-effort. */
+function clearCachedKey() {
+  for (const path of [CREDENTIALS_PATH, LEGACY_CREDENTIALS_PATH]) {
+    try {
+      rmSync(path, { force: true });
+    } catch {}
+  }
+}
+
+/**
+ * Live-check a key against the search endpoint. Returns { ok } — true only when
+ * the key authenticates and search responds. Shared by the reinstall
+ * verify-then-refresh path and the final post-install verification.
+ */
+async function verifyKey(key) {
+  try {
+    const resp = await fetch(`${API_BASE}/search`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-AM-API-Key": key },
+      body: JSON.stringify({ query: "test", max_results: 1 }),
+    });
+    let data = {};
+    try {
+      data = await resp.json();
+    } catch {}
+    if (resp.ok && data.capabilities) return { ok: true };
+    return { ok: false, detail: `HTTP ${resp.status}${data.error ? ` — ${data.error}` : ""}` };
+  } catch (err) {
+    return { ok: false, detail: err.message };
+  }
+}
+
 function getExistingKey() {
   // Prefer the new path, but recognise a legacy ~/.config/penguin key too so an
   // existing user isn't re-prompted (resolveApiKey applies the same fallback).
@@ -598,22 +631,21 @@ function getExistingKey() {
 
 /**
  * Link a bare global `agentrelay` command so users skip `npx` after install.
- * No-ops only when a GENUINE install of `agentrelay` already matches this
- * package's version — a stale global install gets upgraded, not skipped.
+ * Always performs a clean relink on reinstall — uninstalls any existing global
+ * first, then reinstalls — so the code on PATH is never stale (there is no
+ * "already the right version, skip" shortcut; that shortcut is exactly what left
+ * old code on PATH after a local edit).
  *
  * npx trap: `npx agentic-relay` prepends its ephemeral cache's .bin to this
  * process's PATH, so `agentrelay` ALWAYS resolves here (to the very copy being
- * run) and disappears when npx exits. A naive "already on your PATH" check
- * therefore never links anything and the user gets `command not found` in
- * their next shell. We resolve the command's real location and ignore it when
- * it lives in an npx/npm-exec cache or inside this package itself.
+ * run) and disappears when npx exits. We therefore never trust the bare command;
+ * we uninstall + reinstall and verify the global bin file landed directly.
  *
- * 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 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`).
+ * Install source: from a DEV CHECKOUT (a .git dir next to the package) the
+ * local path is installed FIRST so your edits actually go global; a normal
+ * published run installs `agentic-relay@<version>` from the registry first, with
+ * the path as fallback. Surfaces npm's actual error (EACCES etc.) and verifies
+ * the global bin landed. System probes live in lib/sysenv.mjs.
  */
 function linkGlobalCli() {
   const pkgRoot = join(__dirname, "..");
@@ -624,21 +656,6 @@ function linkGlobalCli() {
     // unknown version — fall through to the path install
   }
 
-  const binPath = resolveCommandPath("agentrelay");
-  if (binPath && !isEphemeralBin(binPath, pkgRoot)) {
-    try {
-      const out = execSync("agentrelay version", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
-      const installed = (out.trim().split(/\s+/).pop() || "").trim();
-      if (version && installed === version) {
-        success(`\`agentrelay\` ${version} already on your PATH`);
-        return "linked";
-      }
-      log(`global \`agentrelay\` is ${installed || "an unknown version"} — updating to ${version}…`);
-    } catch {
-      // resolves but doesn't run — reinstall it
-    }
-  }
-
   // Preflight: detect the two environment breakages PROACTIVELY instead of
   // letting `npm install -g` fail with a buried stderr.
   const prefix = npmGlobalPrefix();
@@ -654,7 +671,20 @@ function linkGlobalCli() {
     return "blocked";
   }
 
-  const attempts = version ? [`agentic-relay@${version}`, `"${pkgRoot}"`] : [`"${pkgRoot}"`];
+  // Clean relink: remove any existing global so a reinstall can't leave stale
+  // code on PATH. Best-effort — a missing global just no-ops.
+  try {
+    execSync("npm uninstall -g agentic-relay", { stdio: ["ignore", "ignore", "ignore"] });
+  } catch {}
+
+  // Prefer the local path when this is a dev checkout, so local edits actually
+  // reach the global command; otherwise install the published version. Detect a
+  // checkout by the .git dir — a published tarball (incl. an npx run) never has
+  // one. (bin/test/ ships in the package, so it can't be the signal.)
+  const isDevCheckout = existsSync(join(pkgRoot, ".git"));
+  const registrySpec = version ? `agentic-relay@${version}` : "agentic-relay";
+  const pathSpec = `"${pkgRoot}"`;
+  const attempts = isDevCheckout ? [pathSpec, registrySpec] : [registrySpec, pathSpec];
   let lastErr = null;
   let installedFrom = null;
   for (const spec of attempts) {
@@ -696,15 +726,26 @@ function linkGlobalCli() {
 }
 
 async function setupApiKeyInteractive() {
+  // Verify-then-refresh: on a reinstall, keep a cached key that still works, but
+  // wipe a stale/revoked one and prompt for a fresh key — so a dead key never
+  // silently persists. (A working key is never re-typed just because you
+  // reinstalled.)
   const existing = getExistingKey();
   if (existing) {
-    success(`API key already configured (${CREDENTIALS_PATH})`);
-    return true;
+    log("Checking cached API key…");
+    const check = await verifyKey(existing);
+    if (check.ok) {
+      success(`Reusing verified API key (${CREDENTIALS_PATH})`);
+      return true;
+    }
+    warn(`Cached API key is no longer valid (${check.detail}) — clearing it.`);
+    clearCachedKey();
+    // fall through and prompt for a fresh one
   }
 
   // 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("no valid 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;
   }
@@ -748,23 +789,11 @@ async function verifyInstall() {
   if (!key) return;
 
   log("Verifying API key…");
-  try {
-    const resp = await fetch(`${API_BASE}/search`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-AM-API-Key": key,
-      },
-      body: JSON.stringify({ query: "test", max_results: 1 }),
-    });
-    const data = await resp.json();
-    if (resp.ok && data.capabilities) {
-      success("API key verified — search is working");
-    } else {
-      warn(`API returned ${resp.status}: ${data.error || "unknown error"}`);
-    }
-  } catch (err) {
-    warn(`Verification failed: ${err.message}`);
+  const check = await verifyKey(key);
+  if (check.ok) {
+    success("API key verified — search is working");
+  } else {
+    warn(`API key verification failed: ${check.detail}`);
   }
 }
 

package/bin/lib/api.mjs

@@ -66,20 +66,20 @@ export async function apiPost(path, body, { apiKey, timeoutMs = 30000 } = {}) {
   return data;
 }
 
-export function search(query, { apiKey, userContext, maxResults = 25, timeoutMs }) {
-  const body = { query, max_results: maxResults };
-  if (userContext) body.user_context = userContext;
-  return apiPost("/search", body, { apiKey, timeoutMs });
+export function search(query, { apiKey, maxResults = 25, timeoutMs }) {
+  return apiPost("/search", { query, max_results: maxResults }, { apiKey, timeoutMs });
 }
 
 export function sessionStart(
-  { agentId, initialData },
+  { agentId, initialData, taskContext },
   { apiKey, timeoutMs },
 ) {
   return apiPost(
     "/session/start",
     {
       agent_id: agentId,
+      // A2A current-task brief; api-v1 forwards it to capability-session /initiate.
+      ...(taskContext ? { task_context: taskContext } : {}),
       ...(initialData ? { initial_data: initialData } : {}),
     },
     { apiKey, timeoutMs },
@@ -105,30 +105,6 @@ export function sessionEnd({ sessionId }, { apiKey, timeoutMs }) {
   return apiPost("/session/end", { session_id: sessionId }, { apiKey, timeoutMs });
 }
 
-/**
- * Settle a payment request for a session. Omit `paymentCredential` to pay from the
- * account's server-side wallet grant; pass it for a client-side MPP/x402 wallet.
- * Returns the structured SettleResult ({ ok, error_code, ... }); does not throw on a
- * 402 policy/charge rejection — the caller inspects `ok`.
- */
-export async function sessionPay({ sessionId, paymentCredential }, { apiKey, timeoutMs }) {
-  try {
-    return await apiPost(
-      "/session/pay",
-      {
-        ...(sessionId ? { session_id: sessionId } : {}),
-        ...(paymentCredential ? { payment_credential: paymentCredential } : {}),
-      },
-      { apiKey, timeoutMs },
-    );
-  } catch (err) {
-    // A 402 is an expected "policy/charge rejected" outcome — return its structured body
-    // so the agent can fall back to bubbling the payment_url, not crash.
-    if (err instanceof ApiError && err.body && typeof err.body === "object") return err.body;
-    throw err;
-  }
-}
-
 export function feedback({ sessionId, feedbackText, score }, { apiKey, timeoutMs }) {
   return apiPost(
     "/feedback",
@@ -136,50 +112,3 @@ export function feedback({ sessionId, feedbackText, score }, { apiKey, timeoutMs
     { apiKey, timeoutMs },
   );
 }
-
-/**
- * Generic request used by the GET/PATCH payment-policy endpoints. Same timeout +
- * lenient-parse + error handling as apiPost; omits the body for GET.
- */
-async function apiRequest(method, path, body, { apiKey, timeoutMs = 30000 } = {}) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  let resp;
-  try {
-    resp = await fetch(`${API_BASE}${path}`, {
-      method,
-      headers: { "Content-Type": "application/json", "X-AM-API-Key": apiKey },
-      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-      signal: controller.signal,
-    });
-  } catch (err) {
-    if (err && err.name === "AbortError") {
-      throw new ApiError(`timeout after ${Math.round(timeoutMs / 1000)}s`, { status: 0 });
-    }
-    throw new ApiError(`network error: ${err.message}`, { status: 0 });
-  } finally {
-    clearTimeout(timer);
-  }
-
-  const text = await resp.text();
-  const parsed = lenientParse(text);
-  const data = parsed.ok ? parsed.value : null;
-  if (!resp.ok) {
-    const msg = (data && (data.message || data.error)) || `HTTP ${resp.status}`;
-    throw new ApiError(String(msg), { status: resp.status, body: data });
-  }
-  if (!parsed.ok) {
-    throw new ApiError("unparseable response from upstream", { status: resp.status, body: text.slice(0, 500) });
-  }
-  return data;
-}
-
-/** Read the account's autonomous-spend policy. */
-export function getPaymentPolicy({ apiKey, timeoutMs }) {
-  return apiRequest("GET", "/account/payment-policy", undefined, { apiKey, timeoutMs });
-}
-
-/** Update the account's autonomous-spend policy (partial patch; cents). */
-export function patchPaymentPolicy(patch, { apiKey, timeoutMs }) {
-  return apiRequest("PATCH", "/account/payment-policy", patch, { apiKey, timeoutMs });
-}

package/bin/lib/cache.mjs

@@ -1,26 +1,17 @@
 /**
- * On-disk cache (spec §9). Layout under --cache-dir (default ./.agent-relay):
+ * On-disk search cache. Layout under --cache-dir (default ./.agent-relay):
  *
- *   index.json            { slug: { ts, expires, agent_id, last_session_id } }
- *   specs/<slug>.json     a Deliverable
+ *   index.json            { slug: { ts, agent_id, name } }
  *   search/<hash>.json    { ts, expires, query, capabilities }
  *
- * This is what makes just-in-time, project-long consulting near-free: a repeat
- * consult reads specs/<slug>.json instead of re-engaging the agent.
+ * A repeat search inside the TTL is served from disk, and the index lets
+ * `session start` resolve a slug → agent_id without re-searching.
  */
 
-import {
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  rmSync,
-} from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { createHash } from "crypto";
 
-const SPEC_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 const SEARCH_TTL_MS = 60 * 60 * 1000; // 1 hour
 
 export class Cache {
@@ -28,12 +19,10 @@ export class Cache {
     this.dir = dir;
     this.enabled = enabled;
     this.indexPath = join(dir, "index.json");
-    this.specsDir = join(dir, "specs");
     this.searchDir = join(dir, "search");
   }
 
   _ensure() {
-    mkdirSync(this.specsDir, { recursive: true });
     mkdirSync(this.searchDir, { recursive: true });
   }
 
@@ -69,11 +58,7 @@ export class Cache {
     return join(this.searchDir, `${h}.json`);
   }
 
-  /**
-   * 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).
-   */
+  /** Whole unexpired search entry — `{ts, query, capabilities}` — or null. */
   readSearchEntry(query) {
     if (!this.enabled) return null;
     const entry = this._readJson(this._searchPath(query));
@@ -83,7 +68,7 @@ export class Cache {
     return entry;
   }
 
-  writeSearch(query, capabilities, paymentContext = null) {
+  writeSearch(query, capabilities) {
     if (!this.enabled) return;
     this._ensure();
     writeFileSync(
@@ -94,62 +79,10 @@ export class Cache {
           expires: Date.now() + SEARCH_TTL_MS,
           query,
           capabilities,
-          payment_context: paymentContext,
         },
         null,
         2,
       ) + "\n",
     );
   }
-
-  // ── spec (Deliverable) cache ─────────────────────────────────────────
-  _specPath(slug) {
-    return join(this.specsDir, `${slug}.json`);
-  }
-
-  readSpec(slug, { ttlMs = SPEC_TTL_MS } = {}) {
-    if (!this.enabled) return null;
-    const spec = this._readJson(this._specPath(slug));
-    if (!spec) return null;
-    if (spec.ts && Date.now() - new Date(spec.ts).getTime() > ttlMs) return null;
-    return spec;
-  }
-
-  writeSpec(slug, deliverable) {
-    if (!this.enabled) return;
-    this._ensure();
-    writeFileSync(this._specPath(slug), JSON.stringify(deliverable, null, 2) + "\n");
-  }
-
-  listSpecs() {
-    if (!existsSync(this.specsDir)) return [];
-    return readdirSync(this.specsDir)
-      .filter((f) => f.endsWith(".json"))
-      .map((f) => f.replace(/\.json$/, ""));
-  }
-
-  /**
-   * Triage view of the banked specs — read straight from each spec file (no
-   * shared index.json), so it's safe under the parallel breadth pass where N
-   * subagents each `cache put` their own slug file concurrently. Lets the main
-   * agent see what's available + each summary without opening every file.
-   */
-  listSpecHeadlines() {
-    if (!existsSync(this.specsDir)) return [];
-    return this.listSpecs().map((slug) => {
-      const spec = this._readJson(this._specPath(slug)) || {};
-      return {
-        slug,
-        name: spec.name ?? null,
-        summary: spec.summary ?? null,
-        features: Array.isArray(spec.features) ? spec.features.length : null,
-        agent_id: spec.agent_id ?? null,
-        ts: spec.ts ?? null,
-      };
-    });
-  }
-
-  clear() {
-    if (existsSync(this.dir)) rmSync(this.dir, { recursive: true, force: true });
-  }
 }