agentic-relay 3.8.0

package/bin/relay-core.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+/**
+ * agentrelay (CLI core) — token-cheap, parallel agent consulting for coding workflows.
+ *
+ * Wraps the AttentionMarket REST API so a coding agent can consult expert
+ * "solutions-engineer" capability agents without flooding its context with raw
+ * transcripts. The multi-turn qualify→deliver loop, fan-out, and caching run
+ * HERE (in this process), and only compact Deliverables come back.
+ *
+ * Commands:
+ *   agentrelay search <query>        broad discovery (cheap; safe in main context)
+ *   agentrelay consult <slug>        run one agent's full loop → a Deliverable
+ *   agentrelay consult-batch         fan-out, parallel, one consolidated result
+ *   agentrelay cache ls|show|clear   inspect/manage the on-disk spec cache
+ *
+ * Output: a `{ ok, ...payload, errors: [] }` envelope. --json forces machine
+ * output (auto-on when stdout is not a TTY). Exit codes: 0 ok, 1 partial,
+ * 2 usage, 3 auth/config. The API key is never printed.
+ *
+ * Dispatched from bin/cli.mjs (the single `agentrelay` bin). Install globally
+ * with `npm i -g agentic-relay` for a bare `agentrelay` command.
+ */
+
+import { readFileSync } from "fs";
+import { resolveApiKey } from "./lib/config.mjs";
+import {
+  cmdSearch,
+  cmdConsult,
+  cmdConsultBatch,
+  cmdSession,
+  cmdFeedback,
+  cmdCache,
+  cmdBudget,
+  cmdConnectWallet,
+} from "./lib/commands.mjs";
+import { cmdFetch } from "./lib/fetch.mjs";
+
+const EXIT = { OK: 0, PARTIAL: 1, USAGE: 2, AUTH: 3 };
+
+const FLAGS_WITH_VALUE = new Set([
+  "--api-key",
+  "--context",
+  "--cache-dir",
+  "--timeout",
+  "--max-turns",
+  "--concurrency",
+  "--max",
+  "--user-context",
+  "--want",
+  "--want-file",
+  "--agents",
+  "--driver",
+  "--initial",
+  "--message",
+  "--data",
+  "--score",
+  "--text",
+  "--file",
+  "--auto-approve",
+  "--daily-cap",
+  "--require-human-over",
+  "--per-session-cap",
+  "--credential",
+  "--checksum",
+  "--filename",
+]);
+
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else if (FLAGS_WITH_VALUE.has(a) && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) {
+        flags[a.slice(2)] = argv[++i];
+      } else {
+        flags[a.slice(2)] = true;
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { flags, positionals };
+}
+
+function loadContext(path) {
+  if (!path) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    const e = new Error(`could not read --context ${path}: ${err.message}`);
+    e.usage = true;
+    throw e;
+  }
+}
+
+function buildShared(flags) {
+  return {
+    apiKey: resolveApiKey(flags["api-key"] || null),
+    json: Boolean(flags.json) || !process.stdout.isTTY,
+    cacheDir: flags["cache-dir"] || ".agent-relay",
+    noCache: Boolean(flags["no-cache"]),
+    refresh: Boolean(flags.refresh),
+    timeoutMs: (Number(flags.timeout) || 120) * 1000,
+    maxTurns: Number(flags["max-turns"]) || 6,
+    concurrency: Number(flags.concurrency) || 5,
+    quiet: Boolean(flags.quiet),
+    verbose: Boolean(flags.verbose),
+    context: loadContext(flags.context),
+  };
+}
+
+// ── output ──────────────────────────────────────────────────────────────
+function emit(payload, { ok = true, errors = [], json, exitCode = EXIT.OK, human } = {}) {
+  const envelope = { ok, ...payload, errors };
+  if (json) {
+    process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
+  } else if (human) {
+    process.stdout.write(human(envelope) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
+  }
+  process.exit(exitCode);
+}
+
+function fail(message, exitCode, json) {
+  const envelope = { ok: false, errors: [message] };
+  if (json) process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
+  else process.stderr.write(`agentrelay: ${message}\n`);
+  process.exit(exitCode);
+}
+
+// ── human formatters ──────────────────────────────────────────────────────
+const fmtSearch = (e) => {
+  const lines = [`${e.count} capabilities for "${e.query}"`];
+  for (const c of e.capabilities) {
+    const price = c.clearing_price_cents ? `$${(c.clearing_price_cents / 100).toFixed(2)}` : "free";
+    const rel = c.relevance != null ? c.relevance.toFixed(2) : "—";
+    const kind = c.type === "static_offer" ? "[offer]" : "[agent]";
+    const desc = c.description.length > 90 ? c.description.slice(0, 90) + "…" : c.description;
+    lines.push(`  ${kind} ${c.slug}  (rel ${rel}, ${price})  ${c.name}`);
+    if (desc) lines.push(`        ${desc}`);
+  }
+  return lines.join("\n");
+};
+
+const fmtBudget = (e) => {
+  const p = e.policy || {};
+  const dol = (c) => (c == null ? "—" : `$${(c / 100).toFixed(2)}`);
+  return [
+    `autonomous pay: ${p.autonomous_enabled ? "ENABLED" : "disabled (ask every time)"}`,
+    `  auto-approve under:  ${dol(p.auto_approve_under_cents)}`,
+    `  require human over:  ${dol(p.require_human_over_cents)}`,
+    `  daily cap:           ${dol(p.daily_cap_cents)}`,
+    `  per-session cap:     ${dol(p.per_session_cap_cents)}`,
+    `  wallet methods:      ${(p.wallet_methods && p.wallet_methods.length) ? p.wallet_methods.join(", ") : "none connected"}`,
+  ].join("\n");
+};
+
+const fmtDeliverable = (d) => {
+  const lines = [`▸ ${d.name} (${d.slug})${d.cached ? " [cached]" : ""}`];
+  if (d.verdict) lines.push(`  verdict: ${d.verdict}`);
+  if (d.install?.length) lines.push(`  install: ${d.install.join(" && ")}`);
+  if (d.endpoints?.length) lines.push(`  endpoints: ${d.endpoints.map((x) => x.name || x.url).join(", ")}`);
+  if (d.snippets?.length) lines.push(`  snippets: ${d.snippets.map((s) => s.path || s.desc || s.lang).join(", ")}`);
+  if (d.gotchas?.length) lines.push(`  gotchas: ${d.gotchas.join("; ")}`);
+  if (d.free_tier) lines.push(`  free tier: ${d.free_tier}`);
+  if (d.docs?.length) lines.push(`  docs: ${d.docs.join(" ")}`);
+  lines.push(`  (${d.turns} turns, ~${d.tokens_estimate} tokens)`);
+  return lines.join("\n");
+};
+
+const HELP = `agentrelay — converse with capability agents while you build.
+
+Conversation (LLM-driven — drive these from a subagent, or directly when you're stuck):
+  agentrelay session start <slug>     [--initial json] [--message "<first msg>"]
+  agentrelay session send <id> "<m>"  [--data json]
+  agentrelay session pay <id>         [--credential <mpp>]  settle a payment_required
+  agentrelay session end <id>
+  agentrelay feedback <id>            --score <0-100> --text "<s>"
+
+Discovery + cache:
+  agentrelay search <query>           [--max 25] [--user-context <s>] [--dynamic-only]
+  agentrelay cache ls | show <slug> | put <slug> [--file f.json] | clear
+
+Payments (autonomous spend policy — server-canonical):
+  agentrelay budget                   show current policy
+  agentrelay budget --enable|--disable  [--auto-approve=<$>] [--daily-cap=<$>]
+                                     [--require-human-over=<$>] [--per-session-cap=<$>]
+  agentrelay connect-wallet           (wallet connect is set up in the dashboard)
+
+Deliverables (after a paid session returns a delivery object):
+  agentrelay fetch <download_url> [dest]  [--checksum <sha256>] [--filename <name>]
+                                     download + unpack into ./<slug>/ (never executes anything)
+
+Template fallback (code-driven, no LLM — distilled result):
+  agentrelay consult <slug>           --want <s> [--context f.json] [--deliver-now] [--refresh]
+  agentrelay consult-batch            --agents a,b,c (--want <s> | --want-file w.json) [--concurrency 5]
+
+Global: --api-key <k> --json --context <f> --cache-dir <d> --no-cache
+        --timeout <sec> --max-turns <n> --concurrency <n> --quiet --verbose
+
+Key: --api-key | $AGENT_RELAY_API_KEY | ~/.config/agent-relay/credentials.json`;
+
+// ── main ──────────────────────────────────────────────────────────────────
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const { flags, positionals } = parseArgs(argv.slice(1));
+
+  if (!cmd || cmd === "help" || flags.help) {
+    process.stdout.write(HELP + "\n");
+    process.exit(cmd ? EXIT.OK : EXIT.USAGE);
+  }
+  if (cmd === "version" || flags.version) {
+    let v = "unknown";
+    try {
+      v = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
+    } catch { /* fall back to "unknown" */ }
+    process.stdout.write(`agentrelay ${v}\n`);
+    process.exit(EXIT.OK);
+  }
+
+  let shared;
+  try {
+    shared = buildShared(flags);
+  } catch (err) {
+    return fail(err.message, EXIT.USAGE, Boolean(flags.json) || !process.stdout.isTTY);
+  }
+  const json = shared.json;
+
+  // cache and fetch are the only commands that don't need a key.
+  if (cmd !== "cache" && cmd !== "fetch" && !shared.apiKey) {
+    return fail(
+      "no API key — set --api-key, $AGENT_RELAY_API_KEY, or ~/.config/agent-relay/credentials.json",
+      EXIT.AUTH,
+      json,
+    );
+  }
+
+  try {
+    switch (cmd) {
+      case "search": {
+        const query = positionals.join(" ").trim();
+        if (!query) return fail("usage: agentrelay search <query>", EXIT.USAGE, json);
+        const payload = await cmdSearch(query, {
+          ...shared,
+          max: Number(flags.max) || 25,
+          userContext: flags["user-context"] || null,
+          dynamicOnly: Boolean(flags["dynamic-only"]),
+        });
+        return emit(payload, { json, human: fmtSearch });
+      }
+
+      case "consult": {
+        const slug = positionals[0];
+        if (!slug) return fail("usage: agentrelay consult <slug> --want <str>", EXIT.USAGE, json);
+        const payload = await cmdConsult(slug, {
+          ...shared,
+          want: flags.want || null,
+          driver: flags.driver || null,
+          deliverNow: Boolean(flags["deliver-now"]),
+          raw: Boolean(flags.raw),
+        });
+        return emit(payload, { json, human: (e) => fmtDeliverable(e.deliverable) });
+      }
+
+      case "consult-batch": {
+        const payload = await cmdConsultBatch({
+          ...shared,
+          agents: flags.agents ? String(flags.agents).split(",").map((s) => s.trim()).filter(Boolean) : null,
+          want: flags.want || null,
+          wantFile: flags["want-file"] || null,
+          driver: flags.driver || null,
+          deliverNow: Boolean(flags["deliver-now"]),
+          raw: Boolean(flags.raw),
+        });
+        const exitCode = payload.failures.length > 0 ? EXIT.PARTIAL : EXIT.OK;
+        return emit(payload, {
+          json,
+          ok: payload.failures.length === 0,
+          errors: payload.failures.map((f) => `${f.slug}: ${f.reason}`),
+          exitCode,
+          human: (e) =>
+            [
+              `consulted ${e.totals.consulted}: ${e.totals.ok} ok, ${e.totals.failed} failed ` +
+                `(${e.totals.wall_seconds}s, ~${e.totals.tokens_estimate} tokens)`,
+              ...e.deliverables.map(fmtDeliverable),
+              ...e.failures.map((f) => `✗ ${f.slug}: ${f.reason}`),
+            ].join("\n"),
+        });
+      }
+
+      case "session": {
+        const payload = await cmdSession(positionals[0], positionals.slice(1), {
+          ...shared,
+          initial: flags.initial || null,
+          message: flags.message || null,
+          data: flags.data || null,
+          credential: flags.credential || null,
+        });
+        return emit(payload, { json });
+      }
+
+      case "feedback": {
+        const payload = await cmdFeedback(positionals[0], {
+          ...shared,
+          score: flags.score != null ? flags.score : null,
+          text: flags.text || null,
+        });
+        return emit(payload, { json });
+      }
+
+      case "budget": {
+        const payload = await cmdBudget({
+          ...shared,
+          autoApprove: flags["auto-approve"] != null ? flags["auto-approve"] : null,
+          dailyCap: flags["daily-cap"] != null ? flags["daily-cap"] : null,
+          requireHumanOver: flags["require-human-over"] != null ? flags["require-human-over"] : null,
+          perSessionCap: flags["per-session-cap"] != null ? flags["per-session-cap"] : null,
+          enable: Boolean(flags.enable),
+          disable: Boolean(flags.disable),
+        });
+        return emit(payload, { json, human: fmtBudget });
+      }
+
+      case "connect-wallet": {
+        const payload = cmdConnectWallet();
+        return emit(payload, { json, human: (e) => e.message });
+      }
+
+      case "fetch": {
+        // Download a paid deliverable and unpack into ./<slug>/ (no API key needed).
+        // NEVER executes anything from the bundle.
+        const payload = await cmdFetch({
+          url: positionals[0],
+          dest: positionals[1] || null,
+          checksum: flags.checksum || null,
+          filename: flags.filename || null,
+        });
+        return emit(payload, {
+          json,
+          human: (e) =>
+            [`Fetched ${e.kind} → ${e.dest}`, ...e.placed.map((p) => `  ${p}`),
+             `Nothing was executed — inspect the files before use.`].join("\n"),
+        });
+      }
+
+      case "cache": {
+        const payload = cmdCache(positionals[0], positionals[1], { ...shared, file: flags.file || null });
+        const human = Array.isArray(payload.specs)
+          ? (e) =>
+              [`${e.specs.length} banked specs (${e.cache_dir})`, ...e.specs.map((s) => {
+                const feat = s.features != null ? ` (${s.features} features)` : "";
+                const sum = s.summary ? ` — ${s.summary.length > 100 ? s.summary.slice(0, 100) + "…" : s.summary}` : "";
+                return `  ${s.slug}${feat}${sum}`;
+              })].join("\n")
+          : undefined;
+        return emit(payload, { json, human });
+      }
+
+      default:
+        return fail(
+          `unknown command "${cmd}" (session|search|consult|consult-batch|feedback|cache|budget|connect-wallet|fetch)`,
+          EXIT.USAGE,
+          json,
+        );
+    }
+  } catch (err) {
+    const code = err.usage ? EXIT.USAGE : EXIT.PARTIAL;
+    return fail(err.message || String(err), code, json);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`agentrelay: fatal: ${err.message}\n`);
+  process.exit(EXIT.PARTIAL);
+});

