agentic-relay 3.8.0

package/bin/lib/api.mjs

@@ -0,0 +1,188 @@
+/**
+ * Thin upstream client for the AttentionMarket REST API (spec §2). Every call is
+ * wrapped with a timeout (AbortController) and lenient JSON parsing so a
+ * malformed body or slow turn degrades to a handled error rather than a crash.
+ *
+ * The API key is set on the X-AM-API-Key header and never logged.
+ */
+
+import { API_BASE } from "./config.mjs";
+import { lenientParse } from "./parse.mjs";
+
+export class ApiError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * POST JSON to `${API_BASE}${path}`. Returns the parsed response body.
+ * Throws ApiError on non-2xx, timeout, or network failure.
+ */
+export async function apiPost(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: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-AM-API-Key": apiKey,
+      },
+      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;
+}
+
+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 sessionStart(
+  { capabilityId, adUnitId, clearingPriceCents, initialData },
+  { apiKey, timeoutMs },
+) {
+  return apiPost(
+    "/session/start",
+    {
+      capability_id: capabilityId,
+      ad_unit_id: adUnitId,
+      clearing_price_cents: clearingPriceCents,
+      ...(initialData ? { initial_data: initialData } : {}),
+    },
+    { apiKey, timeoutMs },
+  );
+}
+
+export function sessionMessage(
+  { sessionId, message, structuredData },
+  { apiKey, timeoutMs },
+) {
+  return apiPost(
+    "/session/message",
+    {
+      session_id: sessionId,
+      message,
+      ...(structuredData ? { structured_data: structuredData } : {}),
+    },
+    { apiKey, timeoutMs },
+  );
+}
+
+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, referenceId, paymentCredential }, { apiKey, timeoutMs }) {
+  try {
+    return await apiPost(
+      "/session/pay",
+      {
+        ...(sessionId ? { session_id: sessionId } : {}),
+        ...(referenceId ? { reference_id: referenceId } : {}),
+        ...(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",
+    { session_id: sessionId, feedback_text: feedbackText, score },
+    { 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

@@ -0,0 +1,161 @@
+/**
+ * On-disk cache (spec §9). Layout under --cache-dir (default ./.agent-relay):
+ *
+ *   index.json            { slug: { ts, expires, capability_id, ad_unit_id, last_session_id } }
+ *   specs/<slug>.json     a Deliverable
+ *   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.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+} 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 {
+  constructor(dir = ".agent-relay", { enabled = true } = {}) {
+    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 });
+  }
+
+  _readJson(path) {
+    if (!existsSync(path)) return null;
+    try {
+      return JSON.parse(readFileSync(path, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+
+  // ── index ────────────────────────────────────────────────────────────
+  readIndex() {
+    return this._readJson(this.indexPath) || {};
+  }
+
+  updateIndex(slug, entry) {
+    if (!this.enabled) return;
+    this._ensure();
+    const index = this.readIndex();
+    index[slug] = { ...(index[slug] || {}), ...entry };
+    writeFileSync(this.indexPath, JSON.stringify(index, null, 2) + "\n");
+  }
+
+  getIndexEntry(slug) {
+    return this.readIndex()[slug] || null;
+  }
+
+  // ── search cache ─────────────────────────────────────────────────────
+  _searchPath(query) {
+    const h = createHash("sha1").update(query).digest("hex").slice(0, 16);
+    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) {
+    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;
+  }
+
+  writeSearch(query, capabilities, paymentContext = null) {
+    if (!this.enabled) return;
+    this._ensure();
+    writeFileSync(
+      this._searchPath(query),
+      JSON.stringify(
+        {
+          ts: new Date().toISOString(),
+          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,
+        capability_id: spec.capability_id ?? null,
+        ts: spec.ts ?? null,
+      };
+    });
+  }
+
+  clear() {
+    if (existsSync(this.dir)) rmSync(this.dir, { recursive: true, force: true });
+  }
+}