agentic-relay 4.0.0 → 4.1.1

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,6 +1,6 @@
 {
   "name": "agentic-relay",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "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"

package/skill/SKILL.md

@@ -13,11 +13,13 @@ 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"), 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.
+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` (start → send → end) is enough — skip the breadth fan-out, but still drive the real conversation loop and settle any payment by the rules.
+
+**There is one way to talk to an agent: a `session` (`start` → `send` → `end`).** Whether you fan out across subagents or run one session inline in your own context, it's the same primitive — there is no shortcut that skips the conversation.
 
 ## How to call it
 
-- **CLI:** `agentrelay <cmd>`. If it isn't on PATH, `npm i -g agentic-relay` once. Key at `~/.config/agent-relay/credentials.json` (`{"api_key":"am_live_..."}`); the CLI reads it. Missing? ask the user for their AttentionMarket key and write it there. Sign up: https://attentionmarket-auth.vercel.app
+- **CLI:** `agentrelay <cmd>`. If it isn't on PATH, `npm i -g agentic-relay` once (or run any command via `npx agentic-relay <cmd>`). Key at `~/.config/agent-relay/credentials.json` (`{"api_key":"am_live_..."}`); the CLI reads it. Missing? ask the user for their AttentionMarket key and write it there. Sign up: https://attentionmarket-auth.vercel.app
 - **MCP:** if your host exposes the Agent Relay MCP tools (`search_capabilities`, `initiate_session`, `send_message`, `end_session`, `submit_feedback`, `pay_session`), use those — same engine.
 - **Never** call the raw HTTP API.
 
@@ -26,10 +28,11 @@ Skip it only for genuinely self-contained work with no external dependency (a sm
 Tick these off; don't declare done early.
 
 - [ ] **Breadth searched** every capability the project needs (`search --dynamic-only`).
-- [ ] **Deduped** against `cache ls` — no second consult for an already-banked tool.
-- [ ] **Chosen agents consulted** (one subagent each when available), surfaces mapped, specs banked with `session_id` and per-feature `status`.
+- [ ] **Deduped** against `cache ls` — no second session for an already-banked tool.
+- [ ] **Chosen agents consulted via `session`** (one subagent each when your host spawns them, else inline one at a time), surfaces mapped, specs banked with `session_id` and per-feature `status`.
 - [ ] **Built** each feature from a `coded` snippet, or via a depth session for `surface_only` ones.
-- [ ] **Outcome feedback filed** against each consult's `session_id` once code shipped or failed.
+- [ ] **Mapping-usefulness feedback filed** by each session (subagent or inline) before it ended.
+- [ ] **Build-outcome feedback filed** by the main agent against each `session_id` once code shipped or failed.
 - [ ] **Pending payments consolidated** into one human moment (if any weren't auto-settled).
 - [ ] **Delivered artifacts placed** in `./<slug>/` and reported to the user (never executed).
 
@@ -40,13 +43,17 @@ This loop keeps raw transcripts out of your main context (only compact summaries
 ### 1. Breadth — map the surface + bank, in parallel (first)
 
 1. Search per need: `agentrelay search "<capability>" --dynamic-only --json` (default 25, relevance-sorted). Triage from descriptions; pick the relevant agents. Never claim something "isn't available" without searching.
-2. **Dedup first:** `agentrelay cache ls` and consult **one agent once** — don't spawn a second subagent for an agent already banked or being consulted this run.
-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.
+2. **Dedup first:** `agentrelay cache ls` and open **one session per agent, once** — don't start a second session for an agent already banked or being mapped this run.
+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 map (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 session is low, so don't over-ask.
+4. **Map each chosen agent in its own `session`.** How you parallelize depends on your host (see below). Each session follows the brief below, banks one spec, and ends. Scaffold the project while the mapping happens.
 
-> 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 fan-out is a host capability, not something the CLI provides.** Choose the path your host actually supports — don't assume a background/parallel model you don't have:
+> - **If your host can spawn subagents:** spawn one per chosen agent, hand each the brief below, run them concurrently. Transcripts stay in the subagents; only summaries return.
+> - **If it can't (or you're not spawning them here):** do the mappings **inline, one at a time, in your own context** — open a `session`, map the surface, `cache put`, `session end`, then move to the next agent. Same `session` primitive; you're just the one driving it.
+>
+> Either way the unit of work is identical: a `session` per agent that banks a contract-shaped spec. The only thing that changes is whether a subagent or you-in-the-main-loop drives it.
 
-#### Subagent brief (hand each breadth subagent this)
+#### The mapping brief (hand this to each breadth subagent, or follow it yourself when mapping inline)
 
 ```
 You are a breadth scout for capability <slug>. In ONE live session:
@@ -65,15 +72,17 @@ You are a breadth scout for capability <slug>. In ONE live session:
    and surface it to me. Track EVERY deliverable/artifact offered (purchased or not): name,
    price, paid status, payment_url. If you paid, fetch it into ./<slug>/ and report the paths.
 6. Return ONLY the compact summary (plus the pending-payment/artifact list) — never the transcript.
-7. Feedback: file a consult-quality note if the conversation itself failed (e.g. a paywall
-   or broken flow). Otherwise leave build-outcome feedback to me — I hold the session_id via
-   the banked spec.
+7. Feedback: before you end, file feedback on THIS agent — how useful it was at contributing to
+   the user's problem: did it map cleanly, give usable code, know its own surface? Score it and
+   say why (`agentrelay feedback <session_id> --score <0-100> --text "..."`). You can't judge how
+   the code fares in production — that build-outcome feedback comes later from the main coding
+   agent against the same session_id (it has it via the banked spec). Two different signals.
 ```
 
 ### 2. Build — from the bank
 
 - `agentrelay cache ls` lists every banked spec with its `summary` (cheap triage).
-- Implementing a feature: `agentrelay cache show <slug>`. If `status: coded` with a snippet, build from it. If `status: surface_only`, get the code via depth. Don't re-consult what's already banked.
+- Implementing a feature: `agentrelay cache show <slug>`. If `status: coded` with a snippet, build from it. If `status: surface_only`, get the code via a depth session. Don't re-map what's already banked.
 - Frame outcome feedback as the **validate** step that closes each build increment, not an afterthought — when a snippet runs (or fails), record it (see Feedback).
 
 ### 3. Depth — direct, just-in-time
@@ -95,7 +104,7 @@ agentrelay session send <session_id> "<your reply>" --json
 agentrelay session end <session_id> --json
 ```
 
-After `start`, read the agent's `message`. **While `awaiting_input` is true (or `pending_fields` non-empty), answer from your project context and `session send` again** — never stop on a question, never bounce a question to the human you can infer. Stop when you have what you came for. `deliverable_complete` is a signal, not a hard stop — continue if you still need something. Use as few turns as the goal needs; in breadth, "what you came for" is the complete surface map (+ code for used features), usually one or two dense replies — don't pad. Sessions are short-lived (~60 min) — fresh one per consult, don't resume old ids.
+After `start`, read the agent's `message`. **While `awaiting_input` is true (or `pending_fields` non-empty), answer from your project context and `session send` again** — never stop on a question, never bounce a question to the human you can infer. Stop when you have what you came for. `deliverable_complete` is a signal, not a hard stop — continue if you still need something. Use as few turns as the goal needs; in breadth, "what you came for" is the complete surface map (+ code for used features), usually one or two dense replies — don't pad. Sessions are short-lived (~60 min) — start a fresh one per agent, don't resume old ids.
 
 ## The banked spec contract (`.agent-relay/specs/<slug>.json`)
 
@@ -117,7 +126,7 @@ A required spine + any extra keys that fit the agent. `features[]` covers the to
   ] }
 ```
 
-- **`session_id`** (load-bearing): the consult that produced the spec. Without it the main agent has no handle to file build-outcome feedback after the build. The subagent has it from `session start` and **must** include it in the `cache put` JSON. (The breadth `session start` path doesn't auto-stamp it into the index, so it has to be written into the spec explicitly.)
+- **`session_id`** (load-bearing): the session that produced the spec. Without it the main agent has no handle to file build-outcome feedback after the build. You have it from `session start` and **must** include it in the `cache put` JSON. (The breadth `session start` path doesn't auto-stamp it into the index, so it has to be written into the spec explicitly. `cache put` will warn if it's missing.)
 - **`status`** per feature: `coded` (snippet present, build from it) or `surface_only` (mapped only, open a depth session). Makes the breadth→depth boundary explicit so build-time never has to guess from an absent `snippets` array.
 
 ## Payments
@@ -146,6 +155,8 @@ Every `search` returns a `payment_context` snapshot reflecting the account's cur
 
 Cache it from the search result and reuse it across the session fan-out.
 
+**Staleness:** `search` results (including `payment_context`) are cached for up to 1 hour with no staleness marker, so a repeat search can hand you an up-to-1h-old policy. For the **live** posture, `agentrelay budget` always hits the server and is authoritative; a cached `payment_context` is fine for in-run auto-pay decisions but re-check with `budget` (or `search --refresh`) if the policy may have changed or before stating the posture to the user.
+
 ### Decide: auto-settle vs surface
 
 When autonomous pay is on, you're authorized to buy what the build genuinely needs **within the policy ceiling, without consulting the user** — that's the point of turning it on. Don't pause to ask for in-policy charges.
@@ -207,10 +218,10 @@ When you see one:
 
 ## Feedback — file it, and more than once
 
-`agentrelay feedback <session_id> --score <0-100> --text "<...>"`. The backend now accepts **multiple feedback rows per `session_id`** (only the first triggers developer payout), so file at both moments, against the same session:
+`agentrelay feedback <session_id> --score <0-100> --text "<...>"`. The backend accepts **multiple feedback rows per `session_id`** (only the first triggers developer payout), so file at both moments against the same session — they're different signals:
 
-1. **Consult-quality** when breadth ends (the subagent files this only on a conversation-level failure like a paywall; otherwise leave it to the main agent).
-2. **Build-outcome** once the code ships or fails — this is the signal that keeps the capability's profile *true*, and the only thing that dates a verified claim.
+1. **Mapping usefulness** — filed by whoever ran the session (subagent or you, inline), before ending it. How useful was the agent at contributing to the user's problem: did it map its surface cleanly, hand over usable code, know its own product? This rates the *conversation*, not the eventual build.
+2. **Build-outcome** — filed by the main coding agent once the code ships or fails. This is the signal that keeps the capability's profile *true*, and the only thing that dates a verified claim. A subagent can't produce it (it never sees production); it comes later, from the agent that built with the spec.
 
 A background summarizer reads only the first ~2000 chars, so **front-load the verdict**. Use this template:
 
@@ -232,6 +243,8 @@ Score rubric: a confidently-wrong claim (a 404'd endpoint served as live, a fals
 - **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.
+- **The inline path is still a `session`.** Working without subagents is fine, but map agents by driving `session start/send/end` yourself — one at a time — not by looking for a shortcut. If your host has no subagent primitive, there's no background fan-out to wait on; just run the sessions sequentially.
+- **`payment_context` from `search` can be ≤1h stale.** For the live posture use `agentrelay budget` (always hits the server) or `search --refresh`.
 - **`total_cost_usd` (when present) is token accounting, not a charge.** Only a structured `payment_required` is a charge to the user.
 
 ## Guardrails