@inflexa-ai/harness 0.1.1

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

@@ -0,0 +1,61 @@
+/**
+ * Cortex-native chat-stream events — the harness wire vocabulary.
+ *
+ * Distinct from the 15 `data-*` chat parts (`chat-parts.ts`): those are UI
+ * presentation payloads a tool emits; these are the agent-loop stream events
+ * the harness chat route frames as Cortex-native SSE. Together they are the
+ * sole Cortex↔frontend wire contract — there is no AI SDK UI Message Stream
+ * Protocol and no translation layer.
+ *
+ * Every event carries `source` — the agent call chain at the point of
+ * emission, derived from the harness `Session.callPath`.
+ */
+/**
+ * Provenance stamped on every chat-stream event: the emitting agent and the
+ * call chain that reached it (e.g. `["conversation-agent"]`, or
+ * `["conversation-agent", "literature-reviewer"]` for a sub-agent).
+ */
+export interface EventSource {
+    agentId: string;
+    callPath: string[];
+}
+/** A run of assistant text. Deltas accumulate into the turn's reply. */
+export interface TextDeltaEvent {
+    type: "text-delta";
+    text: string;
+    source: EventSource;
+}
+/** A tool call has been dispatched. */
+export interface ToolStartedEvent {
+    type: "tool-started";
+    /** The Anthropic `tool_use` block id — pairs with `tool-finished`. */
+    toolUseId: string;
+    /** The tool name. */
+    name: string;
+    source: EventSource;
+}
+/** A tool call has resolved. */
+export interface ToolFinishedEvent {
+    type: "tool-finished";
+    toolUseId: string;
+    name: string;
+    /** True when the tool produced an `is_error` result. */
+    isError: boolean;
+    source: EventSource;
+}
+/** The agent loop produced its terminal reply — the turn is complete. */
+export interface FinishEvent {
+    type: "finish";
+    source: EventSource;
+}
+/** The turn failed. `reason` is a machine-readable code when one applies. */
+export interface ChatErrorEvent {
+    type: "error";
+    /** Human-readable, scrubbed error message. */
+    message: string;
+    /** Machine-readable failure code, e.g. `"budget_exceeded"`. */
+    reason?: string;
+    source: EventSource;
+}
+/** The discriminated union of all Cortex-native chat-stream events. */
+export type CortexChatEvent = TextDeltaEvent | ToolStartedEvent | ToolFinishedEvent | FinishEvent | ChatErrorEvent;

package/dist/contracts/chat-events.js

@@ -0,0 +1,13 @@
+/**
+ * Cortex-native chat-stream events — the harness wire vocabulary.
+ *
+ * Distinct from the 15 `data-*` chat parts (`chat-parts.ts`): those are UI
+ * presentation payloads a tool emits; these are the agent-loop stream events
+ * the harness chat route frames as Cortex-native SSE. Together they are the
+ * sole Cortex↔frontend wire contract — there is no AI SDK UI Message Stream
+ * Protocol and no translation layer.
+ *
+ * Every event carries `source` — the agent call chain at the point of
+ * emission, derived from the harness `Session.callPath`.
+ */
+export {};

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

