@robzilla1738/agentswarm 0.3.0 → 0.6.0

package/dist/tools.js

@@ -33,12 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FINISH_TOOL = exports.WAIT_TOOL = exports.SPAWN_TASKS_TOOL = exports.SUBMIT_FINAL_TOOL = exports.VERDICT_TOOL = exports.REPORT_TOOL = void 0;
+exports.FINISH_TOOL = exports.WAIT_TOOL = exports.SET_PHASE_TOOL = exports.UPDATE_PLAN_TOOL = exports.CONDUCTOR_READ_REPORT_TOOL = exports.SPAWN_TASKS_TOOL = exports.SUBMIT_FINAL_TOOL = exports.VERDICT_TOOL = exports.REPORT_TOOL = void 0;
 exports.workerToolset = workerToolset;
 exports.verifierToolset = verifierToolset;
 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 ----------
@@ -61,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.`);
@@ -84,7 +125,7 @@ async function writeFileVia(ctx, abs, content) {
     }
 }
 // ---------- tool definitions ----------
-function workerToolset() {
+function workerToolset(cfg) {
     const tools = {};
     tools.shell = {
         schema: {
@@ -163,13 +204,14 @@ function workerToolset() {
             if (content.length > 5_000_000)
                 throw new Error("content too large (>5MB)");
             await writeFileVia(ctx, abs, content);
-            return `wrote ${abs} (${content.length} chars)`;
+            const warn = ctx.checkClaim?.(String(args.path));
+            return `wrote ${abs} (${content.length} chars)${warn ? `\n${warn}` : ""}`;
         },
     };
     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: {
@@ -177,24 +219,96 @@ function workerToolset() {
                     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);
-            return `replaced ${args.all ? count : 1} occurrence(s) in ${abs}`;
+            const warn = ctx.checkClaim?.(String(args.path));
+            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("");
+            const cmd = `grep ${flags}${include}${excludes} -e ${shq(pattern)} ${shq(root)} | head -n ${max + 1}`;
+            const r = await ctx.sandbox.exec(cmd, { cwd: ctx.workdir, timeoutSec: 60, signal: ctx.signal });
+            const lines = r.out.split("\n").filter(Boolean);
+            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 = {
@@ -266,20 +380,20 @@ function workerToolset() {
     tools.web_search = {
         schema: {
             name: "web_search",
-            description: "Search the web. Returns ranked results with title, URL and snippet. " +
-                "Set deep=true to also fetch top pages and return quotable passages (slower; use for claims that need grounding).",
+            description: "Search the web. Fans out across multiple engines (DuckDuckGo, Bing, +TinyFish if configured), merges and quality-ranks results, and dedupes by canonical URL. Returns ranked results with title, URL and snippet. " +
+                "Set deep=true to widen the query into complementary phrasings, fetch the top pages, and return quotable passages with publication dates — use for thorough research and any claim that needs grounding. Raise count (up to 25) to pull more sources per call.",
             parameters: {
                 type: "object",
                 properties: {
                     query: { type: "string" },
-                    count: { type: "number", description: "Max results, default 6, max 10" },
-                    deep: { type: "boolean", description: "Fetch page content for quotable passages" },
+                    count: { type: "number", description: "Max results, default 8, max 25" },
+                    deep: { type: "boolean", description: "Multi-phrasing sweep + fetch pages for quotable passages" },
                 },
                 required: ["query"],
             },
         },
         run: async (args, ctx) => {
-            const count = Math.min(Math.max(Number(args.count) || 6, 1), 10);
+            const count = Math.min(Math.max(Number(args.count) || 8, 1), 25);
             const hits = await (0, webtools_1.webSearch)(ctx.cfg, String(args.query), count, ctx.signal, Boolean(args.deep), (msg) => ctx.log?.("warn", msg));
             if (!hits.length)
                 return "no results";
@@ -292,6 +406,39 @@ function workerToolset() {
                 .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",
@@ -315,25 +462,94 @@ function workerToolset() {
     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.",
+            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: {
                     text: { type: "string" },
                     key: { type: "string", description: "Optional short label" },
+                    kind: {
+                        type: "string",
+                        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) => {
-            ctx.addNote(String(args.text), args.key ? String(args.key) : undefined);
+            const kind = ["finding", "decision", "conflict", "open-question", "handoff", "claim"].includes(String(args.kind))
+                ? String(args.kind)
+                : undefined;
+            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";
         },
     };
+    tools.search_notes = {
+        schema: {
+            name: "search_notes",
+            description: "Keyword-search the ENTIRE blackboard history (the digest in your prompt only shows the recent tail). Use when you need a fact another agent may have posted earlier in the run.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Keywords to match against note text/labels" },
+                },
+                required: ["query"],
+            },
+        },
+        run: async (args, ctx) => {
+            if (!ctx.searchNotes)
+                return "note search is unavailable in this context";
+            return ctx.searchNotes(String(args.query ?? ""));
+        },
+    };
+    tools.read_report = {
+        schema: {
+            name: "read_report",
+            description: "Read the FULL report of a settled task (dependency reports in your prompt are excerpts). Use when an excerpt cuts off details you need.",
+            parameters: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "e.g. T3" },
+                },
+                required: ["task_id"],
+            },
+        },
+        run: async (args, ctx) => {
+            if (!ctx.readReport)
+                return "report lookup is unavailable in this context";
+            return ctx.readReport(String(args.task_id ?? ""));
+        },
+    };
+    tools.checkpoint = {
+        schema: {
+            name: "checkpoint",
+            description: "Journal a durable progress checkpoint: a dense summary of what you've completed, key findings, and what remains. If the run is interrupted, the next attempt resumes from your latest checkpoint instead of starting over. Use after completing each major chunk of a long task.",
+            parameters: {
+                type: "object",
+                properties: {
+                    summary: {
+                        type: "string",
+                        description: "Completed work (exact paths/commands), key findings, and remaining steps",
+                    },
+                },
+                required: ["summary"],
+            },
+        },
+        run: async (args, ctx) => {
+            const summary = String(args.summary ?? "").trim();
+            if (!summary)
+                throw new Error("summary is required");
+            ctx.addCheckpoint?.(summary);
+            return "checkpoint saved";
+        },
+    };
     tools.save_artifact = {
         schema: {
             name: "save_artifact",
-            description: "Save a deliverable into the run's artifacts folder (shown prominently to the operator). Provide content, or from_path to copy an existing file.",
+            description: "Save a deliverable into the run's artifacts folder (shown prominently to the operator). Provide content, or from_path to copy an existing file. Any file type works — save deliverables in the format that fits them (.csv/.json for data, .html for documents, runnable code files), not just markdown.",
             parameters: {
                 type: "object",
                 properties: {
@@ -346,8 +562,12 @@ function workerToolset() {
         },
         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));
@@ -366,6 +586,64 @@ function workerToolset() {
             return `saved artifacts/${name}`;
         },
     };
+    // Only offered when a crawl backend (Firecrawl / context.dev / deepcrawl)
+    // is configured — there is no free fallback for whole-site crawls.
+    if (cfg && (0, crawltools_1.resolveCrawlBackend)(cfg)) {
+        tools.crawl_site = {
+            schema: {
+                name: "crawl_site",
+                description: "Crawl a website (JS-rendered, clean markdown) and save every discovered page as a markdown file under crawl/<host>/ in the working directory. Returns an index of the saved files — read individual pages afterwards with read_file. Use for ingesting documentation sites or multi-page content; use fetch_url for single pages.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        url: { type: "string", description: "Starting URL to crawl" },
+                        max_pages: { type: "number", description: "Page limit (default 15, max 50)" },
+                        include_paths: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Limit the crawl to URL path prefixes/globs, e.g. /docs/*",
+                        },
+                    },
+                    required: ["url"],
+                },
+            },
+            run: async (args, ctx) => {
+                const url = String(args.url ?? "");
+                if (!/^https?:\/\//.test(url))
+                    throw new Error("only http(s) URLs are supported");
+                const maxPages = Math.min(Math.max(Number(args.max_pages) || 15, 1), 50);
+                const includePaths = Array.isArray(args.include_paths)
+                    ? args.include_paths.map(String).filter(Boolean)
+                    : undefined;
+                const out = await (0, crawltools_1.crawlSite)(ctx.cfg, { url, maxPages, includePaths, signal: ctx.signal });
+                if (!out.pages.length) {
+                    return `crawled ${url} via ${out.backend}: no pages with content${out.warnings.length ? `\nwarnings: ${out.warnings.join("; ")}` : ""}`;
+                }
+                const used = new Set();
+                const lines = [];
+                for (const page of out.pages) {
+                    const { host, slug } = (0, crawltools_1.slugForUrl)(page.url || url);
+                    let rel = `crawl/${host}/${slug}.md`;
+                    for (let n = 2; used.has(rel); n++)
+                        rel = `crawl/${host}/${slug}-${n}.md`;
+                    used.add(rel);
+                    const abs = resolveWrite(rel, ctx);
+                    const header = `# ${page.title || page.url || "untitled"}\n\nSource: ${page.url || url}\n\n`;
+                    await writeFileVia(ctx, abs, header + page.markdown);
+                    if (lines.length < 50) {
+                        lines.push(`  ${rel} — "${page.title || "untitled"}" (${page.markdown.length.toLocaleString()} chars)`);
+                    }
+                }
+                const hidden = out.pages.length - lines.length;
+                return [
+                    `crawled ${url} via ${out.backend}: ${out.pages.length} page${out.pages.length > 1 ? "s" : ""} saved`,
+                    ...lines,
+                    ...(hidden > 0 ? [`  …and ${hidden} more (list crawl/ to see all)`] : []),
+                    ...(out.warnings.length ? [`warnings: ${out.warnings.join("; ")}`] : []),
+                ].join("\n");
+            },
+        };
+    }
     return tools;
 }
 function verifierToolset() {
@@ -383,6 +661,7 @@ function synthToolset() {
     return {
         read_file: all.read_file,
         list_dir: all.list_dir,
+        save_artifact: all.save_artifact,
     };
 }
 // ---------- terminal tool schemas (handled by the agent loop, not executed) ----------
@@ -402,6 +681,35 @@ exports.REPORT_TOOL = {
                 items: { type: "string" },
                 description: "Paths of files you created/changed that matter",
             },
+            key_facts: {
+                type: "array",
+                items: { type: "string" },
+                description: "3-8 standalone facts downstream tasks need (figures, paths, URLs, decisions)",
+            },
+            open_questions: {
+                type: "array",
+                items: { type: "string" },
+                description: "Unresolved questions or risks the conductor should know about",
+            },
+            files_touched: {
+                type: "array",
+                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"],
     },
@@ -417,6 +725,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"],
     },
