agentic-relay 3.8.0

package/bin/lib/driver.mjs

@@ -0,0 +1,165 @@
+/**
+ * Conversation driver (spec §6) — runs ONE agent's full qualify→deliver loop in
+ * isolation and returns a compact Deliverable. The agent's raw transcript never
+ * leaves this module (only the distilled Deliverable does), which is the whole
+ * point: keep transcripts out of the orchestrator's context.
+ *
+ * Completion detection prefers the backend flags (spec §10:
+ * `deliverable_complete` / `awaiting_input`) and falls back to a prose heuristic
+ * when an older backend doesn't send them.
+ */
+
+import { sessionStart, sessionMessage, sessionEnd } from "./api.mjs";
+import { extractJsonObject } from "./parse.mjs";
+import { normalizeDeliverable, hasSubstance } from "./deliverable.mjs";
+
+const OFFER_PHRASES = [
+  "reply with",
+  "let me know",
+  "want me to",
+  "which would you like",
+  "tell me",
+  "could you",
+  "can you provide",
+  "do you want",
+  "would you like",
+  "please share",
+  "please provide",
+  "to confirm",
+];
+
+/** Does this turn end expecting the user to respond before the agent proceeds? */
+export function turnAwaitsInput(turn) {
+  if (turn.deliverable_complete === true) return false; // explicit: done
+  if (turn.awaiting_input === true) return true; // explicit: waiting
+  if (Array.isArray(turn.pending_fields) && turn.pending_fields.length > 0) return true;
+  // Heuristic fallback on prose (spec §6 step 3).
+  const msg = String(turn.message || "").trim().toLowerCase();
+  if (msg.endsWith("?")) return true;
+  return OFFER_PHRASES.some((p) => msg.includes(p));
+}
+
+/**
+ * Decide whether the loop can stop. `hasDeliverable` = we've already parsed a
+ * substantive Deliverable from this (or a prior) turn. Pure + unit-tested.
+ */
+export function assessTurn(turn, hasDeliverable) {
+  if (turn.deliverable_complete === true) {
+    return { complete: true, reason: "flag:deliverable_complete" };
+  }
+  const awaiting = turnAwaitsInput(turn);
+  if (!awaiting && hasDeliverable) {
+    return { complete: true, reason: "deliverable+not-awaiting" };
+  }
+  return { complete: false, reason: awaiting ? "awaiting-input" : "no-deliverable" };
+}
+
+const SCHEMA_LINE =
+  "{verdict, install:[], env:[{name,required,desc}], endpoints:[{name,method,url,notes}], " +
+  "snippets:[{lang,path,desc,code}], gotchas:[], free_tier, docs:[]}";
+
+function buildPrimaryMessage(want, context, deliverNow) {
+  const ctx = context ? JSON.stringify(context) : "(none provided)";
+  return (
+    "You are replying to an automated coding agent, NOT a human — your reply is parsed by a program. " +
+    `Deliverable needed: ${want}. ` +
+    `Stack/context: ${ctx}. ` +
+    "Reply with ONLY one JSON object — no prose, no markdown, no ``` fences — matching this schema: " +
+    SCHEMA_LINE +
+    ". Hard rules: keep the ENTIRE reply under ~450 words; each `snippets[].code` ≤ 25 lines " +
+    "(reference the docs URL instead of pasting full multi-file implementations); use real newlines in " +
+    "code, never literal \\n; assume sensible defaults for the stack and do NOT ask questions." +
+    (deliverNow ? " Deliver the complete JSON now." : "")
+  );
+}
+
+function buildFollowup() {
+  return (
+    "Return the complete deliverable now as ONE JSON object only — no prose, no markdown, no fences — " +
+    "under ~450 words, each snippet ≤ 25 lines. Assume sensible defaults; do not ask anything further."
+  );
+}
+
+/** Trim a prose message to a short excerpt for --raw / fallback verdict. */
+function excerpt(msg, max = 1200) {
+  const s = String(msg || "").trim();
+  return s.length > max ? s.slice(0, max) + "…" : s;
+}
+
+/**
+ * Run the full loop for one capability.
+ *
+ * @param resolved { capabilityId, adUnitId, clearingPriceCents, slug, name }
+ * @param opts { want, context, deliverNow, raw, maxTurns, timeoutMs, apiKey }
+ * @returns { deliverable, sessionId, turns }
+ */
+export async function consultOne(resolved, opts) {
+  const { capabilityId, adUnitId, clearingPriceCents, slug, name } = resolved;
+  const { want, context, deliverNow, raw, maxTurns = 6, timeoutMs, apiKey } = opts;
+  const meta = { slug, name, capability_id: capabilityId, ad_unit_id: adUnitId };
+
+  let turns = 0;
+  let sessionId = null;
+  let bestDeliverable = null;
+  let lastMessage = "";
+
+  const consider = (turn) => {
+    const obj = extractJsonObject(turn.message);
+    if (obj) {
+      const d = normalizeDeliverable(obj, { ...meta, turns });
+      if (hasSubstance(d)) bestDeliverable = d;
+    }
+  };
+
+  // 1. Start the session (context as initial_data so the greeting is relevant).
+  const start = await sessionStart(
+    {
+      capabilityId,
+      adUnitId,
+      clearingPriceCents,
+      initialData: context ? { ...context, task: want } : { task: want },
+    },
+    { apiKey, timeoutMs },
+  );
+  sessionId = start.session_id;
+  turns = 1;
+  lastMessage = start.message || "";
+  consider(start);
+
+  // 2. Drive: send the want + output contract, then loop until complete.
+  let nextMessage = buildPrimaryMessage(want, context, deliverNow);
+  try {
+    while (turns < maxTurns) {
+      const resp = await sessionMessage({ sessionId, message: nextMessage }, { apiKey, timeoutMs });
+      turns += 1;
+      lastMessage = resp.message || lastMessage;
+      consider(resp);
+
+      const { complete } = assessTurn(resp, Boolean(bestDeliverable));
+      if (complete) break;
+      nextMessage = buildFollowup();
+    }
+  } finally {
+    // 3. Always release the session (best-effort; spec §6 step 6).
+    if (sessionId) {
+      try {
+        await sessionEnd({ sessionId }, { apiKey, timeoutMs });
+      } catch {
+        /* non-fatal */
+      }
+    }
+  }
+
+  // 4. Finalize. If no structured deliverable surfaced, fall back to a prose
+  //    excerpt as the verdict (and raw_excerpt when --raw).
+  if (!bestDeliverable) {
+    bestDeliverable = normalizeDeliverable(
+      { verdict: excerpt(lastMessage, 400) },
+      { ...meta, turns, raw_excerpt: raw ? excerpt(lastMessage) : null },
+    );
+  } else if (raw) {
+    bestDeliverable.raw_excerpt = excerpt(lastMessage);
+  }
+
+  return { deliverable: bestDeliverable, sessionId, turns };
+}