@@ -0,0 +1,308 @@
+/**
+ * Cortex chat data parts — custom parts emitted via writer.write() / writer.custom()
+ * that flow through the chat stream and are rendered by the frontend.
+ *
+ * 15 part types across four categories:
+ *   Presentation:    data-presentation (agent-synthesized content),
+ *                    data-plan (plan by id), data-file-reference (files by path)
+ *   Run lifecycle:   run-started, dag-state, run-completed, run-failed, run-synthesis,
+ *                    synthesis-progress
+ *   Per-step live:   step-activity, step-file-tree
+ *   Per-step final:  step-output, step-summary
+ */
+export interface PlanStep {
+    id: string;
+    name: string;
+    agent: string;
+    question: string;
+    depends_on: string[];
+    resources?: {
+        cpu: number;
+        memoryGb: number;
+    };
+    maxSteps: number;
+}
+export type PresentationContent = 
+/** `dataPath` (optional): an analysis-rooted CSV artifact path the host loads and injects as the
+ *  chart's `dataset.source` at render time — the data never rides through the context window. */
+{
+    kind: "echart";
+    spec: Record<string, unknown>;
+    dataPath?: string;
+} | {
+    kind: "markdown";
+    body: string;
+} | {
+    kind: "code";
+    code: string;
+    language: string;
+} | {
+    kind: "svg";
+    markup: string;
+} | {
+    kind: "table";
+    headers: string[];
+    rows: string[][];
+    caption?: string;
+};
+export interface PresentationPart {
+    type: "data-presentation";
+    id: string;
+    title?: string;
+    content: PresentationContent;
+}
+export interface PlanPart {
+    type: "data-plan";
+    id: string;
+    planId: string;
+    title?: string;
+    steps?: PlanStep[];
+    analytical_narrative?: string;
+    omicsType?: string;
+    omicsSubtype?: string;
+}
+export interface RunCardPart {
+    type: "data-run-card";
+    id: string;
+    runId: string;
+    planId: string;
+    title: string;
+    stepCount: number;
+}
+export interface FileReferenceEntry {
+    path: string;
+    runId?: string;
+    caption?: string;
+}
+export interface FileReferencePart {
+    type: "data-file-reference";
+    id: string;
+    title?: string;
+    files: FileReferenceEntry[];
+}
+export interface RunStartedPart {
+    type: "data-run-started";
+    runId: string;
+    planSummary: string;
+    stepCount: number;
+}
+/** `"pending"` = waiting on dependencies; `"queued"` = dependencies satisfied,
+ *  held until in-flight steps free machine-budget capacity. */
+export type StepStatus = "pending" | "queued" | "running" | "completed" | "failed";
+export interface DagStepState {
+    id: string;
+    name: string;
+    agent: string;
+    status: StepStatus;
+    /**
+     * Topological depth from DAG sources (level 0 = no deps; level N = max(level(deps)) + 1).
+     * Layout-only — does NOT gate execution. Two steps at the same level may run or
+     * complete in any order.
+     */
+    level: number;
+    dependsOn: string[];
+    /** Duration in ms (set on completion). */
+    durationMs?: number;
+    /** Artifact count (set on completion). */
+    artifactCount?: number;
+    /** Brief summary (set on completion). */
+    summary?: string;
+    /** Error message (set on failure). */
+    error?: string;
+}
+export interface DagStatePart {
+    type: "data-dag-state";
+    /** Stable ID for reconciliation — same across all updates for a run. */
+    id: string;
+    runId: string;
+    steps: DagStepState[];
+}
+export type StepPhase = "sandbox-init" | "executing" | "generating-metadata" | "generating-summary" | "indexing"
+/** Step bytes are uploading to the artifact store inline (per-step sync). */
+ | "persisting" | "complete" | "failed"
+/** Step is being retried after a classified-transient failure. */
+ | "retrying"
+/** Non-fatal warning emitted during step execution (e.g., maxSteps hit). */
+ | "warning";
+export interface StepActivityPart {
+    type: "data-step-activity";
+    /** Stable ID for reconciliation — unique per step within a run. */
+    id: string;
+    runId: string;
+    stepId: string;
+    /** Current execution phase. */
+    phase: StepPhase;
+    /** Human-readable activity description (e.g., "Running DESeq2 analysis"). */
+    activity: string;
+}
+export interface FileTreeEntry {
+    path: string;
+    size?: number;
+    type: "file" | "directory";
+}
+export interface StepFileTreePart {
+    type: "data-step-file-tree";
+    /** Stable ID for reconciliation — unique per step within a run. */
+    id: string;
+    runId: string;
+    stepId: string;
+    /** Current file tree snapshot. May be empty if sandbox hasn't written to disk yet. */
+    files: FileTreeEntry[];
+}
+export interface StepOutputFile {
+    path: string;
+    size: number;
+    /** File category for grouping/icons. */
+    fileType: "script" | "output" | "figure" | "log" | "notebook" | "summary";
+    /** LLM-generated description of the file contents. */
+    description: string;
+}
+export interface StepOutputPart {
+    type: "data-step-output";
+    id: string;
+    runId: string;
+    stepId: string;
+    agentId: string;
+    files: StepOutputFile[];
+    artifactCount: number;
+    durationMs: number;
+    /** Agent-stream finish reason ("stop", "tool-calls", "length", ...). Absent on rescued-from-failure outputs. */
+    finishReason?: string;
+    /** True when the agent exhausted its maxSteps turn budget. */
+    hitMaxSteps?: boolean;
+}
+/** Step summary — free-form markdown body, rendered verbatim by the UI. */
+export interface StepSummaryPart {
+    type: "data-step-summary";
+    id: string;
+    runId: string;
+    stepId: string;
+    agentId: string;
+    /** Free-form markdown body. Render with a markdown renderer. */
+    markdown: string;
+}
+/**
+ * Emitted when a step agent declares it cannot fulfil its step via
+ * `report_blocker` (see the harness-sandbox-agents spec). A blocked step has no deliverables; the
+ * reason surfaces in the run side panel.
+ */
+export interface StepBlockedPart {
+    type: "data-step-blocked";
+    id: string;
+    runId: string;
+    stepId: string;
+    agentId: string;
+    /** Agent-declared reason the step could not be fulfilled. */
+    reason: string;
+}
+export interface RunCompletedFinding {
+    title: string;
+    confidence: "high" | "medium" | "low";
+}
+export interface RunCompletedPart {
+    type: "data-run-completed";
+    runId: string;
+    status: "completed" | "partial";
+    completedSteps: number;
+    totalSteps: number;
+    artifactCount: number;
+    /** Top findings for quick display. */
+    findings: RunCompletedFinding[];
+    /**
+     * Optional human-readable explanation — present when `status === "partial"`
+     * to explain why (e.g., synthesis failed but step summaries are available).
+     */
+    note?: string;
+}
+export interface SynthesizedFinding {
+    stepId: string;
+    title: string;
+    description: string;
+    confidence: "high" | "medium" | "low";
+    noveltyStatus: "novel" | "confirmed" | "partially_confirmed" | "contradicted" | "expected";
+    literatureInterpretation: string;
+}
+export interface BiologicalTheme {
+    name: string;
+    findings: {
+        stepId: string;
+        title: string;
+    }[];
+    narrative: string;
+}
+export interface RunSynthesisPart {
+    type: "data-run-synthesis";
+    id: string;
+    runId: string;
+    overview: string;
+    conclusions?: string;
+    findings: SynthesizedFinding[];
+    themes: BiologicalTheme[];
+    limitations?: string[];
+    keyReferences: {
+        pmid: string;
+        citation: string;
+        description: string;
+    }[];
+}
+export type SynthesisPhase = "starting" | "researching" | "drafting" | "validating" | "refining" | "indexing" | "persisting" | "complete"
+/**
+ * Synthesizer chose to skip (e.g., technical-only run, summaries with no
+ * findings worth surfacing). Distinct from `failed` — this is an
+ * intentional outcome, not a breakage.
+ */
+ | "skipped" | "failed";
+export interface SynthesisProgressPart {
+    type: "data-synthesis-progress";
+    /** Stable ID for reconciliation — `synthesis-progress-{runId}`. */
+    id: string;
+    runId: string;
+    phase: SynthesisPhase;
+    /** Human-readable activity description. */
+    activity: string;
+    /** Number of literature-reviewer delegations started so far. */
+    delegationCount?: number;
+    /** Number of times the synthesizer's submit_synthesis call was rejected. */
+    validationAttempts?: number;
+    /** Agent-provided reason — set when phase === "skipped". */
+    reason?: string;
+    /** Error message — set when phase === "failed". */
+    error?: string;
+}
+export interface RunFailedPart {
+    type: "data-run-failed";
+    runId: string;
+    /** Scrubbed error message (no internal details). */
+    error: string;
+    /** Machine-readable failure reason (e.g., "budget_exceeded"). */
+    reason?: string;
+}
+export interface PreviewPart {
+    type: "data-report-preview";
+    /** Unique per emission (UUID). */
+    id: string;
+    /** Groups all versions of the same preview. */
+    previewId: string;
+    /** Version number (1, 2, 3, ...). */
+    version: number;
+    /** Report title. */
+    title: string;
+    /** Version-relative path (e.g., "v1/index.html"). */
+    previewPath: string;
+    /** Report format. */
+    format: "html" | "pdf";
+}
+export interface DataPreviewFailedPart {
+    type: "data-report-preview-failed";
+    /** Unique per emission (UUID). */
+    id: string;
+    /** Groups all versions of the same preview. */
+    previewId: string;
+    /** Attempted version number that failed. */
+    version: number;
+    /** Human-readable failure reason. */
+    reason: string;
+    /** Optional taxonomy of failure kinds. */
+    errorKind?: "render" | "submit" | "build" | "timeout" | "internal";
+}
+export type CortexChatPart = PresentationPart | PlanPart | RunCardPart | FileReferencePart | RunStartedPart | DagStatePart | StepActivityPart | StepFileTreePart | StepOutputPart | StepSummaryPart | StepBlockedPart | RunSynthesisPart | SynthesisProgressPart | RunCompletedPart | RunFailedPart | PreviewPart | DataPreviewFailedPart;

