@inflexa-ai/harness 0.44.0 → 0.45.1

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, LaunchPlanRunInput, 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";
@@ -48,10 +52,14 @@ export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { createRunCanceler, UnknownRunError } from "./execution/run-canceler.js";
 export type { RunCanceler, RunCancelerDeps, CancelRunResult } from "./execution/run-canceler.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
+export { createHttpKnowledgeClient, createKnowledgeRecommendTool, createKnowledgeCheckTool, createKnowledgeTools, knowledgeToolDefinitionHash, } from "./tools/knowledge/index.js";
+export type { KnowledgeClient, KnowledgeSituation, HttpKnowledgeClientConfig } from "./tools/knowledge/index.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
 export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 export { createCitationResolver } from "./citations/resolve.js";
 export type { CitationResolverConfig, CitationResolverDependencies, CitationResolverSourceConfig } from "./citations/resolve.js";
+export { createSearxngEngine } from "./tools/research/searxng-engine.js";
+export type { WebSearchEngine } from "./tools/research/web-search.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
 export type { CitationKind, CitationInput, CitationSource, CitationSourceStatus, CitationResolver, CitationResolveOptions, CitationResolutionResult, CitationVerdict, CitationCoverage, ComparisonStatus, CitationField, UnsupportedWorkKind, CitationIdentifiers, NormalizedCitationMetadata, NormalizedCitation, CitationSourceOutcome, CitationRecord, IdentifierEvidence, CitationFieldComparison, CitationConflict, CitationCandidateCluster, CitationSourceClient, CitationSourceRequest, CitationSourceOperation, CitationSourcePlanItem, RegistrationAgencyEvidence, } from "./citations/types.js";
 export { createAskGateway } from "./tools/approval/gateway.js";
