@inflexa-ai/harness 0.7.2 → 0.9.0

package/dist/tools/iterate-report.js

@@ -42,15 +42,15 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { scopeResource } from "../auth/types.js";
 import { defineTool } from "./define-tool.js";
-import { previewDir } from "../workspace/paths.js";
+import { latestPreviewVersion, previewDir } from "../workspace/paths.js";
 import { runReportIteration } from "../execution/report-runner.js";
 import { formatBytes, stageReportAssets } from "./lib/report-preflight.js";
 import { createNoopLogger } from "../lib/console-logger.js";
-import { hintForZodIssue } from "../lib/zod-issues.js";
+import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 const REPORT_TOOL_ACCESS_TTL_SECONDS = 3600;
 const PREVIEW_META_FILE = "preview-meta.json";
 async function readPreviewMeta(metaPath) {
@@ -285,7 +285,7 @@ export const submitReportInputSchema = z
         .min(1)
         .optional()
         .describe("Version to branch from (1-based) — use when the user prefers an earlier version. Defaults to the latest."),
-    format: z.enum(["html", "pdf"]).default("html").describe("Output format. Defaults to 'html' — only set explicitly for PDF."),
+    format: z.enum(["html"]).default("html").describe("Output format. HTML is the only format the report path produces; you can leave this unset."),
     report: z
         .unknown()
         .optional()
@@ -309,6 +309,22 @@ export const submitReportInputSchema = z
 })
     .refine((data) => !(data.report !== undefined && data.sources), {
     message: "Top-level `sources` is for iteration mode. For creation, put sources inside the brief's `sources`.",
+})
+    // `baseVersion` names a version to branch from, and a creation call has
+    // none. Left admissible it is not inert: the base-existence guard below is
+    // scoped to iteration, so the value reaches the runner unchecked and numbers
+    // a brand-new report `v{baseVersion + 1}`.
+    .refine((data) => !(data.report !== undefined && data.baseVersion !== undefined), {
+    message: "`baseVersion` is for iteration mode — a new report has no earlier version to branch from. " +
+        "To build on an existing version, pass `modifications` plus that report's `previewId` instead of a `report` brief.",
+})
+    // `previewId` names the report the change text applies to. Without one there
+    // is nothing to iterate, and the tool would mint a fresh id — an id the
+    // caller never chose, which its own refusal would then quote back as though
+    // it were a real report worth retrying against.
+    .refine((data) => !(data.modifications !== undefined && data.previewId === undefined), {
+    message: "Iterating with `modifications` requires the `previewId` of the report to change — take it from that report's preview card. " +
+        "To build a new report instead, pass a `report` brief and no `previewId`.",
 });
 // ── plan_report: the just-in-time authoring contract ────────────────
 /**
@@ -402,6 +418,38 @@ export const planReportTool = defineTool({
         rules: REPORT_AUTHORING_RULES,
     }),
 });
+/**
+ * Validate a submitted brief, first repairing one that arrived double-encoded.
+ *
+ * Every other committing tool (`submit_plan`, `submit_synthesis`) puts its real
+ * schema on the wire, so a JSON-encoded argument fails the tool's input schema and
+ * the agent loop's issue-guided repair pass catches it before `execute` ever runs.
+ * `report` rides as `z.unknown()` to keep the ~12k brief schema off the always-on
+ * tool surface — which also means a double-encoded brief *satisfies* the input
+ * schema, the loop sees no failure to act on, and the repair never fires. That
+ * makes this the one committing path where the brief must be repaired locally.
+ *
+ * When the brief decodes but is then invalid, the issues reported are the decoded
+ * value's, not the encoding error's — once the string has been parsed, "expected
+ * object, received string" describes a problem this function already solved, and
+ * would send the model chasing it instead of the fields actually missing. A brief
+ * that does not decode at all keeps its original failure.
+ *
+ * `validated` is the value the returned issues are addressed to, which is the
+ * repaired brief whenever repair happened. An issue's `path` indexes into that
+ * value alone, so a diagnostic that walks the path — `hintForZodIssue` — must be
+ * handed the same value; walking a decoded field's path into the still-encoded
+ * original resolves nothing and silently yields no hint.
+ */
+function acceptBrief(report) {
+    const direct = ReportBriefSchema.safeParse(report);
+    if (direct.success)
+        return { parsed: direct, validated: report };
+    const repaired = repairToolInput(report, direct.error);
+    if (repaired === undefined)
+        return { parsed: direct, validated: report };
+    return { parsed: ReportBriefSchema.safeParse(repaired), validated: repaired };
+}
 /**
  * `submit_report` — takes the composed brief and drives the report iteration.
  * On a valid brief its behaviour is byte-for-byte the former `iterate_report`:
@@ -412,7 +460,7 @@ export const planReportTool = defineTool({
 export function createReportSubmitTool(deps) {
     return defineTool({
         id: "submit_report",
-        description: "Submit a composed report brief to build or iterate an HTML/PDF report " +
+        description: "Submit a composed report brief to build or iterate an HTML report " +
             "(the report-builder renders it; it never sees the analysis tree). Call " +
             "`plan_report` FIRST to get the brief schema + authoring rules, compose " +
             "the brief, then call this. CREATE: pass `report` (the composed brief), " +
@@ -429,14 +477,14 @@ export function createReportSubmitTool(deps) {
             // (the validate_plan trade) — never a thrown error.
             let brief;
             if (input.report !== undefined) {
-                const parsed = ReportBriefSchema.safeParse(input.report);
+                const { parsed, validated } = acceptBrief(input.report);
                 if (!parsed.success) {
                     return ok({
                         ok: false,
                         issues: parsed.error.issues.map((i) => ({
                             path: i.path.join(".") || "(root)",
                             message: i.message,
-                            hint: hintForZodIssue(i, input.report),
+                            hint: hintForZodIssue(i, validated),
                         })),
                         hint: "The `report` brief did not match the schema. Call `plan_report` for the full schema, fix the fields named in `issues`, and resubmit.",
                     });
@@ -445,13 +493,79 @@ export function createReportSubmitTool(deps) {
             }
             const { resourceId } = scopeResource(ctx.session.scope);
             const analysisRoot = deps.resolveWorkspaceRoot(resourceId);
-            // Zod fills the default at parse time but the static type keeps it
-            // optional — re-apply so the runner sees a concrete value.
-            const format = input.format ?? "html";
+            const format = input.format;
             const previewId = input.previewId ?? `prv-${randomUUID().slice(0, 8)}`;
             const previewRootAbs = join(analysisRoot, previewDir(previewId));
             const assetsDirAbs = join(previewRootAbs, "assets");
             const metaPathAbs = join(previewRootAbs, PREVIEW_META_FILE);
+            // Iteration carries no brief: the builder's entire input is the change
+            // text plus the base version's template. A base that is not on disk
+            // therefore hands it a change request and nothing to change, and it
+            // authors a fresh version while being told the previous template is
+            // already in its working directory. Two ways to reach that state — a
+            // preview holding no version at all, and a `baseVersion` naming one
+            // that was never written — so the base is resolved here exactly as the
+            // runner resolves it (`baseVersion ?? latest`) and both are refused.
+            // Scoping to iteration is exact, not incidental: the input schema
+            // refuses `baseVersion` alongside a brief, so a creation call carries
+            // no base to resolve.
+            // The check is a directory read and precedes access minting, asset
+            // staging, and the builder, so a bad id costs no model turns and
+            // leaves no partial state.
+            //
+            // A version directory implies its `report.html.j2`, so the directory
+            // read is the whole check and no template stat is needed. What holds
+            // that up is the builder's own finalize gate
+            // (`tools/report/submit-report.ts`), which refuses a version whose
+            // `report.html.j2` is absent; a version the gate never accepted is
+            // never recorded, and the runner removes the directory it created.
+            // Relaxing that gate is what would make this check insufficient.
+            //
+            // The read may also sit outside `withPreviewLock`: nothing in the
+            // report path removes an existing version, so a concurrent iteration
+            // can only add, and a base seen here is still there when the runner
+            // takes the lock. Introducing version deletion makes that ordering
+            // load-bearing.
+            if (!brief) {
+                let versionDirs = [];
+                try {
+                    versionDirs = (await readdir(previewRootAbs, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+                }
+                catch {
+                    /* no preview root — indistinguishable from one holding no versions */
+                }
+                const latestVersion = latestPreviewVersion(versionDirs);
+                let reason;
+                if (latestVersion === 0) {
+                    reason =
+                        `No report exists under previewId '${previewId}', so there is nothing to modify. ` +
+                            "Create the report first by calling `submit_report` with a `report` brief and no `previewId`, " +
+                            "or retry with the `previewId` shown on the preview card of the report you meant to change.";
+                }
+                else if (input.baseVersion !== undefined && !versionDirs.includes(`v${input.baseVersion}`)) {
+                    reason =
+                        `Preview '${previewId}' has no version ${input.baseVersion} to branch from — its latest version is ${latestVersion}. ` +
+                            "Retry with a `baseVersion` that exists, or omit `baseVersion` to branch from the latest version.";
+                }
+                if (reason !== undefined) {
+                    await ctx.emit({
+                        type: "data-report-preview-failed",
+                        data: {
+                            id: randomUUID(),
+                            previewId,
+                            version: 0,
+                            reason,
+                            errorKind: "build",
+                        },
+                    });
+                    return ok({
+                        previewId,
+                        version: 0,
+                        previewPath: "",
+                        error: reason,
+                    });
+                }
+            }
             // Iteration mode: recover the title from the creation-time meta file
             // so the data-report-preview part keeps the original title across versions.
             const existingMeta = brief ? null : await readPreviewMeta(metaPathAbs);
