@inflexa-ai/harness 0.31.1 → 0.33.0

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

@@ -1,26 +1,25 @@
 /**
- * listAvailablePackages — query the R/Python/CLI/Node packages available in the
- * sandbox.
+ * listAvailablePackages — query the R/Python/CLI/Node packages of the
+ * environment, from the inventory source the embedder binds.
  *
- * The data source is the store's `packages.txt`, assembled by the library-store
- * build (see the lib-store-build spec) and read from wherever the HOST can see
- * it — the container path when the host mounts the same store, an injected path
- * when it does not. Its shape is fixed by the
- * producers (`scripts/lib-store-common.sh`, `images/sandbox-python/inflexa-libs-refresh`):
- * two `#` advisory lines, then one `## <Section>` heading per language track
- * followed by that track's packages as a single comma-separated line.
+ * Two sources exist, one per vantage. A SANDBOX agent reads the
+ * `inflexa.lock` of the mounted farm — what a step can import right now —
+ * from wherever the HOST can see it: the farm container path when the host
+ * mounts the same farm, an injected path when it does not. A CONVERSATION or
+ * planning surface reads the pool-scope inventory (`readPoolInventory`) —
+ * everything the store holds, whether or not a farm links it yet — because
+ * the ask flow marks the packages the POOL does not hold, and the farm of a
+ * new analysis is empty. The baked image inventory fragment
+ * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
+ * report when the host can read one. The fragment keeps the section format:
  *
- *     # Available packages in the sandbox environment.
- *     # Do NOT attempt to install packages — ...
+ *     ## System tools (CLI)
+ *     samtools, bcftools, ...
  *
- *     ## R (CRAN)
- *     Seurat, dplyr, ggplot2, ...
- *
- *     ## Python (pip)
- *     anndata, scanpy, ...
- *
- * The file carries **names only — there are no version strings in it**, so this
- * tool reports presence and language track and cannot report a version.
+ * Each entry renders as `name==version` where the source pins a version, and
+ * a targeted `names` lookup also carries the store directory and the full
+ * content hash where the source records them. A full listing carries no
+ * hashes — a thousand rows of sha256 would bury the signal.
  */
 import { readFile } from "node:fs/promises";
 import { ok } from "neverthrow";
@@ -28,12 +27,45 @@ 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";
+import { readFarmLockFile } from "../../sandbox/farm.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.
+ * Where the lock lives when the host mounts the farm at the same path the
+ * sandbox does. Both farm container paths are tried, because the path keys on
+ * the declared toolchain (`/mnt/libs/farm` under `"image"`, `/mnt/libs/current`
+ * under `"store"`), and the tool does not carry that declaration. A host that
+ * reads the farm somewhere else injects its own path instead.
  */
