@inflexa-ai/harness 0.35.3 → 0.35.4

package/dist/citations/types.d.ts

@@ -48,9 +48,9 @@ export declare const CitationVerdictSchema: z.ZodEnum<{
 }>;
 export type CitationVerdict = z.infer<typeof CitationVerdictSchema>;
 export declare const CitationCoverageSchema: z.ZodEnum<{
+    partial: "partial";
     none: "none";
     complete: "complete";
-    partial: "partial";
 }>;
 export type CitationCoverage = z.infer<typeof CitationCoverageSchema>;
 export declare const ComparisonStatusSchema: z.ZodEnum<{
@@ -496,9 +496,9 @@ export declare const CitationResolutionResultSchema: z.ZodObject<{
         inconclusive: "inconclusive";
     }>;
     coverage: z.ZodEnum<{
+        partial: "partial";
         none: "none";
         complete: "complete";
-        partial: "partial";
     }>;
 }, z.core.$strip>;
 export type CitationResolutionResult = z.infer<typeof CitationResolutionResultSchema>;

package/dist/config/environment-stores.d.ts

@@ -8,6 +8,7 @@
  * "the profiler", "the planner") while the contract stayed identical. Extending
  * this interface keeps one description of a field that has one meaning.
  */
+import type { Track } from "../sandbox/package-identity.js";
 /**
  * Host paths of the environment's two read-only stores.
  *
@@ -94,5 +95,14 @@ export interface PoolInventoryPackage {
 /** One language-track section of an inventory, as `list_available_packages` renders it. */
 export interface PoolInventorySection {
     readonly title: string;
+    /**
+     * The ecosystem that holds the packages of this section. It carries the
+     * track as DATA, thus no reader derives one from the title: a title is
+     * display text, and a heading that changes wording would silently change
+     * which packages a `language` filter answers. A section of system tools or
+     * of node packages carries none, because neither is a package track of the
+     * pool.
+     */
+    readonly track?: Track;
     readonly packages: readonly PoolInventoryPackage[];
 }

package/dist/contracts/schemas/chat-parts.d.ts

