@inflexa-ai/harness 0.44.0 → 0.45.0

package/dist/execution/run-event-stream.d.ts

@@ -36,6 +36,11 @@ import type { ChatPart } from "../contracts/chat-parts.js";
 import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
 import type { RunStatus } from "../state/schema.js";
+/** The part of a run row that the terminal part is made from. */
+export interface RunEventRunRead {
+    readonly status: RunStatus;
+    readonly error: string | null;
+}
 /**
  * Construction-time dependencies. The pool is the application pool the run
  * ledger lives in; the logger is where every contained failure is reported, and
@@ -45,8 +50,13 @@ import type { RunStatus } from "../state/schema.js";
 export interface RunEventStreamDeps {
     readonly pool: Pool;
     readonly logger?: Logger;
-    /** Reads the status of the run row, `null` when no row exists. Defaults to `queryRun` on `pool`. */
-    readonly readRunStatus?: (runId: string) => ResultAsync<RunStatus | null, DbError>;
+    /** Reads the status and the error of the run row, `null` when no row exists. Defaults to `queryRun` on `pool`. */
+    readonly readRun?: (runId: string) => ResultAsync<RunEventRunRead | null, DbError>;
+    /**
+     * Reads the status of the parent workflow in the durability engine, `null` when no workflow exists. Defaults to
+     * `DBOS.getWorkflowStatus`.
+     */
+    readonly readWorkflowStatus?: (runId: string) => Promise<string | null>;
     /** The wait between two reads of the run row. Defaults to a timer. */
     readonly sleep?: (ms: number) => Promise<void>;
 }