@@ -460,6 +781,17 @@ exports.SPAWN_TASKS_TOOL = {
                         },
                         verify: { type: "boolean", description: "Adversarially verify this task's result before accepting it" },
                         context: { type: "string", description: "Facts, paths, URLs, constraints the worker needs inlined" },
+                        model: {
+                            type: "string",
+                            enum: ["cheap", "default", "strong"],
+                            description: "Model tier: cheap for scouts/bulk extraction, strong for leads, integration, and verified deliverables",
+                        },
+                        team: {
+                            type: "boolean",
+                            description: "Run as a sub-swarm: this task gets its own conductor that decomposes it into parallel sub-tasks and reports one consolidated result. Use for coherent multi-task subsystems (e.g. 'build the backend'). Teams cannot spawn teams.",
+                        },
+                        team_max_workers: { type: "number", description: "Parallelism inside the team (default: half the run's)" },
+                        team_budget_tokens: { type: "number", description: "Token slice for the team (default: a quarter of what remains)" },
                     },
                     required: ["title", "objective"],
                 },
@@ -468,6 +800,41 @@ exports.SPAWN_TASKS_TOOL = {
         required: ["tasks"],
     },
 };
+exports.CONDUCTOR_READ_REPORT_TOOL = {
+    name: "read_report",
+    description: "Read the full report of any settled task. Updates show one-line summaries once many tasks settle — use this when a summary isn't enough to plan from.",
+    parameters: {
+        type: "object",
+        properties: {
+            task_id: { type: "string", description: "e.g. T17" },
+        },
+        required: ["task_id"],
+    },
+};
+exports.UPDATE_PLAN_TOOL = {
+    name: "update_plan",
+    description: "Maintain the mission's living plan document (artifacts/mission-plan.md, full overwrite). On missions beyond ~20 tasks, keep it current: approach, phases, what's done, what's next, open risks. Its head is pinned into every update you receive, surviving history trimming and restarts.",
+    parameters: {
+        type: "object",
+        properties: {
+            markdown: { type: "string", description: "The complete plan document (markdown)" },
+        },
+        required: ["markdown"],
+    },
+};
+exports.SET_PHASE_TOOL = {
+    name: "set_phase",
+    description: "Declare the mission's current phase/milestone. Use on long missions to structure the work (e.g. 'discovery' → 'build' → 'integrate' → 'polish'). The phase and its exit criteria are pinned into every update you receive, surviving history trimming.",
+    parameters: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "Short phase name" },
+            goal: { type: "string", description: "What this phase accomplishes" },
+            exit_criteria: { type: "string", description: "Concrete conditions that end this phase" },
+        },
+        required: ["name"],
+    },
+};
 exports.WAIT_TOOL = {
     name: "wait",
     description: "Do nothing for now; wake again when running tasks report.",

package/dist/util.js

@@ -48,6 +48,7 @@ exports.ensureDir = ensureDir;
 exports.readJson = readJson;
 exports.writeJson = writeJson;
 exports.pathInside = pathInside;
+exports.validateArtifactFormat = validateArtifactFormat;
 exports.decodeEntities = decodeEntities;
 exports.htmlToText = htmlToText;
 const fs = __importStar(require("fs"));
@@ -147,6 +148,90 @@ function pathInside(parent, child) {
     const rel = path.relative(path.resolve(parent), path.resolve(child));
     return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
+// ---------- artifact validation ----------
+/**
+ * Cheap structural checks for common deliverable formats — catches a worker
+ * shipping malformed JSON/CSV/stub HTML before an LLM verifier spends tokens
+ * on it. Returns a problem description, or null when the file looks sound
+ * (or is a format we don't check).
+ */
+function validateArtifactFormat(absPath) {
+    const ext = path.extname(absPath).toLowerCase();
+    if (![".json", ".csv", ".html", ".htm"].includes(ext))
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null; // existence/size is the caller's check
+    }
+    if (ext === ".json") {
+        try {
+            JSON.parse(raw);
+            return null;
+        }
+        catch (e) {
+            return `not valid JSON (${errMsg(e)})`;
+        }
+    }
+    if (ext === ".csv") {
+        const counts = csvFieldCounts(raw, 50);
+        if (!counts.length)
+            return "CSV has no records";
+        const expect = counts[0];
+        const bad = counts.findIndex((c) => c !== expect);
+        if (bad > 0)
+            return `inconsistent CSV: record 1 has ${expect} field(s), record ${bad + 1} has ${counts[bad]}`;
+        return null;
+    }
+    // .html / .htm — catch empty shells and plain text passed off as HTML.
+    if (raw.length < 200 || !/<[a-z!][^>]*>/i.test(raw) || !/<\/[a-z][a-z0-9]*>/i.test(raw)) {
+        return "HTML looks like a stub (too short or no real markup)";
+    }
+    return null;
+}
+/** Field count per CSV record (quote-aware, handles newlines inside quotes). */
+function csvFieldCounts(raw, maxRecords) {
+    const counts = [];
+    let fields = 1;
+    let chars = 0; // non-separator chars seen in the current record
+    let inQ = false;
+    for (let i = 0; i < raw.length && counts.length < maxRecords; i++) {
+        const ch = raw[i];
+        if (inQ) {
+            if (ch === '"') {
+                if (raw[i + 1] === '"')
+                    i++;
+                else
+                    inQ = false;
+            }
+            chars++;
+        }
+        else if (ch === '"') {
+            inQ = true;
+            chars++;
+        }
+        else if (ch === ",") {
+            fields++;
+            chars++;
+        }
+        else if (ch === "\n" || ch === "\r") {
+            if (ch === "\r" && raw[i + 1] === "\n")
+                i++;
+            if (chars > 0)
+                counts.push(fields); // skip blank lines
+            fields = 1;
+            chars = 0;
+        }
+        else {
+            chars++;
+        }
+    }
+    if (chars > 0 && counts.length < maxRecords)
+        counts.push(fields);
+    return counts;
+}
 // ---------- html ----------
 const ENTITIES = {
     amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ",