@inflexa-ai/harness 0.35.2 → 0.35.4

package/dist/state/index.d.ts

@@ -21,7 +21,7 @@ export type { ActiveSandboxRow } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
 export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
-export type { DataProfileStatus, DataProfileResult, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileDimension, DataProfileGroup, DataProfileGroupSlot, DataProfileFile, DataProfileMemberAnnotation, DataProfileObservation, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileKind, DataProfileAxis, DataProfileInputSignature, DataProfileCoverage, } from "./data-profile.js";
+export type { DataProfileStatus, DataProfileTerminalWrite, DataProfileResult, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileDimension, DataProfileGroup, DataProfileGroupSlot, DataProfileFile, DataProfileMemberAnnotation, DataProfileObservation, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileKind, DataProfileAxis, DataProfileInputSignature, DataProfileCoverage, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { createAnalysisPurge } from "./purge-analysis.js";
 export type { AnalysisPurge, AnalysisPurgeDeps, AnalysisPurgeOutcome } from "./purge-analysis.js";

package/dist/state/schema.d.ts

@@ -46,10 +46,10 @@ export declare const ArtifactRowSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ArtifactRow = z.infer<typeof ArtifactRowSchema>;
 export declare const RunStatus: z.ZodEnum<{
-    partial: "partial";
     running: "running";
     completed: "completed";
     failed: "failed";
+    partial: "partial";
     canceled: "canceled";
     suspended_insufficient_funds: "suspended_insufficient_funds";
 }>;
@@ -77,10 +77,10 @@ export declare const CortexRunRowSchema: z.ZodObject<{
     threadId: z.ZodNullable<z.ZodString>;
     workflowName: z.ZodString;
     status: z.ZodEnum<{
-        partial: "partial";
         running: "running";
         completed: "completed";
         failed: "failed";
+        partial: "partial";
         canceled: "canceled";
         suspended_insufficient_funds: "suspended_insufficient_funds";
     }>;

package/dist/tasks/data-profile.js

@@ -45,6 +45,7 @@ import { PROFILE_INDEX_TYPES, buildProfileIndexEntries } from "./data-profile-in
 import { absorbRecipe, renderAbsorbDelta } from "./data-profile-absorb.js";
 import { formatResolutionErrors, resolveProfileSubmission } from "./data-profile-resolve.js";
 import { completeDataProfile, completeEmptyDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
+import { elapsedSinceIso, recordRunCompleted } from "../lib/metrics.js";
 import { createProfileActivityEmitter } from "./data-profile-activity.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
 // The run literal is declared in `contracts/` — a consumer reads it back off recorded usage, and this
@@ -316,8 +317,7 @@ export async function runDataProfileBody(input, deps) {
             // catalogue's fit is measured, and a completion that emitted none would make the
             // empty-manifest path invisible to the same monitoring that watches every other.
             logProfileMonitoring(logger, { dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
-            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)))
-                logTerminalNoop(logger, analysisId, "completion");
+            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)), "completed");
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
             // This is a terminal completion like any other, so it reports one — a consumer watching
             // an empty-manifest profile sees it settle rather than seeing the stream simply stop.
@@ -370,8 +370,7 @@ export async function runDataProfileBody(input, deps) {
             await activity.indexing();
             await indexProfile({ deps, analysisId, session: runSession, record, scan, logger });
             logProfileMonitoring(logger, { resolution, dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
-            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, record)))
-                logTerminalNoop(logger, analysisId, "completion");
+            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, record)), "completed");
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
             await activity.complete();
             return;
@@ -397,8 +396,7 @@ export async function runDataProfileBody(input, deps) {
                 repairRounds: 0,
                 absorb: absorb.kind,
             });
-            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, absorbed)))
-                logTerminalNoop(logger, analysisId, "completion");
+            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, absorbed)), "completed");
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
             await activity.complete();
             return;
@@ -575,9 +573,7 @@ export async function runDataProfileBody(input, deps) {
             });
             // 6. Complete — store the FULL profiler finding plus the input signature for
             // staleness detection. The scratch tree is gone; this row is all that survives.
