@inflexa-ai/harness 0.20.0 → 0.21.0

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

@@ -1,9 +1,9 @@
 /**
  * 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 tool records one version of the report. A version that the gate did not accept must never stand, thus
+ * the tool runs the whole gate first, and only a pass reaches the store. The gate and the look rule run on
+ * every record, the first and each later one alike.
  *
  * 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
@@ -18,16 +18,28 @@
  * 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.
+ * the thread row. A record on a thread that holds a version replaces that version whole, under the same
+ * version id. Thus the loop is unbounded: the agent amends, looks again, and records again, and the stored
+ * version equals the page that the last look accepted. A refused record leaves the stored version as it was.
+ * The outcome of a pass carries the version id, and it names a replacement.
+ *
+ * The prune runs after the version lands. It removes the output file of each derivation that the recorded
+ * document does not reference, under the `derived/` directory of the session alone. The records stay
+ * append-only, because the bytes are reproducible from the script and the sources. A failed removal logs and
+ * changes no outcome.
  */
 import { ok } from "neverthrow";
+import { rm } from "node:fs/promises";
+import { resolve as resolvePath, sep } from "node:path";
 import { z } from "zod";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeDbError } from "../../lib/db-result.js";
+import { describeFsError, tryFsWrite } from "../../lib/fs-result.js";
+import { referencedPaths, walkBlocks } from "../../report-model/block-walk.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 { reportSessionDerivedDir, resolveWorkspacePath } from "../../workspace/paths.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. */
@@ -41,12 +53,66 @@ function describeRecordFailure(error) {
             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);
     }
 }
