@inflexa-ai/harness 0.15.1 → 0.17.0

package/dist/citations/types.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+export const CitationKindSchema = z.enum(["doi", "pmid", "arxiv", "free_text", "auto"]);
+export const CitationInputSchema = z.object({
+    citation: z.string().trim().min(1).max(5_000),
+    kind: CitationKindSchema.optional(),
+    title: z.string().trim().min(1).max(2_000).optional(),
+    authors: z.array(z.string().trim().min(1).max(500)).max(500).optional(),
+    year: z.number().int().min(1000).max(3000).optional(),
+    venue: z.string().trim().min(1).max(1_000).optional(),
+    volume: z.string().trim().min(1).max(100).optional(),
+    firstPage: z.string().trim().min(1).max(100).optional(),
+});
+export const CitationSourceSchema = z.enum(["doi_registry", "crossref", "pubmed", "arxiv", "semantic_scholar"]);
+export const CitationSourceStatusSchema = z.enum(["ok", "no_data", "unavailable", "not_applicable"]);
+export const CitationVerdictSchema = z.enum(["verified", "metadata_mismatch", "not_found", "unverifiable", "inconclusive"]);
+export const CitationCoverageSchema = z.enum(["complete", "partial", "none"]);
+export const ComparisonStatusSchema = z.enum(["match", "mismatch", "not_compared"]);
+export const CitationFieldSchema = z.enum(["title", "authors", "year", "venue", "volume", "firstPage"]);
+export const UnsupportedWorkKindSchema = z.enum(["personal_communication", "unpublished", "unregistered_in_press"]);
+export const CitationIdentifiersSchema = z.object({
+    doi: z.string().optional(),
+    pmid: z.string().optional(),
+    arxiv: z.string().optional(),
+    corpusId: z.string().optional(),
+});
+export const NormalizedCitationMetadataSchema = z.object({
+    title: z.string().optional(),
+    authors: z.array(z.string()).optional(),
+    year: z.number().int().optional(),
+    venue: z.string().optional(),
+    volume: z.string().optional(),
+    firstPage: z.string().optional(),
+});
+export const NormalizedCitationSchema = z.object({
+    citation: z.string(),
+    query: z.string(),
+    kind: z.enum(["doi", "pmid", "arxiv", "free_text"]),
+    identifiers: CitationIdentifiersSchema,
+    supplied: NormalizedCitationMetadataSchema,
+    unsupportedWorkKind: UnsupportedWorkKindSchema.optional(),
+});
+export const CitationRecordSchema = z.object({
+    source: CitationSourceSchema,
+    sourceRecordId: z.string(),
+    identifiers: CitationIdentifiersSchema,
+    title: z.string().optional(),
+    authors: z.array(z.string()).optional(),
+    year: z.number().int().optional(),
+    venue: z.string().optional(),
+    volume: z.string().optional(),
+    firstPage: z.string().optional(),
+    registrationAgency: z.string().optional(),
+    url: z.string().optional(),
+});
+export const IdentifierEvidenceSchema = z.object({
+    type: z.enum(["doi", "pmid", "arxiv"]),
+    identifier: z.string(),
+    exists: z.boolean(),
+    registrationAgency: z.string().optional(),
+    metadataAvailable: z.boolean(),
+});
+export const CitationSourceOutcomeSchema = z.object({
+    source: CitationSourceSchema,
+    operation: z.string(),
+    status: CitationSourceStatusSchema,
+    requestCount: z.number().int().nonnegative(),
+    records: z.array(CitationRecordSchema),
+    detail: z.string().optional(),
+    identifierEvidence: IdentifierEvidenceSchema.optional(),
+});
+export const CitationFieldComparisonSchema = z.object({
+    field: CitationFieldSchema,
+    status: ComparisonStatusSchema,
+    supplied: z.union([z.string(), z.number(), z.array(z.string())]),
+    sourceValues: z.array(z.object({
+        source: CitationSourceSchema,
+        value: z.union([z.string(), z.number(), z.array(z.string())]),
+    })),
+    ruleVersion: z.string(),
+});
+export const CitationConflictSchema = z.object({
+    field: CitationFieldSchema,
+    values: z.array(z.object({
+        source: CitationSourceSchema,
+        value: z.union([z.string(), z.number(), z.array(z.string())]),
+    })),
+});
+export const CitationClusterRelationSchema = z.object({
+    clusterId: z.string(),
+    kind: z.enum(["preprint_of", "published_as", "related_version"]),
+});
+export const CitationCandidateClusterSchema = z.object({
+    id: z.string(),
+    score: z.number().min(0).max(1),
+    records: z.array(CitationRecordSchema).min(1),
+    relations: z.array(CitationClusterRelationSchema),
+});
+export const CitationResolutionResultSchema = z.object({
+    input: CitationInputSchema,
+    normalized: NormalizedCitationSchema,
+    sourceOutcomes: z.array(CitationSourceOutcomeSchema),
+    candidates: z.array(CitationCandidateClusterSchema),
+    selectedClusterId: z.string().optional(),
+    comparisons: z.array(CitationFieldComparisonSchema),
+    conflicts: z.array(CitationConflictSchema),
+    verdict: CitationVerdictSchema,
+    coverage: CitationCoverageSchema,
+});
+export const CitationSourceOperationSchema = z.enum([
+    "doi_exact",
+    "crossref_doi_if_owned",
+    "crossref_bibliographic",
+    "pubmed_exact",
+    "pubmed_doi",
+    "pubmed_structured",
+    "pubmed_title",
+    "arxiv_exact",
+    "arxiv_bibliographic",
+    "semantic_scholar_identifier",
+    "semantic_scholar_bibliographic",
+    "none",
+]);
+export const CitationSourcePlanItemSchema = z.object({
+    source: CitationSourceSchema,
+    applicable: z.boolean(),
+    operation: CitationSourceOperationSchema,
+    candidateGeneration: z.boolean(),
+    reason: z.string(),
+});

