@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/state/report-session-state.js

@@ -31,11 +31,15 @@
  * lands only when the row still holds it. Thus two concurrent turns cannot both land,
  * and the loser reads the state again.
  *
+ * A persist that names an authoring call stores the result of the call in
+ * `cortex_authoring_results`, in the transaction of the document and under the lock
+ * of the row. A second persist of the same call finds that result and writes nothing.
+ *
  * A purge of the analysis removes the row through the analysis-id cascade.
  */
-import { err, ok } from "neverthrow";
+import { err, ok, okAsync } from "neverthrow";
 import { z } from "zod";
-import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
 import { DraftDocumentSchema } from "../report-model/draft.js";
 import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
 const DerivationSourceSchema = z.object({ path: z.string(), hash: z.string() });
@@ -45,6 +49,7 @@ const DerivationRecordSchema = z.object({
     sources: z.array(DerivationSourceSchema),
     scriptHash: z.string(),
     script: z.string(),
+    toolCallId: z.string().optional(),
 });
 const DerivationListSchema = z.array(DerivationRecordSchema);
 const _assertReadError = true;
@@ -155,6 +160,40 @@ export function createReportSessionStateStore({ pool }) {
         });
     }
     function persistDocument(input) {
+        const { call } = input;
+        if (call === undefined)
+            return swapDocument(pool, input);
+        return withTransaction(pool, "report-session-state.persistDocument", (client) => 
+        // The row lock serializes each persist of the thread, thus a second run of one
+        // call waits for the first and then finds its result.
+        tryQuery("report-session-state.persistDocument.lock", () => client.query({
+            text: `SELECT (SELECT COUNT(*) FROM cortex_authoring_results WHERE thread_id = $1 AND call_key = $2)::int AS held, analysis_id
+  FROM cortex_report_session_state WHERE thread_id = $1 FOR UPDATE`,
+            values: [input.threadId, call.key],
+        })).andThen(({ rows }) => {
+            const row = rows[0];
+            if (row === undefined)
+                return okAsync("absent");
+            if (row.held > 0)
+                return okAsync("replayed");
+            return swapDocument(client, input).andThen((outcome) => outcome !== "persisted"
+                ? okAsync(outcome)
+                : tryMutation("report-session-state.persistDocument.result", () => client.query({
+                    text: "INSERT INTO cortex_authoring_results (thread_id, call_key, analysis_id, result) VALUES ($1, $2, $3, $4::jsonb)",
+                    values: [input.threadId, call.key, row.analysis_id, JSON.stringify(call.result)],
+                })).map(() => "persisted"));
+        }));
+    }
+    function readCallResult(threadId, callKey) {
+        return tryQuery("report-session-state.readCallResult", () => pool.query({
+            text: "SELECT result FROM cortex_authoring_results WHERE thread_id = $1 AND call_key = $2",
+            values: [threadId, callKey],
+        })).map(({ rows }) => {
+            const row = rows[0];
+            return row === undefined ? null : { result: row.result };
+        });
+    }
+    function swapDocument(querier, input) {
         return tryMutation("report-session-state.persistDocument", async () => {
             // The prior document rides as SQL NULL when absent, thus the compare-and-swap
             // matches a fresh row whose document column is null. A JSON `null` would be a
@@ -163,7 +202,7 @@ export function createReportSessionStateStore({ pool }) {
             // One statement tells a conflict from an absence. `existed` counts the row, and
             // `updated` counts the compare-and-swap. A row that exists but did not update
             // holds a different prior document, thus a concurrent turn landed first.
-            const { rows } = await pool.query({
+            const { rows } = await querier.query({
                 text: `WITH target AS (
     SELECT 1 FROM cortex_report_session_state WHERE thread_id = $1
   ), updated AS (
@@ -241,5 +280,5 @@ export function createReportSessionStateStore({ pool }) {
             return row.appended > 0 ? "appended" : "duplicate";
         });
     }
-    return { readState, writeSnapshot, persistDocument, stampRendered, stampSeen, appendDerivation };
+    return { readState, writeSnapshot, persistDocument, readCallResult, stampRendered, stampSeen, appendDerivation };
 }

package/dist/state/report-versions.d.ts

@@ -29,9 +29,9 @@ import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
 import type { ReportSnapshot } from "../report-model/reference-resolver.js";
 import { type SchemaIssue } from "./snapshot-parse.js";
-export type { SchemaIssue };
+export type { SchemaIssue } from "./snapshot-parse.js";
 /** The anchor and the payload of a version to record. */
-export interface RecordVersionInput {
+export type RecordVersionInput = {
     /** The block document. It rides as `unknown`, and the record parses it. */
     readonly document: unknown;
     /** The pinned snapshot, stored as given. */
@@ -44,16 +44,21 @@ export interface RecordVersionInput {
     readonly parentSeq: number | null;
     /** The earlier version that this one reuses. The parent must belong to the same analysis. */
     readonly parentVersionId?: string;
-}
+    /**
+     * The id of the version when the record makes the row. A record that replaces the
+     * version of the thread keeps the stored id. Omitted, the record mints a random id.
+     */
+    readonly versionId?: string;
+};
 /** The stable reference of a recorded version, and how the record landed. */
-export interface RecordedVersionRef {
+export type RecordedVersionRef = {
     readonly versionId: string;
     /**
      * `created` minted the row. `replaced` wrote over the one version of the
      * thread, under the same version id.
      */
     readonly outcome: "created" | "replaced";
-}
+};
 /**
  * A record the store refuses as data, before or in place of a row. Distinct from
  * `DbError`: the request describes a version that the store will not write.
@@ -97,7 +102,7 @@ export type VersionReadError = {
     readonly issues: readonly SchemaIssue[];
 };
 /** One recorded version, as the store gives it back. */
-export interface RecordedVersion {
+export type RecordedVersion = {
     readonly versionId: string;
     readonly analysisId: string;
     readonly threadId: string;
@@ -108,8 +113,8 @@ export interface RecordedVersion {
     readonly document: ReportDocument;
     readonly snapshot: ReportSnapshot;
     readonly createdAt: Date;
-}
-export interface ReportVersionStore {
+};
+export type ReportVersionStore = {
     /**
      * Record a version. The record parses the document, refuses a malformed value
      * as data with no row, and refuses a parent from a different analysis. It reads
@@ -122,11 +127,11 @@ export interface ReportVersionStore {
     getVersion(versionId: string): ResultAsync<RecordedVersion | null, DbError | VersionReadError>;
     /** The one version of a thread, or `null` for a thread with no version. */
     getThreadVersion(threadId: string): ResultAsync<RecordedVersion | null, DbError | VersionReadError>;
-}
-export interface ReportVersionStoreDeps {
+};
+export type ReportVersionStoreDeps = {
     readonly pool: Pool;
     readonly logger?: Logger;
-}
+};
 /**
  * Create a `ReportVersionStore` bound to a Postgres pool. The
  * `cortex_report_versions` table is provisioned by the state-init DDL.

package/dist/state/report-versions.js

@@ -50,8 +50,10 @@ const VERSION_COLUMNS = "version_id, analysis_id, thread_id, parent_thread_id, p
  * It writes neither `version_id` nor `created_at`: the version keeps its name, and
  * the row keeps the time of its first record.
  *
- * The returned id names the row that stands. It equals the minted id on the insert
- * arm alone, thus the caller reads which arm ran.
+ * The returned id names the row that stands. It equals the given id on the insert
+ * arm, and the stored id on the replace arm, thus the caller reads which arm ran. A
+ * second record with the id of the stored version reads as the record that made it,
+ * thus a rerun of one durable step does not read as a replacement.
  */
 const RECORD_SQL = `INSERT INTO cortex_report_versions
     (version_id, analysis_id, thread_id, parent_thread_id, parent_seq,
@@ -115,7 +117,7 @@ export function createReportVersionStore({ pool }) {
             return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: parsedSnapshot.error });
         }
         const write = () => {
-            const minted = randomUUID();
+            const minted = input.versionId ?? randomUUID();
             return tryMutation("report-versions.record.write", async () => {
                 const { rows } = await pool.query({
                     text: RECORD_SQL,

package/dist/state/runs.d.ts

@@ -10,27 +10,40 @@
  * `err(constraint_violation)` via `tryMutation`.
  */
 import type { ResultAsync } from "neverthrow";
+import type { QueryConfig } from "pg";
 import type { DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
-import type { CortexRunRow, SynthesisStatus } from "./schema.js";
-export interface InsertRunInput {
+import { type CortexRunRow, type SynthesisStatus } from "./schema.js";
+/**
+ * The row-reading surface of this module: one query over the text or config form, whose rows the mapRunRow
+ * parser types. A computed test fake satisfies this shape directly, where the row-generic of `Querier`
+ * cannot be implemented by a fake that computes its rows.
+ */
+export type RunRowQuerier = {
+    query(queryTextOrConfig: string | QueryConfig, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+        rowCount: number | null;
+    }>;
+};
+export type InsertRunInput = {
     runId: string;
     analysisId: string;
     threadId?: string | null;
     workflowName: string;
     planId?: string | null;
-    mandateJti?: string | null;
-    mandateExpiresAt?: string | null;
-}
-export interface RunReservation {
+    mandateId?: string | null;
+    /** The start time as an ISO string. Without it, the row gets the clock of the host. */
+    startedAt?: string;
+};
+export type RunReservation = {
     readonly row: CortexRunRow;
     readonly inserted: boolean;
-}
+};
 /** Bounded run rows paired with the true count before limit/offset. */
-export interface RunPage {
+export type RunPage = {
     readonly runs: CortexRunRow[];
     readonly total: number;
-}
+};
 export declare class RunIdentityCollisionError extends Error {
     readonly runId: string;
     constructor(runId: string);
@@ -64,6 +77,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 type 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 +98,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 +124,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", 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 }?: {
+export declare function queryRun(pool: RunRowQuerier, runId: string): ResultAsync<CortexRunRow | null, DbError>;
+/**
+ * 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 +164,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
@@ -142,21 +186,22 @@ export declare function queryNonTerminalRunsByAnalysis(pool: Querier, analysisId
  * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
  * contract.
  */
-export declare function queryRunsForInspection(pool: Querier, analysisId: string, { limit, offset }?: {
+export declare function queryRunsForInspection(pool: RunRowQuerier, analysisId: string, { limit, offset }?: {
     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
- * handler can revoke the mandate by `runId → jti` lookup. oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
- * The JWT itself is NOT persisted — it rides in DBOS workflow input.
+ * Persist the run mandate reference for a run. oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+ * Called by the host authorizer after it authorizes the run, so the cancel
+ * handler can revoke the mandate by `runId → mandate id` lookup. oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+ * The reference has no expiry here: the run does not depend on a clock.
  */
-export declare function setRunMandate(pool: Querier, runId: string, jti: string, expiresAt: string): ResultAsync<void, DbError>;
+export declare function setRunMandate(pool: Querier, runId: string, mandateId: string): ResultAsync<void, DbError>;
 /**
  * Record the run-level synthesis outcome on the run ledger. `synthesisReason`
  * carries operator-facing detail for a skipped/failed outcome; it stays null