@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/schemas/plan-schemas.d.ts

@@ -7,8 +7,8 @@ import type { AnalysisPlan } from "./workflow-state.js";
 /** Step schema for planner output — omits fields populated at execution time
  *  and the hardcoded sandbox turn budget. */
 export declare const PlanStepSchema: z.ZodObject<{
-    name: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     id: z.ZodString;
     caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -21,11 +21,29 @@ export declare const PlanStepSchema: z.ZodObject<{
             count: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
+    grounding: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            grounded: "grounded";
+            ungrounded: "ungrounded";
+            flagged: "flagged";
+        }>;
+        snapshot: z.ZodString;
+        claims: z.ZodArray<z.ZodString>;
+        template: z.ZodOptional<z.ZodString>;
+        settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            step: z.ZodString;
+            name: z.ZodString;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
     track: z.ZodString;
     step_type: z.ZodString;
     acceptance_criteria: z.ZodArray<z.ZodString>;
     constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    capability: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
     agent: z.ZodEnum<{
         [x: string]: string;
     }>;
@@ -40,8 +58,8 @@ export declare const PlannerPlanSchema: z.ZodObject<{
     omicsSubtype: z.ZodOptional<z.ZodString>;
     title: z.ZodString;
     steps: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
         context: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
         caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -54,11 +72,29 @@ export declare const PlannerPlanSchema: z.ZodObject<{
                 count: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
+        grounding: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<{
+                grounded: "grounded";
+                ungrounded: "ungrounded";
+                flagged: "flagged";
+            }>;
+            snapshot: z.ZodString;
+            claims: z.ZodArray<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                step: z.ZodString;
+                name: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
         track: z.ZodString;
         step_type: z.ZodString;
         acceptance_criteria: z.ZodArray<z.ZodString>;
         constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        capability: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
         agent: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -82,8 +118,8 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
         omicsSubtype: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
         steps: z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
             context: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
             id: z.ZodString;
             caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -96,11 +132,29 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
                     count: z.ZodNumber;
                 }, z.core.$strip>>;
             }, z.core.$strip>>>;
+            grounding: z.ZodOptional<z.ZodObject<{
+                status: z.ZodEnum<{
+                    grounded: "grounded";
+                    ungrounded: "ungrounded";
+                    flagged: "flagged";
+                }>;
+                snapshot: z.ZodString;
+                claims: z.ZodArray<z.ZodString>;
+                template: z.ZodOptional<z.ZodString>;
+                settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    step: z.ZodString;
+                    name: z.ZodString;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+                    source: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                reason: z.ZodString;
+            }, z.core.$strip>>;
             track: z.ZodString;
             step_type: z.ZodString;
             acceptance_criteria: z.ZodArray<z.ZodString>;
             constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
             packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+            capability: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
             agent: z.ZodEnum<{
                 [x: string]: string;
             }>;

package/dist/schemas/plan-schemas.js

@@ -17,7 +17,7 @@ export const PlanStepSchema = AnalysisStepSchema.omit({
     error: true,
     maxSteps: true,
 })
-    .required({ agent: true, resources: true, packages: true })
+    .required({ agent: true, resources: true, packages: true, capability: true })
     .extend({
     agent: z.enum(plannableAgentIds).describe("Sandbox agent ID, routed by the step's primary data object. Must be one of the available agents."),
 });

package/dist/schemas/workflow-state.d.ts

@@ -5,6 +5,47 @@
  * and the completion schemas that validate LLM structured output.
  */
 import { z } from "zod";
+/**
+ * One scientific setting of a grounded step: a parameter of the procedure
+ * that `knowledge_recommend` returned, with the procedure step it belongs to
+ * and the source of its value. The host binds the settings to the template
+ * of the step at dispatch, thus a template default never replaces a plan
+ * decision silently.
+ */
+export declare const GroundingSettingSchema: z.ZodObject<{
+    step: z.ZodString;
+    name: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+    source: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GroundingSetting = z.infer<typeof GroundingSettingSchema>;
+/**
+ * The grounding of one method step: the claim identifiers and the snapshot
+ * digest that `knowledge_recommend` returned in this run, the template the
+ * step renders, the settings of the procedure, and a one-line reason.
+ * Optional on both step schemas, thus a stored plan and a plan made without
+ * the knowledge service load and validate as before. Phase 0 validates the
+ * shape only. An empty field is visible: the evaluation counts a method step
+ * without a value as ungrounded.
+ */
+export declare const GroundingSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        grounded: "grounded";
+        ungrounded: "ungrounded";
+        flagged: "flagged";
+    }>;
+    snapshot: z.ZodString;
+    claims: z.ZodArray<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        step: z.ZodString;
+        name: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type Grounding = z.infer<typeof GroundingSchema>;
 /**
  * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
  * this into the planner's output contract and emits it as the `submit_plan`
@@ -37,7 +78,25 @@ export declare const AnalysisStepSchema: z.ZodObject<{
             count: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    grounding: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            grounded: "grounded";
+            ungrounded: "ungrounded";
+            flagged: "flagged";
+        }>;
+        snapshot: z.ZodString;
+        claims: z.ZodArray<z.ZodString>;
+        template: z.ZodOptional<z.ZodString>;
+        settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            step: z.ZodString;
+            name: z.ZodString;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
     agent: z.ZodOptional<z.ZodString>;
+    capability: z.ZodOptional<z.ZodString>;
     timeout: z.ZodOptional<z.ZodNumber>;
     maxSteps: z.ZodNumber;
     description: z.ZodOptional<z.ZodString>;
@@ -74,7 +133,25 @@ export declare const AnalysisPlanSchema: z.ZodObject<{
                 count: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        grounding: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<{
+                grounded: "grounded";
+                ungrounded: "ungrounded";
+                flagged: "flagged";
+            }>;
+            snapshot: z.ZodString;
+            claims: z.ZodArray<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                step: z.ZodString;
+                name: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
         agent: z.ZodOptional<z.ZodString>;
+        capability: z.ZodOptional<z.ZodString>;
         timeout: z.ZodOptional<z.ZodNumber>;
         maxSteps: z.ZodNumber;
         description: z.ZodOptional<z.ZodString>;
@@ -146,7 +223,25 @@ export declare const ContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     count: z.ZodNumber;
                 }, z.core.$strip>>;
             }, z.core.$strip>>;
+            grounding: z.ZodOptional<z.ZodObject<{
+                status: z.ZodEnum<{
+                    grounded: "grounded";
+                    ungrounded: "ungrounded";
+                    flagged: "flagged";
+                }>;
+                snapshot: z.ZodString;
+                claims: z.ZodArray<z.ZodString>;
+                template: z.ZodOptional<z.ZodString>;
+                settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    step: z.ZodString;
+                    name: z.ZodString;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+                    source: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                reason: z.ZodString;
+            }, z.core.$strip>>;
             agent: z.ZodOptional<z.ZodString>;
+            capability: z.ZodOptional<z.ZodString>;
             timeout: z.ZodOptional<z.ZodNumber>;
             maxSteps: z.ZodNumber;
             description: z.ZodOptional<z.ZodString>;
@@ -266,7 +361,25 @@ export declare const SuspensionPayloadSchema: z.ZodObject<{
                         count: z.ZodNumber;
                     }, z.core.$strip>>;
                 }, z.core.$strip>>;
+                grounding: z.ZodOptional<z.ZodObject<{
+                    status: z.ZodEnum<{
+                        grounded: "grounded";
+                        ungrounded: "ungrounded";
+                        flagged: "flagged";
+                    }>;
+                    snapshot: z.ZodString;
+                    claims: z.ZodArray<z.ZodString>;
+                    template: z.ZodOptional<z.ZodString>;
+                    settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        step: z.ZodString;
+                        name: z.ZodString;
+                        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+                        source: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>>;
+                    reason: z.ZodString;
+                }, z.core.$strip>>;
                 agent: z.ZodOptional<z.ZodString>;
+                capability: z.ZodOptional<z.ZodString>;
                 timeout: z.ZodOptional<z.ZodNumber>;
                 maxSteps: z.ZodNumber;
                 description: z.ZodOptional<z.ZodString>;

package/dist/schemas/workflow-state.js

@@ -6,6 +6,50 @@
  */
 import { z } from "zod";
 // ── Plan structures ─────────────────────────────────────────────────
+/**
+ * One scientific setting of a grounded step: a parameter of the procedure
+ * that `knowledge_recommend` returned, with the procedure step it belongs to
+ * and the source of its value. The host binds the settings to the template
+ * of the step at dispatch, thus a template default never replaces a plan
+ * decision silently.
+ */
+export const GroundingSettingSchema = z.object({
+    step: z.string().describe("The procedure step the setting belongs to (for example `differential_expression` or `normalize`)."),
+    name: z.string().describe("The parameter name as the procedure names it (for example `alpha` or `lfc_shrink`)."),
+    value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]).describe("The value the procedure sets."),
+    source: z.string().optional().describe("The source of the value (a doi or a document) when the procedure names one. Absent otherwise."),
+});
+/**
+ * The grounding of one method step: the claim identifiers and the snapshot
+ * digest that `knowledge_recommend` returned in this run, the template the
+ * step renders, the settings of the procedure, and a one-line reason.
+ * Optional on both step schemas, thus a stored plan and a plan made without
+ * the knowledge service load and validate as before. Phase 0 validates the
+ * shape only. An empty field is visible: the evaluation counts a method step
+ * without a value as ungrounded.
+ */
+export const GroundingSchema = z.object({
+    status: z
+        .enum(["grounded", "ungrounded", "flagged"])
+        .describe("`grounded` when the step follows a returned procedure; `ungrounded` when no rule covered it or the service did not answer; `flagged` when a rule changed the outcome of the step."),
+    snapshot: z.string().describe("The `snapshot.digest` that `knowledge_recommend` returned in this run, or `none`."),
+    claims: z
+        .array(z.string())
+        .describe("The claim identifiers of the step as `knowledge_recommend` returned them (for example `R-0031@e7d0`). Empty when ungrounded."),
+    template: z
+        .string()
+        .optional()
+        .describe("The template id with its version (for example `tpl-deseq2-two-group@1.0.0`) when the step renders a template. Absent otherwise."),
+    settings: z
+        .array(GroundingSettingSchema)
+        .optional()
+        .describe("The scientific settings of the step: the parameters of the procedure steps the plan step holds, as `knowledge_recommend` returned them. " +
+        "Copy the `grounding.settings` of the skeleton step as it is, one entry per parameter, with its step, name, value, and source. " +
+        "Do not restate a setting as prose only, and do not change a value here: state a different value in the step and its reason. Absent when the step is ungrounded."),
+    reason: z
+        .string()
+        .describe("One line: the situation and the method with the rule that selects it, the side chosen for a disputed rule, or why the step is ungrounded or flagged."),
+});
 /**
  * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
  * this into the planner's output contract and emits it as the `submit_plan`
@@ -52,8 +96,18 @@ export const AnalysisStepSchema = z.object({
     })
         .optional()
         .describe("Resources the step needs. Ground the estimate in the actual data size — see the resource-estimation rules."),
+    grounding: GroundingSchema.optional().describe("The knowledge grounding of a method step: fill it from the answer of `knowledge_recommend` when that tool is attached. Omit it when no knowledge tool is attached."),
     // Execution fields
     agent: z.string().optional().describe("Assigned sandbox agent name from registry"),
+    // Optional on the persistence schema so a plan stored before this field still parses.
+    // `PlanStepSchema` re-requires it for planner output. The launch reads it with the agent id to
+    // resolve what reference data the capability declares — refer to `capabilityDataRequirement`.
+    capability: z
+        .string()
+        .optional()
+        .describe("The one capability phrase of the assigned agent that this step uses, copied EXACTLY from the agent catalog. " +
+        "One phrase, verbatim — never a paraphrase, never a list, never your own wording. " +
+        "The launch resolves the reference data that the capability declares before the run starts, so a reworded phrase loses that check and the step discovers an absent source itself."),
     timeout: z.number().optional().describe("Execution timeout in seconds (falls back to image default)"),
     maxSteps: z.number().describe("Max LLM agentic steps for sandbox agent"),
     description: z.string().optional().describe("Human-readable description of what the step produces."),

package/dist/state/artifacts.d.ts

@@ -84,6 +84,13 @@ export interface ArtifactPageQuery {
     fileType?: string;
     /** A part of the path, with no regard to case. Each character matches only itself. */
     q?: string;
