@company-semantics/contracts 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -133,6 +133,38 @@ export type {
   AssistantMessagePart,
   PartBuilderState,
   AddPartResult,
+  // Preview types (Phase 3)
+  PreviewArtifactKind,
+  PreviewArtifact,
+  PreviewData,
+  PreviewPart,
+  PreviewDataPart,
+  // Confirmation types (Phase 4)
+  ConfirmationChoice,
+  ConfirmationRisk,
+  ConfirmationData,
+  ConfirmationDataPart,
+  ConfirmationResponseData,
+  ConfirmationResponsePart,
+  ConfirmationResponseDataPart,
+  // Execution result types (Phase 5)
+  ExecutionArtifactStatus,
+  ExecutionResultData,
+  ExecutionResultPart,
+  ExecutionResultDataPart,
+  // Message lifecycle types (Phase 1 streaming)
+  // @see ADR-CONT-027 for design rationale
+  StreamPhase,
+  MessageLifecycleEventType,
+  MessageLifecycleEvent,
+  MessageStartEvent,
+  MessageDeltaEvent,
+  MessageCompleteEvent,
+  ToolResultRenderClass,
+  ToolResultPart,
+  MessageStartDataPart,
+  MessageDeltaDataPart,
+  MessageCompleteDataPart,
 } from './message-parts/index.js'
 
 export {

package/src/message-parts/__tests__/confirmation.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest'
+import { WireSurfaceBuilder } from '../wire.js'
+import type { ConfirmationData, ConfirmationResponseData } from '../confirmation.js'
+
+describe('WireSurfaceBuilder.confirmation', () => {
+  it('creates a confirmation data part', () => {
+    const data: ConfirmationData = {
+      actionId: 'msg-123',
+      title: 'Send Slack message to #sales',
+      prompt: 'Confirm sending this message?',
+      risk: 'low',
+    }
+
+    const result = WireSurfaceBuilder.confirmation(data)
+
+    expect(result.type).toBe('data-confirmation')
+    expect(result.data).toEqual(data)
+  })
+
+  it('preserves actionId exactly', () => {
+    const data: ConfirmationData = {
+      actionId: 'complex-action-id-12345',
+      title: 'Test',
+      prompt: 'Confirm?',
+    }
+
+    const result = WireSurfaceBuilder.confirmation(data)
+
+    expect(result.data.actionId).toBe('complex-action-id-12345')
+  })
+
+  it('handles confirmation without optional risk level', () => {
+    const data: ConfirmationData = {
+      actionId: 'no-risk-specified',
+      title: 'Simple action',
+      prompt: 'Do you want to proceed?',
+    }
+
+    const result = WireSurfaceBuilder.confirmation(data)
+
+    expect(result.type).toBe('data-confirmation')
+    expect(result.data.risk).toBeUndefined()
+  })
+
+  it('preserves all risk levels', () => {
+    const risks: Array<'low' | 'medium' | 'high'> = ['low', 'medium', 'high']
+
+    for (const risk of risks) {
+      const data: ConfirmationData = {
+        actionId: `risk-${risk}`,
+        title: `${risk} risk action`,
+        prompt: 'Confirm?',
+        risk,
+      }
+
+      const result = WireSurfaceBuilder.confirmation(data)
+
+      expect(result.data.risk).toBe(risk)
+    }
+  })
+})
+
+describe('WireSurfaceBuilder.confirmationResponse', () => {
+  it('creates a confirmation response for confirm choice', () => {
+    const data: ConfirmationResponseData = {
+      actionId: 'msg-123',
+      choice: 'confirm',
+    }
+
+    const result = WireSurfaceBuilder.confirmationResponse(data)
+
+    expect(result.type).toBe('data-confirmation-response')
+    expect(result.data.actionId).toBe('msg-123')
+    expect(result.data.choice).toBe('confirm')
+  })
+
+  it('creates a confirmation response for cancel choice', () => {
+    const data: ConfirmationResponseData = {
+      actionId: 'msg-123',
+      choice: 'cancel',
+    }
+
+    const result = WireSurfaceBuilder.confirmationResponse(data)
+
+    expect(result.type).toBe('data-confirmation-response')
+    expect(result.data.choice).toBe('cancel')
+  })
+
+  it('preserves actionId exactly in response', () => {
+    const data: ConfirmationResponseData = {
+      actionId: 'complex-action-id-12345',
+      choice: 'confirm',
+    }
+
+    const result = WireSurfaceBuilder.confirmationResponse(data)
+
+    expect(result.data.actionId).toBe('complex-action-id-12345')
+  })
+})

package/src/message-parts/__tests__/preview.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { WireSurfaceBuilder } from '../wire.js'
+import type { PreviewData, PreviewArtifact } from '../preview.js'
+
+describe('WireSurfaceBuilder.preview', () => {
+  it('creates a preview data part', () => {
+    const data: PreviewData = {
+      actionId: 'msg-123',
+      title: 'Send Slack message to #sales',
+      description: 'This will notify the sales team about the new pricing.',
+      artifacts: [
+        {
+          kind: 'message',
+          label: '#sales',
+          content: {
+            channel: 'C123456',
+            text: 'New pricing is live!',
+          },
+        },
+      ],
+    }
+
+    const result = WireSurfaceBuilder.preview(data)
+
+    expect(result.type).toBe('data-preview')
+    expect(result.data).toEqual(data)
+  })
+
+  it('preserves artifact structure exactly', () => {
+    const artifacts: PreviewArtifact[] = [
+      {
+        kind: 'api_call',
+        label: 'POST /api/notify',
+        content: { method: 'POST', body: { message: 'test' } },
+        metadata: { target: 'internal-api', impact: 'low' },
+      },
+      {
+        kind: 'notification',
+        label: 'Email to team@example.com',
+        content: { to: 'team@example.com', subject: 'Update' },
+      },
+    ]
+
+    const data: PreviewData = {
+      actionId: 'multi-123',
+      title: 'Multi-step action',
+      artifacts,
+    }
+
+    const result = WireSurfaceBuilder.preview(data)
+
+    expect(result.data.artifacts).toEqual(artifacts)
+    expect(result.data.artifacts[0].metadata?.impact).toBe('low')
+  })
+
+  it('handles empty artifacts array', () => {
+    const data: PreviewData = {
+      actionId: 'empty-preview',
+      title: 'No actions preview',
+      artifacts: [],
+    }
+
+    const result = WireSurfaceBuilder.preview(data)
+
+    expect(result.type).toBe('data-preview')
+    expect(result.data.artifacts).toEqual([])
+  })
+
+  it('preserves all artifact kinds', () => {
+    const allKinds: PreviewArtifact[] = [
+      { kind: 'message', label: 'Slack message', content: {} },
+      { kind: 'api_call', label: 'API call', content: {} },
+      { kind: 'diff', label: 'File change', content: {} },
+      { kind: 'notification', label: 'Notification', content: {} },
+      { kind: 'task', label: 'Task creation', content: {} },
+      { kind: 'calendar', label: 'Calendar event', content: {} },
+    ]
+
+    const data: PreviewData = {
+      actionId: 'all-kinds',
+      title: 'All artifact kinds',
+      artifacts: allKinds,
+    }
+
+    const result = WireSurfaceBuilder.preview(data)
+
+    expect(result.data.artifacts).toHaveLength(6)
+    expect(result.data.artifacts.map((a) => a.kind)).toEqual([
+      'message',
+      'api_call',
+      'diff',
+      'notification',
+      'task',
+      'calendar',
+    ])
+  })
+})

package/src/message-parts/confirmation.ts

@@ -0,0 +1,87 @@
+/**
+ * Confirmation Surface Types
+ *
+ * Confirmation surfaces request explicit user decision on a proposed action.
+ * Only structured signals are accepted - no natural language inference.
+ *
+ * CONFIRMATION MODE INVARIANTS:
+ * - Confirmation is deterministic and system-owned
+ * - No tool calls are allowed in confirmation mode
+ * - Confirmation must reference a specific actionId
+ * - Only structured confirmation-response signals are accepted
+ * - Natural language is never used to infer confirmation ("yes", "go ahead" = invalid)
+ * - Execution is impossible in Phase 4 - only Phase 5 can execute
+ * - At most one action is confirmable at a time
+ * - Mismatched actionId fails closed and re-prompts
+ *
+ * @see DECISIONS.md for design rationale
+ */
+
+/**
+ * Choice options for confirmation.
+ */
+export type ConfirmationChoice = 'confirm' | 'cancel';
+
+/**
+ * Risk level for confirmation prompts.
+ */
+export type ConfirmationRisk = 'low' | 'medium' | 'high';
+
+/**
+ * Confirmation request data payload.
+ */
+export interface ConfirmationData {
+  /** Must match the active preview's actionId */
+  actionId: string;
+  /** Summary of the action being confirmed */
+  title: string;
+  /** The confirmation prompt, e.g. "Confirm sending this Slack message?" */
+  prompt: string;
+  /** Optional risk level for UI styling */
+  risk?: ConfirmationRisk;
+}
+
+/**
+ * Confirmation request message part (semantic type).
+ */
+export interface ConfirmationPart {
+  type: 'confirmation';
+  data: ConfirmationData;
+}
+
+/**
+ * Confirmation request data part (wire format).
+ */
+export interface ConfirmationDataPart {
+  type: 'data-confirmation';
+  data: ConfirmationData;
+}
+
+// === Confirmation Response Types (New in Phase 4) ===
+
+/**
+ * Confirmation response data payload.
+ * Sent by the user (via UI button or structured message) to confirm/cancel.
+ */
+export interface ConfirmationResponseData {
+  /** Must match the active confirmation's actionId */
+  actionId: string;
+  /** The user's decision */
+  choice: ConfirmationChoice;
+}
+
+/**
+ * Confirmation response message part (semantic type).
+ */
+export interface ConfirmationResponsePart {
+  type: 'confirmation-response';
+  data: ConfirmationResponseData;
+}
+
+/**
+ * Confirmation response data part (wire format).
+ */
+export interface ConfirmationResponseDataPart {
+  type: 'data-confirmation-response';
+  data: ConfirmationResponseData;
+}

package/src/message-parts/execution.ts

@@ -0,0 +1,53 @@
+/**
+ * Execution Result Surface Types
+ *
+ * Surfaces for displaying execution results to the user.
+ *
+ * EXECUTION MODE INVARIANTS:
+ * - Execution occurs only after confirmation with matching actionId
+ * - Each actionId executes at most once (idempotency)
+ * - All executions produce audit records (success or failure)
+ * - Execution is synchronous and deterministic
+ * - Tools are explicitly allowlisted per artifact kind
+ * - No retries, no background work, no rollback
+ * - Failures stop execution immediately
+ *
+ * @see DECISIONS.md for design rationale
+ */
+
+import type { PreviewArtifactKind } from './preview.js';
+
+/**
+ * Status of a single artifact's execution.
+ */
+export interface ExecutionArtifactStatus {
+  kind: PreviewArtifactKind;
+  label: string;
+  status: 'success' | 'failed' | 'skipped';
+  error?: string;
+}
+
+/**
+ * Execution result data payload.
+ */
+export interface ExecutionResultData {
+  actionId: string;
+  status: 'success' | 'failed';
+  artifacts: ExecutionArtifactStatus[];
+}
+
+/**
+ * Execution result message part (semantic type).
+ */
+export interface ExecutionResultPart {
+  type: 'execution-result';
+  data: ExecutionResultData;
+}
+
+/**
+ * Execution result data part (wire format).
+ */
+export interface ExecutionResultDataPart {
+  type: 'data-execution-result';
+  data: ExecutionResultData;
+}

package/src/message-parts/index.ts

@@ -14,11 +14,54 @@ export type {
   ChartPart,
   ChartDataPoint,
   TablePart,
-  ConfirmationPart,
   SurfacePart,
   AssistantMessagePart,
 } from './types.js'
 
+// Preview types
+export type {
+  PreviewArtifactKind,
+  PreviewArtifact,
+  PreviewData,
+  PreviewPart,
+  PreviewDataPart,
+} from './preview.js'
+
+// Confirmation types
+export type {
+  ConfirmationChoice,
+  ConfirmationRisk,
+  ConfirmationData,
+  ConfirmationPart,
+  ConfirmationDataPart,
+  ConfirmationResponseData,
+  ConfirmationResponsePart,
+  ConfirmationResponseDataPart,
+} from './confirmation.js'
+
+// Execution result types
+export type {
+  ExecutionArtifactStatus,
+  ExecutionResultData,
+  ExecutionResultPart,
+  ExecutionResultDataPart,
+} from './execution.js'
+
+// Lifecycle types (Phase 1 streaming)
+export type {
+  StreamPhase,
+  MessageLifecycleEventType,
+  MessageLifecycleEvent,
+  MessageStartEvent,
+  MessageDeltaEvent,
+  MessageCompleteEvent,
+  ToolResultRenderClass,
+  ToolResultPart,
+  MessageStartDataPart,
+  MessageDeltaDataPart,
+  MessageCompleteDataPart,
+} from './lifecycle.js'
+
 // Type guards
 export { isTextPart, isSurfacePart } from './types.js'
 

package/src/message-parts/lifecycle.ts

@@ -0,0 +1,147 @@
+/**
+ * Message Lifecycle Event Vocabulary
+ *
+ * Explicit lifecycle events for message streaming.
+ * Backend is the single authority for message lifecycle state.
+ *
+ * INVARIANTS:
+ * - Every message stream MUST emit: start -> delta* -> complete
+ * - messageId MUST be consistent across all events for a single message
+ * - version field enables protocol evolution without breaking changes
+ *
+ * @see ADR-CONT-027 for design rationale
+ */
+
+// =============================================================================
+// Stream Phase
+// =============================================================================
+
+/**
+ * Derived stream phase for UI state management.
+ * Frontend derives this from lifecycle events, not vice versa.
+ *
+ * - idle: No active stream (initial state, or after complete)
+ * - streaming: Between message.start and message.complete
+ * - complete: After message.complete received
+ */
+export type StreamPhase = 'idle' | 'streaming' | 'complete'
+
+// =============================================================================
+// Lifecycle Event Types
+// =============================================================================
+
+/**
+ * Lifecycle event type discriminator.
+ */
+export type MessageLifecycleEventType =
+  | 'message.start'
+  | 'message.delta'
+  | 'message.complete'
+
+/**
+ * Base interface for all message lifecycle events.
+ *
+ * @property type - Event discriminator
+ * @property version - Protocol version (add now, expensive to retrofit later)
+ * @property messageId - Correlation identifier for the message
+ * @property timestamp - ISO 8601 timestamp of event emission
+ */
+export interface MessageLifecycleEvent {
+  type: MessageLifecycleEventType
+  version: 1
+  messageId: string
+  timestamp: string
+}
+
+/**
+ * Message start event.
+ * Emitted when a new message stream begins.
+ */
+export interface MessageStartEvent extends MessageLifecycleEvent {
+  type: 'message.start'
+}
+
+/**
+ * Message delta event.
+ * Emitted for each text chunk during streaming.
+ * Only contains narrative text, not surface parts.
+ */
+export interface MessageDeltaEvent extends MessageLifecycleEvent {
+  type: 'message.delta'
+  /** The text delta (narrative content only) */
+  delta: string
+}
+
+/**
+ * Message complete event.
+ * Emitted when the message stream ends.
+ * Signals that all narrative content has been streamed.
+ */
+export interface MessageCompleteEvent extends MessageLifecycleEvent {
+  type: 'message.complete'
+  /** Total length of narrative content for validation */
+  narrativeLength: number
+}
+
+// =============================================================================
+// Tool Result Rendering Classification
+// =============================================================================
+
+/**
+ * Tool result rendering classification.
+ * This is protocol metadata, not a UI decision.
+ *
+ * - inline: Render during streaming (narrative-like)
+ *   Examples: search snippets, numbers, short text, intermediate reasoning
+ *   No atomicity guarantee, safe to interleave with text
+ *
+ * - surface: Render only after message.complete (UI commitment)
+ *   Examples: tool lists, cards, dashboards, MCP UI components
+ *   Atomic, deterministic, never stream
+ */
+export type ToolResultRenderClass = 'inline' | 'surface'
+
+/**
+ * Tool result part with rendering classification.
+ */
+export interface ToolResultPart {
+  type: 'tool-result'
+  /** Tool identifier */
+  toolName: string
+  /** Rendering classification */
+  render: ToolResultRenderClass
+  /** Tool-specific payload */
+  payload: unknown
+  /** Optional message correlation (enables out-of-band arrival, multi-message chains) */
+  messageId?: string
+}
+
+// =============================================================================
+// Wire Format Types
+// =============================================================================
+
+/**
+ * Wire format for message start event.
+ * Follows AI SDK's data-{name} convention.
+ */
+export interface MessageStartDataPart {
+  type: 'data-message-start'
+  data: Omit<MessageStartEvent, 'type'>
+}
+
+/**
+ * Wire format for message delta event.
+ * Note: Standard text-delta may be used instead for AI SDK compatibility.
+ */
+export interface MessageDeltaDataPart {
+  type: 'data-message-delta'
+  data: Omit<MessageDeltaEvent, 'type'>
+}
+
+/**
+ * Wire format for message complete event.
+ */
+export interface MessageCompleteDataPart {
+  type: 'data-message-complete'
+  data: Omit<MessageCompleteEvent, 'type'>
+}

package/src/message-parts/preview.ts

@@ -0,0 +1,81 @@
+/**
+ * Preview Surface Types
+ *
+ * Preview surfaces represent exactly what would happen if an action were executed.
+ * They are read-only by contract and contain no side effects.
+ *
+ * PREVIEW MODE INVARIANTS:
+ * - Preview surfaces are read-only
+ * - Preview mode allows zero side effects
+ * - Preview artifacts must be exactly executable later
+ * - Execution is impossible without a later mode transition
+ * - LLMs never execute actions in preview mode
+ * - Preview mode is entered when system emits data-preview surface (not user intent)
+ * - User messages during preview do not affect mode; only assistant output controls persistence
+ * - At most one preview proposal is active at a time (multiple previews are sequential, not concurrent)
+ *
+ * @see DECISIONS.md for design rationale
+ */
+
+/**
+ * Preview artifact kinds.
+ * Each kind represents a different type of action that could be executed.
+ */
+export type PreviewArtifactKind =
+  | 'message' // Slack/chat message to send
+  | 'api_call' // External API call
+  | 'diff' // File or document change
+  | 'notification' // Notification to user/team
+  | 'task' // Task creation
+  | 'calendar' // Calendar event
+
+/**
+ * A single artifact within a preview.
+ * Represents one atomic action that would be taken.
+ */
+export interface PreviewArtifact {
+  /** The kind of action this artifact represents */
+  kind: PreviewArtifactKind
+  /** Human-readable label for this artifact */
+  label: string
+  /** The exact payload that would be executed - must be JSON-safe */
+  content: unknown
+  /** Optional metadata for display purposes */
+  metadata?: {
+    /** Target system (e.g., "slack", "google-calendar") */
+    target?: string
+    /** Estimated impact level */
+    impact?: 'low' | 'medium' | 'high'
+  }
+}
+
+/**
+ * Preview surface data payload.
+ */
+export interface PreviewData {
+  /** Stable identifier for this preview - used for confirmation tracking */
+  actionId: string
+  /** Human-readable summary of what will happen */
+  title: string
+  /** Optional detailed explanation */
+  description?: string
+  /** The artifacts that would be created/sent/modified */
+  artifacts: PreviewArtifact[]
+}
+
+/**
+ * Preview message part (semantic type).
+ */
+export interface PreviewPart {
+  type: 'preview'
+  data: PreviewData
+}
+
+/**
+ * Preview data part (wire format).
+ * Uses AI SDK's data-{name} convention.
+ */
+export interface PreviewDataPart {
+  type: 'data-preview'
+  data: PreviewData
+}

package/src/message-parts/types.ts

@@ -14,6 +14,8 @@
  */
 
 import type { ToolListMessagePart } from '../mcp/index.js'
+import type { PreviewPart } from './preview.js'
+import type { ConfirmationPart, ConfirmationResponsePart } from './confirmation.js'
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -102,20 +104,6 @@ export interface TablePart {
   rows: string[][]
 }
 
-/**
- * Confirmation request surface part.
- * Requests user confirmation before proceeding.
- */
-export interface ConfirmationPart {
-  type: 'confirmation'
-  /** What is being confirmed */
-  action: string
-  /** Optional details */
-  details?: string
-  /** Confirmation ID for response tracking */
-  confirmationId: string
-}
-
 // =============================================================================
 // Part Unions
 // =============================================================================
@@ -123,6 +111,9 @@ export interface ConfirmationPart {
 /**
  * Surface parts are rendered atomically (never streamed).
  * Extensible: add new surface types to this union.
+ *
+ * Note: ConfirmationResponsePart is user-originated but included
+ * here for uniform parsing. Do not render as UI surface.
  */
 export type SurfacePart =
   | ToolListPart
@@ -130,6 +121,8 @@ export type SurfacePart =
   | ChartPart
   | TablePart
   | ConfirmationPart
+  | ConfirmationResponsePart
+  | PreviewPart
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -11,6 +11,18 @@
  */
 
 import type { MCPToolDescriptor, ToolListDataPart } from '../mcp/index.js'
+import type { PreviewDataPart, PreviewData } from './preview.js'
+import type {
+  ConfirmationData,
+  ConfirmationDataPart,
+  ConfirmationResponseData,
+  ConfirmationResponseDataPart,
+} from './confirmation.js'
+import type { ExecutionResultData, ExecutionResultDataPart } from './execution.js'
+import type {
+  MessageStartDataPart,
+  MessageCompleteDataPart,
+} from './lifecycle.js'
 
 /**
  * Factory for creating wire-format surface parts.
@@ -37,4 +49,129 @@ export const WireSurfaceBuilder = {
       data: { tools },
     }
   },
+
+  /**
+   * Build a preview data part for streaming.
+   * Previews show exactly what would happen if an action were executed.
+   *
+   * INVARIANTS:
+   * - Preview data must be exactly executable later
+   * - No placeholders or approximations
+   * - actionId must be stable for confirmation tracking
+   *
+   * @param data - Preview data containing actionId, title, and artifacts
+   * @returns Wire-format preview part ready for stream
+   */
+  preview(data: PreviewData): PreviewDataPart {
+    return {
+      type: 'data-preview',
+      data,
+    }
+  },
+
+  /**
+   * Build a confirmation request data part for streaming.
+   * Requests explicit user decision on a proposed action.
+   *
+   * INVARIANTS:
+   * - actionId must match the active preview
+   * - Only structured responses are accepted
+   *
+   * @param data - Confirmation data containing actionId, title, and prompt
+   * @returns Wire-format confirmation part ready for stream
+   */
+  confirmation(data: ConfirmationData): ConfirmationDataPart {
+    return {
+      type: 'data-confirmation',
+      data,
+    }
+  },
+
+  /**
+   * Build a confirmation response data part.
+   * Used when processing user's confirm/cancel decision.
+   *
+   * INVARIANTS:
+   * - actionId must match the active confirmation
+   * - choice must be 'confirm' or 'cancel'
+   *
+   * @param data - Response data containing actionId and choice
+   * @returns Wire-format confirmation response part
+   */
+  confirmationResponse(data: ConfirmationResponseData): ConfirmationResponseDataPart {
+    return {
+      type: 'data-confirmation-response',
+      data,
+    }
+  },
+
+  /**
+   * Build an execution result data part for streaming.
+   * Reports the outcome of an executed action.
+   *
+   * INVARIANTS:
+   * - actionId must match the executed action
+   * - All artifacts have a status (success, failed, or skipped)
+   * - Execution is complete and audited before this is sent
+   *
+   * @param data - Execution result data
+   * @returns Wire-format execution result part ready for stream
+   */
+  executionResult(data: ExecutionResultData): ExecutionResultDataPart {
+    return {
+      type: 'data-execution-result',
+      data,
+    }
+  },
+
+  // =========================================================================
+  // Message Lifecycle Events (Phase 1)
+  // =========================================================================
+
+  /**
+   * Build a message start event for streaming.
+   * Emit at the beginning of a new message stream.
+   *
+   * INVARIANTS:
+   * - Must be emitted before any text-delta or surface parts
+   * - messageId must be consistent across all events for this message
+   *
+   * @param messageId - Unique identifier for this message
+   * @returns Wire-format message start event
+   */
+  messageStart(messageId: string): MessageStartDataPart {
+    return {
+      type: 'data-message-start',
+      data: {
+        version: 1,
+        messageId,
+        timestamp: new Date().toISOString(),
+      },
+    }
+  },
+
+  /**
+   * Build a message complete event for streaming.
+   * Emit after all narrative content has been streamed.
+   *
+   * INVARIANTS:
+   * - Must be emitted after all text-delta events
+   * - Surface parts (if any) should be emitted after this
+   * - narrativeLength must match total text content length
+   *
+   * @param messageId - Message identifier (must match start event)
+   * @param narrativeLength - Total length of streamed narrative text
+   * @returns Wire-format message complete event
+   */
+  messageComplete(messageId: string, narrativeLength: number): MessageCompleteDataPart {
+    return {
+      type: 'data-message-complete',
+      data: {
+        version: 1,
+        messageId,
+        narrativeLength,
+        timestamp: new Date().toISOString(),
+      },
+    }
+  },
 } as const