agentic-relay 3.8.5 → 4.1.0

package/bin/test/install-args.test.mjs

@@ -0,0 +1,68 @@
+/**
+ * Tests for installer argument parsing (bin/lib/install-args.mjs) — focused on
+ * the `--api-key= <key>` space-typo rescue observed in the field.
+ * Run: `node --test bin/test/install-args.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseInstallArgs } from "../lib/install-args.mjs";
+
+const KEY = "am_live_abc123def456";
+
+test("--api-key=KEY parses", () => {
+  const { flags, warnings } = parseInstallArgs([`--api-key=${KEY}`, "--all"]);
+  assert.equal(flags.apiKey, KEY);
+  assert.equal(flags.all, true);
+  assert.deepEqual(warnings, []);
+});
+
+test("--api-key KEY (space-separated) parses", () => {
+  const { flags, warnings } = parseInstallArgs(["--api-key", KEY]);
+  assert.equal(flags.apiKey, KEY);
+  assert.deepEqual(warnings, []);
+});
+
+test("--api-key= KEY (the space typo) rescues the bare key with a warning", () => {
+  const { flags, warnings } = parseInstallArgs(["--all", "--api-key=", KEY]);
+  assert.equal(flags.apiKey, KEY);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /no space/);
+});
+
+test("bare am_live_* positional alone is rescued with a warning", () => {
+  const { flags, warnings } = parseInstallArgs([KEY, "--all"]);
+  assert.equal(flags.apiKey, KEY);
+  assert.equal(warnings.length, 1);
+});
+
+test("empty --api-key= with no rescue positional warns and stays null", () => {
+  const { flags, warnings } = parseInstallArgs(["--api-key="]);
+  assert.equal(flags.apiKey, "");
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /no value/);
+});
+
+test("non-key positionals are not adopted", () => {
+  const { flags, warnings } = parseInstallArgs(["hello", "--all"]);
+  assert.equal(flags.apiKey, null);
+  assert.deepEqual(warnings, []);
+});
+
+test("space-form value is not double-counted as a rescue positional", () => {
+  const { flags, warnings } = parseInstallArgs(["--api-key", KEY]);
+  assert.equal(flags.apiKey, KEY);
+  assert.deepEqual(warnings, []);
+});
+
+test("targets / librechat / legacy flags are unchanged", () => {
+  const { flags } = parseInstallArgs([
+    "--target=claude, codex",
+    "--librechat=/tmp/librechat.yaml",
+    "--claude",
+    "--project",
+  ]);
+  assert.deepEqual(flags.targets, ["claude", "codex"]);
+  assert.equal(flags.librechat, "/tmp/librechat.yaml");
+  assert.equal(flags.legacyClaude, true);
+  assert.equal(flags.project, true);
+});

package/bin/test/parse.test.mjs

@@ -4,7 +4,7 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { lenientParse, extractJsonObject, extractFields } from "../lib/parse.mjs";
+import { lenientParse } from "../lib/parse.mjs";
 
 test("lenientParse: clean JSON parses strictly", () => {
   const r = lenientParse('{"a":1,"b":"hi"}');
@@ -42,29 +42,3 @@ test("lenientParse: truly broken input fails gracefully (no throw)", () => {
   assert.equal(r.ok, false);
   assert.ok(r.error);
 });
-
-test("extractJsonObject: pulls a fenced ```json block out of prose", () => {
-  const msg =
-    "Sure! Here is your deliverable:\n```json\n{\"verdict\":\"use it\",\"install\":[\"npm i x\"]}\n```\nLet me know!";
-  const obj = extractJsonObject(msg);
-  assert.equal(obj.verdict, "use it");
-  assert.deepEqual(obj.install, ["npm i x"]);
-});
-
-test("extractJsonObject: pulls a bare embedded object", () => {
-  const msg = 'prefix {"a":1,"nested":{"b":2}} suffix';
-  const obj = extractJsonObject(msg);
-  assert.deepEqual(obj, { a: 1, nested: { b: 2 } });
-});
-
-test("extractJsonObject: returns null when there's no object", () => {
-  assert.equal(extractJsonObject("just a question?"), null);
-});
-
-test("extractFields: last-resort flat string extraction", () => {
-  const raw = '{"session_id":"abc-123","status":"active","message":"hi \\"there\\""}';
-  const got = extractFields(raw, ["session_id", "status", "message"]);
-  assert.equal(got.session_id, "abc-123");
-  assert.equal(got.status, "active");
-  assert.equal(got.message, 'hi "there"');
-});

package/bin/test/session.test.mjs

@@ -65,8 +65,12 @@ test("deliveryToFetchArgs: maps a delivery object to cmdFetch args (tolerant of
       filename: "x.zip",
       slug: "gstack",
     }),
-    { url: "https://store/x.zip", checksum: "abc123", filename: "x.zip", dest: null },
+    // dest defaults to ./<delivery.slug>/ (the documented contract); an
+    // explicit dest always wins.
+    { url: "https://store/x.zip", checksum: "abc123", filename: "x.zip", dest: "./gstack" },
   );
+  // a hostile slug is slugified — it can't traverse out of the working dir
+  assert.equal(deliveryToFetchArgs({ download_url: "https://s/x", slug: "../../etc" }).dest, "./etc");
   // variant keys + dest override
   assert.deepEqual(
     deliveryToFetchArgs({ url: "https://store/y", checksum: "def" }, { dest: "./out" }),

package/bin/test/update-check.test.mjs

@@ -0,0 +1,56 @@
+/**
+ * Tests for the async update notifier (bin/lib/update-check.mjs) — the pure
+ * pieces: semver compare, state round-trip, suppression predicate.
+ * Run: `node --test bin/test/update-check.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+import { compareSemver, shouldSuppress, readState, writeState } from "../lib/update-check.mjs";
+
+test("compareSemver orders numerically, not lexically", () => {
+  assert.equal(compareSemver("1.2.3", "1.2.3"), 0);
+  assert.equal(compareSemver("1.10.0", "1.2.0"), 1); // lexical would say 1.10 < 1.2
+  assert.equal(compareSemver("4.0.0", "3.9.9"), 1);
+  assert.equal(compareSemver("3.8.5", "4.0.0"), -1);
+  assert.equal(compareSemver("1.2", "1.2.0"), 0);
+});
+
+test("state round-trips through a custom path", () => {
+  const root = mkdtempSync(join(tmpdir(), "agent-relay-update-"));
+  try {
+    const p = join(root, "nested", "update-check.json");
+    const state = { last_check_ts: "2026-06-11T00:00:00.000Z", latest_version: "9.9.9" };
+    assert.equal(writeState(state, p), true);
+    assert.deepEqual(readState(p), state);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("readState returns null for missing/corrupt files", () => {
+  assert.equal(readState("/nonexistent/path/update.json"), null);
+});
+
+const TTY_BASE = { env: {}, stderrIsTTY: true, binPath: "/usr/local/bin/agentrelay" };
+
+test("suppression: env kill-switches", () => {
+  assert.equal(shouldSuppress({ ...TTY_BASE, env: { AGENT_RELAY_NO_UPDATE_CHECK: "1" } }), true);
+  assert.equal(shouldSuppress({ ...TTY_BASE, env: { NO_UPDATE_NOTIFIER: "1" } }), true);
+  assert.equal(shouldSuppress({ ...TTY_BASE, env: { CI: "true" } }), true);
+});
+
+test("suppression: non-TTY stderr (piped/scripted runs)", () => {
+  assert.equal(shouldSuppress({ ...TTY_BASE, stderrIsTTY: false }), true);
+});
+
+test("suppression: running from an npx cache", () => {
+  const npxPath = ["", "Users", "x", ".npm", "_npx", "abc123", "node_modules", ".bin", "agentrelay"].join(sep);
+  assert.equal(shouldSuppress({ ...TTY_BASE, binPath: npxPath }), true);
+});
+
+test("not suppressed: interactive TTY run from a real install", () => {
+  assert.equal(shouldSuppress(TTY_BASE), false);
+});

package/bin/test/zip.test.mjs

@@ -0,0 +1,212 @@
+/**
+ * Tests for the pure-JS zip extractor (bin/lib/zip.mjs). Fixture zips are
+ * hand-assembled in memory (local headers + central directory + EOCD) so we
+ * can exercise shapes the system `zip` tool won't produce — data descriptors,
+ * zip64 markers, encrypted flags. Run: `node --test bin/test/zip.test.mjs`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync, lstatSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deflateRawSync } from "node:zlib";
+import {
+  findEndOfCentralDirectory,
+  listZipEntries,
+  readEntryData,
+  extractZip,
+} from "../lib/zip.mjs";
+
+/**
+ * Assemble a zip from entries: [{name, data, method?, dataDescriptor?, flags?}].
+ * method: 0 store (default), 8 deflate. dataDescriptor: local sizes zeroed,
+ * flag bit 3 set, 16-byte descriptor appended after the data (the shape
+ * streaming writers produce — central directory holds the truth).
+ */
+function buildZip(entries, { zip64Eocd = false } = {}) {
+  const parts = [];
+  const central = [];
+  let offset = 0;
+
+  for (const e of entries) {
+    const name = Buffer.from(e.name, "utf-8");
+    const raw = Buffer.from(e.data ?? "", "utf-8");
+    const method = e.method ?? 0;
+    const payload = method === 8 ? deflateRawSync(raw) : raw;
+    const useDD = Boolean(e.dataDescriptor);
+    const flags = (e.flags ?? 0) | (useDD ? 0x8 : 0);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(flags, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(0, 10); // time
+    local.writeUInt16LE(0, 12); // date
+    local.writeUInt32LE(0, 14); // crc (not verified by extractor)
+    local.writeUInt32LE(useDD ? 0 : payload.length, 18);
+    local.writeUInt32LE(useDD ? 0 : raw.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28); // extra len
+
+    const localOffset = offset;
+    parts.push(local, name, payload);
+    offset += local.length + name.length + payload.length;
+
+    if (useDD) {
+      const dd = Buffer.alloc(16);
+      dd.writeUInt32LE(0x08074b50, 0); // optional descriptor signature
+      dd.writeUInt32LE(0, 4); // crc
+      dd.writeUInt32LE(payload.length, 8);
+      dd.writeUInt32LE(raw.length, 12);
+      parts.push(dd);
+      offset += dd.length;
+    }
+
+    const cen = Buffer.alloc(46);
+    cen.writeUInt32LE(0x02014b50, 0);
+    cen.writeUInt16LE(20, 4); // version made by
+    cen.writeUInt16LE(20, 6); // version needed
+    cen.writeUInt16LE(flags, 8);
+    cen.writeUInt16LE(method, 10);
+    cen.writeUInt16LE(0, 12); // time
+    cen.writeUInt16LE(0, 14); // date
+    cen.writeUInt32LE(0, 16); // crc
+    cen.writeUInt32LE(payload.length, 20); // TRUE sizes live here
+    cen.writeUInt32LE(raw.length, 24);
+    cen.writeUInt16LE(name.length, 28);
+    cen.writeUInt16LE(0, 30); // extra
+    cen.writeUInt16LE(0, 32); // comment
+    cen.writeUInt16LE(0, 34); // disk start
+    cen.writeUInt16LE(0, 36); // internal attrs
+    cen.writeUInt32LE(e.externalAttrs ?? 0, 38);
+    cen.writeUInt32LE(localOffset, 42);
+    central.push(Buffer.concat([cen, name]));
+  }
+
+  const cd = Buffer.concat(central);
+  const cdOffset = offset;
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4); // disk
+  eocd.writeUInt16LE(0, 6); // cd disk
+  eocd.writeUInt16LE(zip64Eocd ? 0xffff : entries.length, 8);
+  eocd.writeUInt16LE(zip64Eocd ? 0xffff : entries.length, 10);
+  eocd.writeUInt32LE(cd.length, 12);
+  eocd.writeUInt32LE(zip64Eocd ? 0xffffffff : cdOffset, 16);
+  eocd.writeUInt16LE(0, 20); // comment len
+  return Buffer.concat([...parts, cd, eocd]);
+}
+
+function tmpDest(prefix) {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+test("stored entry round-trips", () => {
+  const buf = buildZip([{ name: "a.txt", data: "hello stored" }]);
+  const root = tmpDest("zip-stored-");
+  try {
+    const placed = extractZip(buf, join(root, "out"));
+    assert.equal(placed.length, 1);
+    assert.equal(readFileSync(placed[0], "utf-8"), "hello stored");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("deflated entry round-trips", () => {
+  const text = "deflate me ".repeat(100);
+  const buf = buildZip([{ name: "b.txt", data: text, method: 8 }]);
+  const root = tmpDest("zip-deflate-");
+  try {
+    const placed = extractZip(buf, join(root, "out"));
+    assert.equal(readFileSync(placed[0], "utf-8"), text);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("data-descriptor zip (local sizes zeroed) extracts via central directory", () => {
+  const text = "streamed entry with data descriptor";
+  const buf = buildZip([{ name: "dd.txt", data: text, method: 8, dataDescriptor: true }]);
+  // Sanity: the local header really does carry zero sizes.
+  assert.equal(buf.readUInt32LE(18), 0);
+  const entries = listZipEntries(buf);
+  assert.equal(entries[0].compressedSize > 0, true);
+  const root = tmpDest("zip-dd-");
+  try {
+    const placed = extractZip(buf, join(root, "out"));
+    assert.equal(readFileSync(placed[0], "utf-8"), text);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("nested directories are created; dir entries write no files", () => {
+  const buf = buildZip([
+    { name: "pkg/", data: "" },
+    { name: "pkg/deep/file.md", data: "# nested" },
+  ]);
+  const root = tmpDest("zip-nest-");
+  try {
+    const out = join(root, "out");
+    const placed = extractZip(buf, out);
+    assert.equal(placed.length, 1);
+    assert.ok(existsSync(join(out, "pkg", "deep", "file.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("zip-slip entry is rejected before any write", () => {
+  const buf = buildZip([
+    { name: "ok.txt", data: "fine" },
+    { name: "../evil.sh", data: "rm -rf" },
+  ]);
+  const root = tmpDest("zip-slip-");
+  try {
+    const out = join(root, "out");
+    assert.throws(() => extractZip(buf, out), /zip-slip|traversal/);
+    assert.equal(existsSync(join(out, "ok.txt")), false); // nothing written
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("zip64 EOCD markers are rejected with a clear error", () => {
+  const buf = buildZip([{ name: "x.txt", data: "x" }], { zip64Eocd: true });
+  assert.throws(() => findEndOfCentralDirectory(buf), /zip64/);
+});
+
+test("encrypted entries are rejected with a clear error", () => {
+  const buf = buildZip([{ name: "secret.txt", data: "x", flags: 0x1 }]);
+  assert.throws(() => listZipEntries(buf), /encrypted/);
+});
+
+test("unsupported compression method is rejected", () => {
+  const buf = buildZip([{ name: "lzma.bin", data: "x", method: 14 }]);
+  const entries = listZipEntries(buf);
+  assert.throws(() => readEntryData(buf, entries[0]), /unsupported zip compression method 14/);
+});
+
+test("symlink-flagged entry is materialized as a regular file", () => {
+  const S_IFLNK = 0o120000;
+  const buf = buildZip([
+    { name: "link", data: "/etc/passwd", externalAttrs: ((S_IFLNK | 0o777) << 16) >>> 0 },
+  ]);
+  const root = tmpDest("zip-symlink-");
+  try {
+    const out = join(root, "out");
+    extractZip(buf, out);
+    const st = lstatSync(join(out, "link"));
+    assert.equal(st.isSymbolicLink(), false);
+    assert.equal(st.isFile(), true);
+    assert.equal(readFileSync(join(out, "link"), "utf-8"), "/etc/passwd");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("garbage buffer fails with a clear error", () => {
+  assert.throws(() => listZipEntries(Buffer.from("definitely not a zip file")), /end-of-central-directory/);
+});

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "agentic-relay",
-  "version": "3.8.5",
-  "description": "Install Agent Relay AI search across 17+ agents — Claude Code, Codex, Cursor, Gemini CLI, Goose, Windsurf, Cline, BoltAI, Claude Desktop, VS Code, Amazon Q, Roo Code, Witsy, LibreChat, OpenClaw, Tome, Raycast — plus the `agentrelay` CLI for token-cheap parallel agent consulting",
+  "version": "4.1.0",
+  "description": "Install Agent Relay AI search across 17+ agents — Claude Code, Codex, Cursor, Gemini CLI, Goose, Windsurf, Cline, BoltAI, Claude Desktop, VS Code, Amazon Q, Roo Code, Witsy, LibreChat, OpenClaw, Tome, Raycast — plus the `agentrelay` CLI for live agent sessions, payments, and deliverable fetch",
   "bin": {
     "agentrelay": "bin/cli.mjs"
   },
   "scripts": {
-    "test": "node --test \"bin/test/parse.test.mjs\" \"bin/test/driver.test.mjs\" \"bin/test/session.test.mjs\" \"bin/test/cache.test.mjs\" \"bin/test/budget.test.mjs\" \"bin/test/fetch.test.mjs\""
+    "test": "node --test bin/test/*.test.mjs"
   },
   "keywords": [
     "agent-relay",

package/skill/SKILL.md

@@ -13,7 +13,7 @@ Agent Relay is a marketplace of **capability agents**: each is a live solutions
 - Whenever you're **about to choose** a library/API/service, or **stuck integrating** one.
 - **Before** web-searching or answering from your own knowledge about a tool — these agents are current and hand you working code, not approximate recollection.
 
-Skip it only for genuinely self-contained work with no external dependency (a small algorithm or one-off script), or a question answerable without integration. For a trivial lookup ("find me X", "how do I install X"), one inline consult is enough — skip the breadth→subagent→cache ceremony, but still settle any payment by the rules.
+Skip it only for genuinely self-contained work with no external dependency (a small algorithm or one-off script), or a question answerable without integration. For a trivial lookup ("find me X", "how do I install X"), a single inline session (`session start` → a send or two → `session end`) is enough — skip the breadth→subagent→cache ceremony, but still settle any payment by the rules.
 
 ## How to call it
 
@@ -44,7 +44,7 @@ This loop keeps raw transcripts out of your main context (only compact summaries
 3. **After search, use judgment on whether to pause.** When the choice of agents is consequential or ambiguous — several plausible tools, paid capabilities in the mix, an architecture fork — surface the shortlist to the user and suggest which to consult (bias toward broad coverage to maximize breadth), then proceed on their pick. When the picks are obvious, just start breadth autonomously. There's no mandatory gate; the cost of a wrong-but-cheap consult is low, so don't over-ask.
 4. **Spawn one subagent per chosen agent** (Claude Code, Codex, OpenClaw, Cursor all support subagents). Run them concurrently and scaffold the project while they work. Each subagent follows the brief below.
 
-> No subagents on your host? Run consults inline one at a time, or use the `agentrelay consult <slug> --want "<…>"` fallback (generic, code-driven). Note: the fallback currently returns a different spec shape than the contract below — prefer real subagent sessions, and if you must use it, don't bank its output as a contract-shaped spec.
+> No subagents on your host? Drive the sessions inline yourself, one at a time, using the same brief, and bank each spec with `agentrelay cache put <slug>` the same way.
 
 #### Subagent brief (hand each breadth subagent this)
 
@@ -229,6 +229,7 @@ Score rubric: a confidently-wrong claim (a 404'd endpoint served as live, a fals
 ## Known gotchas (seeded from real runs)
 
 - **Don't truncate `--json` search output.** Piping `agentrelay search … --json | head -N` cuts off `payment_context`, which sits after the (long) capabilities array — so the agent never sees the live pay policy and falls back to a wrong default. Read the whole JSON.
+- **A cached search's `payment_context` is a snapshot, not live.** When the search result has `from_cache: true`, its `payment_context` dates from `cached_at` (search cache TTL is 1h). For an actual pay decision, read `agentrelay budget` or re-run the search with `--refresh`.
 - **Never assert pay posture from memory.** Run `agentrelay budget` or read `payment_context` before any statement about whether autonomous pay is on. (A test agent claimed "off by default" while the live setting was on with a $5 auto-approve.)
 - **`deliverable_complete` is not a stop command.** Continue the session if you still need something it didn't include.
 - **Don't reconstruct the workflow from CLAUDE.md.** It's a thin map; this skill is the manual. If you're doing Agent Relay work, you should have loaded this file.

package/bin/lib/deliverable.mjs

@@ -1,70 +0,0 @@
-/**
- * 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,
-  );
-}

package/bin/lib/driver.mjs

@@ -1,165 +0,0 @@
-/**
- * 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 };
-}