-const DEFAULT_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/current/packages.txt`;
+const DEFAULT_FARM_LOCK_FILES = [`${LIBS_CONTAINER_PATH}/farm/inflexa.lock`, `${LIBS_CONTAINER_PATH}/current/inflexa.lock`];
+/** Where the baked image inventory fragment lives inside the image. */
+const DEFAULT_IMAGE_PACKAGES_FILE = "/opt/inflexa/image-packages.txt";
+/** The section title of each known lock track. An unknown track titles itself. */
+const TRACK_TITLES = {
+    python: "Python (pip)",
+    cran: "R (CRAN)",
+    bioconductor: "R (Bioconductor)",
+    github: "R (GitHub)",
+    node: "Node (npm)",
+};
+/**
+ * Group the lock packages into sections, one per track, in a stable order:
+ * the known tracks first, then an unknown track at its first occurrence.
+ * Each entry keeps the lock's version, store directory, and hash, so the
+ * targeted `names` path can report the exact store identity.
+ */
+export function lockSections(lock) {
+    const byTrack = new Map();
+    for (const track of Object.keys(TRACK_TITLES))
+        byTrack.set(track, []);
+    for (const pkg of lock.packages) {
+        const entry = { name: pkg.name, version: pkg.version, storeDir: pkg.store_dir, hash: pkg.hash };
+        const open = byTrack.get(pkg.track);
+        if (open)
+            open.push(entry);
+        else
+            byTrack.set(pkg.track, [entry]);
+    }
+    return [...byTrack.entries()].filter(([, packages]) => packages.length > 0).map(([track, packages]) => ({ title: TRACK_TITLES[track] ?? track, packages }));
+}
 /**
  * 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
@@ -49,11 +81,18 @@ const DEFAULT_LIMIT = 2_000;
  * check, and an agent told to "assume numpy is available" will import it and
  * fail at runtime instead of probing first.
  */
-const UNAVAILABLE_NOTE = "Package list not available — the library store's inventory could not be read, so what is installed is UNKNOWN. " +
+const UNAVAILABLE_NOTE = "Package list not available — the inventory of the farm could not be read, so what is installed is UNKNOWN. " +
     "Do not assume any package is present, and do not infer one from the analysis you were asked to run. " +
     "Probe each package you intend to use before relying on it (`python3 -c 'import <pkg>'`, " +
     'R `requireNamespace("<pkg>", quietly = TRUE)`) and degrade gracefully when it is absent. ' +
     "Nothing can be installed at runtime.";
+/**
+ * The pool-scope twin of {@link UNAVAILABLE_NOTE}. It names no runtime probe,
+ * because a conversation surface has no runtime to probe, and an unreadable
+ * pool must read as UNKNOWN rather than as empty.
+ */
+const POOL_UNAVAILABLE_NOTE = "Package list not available — the package pool could not be read, so what the store holds is UNKNOWN. " +
+    "Do not assume a package is present, and do not report a package as absent.";
 /** The `language` filter values, mapped onto the concrete section headings. */
 const LANGUAGE_MATCHERS = {
     // The R triple: `R (CRAN)`, `R (Bioconductor)`, `R (GitHub)`.
@@ -87,11 +126,15 @@ export function parsePackagesFile(content) {
         for (const name of trimmed.split(",")) {
             const pkg = name.trim();
             if (pkg)
-                open.packages.push(pkg);
+                open.packages.push({ name: pkg });
         }
     }
     return sections;
 }
+/** One entry as the listing renders it: `name==version` where the source pins a version, the bare name otherwise. */
+function renderPackage(entry) {
+    return entry.version === undefined ? entry.name : `${entry.name}==${entry.version}`;
+}
 /** Render sections to the agent-facing listing, bounded at `limit` packages. */
 function renderListing(sections, limit) {
     const lines = [];
@@ -106,7 +149,7 @@ function renderListing(sections, limit) {
         }
         const shown = section.packages.slice(0, room);
         returned += shown.length;
-        lines.push(`\n## ${section.title}`, `  ${shown.join(", ")}`);
+        lines.push(`\n## ${section.title}`, `  ${shown.map(renderPackage).join(", ")}`);
         const hidden = section.packages.length - shown.length;
         if (hidden > 0)
             lines.push(`  … and ${hidden} more in this section (raise \`limit\` or narrow with \`query\`).`);
@@ -126,15 +169,26 @@ export function queryPackages(sections, { names, query, language, limit }) {
             for (const pkg of section.packages) {
                 // First writer wins: `packages.txt` sections are ordered, so a name
                 // colliding across tracks resolves to the earliest one.
-                if (!index.has(pkg.toLowerCase()))
-                    index.set(pkg.toLowerCase(), { name: pkg, section: section.title });
+                if (!index.has(pkg.name.toLowerCase()))
+                    index.set(pkg.name.toLowerCase(), { entry: pkg, section: section.title });
             }
         }
         const checked = names.map((requested) => {
             const hit = index.get(requested.trim().toLowerCase());
+            if (!hit)
+                return { requested, present: false };
             // `name` echoes the catalog's canonical spelling — R package names are
             // case-sensitive at `library()`, so the exact one is what the caller needs.
-            return hit ? { requested, present: true, name: hit.name, section: hit.section } : { requested, present: false };
+            // The store identity rides only where the source records it.
+            return {
+                requested,
+                present: true,
+                name: hit.entry.name,
+                section: hit.section,
+                ...(hit.entry.version === undefined ? {} : { version: hit.entry.version }),
+                ...(hit.entry.storeDir === undefined ? {} : { storeDir: hit.entry.storeDir }),
+                ...(hit.entry.hash === undefined ? {} : { hash: hit.entry.hash }),
+            };
         });
         return { available: true, checked };
     }