+    /** The whole path, with case. It selects the one row of that path. */
+    path?: string;
+    /**
+     * Extensions in lower case, with no dot. A row is selected when the extension of its path is a member. A row with
+     * no extension never matches, and an empty list selects each row. The read compares the members as they are.
+     */
+    extensions?: readonly string[];
     sort: ArtifactPageSort;
     limit: number;
     offset: number;
@@ -100,14 +107,23 @@ export interface ArtifactPageEntry {
     stepId: string | null;
     createdAt: string;
 }
+/** The count of the selected rows that have one extension. */
+export interface ArtifactExtensionCount {
+    /** The extension in lower case with no dot, or `null` for the rows that have no extension. */
+    extension: string | null;
+    count: number;
+}
 /** One page of the ledger, and the count of the rows that the filters select. */
 export interface ArtifactPage {
     entries: ArtifactPageEntry[];
     total: number;
+    /** The selected rows by extension, in the order of the extension with `null` last. The counts sum to `total`. */
+    extensionCounts: ArtifactExtensionCount[];
 }
 /**
  * One page of the artifact ledger of an analysis, in two statements: the count of the rows that the filters
- * select, and the page. The count is a separate statement because a page past the end has no row to carry it.
+ * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
+ * row to carry it. `total` is the sum of the groups.
  *
  * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
  * grows with the ledger of the one analysis, because the count reads each filtered row.

package/dist/state/artifacts.js

@@ -179,9 +179,16 @@ export function queryAnalysisArtifacts(pool, analysisId) {
         return result.rows.map((r) => ({ path: r.path, hash: r.hash, fileType: r.file_type ?? null }));
     });
 }
+/**
+ * The extension of `path` in lower case: the text after the last dot of the file name, which is the part after the
+ * last `/`. The pattern needs one character or more before that dot and one or more after it, thus a name with no dot,
+ * a name whose only dot is its first character, and a name that ends with a dot give `NULL`.
+ */
+const EXTENSION_SQL = `lower(substring(regexp_replace(path, '^.*/', '') from '^.+\\.([^.]+)$'))`;
 /**
  * One page of the artifact ledger of an analysis, in two statements: the count of the rows that the filters
- * select, and the page. The count is a separate statement because a page past the end has no row to carry it.
+ * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
+ * row to carry it. `total` is the sum of the groups.
  *
  * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
  * grows with the ledger of the one analysis, because the count reads each filtered row.
@@ -203,11 +210,21 @@ export function queryArtifactPage(pool, analysisId, query) {
         // `LIKE` would turn `%` and `_` of the input into wildcards.
         if (query.q !== undefined)
             conditions.push(`strpos(lower(path), lower(${bind(query.q)}::text)) > 0`);
+        if (query.path !== undefined)
+            conditions.push(`path = ${bind(query.path)}`);
+        if (query.extensions !== undefined && query.extensions.length > 0) {
+            conditions.push(`${EXTENSION_SQL} = ANY(${bind([...query.extensions])}::text[])`);
+        }
         const where = conditions.join(" AND ");
         const countResult = await pool.query({
-            text: `SELECT COUNT(*)::int AS total FROM cortex_artifacts WHERE ${where}`,
+            text: `SELECT ${EXTENSION_SQL} AS extension, COUNT(*)::int AS n
+          FROM cortex_artifacts
+          WHERE ${where}
+          GROUP BY 1
+          ORDER BY 1 ASC NULLS LAST`,
             values,
         });
+        const extensionCounts = countResult.rows.map((r) => ({ extension: r.extension ?? null, count: Number(r.n) }));
         // `path` is unique in one analysis, thus it breaks each tie and two pages never overlap.
         const order = query.sort === "recent" ? "created_at DESC, path ASC" : "path ASC";
         const rowsResult = await pool.query({
@@ -228,7 +245,8 @@ export function queryArtifactPage(pool, analysisId, query) {
                 stepId: r.source_step ?? null,
                 createdAt: r.created_at,
             })),
-            total: Number(countResult.rows[0]?.total ?? 0),
+            total: extensionCounts.reduce((sum, e) => sum + e.count, 0),
+            extensionCounts,
         };
     });
 }

package/dist/state/index.d.ts

@@ -10,9 +10,9 @@ export { initCortexState } from "./init.js";
 export type { Querier } from "./db.js";
 export { upsertAnalysis, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, queryArtifactPage, countArtifactsByRuns, } from "./artifacts.js";
-export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef, ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount, } from "./artifacts.js";
+export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef, ArtifactExtensionCount, ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount, } from "./artifacts.js";
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, } from "./runs.js";
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } from "./runs.js";
 export type { InsertRunInput, RunPage, RunReservation } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";

package/dist/state/index.js

@@ -10,7 +10,7 @@ export { initCortexState } from "./init.js";
 export { upsertAnalysis, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, queryArtifactPage, countArtifactsByRuns, } from "./artifacts.js";
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, } from "./runs.js";
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, clearSandboxRef, reconcileReapedSandbox } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";

package/dist/state/runs.d.ts

@@ -21,6 +21,8 @@ export interface InsertRunInput {
     planId?: string | null;
     mandateJti?: string | null;
     mandateExpiresAt?: string | null;
+    /** The start time as an ISO string. Without it, the row gets the clock of the host. */
+    startedAt?: string;
 }
 export interface RunReservation {
     readonly row: CortexRunRow;
@@ -64,6 +66,11 @@ export declare function reserveRunById(pool: Querier, input: InsertRunInput): Re
  * most one match.
  */
 export declare function queryActiveRun(pool: Querier, analysisId: string, planId: string | null): ResultAsync<CortexRunRow | null, DbError>;
+/** The optional text filter of the run reads. */
+export interface RunTextFilter {
+    /** A part of the run id or of the plan title, with no regard to case. Each character matches only itself. */
+    q?: string;
+}
 /**
  * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
  *
@@ -80,8 +87,10 @@ export declare function queryActiveRun(pool: Querier, analysisId: string, planId
  * The status set is the one {@link queryActiveRun} uses — non-terminal means `running`. Keep the two
  * in step: a new non-terminal status added to one and not the other makes a live run invisible to
  * exactly one of its readers.
+ *
+ * With `q`, only the runs that the text filter selects are members.
  */
-export declare function queryActiveRunsByAnalysis(pool: Querier, analysisId: string): ResultAsync<CortexRunRow[], DbError>;
+export declare function queryActiveRunsByAnalysis(pool: Querier, analysisId: string, { q }?: RunTextFilter): ResultAsync<CortexRunRow[], DbError>;
 /**
  * How long a reserved run may wait for its workflow before {@link reconcileOrphanedRuns} fails it. A launch writes
  * the workflow row seconds after the reservation, and the margin covers a slow authorization gate of a managed host.
@@ -104,23 +113,36 @@ export declare function reconcileOrphanedRuns(pool: Querier, opts?: {
     now?: number;
     graceMs?: number;
 }): ResultAsync<string[], DbError>;
-export declare function updateRunStatus(pool: Querier, runId: string, status: "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds", error?: string | null): ResultAsync<void, DbError>;
+/**
+ * Write a status to a run row that is still `running`, and report whether the row changed. The first terminal write
+ * of a run wins: a row that already holds a terminal status keeps its status, its `completed_at`, and its error.
+ * The error text loses each NUL character, because Postgres rejects a NUL in text and the write must not fail for its own value.
+ */
+export declare function updateRunStatus(pool: Querier, runId: string, status: "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds", error?: string | null): ResultAsync<boolean, DbError>;
 /**
  * Conditionally transition an ACTIVE run to `canceled`, stamping `completed_at`
  * and recording `reason` in `error` (the same column `collectAndComplete`
  * stamps `external_cancel` into). Reports whether a row transitioned — false
  * means the run was already terminal (e.g. it completed concurrently with an
- * external cancel), and the caller MUST NOT fall back to `updateRunStatus`,
- * which would clobber that terminal status. The guarded set is the active set
- * `queryActiveRun` deduplicates on.
+ * external cancel). The guarded set is the active set `queryActiveRun`
+ * deduplicates on.
  */
 export declare function markRunCanceledIfActive(pool: Querier, runId: string, reason: string): ResultAsync<boolean, DbError>;
 export declare function promoteFailedToPartial(pool: Querier, runId: string): ResultAsync<boolean, DbError>;
 export declare function queryRun(pool: Querier, runId: string): ResultAsync<CortexRunRow | null, DbError>;
-export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, { limit, offset }?: {
+/**
+ * One window of the runs of an analysis, newest start first. With `q`, the window holds only the runs that the text
+ * filter selects: the filter applies before `limit` and `offset`, and it does not change the order.
+ */
+export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, { limit, offset, q }?: {
     limit?: number;
     offset?: number;
-}): ResultAsync<CortexRunRow[], DbError>;
+} & RunTextFilter): ResultAsync<CortexRunRow[], DbError>;
+/**
+ * The count of the runs of an analysis, in one statement. With `q`, the count holds only the runs that the text filter
+ * selects, thus it agrees with the windows of {@link queryRunsByAnalysis} for the same `q`.
+ */
+export declare function countRunsByAnalysis(pool: Querier, analysisId: string, { q }?: RunTextFilter): ResultAsync<number, DbError>;
 /**
  * The run ids of one plan of one analysis, newest start first, at most `limit`.
  * The run id breaks a tie of start times, highest first. A plan with no run gives
@@ -131,6 +153,17 @@ export declare function queryRunIdsByPlan(pool: Querier, opts: {
     planId: string;
     limit: number;
 }): ResultAsync<string[], DbError>;
+/**
+ * The newest run of one plan of one analysis, or `null` for a plan with no run. The order is the one of
+ * {@link queryRunIdsByPlan}: the latest start first, and the highest run id on a tie of start times.
+ */
+export declare function queryNewestPlanRun(pool: Querier, opts: {
+    analysisId: string;
+    planId: string;
+}): ResultAsync<{
+    runId: string;
+    startedAt: string;
+} | null, DbError>;
 /**
  * Read the analysis's non-terminal run activity without coupling it to a
  * conversation thread. The total is counted before the detail limit so a
@@ -146,10 +179,11 @@ export declare function queryRunsForInspection(pool: Querier, analysisId: string
     limit?: number;
     offset?: number;
 }): ResultAsync<RunPage, DbError>;
-export declare function queryRunsByThread(pool: Querier, analysisId: string, threadId: string, { limit, offset }?: {
+/** The runs of one thread of an analysis, newest start first. With `q`, the text filter applies before the window. */
+export declare function queryRunsByThread(pool: Querier, analysisId: string, threadId: string, { limit, offset, q }?: {
     limit?: number;
     offset?: number;
-}): ResultAsync<CortexRunRow[], DbError>;
+} & RunTextFilter): ResultAsync<CortexRunRow[], DbError>;
 /**
  * Persist the run mandate jti + expiry for a run. oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
  * Called by `authorizeForRun` after a successful mint so the cancel