package/bin/test/budget.test.mjs

@@ -0,0 +1,31 @@
+/**
+ * Tests for the `budget` command's dollar→cents conversion + validation.
+ * Run: `node --test bin/test/`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { dollarsToCents } from "../lib/commands.mjs";
+
+test("dollarsToCents: whole dollars → cents", () => {
+  assert.equal(dollarsToCents("--daily-cap", 50), 5000);
+  assert.equal(dollarsToCents("--daily-cap", "50"), 5000);
+});
+
+test("dollarsToCents: fractional dollars round to nearest cent", () => {
+  assert.equal(dollarsToCents("--auto-approve", 2.5), 250);
+  assert.equal(dollarsToCents("--auto-approve", "0.99"), 99);
+  assert.equal(dollarsToCents("--auto-approve", 1.01), 101);
+});
+
+test("dollarsToCents: zero is allowed (e.g. auto-approve nothing)", () => {
+  assert.equal(dollarsToCents("--auto-approve", 0), 0);
+});
+
+test("dollarsToCents: negative is a usage error", () => {
+  assert.throws(() => dollarsToCents("--daily-cap", -5), (e) => e.usage === true);
+});
+
+test("dollarsToCents: non-numeric is a usage error", () => {
+  assert.throws(() => dollarsToCents("--daily-cap", "abc"), (e) => e.usage === true);
+  assert.throws(() => dollarsToCents("--daily-cap", "5dollars"), (e) => e.usage === true);
+});

package/bin/test/cache.test.mjs

@@ -0,0 +1,71 @@
+/**
+ * Tests for the banked-cache contract: race-safe `listSpecHeadlines` (reads
+ * spec files, no index.json) and `resolveCapability`'s spec-file id fallback
+ * (so a depth session resolves from what a breadth subagent banked). No network.
+ * Run: `node --test bin/test/cache.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Cache } from "../lib/cache.mjs";
+import { resolveCapability } from "../lib/commands.mjs";
+
+const ISO = "2026-05-24T00:00:00.000Z";
+
+function withCache(fn) {
+  const dir = mkdtempSync(join(tmpdir(), "agent-relay-bank-"));
+  try {
+    return fn(dir, new Cache(dir));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("listSpecHeadlines: returns slug+name+summary+feature-count, no index.json needed", () => {
+  withCache((dir, cache) => {
+    cache.writeSpec("a-tool", {
+      slug: "a-tool", name: "A", summary: "does A",
+      features: [{ feature: "x", how: "y" }], capability_id: "cap-a", ts: ISO,
+    });
+    cache.writeSpec("b-tool", { slug: "b-tool", name: "B", summary: "does B", features: [], ts: ISO });
+
+    const h = cache.listSpecHeadlines();
+    assert.equal(h.length, 2);
+    const a = h.find((x) => x.slug === "a-tool");
+    assert.equal(a.name, "A");
+    assert.equal(a.summary, "does A");
+    assert.equal(a.features, 1);
+    assert.equal(a.capability_id, "cap-a");
+    // Race-safe: the put path never wrote a shared index.json.
+    assert.equal(existsSync(join(dir, "index.json")), false);
+  });
+});
+
+test("listSpecHeadlines: tolerates a spec missing the optional fields", () => {
+  withCache((_dir, cache) => {
+    cache.writeSpec("bare", { slug: "bare", ts: ISO }); // no name/summary/features
+    const h = cache.listSpecHeadlines();
+    assert.equal(h.length, 1);
+    assert.equal(h[0].slug, "bare");
+    assert.equal(h[0].summary, null);
+    assert.equal(h[0].features, null);
+  });
+});
+
+test("resolveCapability: falls back to the banked spec's ids (no network)", async () => {
+  await withCache(async (dir, cache) => {
+    cache.writeSpec("a-tool", {
+      slug: "a-tool", name: "A Tool", summary: "s", features: [],
+      capability_id: "cap-a", ad_unit_id: "unit-a", clearing_price_cents: 130, ts: ISO,
+    });
+    // No index.json, refresh falsy → must resolve from the spec file alone.
+    const r = await resolveCapability("a-tool", { cacheDir: dir, noCache: false });
+    assert.equal(r.capabilityId, "cap-a");
+    assert.equal(r.adUnitId, "unit-a");
+    assert.equal(r.clearingPriceCents, 130);
+    assert.equal(r.slug, "a-tool");
+    assert.equal(r.name, "A Tool");
+  });
+});

package/bin/test/driver.test.mjs

@@ -0,0 +1,49 @@
+/**
+ * Tests for the completion logic in the conversation driver (spec §6/§10).
+ * Pure functions only — no network. Run: `node --test bin/test/driver.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { turnAwaitsInput, assessTurn } from "../lib/driver.mjs";
+
+test("backend flag deliverable_complete wins over prose", () => {
+  // Message ends in a question, but the backend says it's complete.
+  const turn = { message: "Anything else?", deliverable_complete: true };
+  assert.equal(turnAwaitsInput(turn), false);
+  assert.deepEqual(assessTurn(turn, false).complete, true);
+});
+
+test("backend flag awaiting_input forces another turn", () => {
+  const turn = { message: "Here is everything you need.", awaiting_input: true };
+  assert.equal(turnAwaitsInput(turn), true);
+  assert.equal(assessTurn(turn, true).complete, false);
+});
+
+test("heuristic: non-empty pending_fields means awaiting", () => {
+  const turn = { message: "Got it.", pending_fields: ["api_key"] };
+  assert.equal(turnAwaitsInput(turn), true);
+});
+
+test("heuristic: a question mark means awaiting (no flags)", () => {
+  const turn = { message: "Which framework — Next.js or Remix?" };
+  assert.equal(turnAwaitsInput(turn), true);
+  assert.equal(assessTurn(turn, false).complete, false);
+});
+
+test("heuristic: offer phrase means awaiting", () => {
+  const turn = { message: "I can do that. Let me know if you want the proxy too." };
+  assert.equal(turnAwaitsInput(turn), true);
+});
+
+test("complete when a substantive deliverable exists and not awaiting", () => {
+  const turn = { message: "Here is the typed fetcher and endpoints." };
+  assert.equal(turnAwaitsInput(turn), false);
+  assert.equal(assessTurn(turn, true).complete, true);
+});
+
+test("not complete when not awaiting but no deliverable yet", () => {
+  const turn = { message: "Sure, I can help with that." };
+  const a = assessTurn(turn, false);
+  assert.equal(a.complete, false);
+  assert.equal(a.reason, "no-deliverable");
+});

package/bin/test/fetch.test.mjs

@@ -0,0 +1,128 @@
+/**
+ * Tests for `agent-relay fetch` — the deliverable download/unpack helper.
+ * Covers: sha256 verify, zip magic-byte detection, zip-slip rejection, slug
+ * inference, non-colliding dest, and "never execute" (we only write files).
+ * No network: a fake fetchImpl returns in-memory buffers.
+ * Run: `node --test bin/test/fetch.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  isZip,
+  sha256Hex,
+  inferSlug,
+  uniqueDir,
+  zipEntriesFromListing,
+  assertNoZipSlip,
+  cmdFetch,
+} from "../lib/fetch.mjs";
+
+function fakeFetch(buf, ok = true, status = 200) {
+  return async () => ({ ok, status, arrayBuffer: async () => buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) });
+}
+
+test("isZip detects PK magic bytes, not extension", () => {
+  assert.equal(isZip(Buffer.from([0x50, 0x4b, 0x03, 0x04, 0x00])), true);
+  assert.equal(isZip(Buffer.from("hello world")), false);
+});
+
+test("sha256Hex matches known digest", () => {
+  // echo -n "" | sha256sum
+  assert.equal(sha256Hex(Buffer.from("")), "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+});
+
+test("inferSlug from filename and URL", () => {
+  assert.equal(inferSlug("https://x/y/abc.zip", "My Cool Skill.zip"), "my-cool-skill");
+  assert.equal(inferSlug("https://x/storage/sign/Acme_Bundle.zip?token=1"), "acme-bundle");
+  assert.equal(inferSlug("not a url"), "deliverable");
+});
+
+test("zipEntriesFromListing parses unzip -l output", () => {
+  const listing = [
+    "Archive:  x.zip",
+    "  Length      Date    Time    Name",
+    "---------  ---------- -----   ----",
+    "       12  2026-06-03 10:00   skill/SKILL.md",
+    "        0  2026-06-03 10:00   skill/",
+    "---------                     -------",
+    "       12                     2 files",
+  ].join("\n");
+  const entries = zipEntriesFromListing(listing);
+  assert.deepEqual(entries, ["skill/SKILL.md", "skill/"]);
+});
+
+test("assertNoZipSlip rejects traversal and absolute paths", () => {
+  const dest = join(tmpdir(), "dest");
+  assert.throws(() => assertNoZipSlip(["../escape.sh"], dest), /zip-slip|traversal/);
+  assert.throws(() => assertNoZipSlip(["/etc/passwd"], dest), /absolute/);
+  assert.doesNotThrow(() => assertNoZipSlip(["ok/file.txt", "nested/dir/x"], dest));
+});
+
+test("uniqueDir suffixes when the base exists", () => {
+  const root = mkdtempSync(join(tmpdir(), "agent-relay-fetch-uniq-"));
+  try {
+    const base = join(root, "thing");
+    const d1 = uniqueDir(base);
+    assert.equal(d1, base);
+    writeFileSync(base, "x"); // occupy it
+    const d2 = uniqueDir(base);
+    assert.equal(d2, `${base}-1`);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("cmdFetch verifies checksum and aborts on mismatch (writes nothing)", async () => {
+  const buf = Buffer.from("plain artifact contents");
+  await assert.rejects(
+    () => cmdFetch({ url: "https://x/a.txt", checksum: "deadbeef", fetchImpl: fakeFetch(buf), dest: join(tmpdir(), "nope-" + Date.now()) }),
+    /checksum mismatch/,
+  );
+});
+
+test("cmdFetch drops a non-zip file into ./<slug>/ as-is", async () => {
+  const cwd = process.cwd();
+  const root = mkdtempSync(join(tmpdir(), "agent-relay-fetch-file-"));
+  process.chdir(root);
+  try {
+    const buf = Buffer.from("hello deliverable");
+    const r = await cmdFetch({ url: "https://x/y/readme.txt", filename: "readme.txt", checksum: sha256Hex(buf), fetchImpl: fakeFetch(buf) });
+    assert.equal(r.kind, "file");
+    assert.equal(r.placed.length, 1);
+    assert.equal(readFileSync(r.placed[0], "utf-8"), "hello deliverable");
+  } finally {
+    process.chdir(cwd);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("cmdFetch extracts a real zip into ./<slug>/ (no execution)", async () => {
+  const cwd = process.cwd();
+  const root = mkdtempSync(join(tmpdir(), "agent-relay-fetch-zip-"));
+  process.chdir(root);
+  try {
+    // Build a tiny real zip with the system zip tool; skip if unavailable.
+    const srcDir = join(root, "src");
+    execFileSync("mkdir", ["-p", srcDir]);
+    writeFileSync(join(srcDir, "SKILL.md"), "# hi");
+    const zipPath = join(root, "bundle.zip");
+    try {
+      execFileSync("zip", ["-q", "-r", zipPath, "SKILL.md"], { cwd: srcDir });
+    } catch {
+      return; // no `zip` on PATH — skip this env
+    }
+    const buf = readFileSync(zipPath);
+    const r = await cmdFetch({ url: "https://x/cool-bundle.zip", filename: "cool-bundle.zip", checksum: sha256Hex(buf), fetchImpl: fakeFetch(buf) });
+    assert.equal(r.kind, "zip");
+    assert.ok(r.dest.endsWith("cool-bundle"));
+    assert.ok(r.placed.some((p) => p.endsWith("SKILL.md")));
+    assert.ok(existsSync(join(r.dest, "SKILL.md")));
+  } finally {
+    process.chdir(cwd);
+    rmSync(root, { recursive: true, force: true });
+  }
+});