@inflexa-ai/harness 0.22.1 → 0.24.0

package/dist/tools/start-report-session.js

@@ -167,13 +167,23 @@ export function createStartReportSessionTool(deps) {
                 }
             }
             const spawned = await spawn.spawnReportSession(parentThreadId, brief);
-            return ok(spawned.match((child) => ({ outcome: "started", threadId: child.threadId, title: child.title }), (fault) => {
-                const outcome = toOutcome(fault);
-                if (outcome.outcome === "failed") {
-                    logger.warn("the report session did not start", { parentThreadId, reason: fault.type, ...logger.errorFields(causeOf(fault)) });
-                }
-                return outcome;
-            }));
+            if (spawned.isOk()) {
+                const child = spawned.value;
+                // The part rides the started arm only. The existing-session arm
+                // names a session that an earlier turn announced, thus a second
+                // part would put a second entry into the transcript.
+                await ctx.emit({
+                    type: "data-child-session-started",
+                    data: { threadId: child.threadId, parentThreadId, threadType: "report" },
+                });
+                return ok({ outcome: "started", threadId: child.threadId, title: child.title });
+            }
+            const fault = spawned.error;
+            const outcome = toOutcome(fault);
+            if (outcome.outcome === "failed") {
+                logger.warn("the report session did not start", { parentThreadId, reason: fault.type, ...logger.errorFields(causeOf(fault)) });
+            }
+            return ok(outcome);
         },
     });
 }

package/dist/workspace/paths.d.ts

