@company-semantics/contracts 0.26.0 → 0.27.0

package/package.json

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

package/src/index.ts

@@ -133,6 +133,25 @@ 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,
 } 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,39 @@ 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'
+
 // Type guards
 export { isTextPart, isSurfacePart } from './types.js'
 

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,14 @@
  */
 
 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'
 
 /**
  * Factory for creating wire-format surface parts.
@@ -37,4 +45,78 @@ 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,
+    }
+  },
 } as const