package/dist/contracts/chat-parts.js

@@ -0,0 +1,13 @@
+/**
+ * Cortex chat data parts — custom parts emitted via writer.write() / writer.custom()
+ * that flow through the chat stream and are rendered by the frontend.
+ *
+ * 15 part types across four categories:
+ *   Presentation:    data-presentation (agent-synthesized content),
+ *                    data-plan (plan by id), data-file-reference (files by path)
+ *   Run lifecycle:   run-started, dag-state, run-completed, run-failed, run-synthesis,
+ *                    synthesis-progress
+ *   Per-step live:   step-activity, step-file-tree
+ *   Per-step final:  step-output, step-summary
+ */
+export {};

package/dist/contracts/content-url.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Content URL construction — shared between the frontend and Cortex.
+ *
+ * The `res` claim formula and URL shape are the canonical TypeScript contract
+ * for the content-token preview flow. The storage backend mirrors the formula in Go; both
+ * sides are locked by the shared test vector at
+ * `src/__tests__/fixtures/preview-res.json`.
+ *
+ * End-to-end contract:
+ *   token res claim : "previews/{analysisId}/{previewId}"
+ *   URL             : {contentBaseUrl}/previews/{analysisId}/{previewId}/{previewPath}?t={token}
+ *   Caddy predicate : request.path.startsWith("/" + res + "/")
+ *
+ * This is URL space only. On disk a preview lives inside its analysis's workspace tree, at
+ * `{resolveWorkspaceRoot(analysisId)}/previews/{previewId}/{previewPath}` (the workspace-layout
+ * spec) — the `res` claim carries the analysis id because the URL needs an authorization
+ * boundary, whereas the resolved root already identifies the analysis and so does not repeat it.
+ * A host that serves previews owns the map between the two.
+ *
+ * The harness's contracts module owns this TS implementation so both the harness and
+ * react-client consume one canonical formula.
+ */
+/**
+ * Canonical `res` claim formula for a preview. Returns the literal string
+ * `previews/{analysisId}/{previewId}` with no leading or trailing slash.
+ *
+ * This is the URL sub-path served by the content-server (Caddy) and the token's
+ * authorization boundary — NOT a filesystem sub-path; see the module doc.
+ *
+ * MUST match `fmt.Sprintf("previews/%s/%s", analysisID, previewID)` in
+ * the storage backend's Go preview-access implementation. Drift is caught by the shared test
+ * vector at `src/__tests__/fixtures/preview-res.json`.
+ */
+export declare function previewResourceId(analysisId: string, previewId: string): string;
+/**
+ * Build a content-token preview URL for an iframe src.
+ *
+ * Produces `{contentBaseUrl}/{res}/{previewPath}?t={token}` where `res` is
+ * the output of `previewResourceId(analysisId, previewId)`. The query parameter
+ * name is `t` (matching Caddy's `from_query t` directive). The token is
+ * URL-encoded.
+ *
+ * @param contentBaseUrl - Content server base URL (trailing slash tolerated)
+ * @param analysisId - The analysis ID (authorization boundary)
+ * @param previewId - The preview ID (groups all versions)
+ * @param previewPath - Version-relative path (e.g., "v1/index.html"). Leading slash tolerated.
+ * @param token - Short-lived content token minted by the storage backend (required)
+ */
+export declare function buildPreviewUrl(contentBaseUrl: string, analysisId: string, previewId: string, previewPath: string, token: string): string;