package/bin/lib/fetch.mjs

@@ -0,0 +1,189 @@
+/**
+ * agentrelay fetch — download a paid deliverable artifact and unpack it into a
+ * subfolder of the working directory.
+ *
+ * v1 is deliberately dumb: the artifact is an OPAQUE blob. If it's a zip we
+ * extract it; otherwise we drop the file in as-is. We NEVER execute anything
+ * from the bundle (no install scripts, no running code) — there is no content
+ * scanning yet, so contents are inert files for the user/agent to inspect.
+ *
+ * Security: verify sha256 before unpacking; detect zip by magic bytes (not
+ * extension); reject any archive entry that escapes the destination (zip-slip);
+ * never extract into the project root.
+ */
+
+import {
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+  statSync,
+} from "fs";
+import { join, resolve, basename, sep } from "path";
+import { tmpdir } from "os";
+import { createHash } from "crypto";
+import { execFileSync } from "child_process";
+
+const ZIP_MAGIC = Buffer.from([0x50, 0x4b, 0x03, 0x04]); // "PK\x03\x04"
+
+export function isZip(buf) {
+  return buf.length >= 4 && buf.subarray(0, 4).equals(ZIP_MAGIC);
+}
+
+export function sha256Hex(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+/** Slugify for a default destination folder name. */
+export function slugify(input) {
+  return (input || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+/** Infer a folder slug from an explicit filename or a URL path. */
+export function inferSlug(url, filename) {
+  if (filename) {
+    const stem = basename(filename).replace(/\.[^.]+$/, "");
+    const s = slugify(stem);
+    if (s) return s;
+  }
+  try {
+    const p = new URL(url).pathname;
+    const last = decodeURIComponent(p.split("/").filter(Boolean).pop() || "");
+    const s = slugify(last.replace(/\.[^.]+$/, ""));
+    if (s) return s;
+  } catch {
+    /* not a URL we can parse */
+  }
+  return "deliverable";
+}
+
+/** Pick a non-colliding destination dir: ./<base>, then ./<base>-1, -2, … */
+export function uniqueDir(base) {
+  let dir = resolve(base);
+  if (!existsSync(dir)) return dir;
+  for (let i = 1; i < 1000; i++) {
+    const cand = resolve(`${base}-${i}`);
+    if (!existsSync(cand)) return cand;
+  }
+  throw new Error(`could not find a free destination near ${base}`);
+}
+
+/**
+ * Validate that an `unzip -l` listing contains no zip-slip entries (absolute
+ * paths or `..` traversal that escapes dest). Returns the list of entry names.
+ * Pure-ish: takes the raw listing text so it's unit-testable.
+ */
+export function zipEntriesFromListing(listingText) {
+  // `unzip -l` columns: Length  Date  Time  Name — name is everything after
+  // the 4th whitespace-delimited column. Skip header/footer lines.
+  const names = [];
+  for (const line of listingText.split("\n")) {
+    const m = line.match(/^\s*\d+\s+\S+\s+\S+\s+(.+)$/);
+    if (m && m[1] && m[1] !== "Name") names.push(m[1].trim());
+  }
+  return names;
+}
+
+export function assertNoZipSlip(entryNames, destDir) {
+  const destRoot = resolve(destDir) + sep;
+  for (const name of entryNames) {
+    if (name.startsWith("/") || name.includes("\0")) {
+      throw new Error(`unsafe archive entry (absolute path): ${name}`);
+    }
+    const target = resolve(destDir, name);
+    if (target !== resolve(destDir) && !target.startsWith(destRoot)) {
+      throw new Error(`unsafe archive entry (path traversal / zip-slip): ${name}`);
+    }
+  }
+}
+
+function hasUnzip() {
+  try {
+    execFileSync("unzip", ["-v"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Download + unpack. opts: { url, dest?, checksum?, filename?, fetchImpl? }.
+ * Returns { ok, dest, kind, filename, checksum_sha256, placed: [...] }.
+ */
+export async function cmdFetch(opts) {
+  const { url, checksum = null, filename = null } = opts;
+  if (!url || typeof url !== "string") {
+    const e = new Error("usage: agentrelay fetch <download_url> [dest] [--checksum <sha256>] [--filename <name>]");
+    e.usage = true;
+    throw e;
+  }
+
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  const res = await fetchImpl(url);
+  if (!res.ok) throw new Error(`download failed: HTTP ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+
+  // Integrity: verify BEFORE we write anything to disk.
+  const digest = sha256Hex(buf);
+  if (checksum && digest.toLowerCase() !== String(checksum).toLowerCase()) {
+    throw new Error(`checksum mismatch: expected ${checksum}, got ${digest}`);
+  }
+
+  const slug = inferSlug(url, filename);
+  const dest = uniqueDir(opts.dest || `./${slug}`);
+
+  if (isZip(buf)) {
+    if (!hasUnzip()) {
+      throw new Error("`unzip` is required to extract a zip artifact but was not found on PATH");
+    }
+    const tmpZip = join(tmpdir(), `agent-relay-fetch-${digest.slice(0, 12)}.zip`);
+    writeFileSync(tmpZip, buf);
+    try {
+      // Zip-slip guard: inspect entries before extracting.
+      const listing = execFileSync("unzip", ["-l", tmpZip], { encoding: "utf-8" });
+      const entries = zipEntriesFromListing(listing);
+      assertNoZipSlip(entries, dest);
+
+      mkdirSync(dest, { recursive: true });
+      // -o overwrite within the freshly-created dest only; -d targets dest.
+      execFileSync("unzip", ["-o", "-q", tmpZip, "-d", dest], { stdio: "ignore" });
+    } finally {
+      try { rmSync(tmpZip, { force: true }); } catch { /* ignore */ }
+    }
+    return {
+      ok: true,
+      kind: "zip",
+      dest,
+      checksum_sha256: digest,
+      placed: listPlaced(dest),
+    };
+  }
+
+  // Non-zip: drop the single file into dest as-is.
+  mkdirSync(dest, { recursive: true });
+  const outName = filename ? basename(filename) : basename(new URL(url).pathname) || "artifact";
+  const outPath = join(dest, outName);
+  writeFileSync(outPath, buf);
+  return {
+    ok: true,
+    kind: "file",
+    dest,
+    filename: outName,
+    checksum_sha256: digest,
+    placed: [outPath],
+  };
+}
+
+function listPlaced(dir, acc = []) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) listPlaced(p, acc);
+    else acc.push(p);
+  }
+  return acc;
+}

package/bin/lib/parse.mjs

@@ -0,0 +1,148 @@
+/**
+ * Lenient JSON parsing for the AttentionMarket upstream API.
+ *
+ * The capability-session agent returns markdown + code blocks inside the
+ * `message` string. Those payloads sometimes contain lone backslashes or raw
+ * control characters that make strict `JSON.parse` throw (spec §2). Never let a
+ * parse error crash a batch — degrade gracefully instead.
+ *
+ * Strategy (in order):
+ *   1. plain JSON.parse
+ *   2. JSON.parse after doubling lone backslashes (those not starting a valid escape)
+ *   3. JSON.parse after also escaping raw control chars that appear *inside* strings
+ *   4. caller falls back to field extraction (extractFields) as a last resort
+ */
+
+/** Double backslashes that aren't part of a valid JSON escape sequence. */
+function fixLoneBackslashes(s) {
+  return s.replace(/\\(?!["\\/bfnrtu])/g, "\\\\");
+}
+
+/**
+ * Escape raw control characters (U+0000–U+001F) that occur inside a JSON string
+ * literal. Tracks quote/escape state so structural whitespace between tokens is
+ * left untouched.
+ */
+function escapeControlCharsInStrings(s) {
+  let out = "";
+  let inStr = false;
+  let esc = false;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    const code = s.charCodeAt(i);
+    if (esc) {
+      out += ch;
+      esc = false;
+      continue;
+    }
+    if (ch === "\\") {
+      out += ch;
+      esc = true;
+      continue;
+    }
+    if (ch === '"') {
+      inStr = !inStr;
+      out += ch;
+      continue;
+    }
+    if (inStr && code < 0x20) {
+      if (ch === "\n") out += "\\n";
+      else if (ch === "\r") out += "\\r";
+      else if (ch === "\t") out += "\\t";
+      else out += "\\u" + code.toString(16).padStart(4, "0");
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/**
+ * Parse a possibly-malformed JSON string. Returns
+ * `{ ok: true, value, method }` or `{ ok: false, error }`. Never throws.
+ */
+export function lenientParse(text) {
+  if (typeof text !== "string") {
+    // Already an object (e.g. response.json() succeeded upstream).
+    return { ok: true, value: text, method: "passthrough" };
+  }
+  const attempts = [
+    ["strict", (s) => s],
+    ["fixed_backslashes", fixLoneBackslashes],
+    ["escaped_controls", (s) => escapeControlCharsInStrings(fixLoneBackslashes(s))],
+  ];
+  let lastErr;
+  for (const [method, transform] of attempts) {
+    try {
+      return { ok: true, value: JSON.parse(transform(text)), method };
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  return { ok: false, error: lastErr };
+}
+
+/**
+ * Pull the first balanced JSON object out of free text — handles ```json
+ * fences and objects embedded in prose. Returns the parsed object or null.
+ */
+export function extractJsonObject(text) {
+  if (typeof text !== "string") return null;
+
+  // Prefer a fenced ```json block if present.
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidates = [];
+  if (fence) candidates.push(fence[1]);
+
+  // Then any balanced {...} span (greedy from first { to matching }).
+  const start = text.indexOf("{");
+  if (start !== -1) {
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+      const ch = text[i];
+      if (esc) { esc = false; continue; }
+      if (ch === "\\") { esc = true; continue; }
+      if (ch === '"') { inStr = !inStr; continue; }
+      if (inStr) continue;
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          candidates.push(text.slice(start, i + 1));
+          break;
+        }
+      }
+    }
+  }
+
+  for (const c of candidates) {
+    const parsed = lenientParse(c);
+    if (parsed.ok && parsed.value && typeof parsed.value === "object") {
+      return parsed.value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Last-resort field extraction: pull `"key": "..."` string values from raw text
+ * when the whole payload won't parse. Only handles flat string fields.
+ */
+export function extractFields(text, keys) {
+  const out = {};
+  if (typeof text !== "string") return out;
+  for (const key of keys) {
+    const re = new RegExp(`"${key}"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"`);
+    const m = text.match(re);
+    if (m) {
+      try {
+        out[key] = JSON.parse(`"${m[1]}"`);
+      } catch {
+        out[key] = m[1];
+      }
+    }
+  }
+  return out;
+}

package/bin/lib/pool.mjs

@@ -0,0 +1,26 @@
+/**
+ * Minimal promise pool — runs `worker(item)` over `items` with at most
+ * `concurrency` in flight. Resolves to results in input order. A worker that
+ * rejects yields `{ error }` in that slot so one failure never sinks the batch
+ * (consult-batch turns these into `failures[]` entries).
+ */
+export async function pool(items, concurrency, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+
+  async function run() {
+    for (;;) {
+      const i = next++;
+      if (i >= items.length) return;
+      try {
+        results[i] = { ok: true, value: await worker(items[i], i) };
+      } catch (error) {
+        results[i] = { ok: false, error };
+      }
+    }
+  }
+
+  const n = Math.max(1, Math.min(concurrency || 1, items.length || 1));
+  await Promise.all(Array.from({ length: n }, run));
+  return results;
+}