@@ -159,27 +159,6 @@ export declare function tailWritePrefix(args: {
  * a step briefing names (see the harness-workspace-tools spec).
  */
 export declare function toSandboxPath(workspaceRoot: string, resourceId: string, hostAbsPath: string): string;
-/**
- * Parent of every preview, workspace-root-relative. Callers that enumerate
- * previews join this; callers that address one join {@link previewDir}. Both
- * spell the segment through this constant so the tree has one owner.
- */
-export declare const PREVIEWS_ROOT = "previews";
-/**
- * Versioned preview directory, workspace-root-relative. Previews live inside
- * the analysis tree (`previews/{previewId}/v{N}`); the content-token `res`
- * claim keeps the separate `previews/{analysisId}/{previewId}` formula in
- * `contracts/content-url.ts` — that is URL space, not a filesystem sub-path,
- * and hosts that serve previews map one onto the other themselves.
- */
-export declare function previewVersionDir(previewId: string, version: number): string;
-/** Preview root for a specific preview (all versions), workspace-root-relative. */
-export declare function previewDir(previewId: string): string;
-/**
- * Find the highest version number from a list of version directory names.
- * Expects names like "v1", "v2", etc. Returns 0 if no versions found.
- */
-export declare function latestPreviewVersion(dirNames: string[]): number;
 /**
  * Parent of every report session, workspace-root-relative. Callers that
  * enumerate the sessions join this. Callers that address one join

package/dist/workspace/paths.js

@@ -151,43 +151,6 @@ export function toSandboxPath(workspaceRoot, resourceId, hostAbsPath) {
     }
     return tail === "" ? `/${resourceId}` : `/${resourceId}/${tail}`;
 }
-/**
- * Parent of every preview, workspace-root-relative. Callers that enumerate
- * previews join this; callers that address one join {@link previewDir}. Both
- * spell the segment through this constant so the tree has one owner.
- */
-export const PREVIEWS_ROOT = "previews";
-/**
- * Versioned preview directory, workspace-root-relative. Previews live inside
- * the analysis tree (`previews/{previewId}/v{N}`); the content-token `res`
- * claim keeps the separate `previews/{analysisId}/{previewId}` formula in
- * `contracts/content-url.ts` — that is URL space, not a filesystem sub-path,
- * and hosts that serve previews map one onto the other themselves.
- */
-export function previewVersionDir(previewId, version) {
-    return `${previewDir(previewId)}/v${version}`;
-}
-/** Preview root for a specific preview (all versions), workspace-root-relative. */
-export function previewDir(previewId) {
-    assertSafeId(previewId, "previewId");
-    return `${PREVIEWS_ROOT}/${previewId}`;
-}
-/**
- * Find the highest version number from a list of version directory names.
- * Expects names like "v1", "v2", etc. Returns 0 if no versions found.
- */
-export function latestPreviewVersion(dirNames) {
-    let max = 0;
-    for (const name of dirNames) {
-        const match = name.match(/^v(\d+)$/);
-        if (match) {
-            const n = parseInt(match[1], 10);
-            if (n > max)
-                max = n;
-        }
-    }
-    return max;
-}
 /**
  * Parent of every report session, workspace-root-relative. Callers that
  * enumerate the sessions join this. Callers that address one join

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.22.1",
+    "version": "0.24.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -76,7 +76,6 @@
         "mime": "^4.1.0",
         "nanoid": "^5.1.16",
         "neverthrow": "^8.2.0",
-        "nunjucks": "^3.2.4",
         "openai": "^7.4.0",
         "p-queue": "^9.3.3",
         "pdf-parse": "^2.4.5",
@@ -89,7 +88,6 @@
         "@types/bun": "latest",
         "@types/dockerode": "^3.3.47",
         "@types/node": "^24.13.3",
-        "@types/nunjucks": "^3.2.6",
         "@types/pdf-parse": "^1.1.5",
         "@types/pg": "^8.20.0",
         "csstree-validator": "^4.0.1",

package/dist/agents/report-builder.d.ts

@@ -1,34 +0,0 @@
-/**
- * Report Builder Agent — in-process templating agent (no sandbox).
- *
- * Authors HTML reports via Jinja2 templating. Runs in the Cortex Node
- * process — file IO is in-process via the `versionFs` tool roster, rendering
- * is Node-side via Nunjucks (`build_report` tool), and visual validation
- * uses headless Chrome via the `preview_snapshot` tool.
- *
- * The agent receives a complete brief from iterate-report's pre-flight
- * (assets staged, columns parsed, sections fully composed) and has no
- * discovery surface — its workspace is rooted at the version directory.
- *
- * NOT a sandbox-agent catalog member (per design Decision #2 — not
- * plannable). The full tool roster is constructed inside the runner so
- * each tool shares the runner's closure-captured outcome state and
- * preview-dir paths; this factory just packages the result into a plain
- * `AgentDefinition`.
- */
-import type { AgentDefinition } from "../loop/types.js";
-import type { Tool } from "../tools/define-tool.js";
-export declare const REPORT_BUILDER_AGENT_ID = "report-builder";
-/** Skill pack the report-builder prompt directs the model to read (design-system reference). */
-export declare const REPORT_BUILDER_SKILLS: readonly ["report-html"];
-export interface CreateReportBuilderAgentDeps {
-    /** Model id — provenance / metric label; the provider owns the wire model. */
-    readonly model: string;
-    /**
-     * Full tool roster — the 4 custom report tools plus the in-process
-     * versionFs surface, all constructed inside the runner so they close
-     * over the iteration's outcome state and preview-dir paths.
-     */
-    readonly tools: readonly Tool[];
-}
-export declare function createReportBuilderAgent(deps: CreateReportBuilderAgentDeps): AgentDefinition;

package/dist/agents/report-builder.js

@@ -1,34 +0,0 @@
-/**
- * Report Builder Agent — in-process templating agent (no sandbox).
- *
- * Authors HTML reports via Jinja2 templating. Runs in the Cortex Node
- * process — file IO is in-process via the `versionFs` tool roster, rendering
- * is Node-side via Nunjucks (`build_report` tool), and visual validation
- * uses headless Chrome via the `preview_snapshot` tool.
- *
- * The agent receives a complete brief from iterate-report's pre-flight
- * (assets staged, columns parsed, sections fully composed) and has no
- * discovery surface — its workspace is rooted at the version directory.
- *
- * NOT a sandbox-agent catalog member (per design Decision #2 — not
- * plannable). The full tool roster is constructed inside the runner so
- * each tool shares the runner's closure-captured outcome state and
- * preview-dir paths; this factory just packages the result into a plain
- * `AgentDefinition`.
- */
-import { reportBuilderPrompt } from "../prompts/report-builder.js";
-import { composeSystemPrompt } from "./system-prompt.js";
-export const REPORT_BUILDER_AGENT_ID = "report-builder";
-/** Skill pack the report-builder prompt directs the model to read (design-system reference). */
-export const REPORT_BUILDER_SKILLS = ["report-html"];
-/** Runaway guard — Jinja recovery may take several build/edit cycles. */
-const REPORT_BUILDER_MAX_ITERATIONS = 75;
-export function createReportBuilderAgent(deps) {
-    return {
-        id: REPORT_BUILDER_AGENT_ID,
-        systemPrompt: composeSystemPrompt(reportBuilderPrompt),
-        model: deps.model,
-        tools: deps.tools,
-        maxIterations: REPORT_BUILDER_MAX_ITERATIONS,
-    };
-}

package/dist/execution/report-render.d.ts

@@ -1,39 +0,0 @@
-/**
- * Report renderer — Node-side Nunjucks render of v{N}/report.html.j2 to v{N}/index.html.
- *
- * Stateless pure module: no harness imports, no env reads at import time,
- * safe to run standalone in tests.
- */
-export interface RenderReportOptions {
-    versionDir: string;
-    templatesDir: string;
-}
-export interface RenderReportResult {
-    ok: boolean;
-    indexBytes: number;
-    error?: {
-        kind: "missing-template" | "syntax" | "runtime";
-        message: string;
-        line?: number;
-        snippet?: string;
-    };
-}
-/**
- * Render `${versionDir}/report.html.j2` to `${versionDir}/index.html`.
- *
- * Loader resolution order: [versionDir, templatesDir]. `report.html.j2`
- * lives in versionDir; `extends "base.html.j2"` and `include "components/..."`
- * resolve from templatesDir. Autoescape is OFF — templates own escaping.
- *
- * `${templatesDir}/echarts-theme.json` is read, parsed, re-stringified, and
- * passed as `echarts_theme` (a JSON string) for safe inlining inside a
- * `<script>` block.
- *
- * Returns `{ ok: true, indexBytes }` on success. On failure, returns
- * `{ ok: false, indexBytes: 0, error }` with `error.kind`:
- *   - "missing-template" — `report.html.j2` (or any `extends`/`include` target)
- *      not found by either loader. Message identifies the missing path.
- *   - "syntax" — Nunjucks parse error in any loaded template.
- *   - "runtime" — anything else thrown during render or write.
- */
-export declare function renderReport(opts: RenderReportOptions): Promise<RenderReportResult>;

package/dist/execution/report-render.js

@@ -1,98 +0,0 @@
-/**
- * Report renderer — Node-side Nunjucks render of v{N}/report.html.j2 to v{N}/index.html.
- *
- * Stateless pure module: no harness imports, no env reads at import time,
- * safe to run standalone in tests.
- */
-import { readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import nunjucks from "nunjucks";
-/**
- * Render `${versionDir}/report.html.j2` to `${versionDir}/index.html`.
- *
- * Loader resolution order: [versionDir, templatesDir]. `report.html.j2`
- * lives in versionDir; `extends "base.html.j2"` and `include "components/..."`
- * resolve from templatesDir. Autoescape is OFF — templates own escaping.
- *
- * `${templatesDir}/echarts-theme.json` is read, parsed, re-stringified, and
- * passed as `echarts_theme` (a JSON string) for safe inlining inside a
- * `<script>` block.
- *
- * Returns `{ ok: true, indexBytes }` on success. On failure, returns
- * `{ ok: false, indexBytes: 0, error }` with `error.kind`:
- *   - "missing-template" — `report.html.j2` (or any `extends`/`include` target)
- *      not found by either loader. Message identifies the missing path.
- *   - "syntax" — Nunjucks parse error in any loaded template.
- *   - "runtime" — anything else thrown during render or write.
- */
-export async function renderReport(opts) {
-    const { versionDir, templatesDir } = opts;
-    let echartsThemeJson;
-    try {
-        const raw = await readFile(join(templatesDir, "echarts-theme.json"), "utf8");
-        echartsThemeJson = JSON.stringify(JSON.parse(raw));
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        const kind = isNotFound(err) ? "missing-template" : "runtime";
-        return {
-            ok: false,
-            indexBytes: 0,
-            error: { kind, message: `failed to load echarts-theme.json: ${msg}` },
-        };
-    }
-    const env = new nunjucks.Environment(new nunjucks.FileSystemLoader([versionDir, templatesDir], {
-        noCache: true,
-    }), { autoescape: false, throwOnUndefined: false });
-    let html;
-    try {
-        html = env.render("report.html.j2", { echarts_theme: echartsThemeJson });
-    }
-    catch (err) {
-        return { ok: false, indexBytes: 0, error: classifyNunjucksError(err) };
-    }
-    try {
-        const indexPath = join(versionDir, "index.html");
-        await writeFile(indexPath, html, "utf8");
-        return { ok: true, indexBytes: Buffer.byteLength(html, "utf8") };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            ok: false,
-            indexBytes: 0,
-            error: { kind: "runtime", message: `failed to write index.html: ${msg}` },
-        };
-    }
-}
-function isNotFound(err) {
-    if (!err || typeof err !== "object")
-        return false;
-    const code = err.code;
-    return code === "ENOENT";
-}
-function classifyNunjucksError(err) {
-    const message = err instanceof Error ? err.message : String(err);
-    if (/template not found/i.test(message)) {
-        return { kind: "missing-template", message };
-    }
-    // Nunjucks tags parse errors with "Template render error" + "expected" /
-    // "unexpected" / "parseError" markers; the Template error carries lineno.
-    const lineno = err?.lineno;
-    const colno = err?.colno;
-    const line = typeof lineno === "number" ? lineno : undefined;
-    const isSyntax = /parseError|expected|unexpected token|unexpected end of/i.test(message) || /Template render error.*line \d+/i.test(message);
-    if (isSyntax) {
-        const snippet = extractSnippet(message, line, typeof colno === "number" ? colno : undefined);
-        return snippet ? { kind: "syntax", message, line, snippet } : line !== undefined ? { kind: "syntax", message, line } : { kind: "syntax", message };
-    }
-    return line !== undefined ? { kind: "runtime", message, line } : { kind: "runtime", message };
-}
-function extractSnippet(message, line, col) {
-    if (!line)
-        return undefined;
-    const m = message.split("\n").find((l) => l.trim().length > 0 && !/^\s*at\s/.test(l));
-    if (!m)
-        return undefined;
-    return col !== undefined ? `${m} (col ${col})` : m;
-}

package/dist/execution/report-runner.d.ts

@@ -1,111 +0,0 @@
-/**
- * Report runner — orchestrates an iterative report build entirely in the
- * Cortex Node process. No sandbox, no Python.
- *
- * Lifecycle:
- *  1. Resolve version (latest + 1, or baseVersion + 1)
- *  2. Prepare version dir (mkdir, copy v{base}/report.html.j2, symlink ../assets)
- *  3. Construct the 4 custom report tools + the in-process versionFs surface;
- *     all of them close over the iteration's preview-dir state and a single
- *     `outcome: ReportOutcome | undefined` variable (the closure-state
- *     closure-state capture — see design.md Decision #9, mirrors
- *     `harness/tools/research/generate-plan.ts`'s
- *     `PlannerOutcome` capture).
- *  4. Build the `report-builder` AgentDefinition with that tool roster and
- *     drive it via `runAgent` + `passthroughStep`.
- *  5. Verify the closure-captured `outcome` is `{ ok: true, ... }` (else
- *     classify the failure, roll back the version dir, return a structured
- *     failure).
- *  6. Return success or a structured failure.
- *
- * Concurrency: per-previewId serialization via `withPreviewLock` so two
- * iterations on the same preview don't race on shared assets/.
- *
- * Billing: the report-builder's LLM calls flow through the `ChatProvider`
- * seam with `forSubAgent(session, REPORT_BUILDER_AGENT_ID)` — the provider's
- * lazy `resolveBilling` fires at the call site. No ALS, no fetch-patch
- * (Decision #6).
- *
- * Preview surface: the `preview_snapshot` and `mint_preview_url` tools mint
- * a content-server URL through the injected `PreviewPublisher` seam. The
- * managed publisher owns the short-lived host credential; the local default
- * returns "unavailable" so the report still builds without a hosted preview.
- */
-import type { Pool } from "pg";
-import { type RequestSession } from "../auth/types.js";
-import type { EmitFn } from "../loop/types.js";
-import type { ChatProvider } from "../providers/types.js";
-import type { PreviewPublisher } from "../tools/report/preview-publisher.js";
-import type { ChromeConfig } from "../lib/chrome.js";
-import type { Logger } from "../lib/logger.js";
-import type { UsageRecorder } from "../billing/usage-recorder.js";
-import type { AgentRunUsage } from "../loop/metrics.js";
-export interface ReportRunnerDeps {
-    /** Operational logging seam; omitted falls back to no-op. */
-    readonly logger?: Logger;
-    readonly provider: ChatProvider;
-    readonly pool: Pool;
-    /** Model id — provenance / metric label; provider owns the wire model. */
-    readonly model: string;
-    /** Root templates dir; `report-html` is joined onto it. */
-    readonly templatesDir: string;
-    /** Skills root; the report-builder gets read-only `report-html` skill tools. */
-    readonly skillsDir: string;
-    readonly chrome: ChromeConfig;
-    /** LLM usage-accounting seam for the report-builder loop; omitted falls back to the no-op recorder. */
-    readonly usageRecorder?: UsageRecorder;
-}
-export interface ReportRunnerOptions {
-    readonly resourceId: string;
-    /** Absolute host root of the analysis's workspace tree (previews live inside it). */
-    readonly workspaceRoot: string;
-    readonly previews: PreviewPublisher;
-    /** Preview group ID. Auto-generated by the tool layer if not provided. */
-    readonly previewId: string;
-    /** Base version to iterate from. Defaults to latest. */
-    readonly baseVersion?: number;
-    /**
-     * Format the preview was built as. The tool boundary admits only `"html"`,
-     * so no other value can reach a live iteration; the union stays wide because
-     * previews persisted with a broader vocabulary must still parse. Read this
-     * field as a record of what a preview is, not as a request for a renderer.
-     */
-    readonly format: "html" | "pdf";
-    /** Prompt for the report-builder agent. */
-    readonly prompt: string;
-    /** Live chat session — derives the child agent's session via forSubAgent. */
-    readonly session: RequestSession;
-    /** Cancellation signal — propagates to the agent stream. */
-    readonly signal: AbortSignal;
-    /** Event sink — forwarded to the agent loop. */
-    readonly emit: EmitFn;
-    /**
-     * The calling turn's usage accumulator (`ctx.turnUsage`), so the
-     * report-builder loop's tokens land in the turn total its root reports.
-     */
-    readonly turnUsage?: AgentRunUsage;
-    /**
-     * The dispatching tool call's id (`ctx.invocationId`), which discriminates
-     * the builder loop's usage record keys from those of a sibling iteration
-     * dispatched in the same round — same frame, same call path, same
-     * loop-local step names.
-     */
-    readonly invocationId?: string;
-}
-export type ReportRunnerResult = {
-    ok: true;
-    previewId: string;
-    version: number;
-    previewPath: string;
-    durationMs: number;
-    /** Caveats surfaced by the agent via submit_report. */
-    notes: readonly string[];
-} | {
-    ok: false;
-    previewId: string;
-    version: number;
-    reason: string;
-    errorKind: "render" | "submit" | "build" | "timeout" | "internal";
-    durationMs: number;
-};
-export declare function runReportIteration(deps: ReportRunnerDeps, opts: ReportRunnerOptions): Promise<ReportRunnerResult>;