@inflexa-ai/harness 0.13.0 → 0.14.0

package/dist/providers/errors.d.ts

@@ -77,6 +77,13 @@ export interface ProviderErrorClassification {
      */
     readonly retryable: boolean;
 }
+/**
+ * Walk the `cause` chain for the first numeric HTTP status. The single status
+ * walker: `classifyProviderError` keys on what this returns, so a caller asking
+ * "did the provider layer have a status to classify on?" must ask it here rather
+ * than re-implement the traversal.
+ */
+export declare function extractStatus(err: unknown): number | undefined;
 /**
  * Classify a provider failure by origin.
  *

package/dist/providers/errors.js

@@ -15,6 +15,7 @@
  * re-authenticating fixes it — which is a different remedy from every other
  * non-retryable 4xx, so it is a different kind.
  */
+import { redactSecrets } from "../input-sanitization.js";
 /**
  * Structural guard for an already-constructed `ProviderError` value. A
  * `ProviderError` is a plain object, not an `Error`, so it cannot be
@@ -71,7 +72,67 @@ export function toProviderError(e, workload) {
             cause: e,
         };
     }
-    return { type: "provider", retryable, message: detail, cause: e };
+    // The `provider` arm composes like its three siblings rather than forwarding
+    // the SDK message verbatim. It has to: when a 4xx body does not parse against
+    // the configured provider's error schema, the AI SDK falls back to
+    // `response.statusText`, so the "detail" is a bare HTTP reason phrase —
+    // `"Bad Request"` — that names neither the call nor the cause, while the
+    // status, the workload, and the body the SDK captured are all still on the
+    // `cause` chain right here.
+    //
+    // Composed strictly AFTER `classifyProviderError` has returned, so message
+    // text can never become a classification input: the harness-providers spec
+    // fixes classification on the HTTP status alone.
+    const status = extractStatus(e);
+    const lead = status === undefined ? `Provider call failed for ${workload}` : `Provider call failed for ${workload} (HTTP ${status})`;
+    // A transport that carries no reason phrase (an HTTP/2 hop yields
+    // `statusText === ""`) leaves `detail` empty; appending it regardless would
+    // trail a bare `": "` on an otherwise complete message.
+    const reason = detail.trim();
+    const diagnosed = reason ? `${lead}: ${reason}` : lead;
+    const body = extractResponseBody(e);
+    return {
+        type: "provider",
+        retryable,
+        // The excerpt trails deliberately — workload and status lead, so a
+        // downstream truncation (`profileFailureReason` cuts the line at 200)
+        // eats the least diagnostic content first.
+        message: body ? `${diagnosed} — response body: ${excerptResponseBody(body)}` : diagnosed,
+        cause: e,
+    };
+}
+/**
+ * Max characters of a captured provider response body carried in a message.
+ *
+ * Derived, not picked: the tightest downstream consumer (`profileFailureReason`,
+ * `tasks/data-profile.ts`) truncates the whole line at 200, and the lead this
+ * excerpt trails — a workload label plus `HTTP <status>` plus a reason phrase —
+ * runs to roughly 80. 120 is therefore the largest round value that cannot evict
+ * that lead.
+ *
+ * Deliberately NOT shared with that consumer's `PROFILE_ERROR_MAX_LEN`: that one
+ * bounds a `varchar` ledger column, this one bounds a message many non-ledger
+ * consumers read, and coupling them would make either one unmovable.
+ */
+const PROVIDER_BODY_EXCERPT_MAX_LEN = 120;
+/**
+ * Single-lined, secret-redacted, length-capped rendering of a captured response body. Bounding happens
+ * here rather than at a consumer because most `ProviderError` consumers truncate nothing at all, and the
+ * one that does would let an unbounded body crowd out the workload and status ahead of it.
+ *
+ * The body is an UNTRUSTED upstream/proxy payload, and this excerpt lands verbatim in the ledger's
+ * `data_profile_error` (surfaced to the UI) and the logs, whereas the composed lead does not — so
+ * secrets are redacted here and nowhere else on the message. Redaction runs on the FULL body before
+ * truncation: a token straddling the cut would otherwise be sliced into an unmatchable fragment that
+ * leaks. `redactSecrets` matches only prefixed formats (API keys, JWTs, bearer tokens, connection
+ * strings) and is safe on biological data, so a legitimate error body passes through intact.
+ */
+function excerptResponseBody(body) {
+    const singleLine = redactSecrets(body).replace(/\s+/g, " ").trim();
+    // Slice by CODE POINT, not UTF-16 unit: a raw byte body can carry astral characters, and a plain
+    // `.slice` could bisect a surrogate pair into a lone half that renders as U+FFFD.
+    const chars = [...singleLine];
+    return chars.length > PROVIDER_BODY_EXCERPT_MAX_LEN ? chars.slice(0, PROVIDER_BODY_EXCERPT_MAX_LEN - 1).join("") + "…" : singleLine;
 }
 /** Max links walked on the `cause` chain looking for a structured status. */
 const MAX_CAUSE_HOPS = 5;
