@inflexa-ai/harness 0.19.0 → 0.19.2

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

@@ -6,7 +6,7 @@
  * resolves each reference through the injected resolver, bridges the resolved values into the render model,
  * and renders the page.
  *
- * The page and its staged image assets land in `report-sessions/{threadId}/` under the workspace root. That
+ * The page and its staged assets land in `report-sessions/{threadId}/` under the workspace root. That
  * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
  * trees. The result carries the absolute page path, thus a local host shows the page with no seam.
  *
@@ -15,23 +15,29 @@
  * this tree. A hosted view of a session page is a later capability, with a URL space of its own.
  *
  * Each degraded condition is a typed outcome in the ok channel: a session refusal, a gap list, a resolver
- * absence, an unresolved reference, a bridge mismatch, a render problem, a figure that escapes the
- * workspace root, and a write failure. The tool never throws for one of them. The filesystem speaks the
+ * absence, an unresolvable root at resolver construction, an unresolved reference, a bridge mismatch, a
+ * render problem, a figure that escapes the workspace root, a write failure, and a stamp failure. The tool
+ * never throws for one of them. When the page
+ * lands, the tool stamps the hash of the rendered draft on the session state, thus the eyes and the record
+ * know which draft the page shows. The filesystem speaks the
  * throw protocol, and the workspace-root seam signals an unresolvable resource the same way. Thus the
  * write runs through the `tryFs` glue, which turns a genuine fault into the ok-channel outcome and lets a
  * control-flow exception propagate.
  */
 import { err, ok } from "neverthrow";
 import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { extname, join } from "node:path";
 import { z } from "zod";
 import { resolveWorkspacePath } from "../../workspace/paths.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeFsError, tryFsWrite } from "../../lib/fs-result.js";
 import { defaultErrorFields } from "../../lib/logger.js";
+import { computeDraftHash } from "../../report-model/draft-hash.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
 import { resolveDocumentReferences } from "../../report-model/validate.js";
 import { bridgeValues } from "../../report-render/value-bridge.js";
+import { PAGE_ASSETS } from "../../report-render/assets.js";
 import { renderReportPage } from "../../report-render/render.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
