@inflexa-ai/harness 0.1.1

package/dist/workspace/paths.js

@@ -0,0 +1,219 @@
+/**
+ * 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).
+ */
+import { relative as relativePath, resolve as resolvePath, sep } from "node:path";
+/**
+ * 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 function resolveWorkspacePath(args) {
+    const { workspaceRoot, analysisId, path } = args;
+    if (path.length === 0 || path.includes("\0"))
+        return { kind: "out_of_scope" };
+    const analysisRoot = resolvePath(workspaceRoot);
+    let absolute;
+    if (path.startsWith("/")) {
+        const stripped = stripAnalysisRoot(path, analysisId);
+        if (stripped === null)
+            return { kind: "out_of_scope" };
+        absolute = resolvePath(analysisRoot, stripped);
+    }
+    else {
+        const base = args.workingDir ?? analysisRoot;
+        absolute = resolvePath(base, path);
+    }
+    if (absolute !== analysisRoot && !absolute.startsWith(analysisRoot + sep)) {
+        return { kind: "out_of_scope" };
+    }
+    const relative = absolute === analysisRoot ? "" : absolute.slice(analysisRoot.length + 1);
+    return { kind: "ok", absolute, relative };
+}
+/**
+ * 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 function resolveForWrite(args) {
+    const resolved = resolveWorkspacePath(args);
+    if (resolved.kind === "out_of_scope")
+        return { kind: "out_of_scope" };
+    const prefix = resolvePath(args.workingDir);
+    if (resolved.absolute !== prefix && !resolved.absolute.startsWith(prefix + sep)) {
+        return { kind: "out_of_prefix" };
+    }
+    return { kind: "ok", absolute: resolved.absolute, relative: resolved.relative };
+}
+/**
+ * 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 function stepWritePrefix(args) {
+    // `stepId` originates in an LLM-authored plan; validate before it becomes a
+    // host directory path (this prefix is the mkdir target and the docker bind
+    // source) so a crafted `..`/`/` segment cannot widen or escape the mount.
+    assertSafeId(args.runId, "runId");
+    assertSafeId(args.stepId, "stepId");
+    return resolvePath(args.workspaceRoot, "runs", args.runId, args.stepId);
+}
+/**
+ * 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 function toSandboxPath(workspaceRoot, resourceId, hostAbsPath) {
+    const tail = relativePath(workspaceRoot, hostAbsPath).split(sep).join("/");
+    // A `..`-leading tail means `hostAbsPath` is not under `workspaceRoot`; every
+    // current caller passes an in-tree path (a step write prefix), so this is a
+    // guard against a future miswire producing `/{resourceId}/../…`, not a
+    // reachable case today.
+    if (tail === ".." || tail.startsWith("../")) {
+        throw new Error(`toSandboxPath: host path escapes the workspace root: ${hostAbsPath}`);
+    }
+    return tail === "" ? `/${resourceId}` : `/${resourceId}/${tail}`;
+}
+/**
+ * Parent of every preview, workspace-root-relative. Callers that enumerate
+ * previews join this; callers that address one join {@link previewDir}. Both
+ * spell the segment through this constant so the tree has one owner.
+ */
+export const PREVIEWS_ROOT = "previews";
+/**
+ * Versioned preview directory, workspace-root-relative. Previews live inside
+ * the analysis tree (`previews/{previewId}/v{N}`); the content-token `res`
+ * claim keeps the separate `previews/{analysisId}/{previewId}` formula in
+ * `contracts/content-url.ts` — that is URL space, not a filesystem sub-path,
+ * and hosts that serve previews map one onto the other themselves.
+ */
+export function previewVersionDir(previewId, version) {
+    return `${previewDir(previewId)}/v${version}`;
+}
+/** Preview root for a specific preview (all versions), workspace-root-relative. */
+export function previewDir(previewId) {
+    assertSafeId(previewId, "previewId");
+    return `${PREVIEWS_ROOT}/${previewId}`;
+}
+/**
+ * Find the highest version number from a list of version directory names.
+ * Expects names like "v1", "v2", etc. Returns 0 if no versions found.
+ */
+export function latestPreviewVersion(dirNames) {
+    let max = 0;
+    for (const name of dirNames) {
+        const match = name.match(/^v(\d+)$/);
+        if (match) {
+            const n = parseInt(match[1], 10);
+            if (n > max)
+                max = n;
+        }
+    }
+    return max;
+}
+/**
+ * For an analysis-rooted input (`/{analysisId}/...`), strip the leading
+ * `/{analysisId}/` segment so it can be resolved relative to the analysis
+ * root. Returns `null` if the first segment does not match `analysisId` —
+ * paths under a different analysis or system paths like `/etc/passwd` are
+ * rejected here.
+ */
+function stripAnalysisRoot(path, analysisId) {
+    const withoutLead = path.slice(1);
+    const slashIdx = withoutLead.indexOf("/");
+    const firstSegment = slashIdx === -1 ? withoutLead : withoutLead.slice(0, slashIdx);
+    if (firstSegment !== analysisId)
+        return null;
+    return slashIdx === -1 ? "" : withoutLead.slice(slashIdx + 1);
+}
+const SAFE_ID = /^[\w.-]+$/;
+/**
+ * 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 function isSafeId(value) {
+    return SAFE_ID.test(value) && value !== "." && value !== "..";
+}
+/**
+ * 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 function assertSafeId(value, label) {
+    if (!isSafeId(value)) {
+        throw new Error(`Invalid ${label}: ${value}`);
+    }
+}
+/** Root directory for a specific workflow run, workspace-root-relative. */
+export function runDir(runId) {
+    assertSafeId(runId, "runId");
+    return `runs/${runId}`;
+}
+/** Step directory within a run, workspace-root-relative. */
+export function runStepDir(runId, stepId) {
+    assertSafeId(runId, "runId");
+    assertSafeId(stepId, "stepId");
+    return `runs/${runId}/${stepId}`;
+}
+export function stepSubdir(stepBase, type) {
+    return `${stepBase}/${type}`;
+}
+/** Report output directory, workspace-root-relative. */
+export function reportDir(reportId) {
+    assertSafeId(reportId, "reportId");
+    return `reports/${reportId}`;
+}
+/** All standard subdirectory types for a step. */
+export const STEP_SUBDIRS = ["scripts", "output", "figures", "logs", "notebooks"];
+/** Get all subdirectory paths for a step. */
+export function allStepSubdirs(stepBase) {
+    return STEP_SUBDIRS.map((type) => stepSubdir(stepBase, type));
+}