package/dist/contracts/content-url.js

@@ -0,0 +1,56 @@
+/**
+ * Content URL construction — shared between the frontend and Cortex.
+ *
+ * The `res` claim formula and URL shape are the canonical TypeScript contract
+ * for the content-token preview flow. The storage backend mirrors the formula in Go; both
+ * sides are locked by the shared test vector at
+ * `src/__tests__/fixtures/preview-res.json`.
+ *
+ * End-to-end contract:
+ *   token res claim : "previews/{analysisId}/{previewId}"
+ *   URL             : {contentBaseUrl}/previews/{analysisId}/{previewId}/{previewPath}?t={token}
+ *   Caddy predicate : request.path.startsWith("/" + res + "/")
+ *
+ * This is URL space only. On disk a preview lives inside its analysis's workspace tree, at
+ * `{resolveWorkspaceRoot(analysisId)}/previews/{previewId}/{previewPath}` (the workspace-layout
+ * spec) — the `res` claim carries the analysis id because the URL needs an authorization
+ * boundary, whereas the resolved root already identifies the analysis and so does not repeat it.
+ * A host that serves previews owns the map between the two.
+ *
+ * The harness's contracts module owns this TS implementation so both the harness and
+ * react-client consume one canonical formula.
+ */
+/**
+ * Canonical `res` claim formula for a preview. Returns the literal string
+ * `previews/{analysisId}/{previewId}` with no leading or trailing slash.
+ *
+ * This is the URL sub-path served by the content-server (Caddy) and the token's
+ * authorization boundary — NOT a filesystem sub-path; see the module doc.
+ *
+ * MUST match `fmt.Sprintf("previews/%s/%s", analysisID, previewID)` in
+ * the storage backend's Go preview-access implementation. Drift is caught by the shared test
+ * vector at `src/__tests__/fixtures/preview-res.json`.
+ */
+export function previewResourceId(analysisId, previewId) {
+    return `previews/${analysisId}/${previewId}`;
+}
+/**
+ * Build a content-token preview URL for an iframe src.
+ *
+ * Produces `{contentBaseUrl}/{res}/{previewPath}?t={token}` where `res` is
+ * the output of `previewResourceId(analysisId, previewId)`. The query parameter
+ * name is `t` (matching Caddy's `from_query t` directive). The token is
+ * URL-encoded.
+ *
+ * @param contentBaseUrl - Content server base URL (trailing slash tolerated)
+ * @param analysisId - The analysis ID (authorization boundary)
+ * @param previewId - The preview ID (groups all versions)
+ * @param previewPath - Version-relative path (e.g., "v1/index.html"). Leading slash tolerated.
+ * @param token - Short-lived content token minted by the storage backend (required)
+ */
+export function buildPreviewUrl(contentBaseUrl, analysisId, previewId, previewPath, token) {
+    const base = contentBaseUrl.replace(/\/+$/, "");
+    const path = previewPath.replace(/^\/+/, "");
+    const res = previewResourceId(analysisId, previewId);
+    return `${base}/${res}/${path}?t=${encodeURIComponent(token)}`;
+}

