@inflexa-ai/harness 0.1.1

package/dist/workspace/filesystem.js

@@ -0,0 +1,304 @@
+/**
+ * The workspace read seam — `{ readFile, list, stat }` over the analysis
+ * workspace tree. A construction-time dependency (see the harness-durable-runtime spec): the composition
+ * root builds one `WorkspaceFilesystem` and passes it to tool factories.
+ *
+ * Reads resolve from the analysis's workspace root when the file is present and
+ * fall back to an embedder-supplied presigned URL otherwise. The seam writes no
+ * provenance — reads don't produce lineage — and does not depend on any
+ * sandbox.
+ *
+ * Scoping is enforced once, here, by `resolveWorkspacePath`: any path that
+ * escapes the analysis's resolved workspace root is rejected before any I/O.
+ * `read_file` / `grep` / any future reader share the chokepoint.
+ *
+ * Reads roam the whole tree read-only, so the seam never confines. Relative
+ * paths resolve against the caller-supplied `workingDir` (frame-local, per
+ * the harness-workspace-tools spec);
+ * when omitted they resolve against the analysis root, which is the
+ * conversation-agent behaviour. Sandbox read tools pass the step working
+ * directory so a relative path reads back what a relative write wrote.
+ *
+ * Failure is modelled as values (see `lib/fs-result.ts`): the public methods
+ * return `ResultAsync<…, FsError>`. The `not_found` / `out_of_scope` /
+ * `truncated` outcomes are NOT failures — they ride the OK channel as `.kind`
+ * data variants. `err(FsError)` is reserved for a genuine I/O failure
+ * (permission, `EISDIR`, a presigned-fetch throw). An `AbortError` raised
+ * inside a streamed read is control-flow — the streaming/iteration body is kept
+ * OUTSIDE `tryFs`, so only the discrete `fs.open` / `fs.read` / `fs.readFile`
+ * calls become `err`.
+ */
+import { open as fsOpen, readFile as fsReadFile, readdir as fsReaddir, stat as fsStat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { join } from "node:path";
+import { ResultAsync, err, errAsync, ok } from "neverthrow";
+import { scopeResource } from "../auth/types.js";
+import { tryFetch, tryFs } from "../lib/fs-result.js";
+import { classifyWithinRoot } from "../lib/fs-helpers.js";
+import { resolveWorkspacePath } from "./paths.js";
+// ── Constructor ───────────────────────────────────────────────────────────
+export function createWorkspaceFilesystem(deps) {
+    const { resolveWorkspaceRoot, presignedFallback } = deps;
+    /**
+     * `ResolveWorkspaceRoot` signals an unresolvable resource by throwing — the contract that
+     * makes a resolution failure inside a DBOS body a durably-failed step. This seam is not a
+     * DBOS body: it promises `Result`, and the read tools it backs are reachable from a live
+     * chat turn whose analysis folder may have been moved or deleted since the turn began.
+     * Convert at the boundary so an unresolvable root is a value here, not an exception that
+     * only survives because some caller happens to wrap it.
+     */
+    function resolveFor(session, path, workingDir) {
+        const { resourceId: analysisId } = scopeResource(session.scope);
+        let workspaceRoot;
+        try {
+            workspaceRoot = resolveWorkspaceRoot(analysisId);
+        }
+        catch (cause) {
+            return err({ type: "read_failed", op: "workspace.resolveWorkspaceRoot", path: analysisId, cause });
+        }
+        return ok({ resolved: resolveWorkspacePath({ workspaceRoot, analysisId, path, workingDir }), workspaceRoot });
+    }
+    /**
+     * Lexical resolution PLUS a symlink-following confinement check — the single
+     * chokepoint every read tool (`read_file`, `grep`, `list`, `stat`) funnels
+     * through. `resolveWorkspacePath` is purely lexical, so a symlink an agent
+     * planted in its writable step dir (pointing at a host file outside the tree)
+     * would otherwise be read through by this host process. `classifyWithinRoot`
+     * follows the link: an `escaped` verdict is downgraded to `out_of_scope`; an
+     * `absent` path passes through unchanged so the caller's own not-found /
+     * presigned-fallback handling still runs (a non-existent path leaks nothing).
+     */
+    function confinedResolve(session, path, workingDir) {
+        const base = resolveFor(session, path, workingDir);
+        if (base.isErr())
+            return errAsync(base.error);
+        const { resolved, workspaceRoot } = base.value;
+        if (resolved.kind === "out_of_scope")
+            return okAsync(resolved);
+        return ResultAsync.fromPromise(classifyWithinRoot(workspaceRoot, resolved.absolute), (cause) => ({
+            type: "read_failed",
+            op: "workspace.confineRealpath",
+            path: resolved.absolute,
+            cause,
+        })).map((verdict) => (verdict === "escaped" ? { kind: "out_of_scope" } : resolved));
+    }
+    return {
+        readFile({ session, path, maxBytes, headLines, tailLines, workingDir }) {
+            return confinedResolve(session, path, workingDir).andThen((resolved) => {
+                if (resolved.kind === "out_of_scope") {
+                    return okAsync({ kind: "out_of_scope" });
+                }
+                const absolute = resolved.absolute;
+                const relative = resolved.relative;
+                return safeStat(absolute).andThen((localStat) => {
+                    if (localStat?.isFile()) {
+                        if (headLines !== undefined) {
+                            return readHeadLines(absolute, headLines, maxBytes);
+                        }
+                        if (tailLines !== undefined) {
+                            return readTailLines(absolute, localStat.size, tailLines, maxBytes);
+                        }
+                        return readWithCap(absolute, localStat.size, maxBytes);
+                    }
+                    if (presignedFallback) {
+                        return tryFetch("workspace.presignedFetch", () => presignedFallback.fetch({ session, relativePath: relative }), relative).map((content) => {
+                            if (content !== null) {
+                                if (headLines !== undefined)
+                                    return sliceHeadLines(content, headLines, maxBytes);
+                                if (tailLines !== undefined)
+                                    return sliceTailLines(content, tailLines, maxBytes);
+                                return capBuffer(content, maxBytes);
+                            }
+                            return { kind: "not_found" };
+                        });
+                    }
+                    return okAsync({ kind: "not_found" });
+                });
+            });
+        },
+        list({ session, path, workingDir }) {
+            return confinedResolve(session, path, workingDir).andThen((resolved) => {
+                if (resolved.kind === "out_of_scope") {
+                    return okAsync({ kind: "out_of_scope" });
+                }
+                const absolute = resolved.absolute;
+                return tryFs("workspace.list", () => fsReaddir(absolute, { withFileTypes: true }), { path: absolute, onAbsent: () => ({ notFound: true }) }).andThen((dirents) => {
+                    if ("notFound" in dirents)
+                        return okAsync({ kind: "not_found" });
+                    return collectEntries(absolute, dirents).map((entries) => ({ kind: "ok", entries }));
+                });
+            });
+        },
+        stat({ session, path, workingDir }) {
+            return confinedResolve(session, path, workingDir).andThen((resolved) => {
+                if (resolved.kind === "out_of_scope") {
+                    return okAsync({ kind: "out_of_scope" });
+                }
+                return safeStat(resolved.absolute).map((s) => {
+                    if (!s)
+                        return { kind: "not_found" };
+                    return {
+                        kind: "ok",
+                        type: s.isDirectory() ? "directory" : "file",
+                        size: s.size,
+                    };
+                });
+            });
+        },
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+/** A bare `ok(value)` as a `ResultAsync`, with no `fs` call to wrap. */
+function okAsync(value) {
+    return new ResultAsync(Promise.resolve(ok(value)));
+}
+/** Stat a path; absence (`ENOENT`/`ENOTDIR`) → `ok(null)`, genuine I/O → `err`. */
+function safeStat(absolute) {
+    return tryFs("workspace.stat", () => fsStat(absolute), {
+        path: absolute,
+        onAbsent: () => null,
+    });
+}
+/** Stat each directory entry to attach a size; absence/I/O failures degrade to no size. */
+function collectEntries(dir, dirents) {
+    return ResultAsync.combine(dirents.map((d) => {
+        if (d.isDirectory())
+            return okAsync({ name: d.name, type: "directory" });
+        return safeStat(join(dir, d.name)).map((s) => ({ name: d.name, type: "file", size: s?.size ?? undefined }));
+    }));
+}
+function readWithCap(absolute, totalSize, maxBytes) {
+    if (maxBytes !== undefined && totalSize > maxBytes) {
+        return tryFs("workspace.readCapped", async () => {
+            const fh = await fsOpen(absolute, "r");
+            try {
+                const buf = Buffer.alloc(maxBytes);
+                await fh.read(buf, 0, maxBytes, 0);
+                return { kind: "truncated", content: buf, totalSize };
+            }
+            finally {
+                await fh.close();
+            }
+        }, { path: absolute });
+    }
+    return tryFs("workspace.readFile", async () => ({ kind: "ok", content: await fsReadFile(absolute), truncated: false }), { path: absolute });
+}
+function capBuffer(content, maxBytes) {
+    if (maxBytes !== undefined && content.length > maxBytes) {
+        return {
+            kind: "truncated",
+            content: content.subarray(0, maxBytes),
+            totalSize: content.length,
+        };
+    }
+    return { kind: "ok", content, truncated: false };
+}
+/**
+ * Stream the first `headLines` lines from disk, byte-bounded by `maxBytes`.
+ * Stops at whichever cap binds first; the stream is destroyed eagerly so
+ * we never read past the cap into RAM.
+ *
+ * The streaming/iteration body is kept OUTSIDE `tryFs` — an `AbortError` raised
+ * inside it is control-flow and must propagate, not become `err`. Only the
+ * follow-up `safeStat` (a discrete `fs` call) flows the `FsError` channel.
+ */
+function readHeadLines(absolute, headLines, maxBytes) {
+    return new ResultAsync((async () => {
+        const stream = createReadStream(absolute, { highWaterMark: 16 * 1024 });
+        const rl = createInterface({ input: stream, crlfDelay: Infinity });
+        const collected = [];
+        let bytes = 0;
+        let truncated = false;
+        try {
+            for await (const line of rl) {
+                const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+                if (maxBytes !== undefined && bytes + lineBytes > maxBytes) {
+                    truncated = true;
+                    break;
+                }
+                collected.push(line);
+                bytes += lineBytes;
+                if (collected.length >= headLines)
+                    break;
+            }
+        }
+        finally {
+            rl.close();
+            stream.destroy();
+        }
+        const content = Buffer.from(collected.join("\n"));
+        if (truncated) {
+            // Total size is unknown without a full stat; report it as a separate read.
+            return (await safeStat(absolute)).map((s) => ({
+                kind: "truncated",
+                content,
+                totalSize: s?.size ?? content.length,
+            }));
+        }
+        // Whether the loop exhausted the file or hit the line cap, the agent asked
+        // for exactly this window, so this is `ok` not `truncated`. The tool layer
+        // reports `mode: "head"` so the agent knows it's a window.
+        return ok({ kind: "ok", content, truncated: false });
+    })());
+}
+/**
+ * Read the last `tailLines` lines via a windowed read from the end. The
+ * window size is bounded by `maxBytes` (default cap caller-supplied), so we
+ * never page in the whole file. If the window doesn't start at offset 0, the
+ * first line in the window is partial and is dropped.
+ *
+ * The discrete `fs.open` / `fh.read` calls are wrapped in `tryFs`; the buffer
+ * slicing is pure and runs inside the same `fn`.
+ */
+function readTailLines(absolute, totalSize, tailLines, maxBytes) {
+    return tryFs("workspace.readTail", async () => {
+        const windowSize = Math.min(totalSize, maxBytes ?? totalSize);
+        const offset = totalSize - windowSize;
+        const fh = await fsOpen(absolute, "r");
+        try {
+            const buf = Buffer.alloc(windowSize);
+            if (windowSize > 0) {
+                await fh.read(buf, 0, windowSize, offset);
+            }
+            const allLines = buf.toString("utf8").split(/\r?\n/);
+            // Drop the partial leading line if the window doesn't cover the file start.
+            const candidateLines = offset > 0 ? allLines.slice(1) : allLines;
+            const sliced = candidateLines.length > tailLines ? candidateLines.slice(-tailLines) : candidateLines;
+            const content = Buffer.from(sliced.join("\n"));
+            const gotEnoughLines = sliced.length >= tailLines || offset === 0;
+            if (!gotEnoughLines) {
+                return { kind: "truncated", content, totalSize };
+            }
+            return { kind: "ok", content, truncated: false };
+        }
+        finally {
+            await fh.close();
+        }
+    }, { path: absolute });
+}
+function sliceHeadLines(content, headLines, maxBytes) {
+    const capped = maxBytes !== undefined && content.length > maxBytes ? content.subarray(0, maxBytes) : content;
+    const lines = capped.toString("utf8").split(/\r?\n/);
+    const slice = lines.slice(0, headLines);
+    const out = Buffer.from(slice.join("\n"));
+    if (maxBytes !== undefined && content.length > maxBytes && slice.length < headLines) {
+        return { kind: "truncated", content: out, totalSize: content.length };
+    }
+    return { kind: "ok", content: out, truncated: false };
+}
+function sliceTailLines(content, tailLines, maxBytes) {
+    if (maxBytes === undefined || content.length <= maxBytes) {
+        const lines = content.toString("utf8").split(/\r?\n/);
+        const slice = lines.length > tailLines ? lines.slice(-tailLines) : lines;
+        return { kind: "ok", content: Buffer.from(slice.join("\n")), truncated: false };
+    }
+    const window = content.subarray(content.length - maxBytes);
+    const lines = window.toString("utf8").split(/\r?\n/).slice(1);
+    const slice = lines.length > tailLines ? lines.slice(-tailLines) : lines;
+    const out = Buffer.from(slice.join("\n"));
+    if (slice.length < tailLines) {
+        return { kind: "truncated", content: out, totalSize: content.length };
+    }
+    return { kind: "ok", content: out, truncated: false };
+}

package/dist/workspace/mount-strategy.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Mount strategy — single source of truth for workspace/pod mount paths.
+ *
+ * Single-mount model: one workspace mount covers the full analysis tree.
+ * Write protection is enforced via K8s RO volumeMount (execute_command) and
+ * by the harness write guard at the workspace-filesystem layer. Pod mounts
+ * are nested (K8s handles this fine — most-specific path wins).
+ */
+/**
+ * Canonical paths for a step.
+ *
+ * ANALYSIS is the single workspace mount (covers the full analysis tree).
+ * ARTIFACTS is a subpath within that mount (the step's writable area, used as CWD).
+ */
+export declare function buildMountPaths(resourceId: string, runId: string, stepId: string): {
+    /** Full analysis tree — single workspace mount. */
+    readonly ANALYSIS: `/${string}`;
+    /** Step's writable area — subpath within ANALYSIS, used as CWD. */
+    readonly ARTIFACTS: `/${string}`;
+};
+export interface PodMount {
+    mountPath: string;
+    subPath: string;
+    readOnly: boolean;
+}
+export interface DockerMount {
+    hostPath: string;
+    containerPath: string;
+    readOnly: boolean;
+}
+/**
+ * Build pod volumeMount specs — nested: full analysis (RO) + step area (RW).
+ * K8s handles nested mounts — the most-specific path wins.
+ */
+export declare function buildPodMounts(opts: {
+    resourceId: string;
+    runId: string;
+    stepId: string;
+}): PodMount[];
+/**
+ * Build Docker bind mount specs — same nesting logic as buildPodMounts,
+ * but with host paths derived from sessionPath.
+ * Docker handles nested mounts — the most-specific path wins.
+ */
+export declare function buildDockerMounts(opts: {
+    resourceId: string;
+    runId: string;
+    stepId: string;
+    sessionPath: string;
+}): DockerMount[];

package/dist/workspace/mount-strategy.js

@@ -0,0 +1,67 @@
+/**
+ * Mount strategy — single source of truth for workspace/pod mount paths.
+ *
+ * Single-mount model: one workspace mount covers the full analysis tree.
+ * Write protection is enforced via K8s RO volumeMount (execute_command) and
+ * by the harness write guard at the workspace-filesystem layer. Pod mounts
+ * are nested (K8s handles this fine — most-specific path wins).
+ */
+import { runStepDir } from "./paths.js";
+import { join } from "node:path";
+// ── Mount Path Builders ──────────────────────────────────────────────────
+/**
+ * Canonical paths for a step.
+ *
+ * ANALYSIS is the single workspace mount (covers the full analysis tree).
+ * ARTIFACTS is a subpath within that mount (the step's writable area, used as CWD).
+ */
+export function buildMountPaths(resourceId, runId, stepId) {
+    return {
+        /** Full analysis tree — single workspace mount. */
+        ANALYSIS: `/${resourceId}`,
+        /** Step's writable area — subpath within ANALYSIS, used as CWD. */
+        ARTIFACTS: `/${runStepDir(resourceId, runId, stepId)}`,
+    };
+}
+// ── Pod mounts ──────────────────────────────────────────────────────────
+/**
+ * Build pod volumeMount specs — nested: full analysis (RO) + step area (RW).
+ * K8s handles nested mounts — the most-specific path wins.
+ */
+export function buildPodMounts(opts) {
+    const mp = buildMountPaths(opts.resourceId, opts.runId, opts.stepId);
+    return [
+        {
+            mountPath: mp.ANALYSIS,
+            subPath: opts.resourceId,
+            readOnly: true,
+        },
+        {
+            mountPath: mp.ARTIFACTS,
+            subPath: runStepDir(opts.resourceId, opts.runId, opts.stepId),
+            readOnly: false,
+        },
+    ];
+}
+// ── Docker bind mounts ─────────────────────────────────────────────────
+/**
+ * Build Docker bind mount specs — same nesting logic as buildPodMounts,
+ * but with host paths derived from sessionPath.
+ * Docker handles nested mounts — the most-specific path wins.
+ */
+export function buildDockerMounts(opts) {
+    const mp = buildMountPaths(opts.resourceId, opts.runId, opts.stepId);
+    const stepRelPath = runStepDir(opts.resourceId, opts.runId, opts.stepId);
+    return [
+        {
+            hostPath: join(opts.sessionPath, opts.resourceId),
+            containerPath: mp.ANALYSIS,
+            readOnly: true,
+        },
+        {
+            hostPath: join(opts.sessionPath, stepRelPath),
+            containerPath: mp.ARTIFACTS,
+            readOnly: false,
+        },
+    ];
+}

package/dist/workspace/paths.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Canonical workspace path resolver — shared between the read surface and
+ * the sandbox-gated mutate surface.
+ *
+ * One module that maps agent-supplied paths to physical workspace-tree
+ * locations under the frame-aware path model (see the harness-workspace-tools spec):
+ *
+ *   - A **relative** path resolves against the caller's `workingDir` (the
+ *     agent's writable working directory; the analysis root when omitted, as
+ *     for the conversation agent). Frame-local.
+ *   - An **absolute `/{analysisId}/...`** path resolves against the analysis
+ *     root regardless of `workingDir`. Frame-independent — the canonical
+ *     interchange form for paths crossing an agent or frame boundary.
+ *
+ * The analysis root itself comes from the embedder through the
+ * {@link ResolveWorkspaceRoot} seam — the harness owns the layout *inside*
+ * the root, the embedder owns *where* the root lives. Host paths carry no
+ * `{resourceId}` segment (the resolved root already identifies the resource);
+ * the `/{resourceId}/…` form survives only as the container-side view, which
+ * bind mounts keep independent of the host location.
+ *
+ * Both surfaces share this resolver, so a file a step writes is read back at
+ * the identical path — agreement is structural, not re-implemented per tool.
+ * `resolveForWrite` adds confinement: a resolved path outside `workingDir`
+ * comes back `out_of_prefix` (the read surface skips that — it roams the tree
+ * read-only).
+ */
+/**
+ * The workspace-root resolution seam (see the workspace-root-resolution spec).
+ *
+ * Maps a resource id to the absolute host directory of that resource's
+ * workspace tree. Supplied by the embedder at the composition root and closed
+ * over once at workflow registration — the *function* is fixed per process,
+ * its *result* varies per resource, which is what makes per-resource roots
+ * compatible with DBOS's register-once model.
+ *
+ * Realization contract:
+ *   - **Injective** — two live resources never resolve to the same root; the
+ *     harness treats the root as exclusively owned and does not verify this.
+ *   - **Durable-state-backed** — resolve from host state that survives the
+ *     process (a DB row, a config map), never process memory, so a recovered
+ *     workflow on a fresh process resolves correctly.
+ *   - **Stable while the resource has an active run** — derived paths are
+ *     recorded in durable step outputs; preventing mid-run moves is the
+ *     embedder's job.
+ *   - **Throws on unknown resources** — inside DBOS bodies the failure must
+ *     cross the step boundary as a throw so the step is durably recorded as
+ *     failed (see `lib/result.ts` house rules).
+ */
+export type ResolveWorkspaceRoot = (resourceId: string) => string;
+/** Result of resolving a workspace path against the canonical layout. */
+export type ResolvedPath = {
+    readonly kind: "ok";
+    readonly absolute: string;
+    readonly relative: string;
+} | {
+    readonly kind: "out_of_scope";
+};
+/**
+ * Result of resolving a path for a *write*: scope resolution plus confinement
+ * to the caller's `workingDir`. `out_of_prefix` (in-tree but outside the
+ * working directory) is distinct from `out_of_scope` (escaped the analysis
+ * tree) so the model can correct toward its working directory rather than
+ * guessing why the write failed. Both are data variants — never throws.
+ */
+export type WriteResolvedPath = {
+    readonly kind: "ok";
+    readonly absolute: string;
+    readonly relative: string;
+} | {
+    readonly kind: "out_of_scope";
+} | {
+    readonly kind: "out_of_prefix";
+};
+/**
+ * Resolve an agent-supplied path against the analysis tree under the
+ * frame-aware model.
+ *
+ *   - **Relative** (no leading slash) → resolved against `workingDir`
+ *     (defaults to the analysis root). E.g. with `workingDir` =
+ *     `…/runs/{runId}/{stepId}`, `"output/x.csv"` → that step's output dir.
+ *   - **Absolute `/{analysisId}/...`** → resolved against the analysis root,
+ *     ignoring `workingDir`. Frame-independent.
+ *
+ * The returned `relative` is always **analysis-root-relative** (used to build
+ * the in-sandbox `/{analysisId}/…` path). Returns `out_of_scope` for any input
+ * that escapes the resolved workspace root (`..` traversal, absolute host
+ * paths outside the tree, `/{otherAnalysisId}/...`).
+ */
+export declare function resolveWorkspacePath(args: {
+    /** Absolute host root of the analysis's workspace tree (from the embedder's resolver). */
+    readonly workspaceRoot: string;
+    readonly analysisId: string;
+    readonly path: string;
+    /** Absolute host base that relative paths resolve against. Defaults to the analysis root. */
+    readonly workingDir?: string;
+}): ResolvedPath;
+/**
+ * Resolve a path for a write: same frame-aware resolution as
+ * `resolveWorkspacePath` (relative → `workingDir`, absolute → analysis root),
+ * then confine the result to `workingDir`. A `..` escape from the tree is
+ * `out_of_scope`; an in-tree path outside the working directory is
+ * `out_of_prefix`. A path equal to `workingDir` itself is in-prefix.
+ *
+ * `workingDir` is the absolute host path of the agent's writable working
+ * directory (for a plannable step, `stepWritePrefix(...)`).
+ */
+export declare function resolveForWrite(args: {
+    /** Absolute host root of the analysis's workspace tree (from the embedder's resolver). */
+    readonly workspaceRoot: string;
+    readonly analysisId: string;
+    readonly path: string;
+    readonly workingDir: string;
+}): WriteResolvedPath;
+/**
+ * Derive the canonical writable-prefix absolute path for a sandbox step.
+ * Single source of truth — the agent does NOT supply this; it is computed
+ * from the workspace root + run/step coordinates the workflow owns.
+ */
+export declare function stepWritePrefix(args: {
+    readonly workspaceRoot: string;
+    readonly runId: string;
+    readonly stepId: 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
+ * the sandbox path is the resource id plus the root-relative tail — the host
+ * location of the root never leaks into the container. Single source of truth
+ * for the `execute_command` / `write_file` cwd and the `{{WORKING_DIR}}`
+ * prompt substitution (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;
+/**
+ * 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
+ * segment (`.`/`..`), which the charset otherwise admits and which `resolve`/`join`
+ * would treat as the current/parent directory and use to climb the tree. The one
+ * definition of "safe id", shared by the throwing {@link assertSafeId} at path
+ * builders and the plan validator (`validate-plan.ts`), so a stepId is judged the
+ * same at plan time and at mount time.
+ */
+export declare function isSafeId(value: string): boolean;
+/**
+ * Throwing form of {@link isSafeId} for the mount/host-path builders. Ids are
+ * harness-minted UUIDs on every trusted path, but `stepId` reaches these builders
+ * straight from an LLM-authored plan, so this is the boundary that keeps a crafted
+ * id from re-rooting a mount or a host write. Exported so the mount-plan builders
+ * (the container-path source of truth) validate the same way.
+ */
+export declare function assertSafeId(value: string, label: string): void;
+/** Root directory for a specific workflow run, workspace-root-relative. */
+export declare function runDir(runId: string): string;
+/** Step directory within a run, workspace-root-relative. */
+export declare function runStepDir(runId: string, stepId: string): string;
+/** Step subdirectory for a specific artifact type. */
+export type StepSubdirType = "scripts" | "output" | "figures" | "logs" | "notebooks";
+export declare function stepSubdir(stepBase: string, type: StepSubdirType): string;
+/** Report output directory, workspace-root-relative. */
+export declare function reportDir(reportId: string): string;
+/** All standard subdirectory types for a step. */
+export declare const STEP_SUBDIRS: readonly StepSubdirType[];
+/** Get all subdirectory paths for a step. */
+export declare function allStepSubdirs(stepBase: string): string[];