package/dist/workspace/provenance-collector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Provenance collector seam — the mutate surface records a SHA-256 content
+ * snapshot at each write. Construction-time dependency (see the harness-durable-runtime spec): the
+ * composition root builds a `ProvenanceCollector` and passes it to the
+ * mutate tool factories.
+ *
+ * Captured here are *harness-side* writes (`write_file`, `edit_file`). The
+ * harness does NOT hash in-sandbox writes produced by `execute_command`'s
+ * arbitrary commands — sandbox-server emits its own provenance frames per
+ * `sandbox-provenance-tracking` and artifact registration reconciles them.
+ *
+ * `recordSnapshot` is best-effort metadata: collector failures SHALL NOT
+ * fail the write. The mutate tools catch and log internally; this contract
+ * does not require the collector to be non-throwing.
+ */
+export interface ProvenanceSnapshot {
+    readonly analysisId: string;
+    readonly runId: string;
+    readonly stepId: string;
+    /**
+     * The resolved workspace path of the written file — the sandbox-visible
+     * path (e.g. `/{analysisId}/runs/{runId}/{stepId}/output/x.csv`), which is
+     * the same path the read surface uses.
+     */
+    readonly path: string;
+    /** Lowercase hex SHA-256 of the *written* content (post-edit for edit_file). */
+    readonly sha256: string;
+    readonly bytes: number;
+    /** Unix milliseconds at the time of recording. */
+    readonly timestamp: number;
+}
+export interface ProvenanceCollector {
+    recordSnapshot(snapshot: ProvenanceSnapshot): Promise<void>;
+}

package/dist/workspace/provenance-collector.js