@@ -78,10 +88,12 @@ export interface RunEventStream {
      * aborts.
      *
      * A canceled workflow runs no more steps, thus it never writes its own
-     * terminal part, and the canceler cannot write a stream. When the parent
-     * stream ends with no `data-run-completed` or `data-run-failed` part and
-     * the run row reads `canceled`, the last part delivered is a
-     * `data-run-failed` part with `reason: "canceled"`.
+     * terminal part, and the canceler cannot write a stream. When every stream
+     * ends with no `data-run-completed` or `data-run-failed` part, the last
+     * part delivered is a `data-run-failed` part that the run row gives, or the
+     * status of the parent workflow when the row still reads `running`. A row
+     * that does not exist, a `completed` or `partial` row, an active workflow,
+     * and no workflow give no part.
      *
      * Parts from one workflow arrive in the order that workflow wrote them. No
      * order is promised ACROSS the parent and its children: those workflows

package/dist/execution/run-event-stream.js

@@ -37,6 +37,28 @@ import { describeDbError } from "../lib/db-result.js";
 import { queryRun } from "../state/runs.js";
 import { queryStepsByRun } from "../state/step-executions.js";
 import { foldRunEventParts, parseRunEventPart } from "./run-event-parts.js";
+const canceledPart = (runId) => ({ type: "data-run-failed", runId, error: "Run canceled", reason: "canceled" });
+/** The terminal part that a settled run row gives, or `null` when the body of the run writes the part. */
+function partOfRow(runId, row) {
+    switch (row.status) {
+        case "canceled":
+            return canceledPart(runId);
+        case "suspended_insufficient_funds":
+            return row.error === null
+                ? { type: "data-run-failed", runId, error: "Run suspended" }
+                : { type: "data-run-failed", runId, error: row.error, reason: row.error };
+        case "failed":
+            return { type: "data-run-failed", runId, error: row.error ?? "Run failed" };
+        case "completed":
+        case "partial":
+        case "running":
+            return null;
+        default: {
+            const _exhaustive = row.status;
+            throw new Error(`unhandled run status: ${String(_exhaustive)}`);
+        }
+    }
+}
 /** Durable stream key every run producer writes its parts under. */
 const RUN_EVENT_STREAM_KEY = "events";
 /**
@@ -58,8 +80,8 @@ const CHILD_DISCOVERY_INTERVAL_MS = 1_000;
  * the stream can end before the row changes, and the later reads wait out that
  * window.
  */
-const CANCELED_ROW_READ_ATTEMPTS = 4;
-const CANCELED_ROW_READ_INTERVAL_MS = 500;
+const TERMINAL_ROW_READ_ATTEMPTS = 4;
+const TERMINAL_ROW_READ_INTERVAL_MS = 500;
 /**
  * Build the DBOS-backed realization of {@link RunEventStream}.
  *
@@ -72,7 +94,8 @@ const CANCELED_ROW_READ_INTERVAL_MS = 500;
  */
 export function createRunEventStream(deps) {
     const baseLogger = (deps.logger ?? createNoopLogger()).named("run-event-stream");
-    const readRunStatus = deps.readRunStatus ?? ((runId) => queryRun(deps.pool, runId).map((row) => row?.status ?? null));
+    const readRun = deps.readRun ?? ((runId) => queryRun(deps.pool, runId).map((row) => (row === null ? null : { status: row.status, error: row.error })));
+    const readWorkflowStatus = deps.readWorkflowStatus ?? (async (runId) => (await DBOS.getWorkflowStatus(runId))?.status ?? null);
     const waitForRowRead = deps.sleep ?? sleep;
     return {
         async subscribe({ runId, onPart, signal }) {
@@ -210,37 +233,64 @@ export function createRunEventStream(deps) {
                     await Promise.race([sleep(CHILD_DISCOVERY_INTERVAL_MS), aborted, parentRead]);
                 }
             })();
-            const canceledTerminalPart = async () => {
-                for (let attempt = 1; attempt <= CANCELED_ROW_READ_ATTEMPTS; attempt++) {
-                    const read = await readRunStatus(runId);
+            const workflowTerminalPart = async () => {
+                let workflowStatus;
+                try {
+                    workflowStatus = await readWorkflowStatus(runId);
+                }
+                catch (err) {
+                    logger.warn("workflow status read failed", logger.errorFields(err));
+                    return null;
+                }
+                switch (workflowStatus) {
+                    case "CANCELLED":
+                        return canceledPart(runId);
+                    case "ERROR":
+                    case "MAX_RECOVERY_ATTEMPTS_EXCEEDED":
+                    case "SUCCESS":
+                        return { type: "data-run-failed", runId, error: "Run ended without a terminal status" };
+                    case "PENDING":
+                    case "ENQUEUED":
+                    case "DELAYED":
+                        logger.warn("run streams ended while the workflow is active", { workflowStatus });
+                        return null;
+                    default:
+                        // No workflow: the launch did not start it, or it never started. An unknown status gives no part too.
+                        if (workflowStatus !== null)
+                            logger.warn("unknown workflow status", { workflowStatus });
+                        return null;
+                }
+            };
+            const missingTerminalPart = async () => {
+                let rowReadsRunning = false;
+                for (let attempt = 1; attempt <= TERMINAL_ROW_READ_ATTEMPTS; attempt++) {
+                    const read = await readRun(runId);
+                    rowReadsRunning = false;
                     if (read.isErr()) {
                         logger.warn("run row read failed", { err: describeDbError(read.error) });
                     }
                     else {
-                        const status = read.value;
-                        if (status === "canceled")
-                            return { type: "data-run-failed", runId, error: "Run canceled", reason: "canceled" };
                         // The launch writes the row before the workflow starts, thus
                         // no row means that the id is not an analysis run.
-                        if (status === null)
-                            return null;
-                        // Only an active row can still become `canceled`.
-                        if (status !== "running" && status !== "suspended_insufficient_funds")
+                        if (read.value === null)
                             return null;
+                        if (read.value.status !== "running")
+                            return partOfRow(runId, read.value);
+                        rowReadsRunning = true;
                     }
-                    if (attempt < CANCELED_ROW_READ_ATTEMPTS)
-                        await Promise.race([waitForRowRead(CANCELED_ROW_READ_INTERVAL_MS), aborted]);
+                    if (attempt < TERMINAL_ROW_READ_ATTEMPTS)
+                        await Promise.race([waitForRowRead(TERMINAL_ROW_READ_INTERVAL_MS), aborted]);
                     if (signal.aborted)
                         return null;
                 }
-                return null;
+                return rowReadsRunning ? workflowTerminalPart() : null;
             };
             const settled = (async () => {
                 await discovery;
                 await parentRead;
                 await Promise.all(childReads);
                 if (!sawTerminal && !signal.aborted) {
-                    const terminal = await canceledTerminalPart();
+                    const terminal = await missingTerminalPart();
                     if (terminal !== null)
                         pending.push(terminal);
                 }

package/dist/execution/run-synthesis.d.ts

@@ -24,6 +24,7 @@
  * `failed` part. We do not throw here for routine submitter rejections.
  */
 import { type RunSynthesis } from "../schemas/run-synthesis.js";
+import type { RunSynthesisPart } from "../contracts/chat-parts.js";
 import type { StepSummary } from "../schemas/step-summary.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
@@ -119,6 +120,26 @@ export interface PersistSynthesisInput {
     readonly synthesis: RunSynthesis;
 }
 export declare function persistSynthesis(args: PersistSynthesisInput): Promise<string>;
+export interface ReadSynthesisInput {
+    /** Absolute host root of the analysis's workspace tree. */
+    readonly workspaceRoot: string;
+    readonly runId: string;
+}
+/**
+ * Read the text of a synthesis record under the cap, or give `undefined` when the bytes do not come back.
+ *
+ * The read takes a bounded byte window, thus a file of any size costs the cap. A run id that can escape
+ * the run tree, an absent file, a genuine read fault, and a file over the cap each give `undefined`,
+ * because a collection reports no error for one record.
+ */
+export declare function readSynthesisText(args: ReadSynthesisInput): Promise<string | undefined>;
+/**
+ * The validated synthesis record of a run as the flat `data-run-synthesis` part, the shape that the run
+ * stream carries for the same record. It gives `null` for each fault of {@link readSynthesisText}, for text
+ * that is not JSON, and for JSON that fails {@link RunSynthesisSchema}. The run row stays the authority on
+ * whether a synthesis exists, thus the read does not consult it.
+ */
+export declare function readRunSynthesis(args: ReadSynthesisInput): Promise<RunSynthesisPart | null>;
 export declare function formatSynthesisEmbeddingText(synthesis: RunSynthesis): string;
 /**
  * Build the `data-run-synthesis` chat part the parent stream emits when the

package/dist/execution/run-synthesis.js

@@ -23,16 +23,18 @@
  * resolves with `{ kind: "failed" }`, the wrapper emits a synthesis-progress
  * `failed` part. We do not throw here for routine submitter rejections.
  */
-import { readFile } from "node:fs/promises";
+import { open, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
+import { tryFs } from "../lib/fs-result.js";
 import { hintForZodIssue } from "../lib/zod-issues.js";
 import { BiologicalThemeSchema, KeyReferenceSchema, RunSynthesisSchema, SynthesizedFindingSchema, } from "../schemas/run-synthesis.js";
 import { synthesisAgentPrompt } from "../prompts/synthesis-agent.js";
 import { composeSystemPrompt } from "../agents/system-prompt.js";
-import { runDir } from "../workspace/paths.js";
+import { flattenDataPart } from "../contracts/chat-frame.js";
+import { isSafeId, runDir } from "../workspace/paths.js";
 import { decodeObjectString } from "../lib/zod-issues.js";
 import { runToTerminal } from "../loop/run-to-terminal.js";
 import { passthroughStep } from "../loop/run-step.js";
@@ -435,15 +437,87 @@ export async function loadStepSummariesFromDisk(args) {
     }
     return out;
 }
+/** The file name of the synthesis record inside the run directory. */
+const SYNTHESIS_FILE = "synthesis.json";
+/**
+ * The cap of one synthesis read. A synthesis record is small by construction, and the cap bounds the
+ * cost of a file that is not. A file over the cap gives no text, because a cut JSON text cannot parse.
+ */
+const SYNTHESIS_CAP_BYTES = 1024 * 1024;
 export async function persistSynthesis(args) {
     // Confine to the run directory, not the whole workspace: synthesis.json sits
     // at runs/{runId}/, above any step's RW mount and never in the hard-linked
     // `data/` inputs.
     const runRoot = join(args.workspaceRoot, runDir(args.runId));
-    const path = join(runRoot, "synthesis.json");
+    const path = join(runRoot, SYNTHESIS_FILE);
     await writeFileWithinRoot(runRoot, path, JSON.stringify(args.synthesis, null, 2));
     return path;
 }
+/**
+ * Read the text of a synthesis record under the cap, or give `undefined` when the bytes do not come back.
+ *
+ * The read takes a bounded byte window, thus a file of any size costs the cap. A run id that can escape
+ * the run tree, an absent file, a genuine read fault, and a file over the cap each give `undefined`,
+ * because a collection reports no error for one record.
+ */
+export async function readSynthesisText(args) {
+    // The path builder refuses an id that can escape the run tree with a throw. The guard keeps the read on
+    // the value channel.
+    if (!isSafeId(args.runId)) {
+        return undefined;
+    }
+    const absolute = join(args.workspaceRoot, runDir(args.runId), SYNTHESIS_FILE);
+    return tryFs("runSynthesis.readText", async () => {
+        const handle = await open(absolute, "r");
+        try {
+            // The window takes one byte more than the cap. A read that fills it states that the file
+            // holds more bytes than the cap admits, thus the two conditions stay apart.
+            const buffer = Buffer.alloc(SYNTHESIS_CAP_BYTES + 1);
+            // One read of a network-backed file can give fewer bytes than the window holds. Such a
+            // short read cuts the text in the middle of the JSON, and the record then parses to no
+            // key at all. Thus the loop reads again from the offset that the last read reached, and
+            // it stops when the window fills or when a read gives no byte.
+            let filled = 0;
+            while (filled < buffer.length) {
+                const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, filled);
+                if (bytesRead === 0) {
+                    break;
+                }
+                filled += bytesRead;
+            }
+            return filled > SYNTHESIS_CAP_BYTES ? undefined : buffer.subarray(0, filled).toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }, { path: absolute, onAbsent: () => undefined }).unwrapOr(undefined);
+}
+/**
+ * The validated synthesis record of a run as the flat `data-run-synthesis` part, the shape that the run
+ * stream carries for the same record. It gives `null` for each fault of {@link readSynthesisText}, for text
+ * that is not JSON, and for JSON that fails {@link RunSynthesisSchema}. The run row stays the authority on
+ * whether a synthesis exists, thus the read does not consult it.
+ */
+export async function readRunSynthesis(args) {
+    const text = await readSynthesisText(args);
+    if (text === undefined) {
+        return null;
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const parsed = RunSynthesisSchema.safeParse(json);
+    if (!parsed.success) {
+        return null;
+    }
+    // The payload comes from a validated `RunSynthesis`, and the builder sets each field of the part contract.
+    // The tests parse the result with `RunSynthesisPartSchema`.
+    return flattenDataPart(buildRunSynthesisPart(args.runId, parsed.data));
+}
 // ── Embedding text ──────────────────────────────────────────────────
 export function formatSynthesisEmbeddingText(synthesis) {
     return [

package/dist/index.d.ts

@@ -16,6 +16,10 @@ export { resolveCompositionEyes } from "./runtime/assemble.js";
 export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/assemble.js";
 export { createReportSessionSpawn } from "./app/spawn-report-session.js";
 export type { ReportSessionSpawn, ReportSessionSpawnDeps, ReportSessionPaging, SpawnRefusal, ReportBrief, ReportSessionDelta, NewestReportChild, } from "./app/spawn-report-session.js";
+export { launchPlanRun } from "./tools/execute-analysis.js";
+export type { LaunchPlanRunDeps, LaunchPlanRunRefusal, PlanLaunch } from "./tools/execute-analysis.js";
+export { approvePlan } from "./app/approve-plan.js";
+export type { ApprovePlanDeps, ApprovePlanInput, ApprovePlanRefusal, PlanApproval } from "./app/approve-plan.js";
 export type { EnsureSessionStateResult } from "./app/report-session-runtime.js";
 export { bootHarness } from "./runtime/boot.js";
 export type { BootHarnessDeps, BootedHarness } from "./runtime/boot.js";
@@ -85,7 +89,7 @@ export { createStreamingChat } from "./providers/streaming-chat.js";
 export { openChatTurn, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
 export type { ChatTurnOutcome, ChatTurnRan, ChatTurnRefusal, ChatTurnResult, ChatTurnSession, OpenChatTurn, OpenChatTurnParams, PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult, RunChatTurnDeps, RunChatTurnParams, RunOpenChatTurnParams, } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
-export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
+export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ListRecentThreadsInput, ThreadPage, } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 export type { ThreadHistory, StoredMessage, RetractOutcome, ConversationTurn, TurnWrite, TurnWriteResult, TurnClose, TurnStatus, StoredTurnRecord, } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
@@ -96,10 +100,12 @@ export type { ConversationDisplayMetadata, ConversationUIData, ConversationUIMes
 export { storedMessagesToChat } from "./memory/conversation-display-replay.js";
 export type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
 export { toChatFrame, applyChatFrame, checkChatPart } from "./contracts/chat-frame.js";
+export { createSubAgentActivityTracker, SUBAGENT_ACTIVITY_MAX_ENTRIES } from "./contracts/subagent-activity.js";
+export type { SubAgentActivityTracker } from "./contracts/subagent-activity.js";
 export type { TextPart, ToolCallPart, MessagePart, ChatMessage } from "./contracts/message.js";
 export type { TurnTerminal, ApplyFrameResult, ChatPartCheck } from "./contracts/chat-frame.js";
 export type { TokenUsageRollup } from "./contracts/usage.js";
-export type { ChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, StepStatus, StepActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, CompactionPart, AskPart, ChildSessionStartedPart, ReportRenderedPart, } from "./contracts/chat-parts.js";
+export type { ChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, PlanApprovalPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, PlanGraphStep, StepStatus, StepActivityPart, ActivityEntryPart, SubAgentActivityEntry, SubAgentActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, FindingReference, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, CompactionPart, AskPart, ChildSessionStartedPart, ReportRenderedPart, } from "./contracts/chat-parts.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 export type { ChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./contracts/part-registry.js";
 export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./contracts/structure-source.js";
@@ -115,7 +121,7 @@ export { createPool } from "./lib/storage.js";
 export type { PoolConfig } from "./lib/storage.js";
 export type { Pool } from "pg";
 export { registerDataProfileWorkflow, triggerDataProfile, runDataProfile, describeDataProfileStartError } from "./tasks/data-profile.js";
-export type { DataProfileDeps, DataProfileWorkflowInput, DataProfileTriggerDeps, DataProfileTriggerParams, DataProfileTriggerResult, DataProfileStartError, } from "./tasks/data-profile.js";
+export type { DataProfileDeps, DataProfileWorkflowInput, DataProfileTriggerDeps, DataProfileTriggerParams, DataProfileTriggerResult, DataProfileStartError, DataProfileSettlement, NotifyDataProfileSettled, } from "./tasks/data-profile.js";
 /**
  * The synthetic run id the data-profile workflow stamps onto its own frame — the profile has no run
  * row, so this literal is the only thing that identifies its work as the profile's.
@@ -132,6 +138,12 @@ export { upsertAnalysis } from "./state/analyses.js";
 export { clearDataProfile, loadDataProfileStatus, tryRetryDataProfile, reconcileOrphanedDataProfile } from "./state/data-profile.js";
 export type { DataProfileAxis, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileCoverage, DataProfileDimension, DataProfileFile, DataProfileGroup, DataProfileGroupSlot, DataProfileInputSignature, DataProfileKind, DataProfileLifecycleStatus, DataProfileMemberAnnotation, DataProfileObservation, DataProfileOrganism, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileResult, DataProfileSubjectSource, } from "./contracts/data-profile.js";
 export type { DataProfileStatus } from "./state/data-profile.js";
+export { queryLatestRunsByAnalyses, queryDataProfileStatusByAnalyses, queryRunProgressByRuns, queryRunsEndedSince } from "./state/analyses-metrics.js";
+export type { DataProfileSummary, EndedRunSummary, LatestRunSummary, RunProgressSummary } from "./state/analyses-metrics.js";
+export { queryArtifactPage, countArtifactsByRuns } from "./state/artifacts.js";
+export type { ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount } from "./state/artifacts.js";
+export { readRunSynthesis } from "./execution/run-synthesis.js";
+export type { ReadSynthesisInput } from "./execution/run-synthesis.js";
 export { DIMENSION_CATEGORIES, DIMENSION_CATEGORY_IDS, DIMENSION_PROBES, DIMENSION_PROBE_IDS, GROUP_CATEGORIES, GROUP_CATEGORY_IDS, GROUP_ROLES, GROUP_ROLE_IDS, PROBE_OUTCOME_IDS, dimensionCategoryEntry, dimensionScope, groupCategoryEntry, } from "./contracts/profile-vocabulary.js";
 export type { DimensionCategory, DimensionCategoryEntry, DimensionProbe, DimensionProbeEntry, DimensionScope, DimensionTreatment, GroupCategory, GroupCategoryEntry, GroupRole, GroupRoleEntry, ProbeOutcome, } from "./contracts/profile-vocabulary.js";
 export { dimensionCardinalities, profileCaveats, profileDatasetFileCount, profileDimensions, profileFileRecords, profileGroups, } from "./app/data-profile-view.js";
@@ -165,22 +177,24 @@ export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult,
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
 export { createRunEventStream } from "./execution/run-event-stream.js";
-export type { RunEventStream, RunEventStreamDeps, RunEventSubscribeOptions, RunEventPartHandler } from "./execution/run-event-stream.js";
+export type { RunEventStream, RunEventStreamDeps, RunEventRunRead, RunEventSubscribeOptions, RunEventPartHandler } from "./execution/run-event-stream.js";
 export { pipeFoldedRunEvents } from "./execution/run-event-parts.js";
 export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.js";
 export type { SandboxAgentDeps, SandboxStepCoords, AgentMeta } from "./agents/sandbox/index.js";
 export { AnalysisPlanSchema } from "./schemas/workflow-state.js";
 export type { AnalysisPlan, AnalysisStep } from "./schemas/workflow-state.js";
 export type { PlanStep } from "./workflows/execute-analysis-scheduler.js";
+export { planGraphOf } from "./workflows/plan/graph.js";
+export { planPartOf } from "./memory/card-builders.js";
 export { validatePlan } from "./schemas/validate-plan.js";
 export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
-export { upsertPlan, loadPlan } from "./state/plans.js";
-export type { UpsertPlanInput } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
+export type { UpsertPlanInput, PlanRecord } from "./state/plans.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export type { InsertRunInput, RunReservation } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
-export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.js";
+export type { CortexRunRow, StepExecutionRow, RunStatus, TerminalRunStatus } from "./state/schema.js";
 export type { DbError } from "./lib/db-result.js";
 export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
 export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset } from "./reference-data/catalog.js";

package/dist/index.js

@@ -22,6 +22,11 @@ export { resolveCompositionEyes } from "./runtime/assemble.js";
 // the report sessions of one analysis. An embedder reaches the listing for its
 // navigation surface, thus these names belong on the front door.
 export { createReportSessionSpawn } from "./app/spawn-report-session.js";
+// Start the run of a stored plan, and approve a plan by its id. Each gives a `Result` and never throws, thus
+// a host route calls them with no `try`. `CoreRuntime.approvePlan` binds the approval over the deps of the
+// conversation agent.
+export { launchPlanRun } from "./tools/execute-analysis.js";
+export { approvePlan } from "./app/approve-plan.js";
 // The harness-owned boot sequence: ordered boot steps around `assembleCoreRuntime`
 // (skill validation → state init → connection budget → assemble → launch) + a
 // `shutdown` handle the embedder wires to its process signals.
@@ -156,6 +161,7 @@ export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/co
 // by dropping that part, so one stale row cannot fail a whole thread.
 export { storedMessagesToChat } from "./memory/conversation-display-replay.js";
 export { toChatFrame, applyChatFrame, checkChatPart } from "./contracts/chat-frame.js";
+export { createSubAgentActivityTracker, SUBAGENT_ACTIVITY_MAX_ENTRIES } from "./contracts/subagent-activity.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 // The source grammar of a `structure` presentation card — a host re-runs the same parse over a
 // persisted `url` before it fetches, so the rule lives in one place for both sides.
@@ -215,6 +221,12 @@ export { upsertAnalysis } from "./state/analyses.js";
 // analysis's input set empties (deferring on a running workflow), so the UI
 // stops advertising a profile that describes files the analysis no longer has.
 export { clearDataProfile, loadDataProfileStatus, tryRetryDataProfile, reconcileOrphanedDataProfile } from "./state/data-profile.js";
+// The grouped reads that summarize a page of analyses: one statement for the whole list.
+export { queryLatestRunsByAnalyses, queryDataProfileStatusByAnalyses, queryRunProgressByRuns, queryRunsEndedSince } from "./state/analyses-metrics.js";
+// The artifact ledger reads of one analysis: one page with an exact total, and the step-output count of each run of a list in one statement.
+export { queryArtifactPage, countArtifactsByRuns } from "./state/artifacts.js";
+// The validated synthesis record of a run as the flat `data-run-synthesis` part of the run stream, or null.
+export { readRunSynthesis } from "./execution/run-synthesis.js";
 // The controlled vocabulary the profiler draws from, as data. A consumer rendering a
 // stored group needs the category's meaning, and the package owns the catalogue — a host
 // does not extend it.
@@ -277,12 +289,14 @@ export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.
 // an embedder supplies the plan's step DATA and the harness composes each step's
 // seed at dispatch, when the step's dependencies have actually produced something.
 export { AnalysisPlanSchema } from "./schemas/workflow-state.js";
+export { planGraphOf } from "./workflows/plan/graph.js";
+export { planPartOf } from "./memory/card-builders.js";
 export { validatePlan } from "./schemas/validate-plan.js";
 // Plan + run + step ledgers around a trigger. `upsertPlan` takes a
 // caller-derived id and inserts-if-absent (the deterministic-id intake path);
 // the run-state calls mirror the chat trigger's reserve → dedup → status flow.
-export { upsertPlan, loadPlan } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 // Host-neutral reference-data catalog and shared installation receipts. Each
 // artifact names the third-party upstream it is fetched from; embedders own all

package/dist/lib/hooks.d.ts

@@ -29,7 +29,7 @@ export interface NoticeFailure {
     readonly reason: string;
 }
 export type GateName = "RunAuthorizer.authorize" | "RunCharge.open" | "ArtifactRegistry.register" | "resolveRequestHeaders" | "resolveSandboxLabels";
-export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByJti" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record";
+export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByJti" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record" | "notifyDataProfileSettled";
 export type GateRefusal = {
     readonly kind: "failed";
     readonly gate: GateName;

package/dist/lib/metrics.d.ts

@@ -32,8 +32,8 @@
  * 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";
+/** Terminal status of a run, the same as the run ledger. */
+export type RunOutcome = "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds";
 /** The workflow family a run belongs to. */
 export type RunWorkflow = "analysis" | "data_profile";
 /** Terminal status of an executed step. A blocker is a failure to deliver, so `blocked` maps here to `failed`. */

package/dist/loop/run-agent.js

@@ -97,6 +97,7 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
     const source = {
         agentId: session.provenance.agentId ?? agent.id,
         callPath: session.provenance.callPath,
+        ...(opts.invocationId === undefined ? {} : { invocationId: opts.invocationId }),
     };
     const policy = opts.compaction;
     const viewOptions = { keepFirstTurn: policy?.keepFirstTurn === true };

package/dist/loop/types.d.ts

@@ -46,6 +46,8 @@ export type RunStep = <T>(name: string, fn: () => Promise<T>) => Promise<T>;
 export interface EventSource {
     readonly agentId: string;
     readonly callPath: readonly string[];
+    /** The id of the tool call that runs this loop. For a data profile, the workflow id of its attempt. */
+    readonly invocationId?: string;
 }
 /**
  * Orchestration events the loop emits: iteration boundaries and tool-call

package/dist/memory/card-builders.d.ts

@@ -16,9 +16,12 @@
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type DbError } from "../lib/db-result.js";
+import type { PlanPart } from "../contracts/chat-parts.js";
+import { type PlanRecord } from "../state/index.js";
 export interface PlanCardData {
     id: string;
     planId: string;
+    parentPlanId?: string;
     title?: string;
     steps: unknown;
     analytical_narrative: unknown;
@@ -37,6 +40,14 @@ export interface RunCardData {
     title: string;
     stepCount: number;
 }
+/** Build the `data-plan` payload of a stored plan record. `null` when the
+ *  document no longer parses. An explicit `title` overrides the plan title. */
+export declare function planCardOf(record: PlanRecord, title?: string): PlanCardData | null;
+/** The `data-plan` part of a stored plan record, with the title of the plan. The
+ *  part schema drops each key that it does not name, thus the part equals the
+ *  stored card of a transcript. `null` when the document does not parse or the
+ *  schema refuses the part. */
+export declare function planPartOf(record: PlanRecord): PlanPart | null;
 /** Build the `data-plan` payload by loading the stored plan. `ok(null)` when
  *  the plan is missing or no longer parses (absence is NOT an error) — the
  *  caller falls back to a chip. */

package/dist/memory/card-builders.js

@@ -16,8 +16,9 @@
 import { createHash } from "node:crypto";
 import { okAsync } from "neverthrow";
 import { tryQuery } from "../lib/db-result.js";
+import { PlanPartSchema } from "../contracts/schemas/chat-parts.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
-import { loadPlan } from "../state/index.js";
+import { loadPlan, loadPlanRecord } from "../state/index.js";
 import { parseStructureUrl } from "../contracts/structure-source.js";
 import { normalizeEchartSpec } from "../tools/display/normalize-echart-spec.js";
 import { validatePath } from "../tools/lib/path-validation.js";
@@ -32,30 +33,43 @@ function presentationId(input) {
         .slice(0, 16);
     return `pres-${hash}`;
 }
+/** Build the `data-plan` payload of a stored plan record. `null` when the
+ *  document no longer parses. An explicit `title` overrides the plan title. */
+export function planCardOf(record, title) {
+    const parsed = AnalysisPlanSchema.safeParse(record.plan);
+    if (!parsed.success)
+        return null;
+    const id = `pres-${createHash("sha256").update(record.planId).digest("hex").slice(0, 16)}`;
+    // Explicit `show_plan({ title })` overrides; otherwise default to the
+    // planner-set plan title so both cards share one source.
+    const heading = title ?? parsed.data.title;
+    return {
+        id,
+        planId: record.planId,
+        ...(record.parentPlanId !== null ? { parentPlanId: record.parentPlanId } : {}),
+        ...(heading !== undefined ? { title: heading } : {}),
+        steps: parsed.data.steps,
+        analytical_narrative: parsed.data.analytical_narrative,
+        omicsType: parsed.data.omicsType,
+        omicsSubtype: parsed.data.omicsSubtype,
+    };
+}
+/** The `data-plan` part of a stored plan record, with the title of the plan. The
+ *  part schema drops each key that it does not name, thus the part equals the
+ *  stored card of a transcript. `null` when the document does not parse or the
+ *  schema refuses the part. */
+export function planPartOf(record) {
+    const card = planCardOf(record);
+    if (!card)
+        return null;
+    const part = PlanPartSchema.safeParse({ type: "data-plan", ...card });
+    return part.success ? part.data : null;
+}
 /** Build the `data-plan` payload by loading the stored plan. `ok(null)` when
  *  the plan is missing or no longer parses (absence is NOT an error) — the
  *  caller falls back to a chip. */
 export function buildPlanCardData(pool, planId, analysisId, title) {
-    return loadPlan(pool, planId, { analysisId }).map((plan) => {
-        if (!plan)
-            return null;
-        const parsed = AnalysisPlanSchema.safeParse(plan);
-        if (!parsed.success)
-            return null;
-        const id = `pres-${createHash("sha256").update(planId).digest("hex").slice(0, 16)}`;
-        // Explicit `show_plan({ title })` overrides; otherwise default to the
-        // planner-set plan title so both cards share one source.
-        const heading = title ?? parsed.data.title;
-        return {
-            id,
-            planId,
-            ...(heading !== undefined ? { title: heading } : {}),
-            steps: parsed.data.steps,
-            analytical_narrative: parsed.data.analytical_narrative,
-            omicsType: parsed.data.omicsType,
-            omicsSubtype: parsed.data.omicsSubtype,
-        };
-    });
+    return loadPlanRecord(pool, planId, { analysisId }).map((record) => (record ? planCardOf(record, title) : null));
 }
 /** Build the `data-run-card` payload for a started analysis run. Loads the
  *  plan (for `title` + `stepCount`) the same way `buildPlanCardData` does. The

package/dist/memory/conversation-display-recorder.d.ts

@@ -20,6 +20,8 @@ export interface ConversationDisplayRecorderOptions {
     readonly sink: EmitFn;
     readonly userMessageId?: string;
     readonly assistantMessageId?: string;
+    /** The clock for the times of the sub-agent activity, in milliseconds. The default is the wall clock. */
+    readonly now?: () => number;
 }
 /**
  * Record the display of a turn through the same translation path as a live surface: each event becomes a