agentic-relay 3.8.5 → 4.0.0

package/CLAUDE.md

@@ -6,7 +6,7 @@ Expert "solutions-engineer" agents for real third-party tools (APIs, SDKs, libra
 
 On any non-trivial build that touches a third-party tool, **load the `agent-relay` skill before doing Agent Relay work.** This file is a map, not the manual — the skill holds the real procedure. Load it because the workflow has paid actions and a feedback loop you will get wrong from memory: when a charge fires, how to react, who fetches a paid deliverable, and what feedback to file when code survives (or fails) contact with production. Don't reconstruct that from this file.
 
-Lightweight exception: a one-off lookup ("find me X", "how do I install X") doesn't need the full breadth→build→depth ceremony. A single inline consult is fine — but still settle payments by the rules below.
+Lightweight exception: a one-off lookup ("find me X", "how do I install X") doesn't need the full breadth→build→depth ceremony. A single inline session (`session start` → a send or two → `session end`) is fine — but still settle payments by the rules below.
 
 ## Commands
 

package/README.md

@@ -134,7 +134,7 @@ gotchas}], capability_id, ad_unit_id }` (+ any extra keys) — see `schema/deliv
 | `agentrelay session end <id>` | Close + summary. |
 | `agentrelay feedback <id>` | `--score <0-100> --text "<s>"`. |
 | `agentrelay cache ls\|show <slug>\|put <slug>\|clear` | Persist/review distillations (`.agent-relay/`). |