package/dist/contracts/chat-events.d.ts

@@ -37,6 +37,22 @@ export interface TextDeltaEvent {
  * admit the impossible "not an error, but denied".
  */
 export type ToolOutcome = "ok" | "error" | "denied";
+/**
+ * How a RECORDED call ended — the three live outcomes plus `incomplete`.
+ *
+ * `incomplete` is the state a live event cannot carry and a record cannot avoid:
+ * the harness observed a dispatch and no completion, because the turn was cut off
+ * mid-call. A `tool-finished` is never incomplete, which is why this widens
+ * {@link ToolOutcome} rather than replacing it.
+ *
+ * It is a fourth value of ONE field rather than a second field beside the outcome,
+ * for the same reason the outcome is three-way instead of `isError` plus `denied`:
+ * a call has exactly one terminal state, and splitting that across two fields both
+ * admits impossible pairs and leaves every consumer to invent the meaning of the
+ * combination. A consumer switches on this one field, and a consumer that forgets
+ * a case fails to compile rather than silently reporting a success.
+ */
+export type ToolCallOutcome = ToolOutcome | "incomplete";
 /**
  * One line naming what a tool call is doing, produced by the tool's own
  * `describeCall` hook and normalized at the emit site.

package/dist/contracts/message.d.ts

@@ -6,7 +6,7 @@
  * discriminant is `type`, so `switch (part.type) { case "data-report-preview": ... }`
  * narrows the union member without any `as` cast.
  */
-import type { ToolCallDetail, ToolOutcome } from "./chat-events.js";
+import type { ToolCallDetail, ToolCallOutcome } from "./chat-events.js";
 import type { CortexChatPart } from "./chat-parts.js";
 import type { TokenUsageRollup } from "./usage.js";
 /** A plain assistant/user text run. */
@@ -17,20 +17,25 @@ export interface TextPart {
 /**
  * A tool call observed during the turn (or replayed from history).
  *
- * Live frames collapse a `tool-started`+`tool-finished` pair into a single
- * part keyed by `toolCallId`. History-replayed calls always arrive with
- * `status: "finished"`.
+ * Live frames collapse a `tool-started`+`tool-finished` pair into a single part
+ * keyed by `toolCallId`.
+ *
+ * `outcome` carries the call's whole terminal state in one field, and its absence
+ * means exactly one thing: the call is still in flight. A REPLAYED call therefore
+ * always has one — a turn cut off mid-call replays as `incomplete`, not as an
+ * absent outcome a reader would have to interpret. That is what lets a consumer
+ * switch on this single field and be told by the compiler when it misses a case,
+ * rather than each host inventing what "no outcome" means and disagreeing.
  */
 export interface ToolCallPart {
     type: "tool-call";
     toolCallId: string;
     toolName: string;
-    status: "started" | "finished";
     /**
-     * How the call ended. Absent while `status` is `"started"` — the outcome is
-     * not known yet. See {@link ToolOutcome}.
+     * How the call ended. Absent ONLY while the call is in flight on a live
+     * surface; every replayed call carries one. See {@link ToolCallOutcome}.
      */
-    outcome?: ToolOutcome;
+    outcome?: ToolCallOutcome;
     /** See {@link ToolCallDetail}. Absent when no detail was produced. */
     detail?: ToolCallDetail;
 }

package/dist/contracts/schemas/chat-events.d.ts

@@ -20,6 +20,13 @@ export declare const ToolOutcomeSchema: z.ZodEnum<{
     ok: "ok";
     denied: "denied";
 }>;
+/** Mirrors `ToolCallOutcome` — the live three plus the record-only `incomplete`. */
+export declare const ToolCallOutcomeSchema: z.ZodEnum<{
+    error: "error";
+    ok: "ok";
+    denied: "denied";
+    incomplete: "incomplete";
+}>;
 export declare const ToolStartedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"tool-started">;
     toolUseId: z.ZodString;

package/dist/contracts/schemas/chat-events.js

@@ -14,6 +14,8 @@ export const TextDeltaEventSchema = z.object({
 });
 /** Mirrors the `ToolOutcome` union — three states, never a boolean. */
 export const ToolOutcomeSchema = z.enum(["ok", "error", "denied"]);
+/** Mirrors `ToolCallOutcome` — the live three plus the record-only `incomplete`. */
+export const ToolCallOutcomeSchema = z.enum(["ok", "error", "denied", "incomplete"]);
 export const ToolStartedEventSchema = z.object({
     type: z.literal("tool-started"),
     toolUseId: z.string(),

package/dist/contracts/schemas/chat-parts.d.ts

@@ -182,6 +182,7 @@ export declare const DagStatePartSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const StepPhaseSchema: z.ZodEnum<{
+    complete: "complete";
     failed: "failed";
     warning: "warning";
     "sandbox-init": "sandbox-init";
@@ -190,7 +191,6 @@ export declare const StepPhaseSchema: z.ZodEnum<{
     "generating-summary": "generating-summary";
     indexing: "indexing";
     persisting: "persisting";
-    complete: "complete";
     retrying: "retrying";
 }>;
 export declare const StepActivityPartSchema: z.ZodObject<{
@@ -199,6 +199,7 @@ export declare const StepActivityPartSchema: z.ZodObject<{
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         warning: "warning";
         "sandbox-init": "sandbox-init";
@@ -207,7 +208,6 @@ export declare const StepActivityPartSchema: z.ZodObject<{
         "generating-summary": "generating-summary";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         retrying: "retrying";
     }>;
     activity: z.ZodString;
@@ -314,8 +314,8 @@ export declare const RunCompletedPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        completed: "completed";
         partial: "partial";
+        completed: "completed";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;
@@ -403,11 +403,11 @@ export declare const RunSynthesisPartSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SynthesisPhaseSchema: z.ZodEnum<{
+    complete: "complete";
     failed: "failed";
     skipped: "skipped";
     indexing: "indexing";
     persisting: "persisting";
-    complete: "complete";
     starting: "starting";
     researching: "researching";
     drafting: "drafting";
@@ -419,11 +419,11 @@ export declare const SynthesisProgressPartSchema: z.ZodObject<{
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         skipped: "skipped";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         starting: "starting";
         researching: "researching";
         drafting: "drafting";
@@ -574,6 +574,7 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         warning: "warning";
         "sandbox-init": "sandbox-init";
@@ -582,7 +583,6 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         "generating-summary": "generating-summary";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         retrying: "retrying";
     }>;
     activity: z.ZodString;
@@ -693,11 +693,11 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         skipped: "skipped";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         starting: "starting";
         researching: "researching";
         drafting: "drafting";
@@ -712,8 +712,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        completed: "completed";
         partial: "partial";
+        completed: "completed";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;

package/dist/contracts/target-dossier.d.ts

@@ -1785,11 +1785,11 @@ export declare const ExpressionHeatmapCellSchema: z.ZodObject<{
         dog: "dog";
     }>;
     rank: z.ZodEnum<{
+        no_data: "no_data";
+        absent: "absent";
         high: "high";
         medium: "medium";
         low: "low";
-        absent: "absent";
-        no_data: "no_data";
         not_loaded: "not_loaded";
     }>;
 }, z.core.$strip>;
@@ -1804,11 +1804,11 @@ export declare const ExpressionHeatmapSchema: z.ZodObject<{
             dog: "dog";
         }>;
         rank: z.ZodEnum<{
+            no_data: "no_data";
+            absent: "absent";
             high: "high";
             medium: "medium";
             low: "low";
-            absent: "absent";
-            no_data: "no_data";
             not_loaded: "not_loaded";
         }>;
     }, z.core.$strip>>;
@@ -1911,11 +1911,11 @@ export declare const PreclinicalProfileSchema: z.ZodObject<{
                     dog: "dog";
                 }>;
                 rank: z.ZodEnum<{
+                    no_data: "no_data";
+                    absent: "absent";
                     high: "high";
                     medium: "medium";
                     low: "low";
-                    absent: "absent";
-                    no_data: "no_data";
                     not_loaded: "not_loaded";
                 }>;
             }, z.core.$strip>>;
@@ -4229,11 +4229,11 @@ export declare const DossierSchema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -5482,11 +5482,11 @@ export declare const ReferenceBiologyV4Shape: z.ZodObject<{
                         dog: "dog";
                     }>;
                     rank: z.ZodEnum<{
+                        no_data: "no_data";
+                        absent: "absent";
                         high: "high";
                         medium: "medium";
                         low: "low";
-                        absent: "absent";
-                        no_data: "no_data";
                         not_loaded: "not_loaded";
                     }>;
                 }, z.core.$strip>>;
@@ -6914,11 +6914,11 @@ export declare const DossierV4Schema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -9131,11 +9131,11 @@ export declare const DossierV4BodySchema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -12206,11 +12206,11 @@ export declare const DossierV5Schema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -14928,11 +14928,11 @@ export declare const DossierV5BodySchema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -16557,11 +16557,11 @@ export declare const DossierSchemaV3Legacy: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;

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

@@ -31,6 +31,7 @@ import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { RunSession } from "../auth/types.js";
 import { type Tool } from "../tools/define-tool.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { CitationResolver } from "../citations/types.js";
 /**
  * The synthesizer's agent identity — the `source.agentId` on its loop events
  * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
@@ -67,6 +68,8 @@ export interface GenerateRunSynthesisInput {
     readonly model: string;
     /** API keys for the bio/chem tools the embedded literature reviewer uses. */
     readonly bioKeys: BioToolKeys;
+    /** Shared resolver used by the embedded literature reviewer. */
+    readonly citationResolver: CitationResolver;
     /** LLM usage-accounting seam for the synthesizer + reviewer loops; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
     /** Step summaries from the completed run. Non-empty. */

package/dist/execution/run-synthesis.js

@@ -349,6 +349,7 @@ export async function generateRunSynthesis(input) {
         provider: input.provider,
         model: input.model,
         bioKeys: input.bioKeys,
+        citationResolver: input.citationResolver,
         usageRecorder: input.usageRecorder,
     });
     const validateTool = buildValidateTool(innerCtx);

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { assembleCoreRuntime } from "./runtime/assemble.js";
 export type { CoreRuntime, CoreRuntimeDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable } from "./runtime/assemble.js";
+export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/assemble.js";
 export { bootHarness } from "./runtime/boot.js";
 export type { BootHarnessDeps, BootedHarness } from "./runtime/boot.js";
 export { createConversationAgent } from "./agents/conversation-agent.js";
@@ -31,6 +32,10 @@ export type { DbosWorkflowPurgerDeps } from "./execution/dbos-workflow-purger.js
 export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
+export { createCitationResolver } from "./citations/resolve.js";
+export type { CitationResolverConfig, CitationResolverDependencies, CitationResolverSourceConfig } from "./citations/resolve.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";
 export type { AskGateway, AskGatewayDeps, AskContext, AnswerOutcome, PendingAsk } from "./tools/approval/gateway.js";
 export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
@@ -56,17 +61,16 @@ export { createStreamingChat } from "./providers/streaming-chat.js";
 export { prepareChatTurn } from "./app/chat-turn.js";
 export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
-export type { ThreadStore, Thread, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
-export { createThreadHistory } from "./memory/thread-history.js";
-export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome } from "./memory/thread-history.js";
+export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
+export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
+export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome, ConversationTurn } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
-export { contentToCortexMessages } from "./memory/content-to-cortex.js";
-export type { ContentToCortexOptions } from "./memory/content-to-cortex.js";
-export { createCardResolver } from "./memory/reconstruct-cards.js";
-export type { ToolCardResolver, StoredToolCallForCard } from "./memory/reconstruct-cards.js";
-export { createDetailResolver } from "./tools/detail-resolver.js";
-export type { ToolDetailResolver } from "./tools/detail-resolver.js";
-export type { CortexChatEvent, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.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 { storedMessagesToCortex } from "./memory/conversation-display-replay.js";
+export type { CortexChatEvent, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
 export type { TokenUsageRollup } from "./contracts/usage.js";
 export type { CortexChatPart, 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, PreviewPart, DataPreviewFailedPart, } from "./contracts/chat-parts.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";

package/dist/index.js

@@ -33,6 +33,9 @@ export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// Host-agnostic citation verification service and its public contracts.
+export { createCitationResolver } from "./citations/resolve.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
 // the boot-time `sweepExpired`; `UnavailableAsk` is the shipped deny-by-default
@@ -80,15 +83,13 @@ export { toProviderError, isProviderError } from "./providers/errors.js";
 // gets live token streaming out of the otherwise non-streaming loop.
 export { createStreamingChat } from "./providers/streaming-chat.js";
 // Conversation turn + thread memory — the transport-free halves of one chat
-// turn a same-process host drives itself. `prepareChatTurn` assembles the
-// message array (thread-ownership resolution, title seed, analysis-context
-// injection); the caller runs `runAgent` with its own `emit`; `appendTurn`
-// (`createThreadHistory`) persists the turn. `createThreadStore` owns thread
-// metadata (create/list/title). `contentToCortexMessages` + `createCardResolver`
-// reconstruct display cards from a persisted thread on reload.
+// turn a same-process host drives itself. `prepareChatTurn` assembles the model
+// message array; `createConversationDisplayRecorder` records the independently
+// replayable UI projection while forwarding live events; `appendTurn` persists
+// both atomically. `createThreadStore` owns thread metadata (create/list/title).
 export { prepareChatTurn } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
-export { createThreadHistory } from "./memory/thread-history.js";
+export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 // The synthetic-message primitives. A host appends a record of out-of-band work (an analysis run's
 // outcome) into a thread through `appendTurn`, and needs a message the model reads but that is not
 // user input — which is exactly what the marker denotes. The constructor is exported rather than
@@ -96,16 +97,19 @@ export { createThreadHistory } from "./memory/thread-history.js";
 // (`isGenuineUserStart` and its SQL twin) would then fail to recognise; `isSyntheticUserMessage`
 // lets a host renderer tell such a message apart from a genuine user turn on the way back out.
 // `syntheticRecordMessage` is the one a HOST reaches for: equally non-turn-opening, but rendered —
-// the display reconstruction emits it as a `system` message rather than dropping it as loop
-// machinery, so an appended run outcome is visible in the transcript instead of silently absent.
+// it displays as a `system` message rather than being dropped as loop machinery, so an appended run
+// outcome is visible in the transcript instead of silently absent. `conversationRecordTurn` wraps it
+// as a complete append (model message plus its display projection), which is what a host should
+// reach for: a record appended without one would be stored but never replayed.
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
-export { contentToCortexMessages } from "./memory/content-to-cortex.js";
-export { createCardResolver } from "./memory/reconstruct-cards.js";
-// The call-detail resolver, the reload counterpart of the `describeCall` hook a
-// tool declares. Built over a tool list the HOST supplies — its own composed
-// roster, `HarnessRuntime.conversationAgent.tools` — because tools contributed
-// through the host-tools seam are invisible to any map the harness holds.
-export { createDetailResolver } from "./tools/detail-resolver.js";
+export { createConversationDisplayRecorder } from "./memory/conversation-display-recorder.js";
+export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
+// The transcript read. Every append persists what it displayed, so replay concatenates stored
+// projections and consults nothing else — no tool names, no card builders, no workspace or database
+// lookups. The migration renderer that DOES consult those (`content-to-cortex.js`,
+// `reconstruct-cards.js`, `tools/detail-resolver.js`) is deliberately absent from this barrel: it
+// runs once per legacy row at startup and has no runtime caller.
+export { storedMessagesToCortex } from "./memory/conversation-display-replay.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 // Embedder runtime surface — what a same-process host needs to run durable
 // workflows itself: the DBOS lifecycle, per-workflow registration + triggers,

package/dist/lib/cache.d.ts

@@ -0,0 +1,8 @@
+export declare class BoundedTtlCache<Value> {
+    private readonly maximum;
+    private readonly now;
+    private readonly entries;
+    constructor(maximum: number, now?: () => number);
+    get(key: string): Value | undefined;
+    set(key: string, value: Value, ttlMs: number): void;
+}

package/dist/lib/cache.js

@@ -0,0 +1,35 @@
+export class BoundedTtlCache {
+    maximum;
+    now;
+    entries = new Map();
+    constructor(maximum, now = Date.now) {
+        this.maximum = maximum;
+        this.now = now;
+        if (!Number.isInteger(maximum) || maximum < 0)
+            throw new Error("cache maximum must be a non-negative integer");
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiresAt <= this.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        if (this.maximum === 0 || ttlMs <= 0)
+            return;
+        this.entries.delete(key);
+        this.entries.set(key, { value, expiresAt: this.now() + ttlMs });
+        while (this.entries.size > this.maximum) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+}