-            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord))) {
-                logTerminalNoop(logger, analysisId, "completion");
-            }
+            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord)), "completed");
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
             // LAST statement of the success path, and that placement is the guarantee that exactly
             // one terminal activity is ever emitted. Everything that could still throw — the ledger
@@ -599,8 +595,7 @@ export async function runDataProfileBody(input, deps) {
     catch (err) {
         logger.error("profile failed", logger.errorFields(err));
         const reason = profileFailureReason(err);
-        if (!unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)))
-            logTerminalNoop(logger, analysisId, "failure");
+        settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)), "failed");
         await deps.runAuthorizer.revoke(authorization, "data-profile-failed");
         // The same bounded, user-safe line the ledger receives — never the raw error, whose paths and
         // stack frames stay in the log record above. This is the only other terminal emission, so
@@ -617,6 +612,21 @@ export async function runDataProfileBody(input, deps) {
 function logTerminalNoop(logger, analysisId, write) {
     logger.warn("terminal write skipped: ledger row not running (cleared or expired concurrently)", { analysisId, write });
 }
+/**
+ * Settle one terminal write of the profile ledger. A refused stamp is logged
+ * (see `logTerminalNoop`). An accepted stamp records the profile's run outcome:
+ * the CAS admits one write per `running` claim, so this is the exactly-once
+ * point of the transition — a recovery replay of the body finds the row no
+ * longer `running`, and records nothing again. The duration runs from the
+ * `data_profile_started_at` the claim stamped, never from a body-local clock.
+ */
+function settleTerminalWrite(logger, analysisId, write, status) {
+    if (!write.stamped) {
+        logTerminalNoop(logger, analysisId, status === "completed" ? "completion" : "failure");
+        return;
+    }
+    recordRunCompleted({ workflow: "data_profile", status, durationMs: elapsedSinceIso(write.startedAt) });
+}
 /**
  * Resolve the `RunSession` the workflow runs under. Whether the authorization
  * is freshly minted (Cortex-owned) or reused (caller-owned) is decided by the
@@ -762,13 +772,17 @@ async function compensateStartFailure(deps, analysisId, phase, err) {
     if (failed.isErr()) {
         logger.error("failed to mark failed after a start error", { phase, err: failed.error });
     }
-    else if (!failed.value) {
+    else if (!failed.value.stamped) {
         // The row this compensation was written to fail is no longer `running` — a
         // concurrent clear/expire already moved it on, so the running-CAS refused the
         // stamp. Nothing wedged at `running`, which is the outcome compensation exists
         // to guarantee; just record the no-op.
         logTerminalNoop(logger, analysisId, "compensation");
     }
+    else {
+        // A profile that failed at start is a failed profile: its claim opened a run the ledger now closes.
+        recordRunCompleted({ workflow: "data_profile", status: "failed", durationMs: elapsedSinceIso(failed.value.startedAt) });
+    }
 }
 /**
  * Start the data-profile workflow for an already-claimed analysis (the retry

package/dist/tools/execute-analysis.js

@@ -10,6 +10,7 @@ import { DEFAULT_SANDBOX_MAX_STEPS } from "../config/resource-limits.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { buildRunCardData } from "../memory/card-builders.js";
+import { formatQuery, parseQuery } from "../sandbox/package-identity.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
 import { validatePlan } from "../schemas/validate-plan.js";
 import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, updateRunStatus, upsertPlan } from "../state/index.js";
@@ -80,39 +81,41 @@ export class PlanPackagesMissingError extends Error {
         this.name = "PlanPackagesMissingError";
     }
 }
-/** One plan package entry, in requirement form: a bare name, or a name with one exact version. */
-function parseRequirement(entry) {
-    const split = entry.indexOf("==");
-    if (split < 0)
-        return { name: entry.trim() };
-    return { name: entry.slice(0, split).trim(), version: entry.slice(split + 2).trim() };
-}
 /**
  * Link the packages of the plan into the farm of the analysis, before the
- * run reserves anything. The linked set is the union of the packages of each
- * step. A pool miss and a collision refuse the launch with the names. Without
- * a bound seam, the pass returns at once.
+ * run reserves anything. The linked set is the union of the queries of each
+ * step. A pool miss and a collision refuse the launch with the spellings.
+ * Without a bound seam, the pass returns at once.
  */
 async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     if (!extendAnalysisFarm)
         return;
+    // The union dedupes EQUAL queries only: two entries are one ask when their
+    // spelling, their track, and their version are equal. A bare entry beside a
+    // qualified entry of one spelling stays two asks, because the bare one
+    // carries its own refusal — an absorption would drop the pin of one entry
+    // and silence a wrong track.
     const union = new Map();
     for (const step of plan.steps) {
         for (const entry of step.packages ?? []) {
-            // The FIRST spelling of the plan rides the request. An outcome
-            // echoes the requested spelling, and a last-writer fold could
-            // echo `seurat` where the plan said `Seurat` — a remedy in that
-            // case names a package that no repository holds.
-            const key = entry.trim().toLowerCase();
+            const parsed = parseQuery(entry);
+            if (parsed.isErr()) {
+                // `validatePlan` parsed every entry of this plan already, thus a
+                // refusal here means that the two readers disagree.
+                throw new Error(`Step "${step.id}" carries the package entry "${entry}", which the plan validation should have refused`);
+            }
+            const query = parsed.value;
+            const key = formatQuery(query);
             if (!union.has(key))
-                union.set(key, parseRequirement(entry));
+                union.set(key, query);
         }
     }
-    if (union.size === 0)
+    const queries = [...union.values()];
+    if (queries.length === 0)
         return;
     let outcomes;
     try {
-        outcomes = await extendAnalysisFarm(analysisId, [...union.values()]);
+        outcomes = await extendAnalysisFarm(analysisId, queries);
     }
     catch (cause) {
         // A realization throw is an `unavailable` answer, not a driver error.
@@ -132,8 +135,22 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     // so the agent replans from the true state instead of re-asking. A
     // collision's detail names the two pins and what needs each side — the
     // remedy is to drop or re-pin a DEPENDENT, so the refusal must name it.
-    const missing = outcomes.filter((o) => o.kind === "absent").map((o) => (o.detail === undefined ? o.name : `${o.name} — ${o.detail}`));
-    const collisions = outcomes.filter((o) => o.kind === "collision").map((o) => (o.detail === undefined ? o.name : `${o.name} — ${o.detail}`));
+    const missing = outcomes.filter((o) => o.kind === "absent").map((o) => (o.detail === undefined ? o.spelling : `${o.spelling} — ${o.detail}`));
+    // A collision names the two store directories AND the two prefixed forms.
+    // One spelling that both tracks hold is the common cause, and the prefix is
+    // the remedy that a plan can write. `formatQuery` writes the two forms,
+    // thus the refusal quotes the grammar that the plan reads.
+    //
+    // The prefix carries its CONDITION, because the outcome shape cannot tell
+    // the two collisions apart: two versions of one distribution collide too,
+    // and a prefix there resolves nothing. An unconditional instruction would
+    // send the agent through a second launch that refuses identically.
+    const collisions = outcomes
+        .filter((o) => o.kind === "collision")
+        .map((o) => `${o.spelling} — two store directories claim it, ${o.storeDirs[0]} and ${o.storeDirs[1]}` +
+        `${o.detail === undefined ? "" : ` (${o.detail})`}` +
+        `; when the two directories are one spelling in two tracks, name the track in the plan, as ` +
+        `${formatQuery({ spelling: o.spelling, track: "python" })} or ${formatQuery({ spelling: o.spelling, track: "r" })}`);
     if (missing.length > 0 || collisions.length > 0) {
         throw new PlanPackagesMissingError(missing, collisions);
     }

package/dist/tools/research/inspect-run.d.ts

@@ -53,7 +53,7 @@ declare function formatRun(r: CortexRunRow, verbose: boolean, exposePaths?: bool
     synthesisReason?: string | undefined;
     runId: string;
     workflowName: string;
-    status: "partial" | "running" | "completed" | "failed" | "canceled" | "suspended_insufficient_funds";
+    status: "running" | "completed" | "failed" | "partial" | "canceled" | "suspended_insufficient_funds";
     startedAt: string;
     completedAt: string | null;
     planId: string | null;

package/dist/tools/sandbox/link-packages.d.ts

@@ -8,20 +8,20 @@
  * staged — the tool never installs, downloads, or acquires anything. A link
  * is live in a container that already runs, because the farm rides a bind
  * mount.
+ *
+ * Each entry is a query in the one grammar of the `package-identity`
+ * capability, thus the agent learns one grammar for the plan, the tool, and
+ * the prompt layer.
  */
 import type { ExtendAnalysisFarm, PackageRequestOutcome } from "../../sandbox/types.js";
 export interface LinkPackagesDeps {
     readonly extendAnalysisFarm: ExtendAnalysisFarm;
     readonly analysisId: string;
 }
-/** The tool result: one outcome per requested package, index-aligned. */
+/** The tool result: one outcome per requested query, index-aligned. */
 export interface LinkPackagesResult {
     readonly outcomes: readonly PackageRequestOutcome[];
 }
 export declare function createLinkPackagesTool(deps: LinkPackagesDeps): import("../define-tool.js").Tool<{
-    packages: {
-        name: string;
-        version?: string | undefined;
-        ecosystem?: "r" | "python" | undefined;
-    }[];
+    packages: string[];
 }, LinkPackagesResult>;

package/dist/tools/sandbox/link-packages.js

@@ -8,44 +8,75 @@
  * staged — the tool never installs, downloads, or acquires anything. A link
  * is live in a container that already runs, because the farm rides a bind
  * mount.
+ *
+ * Each entry is a query in the one grammar of the `package-identity`
+ * capability, thus the agent learns one grammar for the plan, the tool, and
+ * the prompt layer.
  */
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { parseQuery } from "../../sandbox/package-identity.js";
+/**
+ * The refusal of one entry that is not a query. The text names the entry and
+ * the issue, thus the agent corrects the entry it wrote instead of guessing
+ * which of its packages the tool refused.
+ */
+function describeParseError(entry, error) {
+    switch (error.type) {
+        case "empty":
+            return `"${entry}" names no package — pass a bare name, or name==version`;
+        case "location":
+            return `"${entry}" is a location — pass a package name, never a path, a URL, or a store directory`;
+        case "unknown_prefix":
+            return `"${entry}" carries the prefix "${error.prefix}:", which this tool cannot read — the permitted prefixes are "python:" and "r:", and a bare name searches both tracks`;
+        case "unsupported_specifier":
+            return `"${entry}" pins with the specifier "${error.specifier}", which this tool cannot honor — pass a bare name, or name==version with one exact version`;
+    }
+}
 export function createLinkPackagesTool(deps) {
     return defineTool({
         id: "link_packages",
         description: "Link host-staged packages into the farm of this analysis, so an import that failed works without a restart. " +
             "This tool links what the host already staged — it NEVER installs, downloads, or acquires anything. " +
-            "Pass each module name verbatim, exactly as the import names it. " +
+            "Pass each module name verbatim, exactly as the import names it, optionally behind the track prefix `python:` or `r:` and optionally pinned as `name==version`. " +
             "One outcome comes back per request: `linked` (the pool held it, and it is importable now), " +
             "`present` (the farm held it already), " +
             "`absent` (the pool does not hold it — a real answer, and `acquisitionPossible` states whether the host can acquire that ecosystem; report the package as missing, do not retry), " +
-            "`collision` (the request resolves to two store directories — terminal for that package; the `detail` names the two pins and the packages that need each; report it and continue without it), " +
-            "or `unavailable` (the link pass itself could not answer — the `reason` says why; it says nothing about the package's presence, so report the reason and do not re-request packages).",
+            "`collision` (the request resolves to two store directories; the `detail` names the two pins and the packages that need each), " +
+            "or `unavailable` (the link pass itself could not answer — the `reason` says why; it says nothing about the package's presence, so report the reason and do not re-request packages). " +
+            "After a `collision` of one name that BOTH tracks hold, call this tool again for that package with the prefixed form, `python:<name>` or `r:<name>`. " +
+            "A collision is terminal only after that second call also refuses, or when it names two versions of one distribution — then report it and continue without the package.",
         inputSchema: z.object({
             packages: z
-                .array(z.object({
-                name: z.string().min(1).describe("The module or package name, verbatim."),
-                version: z.string().optional().describe("One exact version, when the requirement pins one."),
-                ecosystem: z.enum(["python", "r"]).optional().describe("The ecosystem, when the bare name is ambiguous."),
-            }))
+                .array(z.string().min(1))
                 .min(1)
                 .max(50)
-                .describe("The packages to link into the farm."),
+                .describe('The packages to link into the farm, each as `[python:|r:]<name>[==<version>]`, for example ["scanpy", "r:Seurat", "numpy==1.26.4"]. A bare name searches both tracks.'),
         }),
-        describeCall: ({ packages }) => packages.map((p) => p.name).join(", "),
+        describeCall: ({ packages }) => packages.join(", "),
         execute: async (input) => {
-            // A realization throw reads as `unavailable` per request. The loop
+            // Every entry parses before any link lands. A partial link over a
+            // batch whose tail is malformed leaves the farm in a state that the
+            // agent did not ask for and cannot see.
+            const queries = [];
+            for (const entry of input.packages) {
+                const parsed = parseQuery(entry);
+                if (parsed.isErr()) {
+                    return err({ error: `link_packages refused the call: ${describeParseError(entry, parsed.error)}`, retryable: true });
+                }
+                queries.push(parsed.value);
+            }
+            // A realization throw reads as `unavailable` per query. The loop
             // would render the throw as a raw tool error, and a raw driver
             // message teaches the agent nothing that `reason` does not.
             try {
-                const outcomes = await deps.extendAnalysisFarm(deps.analysisId, input.packages);
+                const outcomes = await deps.extendAnalysisFarm(deps.analysisId, queries);
                 return ok({ outcomes });
             }
             catch (cause) {
                 const reason = cause instanceof Error ? cause.message : String(cause);
-                return ok({ outcomes: input.packages.map((request) => ({ kind: "unavailable", name: request.name, reason })) });
+                return ok({ outcomes: queries.map((query) => ({ kind: "unavailable", spelling: query.spelling, reason })) });
             }
         },
     });

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -20,8 +20,19 @@
  * hashes — a thousand rows of sha256 would bury the signal.
  */
 import type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventorySection } from "../../config/environment-stores.js";
+import { type Track } from "../../sandbox/package-identity.js";
 import { type FarmLock } from "../../sandbox/farm.js";
 import { type ImagePackages } from "../../sandbox/image-packages.js";
+/**
+ * The ecosystem of one lock subtree. `python` gives the Python track, and
+ * `cran`, `bioconductor`, and `github` give the R track — three subtrees of
+ * one ecosystem, because a repository is a source and not an identity rule.
+ *
+ * A subtree that names neither, such as `node`, carries no track: its packages
+ * are not in the pool of the two ecosystems, and a `names` lookup matches them
+ * by their rendered name.
+ */
+export declare function trackOfLockSubtree(subtree: string): Track | undefined;
 /**
  * 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.
@@ -43,7 +54,12 @@ export declare function imageSections(record: ImagePackages): Section[];
 export type SectionPackage = PoolInventoryPackage;
 /** One language track of the store, in the section order of its source. The seam shape and the render shape are one. */
 export type Section = PoolInventorySection;
-/** One `names` lookup: present + canonical spelling + track + store identity, or absent. */
+/**
+ * One hit of a `names` lookup: present + exact spelling + track + store
+ * identity, or absent. A name that two sections hold answers with one entry
+ * for each of them, thus the array is longer than the `names` array and it is
+ * not aligned with it.
+ */
 export type CheckedPackage = {
     readonly requested: string;
     readonly present: true;
@@ -55,6 +71,12 @@ export type CheckedPackage = {
 } | {
     readonly requested: string;
     readonly present: false;
+    /**
+     * The spelling that the pool does hold, when the resolution finds
+     * one. `seurat` misses and `Seurat` is present, thus the answer
+     * carries the spelling that a plan and a link both accept.
+     */
+    readonly suggestion?: string;
 };
 /**
  * Three shapes, one per call path: the store is unmounted; a `names` presence