@@ -85,21 +93,23 @@ 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 type { ThreadHistory, StoredMessage, LoadPageOptions, TurnPage, RetractOutcome, ConversationTurn, TurnWrite, TurnWriteResult, TurnClose, TurnStatus, StoredTurnRecord, } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { createConversationDisplayRecorder } from "./memory/conversation-display-recorder.js";
 export type { ConversationDisplayRecorder, ConversationDisplayRecorderOptions } from "./memory/conversation-display-recorder.js";
 export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 export type { ConversationDisplayMetadata, ConversationUIData, ConversationUIMessage, StoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 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 type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, MessageStartEvent, } 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 +125,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 +142,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 { ArtifactExtensionCount, 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 +181,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, countRunsByAnalysis, 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.
@@ -65,6 +70,10 @@ export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 export { createRunCanceler, UnknownRunError } from "./execution/run-canceler.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// The knowledge plane: an embedder binds a client at its composition root
+// (or none), and it can hand `knowledge_recommend` to the conversation agent
+// through `hostTools`.
+export { createHttpKnowledgeClient, createKnowledgeRecommendTool, createKnowledgeCheckTool, createKnowledgeTools, knowledgeToolDefinitionHash, } from "./tools/knowledge/index.js";
 // Tool-call-detail authoring aids for an embedder that contributes a host tool.
 // A `describeCall` hook that pre-empts truncation — a count in place of a
 // mid-value cut that would name a file that does not exist — must gate on the
@@ -76,6 +85,12 @@ export { defineTool, isToolError } from "./tools/define-tool.js";
 export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 // Host-agnostic citation verification service and its public contracts.
 export { createCitationResolver } from "./citations/resolve.js";
+// The web-search engine type and the SearXNG realization. An embedder cannot
+// build its composition root without these two names: it constructs the engine
+// and types the `webSearch` field of `ConversationAgentDeps` (the front-door
+// rule of the harness-embedder-exports spec). The tools stay off the barrel —
+// the conversation agent constructs them itself.
+export { createSearxngEngine } from "./tools/research/searxng-engine.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
 // Seam: tool approval (`ctx.ask`). `createAskGateway` realizes the `Ask` seam
 // over the injected `Pool` and carries the outward `answer`/`pending` API plus
@@ -156,6 +171,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 +231,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 +299,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, countRunsByAnalysis, 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/call-guard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The call guard: a bound on repeated tool calls inside one agent run.
+ *
+ * A model that treats a tool answer as a state to poll calls the same tool
+ * with the same input again and again, or drifts through one query after
+ * another, until the iteration cap or the wall clock ends the run. A frontier
+ * model reads an "unavailable" answer once and continues; a smaller model
+ * does not. The guard makes that difference a host decision: the third call
+ * with an input the run already sent, the call past the budget of one tool,
+ * or the call past the budget of the whole run, answers a tool error that
+ * tells the model to continue with what it has. The service behind the tool never sees the refused call.
+ *
+ * The guard wraps a list of tools for ONE run. Build it where the tools of
+ * the run are built, never at construction of the host, thus the counters
+ * start at zero for every run. A terminal tool (one that ends the run) must
+ * not be wrapped: a refusal there would strand the run.
+ */
+import type { Tool } from "../tools/define-tool.js";
+export interface CallGuardPolicy {
+    /** The calls with one identical input that a run may make to one tool. The next one is refused. */
+    readonly identicalLimit: number;
+    /** The calls, with any input, that a run may make to one tool. The next one is refused. */
+    readonly perToolLimit: number;
+    /** The calls, with any input, that a run may make across every guarded tool. The next one is refused by every tool. */
+    readonly totalLimit: number;
+}
+/**
+ * Two identical calls let a model confirm an answer once. Twelve calls of one
+ * tool is above the largest count a frontier planner made in the Phase 0
+ * campaign (six and a half calls per plan across ALL tools) and far below the
+ * two hundred that a looping planner reached. Forty calls across every tool
+ * bounds the round over the tools that stays under each per-tool budget: in
+ * the 32-task campaign every submitted Sonnet plan but two needed fewer, and
+ * the one plan that ran to the wall clock made 62.
+ */
+export declare const DEFAULT_CALL_GUARD: CallGuardPolicy;
+/** A stable key for one input: the JSON text with the object keys sorted at every depth. */
+export declare function canonicalInputKey(input: unknown): string;
+export interface GuardedCallRefusal {
+    readonly tool: string;
+    readonly kind: "identical" | "budget" | "total";
+    readonly calls: number;
+}
+export interface CallGuardOptions {
+    readonly policy?: CallGuardPolicy;
+    /** Called on each refusal, for the log of the host. */
+    readonly onRefusal?: (refusal: GuardedCallRefusal) => void;
+}
+/** Wrap each tool so its `execute` obeys the policy for the life of the returned list. */
+export declare function guardRepeatedCalls(tools: readonly Tool[], options?: CallGuardOptions): Tool[];

package/dist/loop/call-guard.js

@@ -0,0 +1,90 @@
+/**
+ * The call guard: a bound on repeated tool calls inside one agent run.
+ *
+ * A model that treats a tool answer as a state to poll calls the same tool
+ * with the same input again and again, or drifts through one query after
+ * another, until the iteration cap or the wall clock ends the run. A frontier
+ * model reads an "unavailable" answer once and continues; a smaller model
+ * does not. The guard makes that difference a host decision: the third call
+ * with an input the run already sent, the call past the budget of one tool,
+ * or the call past the budget of the whole run, answers a tool error that
+ * tells the model to continue with what it has. The service behind the tool never sees the refused call.
+ *
+ * The guard wraps a list of tools for ONE run. Build it where the tools of
+ * the run are built, never at construction of the host, thus the counters
+ * start at zero for every run. A terminal tool (one that ends the run) must
+ * not be wrapped: a refusal there would strand the run.
+ */
+import { err } from "neverthrow";
+/**
+ * Two identical calls let a model confirm an answer once. Twelve calls of one
+ * tool is above the largest count a frontier planner made in the Phase 0
+ * campaign (six and a half calls per plan across ALL tools) and far below the
+ * two hundred that a looping planner reached. Forty calls across every tool
+ * bounds the round over the tools that stays under each per-tool budget: in
+ * the 32-task campaign every submitted Sonnet plan but two needed fewer, and
+ * the one plan that ran to the wall clock made 62.
+ */
+export const DEFAULT_CALL_GUARD = { identicalLimit: 2, perToolLimit: 12, totalLimit: 40 };
+/** A stable key for one input: the JSON text with the object keys sorted at every depth. */
+export function canonicalInputKey(input) {
+    return JSON.stringify(sortKeys(input));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort())
+            out[key] = sortKeys(value[key]);
+        return out;
+    }
+    return value;
+}
+/** Wrap each tool so its `execute` obeys the policy for the life of the returned list. */
+export function guardRepeatedCalls(tools, options = {}) {
+    const policy = options.policy ?? DEFAULT_CALL_GUARD;
+    let total = 0;
+    return tools.map((tool) => {
+        let calls = 0;
+        const byInput = new Map();
+        const guarded = {
+            ...tool,
+            ...(tool.describeCall ? { describeCall: tool.describeCall.bind(tool) } : {}),
+            ...(tool.describeResult ? { describeResult: tool.describeResult.bind(tool) } : {}),
+            async execute(input, ctx) {
+                calls += 1;
+                const key = canonicalInputKey(input);
+                const identical = (byInput.get(key) ?? 0) + 1;
+                byInput.set(key, identical);
+                if (identical > policy.identicalLimit) {
+                    options.onRefusal?.({ tool: tool.id, kind: "identical", calls: identical });
+                    return err({
+                        error: `This run already called ${tool.id} with this exact input ${identical - 1} times, and the answer does not change within a run. ` +
+                            "Use the answer you have and continue. If the answer was that a resource is absent, plan without it or ask for it; do not search again.",
+                        retryable: false,
+                    });
+                }
+                total += 1;
+                if (total > policy.totalLimit) {
+                    options.onRefusal?.({ tool: tool.id, kind: "total", calls: total });
+                    return err({
+                        error: `This run made ${policy.totalLimit} calls across its search tools, which is the search budget of one run. ` +
+                            "Submit the plan you have now. If a required resource is absent, ask for it; do not search again.",
+                        retryable: false,
+                    });
+                }
+                if (calls > policy.perToolLimit) {
+                    options.onRefusal?.({ tool: tool.id, kind: "budget", calls });
+                    return err({
+                        error: `This run made ${policy.perToolLimit} calls of ${tool.id}, which is the budget of one run for one tool. ` +
+                            "Continue with what you have. If a required resource is absent, ask for it; do not search again.",
+                        retryable: false,
+                    });
+                }
+                return tool.execute(input, ctx);
+            },
+        };
+        return guarded;
+    });
+}