agentic-relay 3.8.0

package/bin/lib/commands.mjs

@@ -0,0 +1,495 @@
+/**
+ * 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.
+ */
+
+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";
+import { consultOne } from "./driver.mjs";
+
+/** Normalize one upstream capability into the spec §4 menu shape. */
+function normalizeCapability(c) {
+  const name = c.name || "";
+  return {
+    slug: slugify(name),
+    name,
+    type: c.type || "dynamic_capability",
+    relevance: typeof c.relevance_score === "number" ? c.relevance_score : null,
+    clearing_price_cents:
+      typeof c.clearing_price_cents === "number" ? c.clearing_price_cents : 0,
+    capability_id: c.capability_id || null,
+    ad_unit_id: c.ad_unit_id || null,
+    description: c.description || "",
+    click_url: c.click_url || null,
+  };
+}
+
+/** Disambiguate duplicate slugs by appending -2, -3, … (stable order). */
+function dedupeSlugs(caps) {
+  const seen = new Map();
+  for (const c of caps) {
+    const n = seen.get(c.slug) || 0;
+    seen.set(c.slug, n + 1);
+    if (n > 0) c.slug = `${c.slug}-${n + 1}`;
+  }
+  return caps;
+}
+
+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.
+  let paymentContext = opts.refresh ? null : cache.readSearchPaymentContext(query);
+
+  let capabilities = opts.refresh ? null : cache.readSearch(query);
+  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);
+    // Seed the index so consult can resolve ids without re-searching.
+    for (const c of capabilities) {
+      if (c.capability_id && c.ad_unit_id) {
+        cache.updateIndex(c.slug, {
+          capability_id: c.capability_id,
+          ad_unit_id: c.ad_unit_id,
+          clearing_price_cents: c.clearing_price_cents,
+          name: c.name,
+          ts: new Date().toISOString(),
+        });
+      }
+    }
+  }
+
+  if (opts.dynamicOnly) {
+    capabilities = capabilities.filter((c) => c.type === "dynamic_capability");
+  }
+  capabilities = capabilities.slice(0, maxResults);
+
+  return { query, count: capabilities.length, capabilities, payment_context: paymentContext };
+}
+
+/**
+ * Resolve a slug (or capability_id) to { capabilityId, adUnitId,
+ * clearingPriceCents, 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).
+ */
+export async function resolveCapability(slugOrId, opts) {
+  const cache = new Cache(opts.cacheDir, { enabled: !opts.noCache });
+  const slug = slugify(slugOrId);
+
+  const entry = cache.getIndexEntry(slug) || cache.getIndexEntry(slugOrId);
+  if (entry && entry.capability_id && entry.ad_unit_id && !opts.refresh) {
+    return {
+      capabilityId: entry.capability_id,
+      adUnitId: entry.ad_unit_id,
+      clearingPriceCents: entry.clearing_price_cents || 0,
+      slug,
+      name: entry.name || slug,
+    };
+  }
+
+  // Banked spec fallback — a breadth subagent stored ids here via `cache put`.
+  if (!opts.refresh) {
+    const spec = cache.readSpec(slug, { ttlMs: Infinity });
+    if (spec && spec.capability_id && spec.ad_unit_id) {
+      return {
+        capabilityId: spec.capability_id,
+        adUnitId: spec.ad_unit_id,
+        clearingPriceCents: spec.clearing_price_cents || 0,
+        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 });
+  const match =
+    found.capabilities.find((c) => c.slug === slug) ||
+    found.capabilities.find((c) => c.capability_id === slugOrId) ||
+    found.capabilities.find((c) => c.slug.startsWith(slug));
+  if (!match || !match.capability_id || !match.ad_unit_id) {
+    throw new Error(
+      `could not resolve "${slugOrId}" — run \`agentrelay search\` first or pass a known slug`,
+    );
+  }
+  return {
+    capabilityId: match.capability_id,
+    adUnitId: match.ad_unit_id,
+    clearingPriceCents: match.clearing_price_cents || 0,
+    slug: match.slug,
+    name: match.name,
+  };
+}
+
+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;
+  try {
+    return JSON.parse(s);
+  } catch (err) {
+    const e = new Error(`--${name} must be valid JSON: ${err.message}`);
+    e.usage = true;
+    throw e;
+  }
+}
+
+/** Shape a raw session turn for output — the agent's message is passed through. */
+export function shapeSessionTurn(r) {
+  return {
+    session_id: r.session_id,
+    message: r.message,
+    awaiting_input: r.awaiting_input ?? null,
+    deliverable_complete: r.deliverable_complete ?? null,
+    pending_fields: r.pending_fields ?? [],
+    structured_data: r.structured_data ?? {},
+    ...(r.expires_at ? { expires_at: r.expires_at } : {}),
+    // Advisory: surfaced by api-v1 when the seller owes a charge. Never blocks the turn;
+    // decide auto-pay vs bubble against the cached payment_context (see SKILL.md Pay).
+    ...(r.payment_required ? { payment_required: r.payment_required } : {}),
+  };
+}
+
+export async function cmdSession(sub, positionals, opts) {
+  const net = { apiKey: opts.apiKey, timeoutMs: opts.timeoutMs };
+
+  if (sub === "start") {
+    const slugOrId = positionals[0];
+    if (!slugOrId) {
+      const e = new Error("usage: agentrelay session start <slug|capability_id> [--initial json] [--message m]");
+      e.usage = true;
+      throw e;
+    }
+    const resolved = await resolveCapability(slugOrId, opts);
+    const start = await sessionStart(
+      {
+        capabilityId: resolved.capabilityId,
+        adUnitId: resolved.adUnitId,
+        clearingPriceCents: resolved.clearingPriceCents,
+        initialData: parseJsonFlag(opts.initial, "initial"),
+      },
+      net,
+    );
+    // NOTE: intentionally no `cache.updateIndex` here. `session start` is called
+    // by parallel breadth subagents (separate processes); a shared index.json
+    // read-modify-write would race. The session_id is returned to the caller
+    // below, and ids resolve via search-seeded index or the banked spec file.
+    // --message: send the first turn in the same call for convenience.
+    if (opts.message) {
+      const turn = await sessionMessage({ sessionId: start.session_id, message: opts.message }, net);
+      return {
+        slug: resolved.slug,
+        greeting: start.message,
+        ...shapeSessionTurn({ ...turn, session_id: start.session_id, expires_at: start.expires_at }),
+      };
+    }
+    return { slug: resolved.slug, ...shapeSessionTurn(start) };
+  }
+
+  if (sub === "send") {
+    const sessionId = positionals[0];
+    const message = positionals.slice(1).join(" ").trim();
+    if (!sessionId || !message) {
+      const e = new Error('usage: agentrelay session send <session_id> "<message>" [--data json]');
+      e.usage = true;
+      throw e;
+    }
+    const turn = await sessionMessage(
+      { sessionId, message, structuredData: parseJsonFlag(opts.data, "data") },
+      net,
+    );
+    return shapeSessionTurn({ ...turn, session_id: sessionId });
+  }
+
+  if (sub === "end") {
+    const sessionId = positionals[0];
+    if (!sessionId) {
+      const e = new Error("usage: agentrelay session end <session_id>");
+      e.usage = true;
+      throw e;
+    }
+    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)`);
+  e.usage = true;
+  throw e;
+}
+
+export async function cmdFeedback(sessionId, opts) {
+  if (!sessionId || opts.score == null) {
+    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) },
+    { 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();
+    // 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 };
+  }
+  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

@@ -0,0 +1,69 @@
+/**
+ * Config + credential resolution for the agent-relay CLI.
+ *
+ * Key resolution order (spec §2): --api-key flag → AGENT_RELAY_API_KEY env →
+ * ~/.config/agent-relay/credentials.json → legacy ~/.config/penguin/credentials.json
+ * (read-only fallback so pre-rename keys keep working). File shape:
+ * {"api_key":"am_live_..."}.
+ *
+ * The key is NEVER printed or logged. Callers receive it only to set the
+ * X-AM-API-Key header.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+export const API_BASE =
+  "https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/api-v1";
+
+export const CREDENTIALS_PATH = join(
+  homedir(),
+  ".config",
+  "agent-relay",
+  "credentials.json",
+);
+
+// Pre-rename location — read as a fallback only; never written.
+export const LEGACY_CREDENTIALS_PATH = join(
+  homedir(),
+  ".config",
+  "penguin",
+  "credentials.json",
+);
+
+function readKeyFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const creds = JSON.parse(readFileSync(path, "utf-8"));
+    if (creds.api_key && String(creds.api_key).trim()) {
+      return String(creds.api_key).trim();
+    }
+  } catch {
+    // fall through — treated as "no key"
+  }
+  return null;
+}
+
+/**
+ * Resolve the API key. `flagKey` is the value of --api-key (or null).
+ * Returns the key string, or null if none is configured.
+ */
+export function resolveApiKey(flagKey) {
+  if (flagKey && flagKey.trim()) return flagKey.trim();
+
+  const envKey = process.env.AGENT_RELAY_API_KEY;
+  if (envKey && envKey.trim()) return envKey.trim();
+
+  return readKeyFile(CREDENTIALS_PATH) || readKeyFile(LEGACY_CREDENTIALS_PATH);
+}
+
+/** kebab-case a capability name into a stable slug used for cache + consult. */
+export function slugify(name) {
+  return String(name || "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60) || "capability";
+}

package/bin/lib/deliverable.mjs

@@ -0,0 +1,70 @@
+/**
+ * Deliverable schema (spec §5) — the structured contract every consult resolves
+ * to. Agents are *prompted* to return this JSON (see driver.mjs output
+ * contract); this module validates/normalizes whatever comes back so the
+ * orchestrator always gets a predictable, compact object. Hand-rolled (no zod)
+ * to keep the package zero-dependency. Mirrors schema/deliverable.json.
+ */
+
+function asStringArray(v) {
+  if (Array.isArray(v)) return v.filter((x) => typeof x === "string");
+  if (typeof v === "string" && v.trim()) return [v.trim()];
+  return [];
+}
+
+function asObjectArray(v) {
+  return Array.isArray(v) ? v.filter((x) => x && typeof x === "object") : [];
+}
+
+/** chars/4 token estimate (spec §6 step 7). */
+export function estimateTokens(obj) {
+  try {
+    return Math.round(JSON.stringify(obj).length / 4);
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Normalize a raw object (parsed from the agent's final message) into a
+ * Deliverable. `meta` carries CLI-known fields (slug, ids, turns, cached, raw).
+ */
+export function normalizeDeliverable(raw, meta = {}) {
+  const r = raw && typeof raw === "object" ? raw : {};
+  const d = {
+    slug: meta.slug || r.slug || "capability",
+    name: meta.name || r.name || meta.slug || "Capability",
+    capability_id: meta.capability_id || r.capability_id || null,
+    ad_unit_id: meta.ad_unit_id || r.ad_unit_id || null,
+    verdict: typeof r.verdict === "string" ? r.verdict : "",
+    install: asStringArray(r.install),
+    env: asObjectArray(r.env),
+    endpoints: asObjectArray(r.endpoints),
+    snippets: asObjectArray(r.snippets),
+    gotchas: asStringArray(r.gotchas),
+    free_tier: typeof r.free_tier === "string" ? r.free_tier : null,
+    docs: asStringArray(r.docs),
+    turns: meta.turns ?? 0,
+    cached: meta.cached ?? false,
+    ts: meta.ts || new Date().toISOString(),
+  };
+  d.tokens_estimate = estimateTokens(d);
+  if (meta.raw_excerpt) d.raw_excerpt = meta.raw_excerpt;
+  else d.raw_excerpt = null;
+  return d;
+}
+
+/**
+ * True if the object carries enough substance to count as a real deliverable
+ * (so we don't cache an empty shell from a turn that only asked a question).
+ */
+export function hasSubstance(d) {
+  return Boolean(
+    (d.verdict && d.verdict.length > 0) ||
+      d.install.length ||
+      d.endpoints.length ||
+      d.snippets.length ||
+      d.gotchas.length ||
+      d.docs.length,
+  );
+}