@@ -0,0 +1,16 @@
+/**
+ * Provenance collector seam — the mutate surface records a SHA-256 content
+ * snapshot at each write. Construction-time dependency (see the harness-durable-runtime spec): the
+ * composition root builds a `ProvenanceCollector` and passes it to the
+ * mutate tool factories.
+ *
+ * Captured here are *harness-side* writes (`write_file`, `edit_file`). The
+ * harness does NOT hash in-sandbox writes produced by `execute_command`'s
+ * arbitrary commands — sandbox-server emits its own provenance frames per
+ * `sandbox-provenance-tracking` and artifact registration reconciles them.
+ *
+ * `recordSnapshot` is best-effort metadata: collector failures SHALL NOT
+ * fail the write. The mutate tools catch and log internally; this contract
+ * does not require the collector to be non-throwing.
+ */
+export {};

package/dist/workspace/search-config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared search configuration — vector index naming and creation.
+ *
+ * Used by both write-time workspaces (sandbox, data-profile) and
+ * read-time workspaces (chat, workflow agents) so they share the
+ * same persistent per-analysis pgvector index.
+ */
+import type { Pool } from "pg";
+/** Derive the vector index name for an analysis. */
+export declare function searchIndexName(resourceId: string): string;
+/**
+ * Ensure the per-analysis pgvector index exists and has an HNSW index
+ * attached. Idempotent across the process lifetime and across concurrent
+ * replicas (`CREATE … IF NOT EXISTS`).
+ *
+ * `dimensions` is the wired `EmbeddingProvider.dimensions` — the provider is
+ * the single source of the vector width, so indexes created here always match
+ * what the write-side embedder emits. A pre-existing index created at another
+ * width is left as-is (`IF NOT EXISTS`); the mismatch surfaces at the vector
+ * upsert. Per-analysis dimension tracking / re-embedding on a provider switch
+ * is a deliberate non-feature for now.
+ */
+export declare function ensureSearchIndex(pool: Pool, resourceId: string, dimensions: number): Promise<void>;

package/dist/workspace/search-config.js

@@ -0,0 +1,43 @@
+/**
+ * Shared search configuration — vector index naming and creation.
+ *
+ * Used by both write-time workspaces (sandbox, data-profile) and
+ * read-time workspaces (chat, workflow agents) so they share the
+ * same persistent per-analysis pgvector index.
+ */
+import { createVectorStore } from "../state/vector-store.js";
+import { unwrapOrThrow } from "../lib/result.js";
+/** Derive the vector index name for an analysis. */
+export function searchIndexName(resourceId) {
+    return `search_${resourceId.replace(/-/g, "_")}`;
+}
+const _ensuredIndexes = new Set();
+/**
+ * Ensure the per-analysis pgvector index exists and has an HNSW index
+ * attached. Idempotent across the process lifetime and across concurrent
+ * replicas (`CREATE … IF NOT EXISTS`).
+ *
+ * `dimensions` is the wired `EmbeddingProvider.dimensions` — the provider is
+ * the single source of the vector width, so indexes created here always match
+ * what the write-side embedder emits. A pre-existing index created at another
+ * width is left as-is (`IF NOT EXISTS`); the mismatch surfaces at the vector
+ * upsert. Per-analysis dimension tracking / re-embedding on a provider switch
+ * is a deliberate non-feature for now.
+ */
+export async function ensureSearchIndex(pool, resourceId, dimensions) {
+    const name = searchIndexName(resourceId);
+    if (_ensuredIndexes.has(name))
+        return;
+    const store = createVectorStore(pool);
+    unwrapOrThrow(await store.createIndex({
+        indexName: name,
+        dimension: dimensions,
+        metric: "cosine",
+    }));
+    unwrapOrThrow(await store.buildIndex({
+        indexName: name,
+        metric: "cosine",
+        indexConfig: { type: "hnsw" },
+    }));
+    _ensuredIndexes.add(name);
+}

