@robzilla1738/agentswarm 0.5.0 → 0.7.0

package/dist/sandbox.js

@@ -302,7 +302,17 @@ class RemoteRuntime {
             throw new Error(`${what} failed (exit ${r.code}): ${r.out.slice(0, 300)}`);
         return r.out;
     }
+    /** base64-over-shell transfers buffer the whole file — refuse the huge ones. */
+    async checkSize(abs, capBytes, what) {
+        const out = await this.execOk(`wc -c < ${shq(abs)}`, `stat ${abs}`);
+        const size = Number(out.trim());
+        if (Number.isFinite(size) && size > capBytes) {
+            throw new Error(`${what}: file is ${Math.round(size / 1e6)}MB (cap ${Math.round(capBytes / 1e6)}MB) — ` +
+                `compress it or extract the relevant part in the sandbox first`);
+        }
+    }
     async readFile(abs) {
+        await this.checkSize(abs, 4_000_000, `read ${abs}`);
         const out = await this.execOk(`base64 < ${shq(abs)}`, `read ${abs}`);
         return Buffer.from(out.replace(/\s+/g, ""), "base64").toString("utf8");
     }
@@ -319,6 +329,7 @@ class RemoteRuntime {
         }
     }
     async pull(remoteAbs, localAbs) {
+        await this.checkSize(remoteAbs, 32_000_000, `pull ${remoteAbs}`);
         const out = await this.execOk(`base64 < ${shq(remoteAbs)}`, `pull ${remoteAbs}`);
         (0, util_1.ensureDir)(path.dirname(localAbs));
         fs.writeFileSync(localAbs, Buffer.from(out.replace(/\s+/g, ""), "base64"));

package/dist/searchcore.js

@@ -9,8 +9,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.queryTerms = queryTerms;
 exports.expandQueries = expandQueries;
+exports.reformulate = reformulate;
+exports.looksAcademic = looksAcademic;
 exports.canonicalizeUrl = canonicalizeUrl;
 exports.classifySource = classifySource;
+exports.freshnessBoost = freshnessBoost;
 exports.detectDate = detectDate;
 exports.selectPassages = selectPassages;
 exports.scorePage = scorePage;
@@ -42,6 +45,22 @@ function expandQueries(query, max = 3) {
     const seen = new Set();
     return out.map((q) => q.trim()).filter((q) => q && !seen.has(q.toLowerCase()) && seen.add(q.toLowerCase())).slice(0, max);
 }
+/**
+ * Fallback phrasing when a query returns nothing: strip quotes and search
+ * operators down to the top keyword terms. Returns "" when no useful
+ * simplification exists.
+ */
+function reformulate(query) {
+    const cleaned = query
+        .replace(/["'""'']/g, " ")
+        .replace(/\b(site|intitle|inurl|filetype):\S+/gi, " ");
+    const alt = queryTerms(cleaned).slice(0, 6).join(" ");
+    return alt && alt !== query.toLowerCase().trim() ? alt : "";
+}
+/** Queries that smell academic trigger the scholarly engines in deep mode. */
+function looksAcademic(query) {
+    return /\b(paper|papers|study|studies|research|arxiv|doi|journal|peer.?review(ed)?|preprint|dataset|benchmark|survey|meta.?analysis|citations?|et al)\b/i.test(query);
+}
 const TRACKING_KEYS = new Set(["fbclid", "gclid", "mc_cid", "mc_eid"]);
 /** Stable canonical form for dedup: strip tracking params, www, trailing slash; sort the query. */
 function canonicalizeUrl(url) {
@@ -61,18 +80,50 @@ function canonicalizeUrl(url) {
         path = path.replace(/\/+$/, "");
     return `${u.protocol.toLowerCase()}//${host}${path}${query}`;
 }
+const ACADEMIC_HOSTS = [
+    "arxiv.org",
+    "doi.org",
+    "semanticscholar.org",
+    "ncbi.nlm.nih.gov",
+    "nature.com",
+    "sciencedirect.com",
+    "springer.com",
+    "link.springer.com",
+    "scholar.google.com",
+    "acm.org",
+    "ieee.org",
+];
 function classifySource(domain) {
     const d = domain.toLowerCase();
     if (d.endsWith(".gov") || d.endsWith(".mil"))
         return "government";
     if (d.endsWith(".edu"))
         return "academic";
+    if (ACADEMIC_HOSTS.some((h) => d === h || d.endsWith("." + h)))
+        return "academic";
     if (["twitter.com", "x.com", "reddit.com", "facebook.com"].some((s) => d.includes(s)))
         return "social";
     if (d.includes("news") || d.includes("reuters.com") || d.includes("apnews.com") || d.includes("bbc."))
         return "news";
     return "secondary";
 }
+/** Recency boost from an ISO date or bare year: +3 <1y, +2 <2y, +1 <5y, 0 older/undated. */
+function freshnessBoost(date, now = Date.now()) {
+    if (!date)
+        return 0;
+    const m = /^(\d{4})(?:-(\d{1,2})(?:-(\d{1,2}))?)?/.exec(date.trim());
+    if (!m)
+        return 0;
+    const t = Date.UTC(Number(m[1]), m[2] ? Number(m[2]) - 1 : 6, m[3] ? Number(m[3]) : 15);
+    const years = (now - t) / 31_557_600_000;
+    if (years < 1)
+        return 3;
+    if (years < 2)
+        return 2;
+    if (years < 5)
+        return 1;
+    return 0;
+}
 /** ISO date if present, else a bare year. */
 function detectDate(text) {
     const iso = /\b(20\d{2}-\d{2}-\d{2})\b/.exec(text);
@@ -136,8 +187,7 @@ function scorePage(page, terms) {
         score += 4;
     if (["pypi.org", "npmjs.com", "rubygems.org"].includes(domain))
         score -= 2;
-    if (page.date)
-        score += 1;
+    score += freshnessBoost(page.date);
     const lowered = page.text.toLowerCase();
     for (const t of terms)
         if (lowered.includes(t))
@@ -158,6 +208,9 @@ function resultQualityScore(c) {
         score += 4;
     if (url.includes("github.com") || url.includes("gitlab.com"))
         score += 3;
+    if (c.engine === "arxiv" || c.engine === "crossref")
+        score += 3;
+    score += Math.min(2, freshnessBoost(c.date));
     if (LOW_VALUE_SNIPPET.some((t) => snippet.includes(t)))
         score -= 10;
     return score;

package/dist/state.js

@@ -21,6 +21,8 @@ class RunState {
     usageByModel = new Map();
     totalUsage = { ...types_1.ZERO_USAGE };
     cost = 0;
+    /** Sampled cumulative token spend over time (budget sparkline). */
+    budgetSeries = [];
     finalSummary;
     finalReportPath;
     lastSeq = 0;
@@ -55,6 +57,13 @@ class RunState {
                 this.usageByModel.set(model, (0, types_1.addUsage)(this.usageByModel.get(model) ?? { ...types_1.ZERO_USAGE }, u));
                 this.totalUsage = (0, types_1.addUsage)(this.totalUsage, u);
                 this.cost += (0, types_1.usageCost)(u, this.pricing[model]);
+                this.pushBudgetPoint(ev.t);
+            }
+            else if (ev.type === "note.added") {
+                // The blackboard is shared swarm-wide at runtime, so team notes are
+                // root facts too — without this, a resume would forget every note a
+                // team agent posted (decisions included).
+                this.pushNote(ev, teamId);
             }
             return;
         }
@@ -127,6 +136,8 @@ class RunState {
                         t.openQuestions = ev.openQuestions;
                     if (Array.isArray(ev.filesTouched))
                         t.filesTouched = ev.filesTouched;
+                    if (Array.isArray(ev.sources))
+                        t.sources = ev.sources;
                 }
                 break;
             }
@@ -195,23 +206,7 @@ class RunState {
                 });
                 break;
             case "note.added":
-                this.notes.push({
-                    t: ev.t,
-                    taskId: ev.taskId,
-                    agentId: ev.agentId,
-                    key: ev.key,
-                    kind: ev.kind,
-                    text: ev.text,
-                });
-                // Reduced state is held live by the hub and the resume seed — keep
-                // only the tail that digests/views actually use. Decisions are never
-                // dropped: they anchor the conductor's long-horizon coherence.
-                if (this.notes.length > 1000) {
-                    const decisions = this.notes.filter((n) => n.kind === "decision");
-                    const rest = this.notes.filter((n) => n.kind !== "decision");
-                    rest.splice(0, rest.length - Math.max(0, 1000 - decisions.length));
-                    this.notes = [...decisions, ...rest].sort((a, b) => a.t - b.t);
-                }
+                this.pushNote(ev);
                 break;
             case "conductor.say":
                 this.conductorLog.push({ t: ev.t, text: ev.text });
@@ -233,6 +228,7 @@ class RunState {
                 this.usageByModel.set(model, (0, types_1.addUsage)(this.usageByModel.get(model) ?? { ...types_1.ZERO_USAGE }, u));
                 this.totalUsage = (0, types_1.addUsage)(this.totalUsage, u);
                 this.cost += (0, types_1.usageCost)(u, this.pricing[model]);
+                this.pushBudgetPoint(ev.t);
                 break;
             }
             case "run.final":
@@ -241,6 +237,60 @@ class RunState {
                 break;
         }
     }
+    /**
+     * Sample the cumulative spend: a point per meaningful jump (≥0.5% of the
+     * budget cap, or 2k tokens unbounded), halving resolution past 600 points.
+     */
+    pushBudgetPoint(t) {
+        const tokens = this.totalUsage.promptTokens + this.totalUsage.completionTokens;
+        const cap = this.meta?.options?.maxTokens ?? 0;
+        const minStep = cap > 0 ? Math.max(2000, cap * 0.005) : 2000;
+        const last = this.budgetSeries[this.budgetSeries.length - 1];
+        if (last && tokens - last.tokens < minStep) {
+            last.t = t;
+            last.tokens = tokens;
+            last.cost = this.cost;
+            return;
+        }
+        this.budgetSeries.push({ t, tokens, cost: this.cost });
+        if (this.budgetSeries.length > 600) {
+            this.budgetSeries = this.budgetSeries.filter((_, i) => i % 2 === 0 || i === this.budgetSeries.length - 1);
+        }
+    }
+    pushNote(ev, teamId) {
+        this.notes.push({
+            t: ev.t,
+            taskId: ev.taskId,
+            teamId,
+            agentId: ev.agentId,
+            key: ev.key,
+            kind: ev.kind,
+            text: ev.text,
+            url: typeof ev.url === "string" ? ev.url : undefined,
+        });
+        // Reduced state is held live by the hub and the resume seed — keep only
+        // the tail that digests/views actually use. Decisions and conflicts are
+        // never dropped: they anchor long-horizon coherence. Forward-pass splice
+        // (mirroring the executor's addNote): the array is permanently at the cap
+        // once a long run passes it, so this runs on every note event — no
+        // filter/sort allocations on the reducer hot path.
+        if (this.notes.length > 1000) {
+            const keep = (n) => n.kind === "decision" || n.kind === "conflict";
+            let pinnedCount = 0;
+            for (const n of this.notes)
+                if (keep(n))
+                    pinnedCount++;
+            let toDrop = this.notes.length - Math.max(pinnedCount, 1000);
+            for (let i = 0; i < this.notes.length && toDrop > 0;) {
+                if (!keep(this.notes[i])) {
+                    this.notes.splice(i, 1);
+                    toDrop--;
+                }
+                else
+                    i++;
+            }
+        }
+    }
     taskList() {
         return this.taskOrder.map((id) => this.tasks.get(id)).filter(Boolean);
     }

package/dist/tools.js

@@ -40,6 +40,7 @@ exports.synthToolset = synthToolset;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const crawltools_1 = require("./crawltools");
+const searchcore_1 = require("./searchcore");
 const util_1 = require("./util");
 const webtools_1 = require("./webtools");
 // ---------- safety ----------
@@ -62,9 +63,48 @@ function checkCommand(cmd, cfg) {
 function resolveRead(p, ctx) {
     return path.resolve(ctx.workdir, p);
 }
+/** Single-quote a string for sh. */
+function shq(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Where a write actually lands: realpath of the deepest existing ancestor plus
+ * the not-yet-created remainder. Confinement checks must use this, or a
+ * symlink inside the workdir smuggles writes anywhere on the host.
+ */
+function realDestination(abs) {
+    let dir = abs;
+    const tail = [];
+    while (!fs.existsSync(dir)) {
+        tail.unshift(path.basename(dir));
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    try {
+        dir = fs.realpathSync(dir);
+    }
+    catch {
+        /* races/permissions: keep the lexical path */
+    }
+    return path.join(dir, ...tail);
+}
+function realBase(base) {
+    try {
+        return fs.realpathSync(base);
+    }
+    catch {
+        return base;
+    }
+}
 function resolveWrite(p, ctx) {
     const abs = path.resolve(ctx.workdir, p);
-    const ok = (0, util_1.pathInside)(ctx.workdir, abs) || (0, util_1.pathInside)(ctx.runDirPath, abs) || !ctx.cfg.safeMode;
+    // Remote sandboxes own their filesystem — host-side realpath is meaningless there.
+    const real = ctx.sandbox.localFs ? realDestination(abs) : abs;
+    const ok = (0, util_1.pathInside)(realBase(ctx.workdir), real) ||
+        (0, util_1.pathInside)(realBase(ctx.runDirPath), real) ||
+        !ctx.cfg.safeMode;
     if (!ok) {
         throw new Error(`safeMode: writes are restricted to the working directory (${ctx.workdir}). ` +
             `Use a relative path, or save deliverables with save_artifact.`);
@@ -171,7 +211,7 @@ function workerToolset(cfg) {
     tools.replace_in_file = {
         schema: {
             name: "replace_in_file",
-            description: "Exact string replacement in a file. `find` must match exactly (including whitespace). Fails if not found, or if ambiguous when all=false.",
+            description: "Exact string replacement in a file. `find` must match exactly (including whitespace). Fails if not found, or if ambiguous when all=false. For several edits to the same file, pass `edits` — they apply in order, all-or-nothing, in one call.",
             parameters: {
                 type: "object",
                 properties: {
@@ -179,25 +219,108 @@ function workerToolset(cfg) {
                     find: { type: "string" },
                     replace: { type: "string" },
                     all: { type: "boolean", description: "Replace every occurrence (default false)" },
+                    edits: {
+                        type: "array",
+                        description: "Batch mode: multiple find/replace pairs applied in order, atomically (replaces top-level find/replace)",
+                        items: {
+                            type: "object",
+                            properties: {
+                                find: { type: "string" },
+                                replace: { type: "string" },
+                                all: { type: "boolean" },
+                            },
+                            required: ["find", "replace"],
+                        },
+                    },
                 },
-                required: ["path", "find", "replace"],
+                required: ["path"],
             },
         },
         run: async (args, ctx) => {
             const abs = resolveWrite(String(args.path), ctx);
             const raw = await readFileVia(ctx, abs);
-            const find = String(args.find);
-            const replace = String(args.replace);
-            const count = raw.split(find).length - 1;
-            if (count === 0)
-                throw new Error("find string not found in file");
-            if (count > 1 && !args.all) {
-                throw new Error(`find string matches ${count} times; provide more context or set all=true`);
+            const edits = Array.isArray(args.edits) && args.edits.length
+                ? args.edits.map((e) => ({
+                    find: String(e.find ?? ""),
+                    replace: String(e.replace ?? ""),
+                    all: Boolean(e.all),
+                }))
+                : args.find !== undefined && args.replace !== undefined
+                    ? [{ find: String(args.find), replace: String(args.replace), all: Boolean(args.all) }]
+                    : null;
+            if (!edits)
+                throw new Error("provide find+replace, or an edits array");
+            // Validate-then-apply against the progressively edited content:
+            // any failing edit aborts the whole batch with nothing written.
+            let next = raw;
+            let total = 0;
+            const at = (i) => (edits.length > 1 ? `edit ${i + 1}: ` : "");
+            for (let i = 0; i < edits.length; i++) {
+                const { find, replace, all } = edits[i];
+                if (!find)
+                    throw new Error(`${at(i)}find must not be empty`);
+                const count = next.split(find).length - 1;
+                if (count === 0) {
+                    throw new Error(`${at(i)}find string not found in file${edits.length > 1 ? " — no edits were applied" : ""}`);
+                }
+                if (count > 1 && !all) {
+                    throw new Error(`${at(i)}find string matches ${count} times; provide more context or set all=true${edits.length > 1 ? " — no edits were applied" : ""}`);
+                }
+                next = all ? next.split(find).join(replace) : next.replace(find, replace);
+                total += all ? count : 1;
             }
-            const next = args.all ? raw.split(find).join(replace) : raw.replace(find, replace);
             await writeFileVia(ctx, abs, next);
             const warn = ctx.checkClaim?.(String(args.path));
-            return `replaced ${args.all ? count : 1} occurrence(s) in ${abs}${warn ? `\n${warn}` : ""}`;
+            return `replaced ${total} occurrence(s) via ${edits.length} edit(s) in ${abs}${warn ? `\n${warn}` : ""}`;
+        },
+    };
+    tools.grep_files = {
+        schema: {
+            name: "grep_files",
+            description: "Search file contents with a regex (grep -E syntax). Returns matching lines as path:line:text. Use this to locate code or text instead of shell grep pipelines — one round-trip, works identically in remote sandboxes, skips node_modules/.git/build output.",
+            parameters: {
+                type: "object",
+                properties: {
+                    pattern: { type: "string", description: "Extended regex (grep -E)" },
+                    path: { type: "string", description: "Directory or file to search (default: working directory)" },
+                    glob: { type: "string", description: "Filename filter, e.g. *.ts" },
+                    ignore_case: { type: "boolean" },
+                    max_results: { type: "number", description: "Default 50, max 200" },
+                },
+                required: ["pattern"],
+            },
+        },
+        run: async (args, ctx) => {
+            const pattern = String(args.pattern ?? "");
+            if (!pattern.trim())
+                throw new Error("pattern is required");
+            const root = args.path ? resolveRead(String(args.path), ctx) : ctx.workdir;
+            const max = Math.min(Math.max(Number(args.max_results) || 50, 1), 200);
+            const flags = `-rnE${args.ignore_case ? "i" : ""}`;
+            const include = args.glob ? ` --include=${shq(String(args.glob))}` : "";
+            const excludes = ["node_modules", ".git", "dist", ".next", "out", "build", "target", "__pycache__", ".venv"]
+                .map((d) => ` --exclude-dir=${d}`)
+                .join("");
+            // No `| head`: a pipe would mask grep's exit code, and an invalid regex
+            // or unreadable path must fail loudly, not read as "no matches".
+            // (Output volume is already bounded by the sandbox's collect cap.)
+            const cmd = `grep ${flags}${include}${excludes} -e ${shq(pattern)} ${shq(root)}`;
+            const r = await ctx.sandbox.exec(cmd, { cwd: ctx.workdir, timeoutSec: 60, signal: ctx.signal });
+            // Sandbox exec merges stderr into out — separate grep's diagnostics.
+            const all = r.out.split("\n").filter(Boolean);
+            const diags = all.filter((l) => l.startsWith("grep:"));
+            const lines = all.filter((l) => !l.startsWith("grep:"));
+            // Exit 1 = clean no-match. Anything past 1 with zero matches is a real
+            // failure (bad pattern, missing path); with matches it's partial
+            // (some files unreadable) and the matches still count.
+            if (r.code !== 0 && r.code !== 1 && !lines.length) {
+                throw new Error(`grep failed (exit ${r.code}): ${diags.join("; ").slice(0, 300) || "no error detail"}`);
+            }
+            if (!lines.length)
+                return "no matches";
+            const shown = lines.slice(0, max);
+            const more = lines.length > max ? `\n…more matches truncated (raise max_results or narrow the pattern)` : "";
+            return shown.join("\n") + more;
         },
     };
     tools.list_dir = {
@@ -295,6 +418,39 @@ function workerToolset(cfg) {
                 .join("\n");
         },
     };
+    tools.academic_search = {
+        schema: {
+            name: "academic_search",
+            description: "Search scholarly sources: arXiv preprints and Crossref journal/conference metadata (keyless APIs). Returns papers with title, link (arXiv/DOI), abstract snippet, and date. Use for scientific or technical questions where peer-reviewed and preprint sources beat the open web.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                    count: { type: "number", description: "Max results, default 8, max 20" },
+                },
+                required: ["query"],
+            },
+        },
+        run: async (args, ctx) => {
+            const count = Math.min(Math.max(Number(args.count) || 8, 1), 20);
+            const q = String(args.query);
+            const settled = await Promise.allSettled([
+                (0, webtools_1.arxivSearch)(q, count, ctx.signal),
+                (0, webtools_1.crossrefSearch)(q, count, ctx.signal),
+            ]);
+            const candidates = settled.flatMap((s) => (s.status === "fulfilled" ? s.value : []));
+            if (!candidates.length) {
+                const err = settled.find((s) => s.status === "rejected");
+                if (err)
+                    throw err.reason;
+                return "no results";
+            }
+            const merged = (0, searchcore_1.mergeCandidates)(candidates, count);
+            return merged
+                .map((h, i) => `${i + 1}. ${h.title}${h.date ? ` (${h.date})` : ""} [${h.engine}]\n   ${h.url}\n   ${h.snippet}`)
+                .join("\n");
+        },
+    };
     tools.fetch_url = {
         schema: {
             name: "fetch_url",
@@ -318,7 +474,7 @@ function workerToolset(cfg) {
     tools.note = {
         schema: {
             name: "note",
-            description: "Post a durable fact/discovery to the swarm's shared blackboard so the conductor and other agents can see it. Use sparingly — facts other tasks need, not progress chatter. Mark kind='decision' for choices the rest of the mission must respect (these are never trimmed from digests).",
+            description: "Post a durable fact/discovery to the swarm's shared blackboard so the conductor and other agents can see it. Use sparingly — facts other tasks need, not progress chatter. Mark kind='decision' for choices the rest of the mission must respect, and kind='conflict' when independent sources disagree on a material fact (both are never trimmed from digests).",
             parameters: {
                 type: "object",
                 properties: {
@@ -326,18 +482,20 @@ function workerToolset(cfg) {
                     key: { type: "string", description: "Optional short label" },
                     kind: {
                         type: "string",
-                        enum: ["finding", "decision", "open-question", "handoff", "claim"],
-                        description: "Category (default finding). kind='claim' with key=<file path> advertises you are editing that file",
+                        enum: ["finding", "decision", "conflict", "open-question", "handoff", "claim"],
+                        description: "Category (default finding). kind='conflict' flags sources that disagree — name both. kind='claim' with key=<file path> advertises you are editing that file",
                     },
+                    url: { type: "string", description: "Source URL backing this note, when it came from the web" },
                 },
                 required: ["text"],
             },
         },
         run: async (args, ctx) => {
-            const kind = ["finding", "decision", "open-question", "handoff", "claim"].includes(String(args.kind))
+            const kind = ["finding", "decision", "conflict", "open-question", "handoff", "claim"].includes(String(args.kind))
                 ? String(args.kind)
                 : undefined;
-            ctx.addNote(String(args.text), args.key ? String(args.key) : undefined, kind);
+            const url = /^https?:\/\//.test(String(args.url ?? "")) ? String(args.url) : undefined;
+            ctx.addNote(String(args.text), args.key ? String(args.key) : undefined, kind, url);
             return "noted on the blackboard";
         },
     };
@@ -416,8 +574,12 @@ function workerToolset(cfg) {
         },
         run: async (args, ctx) => {
             const name = String(args.name).replace(/^\/+/, "");
-            const dest = path.join(ctx.runDirPath, "artifacts", name);
-            if (!(0, util_1.pathInside)(path.join(ctx.runDirPath, "artifacts"), dest)) {
+            const artifactsRoot = path.join(ctx.runDirPath, "artifacts");
+            (0, util_1.ensureDir)(artifactsRoot);
+            const dest = path.join(artifactsRoot, name);
+            // Realpath-based: neither ../ traversal nor a planted symlink may move
+            // the artifact outside the run's artifacts folder.
+            if (!(0, util_1.pathInside)(realBase(artifactsRoot), realDestination(dest))) {
                 throw new Error("artifact name must stay inside the artifacts folder");
             }
             (0, util_1.ensureDir)(path.dirname(dest));
@@ -546,6 +708,20 @@ exports.REPORT_TOOL = {
                 items: { type: "string" },
                 description: "Every file you created or modified (exact paths)",
             },
+            sources: {
+                type: "array",
+                description: "Web sources your findings rely on — REQUIRED whenever your work drew on the web. They flow into the final report's bibliography; a web-sourced claim without an entry here cannot be cited.",
+                items: {
+                    type: "object",
+                    properties: {
+                        url: { type: "string" },
+                        title: { type: "string" },
+                        date: { type: "string", description: "Publication date if known (ISO or year)" },
+                        note: { type: "string", description: "What this source supports" },
+                    },
+                    required: ["url"],
+                },
+            },
         },
         required: ["status", "report"],
     },
@@ -561,6 +737,19 @@ exports.VERDICT_TOOL = {
                 type: "string",
                 description: "If fail: exactly what is wrong and where. If pass: one-line confirmation of the evidence.",
             },
+            issues: {
+                type: "array",
+                description: "On fail: one entry per concrete problem. The worker's retry sees these verbatim — make each actionable.",
+                items: {
+                    type: "object",
+                    properties: {
+                        problem: { type: "string", description: "What is wrong" },
+                        evidence: { type: "string", description: "What you observed that proves it (command output, file content, URL)" },
+                        fix: { type: "string", description: "The exact change that would resolve it" },
+                    },
+                    required: ["problem"],
+                },
+            },
         },
         required: ["pass", "feedback"],
     },