package/dist/contracts/index.d.ts

@@ -0,0 +1,12 @@
+export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCardPart, FileReferenceEntry, FileReferencePart, RunStartedPart, StepStatus, DagStepState, DagStatePart, StepPhase, StepActivityPart, FileTreeEntry, StepFileTreePart, StepOutputFile, StepOutputPart, StepSummaryPart, StepBlockedPart, SynthesizedFinding, BiologicalTheme, RunSynthesisPart, SynthesisPhase, SynthesisProgressPart, RunCompletedFinding, RunCompletedPart, RunFailedPart, PreviewPart, DataPreviewFailedPart, CortexChatPart, } from "./chat-parts.js";
+export type { EventSource, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent, CortexChatEvent } from "./chat-events.js";
+export type { TextPart, ToolCallPart, CortexPart, CortexMessage } from "./message.js";
+export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
+export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./part-registry.js";
+export { AnalogyCoverageSchema, AnalogyReportSchema, AnalogyReportErrorSchema, AnalogicalReasonerOutputSchema } from "./analogy-report.js";
+export type { AnalogyCoverage, AnalogyReport, AnalogyReportError, AnalogicalReasonerOutput } from "./analogy-report.js";
+export { CoverageSchema, EntitySchema, SummarySchema, LiabilitySummarySchema, TractabilitySchema, IndicationsSchema, DrugInteractionsSchema, ClinicalDevelopmentSchema, SafetyProfileSchema, OffTissueRiskSchema, EvidenceConflictsSchema, EvidenceTimelineSchema, TranslationalChainSchema, AdditionalEvidenceSchema, DiscoveryTrialsSchema, DossierSchema, DossierSchemaV3Legacy, DossierV4Schema, DossierV5Schema, DossierV5BodySchema, ClinicalTrialAttributionV5Schema, ClinicalDevelopmentV5Schema, RegulatoryActionRowV5Schema, QualityGateStatusSchema, QualityGatesSchema, LiabilitySummaryV4Schema, ClinicalDevelopmentV4Schema, SafetyProfileV4Schema, OrganRiskRowV4Schema, ReferenceBiologyV4Shape, isDossier, dossierJsonSchema, SECTION_BLURBS, TargetAssessmentPhaseSchema, TargetAssessmentProgressEventSchema, } from "./target-dossier.js";
+export type { Coverage, Entity, Summary, LiabilitySummary, TractabilitySection, EvidenceItem, Dossier, DossierV4, DossierV5, DossierV5Body, ClinicalTrialAttributionV5, ClinicalTrialRowV5, FailedTrialRowV5, TrialOutcomeRowV5, RegulatoryActionRowV5, QualityGateStatus, QualityGates, SectionBlurbKey, TargetAssessmentPhase, TargetAssessmentProgressEvent, } from "./target-dossier.js";
+export { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema, } from "./target-assessment-row.js";
+export type { TargetAssessmentStatus, TargetAssessmentError, TargetAssessmentListRow, TargetAssessmentRow } from "./target-assessment-row.js";
+export { buildPreviewUrl, previewResourceId } from "./content-url.js";