package/dist/workspace/workspace-paths.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Workspace paths — single source of truth for all agent-visible paths.
+ *
+ * Composes mount points (buildMountPaths()) with step subdirectory types
+ * (STEP_SUBDIRS) into the full paths that agents use in workspace tools.
+ *
+ * Import from here — not from mount-strategy or paths directly — when
+ * you need paths that agents will see.
+ */
+import { buildMountPaths } from "./mount-strategy.js";
+import { STEP_SUBDIRS, type StepSubdirType } from "./paths.js";
+export { buildMountPaths };
+export { STEP_SUBDIRS, type StepSubdirType };
+/**
+ * Build artifact subdirectory paths for a step using canonical mount paths.
+ * Agents see these paths in workspace tools and prompts.
+ */
+export declare function buildArtifactDirs(resourceId: string, runId: string, stepId: string): {
+    readonly OUTPUT: `/${string}/output`;
+    readonly SCRIPTS: `/${string}/scripts`;
+    readonly FIGURES: `/${string}/figures`;
+    readonly LOGS: `/${string}/logs`;
+    readonly NOTEBOOKS: `/${string}/notebooks`;
+};
+/** Resolved sessions base path. */
+export declare function sessionsBasePath(sessionsBasePath: string): string;

package/dist/workspace/workspace-paths.js

@@ -0,0 +1,31 @@
+/**
+ * Workspace paths — single source of truth for all agent-visible paths.
+ *
+ * Composes mount points (buildMountPaths()) with step subdirectory types
+ * (STEP_SUBDIRS) into the full paths that agents use in workspace tools.
+ *
+ * Import from here — not from mount-strategy or paths directly — when
+ * you need paths that agents will see.
+ */
+import { buildMountPaths } from "./mount-strategy.js";
+import { STEP_SUBDIRS } from "./paths.js";
+export { buildMountPaths };
+export { STEP_SUBDIRS };
+/**
+ * Build artifact subdirectory paths for a step using canonical mount paths.
+ * Agents see these paths in workspace tools and prompts.
+ */
+export function buildArtifactDirs(resourceId, runId, stepId) {
+    const mp = buildMountPaths(resourceId, runId, stepId);
+    return {
+        OUTPUT: `${mp.ARTIFACTS}/output`,
+        SCRIPTS: `${mp.ARTIFACTS}/scripts`,
+        FIGURES: `${mp.ARTIFACTS}/figures`,
+        LOGS: `${mp.ARTIFACTS}/logs`,
+        NOTEBOOKS: `${mp.ARTIFACTS}/notebooks`,
+    };
+}
+/** Resolved sessions base path. */
+export function sessionsBasePath(sessionsBasePath) {
+    return sessionsBasePath;
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@inflexa-ai/harness",
+  "version": "0.1.1",
+  "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/inflexa-ai/inflexa.git",
+    "directory": "harness"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier --write src/",
+    "format:file": "prettier --write",
+    "lint": "eslint .",
+    "prepare": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run build && bun run smoke",
+    "smoke": "node scripts/smoke.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^4.0.5",
+    "@ai-sdk/openai-compatible": "^3.0.3",
+    "@ai-sdk/provider": "^4.0.1",
+    "@anthropic-ai/sdk": "^0.107.0",
+    "@dbos-inc/dbos-sdk": "^4.23.0",
+    "@kubernetes/client-node": "^1.0.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/core": "^2.8.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.219.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.219.0",
+    "@opentelemetry/resources": "^2.8.0",
+    "@opentelemetry/sdk-metrics": "^2.8.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "ai": "^7.0.11",
+    "cheerio": "^1.0.0",
+    "dockerode": "^4.0.0",
+    "fast-xml-parser": "^5.7.0",
+    "hono": "^4.0.0",
+    "js-tiktoken": "^1.0.0",
+    "mime": "^4.0.0",
+    "nanoid": "^5.0.0",
+    "neverthrow": "^8.2.0",
+    "nunjucks": "^3.2.4",
+    "openai": "^4.77.0",
+    "pdf-parse": "^2.4.0",
+    "pg": "^8.13.0",
+    "pino": "^10.3.1",
+    "puppeteer-core": "^23.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/bun": "latest",
+    "@types/dockerode": "^3.3.0",
+    "@types/node": "^24.0.0",
+    "@types/nunjucks": "^3.2.6",
+    "@types/pdf-parse": "^1.1.4",
+    "@types/pg": "^8.11.0",
+    "eslint": "^10.4.1",
+    "eslint-plugin-neverthrow": "^1.1.4",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.1",
+    "testcontainers": "^10.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "patchedDependencies": {
+    "eslint-plugin-neverthrow@1.1.4": "patches/eslint-plugin-neverthrow@1.1.4.patch"
+  }
+}