@@ -636,7 +750,7 @@ function buildCreationPrompt(report, format, staged) {
     out.push("Each section below carries `intent` (why it exists, what to emphasize) " +
         "and `content` (the data shape to render). You choose the design-system " +
         "components, layout, alternation, and visual treatment. Stay in the " +
-        "Inflexa Design Blueprint — base.html.j2, components, theme.css.");
+        "Inflexa Design Blueprint — base.html.j2, components.");
     out.push("");
     for (let i = 0; i < report.sections.length; i++) {
         out.push(`### ${i + 1}. ${report.sections[i].title} — type: \`${report.sections[i].type}\``);

package/dist/tools/report/mint-preview-url.d.ts

@@ -10,7 +10,7 @@
  *   - inspecting an older version (pass `version`)
  */
 import { type Tool } from "../define-tool.js";
-import type { PreviewPublisher } from "./preview-publisher.js";
+import { type PreviewPublisher } from "./preview-publisher.js";
 /** Shared, mutable URL cell so mint and preview-snapshot share a cached URL. */
 export interface PreviewUrlCell {
     url: string | undefined;

package/dist/tools/report/mint-preview-url.js

@@ -12,13 +12,15 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { describeMintFailure } from "./preview-publisher.js";
 export function createMintPreviewUrlTool(state) {
     return defineTool({
         id: "mint_preview_url",
-        description: "Mint a fresh preview URL for the report. Returns a content-server " +
-            "URL with embedded auth token (15-min TTL). Use this only when you " +
-            "need a URL for direct browser navigation — preview_snapshot handles " +
-            "the common case automatically.",
+        description: "Mint a fresh preview URL for the report. Returns a time-limited " +
+            "content-server URL with an embedded auth token, alongside the " +
+            "`expiresAt` it is good until. Use this only when you need a URL for " +
+            "direct browser navigation — preview_snapshot handles the common case " +
+            "automatically.",
         inputSchema: z.object({
             version: z.number().optional().describe("Version to mint for. Defaults to the iteration's current version."),
         }),
@@ -28,7 +30,7 @@ export function createMintPreviewUrlTool(state) {
             if (!result.ok) {
                 return ok({
                     ok: false,
-                    error: `preview-access mint failed: status=${result.status} ${result.error.message ?? ""}`.trim(),
+                    error: describeMintFailure(result),
                 });
             }
             const url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${version}/index.html?t=${result.data.token}`;

package/dist/tools/report/preview-publisher.d.ts

@@ -24,6 +24,22 @@ export type PreviewMintResult = {
         message?: string;
     };
 };
+/** The not-ok arm of the seam's result — what a failed mint is allowed to carry. */
+export type PreviewMintFailure = Extract<PreviewMintResult, {
+    ok: false;
+}>;
+/**
+ * Renders a failed mint as the line an agent reads back from a preview tool.
+ *
+ * The failure shape is sparse by design: a realization with no HTTP transport
+ * behind it supplies neither a status nor, necessarily, a message. Naming a
+ * field the seam left unset would put the literal `status=undefined` in front
+ * of the model, so the message carries only what actually arrived. This lives
+ * beside the type because its whole job is to honour that type's optionality —
+ * every tool holding the seam owes the same message, and one of them owning
+ * the wording would make the others depend on a peer for a seam-wide concern.
+ */
+export declare function describeMintFailure(failure: PreviewMintFailure): string;
 export interface PreviewPublisher {
     mintPreviewAccess(resourceId: string, previewId: string): Promise<PreviewMintResult>;
 }

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

@@ -10,6 +10,26 @@
  * returns not-ok, so `preview_snapshot` short-circuits before touching
  * Chrome and the report still builds (submit_report is the only gate).
  */
+/**
+ * Renders a failed mint as the line an agent reads back from a preview tool.
+ *
+ * The failure shape is sparse by design: a realization with no HTTP transport
+ * behind it supplies neither a status nor, necessarily, a message. Naming a
+ * field the seam left unset would put the literal `status=undefined` in front
+ * of the model, so the message carries only what actually arrived. This lives
+ * beside the type because its whole job is to honour that type's optionality —
+ * every tool holding the seam owes the same message, and one of them owning
+ * the wording would make the others depend on a peer for a seam-wide concern.
+ */
+export function describeMintFailure(failure) {
+    const detail = [];
+    if (failure.status !== undefined)
+        detail.push(`status=${failure.status}`);
+    const message = failure.error.message?.trim();
+    if (message)
+        detail.push(message);
+    return detail.length > 0 ? `preview-access mint failed: ${detail.join(" ")}` : "preview-access mint failed";
+}
 /**
  * Local default — no hosted preview surface. Returns not-ok so the preview
  * tools surface a clear "unavailable" message and short-circuit before any

package/dist/tools/report/preview-snapshot.d.ts

@@ -10,10 +10,16 @@
  * 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 { type Tool } from "../define-tool.js";
 import { type ChromeConfig } from "../../lib/chrome.js";
-import type { PreviewPublisher } from "./preview-publisher.js";
+import type { Logger } from "../../lib/logger.js";
+import { type PreviewPublisher } from "./preview-publisher.js";
 import type { PreviewUrlCell } from "./mint-preview-url.js";
 export interface PreviewSnapshotToolState {
     readonly resourceId: string;
@@ -22,5 +28,7 @@ export interface PreviewSnapshotToolState {
     readonly previews: PreviewPublisher;
     readonly urlCell: PreviewUrlCell;
     readonly chrome: ChromeConfig;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
 }
 export declare function createPreviewSnapshotTool(state: PreviewSnapshotToolState): Tool;

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

@@ -10,15 +10,23 @@
  * 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 { withPage } from "../../lib/chrome.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { describeMintFailure } from "./preview-publisher.js";
 const NAV_TIMEOUT_MS = 20_000;
 const READY_TIMEOUT_MS = 8_000;
 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 " +
@@ -48,11 +56,17 @@ export function createPreviewSnapshotTool(state) {
             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: `preview-access mint failed: status=${result.status} ${result.error.message ?? ""}`.trim(),
+                        error: describeMintFailure(result),
                     });
                 }
                 url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${state.currentVersion}/index.html?t=${result.data.token}`;

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

@@ -3,6 +3,7 @@
  * `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

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

@@ -3,6 +3,7 @@
  * `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
@@ -23,26 +24,46 @@ const UNRENDERED_JINJA = /\{\{[^{}]*\}\}|\{%-?\s*\w/;
 export function createSubmitReportTool(state) {
     return defineTool({
         id: "submit_report",
-        description: "Declare the report ready. Validates index.html exists, has no " +
-            "unrendered Jinja, and that all referenced asset paths resolve. " +
+        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. files skipped due " +
-            "to the 50MB asset size limit, sections rendered with partial data, " +
-            "missing inputs that forced a fallback) — these reach the conversation " +
-            "agent and the user in the iteration result.",
+            "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: 'skipped raw_counts.h5ad (1.2GB > 50MB cap)', " +
-                "'pathway-enrichment section omitted — no GSEA output found'. " +
+                "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."),
         }),
         execute: async (input) => {
             const problems = [];
-            // 1. index.html exists and is non-empty
+            // 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 {
@@ -57,13 +78,13 @@ export function createSubmitReportTool(state) {
                 problems.push("index.html does not exist — call build_report first");
                 return ok({ ok: false, problems });
             }
-            // 2. No unrendered Jinja markers
+            // 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");
             }
-            // 3. Asset reference resolution
+            // 4. Asset reference resolution
             const refs = extractLocalRefs(html);
             for (const ref of refs) {
                 const resolved = resolveLocalRef(ref, state.versionDir, state.assetsDir);

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

@@ -2,10 +2,10 @@
  * In-process workspace surface for the report-builder agent.
  *
  * Tight read/write/mkdir surface scoped to the version directory.
- * Agent-supplied paths are resolved against `versionDir`; any path that
- * escapes 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.
+ * 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 {

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

@@ -2,10 +2,10 @@
  * In-process workspace surface for the report-builder agent.
  *
  * Tight read/write/mkdir surface scoped to the version directory.
- * Agent-supplied paths are resolved against `versionDir`; any path that
- * escapes 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.
+ * 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";
@@ -19,13 +19,15 @@ function resolveAgentPath(agentPath, versionDir) {
     if (agentPath.length === 0 || agentPath.includes("\0")) {
         return { kind: "out_of_scope", reason: "empty or null-byte path" };
     }
-    // Strip a leading slash so an agent typing "/index.html" is treated as
-    // "index.html" relative to versionDir (the version dir is the root).
-    const stripped = agentPath.replace(/^\/+/, "");
-    if (!stripped) {
-        return { kind: "out_of_scope", reason: "path resolves to the version dir itself" };
+    // 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, stripped);
+    const absolute = resolvePath(versionDir, agentPath);
     if (absolute !== versionDir && !absolute.startsWith(versionDir + sep)) {
         return { kind: "out_of_scope", reason: `path escapes version dir: ${agentPath}` };
     }
@@ -34,9 +36,10 @@ function resolveAgentPath(agentPath, versionDir) {
 export function createVersionFsTools(state) {
     const writeFile = defineTool({
         id: "write_file",
-        description: "Write a UTF-8 text file under the report's version directory. Use " +
-            "relative paths (e.g. `report.html.j2`, `assets/foo.csv`). Returns " +
-            "`out_of_scope` for any path that escapes the version dir.",
+        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(),
@@ -62,8 +65,9 @@ export function createVersionFsTools(state) {
         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`. " +
-            "Returns `not_found` if the file doesn't exist, `no_match` if " +
-            "`oldText` isn't present.",
+            "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),
@@ -102,7 +106,9 @@ export function createVersionFsTools(state) {
     });
     const readFile = defineTool({
         id: "read_file",
-        description: "Read a UTF-8 file inside the report's version directory. Returns " + "truncated content (capped at 256 KiB) for large files.",
+        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),
         }),
@@ -137,7 +143,8 @@ export function createVersionFsTools(state) {
     });
     const mkdir = defineTool({
         id: "mkdir",
-        description: "Create a directory (recursive) inside the report's version directory.",
+        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),
         }),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.7.2",
+    "version": "0.9.0",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -47,6 +47,7 @@
         "@ai-sdk/anthropic": "^4.0.15",
         "@ai-sdk/openai-compatible": "^3.0.10",
         "@ai-sdk/provider": "^4.0.3",
+        "@ai-sdk/provider-utils": "5.0.10",
         "@anthropic-ai/sdk": "^0.107.0",
         "@dbos-inc/dbos-sdk": "^4.23.6",
         "@kubernetes/client-node": "^1.4.0",