@@ -52,6 +58,13 @@ function assetFileName(file) {
 function figureSourcePolicy(file) {
     return `assets/${assetFileName(file)}`;
 }
+/**
+ * The resolver of a package source. A manifest entry names a module specifier, and the resolution reads
+ * the installation of the harness. Thus the staged bytes are the bytes of the pinned version.
+ */
+const moduleResolver = createRequire(import.meta.url);
+/** The default asset lookup: the module resolution of the installation of the harness. */
+const resolvePageAssetFromInstallation = (specifier) => moduleResolver.resolve(specifier);
 /**
  * Pair each block with the resolved value of its binding, in document order.
  *
@@ -112,7 +125,7 @@ async function resolveDocument(document, resolver, snapshot) {
     return { resolutions: collectResolutions(document.sections, resolvedByBlock), unresolved: [] };
 }
 /**
- * Resolve the page root, stage each bound image, and write the page.
+ * Resolve the page root, stage each bound image and each manifest entry, and write the page.
  *
  * The workspace-root seam signals an unresolvable resource by a throw, thus the resolution sits inside
  * the protection and its throw becomes a value. Each `fs` call runs through `tryFsWrite`, the one
@@ -122,6 +135,10 @@ async function resolveDocument(document, resolver, snapshot) {
  * A bound figure names a snapshot path, which is untrusted. A registered `../../` path escapes the root,
  * thus the containment test runs before any copy and reuses the one workspace-path resolver. A source
  * outside the root refuses and names the block, and no copy runs.
+ *
+ * The page references the chart runtime and the fonts under the same `assets/` directory, thus one copy
+ * loop stages the figures and the manifest entries together. The manifest is never empty, thus the assets
+ * directory exists beside every page.
  */
 async function renderToWorkspace(args) {
     let root;
@@ -151,20 +168,28 @@ async function renderToWorkspace(args) {
         }
         sources.set(name, resolved.absolute);
     }
+    // Each manifest entry, mapped from its staged name to the file that the asset lookup gives. A specifier
+    // that does not resolve is a fault of the installation, thus it rides the `fs` kind.
+    for (const asset of PAGE_ASSETS) {
+        try {
+            sources.set(asset.file, args.resolvePageAsset(asset.specifier));
+        }
+        catch (cause) {
+            return err({ kind: "fs", error: { type: "read_failed", op: "preview.resolveAsset", path: asset.specifier, cause } });
+        }
+    }
     const madeSession = await tryFsWrite("preview.mkdir", () => mkdir(sessionDir, { recursive: true }), { path: sessionDir });
     if (madeSession.isErr()) {
         return err({ kind: "fs", error: madeSession.error });
     }
-    if (sources.size > 0) {
-        const madeAssets = await tryFsWrite("preview.mkdir", () => mkdir(assetsDir, { recursive: true }), { path: assetsDir });
-        if (madeAssets.isErr()) {
-            return err({ kind: "fs", error: madeAssets.error });
-        }
-        for (const [name, source] of sources) {
-            const copied = await tryFsWrite("preview.copyFile", () => copyFile(source, join(assetsDir, name)), { path: source });
-            if (copied.isErr()) {
-                return err({ kind: "fs", error: copied.error });
-            }
+    const madeAssets = await tryFsWrite("preview.mkdir", () => mkdir(assetsDir, { recursive: true }), { path: assetsDir });
+    if (madeAssets.isErr()) {
+        return err({ kind: "fs", error: madeAssets.error });
+    }
+    for (const [name, source] of sources) {
+        const copied = await tryFsWrite("preview.copyFile", () => copyFile(source, join(assetsDir, name)), { path: source });
+        if (copied.isErr()) {
+            return err({ kind: "fs", error: copied.error });
         }
     }
     const wrote = await tryFsWrite("preview.writeFile", () => writeFile(pagePath, args.page, "utf8"), { path: pagePath });
@@ -182,6 +207,7 @@ async function renderToWorkspace(args) {
  */
 export function createPreviewReportTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("preview-report");
+    const resolvePageAsset = deps.resolvePageAsset ?? resolvePageAssetFromInstallation;
     return defineTool({
         id: "preview_report",
         description: "Render the current draft to a self-contained HTML page, and give back the page path. " +
@@ -203,10 +229,21 @@ export function createPreviewReportTool(deps) {
                 return ok({ outcome: "gaps", gaps: finished.gaps });
             }
             const document = finished.document;
-            if (deps.resolver === undefined) {
+            if (deps.makeResolver === undefined) {
                 return ok({ outcome: "resolver-unavailable" });
             }
-            const { resolutions, unresolved } = await resolveDocument(document, deps.resolver, snapshot);
+            // The resolver construction resolves the workspace root inside, and that seam throws on an
+            // unresolvable root. The guard turns the throw into a typed outcome that names the fault, thus a
+            // control-flow exception propagates and the unresolvable root does not.
+            let resolver;
+            try {
+                resolver = deps.makeResolver({ analysisId, auth: ctx.session.auth });
+            }
+            catch (cause) {
+                logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
+                return ok({ outcome: "root-unresolvable", detail: "the workspace root did not resolve" });
+            }
+            const { resolutions, unresolved } = await resolveDocument(document, resolver, snapshot);
             if (unresolved.length > 0) {
                 return ok({ outcome: "unresolved-references", unresolved });
             }
@@ -220,6 +257,7 @@ export function createPreviewReportTool(deps) {
             }
             const written = await renderToWorkspace({
                 resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
+                resolvePageAsset,
                 analysisId,
                 threadId,
                 resolutions,
@@ -239,6 +277,15 @@ export function createPreviewReportTool(deps) {
                 logger.warn("the page did not land", { threadId, analysisId, ...defaultErrorFields(failure.error.cause) });
                 return ok({ outcome: "write-failed", detail: describeFsError(failure.error) });
             }
+            // The page shows the draft that the finish read. The stamp records that draft, thus the eyes
+            // copy this hash and the record compares against it. A failed stamp is a transient store fault,
+            // and the page stays on disk. The agent runs the preview again to stamp the marker.
+            const stamped = await deps.gateway.stampRendered(threadId, computeDraftHash(draft));
+            if (stamped.outcome !== "stamped") {
+                const detail = stamped.outcome === "failed" ? stamped.detail : "the session state row is absent";
+                logger.warn("the rendered hash did not stamp", { threadId, analysisId, detail });
+                return ok({ outcome: "stamp-failed", pagePath: written.value, detail });
+            }
             return ok({ outcome: "rendered", pagePath: written.value });
         },
     });

package/dist/tools/report-session/record-version.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The record tool of a report session.
+ *
+ * The tool records one version of the report. The store is append-only with no delete, thus a version that
+ * the gate did not accept must never exist. The tool runs the whole gate first, and only a pass reaches the
+ * store.
+ *
+ * The gate has three parts, in order of cost. The finish gates the schema, the unique ids, and the
+ * structural tier, and a gap list returns as data. The look-before-record rule then compares the seen hash
+ * against the hash of the current draft, on the state that the load already read. A never-seen page and a
+ * stale look each refuse with a distinct reason, and the rule reads no model judgment. The full validation
+ * resolves every reference through the injected resolver, matches each chart encoding, and matches each
+ * assert. A failure names the block that holds the failed part, thus the agent repairs one block and not the
+ * report at large.
+ *
+ * The look runs before the validation on purpose. The validation builds the resolver and its prepare pass
+ * can start a container, thus the cheap look guards the expensive pass. A never-seen or stale draft refuses
+ * before the resolver constructs.
+ *
+ * On a pass the store records the document that the gate validated, the pinned snapshot, and the anchor from
+ * the thread row. The one-per-thread rule of the store bounds a concurrent race, and that refusal returns as
+ * data. The outcome of a pass carries the version id.
+ */
+import { z } from "zod";
+import type { AuthContext } from "../../auth/types.js";
+import type { Logger } from "../../lib/logger.js";
+import type { ThreadStore } from "../../memory/thread-store.js";
+import { type FinishGap } from "../../report-model/draft-finish.js";
+import type { ReferenceResolver } from "../../report-model/reference-resolver.js";
+import { type ResolutionFailure, type SchemaIssue } from "../../report-model/validate.js";
+import type { ReportVersionStore } from "../../state/report-versions.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool records the current draft of the thread, thus it needs no field. */
+declare const recordVersionInput: z.ZodObject<{}, z.core.$strip>;
+export type RecordVersionInput = z.infer<typeof recordVersionInput>;
+/**
+ * The typed outcome of the record tool. Each arm is ok-channel data, thus the tool never throws for a
+ * degraded condition.
+ *
+ * `gaps` names each completeness gap of the draft. `never-seen` means that no eyes ran on the current draft.
+ * `stale-look` means that the eyes ran, and the agent then changed the draft. `root-unresolvable` means that
+ * the resolver construction cannot resolve the workspace root. `invalid` names each gate failure, and a
+ * resolution failure carries the block that holds it. `already-recorded` means that the thread already holds
+ * a version. `recorded` carries the version id.
+ */
+export type RecordVersionResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "gaps";
+    gaps: FinishGap[];
+} | {
+    outcome: "never-seen";
+} | {
+    outcome: "stale-look";
+} | {
+    outcome: "resolver-unavailable";
+} | {
+    outcome: "root-unresolvable";
+    detail: string;
+} | {
+    outcome: "invalid";
+    schemaIssues?: SchemaIssue[];
+    duplicateIds?: string[];
+    resolutionFailures?: ResolutionFailure[];
+} | {
+    outcome: "already-recorded";
+} | {
+    outcome: "record-failed";
+    detail: string;
+} | {
+    outcome: "recorded";
+    versionId: string;
+};
+/**
+ * The construction deps of the record tool.
+ *
+ * `store` is the append-only version store. `threads` reads the anchor of the report thread, thus the
+ * version carries the parent conversation and the transcript position. `makeResolver` is optional, because a
+ * resolver realization can be absent, and the gate needs one. It binds one analysis, thus the tool makes the
+ * resolver over the scope of the call.
+ */
+export interface RecordVersionToolDeps {
+    readonly gateway: ReportSessionStateGateway;
+    readonly store: ReportVersionStore;
+    readonly threads: Pick<ThreadStore, "getThread">;
+    readonly makeResolver?: (scope: {
+        analysisId: string;
+        auth: AuthContext;
+    }) => ReferenceResolver;
+    readonly logger?: Logger;
+}
+/**
+ * Make the record tool over the session-state gateway, the version store, the thread store, and the
+ * resolver.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the state through the gateway. Thus
+ * one factory serves every thread. The tool holds no per-session value.
+ */
+export declare function createRecordVersionTool(deps: RecordVersionToolDeps): Tool<RecordVersionInput, RecordVersionResult>;
+export {};

package/dist/tools/report-session/record-version.js

@@ -0,0 +1,139 @@
+/**
+ * The record tool of a report session.
+ *
+ * The tool records one version of the report. The store is append-only with no delete, thus a version that
+ * the gate did not accept must never exist. The tool runs the whole gate first, and only a pass reaches the
+ * store.
+ *
+ * The gate has three parts, in order of cost. The finish gates the schema, the unique ids, and the
+ * structural tier, and a gap list returns as data. The look-before-record rule then compares the seen hash
+ * against the hash of the current draft, on the state that the load already read. A never-seen page and a
+ * stale look each refuse with a distinct reason, and the rule reads no model judgment. The full validation
+ * resolves every reference through the injected resolver, matches each chart encoding, and matches each
+ * assert. A failure names the block that holds the failed part, thus the agent repairs one block and not the
+ * report at large.
+ *
+ * The look runs before the validation on purpose. The validation builds the resolver and its prepare pass
+ * can start a container, thus the cheap look guards the expensive pass. A never-seen or stale draft refuses
+ * before the resolver constructs.
+ *
+ * On a pass the store records the document that the gate validated, the pinned snapshot, and the anchor from
+ * the thread row. The one-per-thread rule of the store bounds a concurrent race, and that refusal returns as
+ * data. The outcome of a pass carries the version id.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { describeDbError } from "../../lib/db-result.js";
+import { finishDraft } from "../../report-model/draft-finish.js";
+import { computeDraftHash } from "../../report-model/draft-hash.js";
+import { validateReport } from "../../report-model/validate.js";
+import { defineTool } from "../define-tool.js";
+import { openReportThread } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool records the current draft of the thread, thus it needs no field. */
+const recordVersionInput = z.object({});
+/** A short account of a record refusal, for the detail of a transient failure. */
+function describeRecordFailure(error) {
+    switch (error.type) {
+        case "malformed_document":
+            return "the gate accepted a document that the store read as malformed";
+        case "malformed_snapshot":
+            return "the pinned snapshot is malformed";
+        case "parent_analysis_mismatch":
+            return "the parent version belongs to a different analysis";
+        case "thread_already_holds_version":
+            return "the thread already holds a recorded version";
+        default:
+            return describeDbError(error);
+    }
+}
+/**
+ * Make the record tool over the session-state gateway, the version store, the thread store, and the
+ * resolver.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the state through the gateway. Thus
+ * one factory serves every thread. The tool holds no per-session value.
+ */
+export function createRecordVersionTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("record-report-version");
+    return defineTool({
+        id: "record_report_version",
+        description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
+            "resolves each reference, matches each chart encoding, and matches each assert. An incomplete draft gives back the gap list, " +
+            "and a failed reference gives back the block that broke. The tool records a version only after the eyes look at the current page. " +
+            "A thread holds one version, thus a second record gives back that the thread already holds one.",
+        inputSchema: recordVersionInput,
+        executionMode: "inline",
+        describeCall: "none",
+        execute: async (_input, ctx) => {
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr()) {
+                return ok({ outcome: "refused", refusal: opened.error });
+            }
+            const { threadId, analysisId, state, seenDocumentHash } = opened.value;
+            const { document: draft, snapshot } = state;
+            const finished = finishDraft(draft, snapshot);
+            if (!finished.valid) {
+                return ok({ outcome: "gaps", gaps: finished.gaps });
+            }
+            // The look-before-record rule runs before the resolver and the validation, on the state that the
+            // load already read. The preview stamps the rendered hash, and the eyes copy it onto the seen
+            // hash. A never-seen page carries no seen hash. A stale look carries the hash of an earlier draft,
+            // thus a mismatch against the current draft refuses. Each refusal skips the expensive validation.
+            const currentHash = computeDraftHash(draft);
+            if (seenDocumentHash === null) {
+                return ok({ outcome: "never-seen" });
+            }
+            if (seenDocumentHash !== currentHash) {
+                return ok({ outcome: "stale-look" });
+            }
+            if (deps.makeResolver === undefined) {
+                return ok({ outcome: "resolver-unavailable" });
+            }
+            // The resolver construction resolves the workspace root inside, and that seam throws on an
+            // unresolvable root. The guard turns the throw into a typed outcome that names the fault, thus a
+            // control-flow exception propagates and the unresolvable root does not.
+            let resolver;
+            try {
+                resolver = deps.makeResolver({ analysisId, auth: ctx.session.auth });
+            }
+            catch (cause) {
+                logger.warn("the workspace root did not resolve", { threadId, analysisId, ...logger.errorFields(cause) });
+                return ok({ outcome: "root-unresolvable", detail: "the workspace root did not resolve" });
+            }
+            const validation = await validateReport(finished.document, snapshot, resolver);
+            if (!validation.valid) {
+                return ok({
+                    outcome: "invalid",
+                    ...(validation.schemaIssues ? { schemaIssues: validation.schemaIssues } : {}),
+                    ...(validation.duplicateIds ? { duplicateIds: validation.duplicateIds } : {}),
+                    ...(validation.resolutionFailures ? { resolutionFailures: validation.resolutionFailures } : {}),
+                });
+            }
+            const thread = await deps.threads.getThread(threadId);
+            if (thread.isErr()) {
+                logger.warn("the thread row read failed", { threadId, analysisId, ...logger.errorFields(thread.error.cause) });
+                return ok({ outcome: "record-failed", detail: describeDbError(thread.error) });
+            }
+            if (thread.value === null) {
+                logger.warn("the report thread row is absent at record", { threadId, analysisId });
+                return ok({ outcome: "record-failed", detail: "the report thread row is absent" });
+            }
+            const recorded = await deps.store.record({
+                document: finished.document,
+                snapshot,
+                analysisId,
+                threadId,
+                parentThreadId: thread.value.parentThreadId,
+                parentSeq: thread.value.parentSeq,
+            });
+            return recorded.match((ref) => ok({ outcome: "recorded", versionId: ref.versionId }), (error) => {
+                if (error.type === "thread_already_holds_version") {
+                    return ok({ outcome: "already-recorded" });
+                }
+                logger.warn("the version did not record", { threadId, analysisId, reason: error.type });
+                return ok({ outcome: "record-failed", detail: describeRecordFailure(error) });
+            });
+        },
+    });
+}

package/dist/tools/sandbox/list-available-packages.js

@@ -27,12 +27,13 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
+import { LIBS_CONTAINER_PATH } from "../../sandbox/mount-plan.js";
 /**
  * Where the list lives when the host mounts the library store at the same path
  * the sandbox does. Hosts that do not — the store is baked into the image and
  * never bind-mounted — inject their own path instead.
  */
-const DEFAULT_PACKAGES_FILE = "/mnt/libs/current/packages.txt";
+const DEFAULT_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/current/packages.txt`;
 /**
  * Default cap on a listing — high enough that the real store is never truncated.
  * The shipped catalog is ~270 packages (~3 KB, well under a thousand tokens), so

package/dist/tools/sandbox/list-available-refs.d.ts

@@ -14,7 +14,11 @@
  * it at — read where it lives, render where the caller will open it. Reading it
  * host-side is what lets a planner ask what reference data exists before any
  * sandbox is created; a step agent asking mid-run sees the same store, because
- * the mount and this path are the same bytes.
+ * the mount and this path are the same bytes. An omitted `refStorePath` falls
+ * back to that same container path — where a host that mounts the store into its
+ * own process (a K8s pod holding the ref-store PVC) already sees it. The fallback
+ * is stat-verified like any other root, so a host with nothing mounted there
+ * still reports the store as unavailable.
  *
  * The scan reports paths; meaning is joined on afterwards from the install
  * receipt and the catalog it names (organism, format, and each file's internal

package/dist/tools/sandbox/list-available-refs.js

@@ -14,7 +14,11 @@
  * it at — read where it lives, render where the caller will open it. Reading it
  * host-side is what lets a planner ask what reference data exists before any
  * sandbox is created; a step agent asking mid-run sees the same store, because
- * the mount and this path are the same bytes.
+ * the mount and this path are the same bytes. An omitted `refStorePath` falls
+ * back to that same container path — where a host that mounts the store into its
+ * own process (a K8s pod holding the ref-store PVC) already sees it. The fallback
+ * is stat-verified like any other root, so a host with nothing mounted there
+ * still reports the store as unavailable.
  *
  * The scan reports paths; meaning is joined on afterwards from the install
  * receipt and the catalog it names (organism, format, and each file's internal
@@ -30,9 +34,13 @@ import { z } from "zod";
 import { capCodePoints, DETAIL_MAX_LENGTH, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 import { REFERENCE_DATA_CATALOG } from "../../reference-data/catalog.js";
 import { parseReferenceInstallReceipt } from "../../reference-data/receipt.js";
+import { REFS_CONTAINER_PATH } from "../../sandbox/mount-plan.js";
 import { defineTool } from "../define-tool.js";
-/** Container path the ref store is mounted at; every reported path is rendered under it. */
-const REFS_ROOT = "/mnt/refs";
+/**
+ * Container path the ref store is mounted at: every reported path is rendered
+ * under it, and it is the read root when the embedder supplies none.
+ */
+const REFS_ROOT = REFS_CONTAINER_PATH;
 const MAX_ENTRIES = 200;
 const MAX_SCANNED_ENTRIES = 2_000;
 const MAX_PATH_BYTES = 40_000;
@@ -283,8 +291,6 @@ async function collectFiles(directory, relative, budget) {
  */
 async function scanStore(root, relative, recursive = false) {
     const empty = () => ({ entries: [], scannedEntries: 0, truncated: false });
-    if (!root)
-        return { state: "unavailable", ...empty() };
     try {
         if (!(await lstat(root)).isDirectory())
             return { state: "unavailable", ...empty() };
@@ -494,6 +500,7 @@ function renderContent(path, scan, entries) {
 }
 /** Create reference discovery over the host-visible reference store. */
 export function createListAvailableRefsTool(deps) {
+    const storeRoot = deps.refStorePath ?? REFS_ROOT;
     return defineTool({
         id: "list_available_refs",
         description: "Resolve reference data you need into a real path. Reports the reference data provisioned for this environment right now — the only reference data an analysis script can open. " +
@@ -570,7 +577,7 @@ export function createListAvailableRefsTool(deps) {
             // recursive pass a search from the store root only ever sees directories,
             // which carry no dataset labels, so "find me a regulon network" finds nothing.
             const needleGiven = (query?.trim() ?? "") !== "";
-            const raw = await scanStore(deps.refStorePath, posixPath.relative(REFS_ROOT, requested.path) || ".", needleGiven);
+            const raw = await scanStore(storeRoot, posixPath.relative(REFS_ROOT, requested.path) || ".", needleGiven);
             const enriched = enrichEntries(raw.entries, raw);
             const categories = collectCategories(enriched);
             const needle = query?.trim().toLowerCase();

package/dist/workflows/sandbox-step.d.ts

@@ -29,6 +29,7 @@
 import type { TokenUsageRollup } from "@inflexa-ai/harness/contracts/usage.js";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
+import type { ResolveBilling } from "../billing/resolver.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
 import type { AgentDefinition, LoopMessage } from "../loop/types.js";
@@ -232,6 +233,9 @@ export interface SandboxStepDeps {
     /** Write-side embedder for the post-step vector index. */
     readonly embedding: EmbeddingProvider;
     readonly sandboxClient: SandboxClient;
+    /** Resolves the billing context stamped as the sandbox pod's OpenCost
+     *  labels. Absent in upstream-less (dev/OSS) wiring — pods spawn unlabeled. */
+    readonly resolveBilling?: ResolveBilling;
     /**
      * External artifact registration + sync seam. The harness's post-step pipeline
      * registers each step's outputs through it (filesystem index in the

package/dist/workflows/sandbox-step.js

@@ -46,6 +46,8 @@ import { createBlockerHolder } from "../tools/sandbox/report-blocker.js";
  * declare it explicitly.
  */
 export const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
+/** Resolved-header key carrying the billing-context id (see `ResolveBilling`). */
+const BILLING_CONTEXT_HEADER = "X-Inflexa-Billing-Context";
 /**
  * DBOS message topic the child uses to notify the parent that it is
  * about to self-cancel because of a 402 budget-exceeded error. The
@@ -151,7 +153,9 @@ export async function runSandboxStepBody(input, deps) {
     const identity = await DBOS.runStep(() => Promise.resolve(mintSandboxIdentity(input.runId)), { name: "sandbox.mint" });
     // (2b) sandbox.create — spawn (or adopt) the machine under the minted
     // identity. The handle (secret included) is cached so recovery picks the
-    // same machine back up without re-provisioning.
+    // same machine back up without re-provisioning. Billing resolution lives
+    // INSIDE this step (not as its own step) so the child's step sequence is
+    // unchanged — in-flight workflows resumed across a deploy replay cleanly.
     const sandboxMeta = {
         runId: input.runId,
         stepId: input.stepId,
@@ -161,7 +165,22 @@ export async function runSandboxStepBody(input, deps) {
         extraEnv: input.extraEnv,
         resources: input.resources,
     };
-    const sandbox = await DBOS.runStep(() => deps.sandboxClient.createSandbox(sandboxMeta, identity), { name: "sandbox.create" });
+    const sandbox = await DBOS.runStep(async () => {
+        let billing;
+        if (deps.resolveBilling) {
+            try {
+                const bcId = (await deps.resolveBilling(session))[BILLING_CONTEXT_HEADER];
+                if (bcId)
+                    billing = { billingContextId: bcId, userId: input.runSession.identity.user };
+            }
+            catch (err) {
+                logger.error("[billing] step billing resolution failed", { analysisId: input.analysisId, ...logger.errorFields(err) });
+            }
+            if (!billing)
+                logger.error("[billing] sandbox spawned without billing labels", { analysisId: input.analysisId });
+        }
+        return deps.sandboxClient.createSandbox({ ...sandboxMeta, billing }, identity);
+    }, { name: "sandbox.create" });
     // Recovery path: re-check `isAlive` on the persisted ref before continuing.
     // A classified-dead sandbox triggers a fresh `createSandbox` (task 4.6).
     // For first execution this is a cheap no-op; on replay it's the seam

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.19.0",
+    "version": "0.19.2",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -34,6 +34,7 @@
     },
     "scripts": {
         "build": "tsc -p tsconfig.json",
+        "design:fixture": "bun scripts/render-fixture.ts",
         "format": "prettier --write src/",
         "format:file": "prettier --write",
         "lint": "eslint .",
@@ -44,12 +45,15 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "@ai-sdk/anthropic": "^4.0.20",
-        "@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",
+        "@ai-sdk/anthropic": "^4.0.38",
+        "@ai-sdk/openai": "^4.0.39",
+        "@ai-sdk/openai-compatible": "^3.0.30",
+        "@ai-sdk/provider": "^4.0.7",
+        "@ai-sdk/provider-utils": "5.0.27",
+        "@anthropic-ai/sdk": "^0.116.0",
         "@dbos-inc/dbos-sdk": "^4.23.6",
+        "@fontsource-variable/space-grotesk": "5.1.1",
+        "@fontsource/ibm-plex-mono": "5.1.1",
         "@kubernetes/client-node": "^1.4.0",
         "@opentelemetry/api": "^1.9.1",
         "@opentelemetry/core": "^2.9.0",
@@ -60,17 +64,19 @@
         "@opentelemetry/sdk-trace-base": "^2.9.0",
         "@opentelemetry/sdk-trace-node": "^2.9.0",
         "@opentelemetry/semantic-conventions": "^1.43.0",
-        "ai": "^7.0.28",
+        "ai": "^7.0.61",
         "cheerio": "^1.2.0",
         "dockerode": "^4.0.12",
+        "echarts": "5.5.1",
         "fast-xml-parser": "^5.10.0",
         "hono": "^4.12.30",
+        "hyparquet": "^1.28.1",
         "js-tiktoken": "^1.0.21",
         "mime": "^4.1.0",
         "nanoid": "^5.1.16",
         "neverthrow": "^8.2.0",
         "nunjucks": "^3.2.4",
-        "openai": "^4.104.0",
+        "openai": "^7.4.0",
         "p-queue": "^9.3.3",
         "pdf-parse": "^2.4.5",
         "pg": "^8.22.0",