@inflexa-ai/harness 0.24.0 → 0.25.0

package/dist/agents/sandbox/__fixtures__/deps.js

@@ -30,6 +30,9 @@ export function makeFakeSandboxClient() {
         async isAlive() {
             return { alive: true, oomKilled: false };
         },
+        async isAliveById() {
+            return { alive: true, oomKilled: false };
+        },
         async teardown() { },
         async teardownById() { },
         async listManagedSandboxes() {
@@ -42,6 +45,9 @@ export function makeFakeWorkspaceFs() {
         readFile() {
             return okAsync({ kind: "ok", content: Buffer.alloc(0), truncated: false });
         },
+        readBytes() {
+            return okAsync({ kind: "ok", bytes: Buffer.alloc(0) });
+        },
         list() {
             return okAsync({ kind: "ok", entries: [] });
         },

package/dist/agents/sandbox/data-profiler.js

@@ -10,10 +10,11 @@ export const meta = {
     capabilities: ["data profiling", "literature review", "methodology research", "analysis planning", "experimental design analysis"],
     suitableFor: ["bulk-rna-seq", "single-cell", "proteomics", "metabolomics", "genomics", "transcriptomics", "chemical-structures", "compound-screening"],
     skills: [],
-    tools: [...BASE_SANDBOX_TOOLS],
-    // Profiling fans out one programmatic pass per input file (head/wc preview +
-    // a Python script + read-back) before the single submit_profile, so a
-    // many-file analysis needs more headroom than the sandbox default.
+    // `scanInputs` is the profiler's own instrument: the workflow injects one scan into
+    // its briefing, and the tool is how it re-scans a subtree it wants to group
+    // differently. Declared rather than bolted on, so the resolved roster stays
+    // `meta.tools` plus the always-on set.
+    tools: [...BASE_SANDBOX_TOOLS, "scanInputs"],
     defaultMaxSteps: 85,
     plannable: false,
 };

package/dist/agents/sandbox/shared.js

@@ -30,6 +30,7 @@ import { chemblTool, genePreclinicalProfileTool, lookupAnnotationTool, openTarge
 import { createNcbiTools, createChemDbTools } from "../../tools/bio/keys.js";
 // Workspace read surface.
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../../tools/workspace/index.js";
+import { createScanInputsTool } from "../../tools/workspace/scan-inputs.js";
 // Workspace mutate surface.
 import { createEditFileTool, createExecuteCommandTool, createWorkspaceMutator, createWriteFileTool } from "../../tools/workspace/index.js";
 // Skills (declared per agent via meta.skills).
@@ -60,6 +61,16 @@ function resolveSandboxTools(deps, tools) {
     const registry = {
         listAvailablePackages: createListAvailablePackagesTool({ ...(deps.packagesFile ? { packagesFile: deps.packagesFile } : {}) }),
         listAvailableRefs: createListAvailableRefsTool({ ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}) }),
+        scanInputs: createScanInputsTool({
+            workspaceFs: deps.workspaceFs,
+            analysisId: deps.step.analysisId,
+            sandboxClient: deps.sandboxClient,
+            sandbox: deps.step.sandbox,
+            workflowId: deps.step.workflowId,
+            stepId: deps.step.stepId,
+            nextFunctionId: deps.step.nextFunctionId,
+            deadlineMs: deps.step.deadlineMs,
+        }),
         resolveLibraryId: resolveLibraryIdTool,
         queryDocs: queryDocsTool,
         inspectRun: createInspectRunTool(deps.pool),

package/dist/agents/sandbox/types.d.ts

@@ -12,7 +12,7 @@
  * in the tool's `perSource` report; the rest of the call still answers.
  */
 /** Closed allowlist of tools any sandbox agent may declare. */
-export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "resolveLibraryId" | "queryDocs" | "inspectRun" | "pubmed" | "resolve_citation" | "searchGene" | "lookupAnnotation" | "searchInteractions" | "chembl" | "pubchem" | "opentargets" | "geneDiseaseEvidence" | "drugGeneInteractions" | "genePreclinicalProfile" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "targetSafety" | "comptox";
+export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "scanInputs" | "resolveLibraryId" | "queryDocs" | "inspectRun" | "pubmed" | "resolve_citation" | "searchGene" | "lookupAnnotation" | "searchInteractions" | "chembl" | "pubchem" | "opentargets" | "geneDiseaseEvidence" | "drugGeneInteractions" | "genePreclinicalProfile" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "targetSafety" | "comptox";
 /** Planner-facing metadata + tool allowlist for one sandbox agent. */
 export interface AgentMeta {
     /** Stable agent id — also the key in the catalog and the `AgentDefinition.id`. */

package/dist/app/data-profile-orientation.js

@@ -18,6 +18,9 @@
 export const DATA_PROFILE_ORIENTATION_MAX_CHARS = 1200;
 /** Files listed before the tail is elided (the count still reports the total). */
 const MAX_FILES = 8;
+/** Kinds listed before the tail is elided. A dataset with more is described by its first few. */
+const MAX_KINDS = 6;
+const MAX_KIND_DESCRIPTION_CHARS = 90;
 /** Quality concerns listed — the profiler orders them, so these are the top ones. */
 const MAX_CONCERNS = 3;
 const MAX_DESIGN_CHARS = 200;
@@ -105,9 +108,35 @@ export function buildDataProfileOrientation(result, maxChars = DATA_PROFILE_ORIE
         const more = concerns.length > shown.length ? ` (+${concerns.length - shown.length} more)` : "";
         lines.push(`Concerns: ${shown.join("; ")}${more}`);
     }
+    // Kinds come first because they are what the dataset IS at this budget: four lines
+    // describing 3513 files, where the per-file list could only show the first eight of
+    // them and imply the rest away.
+    const kinds = result.kinds ?? [];
+    if (kinds.length > 0) {
+        const shown = kinds.slice(0, MAX_KINDS);
+        const datasetFiles = kinds.reduce((sum, kind) => sum + kind.count, 0);
+        const header = shown.length < kinds.length
+            ? `Kinds (${shown.length} of ${kinds.length}, ${datasetFiles} files):`
+            : `Kinds (${kinds.length}, ${datasetFiles} files):`;
+        lines.push(header);
+        for (const kind of shown) {
+            const facts = [`${kind.count}x`, present(kind.format)].filter((f) => f !== undefined).join(", ");
+            lines.push(`- ${kind.name} (${facts}) — ${clip(kind.memberRepresents, MAX_KIND_DESCRIPTION_CHARS)}`);
+        }
+        const axes = result.axes ?? [];
+        if (axes.length > 0) {
+            lines.push(`Axes: ${axes.map((axis) => `${axis.label} (${axis.cardinality})`).join(", ")}`);
+        }
+        if (result.coverage && result.coverage.unmatched > 0) {
+            lines.push(`Coverage: ${result.coverage.matched} of ${result.coverage.total} files match a kind`);
+        }
+    }
     if (result.files.length > 0) {
         const shown = result.files.slice(0, MAX_FILES);
-        const header = shown.length < result.files.length ? `Files (${shown.length} of ${result.files.length}):` : `Files (${result.files.length}):`;
+        // With kinds present these are the individually notable files — the metadata
+        // sheet, the README, the outlier — not a sample of the dataset.
+        const label = kinds.length > 0 ? "Notable files" : "Files";
+        const header = shown.length < result.files.length ? `${label} (${shown.length} of ${result.files.length}):` : `${label} (${result.files.length}):`;
         lines.push(header);
         for (const file of shown) {
             lines.push(`- ${file.path} — ${clip(file.description, MAX_FILE_DESCRIPTION_CHARS)}${formatFileFacts(file)}`);

package/dist/app/data-profile-policy.d.ts

@@ -5,13 +5,37 @@
  * — staging stays embedder-side per the data-profile-init spec, and the atomic running→expired
  * flip stays an SQL guard (`expireStaleDataProfile`), not part of this decision.
  */
-export type DataProfileLifecycleStatus = "pending" | "running" | "completed" | "failed";
+import type { DataProfileInputSignature, DataProfileLifecycleStatus } from "../contracts/data-profile.js";
+export type { DataProfileLifecycleStatus };
 /**
- * A completed profile is stale when the analysis's seed input set no longer
- * matches the set the profile actually covered — a file was added or swapped
- * since profiling. An empty seed set is never stale (nothing to compare).
+ * The analysis's inputs as they are NOW. A caller holding sizes and mtimes supplies
+ * the signature; one holding only the ledger's seeded ids supplies just those, and the
+ * comparison degrades honestly to what those ids can settle.
  */
-export declare function isDataProfileStale(seedInputFileIds: readonly string[], profiledInputFileIds: readonly string[]): boolean;
+export interface CurrentInputSet {
+    readonly fileIds: readonly string[];
+    readonly signature?: DataProfileInputSignature;
+}
+/** The comparand a profile snapshot carries. Which one is present depends on its era. */
+export interface ProfiledInputSnapshot {
+    readonly inputSignature?: DataProfileInputSignature;
+    readonly inputFileIds?: readonly string[];
+}
+/**
+ * A completed profile is stale when the analysis's current input set no longer matches
+ * the set the profile actually covered.
+ *
+ * The signature is preferred where both sides carry one: it covers size and mtime as
+ * well as identity, so an in-place edit is drift too. A snapshot predating the
+ * signature falls back to its identity list rather than being treated as drift, since
+ * that list answers the same question for the set it covered. A snapshot carrying
+ * NEITHER is drift: nothing establishes what it covered, and one re-profile heals it —
+ * exactly how a wholly absent `result` is already treated.
+ *
+ * An empty current set is never stale: there is nothing to compare, and an analysis
+ * whose inputs were removed is handled by clearing the profile, not by re-profiling it.
+ */
+export declare function isDataProfileStale(current: CurrentInputSet, profiled: ProfiledInputSnapshot | null | undefined): boolean;
 export type DataProfileAction = {
     readonly kind: "none";
 } | {
@@ -21,8 +45,10 @@ export type DataProfileAction = {
 };
 export interface DataProfileDecisionInput {
     readonly status: DataProfileLifecycleStatus;
-    readonly seedInputFileIds: readonly string[];
-    readonly profiledInputFileIds: readonly string[];
+    /** The analysis's inputs as they are now — the seeded ids, plus a signature where the caller has one. */
+    readonly current: CurrentInputSet;
+    /** The comparand the stored profile carries, or null when it holds none. */
+    readonly profiled: ProfiledInputSnapshot | null;
 }
 /**
  * Decide the next profiling action from a (post-expire) status:

package/dist/app/data-profile-policy.js

@@ -6,17 +6,39 @@
  * flip stays an SQL guard (`expireStaleDataProfile`), not part of this decision.
  */
 /**
- * A completed profile is stale when the analysis's seed input set no longer
- * matches the set the profile actually covered — a file was added or swapped
- * since profiling. An empty seed set is never stale (nothing to compare).
+ * A completed profile is stale when the analysis's current input set no longer matches
+ * the set the profile actually covered.
+ *
+ * The signature is preferred where both sides carry one: it covers size and mtime as
+ * well as identity, so an in-place edit is drift too. A snapshot predating the
+ * signature falls back to its identity list rather than being treated as drift, since
+ * that list answers the same question for the set it covered. A snapshot carrying
+ * NEITHER is drift: nothing establishes what it covered, and one re-profile heals it —
+ * exactly how a wholly absent `result` is already treated.
+ *
+ * An empty current set is never stale: there is nothing to compare, and an analysis
+ * whose inputs were removed is handled by clearing the profile, not by re-profiling it.
  */
-export function isDataProfileStale(seedInputFileIds, profiledInputFileIds) {
-    if (seedInputFileIds.length === 0)
+export function isDataProfileStale(current, profiled) {
+    if (current.fileIds.length === 0 && current.signature === undefined)
         return false;
-    if (seedInputFileIds.length !== profiledInputFileIds.length)
+    if (!profiled)
         return true;
-    const profiled = new Set(profiledInputFileIds);
-    return seedInputFileIds.some((id) => !profiled.has(id));
+    if (profiled.inputSignature) {
+        // A caller with no signature of its own can still compare counts, which catches
+        // an added or removed file. It cannot catch a same-count swap, and claiming
+        // otherwise would be a verdict the comparand does not support.
+        if (!current.signature)
+            return profiled.inputSignature.count !== current.fileIds.length;
+        return profiled.inputSignature.digest !== current.signature.digest || profiled.inputSignature.count !== current.signature.count;
+    }
+    if (profiled.inputFileIds) {
+        if (current.fileIds.length !== profiled.inputFileIds.length)
+            return true;
+        const covered = new Set(profiled.inputFileIds);
+        return current.fileIds.some((id) => !covered.has(id));
+    }
+    return true;
 }
 /**
  * Decide the next profiling action from a (post-expire) status:
@@ -30,7 +52,7 @@ export function isDataProfileStale(seedInputFileIds, profiledInputFileIds) {
 export function decideDataProfileAction(input) {
     if (input.status === "pending")
         return { kind: "trigger" };
-    if (input.status === "completed" && isDataProfileStale(input.seedInputFileIds, input.profiledInputFileIds)) {
+    if (input.status === "completed" && isDataProfileStale(input.current, input.profiled)) {
         return { kind: "retrigger" };
     }
     return { kind: "none" };

package/dist/contracts/data-profile.d.ts

@@ -24,3 +24,169 @@
  * reporting the profile as an unnamed run — a failure with no red test anywhere.
  */
 export declare const DATA_PROFILE_RUN_LITERAL: "data-profile";
+/**
+ * Where an extracted subject fact came from, so a consumer can judge how much to trust
+ * it. Ordered most-direct first in the profiler's own guidance.
+ */
+export type DataProfileSubjectSource = "metadata" | "document" | "filename" | "user-context" | "inferred";
+/** The subject organism, with its provenance and the profiler's confidence in it. */
+export interface DataProfileOrganism {
+    scientificName: string;
+    /** NCBI Taxonomy ID as a string, e.g. `"9606"`. */
+    taxonId: string;
+    source: DataProfileSubjectSource;
+    confidence: "high" | "medium" | "low";
+    notes?: string;
+}
+/**
+ * One profiled file's persisted record.
+ *
+ * `path` + `description` are the original pair every snapshot carries; everything below
+ * them is optional on read, because a snapshot written before the record was widened
+ * carries only the pair.
+ */
+export interface DataProfileFile {
+    path: string;
+    description: string;
+    /** Semantic data type (count-matrix, variants, clinical-metadata, document, …). */
+    dataType?: string;
+    /** File format (CSV, h5ad, VCF, BAM, …). */
+    format?: string;
+    rows?: number | null;
+    cols?: number | null;
+    /** Searchable labels the profiler attached. */
+    tags?: string[];
+    /** Quality issues specific to this file. */
+    warnings?: string[];
+    /** Flat, identity-establishing facts (sparsity, delimiter, normalizationState, …). */
+    metrics?: Record<string, string | number | boolean>;
+}
+/** Dataset-wide quality findings the profiler recorded. */
+export interface DataProfileQualityAssessment {
+    concerns: string[];
+    strengths: string[];
+}
+/**
+ * One repeating set of files — the dataset's structure, as opposed to its contents.
+ *
+ * A kind is a claim about MEANING, made by the profiler agent: the deterministic input
+ * scan establishes that filenames differ only at one position, and cannot establish that
+ * the files are the same sort of thing. A singleton is a kind of `count` 1, so a
+ * two-file analysis is two kinds and needs no special case.
+ */
+export interface DataProfileKind {
+    name: string;
+    /** What ONE member represents. The grouping decision, stated apart from the description. */
+    memberRepresents: string;
+    description: string;
+    count: number;
+    /** Glob the members match, relative to the analysis root. Coverage is computed from it. */
+    pathPattern: string;
+    format?: string;
+    /** Labels of the `axes` that vary across this set's members. */
+    axisLabels?: string[];
+}
+/**
+ * What varies across a kind's members — the experimental design, as far as it is
+ * observable. The scan reports that a filename position varies and which values it
+ * takes; what the variation IS is the agent's label.
+ */
+export interface DataProfileAxis {
+    label: string;
+    cardinality: number;
+    exampleValues?: string[];
+    description?: string;
+}
+/**
+ * The comparand identifying WHICH files a profile covered and whether the SAME BYTES
+ * were profiled.
+ *
+ * `digest` is a stable hash over the staged inputs' identities, sizes, and mtimes in a
+ * canonical order, so it depends on the set and not on enumeration order. It excludes
+ * content hashes deliberately: enumerating those would mean reading every input in full
+ * on every parity check. An edit preserving both byte length and mtime is therefore not
+ * detected — bounded, and documented.
+ */
+export interface DataProfileInputSignature {
+    count: number;
+    digest: string;
+}
+/**
+ * How much of the scanned tree the profile's kinds describe.
+ *
+ * Computed deterministically by matching the submitted kind patterns against the scanned
+ * file set — never self-reported. Low coverage is a distinct failure from drift: a
+ * profile that classified a fraction of its inputs used to carry the same comparand as
+ * one that classified all of them, so it read as complete and fresh. Coverage does NOT by
+ * itself drive a re-profile, because some input sets legitimately resist classification.
+ */
+export interface DataProfileCoverage {
+    matched: number;
+    unmatched: number;
+    total: number;
+    unmatchedSample?: string[];
+}
+/**
+ * One profiled input file's legacy drift signature. `fileId` is a path identity (two
+ * files at the same path share it regardless of content), so `size` + `mtimeMs` are what
+ * let a consumer notice the bytes behind a path changed. Superseded by
+ * {@link DataProfileInputSignature}, and still readable on older rows.
+ */
+export interface DataProfileInputFile {
+    fileId: string;
+    size: number;
+    mtimeMs: number;
+}
+/**
+ * The profile snapshot stored in `cortex_analysis_state.data_profile_result`.
+ *
+ * It carries the profiler's full finding rather than a summary of it: this row is the
+ * profile's only durable home, so a field dropped on the way in is not "summarized
+ * away", it is destroyed, and the next reader can recover it only by re-reading the raw
+ * inputs.
+ *
+ * It does NOT carry a record per input file. The workspace filesystem is the
+ * authoritative file list — listing, grep, and the vector index all read the live tree —
+ * so a copy here would be a stale duplicate on a row detoasted by every reader,
+ * including the planner's, which reads a few hundred characters of it. `files` holds the
+ * individually notable inputs; `kinds` holds the dataset's structure.
+ */
+export interface DataProfileResult {
+    summary: string;
+    /** Individually described files — notable singletons, not the dataset's contents. */
+    files: DataProfileFile[];
+    /** The repeating sets the tree was grouped into. Absent on a pre-kinds snapshot. */
+    kinds?: DataProfileKind[];
+    /** What varies across those sets. Absent for the same reason as `kinds`. */
+    axes?: DataProfileAxis[];
+    /** The drift comparand. Preferred over `inputFileIds`, which it replaces. */
+    inputSignature?: DataProfileInputSignature;
+    /** How much of the scanned tree the kinds describe. Absent on pre-coverage snapshots. */
+    coverage?: DataProfileCoverage;
+    /** The legacy identity-list comparand, on rows written before the signature existed. */
+    inputFileIds?: string[];
+    /** The legacy per-file drift signature, on rows of the same era. */
+    inputFiles?: DataProfileInputFile[];
+    /** ISO 8601 timestamp of profile completion. */
+    profiledAt: string;
+    /** Scientific domain (transcriptomics, cheminformatics, clinical, …). */
+    domain?: string;
+    /** Specific subtype within the domain (bulk-rna-seq, single-cell, LC-MS/MS, …). */
+    subtype?: string;
+    /**
+     * Explicit `null` is a real, distinct value — the profiler looked and no input
+     * identified an organism — as opposed to absent, which means the snapshot predates
+     * the field.
+     */
+    organism?: DataProfileOrganism | null;
+    tissue?: string | null;
+    cellType?: string | null;
+    condition?: string | null;
+    /** Public dataset accessions found in any input (GSE/SRP/PRJNA/E-MTAB/phs/EGAS). */
+    accessions?: string[];
+    /** Conditions, groups, comparisons, replicates, pairing. */
+    experimentalDesign?: string;
+    qualityAssessment?: DataProfileQualityAssessment;
+}
+/** The profile's lifecycle, as the ledger records it. */
+export type DataProfileLifecycleStatus = "pending" | "running" | "completed" | "failed";

package/dist/contracts/index.d.ts

@@ -6,6 +6,7 @@ export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCard
 export type { EventSource, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent, CortexChatEvent } from "./chat-events.js";
 export type { TokenUsageRollup } from "./usage.js";
 export { DATA_PROFILE_RUN_LITERAL } from "./data-profile.js";
+export type { DataProfileAxis, DataProfileCoverage, DataProfileFile, DataProfileInputFile, DataProfileInputSignature, DataProfileKind, DataProfileLifecycleStatus, DataProfileOrganism, DataProfileQualityAssessment, DataProfileResult, DataProfileSubjectSource, } from "./data-profile.js";
 export type { TextPart, ToolCallPart, CortexPart, CortexMessage } from "./message.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./part-registry.js";

package/dist/execution/input-signature.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The input signature — the fixed-width comparand a completed profile persists in
+ * place of a per-file identity list.
+ *
+ * `inputFileIds` had exactly one consumer, the staleness comparison, so a set of
+ * several thousand identifiers was persisted, detoasted on every read of the row, and
+ * compared element-wise to answer a question 40 bytes answer. The signature covers
+ * `size` and `mtimeMs` as well, so it also notices that the bytes behind a path
+ * changed — a `fileId` is a path identity and survives an in-place edit unchanged.
+ *
+ * Order independence is a property of the digest, not of the caller: entries are
+ * sorted canonically before hashing, so two enumerations of the same set agree.
+ */
+import type { DataProfileInputSignature } from "../state/data-profile.js";
+import type { StagedInput } from "./staged-input.js";
+/** The fields a signature covers. A manifest entry satisfies it structurally. */
+export interface SignableInput {
+    readonly fileId: string;
+    readonly size: number;
+    readonly mtimeMs?: number;
+}
+/**
+ * Digest a staged input set.
+ *
+ * A workflow input persisted before `StagedInput.mtimeMs` existed deserializes without
+ * it despite the compile-time type; such an entry contributes `-` in the mtime field
+ * rather than omitting the signature entirely. The comparison still notices an added,
+ * removed, or resized file, and one re-profile under the current code restores the full
+ * signature.
+ */
+export declare function computeInputSignature(inputs: readonly SignableInput[]): DataProfileInputSignature;
+/** Convenience over the workflow's own manifest type. */
+export declare function signatureOfStagedInputs(inputs: readonly StagedInput[]): DataProfileInputSignature;

package/dist/index.d.ts

@@ -115,10 +115,13 @@ export { DATA_PROFILE_RUN_LITERAL } from "./contracts/data-profile.js";
 export { initCortexState } from "./state/init.js";
 export { upsertAnalysis } from "./state/analyses.js";
 export { clearDataProfile, loadDataProfileStatus, tryRetryDataProfile, reconcileOrphanedDataProfile } from "./state/data-profile.js";
-export type { DataProfileInputFile, DataProfileResult, DataProfileStatus } from "./state/data-profile.js";
+export type { DataProfileAxis, DataProfileCoverage, DataProfileFile, DataProfileInputFile, DataProfileInputSignature, DataProfileKind, DataProfileLifecycleStatus, DataProfileOrganism, DataProfileQualityAssessment, DataProfileResult, DataProfileSubjectSource, } from "./contracts/data-profile.js";
+export type { DataProfileStatus } from "./state/data-profile.js";
 export { createAnalysisPurge } from "./state/purge-analysis.js";
 export type { AnalysisPurge, AnalysisPurgeDeps, AnalysisPurgeOutcome } from "./state/purge-analysis.js";
 export type { StagedInput } from "./execution/staged-input.js";
+export { computeInputSignature } from "./execution/input-signature.js";
+export type { SignableInput } from "./execution/input-signature.js";
 export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/create-sandbox.js";

package/dist/index.js

@@ -205,6 +205,11 @@ export { clearDataProfile, loadDataProfileStatus, tryRetryDataProfile, reconcile
 // Analysis reclamation — `purgeAnalysis` reclaims an analysis's whole Postgres
 // footprint from its id alone; workspace files stay the embedder's to dispose of.
 export { createAnalysisPurge } from "./state/purge-analysis.js";
+// The input signature a completed profile persists. Exported because the embedder owns
+// the OTHER side of the comparison — it enumerates the current input set — and a second
+// implementation of the digest would silently disagree with the one on the row, which is
+// the failure a fixed-width comparand exists to prevent.
+export { computeInputSignature } from "./execution/input-signature.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";

package/dist/input-scan/coverage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Profile coverage — how much of the scanned tree the agent's kinds actually describe.
+ *
+ * Measured against the SUBMITTED kinds, never against the scan's own shapes. Computed
+ * from the shapes it would report only whether the scan grouped its own observations,
+ * which is always yes; measured against the kinds it is a real check, and it is the
+ * check that was missing when a profile covering 49 of 3513 files read as complete and
+ * fresh.
+ *
+ * Deterministic by construction: matching declared patterns against a known file set
+ * requires no judgement, and a coverage figure a model self-reported would not be a
+ * check at all.
+ */
+export interface ProfileCoverage {
+    /** Files matching at least one declared kind pattern. */
+    readonly matched: number;
+    readonly unmatched: number;
+    readonly total: number;
+    readonly unmatchedSample: string[];
+}
+/** Coverage of a scanned file set by a set of declared kind patterns. */
+export declare function computeCoverage(paths: readonly string[], patterns: readonly string[]): ProfileCoverage;

package/dist/input-scan/coverage.js

@@ -0,0 +1,85 @@
+/**
+ * Profile coverage — how much of the scanned tree the agent's kinds actually describe.
+ *
+ * Measured against the SUBMITTED kinds, never against the scan's own shapes. Computed
+ * from the shapes it would report only whether the scan grouped its own observations,
+ * which is always yes; measured against the kinds it is a real check, and it is the
+ * check that was missing when a profile covering 49 of 3513 files read as complete and
+ * fresh.
+ *
+ * Deterministic by construction: matching declared patterns against a known file set
+ * requires no judgement, and a coverage figure a model self-reported would not be a
+ * check at all.
+ */
+/** Unmatched paths carried on the snapshot, so a shortfall names examples rather than a bare count. */
+const MAX_UNMATCHED_SAMPLE = 10;
+/**
+ * Compile a kind's path pattern to a matcher.
+ *
+ * `**` crosses directory separators, `*` and `?` do not, and `<0>`-style placeholders —
+ * the syntax the manifest renders variable positions in, which an agent may reasonably
+ * copy — match one token. Everything else is literal.
+ */
+function compilePattern(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === "*") {
+            if (pattern[i + 1] === "*") {
+                out += ".*";
+                i++;
+                // `**/` should also match zero directories, so the slash is optional.
+                if (pattern[i + 1] === "/")
+                    i++;
+                continue;
+            }
+            out += "[^/]*";
+            continue;
+        }
+        if (char === "?") {
+            out += "[^/]";
+            continue;
+        }
+        if (char === "<") {
+            const close = pattern.indexOf(">", i);
+            if (close > i) {
+                out += "[^/]*";
+                i = close;
+                continue;
+            }
+        }
+        out += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+function normalize(path) {
+    return path.replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+/g, "/");
+}
+/**
+ * Whether a path falls under a pattern. A pattern naming a directory covers everything
+ * beneath it — agents write `data/inputs/vcf` as often as `data/inputs/vcf/*.vcf.gz`,
+ * and reading the first as a zero-file kind would report a coverage failure that is an
+ * artefact of notation.
+ */
+function matches(path, pattern, compiled) {
+    if (compiled.test(path))
+        return true;
+    const bare = pattern.replace(/\/+$/, "");
+    return bare.length > 0 && !/[*?<]/.test(bare) && path.startsWith(`${bare}/`);
+}
+/** Coverage of a scanned file set by a set of declared kind patterns. */
+export function computeCoverage(paths, patterns) {
+    const compiled = patterns.map((pattern) => ({ pattern, regex: compilePattern(pattern) }));
+    const unmatchedSample = [];
+    let matched = 0;
+    for (const raw of paths) {
+        const path = normalize(raw);
+        if (compiled.some(({ pattern, regex }) => matches(path, pattern, regex))) {
+            matched++;
+            continue;
+        }
+        if (unmatchedSample.length < MAX_UNMATCHED_SAMPLE)
+            unmatchedSample.push(path);
+    }
+    return { matched, unmatched: paths.length - matched, total: paths.length, unmatchedSample };
+}

package/dist/input-scan/enrich.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-shape header readout — the one part of the scan that needs the sandbox.
+ *
+ * A bounded prefix read compared against a magic table runs on the host; a DECODER
+ * over user-supplied bytes does not. zlib, HDF5, and PDF parsers in the long-lived
+ * multi-tenant harness process are exactly the exposure the ephemeral sandbox exists
+ * to contain, so every decode below runs there.
+ *
+ * Cost is O(shapes), not O(files): shapes are observed from names and sizes alone, so
+ * enrichment decodes a bounded number of members per shape — roughly four files for
+ * the 3513-file tree that motivated this capability. One exec covers every shape, so
+ * even the round trip does not scale with the tree.
+ *
+ * Nothing ships in `sandbox-base` for this: the decoder is a Python program passed on
+ * the command line through the existing `runSandboxExec` path, so the capability
+ * releases on the harness's own path rather than on the image's manual one.
+ */
+import type { EmitFn } from "../tools/define-tool.js";
+import type { SandboxClient } from "../sandbox/client.js";
+import type { SandboxRef } from "../sandbox/types.js";
+import type { FileShape } from "./types.js";
+/** Members decoded per shape. One is enough to characterise a set whose names already match. */
+export declare const MEMBERS_DECODED_PER_SHAPE = 1;
+export interface EnrichShapesArgs {
+    readonly shapes: readonly FileShape[];
+    readonly sandboxClient: SandboxClient;
+    readonly sandbox: SandboxRef;
+    /** Absolute in-sandbox path of the analysis root (`/{analysisId}`). */
+    readonly mountRoot: string;
+    readonly execId: string;
+    readonly deadlineMs: number;
+    readonly emit: EmitFn;
+}
+/**
+ * Decode one member per shape and attach the readout.
+ *
+ * A shape whose decode failed keeps its `unavailable` note rather than losing the
+ * shape: the readout is enrichment, and a manifest without it still carries every
+ * structural observation the agent's grouping rests on.
+ */
+export declare function enrichShapes(args: EnrichShapesArgs): Promise<FileShape[]>;