@@ -144,7 +198,7 @@ export function queryPackages(sections, { names, query, language, limit }) {
         .filter((s) => matchesLanguage(s.title))
         .map((s) => ({
         title: s.title,
-        packages: needle ? s.packages.filter((p) => p.toLowerCase().includes(needle)) : s.packages,
+        packages: needle ? s.packages.filter((p) => p.name.toLowerCase().includes(needle)) : s.packages,
     }))
         .filter((s) => s.packages.length > 0);
     const total = filtered.reduce((n, s) => n + s.packages.length, 0);
@@ -161,18 +215,36 @@ export function queryPackages(sections, { names, query, language, limit }) {
     const { content, returned } = renderListing(filtered, limit ?? DEFAULT_LIMIT);
     return { available: true, total, returned, hasMore: returned < total, content };
 }
-/** Create the package inventory over a host-readable `packages.txt`. */
+/**
+ * Create the package inventory over the bound source: the pool-scope reader
+ * when the embedder binds one (a conversation or planning surface), the
+ * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
+ * fragment merges into either report.
+ */
 export function createListAvailablePackagesTool(deps = {}) {
-    const packagesFile = deps.packagesFile ?? DEFAULT_PACKAGES_FILE;
+    const lockCandidates = deps.farmLockFile ? [deps.farmLockFile] : DEFAULT_FARM_LOCK_FILES;
+    const imagePackagesFile = deps.imagePackagesFile ?? DEFAULT_IMAGE_PACKAGES_FILE;
+    const readPoolInventory = deps.readPoolInventory;
+    // The scope decides the framing sentence: a sandbox agent reads what it can
+    // import NOW, and a conversation surface reads what the store HOLDS — a
+    // package absent from the pool needs an acquisition, not a shrug. A sandbox
+    // composition with the link seam gets a third framing. There the farm is
+    // not the boundary of an import, and a closed-world sentence would send the
+    // agent to report a package that one link call supplies.
+    const scopeSentence = readPoolInventory
+        ? "Query the R, Python, CLI, and Node packages the package pool holds — the set a run can link into an analysis. A package reported present needs no acquisition; a package absent here is not in the store yet. "
+        : deps.linkToolPresent
+            ? "Query the R, Python, CLI, and Node packages importable in the sandbox right now. Nothing installs at runtime; a package absent here can still be linkable from the host's staged pool — call `link_packages` before treating it as missing. "
+            : "Query the R, Python, CLI, and Node packages installed in the sandbox. No packages can be installed at runtime — only what this tool reports is importable. ";
     return defineTool({
         id: "list_available_packages",
-        description: "Query the R, Python, CLI, and Node packages installed in the sandbox. No packages can be installed at runtime — only what this tool reports is importable. " +
+        description: scopeSentence +
             "A full listing is small (a few hundred packages) and is returned whole by default, so a listing you get back is the complete set unless `hasMore` says otherwise. " +
             '`names`: check specific packages (e.g. ["Seurat", "scanpy"]) — returns present/absent plus the language track for each, case-insensitively; this is the cheapest call and the right one for \'is X available?\'. ' +
             "`query`: case-insensitive substring filter over package names. " +
             "`language`: restrict to one track (r | python | cli | node). " +
             "`limit`: cap the packages listed; the response always carries the true `total` and a `hasMore` flag, so truncation is never silent. " +
-            'The package list carries NO version numbers — this tool cannot report a package\'s version. Check a version at runtime instead (e.g. `python -c "import scanpy; print(scanpy.__version__)"`).',
+            "Each entry renders as `name==version` where the source pins a version, and a `names` check also reports the store directory and the content hash where the source records them.",
         inputSchema: z.object({
             names: z
                 .array(z.string())
@@ -212,16 +284,35 @@ export function createListAvailablePackagesTool(deps = {}) {
             return "full package list";
         },
         execute: async (input) => {
+            // The baked image fragment merges in when the host can read one; a
+            // missing fragment merges nothing, and that is the normal state for
+            // a host that runs outside the image.
+            const fragmentSections = await readFile(imagePackagesFile, "utf-8")
+                .then(parsePackagesFile)
+                .catch(() => []);
             // An unreadable inventory is an expected environment state — model it as an
-            // `available: false` data variant telling the caller the set is UNKNOWN.
-            let raw;
-            try {
-                raw = await readFile(packagesFile, "utf-8");
+            // `available: false` data variant telling the caller the set is UNKNOWN,
+            // WITH the reason: without it, a structural fault (a damaged dependency
+            // graph) reads as a transient flake, and the caller retries for ever.
+            if (readPoolInventory) {
+                const pool = await readPoolInventory().catch((cause) => ({
+                    kind: "unavailable",
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                }));
+                if (pool.kind === "unavailable")
+                    return ok({ available: false, content: `${POOL_UNAVAILABLE_NOTE} The reason: ${pool.reason}.` });
+                return ok(queryPackages([...pool.sections, ...fragmentSections], input));
+            }
+            let lock = null;
+            for (const candidate of lockCandidates) {
+                lock = readFarmLockFile(candidate).unwrapOr(null);
+                if (lock !== null)
+                    break;
             }
-            catch {
+            if (lock === null) {
                 return ok({ available: false, content: UNAVAILABLE_NOTE });
             }
-            return ok(queryPackages(parsePackagesFile(raw), input));
+            return ok(queryPackages([...lockSections(lock), ...fragmentSections], input));
         },
     });
 }

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

@@ -24,6 +24,7 @@ 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";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 /**
  * The brief of the ask, plus the one override of the advice.
  *
@@ -101,6 +102,12 @@ export interface StartReportSessionToolDeps {
      * carries no stale value of its own.
      */
     readonly anchorSession?: (threadId: string) => Promise<EnsureSessionStateResult>;
+    /**
+     * The provenance seam of the composition. The tool hands it to the spawn,
+     * which emits the creation of the session at the moment that the child lands.
+     * The tool emits nothing of its own.
+     */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /**

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

@@ -111,6 +111,7 @@ export function createStartReportSessionTool(deps) {
         chrome: deps.chrome,
         ...(deps.eyes ? { eyes: deps.eyes } : {}),
         ...(deps.anchorSession ? { anchorSession: deps.anchorSession } : {}),
+        ...(deps.provenance ? { provenance: deps.provenance } : {}),
         ...(deps.logger ? { logger: deps.logger } : {}),
     };
     const spawn = createReportSessionSpawn(spawnDeps);

package/dist/workflows/execute-analysis.d.ts

@@ -69,6 +69,7 @@ import type { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.j
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { RunCharge } from "../billing/run-charge.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type PlanStep } from "./execute-analysis-scheduler.js";
@@ -154,63 +155,6 @@ export interface ExecuteAnalysisResult {
     readonly failedSteps: readonly string[];
     readonly canceledSteps: readonly string[];
 }
-/**
- * A run-lifecycle provenance observation handed to an optional host observer.
- * Harness-owned plain union — the harness stays tsprov-free and bus-free; the
- * host maps these execution facts onto its own ledger vocabulary.
- *
- * Every `atMs` is epoch milliseconds read via `await DBOS.now()`, a checkpointed
- * step: a body re-executed by DBOS recovery reads the recorded value, so a
- * re-emitted event carries the identical timestamp and merges on the host's
- * ledger without a value conflict. Never source these from a wall clock
- * (`Date.now()`) — that would diverge across replays and defeat the merge.
- *
- * `run_completed.durationMs` is the terminal `atMs` minus the `run_started`
- * `atMs` (both `DBOS.now()` reads) — the true workflow-observed run span.
- *
- * `step_completed` fires once at EVERY scheduler-loop settlement — the only site
- * that observes every executed step (registration sees only artifact-producing
- * steps, and a child cannot observe its own parent-driven cancel). Steps that
- * were never dispatched (dependents of a failed sibling) emit nothing by design;
- * the run's terminal status carries that outcome. `status` maps the settlement
- * outcome: `complete` → `"completed"`, `canceled` → `"canceled"`,
- * `failed`/`blocked`/child-error → `"failed"`.
- *
- * `run_completed` fires at BOTH terminal boundaries (success and failure); the
- * `status` field distinguishes them.
- */
-export type RunProvenanceEvent = {
-    type: "run_started";
-    analysisId: string;
-    runId: string;
-    planSummary: string;
-    stepCount: number;
-    atMs: number;
-} | {
-    type: "step_completed";
-    analysisId: string;
-    runId: string;
-    stepId: string;
-    /** Settlement outcome mapped to a terminal step status. */
-    status: "completed" | "failed" | "canceled";
-    /** The child's durable execution duration; absent when the child settled by throwing. */
-    durationMs?: number;
-    atMs: number;
-} | {
-    type: "run_completed";
-    analysisId: string;
-    runId: string;
-    /**
-     * The body's terminal status. Both boundary sites resolve it through `deriveFinalStatus`,
-     * which records a budget pause as `"canceled"` — so `"suspended_insufficient_funds"` (a
-     * `RunStatus` member) is never emitted here and is deliberately absent from this narrower
-     * `ExecuteAnalysisFinalStatus`-minus-`"running"` set.
-     */
-    status: Exclude<ExecuteAnalysisFinalStatus, "running">;
-    atMs: number;
-    /** `atMs − run_started.atMs`: the workflow-observed run span in ms. */
-    durationMs: number;
-};
 /**
  * A step's in-run display state. Wider than the ledger's `StepExecutionStatus`: `queued` is a
  * scheduler-only condition (dependency-satisfied but held for budget capacity) that never reaches a
@@ -291,9 +235,11 @@ export interface ExecuteAnalysisDeps {
      */
     readonly usageRecorder?: UsageRecorder;
     /**
-     * Optional, fire-and-forget provenance observation of the run lifecycle.
-     * Deliberately invoked directly in the workflow body (NOT wrapped in
-     * `DBOS.runStep`) so that body re-execution on DBOS recovery re-fires it —
+     * The provenance seam of the composition. The body reads its run emit member,
+     * and it reads no other member.
+     *
+     * The emit is deliberately invoked directly in the workflow body (NOT wrapped
+     * in `DBOS.runStep`) so that body re-execution on DBOS recovery re-fires it —
      * a cached step would suppress the recovery re-emission, defeating the
      * point. Idempotency is the consumer's job, achieved via the deterministic
      * identifiers the events carry, not via step caching. Every call site is
@@ -303,19 +249,19 @@ export interface ExecuteAnalysisDeps {
      * persisting realization needs its credential, scope, and identity.
      * Implementations may ignore the parameter.
      */
-    readonly emitProvenance?: (event: RunProvenanceEvent, session: RunSession) => void;
+    readonly provenance?: ProvenanceSeam;
     /**
      * Optional, fire-and-forget observation of the run's live shape, for a host driving a UI.
      *
-     * Independent of {@link emitProvenance} in every direction: neither is implemented in terms of
-     * the other, they share no payload, and supplying one does not imply the other. They exist
-     * separately because provenance closes a signed, hash-chained record under a single-writer
-     * lock, while this is a lossy-tolerant display channel — coupling them would put a UI repaint
-     * behind the chain's write discipline and force provenance to carry step names and agent ids it
-     * has no reason to record.
+     * Independent of the run emit of {@link provenance} in every direction: neither is implemented
+     * in terms of the other, they share no payload, and supplying one does not imply the other.
+     * They exist separately because provenance closes a signed, hash-chained record under a
+     * single-writer lock, while this is a lossy-tolerant display channel — coupling them would put
+     * a UI repaint behind the chain's write discipline and force provenance to carry step names and
+     * agent ids it has no reason to record.
      *
-     * Invoked directly in the workflow body (NOT wrapped in `DBOS.runStep`) for the same reason
-     * `emitProvenance` is: body re-execution on recovery must re-fire it, and a cached step would
+     * Invoked directly in the workflow body (NOT wrapped in `DBOS.runStep`) for the same reason the
+     * run emit is: body re-execution on recovery must re-fire it, and a cached step would
      * suppress that. Idempotency comes free for rendering because the payload is a whole-run
      * snapshot; a host taking a DURABLE side effect on one must key it by run id and status itself.
      *

package/dist/workflows/execute-analysis.js

@@ -88,14 +88,15 @@ function emitStreamPart(part) {
  * host's own ledger, not here.
  */
 function emitProvenanceGuarded(deps, event, session) {
-    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis");
-    if (!deps.emitProvenance)
+    const emit = deps.provenance?.emitRunEvent;
+    if (!emit)
         return;
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis");
     try {
-        deps.emitProvenance(event, session);
+        emit(event, session);
     }
     catch (err) {
-        logger.error("emitProvenance threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
+        logger.error("the run emit of the provenance seam threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.31.1",
+    "version": "0.33.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -56,6 +56,7 @@
         "@dbos-inc/dbos-sdk": "^4.23.6",
         "@fontsource-variable/space-grotesk": "5.1.1",
         "@fontsource/ibm-plex-mono": "5.1.1",
+        "@inflexa-ai/tsprov": "0.6.0",
         "@kubernetes/client-node": "^1.4.0",
         "@opentelemetry/api": "^1.9.1",
         "@opentelemetry/core": "^2.9.0",