@@ -88,8 +149,13 @@ const CONNECTION_ERROR_CODES = new Set([
     "UND_ERR_SOCKET",
 ]);
 const CONNECTION_ERROR_PATTERN = /fetch failed|socket hang up|network error|connection (?:refused|reset|error|closed)|econnrefused|enotfound|etimedout|terminated/i;
-/** Walk the `cause` chain for the first numeric HTTP status. */
-function extractStatus(err) {
+/**
+ * Walk the `cause` chain for the first numeric HTTP status. The single status
+ * walker: `classifyProviderError` keys on what this returns, so a caller asking
+ * "did the provider layer have a status to classify on?" must ask it here rather
+ * than re-implement the traversal.
+ */
+export function extractStatus(err) {
     let cursor = err;
     for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
         const e = cursor;
@@ -101,6 +167,25 @@ function extractStatus(err) {
     }
     return undefined;
 }
+/**
+ * Walk the `cause` chain for the first captured provider response body.
+ *
+ * This is what recovers a proxy-minted or otherwise non-conforming error body:
+ * the AI SDK keeps the raw bytes on `APICallError.responseBody` even when its
+ * own parse against the provider's error schema fails and its `message` degrades
+ * to the HTTP reason phrase. A blank body is treated as absent — an empty
+ * `— response body:` segment says less than no segment at all.
+ */
+function extractResponseBody(err) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        const e = cursor;
+        if (typeof e.responseBody === "string" && e.responseBody.trim() !== "")
+            return e.responseBody;
+        cursor = e.cause;
+    }
+    return undefined;
+}
 /** Does any link of the `cause` chain look like a transport-level failure? */
 function looksLikeConnectionError(err) {
     let cursor = err;

package/dist/runtime/pools.d.ts

@@ -1,5 +1,6 @@
 /**
- * Per-pod Postgres pool sizing — the single source of truth.
+ * Per-pod Postgres pool sizing and acquisition bounds — the single source of
+ * truth.
  *
  * Cortex runs two pools per pod against the same cluster (see the postgres-storage-backend spec): the
  * application pool (`lib/storage.ts::createPool()`) and the DBOS system-DB
@@ -21,5 +22,18 @@ export declare const DEFAULT_APP_POOL_SIZE = 12;
  * overlap during DBOS recovery, replication / monitoring users.
  */
 export declare const SAFETY_MARGIN = 5;
+/**
+ * How long a caller may wait for a connection from the app pool before the
+ * acquisition fails.
+ *
+ * The driver waits forever by default, which leaves a caller on a saturated
+ * pool with no failure mode at all — only an indefinite hang, indistinguishable
+ * from work still in progress and therefore able to stall the caller's own
+ * in-flight guard permanently. A bound turns that silent stall into a surfaced
+ * error the caller can degrade on. 30s is long enough that a healthy pool under
+ * burst never trips it, and short enough that a wedged caller surfaces well
+ * inside a human's patience.
+ */
+export declare const APP_POOL_ACQUIRE_TIMEOUT_MS = 30000;
 /** Resolve the app pool size from the optional `DB_POOL_MAX` override. */
 export declare function resolveAppPoolSize(dbPoolMax: string | undefined): number;

package/dist/runtime/pools.js

@@ -1,5 +1,6 @@
 /**
- * Per-pod Postgres pool sizing — the single source of truth.
+ * Per-pod Postgres pool sizing and acquisition bounds — the single source of
+ * truth.
  *
  * Cortex runs two pools per pod against the same cluster (see the postgres-storage-backend spec): the
  * application pool (`lib/storage.ts::createPool()`) and the DBOS system-DB
@@ -21,6 +22,19 @@ export const DEFAULT_APP_POOL_SIZE = 12;
  * overlap during DBOS recovery, replication / monitoring users.
  */
 export const SAFETY_MARGIN = 5;
+/**
+ * How long a caller may wait for a connection from the app pool before the
+ * acquisition fails.
+ *
+ * The driver waits forever by default, which leaves a caller on a saturated
+ * pool with no failure mode at all — only an indefinite hang, indistinguishable
+ * from work still in progress and therefore able to stall the caller's own
+ * in-flight guard permanently. A bound turns that silent stall into a surfaced
+ * error the caller can degrade on. 30s is long enough that a healthy pool under
+ * burst never trips it, and short enough that a wedged caller surfaces well
+ * inside a human's patience.
+ */
+export const APP_POOL_ACQUIRE_TIMEOUT_MS = 30_000;
 /** Resolve the app pool size from the optional `DB_POOL_MAX` override. */
 export function resolveAppPoolSize(dbPoolMax) {
     if (dbPoolMax === undefined || dbPoolMax === "")

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -1,10 +1,23 @@
 /**
  * Pure translation between the agent-loop / sandbox event stream and the
  * typed per-step parts the frontend renders. No DBOS, no per-run state — just the
- * label mapping, the file-tree delta extraction/fold, and the chat-data-part
- * narrowing the `sandbox-step` workflow body composes into its emitters.
+ * reconciliation-id construction, the label mapping, the file-tree delta
+ * extraction/fold, and the chat-data-part narrowing a workflow body composes
+ * into its emitters.
  */
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
+/**
+ * Stable reconciliation id for a step's reconciling parts
+ * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
+ * so the run-stream fold collapses every phase transition latest-wins onto
+ * a single frame. The client keys these by `stepId`, but the server fold
+ * keys by part `id`, so the id MUST be unique per step within the run.
+ *
+ * Every producer of these parts mints its ids here: the id is a
+ * reconciliation contract, and the fold collapses correctly only while all
+ * producers construct it identically.
+ */
+export declare function stepPartId(kind: string, runId: string, stepId: string): string;
 export declare function activityForTool(name: string, input?: unknown): string;
 /** On-change working-tree delta the sandbox executor posts per exec (paths
  *  only; the executor skips directories). */

package/dist/sandbox/sandbox-step-translate.js

@@ -1,9 +1,24 @@
 /**
  * Pure translation between the agent-loop / sandbox event stream and the
  * typed per-step parts the frontend renders. No DBOS, no per-run state — just the
- * label mapping, the file-tree delta extraction/fold, and the chat-data-part
- * narrowing the `sandbox-step` workflow body composes into its emitters.
+ * reconciliation-id construction, the label mapping, the file-tree delta
+ * extraction/fold, and the chat-data-part narrowing a workflow body composes
+ * into its emitters.
  */
+/**
+ * Stable reconciliation id for a step's reconciling parts
+ * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
+ * so the run-stream fold collapses every phase transition latest-wins onto
+ * a single frame. The client keys these by `stepId`, but the server fold
+ * keys by part `id`, so the id MUST be unique per step within the run.
+ *
+ * Every producer of these parts mints its ids here: the id is a
+ * reconciliation contract, and the fold collapses correctly only while all
+ * producers construct it identically.
+ */
+export function stepPartId(kind, runId, stepId) {
+    return `${kind}-${runId}-${stepId}`;
+}
 /** Friendly live-activity label per sandbox tool id. Falls back to the raw
  *  tool name so a newly added tool still reads sensibly. */
 const TOOL_ACTIVITY = {

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

@@ -7,8 +7,8 @@
 import { z } from "zod";
 /**
  * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
- * this into the planner's output contract and emits it as the `validate_plan` /
- * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * this into the planner's output contract and emits it as the `submit_plan`
+ * arg schema — so each field's meaning belongs in `.describe()`,
  * not in a comment the model never sees.
  */
 export declare const AnalysisStepSchema: z.ZodObject<{

package/dist/schemas/workflow-state.js

@@ -8,8 +8,8 @@ import { z } from "zod";
 // ── Plan structures ─────────────────────────────────────────────────
 /**
  * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
- * this into the planner's output contract and emits it as the `validate_plan` /
- * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * this into the planner's output contract and emits it as the `submit_plan`
+ * arg schema — so each field's meaning belongs in `.describe()`,
  * not in a comment the model never sees.
  */
 export const AnalysisStepSchema = z.object({

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

@@ -101,6 +101,13 @@ export interface DataProfileStatus {
     startedAt: string | null;
     completedAt: string | null;
     result: DataProfileResult | null;
+    /**
+     * The DBOS workflow id of the profile attempt that owns this row — the durable
+     * event stream a consumer subscribes to for this profile's activity. `null` means
+     * this profile's stream is not addressable (see
+     * {@link recordDataProfileWorkflowId}).
+     */
+    workflowId: string | null;
     seedInputFileIds: string[] | null;
 }
 /**
@@ -117,14 +124,59 @@ export interface DataProfileStatus {
  * unseeded — neither is an error, both stay in the ok channel.
  */
 export declare function tryStartDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
-/** Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}. */
+/**
+ * Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}.
+ *
+ * Clears `data_profile_workflow_id`, because the claim IS the moment a new attempt takes the row
+ * and the prior attempt's workflow is finished. Left in place it would leave the row `running`
+ * while naming a stream that has already drained, so a consumer would subscribe and observe
+ * nothing without knowing why; NULL says "not addressable yet", which is exactly true until the
+ * new body records its own id (see {@link recordDataProfileWorkflowId}).
+ */
 export declare function tryRetryDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
 /**
  * Claim a `completed` row back into `running` (the re-profile route). `data_profile_result`
  * is deliberately preserved so a consumer can keep serving the prior profile while the new
  * one runs. Carries {@link SEEDED}.
+ *
+ * `data_profile_workflow_id` is NOT preserved alongside it, and the asymmetry is the point: the
+ * result is CONTENT that stays valid until replaced, while the id is a POINTER to a live stream
+ * whose workflow is now finished. Keeping it would leave the row `running` while naming a drained
+ * stream — see {@link tryRetryDataProfile} for the same reasoning.
  */
 export declare function tryRerunDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * Record the DBOS workflow id of the attempt that owns a claimed-`running` row, so a
+ * consumer resolves which durable event stream carries this profile's activity from the
+ * ledger row alone — no durability-engine query, no id reconstructed from the workflow-id
+ * string format. The workflow BODY calls this, never the trigger: the claim CAS runs
+ * before the workflow id is minted, so only the body can report the id of the attempt
+ * that actually started.
+ *
+ * `AND data_profile_status = 'running'` buys exactly one thing: a write that lands late
+ * cannot stamp a row that has already settled, which would otherwise point a consumer at
+ * a workflow for a profile that is already finished. What it does NOT buy is
+ * disambiguation between two attempts that each believe they are the running one — the
+ * stale-expiry claim admits precisely that, since a row whose `data_profile_started_at`
+ * has aged past the timeout can be claimed by a second attempt while the first body is
+ * still alive but has not completed its first step, and that first step then overwrites
+ * the second's id.
+ *
+ * That residue is deliberately left open rather than closed. Its worst outcome is already
+ * a specified-normal state: a consumer subscribed to a superseded workflow reads a stream
+ * that has already drained, so it observes no activity — indistinguishable from "running,
+ * nothing reported yet". A missing activity line for one profile is acceptable; a wrong
+ * one would not be. And closing it costs more than it buys: either the three claim
+ * functions widen their `Result<boolean>` returns to carry the id — their callers branch
+ * on truthiness (`if (!retried)`), so an object return makes every such branch
+ * always-taken, a silent behaviour change in the embedder's recovery path — or the
+ * embedder mints the workflow ids, putting a harness-internal construction in a
+ * consumer's hands.
+ *
+ * `ok(true)` when this call stamped the row; `ok(false)` when the CAS refused it — a
+ * normal in-band outcome, not an error.
+ */
+export declare function recordDataProfileWorkflowId(pool: Querier, analysisId: string, workflowId: string): ResultAsync<boolean, DbError>;
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
  * write CAS'd on `data_profile_status = 'running'`.

package/dist/state/data-profile.js

@@ -38,21 +38,31 @@ export function tryStartDataProfile(pool, analysisId) {
     return tryMutation("dataProfile.tryStartDataProfile", async () => {
         const result = await pool.query({
             text: `UPDATE cortex_analysis_state
-            SET data_profile_status = 'running', data_profile_started_at = $1
+            SET data_profile_status = 'running', data_profile_started_at = $1,
+                data_profile_workflow_id = NULL
             WHERE analysis_id = $2 AND (data_profile_status = 'pending' OR data_profile_status IS NULL) AND ${SEEDED}`,
             values: [now, analysisId],
         });
         return (result.rowCount ?? 0) > 0;
     });
 }
-/** Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}. */
+/**
+ * Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}.
+ *
+ * Clears `data_profile_workflow_id`, because the claim IS the moment a new attempt takes the row
+ * and the prior attempt's workflow is finished. Left in place it would leave the row `running`
+ * while naming a stream that has already drained, so a consumer would subscribe and observe
+ * nothing without knowing why; NULL says "not addressable yet", which is exactly true until the
+ * new body records its own id (see {@link recordDataProfileWorkflowId}).
+ */
 export function tryRetryDataProfile(pool, analysisId) {
     const now = new Date().toISOString();
     return tryMutation("dataProfile.tryRetryDataProfile", async () => {
         const result = await pool.query({
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = 'running', data_profile_started_at = $1,
-                data_profile_error = NULL, data_profile_completed_at = NULL
+                data_profile_error = NULL, data_profile_completed_at = NULL,
+                data_profile_workflow_id = NULL
             WHERE analysis_id = $2 AND data_profile_status = 'failed' AND ${SEEDED}`,
             values: [now, analysisId],
         });
@@ -63,6 +73,11 @@ export function tryRetryDataProfile(pool, analysisId) {
  * Claim a `completed` row back into `running` (the re-profile route). `data_profile_result`
  * is deliberately preserved so a consumer can keep serving the prior profile while the new
  * one runs. Carries {@link SEEDED}.
+ *
+ * `data_profile_workflow_id` is NOT preserved alongside it, and the asymmetry is the point: the
+ * result is CONTENT that stays valid until replaced, while the id is a POINTER to a live stream
+ * whose workflow is now finished. Keeping it would leave the row `running` while naming a drained
+ * stream — see {@link tryRetryDataProfile} for the same reasoning.
  */
 export function tryRerunDataProfile(pool, analysisId) {
     const now = new Date().toISOString();
@@ -70,13 +85,56 @@ export function tryRerunDataProfile(pool, analysisId) {
         const result = await pool.query({
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = 'running', data_profile_started_at = $1,
-                data_profile_error = NULL, data_profile_completed_at = NULL
+                data_profile_error = NULL, data_profile_completed_at = NULL,
+                data_profile_workflow_id = NULL
             WHERE analysis_id = $2 AND data_profile_status = 'completed' AND ${SEEDED}`,
             values: [now, analysisId],
         });
         return (result.rowCount ?? 0) > 0;
     });
 }
+/**
+ * Record the DBOS workflow id of the attempt that owns a claimed-`running` row, so a
+ * consumer resolves which durable event stream carries this profile's activity from the
+ * ledger row alone — no durability-engine query, no id reconstructed from the workflow-id
+ * string format. The workflow BODY calls this, never the trigger: the claim CAS runs
+ * before the workflow id is minted, so only the body can report the id of the attempt
+ * that actually started.
+ *
+ * `AND data_profile_status = 'running'` buys exactly one thing: a write that lands late
+ * cannot stamp a row that has already settled, which would otherwise point a consumer at
+ * a workflow for a profile that is already finished. What it does NOT buy is
+ * disambiguation between two attempts that each believe they are the running one — the
+ * stale-expiry claim admits precisely that, since a row whose `data_profile_started_at`
+ * has aged past the timeout can be claimed by a second attempt while the first body is
+ * still alive but has not completed its first step, and that first step then overwrites
+ * the second's id.
+ *
+ * That residue is deliberately left open rather than closed. Its worst outcome is already
+ * a specified-normal state: a consumer subscribed to a superseded workflow reads a stream
+ * that has already drained, so it observes no activity — indistinguishable from "running,
+ * nothing reported yet". A missing activity line for one profile is acceptable; a wrong
+ * one would not be. And closing it costs more than it buys: either the three claim
+ * functions widen their `Result<boolean>` returns to carry the id — their callers branch
+ * on truthiness (`if (!retried)`), so an object return makes every such branch
+ * always-taken, a silent behaviour change in the embedder's recovery path — or the
+ * embedder mints the workflow ids, putting a harness-internal construction in a
+ * consumer's hands.
+ *
+ * `ok(true)` when this call stamped the row; `ok(false)` when the CAS refused it — a
+ * normal in-band outcome, not an error.
+ */
+export function recordDataProfileWorkflowId(pool, analysisId, workflowId) {
+    return tryMutation("dataProfile.recordDataProfileWorkflowId", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_workflow_id = $1
+            WHERE analysis_id = $2 AND data_profile_status = 'running'`,
+            values: [workflowId, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
  * write CAS'd on `data_profile_status = 'running'`.
@@ -213,7 +271,8 @@ export function clearDataProfile(pool, analysisId) {
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = NULL, data_profile_error = NULL,
                 data_profile_started_at = NULL, data_profile_completed_at = NULL,
-                data_profile_result = NULL, seed_input_file_ids = NULL
+                data_profile_result = NULL, data_profile_workflow_id = NULL,
+                seed_input_file_ids = NULL
             WHERE analysis_id = $1 AND data_profile_status IS DISTINCT FROM 'running'`,
             values: [analysisId],
         });
@@ -242,7 +301,7 @@ export function loadDataProfileStatus(pool, analysisId) {
         const result = await pool.query({
             text: `SELECT data_profile_status, data_profile_error,
                    data_profile_started_at, data_profile_completed_at,
-                   data_profile_result, seed_input_file_ids
+                   data_profile_result, data_profile_workflow_id, seed_input_file_ids
             FROM cortex_analysis_state WHERE analysis_id = $1`,
             values: [analysisId],
         });
@@ -255,6 +314,7 @@ export function loadDataProfileStatus(pool, analysisId) {
             startedAt: row.data_profile_started_at ?? null,
             completedAt: row.data_profile_completed_at ?? null,
             result: row.data_profile_result ?? null,
+            workflowId: row.data_profile_workflow_id ?? null,
             seedInputFileIds: row.seed_input_file_ids ?? null,
         };
     });

package/dist/state/index.d.ts

@@ -12,15 +12,15 @@ export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
 export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef } from "./artifacts.js";
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
-export type { InsertRunInput, RunReservation } from "./runs.js";
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, } 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";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
 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, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";

package/dist/state/index.js

@@ -10,11 +10,11 @@ export { initCortexState } from "./init.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
-export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/init.js

@@ -27,10 +27,22 @@ CREATE TABLE IF NOT EXISTS cortex_analysis_state (
   data_profile_started_at   TEXT,
   data_profile_completed_at TEXT,
   data_profile_result       JSONB,
+  data_profile_workflow_id  TEXT,
   created_at                TEXT NOT NULL,
   updated_at                TEXT NOT NULL
 );
 
+-- DBOS workflow id of the profile attempt that owns the row — what a consumer
+-- subscribes to in order to observe that profile's activity. Written by the
+-- workflow body, not the trigger: the ledger claim happens before the workflow id
+-- is minted, so only the body knows the id of the attempt that actually started.
+-- Nullable, and absence is a normal state rather than a defect, with two ordinary
+-- causes: a row claimed whose body has not yet recorded its id, and a row written
+-- before this column existed. Both mean "this profile's stream is not
+-- addressable", which is true in each case — hence no backfill.
+ALTER TABLE cortex_analysis_state
+  ADD COLUMN IF NOT EXISTS data_profile_workflow_id TEXT;
+
 -- File registry — artifact_id (provenance) + file_id (S3), cross-run.
 CREATE TABLE IF NOT EXISTS cortex_artifacts (
   analysis_id   TEXT NOT NULL,
@@ -207,12 +219,20 @@ CREATE INDEX IF NOT EXISTS idx_cortex_regulatory_chunks_metadata
 -- workflow and sandbox agent loops use the DBOS step cache, never this
 -- table (see the harness-thread-store spec). The (thread_id, seq) primary key already serves
 -- (thread_id, seq DESC) reads, so no separate index is needed.
+--
+-- message_envelope is JSON, not JSONB, and must stay that way. JSONB stores a
+-- re-sorted parse tree rather than the document it was given, so a tool call's
+-- input — and every other free-form payload, which has no schema to be
+-- normalized back against on read — comes back key-reordered. Those bytes are
+-- re-sent to the provider on the next turn, where a reordered prefix misses the
+-- prompt cache. JSON stores the text verbatim. Nothing indexes this column, and
+-- the JSON operators retractLastTurn uses work the same on either type.
 CREATE TABLE IF NOT EXISTS messages (
   thread_id     TEXT NOT NULL,
   seq           BIGINT NOT NULL,
   role          TEXT,
   content_jsonb JSONB,
-  message_envelope JSONB,
+  message_envelope JSON,
   tokens        INTEGER NOT NULL,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   PRIMARY KEY (thread_id, seq)
@@ -411,7 +431,22 @@ export async function initCortexState(pool, injected) {
                 // carry the NOT NULL floor, which would reject a clear. Idempotent:
                 // dropping an absent NOT NULL no-ops, so this is a no-op on fresh DBs.
                 "ALTER TABLE cortex_analysis_state ALTER COLUMN data_profile_status DROP NOT NULL",
-                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS message_envelope JSONB",
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS message_envelope JSON",
+                // Demote an existing JSONB envelope column to JSON (see the CREATE
+                // TABLE comment). Type-guarded because ALTER ... TYPE rewrites the
+                // whole table and this runs at every boot; scoped to
+                // current_schema() so parallel test schemas never see each other.
+                // Rows already written as JSONB carry over as they stand — their
+                // original key order is not recoverable.
+                `DO $$ BEGIN
+                  IF EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_schema = current_schema() AND table_name = 'messages'
+                      AND column_name = 'message_envelope' AND data_type = 'jsonb'
+                  ) THEN
+                    ALTER TABLE messages ALTER COLUMN message_envelope TYPE JSON USING message_envelope::text::json;
+                  END IF;
+                END $$`,
                 // Grant key an 'always' records the standing grant under. Nullable
                 // and unbackfilled: every new row writes it (command when absent), and
                 // orphaned legacy pending rows are swept to 'expired' before any answer

package/dist/state/runs.d.ts

@@ -26,6 +26,11 @@ export interface RunReservation {
     readonly row: CortexRunRow;
     readonly inserted: boolean;
 }
+/** Bounded run rows paired with the true count before limit/offset. */
+export interface RunPage {
+    readonly runs: CortexRunRow[];
+    readonly total: number;
+}
 export declare class RunIdentityCollisionError extends Error {
     readonly runId: string;
     constructor(runId: string);
@@ -59,6 +64,24 @@ 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>;
+/**
+ * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
+ *
+ * The counterpart to {@link queryRunsByAnalysis}, which answers "the newest N runs" — a windowed
+ * question, and the wrong one for a host driving live surfaces. Ordering by `started_at DESC` and
+ * capping means the run most worth watching is the first to fall out: a long analysis still going
+ * while ten short ones start and finish after it leaves the window entirely, so a host reading only
+ * that window loses its progress AND never learns it terminated.
+ *
+ * Unbounded is safe here in a way it is not for the general listing: this result is capped by the
+ * analysis's live concurrency, not by its history, and a run leaves the set permanently when it
+ * finishes.
+ *
+ * The status set is the one {@link queryActiveRun} uses — non-terminal means still running, or
+ * suspended awaiting funds. 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.
+ */
+export declare function queryActiveRunsByAnalysis(pool: Querier, analysisId: string): ResultAsync<CortexRunRow[], DbError>;
 export declare function updateRunStatus(pool: Querier, runId: string, status: "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds", error?: string | null): ResultAsync<void, DbError>;
 export declare function promoteFailedToPartial(pool: Querier, runId: string): ResultAsync<boolean, DbError>;
 export declare function queryRun(pool: Querier, runId: string): ResultAsync<CortexRunRow | null, DbError>;
@@ -66,6 +89,22 @@ export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, {
     limit?: number;
     offset?: number;
 }): ResultAsync<CortexRunRow[], 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
+ * bounded prompt projection can disclose omitted rows.
+ */
+export declare function queryNonTerminalRunsByAnalysis(pool: Querier, analysisId: string, limit?: number): ResultAsync<RunPage, DbError>;
+/**
+ * Read one stable inspection page: running first, then suspended, then
+ * terminal history. This is deliberately separate from
+ * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
+ * contract.
+ */
+export declare function queryRunsForInspection(pool: Querier, analysisId: string, { limit, offset }?: {
+    limit?: number;
+    offset?: number;
+}): ResultAsync<RunPage, DbError>;
 export declare function queryRunsByThread(pool: Querier, analysisId: string, threadId: string, { limit, offset }?: {
     limit?: number;
     offset?: number;