+/**
+ * Remove the output file of each derivation that the recorded document does not reference.
+ *
+ * The unused set is a set difference: a derivation is used when a binding of the recorded document names its
+ * output path. The document is the one that the gate validated, thus the prune reads what the version holds
+ * and never the draft.
+ *
+ * The prune reaches the `derived/` directory of the session alone. A record whose path resolves outside that
+ * directory is skipped, because this tool never removes a file that it does not own. A stale record from an
+ * earlier layout and a crafted path both land in that arm.
+ *
+ * The version already stands at this point. Thus each failure costs the cleanup alone: an unresolvable root,
+ * a path that escapes, and a failed removal each log and change no outcome. The records stay, and the bytes
+ * are reproducible from the script and the sources. The scope of the prune resolves inside the same guard as
+ * the root, because both builders throw and a throw here would read as a failure of a call that succeeded.
+ */
+async function pruneUnusedDerivations(args) {
+    if (args.derivations.length === 0) {
+        return;
+    }
+    const named = referencedPaths(walkBlocks(args.document.sections).references);
+    const unused = args.derivations.filter((record) => !named.has(record.outputPath));
+    if (unused.length === 0) {
+        return;
+    }
+    let root;
+    let derivedDir;
+    try {
+        root = args.resolveWorkspaceRoot(args.analysisId);
+        derivedDir = resolvePath(root, reportSessionDerivedDir(args.threadId));
+    }
+    catch (cause) {
+        args.logger.warn("the unused derivations did not prune", {
+            threadId: args.threadId,
+            analysisId: args.analysisId,
+            ...args.logger.errorFields(cause),
+        });
+        return;
+    }
+    for (const record of unused) {
+        const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId: args.analysisId, path: record.outputPath });
+        if (resolved.kind !== "ok" || !resolved.absolute.startsWith(derivedDir + sep)) {
+            args.logger.warn("an unused derivation sits outside the derived directory of the session", {
+                threadId: args.threadId,
+                analysisId: args.analysisId,
+                path: record.outputPath,
+            });
+            continue;
+        }
+        // An absent file is the normal condition of a prune that ran before, thus `force` treats it as done.
+        const removed = await tryFsWrite("record.rm", () => rm(resolved.absolute, { force: true }), { path: resolved.absolute });
+        if (removed.isErr()) {
+            args.logger.warn("an unused derivation did not go", { path: resolved.absolute, detail: describeFsError(removed.error) });
+        }
+    }
+}
 /**
  * Make the record tool over the session-state gateway, the version store, the thread store, and the
  * resolver.
@@ -61,18 +127,27 @@ export function createRecordVersionTool(deps) {
         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.",
+            "A thread holds one version, thus a later record replaces it whole. Amend the draft, look at the page again, and record again. " +
+            "After the version lands, the tool removes the file of each derived table that no block of the recorded report binds.",
         inputSchema: recordVersionInput,
         executionMode: "inline",
         describeCall: "none",
+        // The version id is the one durable product of the first record, thus the created arm names it. A
+        // later record writes over that same id, thus the line names the update and never reads as a
+        // refusal. Each other arm is a gate that refused, and the kind of the arm is what a watcher reads.
+        describeResult: (_input, result) => {
+            if (result.outcome !== "recorded")
+                return result.outcome;
+            return result.replaced ? "version updated" : `version ${result.versionId}`;
+        },
         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 { threadId, analysisId, state, seenDocumentHash, derivations } = opened.value;
             const { document: draft, snapshot } = state;
-            const finished = finishDraft(draft, snapshot);
+            const finished = finishDraft(draft, snapshot, derivations);
             if (!finished.valid) {
                 return ok({ outcome: "gaps", gaps: finished.gaps });
             }
@@ -127,10 +202,20 @@ export function createRecordVersionTool(deps) {
                 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" });
-                }
+            if (recorded.isOk()) {
+                // The version stands from here. The prune reclaims the bytes of each derivation that the
+                // recorded document ignores, and it decides nothing about the outcome. It runs on each
+                // record, thus an output that an amend unbound goes at the next record.
+                await pruneUnusedDerivations({
+                    resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
+                    analysisId,
+                    threadId,
+                    document: finished.document,
+                    derivations,
+                    logger,
+                });
+            }
+            return recorded.match((ref) => ok({ outcome: "recorded", versionId: ref.versionId, replaced: ref.outcome === "replaced" }), (error) => {
                 logger.warn("the version did not record", { threadId, analysisId, reason: error.type });
                 return ok({ outcome: "record-failed", detail: describeRecordFailure(error) });
             });

package/dist/tools/start-report-session.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The tool that starts a report session from a conversation.
+ *
+ * The tool is the one report path of the conversation agent. It reads the parent
+ * thread from the scope of the call, thus the agent cannot name a different
+ * conversation. It carries the intent brief of the ask, and the spawn seeds the
+ * context of the child with that brief.
+ *
+ * The order of the checks is fixed. The eyes gate runs first. A composition
+ * that names no route to a look is a permanent condition, and the advice is
+ * transient state. The advice runs next. At one user turn or less of the parent
+ * past the anchor of the newest report child, the tool starts nothing and it
+ * names that child. The spawn runs last.
+ *
+ * Each degraded condition is a typed outcome in the ok channel: a scope with no
+ * thread id, a composition with no eyes, the advice, each refusal of the spawn,
+ * and a store fault. The tool never throws for one of them.
+ */
+import type { Pool } from "pg";
+import { z } from "zod";
+import type { EnsureSessionStateResult } from "../app/report-session-runtime.js";
+import type { ChromeConfig } from "../lib/chrome.js";
+import type { AcquireEyes } from "../lib/eyes.js";
+import type { Logger } from "../lib/logger.js";
+import type { ThreadType } from "../memory/thread-store.js";
+import { type Tool } from "./define-tool.js";
+/**
+ * The brief of the ask, plus the one override of the advice.
+ *
+ * Each brief field is short prose. No field names a path, a dataset, or a
+ * format, because the report session reads those from the workspace itself.
+ */
+declare const startReportSessionInput: z.ZodObject<{
+    objective: z.ZodString;
+    audience: z.ZodString;
+    angle: z.ZodString;
+    exclusions: z.ZodOptional<z.ZodString>;
+    openQuestions: z.ZodOptional<z.ZodString>;
+    newSessionAnyway: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type StartReportSessionInput = z.infer<typeof startReportSessionInput>;
+/**
+ * The typed outcome of the tool. Each arm is ok-channel data, thus the tool
+ * never throws for a degraded condition.
+ *
+ * `started` and `existing-session` name a report thread. `refused` names a call
+ * whose scope carries no conversation thread. The four refusals of the spawn
+ * keep their own names, thus the agent reads one reason from the spawn and from
+ * the tool alike. `failed` is a store fault, and it carries a short line.
+ */
+export type StartReportSessionResult = {
+    outcome: "started";
+    threadId: string;
+    title: string | null;
+} | {
+    outcome: "existing-session";
+    threadId: string;
+    title: string | null;
+} | {
+    outcome: "refused";
+    detail: string;
+} | {
+    outcome: "no_browser";
+    detail: string;
+} | {
+    outcome: "parent_not_found";
+} | {
+    outcome: "parent_not_a_conversation";
+    threadType: ThreadType;
+} | {
+    outcome: "empty_parent_transcript";
+} | {
+    outcome: "failed";
+    detail: string;
+};
+/**
+ * The construction deps of the tool.
+ *
+ * The fields build the spawn operation inside the factory. Thus one singleton
+ * tool serves every conversation, and it reads the parent from the scope of each
+ * call.
+ *
+ * Two of the fields name a route to a look at the rendered page: `eyes` and a
+ * `chrome` config that names a browser. The tool binds no capture seam. That
+ * seam replaces the transport of the eyes tool, and the tool here never looks at
+ * a page. A composition that binds a capture seam straight to the spawn still
+ * opens the gate of that spawn.
+ */
+export interface StartReportSessionToolDeps {
+    readonly pool: Pool;
+    readonly chrome: ChromeConfig;
+    /**
+     * The eyes seam of the composition. A bound seam gives a browser for one
+     * look, thus the spawn accepts a session with no configured endpoint. The
+     * tool passes the seam to the spawn, and it acquires no lease.
+     */
+    readonly eyes?: AcquireEyes;
+    /**
+     * The anchor operation of the report session runtime, which the spawn runs
+     * after the seed of the child lands. The composition binds it, thus the tool
+     * carries no stale value of its own.
+     */
+    readonly anchorSession?: (threadId: string) => Promise<EnsureSessionStateResult>;
+    readonly logger?: Logger;
+}
+/**
+ * Make the tool that starts a report session, over one Postgres pool and the
+ * eyes of the composition.
+ *
+ * The factory builds the deps of the spawn one time. The spawn and the gate of
+ * the tool read that one value, thus the two gates cannot disagree. The tool
+ * holds no per-conversation value.
+ */
+export declare function createStartReportSessionTool(deps: StartReportSessionToolDeps): Tool<StartReportSessionInput, StartReportSessionResult>;
+export {};

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

@@ -0,0 +1,179 @@
+/**
+ * The tool that starts a report session from a conversation.
+ *
+ * The tool is the one report path of the conversation agent. It reads the parent
+ * thread from the scope of the call, thus the agent cannot name a different
+ * conversation. It carries the intent brief of the ask, and the spawn seeds the
+ * context of the child with that brief.
+ *
+ * The order of the checks is fixed. The eyes gate runs first. A composition
+ * that names no route to a look is a permanent condition, and the advice is
+ * transient state. The advice runs next. At one user turn or less of the parent
+ * past the anchor of the newest report child, the tool starts nothing and it
+ * names that child. The spawn runs last.
+ *
+ * Each degraded condition is a typed outcome in the ok channel: a scope with no
+ * thread id, a composition with no eyes, the advice, each refusal of the spawn,
+ * and a store fault. The tool never throws for one of them.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { compositionHasEyes, createReportSessionSpawn } from "../app/spawn-report-session.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { describeDbError } from "../lib/db-result.js";
+import { defineTool } from "./define-tool.js";
+/**
+ * The character bound of each brief field. The whole brief lands in one durable
+ * message row, thus the schema holds no unbounded string out of the store.
+ *
+ * The description caps the brief at approximately 2000 tokens, and a token is
+ * about four characters. Thus the five bounds sum to 8000 characters, and the
+ * widest brief that the schema admits still meets the cap that the agent reads.
+ *
+ * The share of each field follows its role. `audience` names one reader, thus a
+ * phrase is enough. `objective` and `angle` carry a sentence or two. Each
+ * optional field carries a list of items, thus it takes the largest share.
+ */
+const BRIEF_MAX = {
+    objective: 1500,
+    audience: 200,
+    angle: 1500,
+    exclusions: 2400,
+    openQuestions: 2400,
+};
+/**
+ * The brief of the ask, plus the one override of the advice.
+ *
+ * Each brief field is short prose. No field names a path, a dataset, or a
+ * format, because the report session reads those from the workspace itself.
+ */
+const startReportSessionInput = z.object({
+    objective: z.string().min(1).max(BRIEF_MAX.objective).describe("The question that the report must answer."),
+    audience: z.string().min(1).max(BRIEF_MAX.audience).describe("The reader of the report."),
+    angle: z.string().min(1).max(BRIEF_MAX.angle).describe("The line that the report takes through the evidence."),
+    exclusions: z.string().max(BRIEF_MAX.exclusions).optional().describe("The material that the report must leave out."),
+    openQuestions: z.string().max(BRIEF_MAX.openQuestions).optional().describe("The points that the user did not decide yet."),
+    newSessionAnyway: z
+        .boolean()
+        .optional()
+        .describe("Set it to true to start a new session when the conversation holds no user turn of new work after the last report session. The default is false."),
+});
+/** The line that a call reads when the scope names no conversation thread. */
+const NO_THREAD_SCOPE_DETAIL = "the scope of the call names no conversation thread, thus the tool cannot start a child session";
+/** The line that a call reads when the thread store refuses the shape of the child. */
+const STORE_REFUSED_DETAIL = "the thread store refused the shape of the child session";
+/**
+ * Map a fault of the spawn onto its arm. The switch is exhaustive over the three
+ * error unions, thus a new variant fails the build instead of falling into one
+ * arm in silence.
+ */
+function toOutcome(fault) {
+    switch (fault.type) {
+        case "no_browser":
+            return { outcome: "no_browser", detail: fault.detail };
+        case "parent_not_found":
+            return { outcome: "parent_not_found" };
+        case "parent_not_a_conversation":
+            return { outcome: "parent_not_a_conversation", threadType: fault.threadType };
+        case "empty_parent_transcript":
+            return { outcome: "empty_parent_transcript" };
+        case "query_failed":
+        case "mutation_failed":
+        case "connection_failed":
+        case "constraint_violation":
+            return { outcome: "failed", detail: describeDbError(fault) };
+        case "parent_analysis_mismatch":
+        case "parent_anchor_unpaired":
+        case "unknown_thread_type":
+            return { outcome: "failed", detail: STORE_REFUSED_DETAIL };
+    }
+}
+/** The cause of a fault, or `undefined` for a fault that carries none. */
+function causeOf(fault) {
+    return "cause" in fault ? fault.cause : undefined;
+}
+/**
+ * Make the tool that starts a report session, over one Postgres pool and the
+ * eyes of the composition.
+ *
+ * The factory builds the deps of the spawn one time. The spawn and the gate of
+ * the tool read that one value, thus the two gates cannot disagree. The tool
+ * holds no per-conversation value.
+ */
+export function createStartReportSessionTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("start-report-session");
+    const spawnDeps = {
+        pool: deps.pool,
+        chrome: deps.chrome,
+        ...(deps.eyes ? { eyes: deps.eyes } : {}),
+        ...(deps.anchorSession ? { anchorSession: deps.anchorSession } : {}),
+        ...(deps.logger ? { logger: deps.logger } : {}),
+    };
+    const spawn = createReportSessionSpawn(spawnDeps);
+    // The gate reads the routes of the very spawn below, thus the two answers
+    // come from one value. The routes are fixed at construction, thus the gate
+    // reads one boolean and never a live probe of the sidecar.
+    const eyesAvailable = compositionHasEyes(spawnDeps);
+    return defineTool({
+        id: "start_report_session",
+        description: "Start an interactive report session as a child of this conversation. " +
+            "The user composes the report in that chat, with the report agent. " +
+            "Give the intent brief: the objective, the audience, and the angle of the report. " +
+            "The brief carries intent only. Do not name a path, a dataset, or a format in it, " +
+            "because the session reads those from the workspace. " +
+            "Keep the whole brief under approximately 2000 tokens. " +
+            "When the conversation holds no user turn of new work after the last report session, the tool " +
+            "starts nothing and it names that session. The ask that started that session is not new work. " +
+            "Then tell the user to continue in that chat.",
+        inputSchema: startReportSessionInput,
+        executionMode: "inline",
+        describeCall: "none",
+        execute: async (input, ctx) => {
+            const brief = {
+                objective: input.objective,
+                audience: input.audience,
+                angle: input.angle,
+                exclusions: input.exclusions,
+                openQuestions: input.openQuestions,
+            };
+            const { scope } = ctx.session;
+            if (scope.kind !== "analysis" || scope.threadId === undefined || scope.threadId.length === 0) {
+                return ok({ outcome: "refused", detail: NO_THREAD_SCOPE_DETAIL });
+            }
+            const parentThreadId = scope.threadId;
+            // The eyes gate has priority over the advice, and the advice costs two
+            // reads. The spawn holds the same gate before each read of its own,
+            // thus a blind composition reaches the `no_browser` refusal of the
+            // spawn with no read and no write. As a result the tool copies no
+            // detail line of the spawn.
+            if (eyesAvailable) {
+                const delta = await spawn.reportSessionDelta(parentThreadId);
+                if (delta.isErr()) {
+                    logger.warn("the report session delta did not read", {
+                        parentThreadId,
+                        reason: delta.error.type,
+                        ...logger.errorFields(delta.error.cause),
+                    });
+                    return ok(toOutcome(delta.error));
+                }
+                const { newestChild, userTurnsSinceAnchor } = delta.value;
+                // The rule admits one turn. A turn appends after its own loop
+                // runs, thus the ask that made the child is itself one user turn
+                // past the anchor. A rule at zero would never advise again after
+                // that turn commits. A second user turn is real work, and a new
+                // session can report on it.
+                if (input.newSessionAnyway !== true && newestChild !== null && userTurnsSinceAnchor !== null && userTurnsSinceAnchor <= 1) {
+                    return ok({ outcome: "existing-session", threadId: newestChild.threadId, title: newestChild.title });
+                }
+            }
+            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;
+            }));
+        },
+    });
+}