package/dist/contracts/index.js

@@ -0,0 +1,5 @@
+export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
+export { AnalogyCoverageSchema, AnalogyReportSchema, AnalogyReportErrorSchema, AnalogicalReasonerOutputSchema } from "./analogy-report.js";
+export { CoverageSchema, EntitySchema, SummarySchema, LiabilitySummarySchema, TractabilitySchema, IndicationsSchema, DrugInteractionsSchema, ClinicalDevelopmentSchema, SafetyProfileSchema, OffTissueRiskSchema, EvidenceConflictsSchema, EvidenceTimelineSchema, TranslationalChainSchema, AdditionalEvidenceSchema, DiscoveryTrialsSchema, DossierSchema, DossierSchemaV3Legacy, DossierV4Schema, DossierV5Schema, DossierV5BodySchema, ClinicalTrialAttributionV5Schema, ClinicalDevelopmentV5Schema, RegulatoryActionRowV5Schema, QualityGateStatusSchema, QualityGatesSchema, LiabilitySummaryV4Schema, ClinicalDevelopmentV4Schema, SafetyProfileV4Schema, OrganRiskRowV4Schema, ReferenceBiologyV4Shape, isDossier, dossierJsonSchema, SECTION_BLURBS, TargetAssessmentPhaseSchema, TargetAssessmentProgressEventSchema, } from "./target-dossier.js";
+export { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema, } from "./target-assessment-row.js";
+export { buildPreviewUrl, previewResourceId } from "./content-url.js";

