@company-semantics/contracts 0.27.0 → 0.28.0

package/package.json

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

package/src/index.ts

@@ -152,6 +152,19 @@ export type {
   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/index.ts

@@ -47,6 +47,21 @@ export type {
   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/wire.ts

@@ -19,6 +19,10 @@ import type {
   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.
@@ -119,4 +123,55 @@ export const WireSurfaceBuilder = {
       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