package/dist/workspace/paths.d.ts

@@ -122,6 +122,34 @@ export declare function stepWritePrefix(args: {
     readonly runId: string;
     readonly stepId: string;
 }): string;
+/**
+ * Split a declared sandbox write tail into its segments, and refuse a tail that is
+ * not one workspace-relative path.
+ *
+ * A tail names the one writable mount of a sandbox in place of the step directory.
+ * It reaches the mount builders from a caller, thus it takes the same discipline as
+ * a `stepId`: each segment passes {@link assertSafeId}, which refuses a separator,
+ * a NUL, a shell-hostile char, and a pure-dot segment. An empty tail names the
+ * workspace root itself, and an absolute tail names a host location. Both are
+ * refused, because a write mount must be a directory inside the tree.
+ *
+ * The segments come back so a host-path builder joins the validated parts, and it
+ * never re-splits the raw text.
+ */
+export declare function assertSafeTail(tail: string, label?: string): string[];
+/**
+ * Derive the host path of a declared write tail under a workspace root.
+ *
+ * The counterpart of {@link stepWritePrefix} for a sandbox that declares its own
+ * write tail. The tail passes the same validation before it becomes a host
+ * directory path, thus a crafted segment cannot widen or escape the mount. This is
+ * the one builder of that path: the host makes the directory with it, and the
+ * Docker bind source comes from it.
+ */
+export declare function tailWritePrefix(args: {
+    readonly workspaceRoot: string;
+    readonly tail: string;
+}): string;
 /**
  * Map a host-side absolute path within an analysis's workspace tree to its
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
@@ -152,6 +180,28 @@ export declare function previewDir(previewId: string): string;
  * 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
+ * {@link reportSessionDir}. Both spell the segment through this constant, thus
+ * the tree has one owner.
+ */
+export declare const REPORT_SESSIONS_ROOT = "report-sessions";
+/**
+ * Directory of one report session, workspace-root-relative. The page of the
+ * session and its staged assets live under this one directory. Thus a host that
+ * reclaims the files of a purged session names each directory through this
+ * helper. The host restates no layout of the harness.
+ */
+export declare function reportSessionDir(threadId: string): string;
+/**
+ * Directory of the derived tables of one report session, workspace-root-relative.
+ *
+ * The derivation writes its output here, and the record prunes an output that the recorded document does
+ * not name. Both spell the segment through this helper, thus the write mount and the prune scope cannot
+ * disagree.
+ */
+export declare function reportSessionDerivedDir(threadId: string): string;
 /**
  * True when `value` is a safe single path segment: the `SAFE_ID` charset (word
  * chars, `.`, `-` — no slash, NUL, or shell-hostile char) AND not a pure-dot

package/dist/workspace/paths.js

@@ -96,6 +96,42 @@ export function stepWritePrefix(args) {
     assertSafeId(args.stepId, "stepId");
     return resolvePath(args.workspaceRoot, "runs", args.runId, args.stepId);
 }
+/**
+ * Split a declared sandbox write tail into its segments, and refuse a tail that is
+ * not one workspace-relative path.
+ *
+ * A tail names the one writable mount of a sandbox in place of the step directory.
+ * It reaches the mount builders from a caller, thus it takes the same discipline as
+ * a `stepId`: each segment passes {@link assertSafeId}, which refuses a separator,
+ * a NUL, a shell-hostile char, and a pure-dot segment. An empty tail names the
+ * workspace root itself, and an absolute tail names a host location. Both are
+ * refused, because a write mount must be a directory inside the tree.
+ *
+ * The segments come back so a host-path builder joins the validated parts, and it
+ * never re-splits the raw text.
+ */
+export function assertSafeTail(tail, label = "writableTail") {
+    if (tail.length === 0 || tail.startsWith("/")) {
+        throw new Error(`Invalid ${label}: ${tail}`);
+    }
+    const segments = tail.split("/");
+    for (const segment of segments) {
+        assertSafeId(segment, label);
+    }
+    return segments;
+}
+/**
+ * Derive the host path of a declared write tail under a workspace root.
+ *
+ * The counterpart of {@link stepWritePrefix} for a sandbox that declares its own
+ * write tail. The tail passes the same validation before it becomes a host
+ * directory path, thus a crafted segment cannot widen or escape the mount. This is
+ * the one builder of that path: the host makes the directory with it, and the
+ * Docker bind source comes from it.
+ */
+export function tailWritePrefix(args) {
+    return resolvePath(args.workspaceRoot, ...assertSafeTail(args.tail));
+}
 /**
  * Map a host-side absolute path within an analysis's workspace tree to its
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
@@ -152,6 +188,33 @@ export function latestPreviewVersion(dirNames) {
     }
     return max;
 }
+/**
+ * Parent of every report session, workspace-root-relative. Callers that
+ * enumerate the sessions join this. Callers that address one join
+ * {@link reportSessionDir}. Both spell the segment through this constant, thus
+ * the tree has one owner.
+ */
+export const REPORT_SESSIONS_ROOT = "report-sessions";
+/**
+ * Directory of one report session, workspace-root-relative. The page of the
+ * session and its staged assets live under this one directory. Thus a host that
+ * reclaims the files of a purged session names each directory through this
+ * helper. The host restates no layout of the harness.
+ */
+export function reportSessionDir(threadId) {
+    assertSafeId(threadId, "threadId");
+    return `${REPORT_SESSIONS_ROOT}/${threadId}`;
+}
+/**
+ * Directory of the derived tables of one report session, workspace-root-relative.
+ *
+ * The derivation writes its output here, and the record prunes an output that the recorded document does
+ * not name. Both spell the segment through this helper, thus the write mount and the prune scope cannot
+ * disagree.
+ */
+export function reportSessionDerivedDir(threadId) {
+    return `${reportSessionDir(threadId)}/derived`;
+}
 /**
  * For an analysis-rooted input (`/{analysisId}/...`), strip the leading
  * `/{analysisId}/` segment so it can be resolved relative to the analysis

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.20.0",
+    "version": "0.21.0",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -64,6 +64,7 @@
         "@opentelemetry/sdk-trace-base": "^2.9.0",
         "@opentelemetry/sdk-trace-node": "^2.9.0",
         "@opentelemetry/semantic-conventions": "^1.43.0",
+        "ag-grid-community": "36.1.0",
         "ai": "^7.0.61",
         "cheerio": "^1.2.0",
         "dockerode": "^4.0.12",