@@ -104,8 +104,8 @@ export declare const FileReferencePartSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const AskStatusSchema: z.ZodEnum<{
-    aborted: "aborted";
     pending: "pending";
+    aborted: "aborted";
     resolved: "resolved";
     rejected: "rejected";
     expired: "expired";
@@ -117,8 +117,8 @@ export declare const AskPartSchema: z.ZodObject<{
     command: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
-        aborted: "aborted";
         pending: "pending";
+        aborted: "aborted";
         resolved: "resolved";
         rejected: "rejected";
         expired: "expired";
@@ -182,8 +182,8 @@ export declare const DagStatePartSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const StepPhaseSchema: z.ZodEnum<{
-    complete: "complete";
     failed: "failed";
+    complete: "complete";
     warning: "warning";
     "sandbox-init": "sandbox-init";
     executing: "executing";
@@ -199,8 +199,8 @@ export declare const StepActivityPartSchema: z.ZodObject<{
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
+        complete: "complete";
         warning: "warning";
         "sandbox-init": "sandbox-init";
         executing: "executing";
@@ -314,8 +314,8 @@ export declare const RunCompletedPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        partial: "partial";
         completed: "completed";
+        partial: "partial";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;
@@ -403,9 +403,9 @@ export declare const RunSynthesisPartSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SynthesisPhaseSchema: z.ZodEnum<{
-    complete: "complete";
     failed: "failed";
     skipped: "skipped";
+    complete: "complete";
     indexing: "indexing";
     persisting: "persisting";
     starting: "starting";
@@ -419,9 +419,9 @@ export declare const SynthesisProgressPartSchema: z.ZodObject<{
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
         skipped: "skipped";
+        complete: "complete";
         indexing: "indexing";
         persisting: "persisting";
         starting: "starting";
@@ -520,8 +520,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     command: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
-        aborted: "aborted";
         pending: "pending";
+        aborted: "aborted";
         resolved: "resolved";
         rejected: "rejected";
         expired: "expired";
@@ -560,8 +560,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
+        complete: "complete";
         warning: "warning";
         "sandbox-init": "sandbox-init";
         executing: "executing";
@@ -679,9 +679,9 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
         skipped: "skipped";
+        complete: "complete";
         indexing: "indexing";
         persisting: "persisting";
         starting: "starting";
@@ -698,8 +698,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        partial: "partial";
         completed: "completed";
+        partial: "partial";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;

package/dist/execution/run-canceler.js

@@ -18,6 +18,7 @@
  * terminal frame read-side.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
+import { elapsedSinceIso, recordRunCompleted, recordStepCompleted } from "../lib/metrics.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { markRunCanceledIfActive, queryRun } from "../state/runs.js";
 import { queryStepsByRun, sweepPendingStepExecutions } from "../state/step-executions.js";
@@ -49,8 +50,9 @@ export function createRunCanceler(deps) {
         })();
         await engineCancel(workflowIds);
     };
-    /** Persisted child workflow ids of steps not yet completed. */
-    const incompleteChildIds = async (runId) => unwrapOrThrow(await queryStepsByRun(pool, runId)).flatMap((step) => step.childWorkflowId !== null && step.completedAt === null ? [step.childWorkflowId] : []);
+    /** Steps whose child started (a persisted child workflow id) and has not written its terminal row. */
+    const incompleteSteps = async (runId) => unwrapOrThrow(await queryStepsByRun(pool, runId)).filter((step) => step.childWorkflowId !== null && step.completedAt === null);
+    const childIds = (steps) => steps.flatMap((step) => (step.childWorkflowId !== null ? [step.childWorkflowId] : []));
     return {
         async cancel(runId, session) {
             const row = unwrapOrThrow(await queryRun(pool, runId));
@@ -71,10 +73,14 @@ export function createRunCanceler(deps) {
             // mark-running step has not yet committed its child_workflow_id. The
             // persisted ids and the post-cancel re-query are belt-and-braces over
             // both ledgers' lag.
-            const knownChildren = await incompleteChildIds(runId);
+            const knownChildren = childIds(await incompleteSteps(runId));
             await cancelWorkflows([workflowId, ...knownChildren]);
+            // The steps the cancel cut: read after the cancel landed, so a child that
+            // wrote its terminal row in the meantime is not among them.
+            let cutSteps;
             try {
-                const late = (await incompleteChildIds(runId)).filter((id) => !knownChildren.includes(id));
+                cutSteps = await incompleteSteps(runId);
+                const late = childIds(cutSteps).filter((id) => !knownChildren.includes(id));
                 if (late.length > 0)
                     await cancelWorkflows(late);
             }
@@ -89,6 +95,16 @@ export function createRunCanceler(deps) {
             catch (err) {
                 logger.error("markRunCanceledIfActive failed", { runId, ...logger.errorFields(err) });
             }
+            // The workflow's own terminal step never runs after a cancel, so this
+            // conditional write is the one terminal write of an external cancel, and
+            // the outcome metrics ride behind it: a refused write means the run
+            // settled on its own and its own terminal step recorded them. A cut
+            // child never reached its terminal row, so its step records here too.
+            if (transitioned) {
+                recordRunCompleted({ workflow: "analysis", status: "canceled", durationMs: elapsedSinceIso(row.startedAt) });
+                for (const step of cutSteps ?? [])
+                    recordStepCompleted({ agentId: step.agentId, status: "canceled" });
+            }
             let steps = false;
             try {
                 unwrapOrThrow(await sweepPendingStepExecutions(pool, runId));

package/dist/index.d.ts

@@ -136,7 +136,9 @@ export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/
 export type { SandboxClient } from "./sandbox/client.js";
 export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
 export type { SandboxError } from "./sandbox/sandbox-error.js";
-export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequest, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
+export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
+export { formatQuery, identityAddress, identityKey, identityOf, parseIdentityKey, parseQuery, pythonIdentity, resolveQuery, rIdentity, } from "./sandbox/package-identity.js";
+export type { PackageIdentity, PackageQuery, ParseQueryError, PoolIndex, QueryResolution, Track } from "./sandbox/package-identity.js";
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
 export type { FarmLock, FarmLockError } from "./sandbox/farm.js";
 export { IMAGE_PACKAGES_FILE } from "./sandbox/image-packages.js";

package/dist/index.js

@@ -246,6 +246,11 @@ export { createSandboxClient } from "./sandbox/create-sandbox.js";
 // The throw of the client seam. An embedder matches the class and reads the
 // typed variant on `error`, instead of a string match on the message.
 export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
+// The identity of a package, the query that asks for one, and the resolution
+// between the two. An embedder reads `by_name` of the dependency graph with
+// these, thus the host lookup, the census, and the graph key never disagree on
+// the identity of a name.
+export { formatQuery, identityAddress, identityKey, identityOf, parseIdentityKey, parseQuery, pythonIdentity, resolveQuery, rIdentity, } from "./sandbox/package-identity.js";
 // The farm contract: one `inflexa.lock` per farm. An embedder that composes
 // farms writes this shape, and the mount gate reads it — one schema, no copy.
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";

package/dist/lib/metrics.d.ts

@@ -2,17 +2,75 @@
  * Custom OTel metrics for Cortex.
  *
  * Instruments:
- *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
- *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *   - cortex.run.completed{status, workflow}      — counter, one per run that reached a terminal status
+ *   - cortex.run.duration_ms{status, workflow}    — histogram, start to terminal status
+ *   - cortex.step.completed{status, agent_id}     — counter, one per executed step that settled
+ *   - cortex.step.duration_ms{status, agent_id}   — histogram, step start to its terminal ledger write
+ *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
- * Both carry `agent_id` (about 15 values) and never a per-step or per-run
- * identifier: a label with unbounded values multiplies the series count.
+ * Every label is a bounded vocabulary: `status` is the terminal enum, `workflow`
+ * names the workflow family, `agent_id` has about 15 values. No instrument
+ * carries a run, step, exec, user, or organization id — a label with unbounded
+ * values multiplies the series count.
+ *
+ * A run or step outcome is recorded INSIDE the DBOS step that persists the same
+ * outcome to the ledger (or behind the ledger's own compare-and-set where the
+ * body has no such step). DBOS caches a completed step and does not re-run its
+ * body on recovery, so a replayed workflow records nothing twice.
  *
  * Instruments are lazy so the record site binds to whichever `MeterProvider`
  * is globally registered at first use. The metrics API has no late-binding
  * proxy: a meter taken at module load, before `initOtel` runs, would stay
  * on the no-op provider for the life of the process.
  */
+import type { StepExecutionStatus } from "../state/schema.js";
+/** Terminal status of a run. A budget pause records as `canceled`, the same as the run ledger. */
+export type RunOutcome = "completed" | "partial" | "failed" | "canceled";
+/** The workflow family a run belongs to. */
+export type RunWorkflow = "analysis" | "target_assessment" | "data_profile";
+/** Terminal status of an executed step. A blocker is a failure to deliver, so `blocked` maps here to `failed`. */
+export type StepOutcome = "completed" | "failed" | "canceled";
+/**
+ * Bucket bounds for durations that run from seconds to hours: 30 s, then
+ * 1, 2, 5, 10, 30, 60, 120, 240 min. Ten buckets with the overflow, so one
+ * histogram costs about ten series per label set.
+ */
+export declare const RUN_DURATION_BOUNDS_MS: readonly number[];
+/**
+ * Record one run that reached a terminal status. Call it inside the DBOS step
+ * that persists that status, or behind the ledger compare-and-set that accepted
+ * it. `durationMs` is omitted when the start instant is unknown: the run is
+ * then counted, not timed.
+ */
+export declare function recordRunCompleted(args: {
+    readonly workflow: RunWorkflow;
+    readonly status: RunOutcome;
+    readonly durationMs?: number;
+}): void;
+/**
+ * Record one executed step that settled. Call it inside the DBOS step that
+ * persists the terminal row, or inside the terminal step of the run for a
+ * step whose own body never reached one. `durationMs` is omitted when the
+ * step settled without a durable duration: it is then counted, not timed.
+ */
+export declare function recordStepCompleted(args: {
+    readonly agentId: string;
+    readonly status: StepOutcome;
+    readonly durationMs?: number;
+}): void;
+/**
+ * The step outcome that a terminal ledger status records. A status that is not
+ * terminal (`pending`, `running`) or that names a step that never executed
+ * (`skipped`) records no outcome.
+ */
+export declare function stepOutcomeOf(status: StepExecutionStatus): StepOutcome | undefined;
+/**
+ * Milliseconds from a persisted ISO-8601 start instant to `nowMs`. `undefined`
+ * when the ledger holds no start or an unparsable one, so the caller counts
+ * without a duration instead of recording a bogus one.
+ */
+export declare function elapsedSinceIso(startedAt: string | null | undefined, nowMs?: number): number | undefined;
 /** Record one manifest entry dropped at reconcile. */
 export declare function recordArtifactReconcileDropped(args: {
     readonly agentId: string;
@@ -24,4 +82,4 @@ export declare function recordLineageInputDropped(args: {
     readonly reason: LineageInputDropReason;
 }): void;
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
-export declare function __resetReconcileMetricsForTest(): void;
+export declare function __resetMetricsForTest(): void;

package/dist/lib/metrics.js

@@ -2,11 +2,22 @@
  * Custom OTel metrics for Cortex.
  *
  * Instruments:
- *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
- *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *   - cortex.run.completed{status, workflow}      — counter, one per run that reached a terminal status
+ *   - cortex.run.duration_ms{status, workflow}    — histogram, start to terminal status
+ *   - cortex.step.completed{status, agent_id}     — counter, one per executed step that settled
+ *   - cortex.step.duration_ms{status, agent_id}   — histogram, step start to its terminal ledger write
+ *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
- * Both carry `agent_id` (about 15 values) and never a per-step or per-run
- * identifier: a label with unbounded values multiplies the series count.
+ * Every label is a bounded vocabulary: `status` is the terminal enum, `workflow`
+ * names the workflow family, `agent_id` has about 15 values. No instrument
+ * carries a run, step, exec, user, or organization id — a label with unbounded
+ * values multiplies the series count.
+ *
+ * A run or step outcome is recorded INSIDE the DBOS step that persists the same
+ * outcome to the ledger (or behind the ledger's own compare-and-set where the
+ * body has no such step). DBOS caches a completed step and does not re-run its
+ * body on recovery, so a replayed workflow records nothing twice.
  *
  * Instruments are lazy so the record site binds to whichever `MeterProvider`
  * is globally registered at first use. The metrics API has no late-binding
@@ -14,11 +25,36 @@
  * on the no-op provider for the life of the process.
  */
 import { metrics } from "@opentelemetry/api";
+/**
+ * Bucket bounds for durations that run from seconds to hours: 30 s, then
+ * 1, 2, 5, 10, 30, 60, 120, 240 min. Ten buckets with the overflow, so one
+ * histogram costs about ten series per label set.
+ */
+export const RUN_DURATION_BOUNDS_MS = [30_000, 60_000, 120_000, 300_000, 600_000, 1_800_000, 3_600_000, 7_200_000, 14_400_000];
 let instruments;
 function getInstruments() {
     if (instruments === undefined) {
         const meter = metrics.getMeter("cortex");
+        const advice = { explicitBucketBoundaries: [...RUN_DURATION_BOUNDS_MS] };
         instruments = {
+            runCompleted: meter.createCounter("cortex.run.completed", {
+                description: "Runs that reached a terminal status. Tagged by status, workflow.",
+                unit: "{run}",
+            }),
+            runDuration: meter.createHistogram("cortex.run.duration_ms", {
+                description: "Run duration from its start to its terminal status. Tagged by status, workflow.",
+                unit: "ms",
+                advice,
+            }),
+            stepCompleted: meter.createCounter("cortex.step.completed", {
+                description: "Executed steps that settled. Tagged by status, agent_id.",
+                unit: "{step}",
+            }),
+            stepDuration: meter.createHistogram("cortex.step.duration_ms", {
+                description: "Step duration from its start to its terminal ledger write. Tagged by status, agent_id.",
+                unit: "ms",
+                advice,
+            }),
             artifactReconcileDropped: meter.createCounter("cortex.artifact.reconcile.dropped", {
                 description: "Manifest entries dropped because their on-disk file was missing at " +
                     "registration time (writes-then-deletes, renames). Tagged by agent_id.",
@@ -33,6 +69,69 @@ function getInstruments() {
     }
     return instruments;
 }
+/**
+ * Record one run that reached a terminal status. Call it inside the DBOS step
+ * that persists that status, or behind the ledger compare-and-set that accepted
+ * it. `durationMs` is omitted when the start instant is unknown: the run is
+ * then counted, not timed.
+ */
+export function recordRunCompleted(args) {
+    const attributes = { status: args.status, workflow: args.workflow };
+    const { runCompleted, runDuration } = getInstruments();
+    runCompleted.add(1, attributes);
+    if (args.durationMs !== undefined)
+        runDuration.record(Math.max(0, args.durationMs), attributes);
+}
+/**
+ * Record one executed step that settled. Call it inside the DBOS step that
+ * persists the terminal row, or inside the terminal step of the run for a
+ * step whose own body never reached one. `durationMs` is omitted when the
+ * step settled without a durable duration: it is then counted, not timed.
+ */
+export function recordStepCompleted(args) {
+    const attributes = { status: args.status, agent_id: args.agentId };
+    const { stepCompleted, stepDuration } = getInstruments();
+    stepCompleted.add(1, attributes);
+    if (args.durationMs !== undefined)
+        stepDuration.record(Math.max(0, args.durationMs), attributes);
+}
+/**
+ * The step outcome that a terminal ledger status records. A status that is not
+ * terminal (`pending`, `running`) or that names a step that never executed
+ * (`skipped`) records no outcome.
+ */
+export function stepOutcomeOf(status) {
+    switch (status) {
+        case "completed":
+            return "completed";
+        case "failed":
+        case "blocked":
+            return "failed";
+        case "canceled":
+            return "canceled";
+        case "pending":
+        case "running":
+        case "skipped":
+            return undefined;
+        default: {
+            const _exhaustive = status;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Milliseconds from a persisted ISO-8601 start instant to `nowMs`. `undefined`
+ * when the ledger holds no start or an unparsable one, so the caller counts
+ * without a duration instead of recording a bogus one.
+ */
+export function elapsedSinceIso(startedAt, nowMs = Date.now()) {
+    if (startedAt === null || startedAt === undefined)
+        return undefined;
+    const startedMs = Date.parse(startedAt);
+    if (!Number.isFinite(startedMs))
+        return undefined;
+    return Math.max(0, nowMs - startedMs);
+}
 /** Record one manifest entry dropped at reconcile. */
 export function recordArtifactReconcileDropped(args) {
     getInstruments().artifactReconcileDropped.add(1, { agent_id: args.agentId });
@@ -42,6 +141,6 @@ export function recordLineageInputDropped(args) {
     getInstruments().lineageInputDropped.add(1, { agent_id: args.agentId, reason: args.reason });
 }
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
-export function __resetReconcileMetricsForTest() {
+export function __resetMetricsForTest() {
     instruments = undefined;
 }

package/dist/lib/otel.d.ts

@@ -14,8 +14,12 @@
  *
  * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
  *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
- *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
- *          metrics are defined in metrics.ts.
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. The run and step
+ *          outcome instruments (`cortex.run.*`, `cortex.step.*`) and the
+ *          reconcile counters are defined in metrics.ts; the agent loop, the
+ *          thread memory, and the workflows hold their own instruments next
+ *          to their record sites. Every instrument binds lazily to the
+ *          provider registered here.
  *
  * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
  *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);

package/dist/lib/otel.js

@@ -14,8 +14,12 @@
  *
  * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
  *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
- *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
- *          metrics are defined in metrics.ts.
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. The run and step
+ *          outcome instruments (`cortex.run.*`, `cortex.step.*`) and the
+ *          reconcile counters are defined in metrics.ts; the agent loop, the
+ *          thread memory, and the workflows hold their own instruments next
+ *          to their record sites. Every instrument binds lazily to the
+ *          provider registered here.
  *
  * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
  *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);

package/dist/prompts/planner.js

@@ -167,6 +167,12 @@ Every step carries a \`packages\` array — the packages its scripts import.
   one exact version (\`"numpy==1.26.4"\`). Never a path, a URL, or a store
   directory — a location is an installer detail, and validation refuses it.
 - An empty array is valid: the step needs nothing beyond the baked toolchain.
+- When the package census shows one name under a Python section AND under an R
+  section, write the prefixed form the census shows: \`"python:igraph"\` or
+  \`"r:igraph"\`. A bare name that both tracks hold refuses the launch, because
+  the pool cannot tell which package you mean.
+- Write a bare name for every other package. The prefix is for a both-track
+  name only.
 - The set is not a promise of completeness. The execution agent can still link a
   missing package mid-step. Name what you know the step imports; do not pad the
   list defensively.

package/dist/prompts/sandbox-standards.d.ts

@@ -42,5 +42,5 @@ export declare function sandboxOrientCorePromptFor(toolchainSource: ToolchainSou
  * constant, thus the prompt stays byte-identical across the steps of one
  * composition.
  */
-export declare const sandboxPackageLinkPrompt = "# Linking Packages\n\nThe host keeps a pool of staged packages beside the farm of this analysis \u2014 the\npool is part of what the host staged before this container started. The\n`link_packages` tool links a staged package into your farm \u2014 live, with no\nrestart. A link adds no new bytes and downloads nothing; it connects your farm\nto a directory that is already on the mount. So a package your farm lacks is\nnot missing until the pool has answered:\n\n- After a failed import, and when `list_available_packages` reports a package\n  absent, call `link_packages` with the module name verbatim.\n- `linked` and `present` mean the import works now \u2014 run it again.\n- `absent` is a real answer: the pool does not hold the package. When\n  `acquisitionPossible` is true, report the package as missing so the host can\n  acquire it. Do not retry the link, and do not attempt an install.\n- `collision` is terminal for that package: the request resolves to two store\n  directories. Report it and continue without the package.\n- Report a package as missing only after `link_packages` answered `absent` or\n  `unavailable` for it.\n";
+export declare const sandboxPackageLinkPrompt = "# Linking Packages\n\nThe host keeps a pool of staged packages beside the farm of this analysis \u2014 the\npool is part of what the host staged before this container started. The\n`link_packages` tool links a staged package into your farm \u2014 live, with no\nrestart. A link adds no new bytes and downloads nothing; it connects your farm\nto a directory that is already on the mount. So a package your farm lacks is\nnot missing until the pool has answered:\n\n- After a failed import, and when `list_available_packages` reports a package\n  absent, call `link_packages` with the module name verbatim. Each entry is\n  `[python:|r:]<name>[==<version>]`, and a bare name searches both tracks.\n- `linked` and `present` mean the import works now \u2014 run it again.\n- `absent` is a real answer: the pool does not hold the package. When\n  `acquisitionPossible` is true, report the package as missing so the host can\n  acquire it. Do not retry the link, and do not attempt an install.\n- `collision` means the request resolved to two store directories. When one\n  name is held by both tracks, call `link_packages` again for that package\n  with the prefixed form, `python:<name>` or `r:<name>`.\n- Drop the package only after that second call also refuses. A collision of two\n  versions of one distribution is terminal at once: report it and continue\n  without the package.\n- Report a package as missing only after `link_packages` answered `absent` or\n  `unavailable` for it.\n";
 export declare const sandboxAnalysisStepStandardsPrompt = "# Sandbox Analysis-Step Conventions\n\nThese apply to plannable analysis steps \u2014 agents that produce reproducible\nscript + output + figure artifacts. They do NOT apply to data profiling or\nreport building (those agents opt out via\n`appendAnalysisStepStandards: false`).\n\n## Language Policy\n\nPython is the DEFAULT language. Use R when:\n(a) No adequate Python equivalent (e.g. minfi, ANCOM-BC2, ChAMP).\n(b) The R implementation is significantly more mature.\n(c) The task explicitly requires an R-only package.\n\nChoose native R or rpy2 based on scope:\n- **Isolated R calls** in a Python pipeline \u2192 rpy2 bridge.\n  Example: DESeq2 for one DE step, fgsea for enrichment.\n- **R-dominant pipeline** where most steps use R packages \u2192 write\n  **native R scripts**. Do not wrap an entire R pipeline in rpy2.\n  Examples: microbiome (DADA2 \u2192 phyloseq \u2192 vegan \u2192 ANCOM-BC2),\n  DNA methylation (minfi \u2192 ChAMP \u2192 DMRcate), untargeted metabolomics\n  (XCMS \u2192 CAMERA).\n\nNative R scripts follow the same standards as Python: structured logging\n(`message()`), named constants, documented functions. Save final outputs\nas CSV (and optionally AnnData) for cross-agent consumption.\n\n## Data Format Standards\n\n- **AnnData (.h5ad)** is the UNIVERSAL container for sample-by-feature\n  data across ALL modalities \u2014 bulk RNA-seq, proteomics, metabolomics,\n  microarray, methylation, single-cell. Samples in `.obs`, features in\n  `.var`, values in `.X`, layers in `.layers`, embeddings in `.obsm`,\n  unstructured results in `.uns`.\n- **MuData (.h5mu)** for multi-modal data (CITE-seq, Multiome,\n  multi-omics integration).\n- Store sample metadata in `.obs`, feature annotations in `.var`. Do\n  NOT write separate metadata CSV files unless explicitly needed.\n- **Intermediate analysis objects**: save as `.h5ad` or `.h5mu`. Do\n  NOT save as `.rds` or `.pkl`. When R packages produce R objects\n  (DESeqDataSet, phyloseq, SingleCellExperiment), convert key results\n  back to AnnData or pandas.\n- **Tabular results**: CSV with human-readable column names\n  (`log2_fold_change`, `adjusted_pvalue`, not `lfc`/`padj`).\n- **Genomic data**: VCF/BED/BAM are acceptable primary containers.\n  Derived summary statistics go in AnnData or CSV.\n- **Dual-format output**: when producing modality-specific results,\n  also output a generic CSV for downstream cross-cutting agents.\n\n## Figure Standards\n\n- **PNG at 300 DPI** for preview AND **PDF (vector)** for publication,\n  same base filename with different extensions.\n- **Colorblind-safe palettes** \u2014 viridis family as default. Never use\n  red-green as the sole distinguishing feature.\n- **Clean minimal themes**: matplotlib `seaborn-v0_8-whitegrid` or\n  equivalent; ggplot2 `theme_classic()` or `theme_minimal()`.\n- **Complete labels**: title, axis labels with units, legend.\n- **Statistical annotations** where applicable (p-values, significance\n  brackets, effect sizes).\n- No default matplotlib/ggplot styling, no cut-off labels, no\n  overlapping text.\n\n## Directory Structure\n\nYour working directory has five subdirectories \u2014 write each kind of artifact\nto its own (paths are relative to your working directory):\n\n```\nscripts/    Analysis scripts (.py, .R)\noutput/     Results: CSV, AnnData (.h5ad), MuData (.h5mu), JSON\nfigures/    Visualizations: PNG (300 DPI) + PDF (vector), same base name\nlogs/       Execution logs from long-running commands\nnotebooks/  Reserved (currently unused)\n```\n\nPut data results in `output/`, not at the working-directory root. For\nlong-running commands, redirect stdout/stderr to a file in `logs/`:\n```python\nsubprocess.run(cmd, stdout=open(\"logs/deseq2_run.log\", \"w\"), stderr=subprocess.STDOUT)\n```\n\n## Code Quality\n\n**Functions** for any non-trivial logic. Each logical operation\n(load, QC, fit, plot) gets its own function with a docstring. Top-level\nscript flow should read like an outline \u2014 call functions, not inline\nlogic.\n\n```python\n# %% [markdown]\n# ## Differential Expression\n\n# %%\ndef run_deseq2(counts: pd.DataFrame, metadata: pd.DataFrame, design: str) -> pd.DataFrame:\n    \"\"\"Run DESeq2 via rpy2 and return results as a DataFrame.\"\"\"\n    ...\n\nde_results = run_deseq2(counts, metadata, \"~ condition + batch\")\n```\n\n**Structured logging**, not `print()`:\n\n- Python \u2014 `logging.getLogger()`:\n  `logger.info(\"Loaded %d samples, %d genes\", n_samples, n_genes)`\n- R \u2014 `message()` / `warning()`:\n  `message(sprintf(\"Loaded %d samples\", n_samples))`\n\nReserve `print()` / `cat()` for intentional data display in notebook\ncells only.\n\n**Validate at function boundaries**. Fail fast with clear messages.\nUse `try/except` only when recovery is meaningful.\n\n**Type hints** on Python function signatures. Add them \u2014 they document\nintent and catch mistakes early.\n\n**Named constants** for thresholds, cutoffs, parameters in the first\ncode cell:\n```python\n# %% Parameters\nRANDOM_SEED = 42\nFDR_THRESHOLD = 0.05\nMIN_LOG2FC = 1.0\n```\n\n**R specifics**: load packages at the top (never inside functions).\nUse `<-` for assignment. Use `message()` / `warning()` not `cat()` /\n`print()`.\n\n## Scripts\n\n- Start with a header comment (title + description).\n- Parameters go in the first code block.\n- Set random seeds for reproducibility.\n- Scripts must be independently re-runnable.\n- **Lint Python scripts with `ruff check <script.py>`** via\n  `execute_command` before executing. `ruff` is pre-installed. This\n  catches import errors, undefined names, and common bugs early.\n\n## Cleanup\n\nWhen a script fails, delete the failed script from `scripts/` and any\npartial output files before writing a corrected version. Only final\nworking scripts should remain. Use `list_files` to verify.\n\n## Interpretation & Literature Grounding\n\nGround findings in the research literature as you work \u2014 not as a\nfinal step:\n\n1. When you identify a significant finding (DE genes, enriched\n   pathways, hub genes, quality issues), search PubMed with\n   `pubmed({action:\"search\"})`.\n2. For relevant hits, call `pubmed({action:\"details\"})` for abstracts and\n   PMIDs. Note short citations (e.g. \"Smith et al., Nature 2023\").\n3. Assess novelty per finding: **novel** (searched, nothing found),\n   **confirmed** (directly supported), **partially confirmed**,\n   **contradicted**, **expected** (domain knowledge, no citation\n   needed).\n4. Document the search even when no references are found. \"Novel\"\n   means you looked and found nothing \u2014 not that you didn't look.\n\nYour structured output captures this interpretation. It is your\nscientific assessment of what the results mean.\n\n## Analysis-Step Anti-Patterns\n\n- **Ignoring script errors.** Read the error, diagnose the root\n  cause, fix the script. Do not move on.\n- **Placeholder or dummy output.** If an analysis cannot produce\n  meaningful results, report the reason clearly instead of faking\n  results.\n- **Monolithic scripts.** Keep scripts under 300 lines. Split into\n  logical sections with markdown annotations.\n- **`print()` for logging.** Use `logging` (Python) or `message()`\n  (R). `print()` is for intentional data display only.\n- **Inline logic without functions.** Wrap non-trivial operations in\n  functions with docstrings and typed parameters.\n- **Magic numbers.** Define thresholds and cutoffs as named constants.\n";

package/dist/prompts/sandbox-standards.js

@@ -312,13 +312,18 @@ to a directory that is already on the mount. So a package your farm lacks is
 not missing until the pool has answered:
 
 - After a failed import, and when \`list_available_packages\` reports a package
-  absent, call \`link_packages\` with the module name verbatim.
+  absent, call \`link_packages\` with the module name verbatim. Each entry is
+  \`[python:|r:]<name>[==<version>]\`, and a bare name searches both tracks.
 - \`linked\` and \`present\` mean the import works now — run it again.
 - \`absent\` is a real answer: the pool does not hold the package. When
   \`acquisitionPossible\` is true, report the package as missing so the host can
   acquire it. Do not retry the link, and do not attempt an install.
-- \`collision\` is terminal for that package: the request resolves to two store
-  directories. Report it and continue without the package.
+- \`collision\` means the request resolved to two store directories. When one
+  name is held by both tracks, call \`link_packages\` again for that package
+  with the prefixed form, \`python:<name>\` or \`r:<name>\`.
+- Drop the package only after that second call also refuses. A collision of two
+  versions of one distribution is terminal at once: report it and continue
+  without the package.
 - Report a package as missing only after \`link_packages\` answered \`absent\` or
   \`unavailable\` for it.
 `;