-| `agentrelay consult <slug>` / `consult-batch` | **Fallback** code-driven template loop (fixed shape, generic). `--want`, `--context`. |
+| `agentrelay session pay <id>` / `fetch` / `budget` | Settle an in-policy charge, fetch a paid deliverable, read/set the spend policy. |
 
 Output is a `{ ok, ...payload, errors: [] }` envelope (`--json` auto-on when piped). Key resolution:
 `--api-key` → `$AGENT_RELAY_API_KEY` → `~/.config/agent-relay/credentials.json` (with a read-only fallback to the

package/bin/cli.mjs

@@ -15,8 +15,6 @@
 
 const CLI_COMMANDS = new Set([
   "search",
-  "consult",
-  "consult-batch",
   "session",
   "feedback",
   "cache",
@@ -25,6 +23,10 @@ const CLI_COMMANDS = new Set([
   "fetch",
   "version",
   "help",
+  // Removed commands — still routed to the CLI core so they fail with a clear
+  // error (exit 2) instead of falling through to the interactive installer.
+  "consult",
+  "consult-batch",
 ]);
 
 const sub = process.argv[2];

package/bin/lib/commands.mjs

@@ -2,12 +2,10 @@
  * 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.
+ * `session start|send|pay|end` are 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. Compact specs get banked in the on-disk cache
+ * (`cache put`/`ls`/`show`) so transcripts stay out of the main context.
  */
 
 import { readFileSync } from "fs";
@@ -23,7 +21,6 @@ import {
 } from "./api.mjs";
 import { slugify } from "./config.mjs";
 import { Cache } from "./cache.mjs";
-import { consultOne } from "./driver.mjs";
 import { cmdFetch } from "./fetch.mjs";
 
 /** Normalize one upstream capability into the spec §4 menu shape. */
@@ -74,7 +71,7 @@ export async function cmdSearch(query, opts) {
     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.
+    // Seed the index so session start can resolve ids without re-searching.
     for (const c of capabilities) {
       if (c.capability_id && c.ad_unit_id) {
         cache.updateIndex(c.slug, {
@@ -153,116 +150,6 @@ export async function resolveCapability(slugOrId, opts) {
   };
 }
 
-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;
@@ -421,13 +308,13 @@ export async function cmdFetchSession(sessionId, opts) {
 }
 
 export async function cmdFeedback(sessionId, opts) {
-  if (!sessionId || opts.score == null) {
+  if (!sessionId || opts.score == null || !opts.text || !String(opts.text).trim()) {
     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) },
+    { sessionId, feedbackText: String(opts.text), score: Number(opts.score) },
     { apiKey: opts.apiKey, timeoutMs: opts.timeoutMs },
   );
 }

package/bin/lib/parse.mjs

@@ -10,7 +10,6 @@
  *   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. */
@@ -82,67 +81,3 @@ export function lenientParse(text) {
   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/relay-core.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 
 /**
- * agentrelay (CLI core) — token-cheap, parallel agent consulting for coding workflows.
+ * agentrelay (CLI core) — live agent sessions, payments, and deliverable fetch.
  *
- * 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.
+ * Wraps the AttentionMarket REST API so a coding agent can converse with expert
+ * "solutions-engineer" capability agents. The caller (a host subagent, or the
+ * main agent directly) drives the conversation via the session primitives and
+ * banks compact specs in the on-disk cache; raw transcripts stay out of the
+ * main context.
  *
  * 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
+ *   agentrelay search <query>          broad discovery (cheap; safe in main context)
+ *   agentrelay session start|send|pay|end   drive a live consult
+ *   agentrelay cache ls|show|put|clear inspect/manage the on-disk spec cache
+ *   agentrelay fetch                   download + verify + unpack a paid deliverable
  *
  * Output: a `{ ok, ...payload, errors: [] }` envelope. --json forces machine
  * output (auto-on when stdout is not a TTY). Exit codes: 0 ok, 1 partial,
@@ -26,8 +27,6 @@ import { readFileSync } from "fs";
 import { resolveApiKey } from "./lib/config.mjs";
 import {
   cmdSearch,
-  cmdConsult,
-  cmdConsultBatch,
   cmdSession,
   cmdFeedback,
   cmdCache,
@@ -44,14 +43,8 @@ const FLAGS_WITH_VALUE = new Set([
   "--context",
   "--cache-dir",
   "--timeout",
-  "--max-turns",
-  "--concurrency",
   "--max",
   "--user-context",
-  "--want",
-  "--want-file",
-  "--agents",
-  "--driver",
   "--initial",
   "--message",
   "--data",
@@ -108,8 +101,6 @@ function buildShared(flags) {
     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),
@@ -163,19 +154,6 @@ const fmtBudget = (e) => {
   ].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):
@@ -202,12 +180,8 @@ Deliverables (after a paid session returns a delivery object):
   agentrelay fetch <download_url> [dest]  [--checksum <sha256>] [--filename <name>]
                                      raw-URL download + unpack (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
+        --timeout <sec> --quiet --verbose
 
 Key: --api-key | $AGENT_RELAY_API_KEY | ~/.config/agent-relay/credentials.json`;
 
@@ -221,6 +195,14 @@ async function main() {
     process.stdout.write(HELP + "\n");
     process.exit(cmd ? EXIT.OK : EXIT.USAGE);
   }
+  if (cmd === "consult" || cmd === "consult-batch") {
+    return fail(
+      `"${cmd}" was removed in v4 — drive a live session instead: ` +
+        "`agentrelay session start <slug>` → `session send` → `session end` (see SKILL.md)",
+      EXIT.USAGE,
+      Boolean(flags.json) || !process.stdout.isTTY,
+    );
+  }
   if (cmd === "version" || flags.version) {
     let v = "unknown";
     try {
@@ -263,45 +245,6 @@ async function main() {
         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,
@@ -390,7 +333,7 @@ async function main() {
 
       default:
         return fail(
-          `unknown command "${cmd}" (session|search|consult|consult-batch|feedback|cache|budget|connect-wallet|fetch)`,
+          `unknown command "${cmd}" (session|search|feedback|cache|budget|connect-wallet|fetch)`,
           EXIT.USAGE,
           json,
         );

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/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.0.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)
 

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 };
-}

package/bin/lib/pool.mjs

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

package/bin/test/driver.test.mjs

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