package/dist/contracts/message.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cortex-owned chat message types — the wire shape, the in-memory shape,
+ * and the public API for everything the chat path exchanges.
+ *
+ * No AI SDK types appear here or anywhere else in the package. The
+ * discriminant is `type`, so `switch (part.type) { case "data-report-preview": ... }`
+ * narrows the union member without any `as` cast.
+ */
+import type { CortexChatPart } from "./chat-parts.js";
+/** A plain assistant/user text run. */
+export interface TextPart {
+    type: "text";
+    text: string;
+}
+/**
+ * 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"`.
+ */
+export interface ToolCallPart {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    status: "started" | "finished";
+    isError?: boolean;
+}
+/** The discriminated union of every part the chat path can carry. */
+export type CortexPart = TextPart | ToolCallPart | CortexChatPart;
+/** A single chat message — user, assistant, or system. */
+export interface CortexMessage {
+    id: string;
+    role: "user" | "assistant" | "system";
+    parts: CortexPart[];
+}

package/dist/contracts/message.js

@@ -0,0 +1,9 @@
+/**
+ * Cortex-owned chat message types — the wire shape, the in-memory shape,
+ * and the public API for everything the chat path exchanges.
+ *
+ * No AI SDK types appear here or anywhere else in the package. The
+ * discriminant is `type`, so `switch (part.type) { case "data-report-preview": ... }`
+ * narrows the union member without any `as` cast.
+ */
+export {};

package/dist/contracts/part-registry.d.ts

@@ -0,0 +1,18 @@
+import type { CortexChatPart } from "./chat-parts.js";
+export type CortexChatPartType = CortexChatPart["type"];
+export type PartEmitter = "workflow" | "conversation";
+export type PartConsumer = "sidebar" | "conversation";
+export interface PartDescriptor {
+    /** Which layer emits this part. */
+    emitter: PartEmitter;
+    /** Which UI surface consumes this part. */
+    consumer: PartConsumer;
+    /** If true, only useful during live streaming — not accumulated in workflow state. */
+    transient: boolean;
+    /** If true, multiple emissions share the same id — latest wins. */
+    reconciling: boolean;
+}
+export declare const PART_REGISTRY: Record<CortexChatPartType, PartDescriptor>;
+export declare function isTransient(type: CortexChatPartType): boolean;
+export declare function isReconciling(type: CortexChatPartType): boolean;
+export declare function isSidebarPart(type: CortexChatPartType): boolean;

package/dist/contracts/part-registry.js

@@ -0,0 +1,28 @@
+export const PART_REGISTRY = {
+    "data-presentation": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
+    "data-plan": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
+    "data-run-card": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
+    "data-file-reference": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
+    "data-run-started": { emitter: "workflow", consumer: "sidebar", transient: true, reconciling: false },
+    "data-dag-state": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: true },
+    "data-step-activity": { emitter: "workflow", consumer: "sidebar", transient: true, reconciling: true },
+    "data-step-file-tree": { emitter: "workflow", consumer: "sidebar", transient: true, reconciling: true },
+    "data-step-output": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
+    "data-step-summary": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
+    "data-step-blocked": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
+    "data-run-synthesis": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
+    "data-synthesis-progress": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: true },
+    "data-run-completed": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
+    "data-run-failed": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
+    "data-report-preview": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
+    "data-report-preview-failed": { emitter: "conversation", consumer: "conversation", transient: false, reconciling: false },
+};
+export function isTransient(type) {
+    return PART_REGISTRY[type].transient;
+}
+export function isReconciling(type) {
+    return PART_REGISTRY[type].reconciling;
+}
+export function isSidebarPart(type) {
+    return PART_REGISTRY[type].consumer === "sidebar";
+}