@inflexa-ai/harness 0.23.0 → 0.24.0

package/dist/tools/report/preview-snapshot.js

@@ -1,98 +0,0 @@
-/**
- * preview_snapshot tool — navigate headless Chrome to the rendered report,
- * wait for the `inflexa-theme-ready` event, capture a screenshot + console
- * messages + failed network requests in a single deterministic call.
- *
- * Lazily mints a preview URL via the `PreviewPublisher` seam on first use,
- * sharing the cached URL with the `mint_preview_url` tool via a
- * closure-captured `PreviewUrlCell`.
- *
- * Returned screenshot is base64-encoded PNG bytes; the agent can inspect
- * console errors / failed requests to decide whether to fix the template
- * or move on to submit_report.
- *
- * A seam that cannot mint is also reported through the injected `Logger`:
- * this tool is the build's only visual verification, so an unavailable seam
- * means that verification silently did not happen — a condition an operator
- * has to be able to see without reading the model transcript.
- */
-import { ok } from "neverthrow";
-import { z } from "zod";
-import { defineTool } from "../define-tool.js";
-import { capturePage } from "../../lib/page-capture.js";
-import { createNoopLogger } from "../../lib/console-logger.js";
-import { describeMintFailure } from "./preview-publisher.js";
-const WAIT_MS_CAP = 30_000;
-export function createPreviewSnapshotTool(state) {
-    const logger = (state.logger ?? createNoopLogger()).named("preview-snapshot").with({ previewId: state.previewId });
-    return defineTool({
-        id: "preview_snapshot",
-        description: "Render the report in a real headless browser and report what you " +
-            "see. Returns a screenshot, console errors, and failed network " +
-            "requests. Use this after build_report to verify the layout, charts, " +
-            "and data loads correctly.",
-        inputSchema: z.object({
-            waitForSelector: z
-                .string()
-                .optional()
-                .describe("Optional CSS selector to wait for after the page is loaded — useful " + "when a specific chart needs to be visible before the screenshot."),
-            waitMs: z
-                .number()
-                .finite()
-                .int()
-                .min(0)
-                .max(WAIT_MS_CAP)
-                .optional()
-                .describe("Optional extra wait in ms after the theme-ready event (e.g., for chart paint). Capped at 30s."),
-        }),
-        describeCall: "none",
-        execute: async (input) => {
-            let url = state.urlCell.url;
-            const expiresAt = state.urlCell.expiresAt;
-            if (url && expiresAt && new Date(expiresAt).getTime() < Date.now() + 60_000) {
-                url = undefined; // refresh if within 60s of expiry
-            }
-            if (!url) {
-                const result = await state.previews.mintPreviewAccess(state.resourceId, state.previewId);
-                if (!result.ok) {
-                    const reason = result.error.message?.trim();
-                    logger.warn("preview access unavailable — visual verification did not run", {
-                        version: state.currentVersion,
-                        ...(result.status !== undefined ? { status: result.status } : {}),
-                        ...(reason ? { reason } : {}),
-                    });
-                    return ok({
-                        ok: false,
-                        consoleErrors: [],
-                        failedRequests: [],
-                        error: describeMintFailure(result),
-                    });
-                }
-                url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${state.currentVersion}/index.html?t=${result.data.token}`;
-                state.urlCell.url = url;
-                state.urlCell.expiresAt = result.data.expiresAt;
-            }
-            try {
-                const captured = await capturePage(state.chrome, url, {
-                    ...(input.waitForSelector !== undefined ? { waitForSelector: input.waitForSelector } : {}),
-                    ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}),
-                });
-                return ok({
-                    ok: true,
-                    screenshotBase64: captured.screenshotBase64,
-                    coverage: captured.coverage,
-                    consoleErrors: captured.consoleErrors,
-                    failedRequests: captured.failedRequests,
-                });
-            }
-            catch (err) {
-                return ok({
-                    ok: false,
-                    consoleErrors: [],
-                    failedRequests: [],
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-        },
-    });
-}

package/dist/tools/report/submit-report.d.ts

@@ -1,26 +0,0 @@
-/**
- * submit_report tool — postcondition gate. The runner refuses to emit
- * `data-report-preview` until this tool writes the success outcome.
- *
- * Checks:
- *   - report.html.j2 exists at versionDir/ — the report itself
- *   - index.html exists at versionDir/ with size > 0
- *   - no unrendered `{{ … }}` or `{% … %}` left in the output
- *   - all referenced asset paths resolve to files on disk
- *
- * On success, writes `{ ok: true, notes }` into the runner's closure-captured
- * outcome variable.
- */
-import { type Tool } from "../define-tool.js";
-/** Terminal outcome the submit-report tool writes into the runner closure. */
-export type ReportOutcome = {
-    ok: true;
-    notes: readonly string[];
-};
-export interface SubmitReportToolState {
-    readonly versionDir: string;
-    readonly assetsDir: string;
-    /** Write-through for the runner's closure-captured outcome variable. */
-    setOutcome(outcome: ReportOutcome): void;
-}
-export declare function createSubmitReportTool(state: SubmitReportToolState): Tool;

package/dist/tools/report/submit-report.js

@@ -1,148 +0,0 @@
-/**
- * submit_report tool — postcondition gate. The runner refuses to emit
- * `data-report-preview` until this tool writes the success outcome.
- *
- * Checks:
- *   - report.html.j2 exists at versionDir/ — the report itself
- *   - index.html exists at versionDir/ with size > 0
- *   - no unrendered `{{ … }}` or `{% … %}` left in the output
- *   - all referenced asset paths resolve to files on disk
- *
- * On success, writes `{ ok: true, notes }` into the runner's closure-captured
- * outcome variable.
- */
-import { readFile, stat } from "node:fs/promises";
-import { join, resolve, sep } from "node:path";
-import { ok } from "neverthrow";
-import { z } from "zod";
-import { defineTool } from "../define-tool.js";
-// `[^{}]*` accepts any expression Nunjucks allows between delimiters
-// (filters `{{ x | tojson }}`, inline conditionals `{{ a if b else c }}`,
-// bracket access `{{ d['k'] }}`) but stops at nested braces — which aren't
-// valid Nunjucks anyway. The `{%-?` arm covers whitespace-trimming tags.
-const UNRENDERED_JINJA = /\{\{[^{}]*\}\}|\{%-?\s*\w/;
-export function createSubmitReportTool(state) {
-    return defineTool({
-        id: "submit_report",
-        description: "Declare the report ready. Validates report.html.j2 and index.html " +
-            "exist, that the output has no unrendered Jinja, and that all " +
-            "referenced asset paths resolve. " +
-            "You MUST call this to finish — the runner ignores any other claim " +
-            "of success. Returns problems[] when checks fail; fix and re-submit. " +
-            "Use `notes` to surface caveats to the caller (e.g. sections rendered " +
-            "with partial data, missing inputs that forced a fallback) — these " +
-            "reach the conversation agent and the user in the iteration result.",
-        inputSchema: z.object({
-            notes: z
-                .array(z.string())
-                .optional()
-                .describe("Caveats / issues to surface to the caller. One short sentence " +
-                "per item. Examples: 'pathway-enrichment section omitted — no " +
-                "GSEA output found', 'cohort table rendered from 8 of 12 " +
-                "samples — the rest had no QC row'. " +
-                "Leave empty when the report shipped cleanly."),
-        }),
-        describeCall: "none",
-        execute: async (input) => {
-            const problems = [];
-            // 1. report.html.j2 exists — the report itself, as opposed to the
-            // artifact rendered from it. Nothing downstream re-derives this: a
-            // version that is finalized without a template persists as one, and
-            // the next iteration copies a template that isn't there, then tells
-            // the builder to edit it in place. Checked first because an absent
-            // template is the cause the checks below can only report symptoms of.
-            const templatePath = join(state.versionDir, "report.html.j2");
-            let hasTemplate;
-            try {
-                hasTemplate = (await stat(templatePath)).isFile();
-            }
-            catch {
-                hasTemplate = false;
-            }
-            if (!hasTemplate) {
-                problems.push("report.html.j2 is missing — a report is authored as report.html.j2 and " +
-                    "rendered into index.html by build_report; a hand-written index.html is " +
-                    "not a report. Write the template, then call build_report.");
-            }
-            // 2. index.html exists and is non-empty
-            const indexPath = join(state.versionDir, "index.html");
-            let html;
-            try {
-                const s = await stat(indexPath);
-                if (!s.isFile() || s.size === 0) {
-                    problems.push("index.html is empty or not a regular file");
-                    return ok({ ok: false, problems });
-                }
-                html = await readFile(indexPath, "utf8");
-            }
-            catch {
-                problems.push("index.html does not exist — call build_report first");
-                return ok({ ok: false, problems });
-            }
-            // 3. No unrendered Jinja markers
-            if (UNRENDERED_JINJA.test(html)) {
-                const match = html.match(UNRENDERED_JINJA);
-                problems.push(`unrendered Jinja in output (e.g. ${JSON.stringify(match?.[0] ?? "")}); ` +
-                    "build_report likely failed silently or report.html.j2 was edited after build");
-            }
-            // 4. Asset reference resolution
-            const refs = extractLocalRefs(html);
-            for (const ref of refs) {
-                const resolved = resolveLocalRef(ref, state.versionDir, state.assetsDir);
-                if (!resolved) {
-                    problems.push(`asset reference does not resolve: ${ref}`);
-                    continue;
-                }
-                try {
-                    const s = await stat(resolved);
-                    if (!s.isFile())
-                        problems.push(`asset reference is not a regular file: ${ref}`);
-                }
-                catch {
-                    problems.push(`asset reference missing on disk: ${ref}`);
-                }
-            }
-            if (problems.length === 0) {
-                const notes = (input.notes ?? []).map((n) => n.trim()).filter(Boolean);
-                state.setOutcome({ ok: true, notes });
-                return ok({ ok: true, problems: [] });
-            }
-            return ok({ ok: false, problems });
-        },
-    });
-}
-const SRC_HREF_RE = /\b(?:src|href)\s*=\s*["']([^"']+)["']/gi;
-const FETCH_RE = /\bfetch\s*\(\s*["'`]([^"'`]+)["'`]/gi;
-function extractLocalRefs(html) {
-    const refs = new Set();
-    for (const m of html.matchAll(SRC_HREF_RE))
-        refs.add(m[1]);
-    for (const m of html.matchAll(FETCH_RE))
-        refs.add(m[1]);
-    // Filter to local refs only — drop absolute URLs and data: / blob: schemes.
-    const out = [];
-    for (const ref of refs) {
-        if (/^[a-z][a-z0-9+.-]*:/i.test(ref))
-            continue; // http:, https:, data:, blob:
-        if (ref.startsWith("//"))
-            continue; // protocol-relative
-        if (ref.startsWith("#"))
-            continue; // anchor
-        out.push(ref);
-    }
-    return out;
-}
-function resolveLocalRef(ref, versionDir, assetsDir) {
-    // Strip leading slash, query string, and fragment.
-    const cleaned = ref.split("?")[0].split("#")[0].replace(/^\/+/, "");
-    if (!cleaned)
-        return undefined;
-    const candidate = resolve(versionDir, cleaned);
-    // The candidate must stay under either versionDir or assetsDir (the
-    // shared assets dir is the symlink target — both are valid roots).
-    const inVersion = candidate.startsWith(versionDir + sep) || candidate === versionDir;
-    const inAssets = candidate.startsWith(assetsDir + sep) || candidate === assetsDir;
-    if (!inVersion && !inAssets)
-        return undefined;
-    return candidate;
-}

package/dist/tools/report/version-fs.d.ts

@@ -1,15 +0,0 @@
-/**
- * In-process workspace surface for the report-builder agent.
- *
- * Tight read/write/mkdir surface scoped to the version directory.
- * Agent-supplied paths are relative to `versionDir`; an absolute path, or one
- * that escapes the directory, is rejected as `out_of_scope`. Constructed
- * inside the iterate-report runner so it always shares the same `versionDir`
- * as the rest of the report tools.
- */
-import { type Tool } from "../define-tool.js";
-export interface VersionFsToolsState {
-    /** Absolute path to the version directory. All paths resolve under this. */
-    readonly versionDir: string;
-}
-export declare function createVersionFsTools(state: VersionFsToolsState): Tool[];

package/dist/tools/report/version-fs.js

@@ -1,165 +0,0 @@
-/**
- * In-process workspace surface for the report-builder agent.
- *
- * Tight read/write/mkdir surface scoped to the version directory.
- * Agent-supplied paths are relative to `versionDir`; an absolute path, or one
- * that escapes the directory, is rejected as `out_of_scope`. Constructed
- * inside the iterate-report runner so it always shares the same `versionDir`
- * as the rest of the report tools.
- */
-import { mkdir as fsMkdir, readFile as fsReadFile, stat as fsStat, writeFile as fsWriteFile } from "node:fs/promises";
-import { dirname, resolve as resolvePath, sep } from "node:path";
-import { ok } from "neverthrow";
-import { z } from "zod";
-import { defineTool } from "../define-tool.js";
-const MAX_READ_BYTES = 256 * 1024;
-const MAX_WRITE_BYTES = 1 * 1024 * 1024;
-/** Resolve an agent-supplied path against `versionDir`, rejecting escapes. */
-function resolveAgentPath(agentPath, versionDir) {
-    if (agentPath.length === 0 || agentPath.includes("\0")) {
-        return { kind: "out_of_scope", reason: "empty or null-byte path" };
-    }
-    // A leading slash is refused rather than trimmed. Trimming it makes the
-    // containment check below unreachable for absolute paths: a deep one such
-    // as "/previews/abc/v1/report.html.j2" would land a real file several
-    // directories below versionDir and report success, and the builder — which
-    // has no directory-listing tool — cannot find where its template went.
-    if (agentPath.startsWith("/")) {
-        return { kind: "out_of_scope", reason: `absolute path rejected, use one relative to the version dir: ${agentPath}` };
-    }
-    const absolute = resolvePath(versionDir, agentPath);
-    if (absolute !== versionDir && !absolute.startsWith(versionDir + sep)) {
-        return { kind: "out_of_scope", reason: `path escapes version dir: ${agentPath}` };
-    }
-    return { kind: "ok", absolute };
-}
-export function createVersionFsTools(state) {
-    const writeFile = defineTool({
-        id: "write_file",
-        description: "Write a UTF-8 text file under the report's version directory. Paths " +
-            "are relative to it (e.g. `report.html.j2`, `assets/foo.csv`); an " +
-            "absolute path, or one that escapes the version dir, returns " +
-            "`out_of_scope` and writes nothing.",
-        inputSchema: z.object({
-            path: z.string().min(1),
-            content: z.string(),
-        }),
-        describeCall: "none",
-        execute: async ({ path, content }) => {
-            const resolved = resolveAgentPath(path, state.versionDir);
-            if (resolved.kind === "out_of_scope") {
-                return ok({ status: "out_of_scope", reason: resolved.reason });
-            }
-            const bytes = Buffer.byteLength(content, "utf8");
-            if (bytes > MAX_WRITE_BYTES) {
-                return ok({
-                    status: "too_large",
-                    reason: `write rejected: ${bytes} bytes exceeds ${MAX_WRITE_BYTES} cap`,
-                });
-            }
-            await fsMkdir(dirname(resolved.absolute), { recursive: true });
-            await fsWriteFile(resolved.absolute, content, "utf8");
-            return ok({ status: "ok", bytesWritten: bytes });
-        },
-    });
-    const editFile = defineTool({
-        id: "edit_file",
-        description: "Surgical edit of an existing UTF-8 file inside the report's version " +
-            "directory: replace the first occurrence of `oldText` with `newText`. " +
-            "Paths are relative to that directory; an absolute or escaping path " +
-            "returns `out_of_scope`. Returns `not_found` if the file doesn't " +
-            "exist, `no_match` if `oldText` isn't present.",
-        inputSchema: z.object({
-            path: z.string().min(1),
-            oldText: z.string().min(1),
-            newText: z.string(),
-        }),
-        describeCall: "none",
-        execute: async ({ path, oldText, newText }) => {
-            const resolved = resolveAgentPath(path, state.versionDir);
-            if (resolved.kind === "out_of_scope") {
-                return ok({ status: "out_of_scope", reason: resolved.reason });
-            }
-            let content;
-            try {
-                content = await fsReadFile(resolved.absolute, "utf8");
-            }
-            catch (err) {
-                if (err.code === "ENOENT") {
-                    return ok({ status: "not_found" });
-                }
-                throw err;
-            }
-            const idx = content.indexOf(oldText);
-            if (idx === -1) {
-                return ok({ status: "no_match" });
-            }
-            const next = content.slice(0, idx) + newText + content.slice(idx + oldText.length);
-            const bytes = Buffer.byteLength(next, "utf8");
-            if (bytes > MAX_WRITE_BYTES) {
-                return ok({
-                    status: "too_large",
-                    reason: `post-edit size ${bytes} bytes exceeds ${MAX_WRITE_BYTES} cap`,
-                });
-            }
-            await fsWriteFile(resolved.absolute, next, "utf8");
-            return ok({ status: "ok", bytesWritten: bytes });
-        },
-    });
-    const readFile = defineTool({
-        id: "read_file",
-        description: "Read a UTF-8 file inside the report's version directory. Paths are " +
-            "relative to it; an absolute or escaping path returns `out_of_scope`. " +
-            "Returns truncated content (capped at 256 KiB) for large files.",
-        inputSchema: z.object({
-            path: z.string().min(1),
-        }),
-        describeCall: "none",
-        execute: async ({ path }) => {
-            const resolved = resolveAgentPath(path, state.versionDir);
-            if (resolved.kind === "out_of_scope") {
-                return ok({ status: "out_of_scope", reason: resolved.reason });
-            }
-            let st;
-            try {
-                st = await fsStat(resolved.absolute);
-            }
-            catch (err) {
-                if (err.code === "ENOENT") {
-                    return ok({ status: "not_found" });
-                }
-                throw err;
-            }
-            if (!st.isFile()) {
-                return ok({ status: "not_found" });
-            }
-            const buf = await fsReadFile(resolved.absolute);
-            const truncated = buf.length > MAX_READ_BYTES;
-            const sliced = truncated ? buf.subarray(0, MAX_READ_BYTES) : buf;
-            return ok({
-                status: "ok",
-                content: sliced.toString("utf8"),
-                truncated,
-                totalBytes: st.size,
-            });
-        },
-    });
-    const mkdir = defineTool({
-        id: "mkdir",
-        description: "Create a directory (recursive) inside the report's version directory. " +
-            "Paths are relative to it; an absolute or escaping path returns `out_of_scope`.",
-        inputSchema: z.object({
-            path: z.string().min(1),
-        }),
-        describeCall: "none",
-        execute: async ({ path }) => {
-            const resolved = resolveAgentPath(path, state.versionDir);
-            if (resolved.kind === "out_of_scope") {
-                return ok({ status: "out_of_scope", reason: resolved.reason });
-            }
-            await fsMkdir(resolved.absolute, { recursive: true });
-            return ok({ status: "ok" });
-        },
-    });
-    return [writeFile, editFile, readFile, mkdir];
-}