@company-semantics/contracts 0.77.0 → 0.79.0

package/package.json

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

package/src/chat/index.ts

@@ -45,3 +45,7 @@ export type {
   LegacyChatListInvalidatedEvent,
   LegacyChatSseEvent,
 } from './types'
+
+// Runtime profile types and constants
+export type { ChatRuntimeProfile, ChatRuntimeProfileInfo } from './runtime-profile'
+export { CHAT_RUNTIME_PROFILES, DEFAULT_CHAT_RUNTIME_PROFILE } from './runtime-profile'

package/src/chat/runtime-profile.ts

@@ -0,0 +1,36 @@
+/**
+ * Chat runtime profile — user-selectable orchestration strategy.
+ *
+ * Abstracts vendor and model details from the UI.
+ * The profile-to-orchestrator mapping is server-defined.
+ *
+ * - fast: Low-latency, single-step. AiSdkOrchestrator + gpt-3.5-turbo.
+ * - balanced: Default. AiSdkOrchestrator + gpt-4o with tool support.
+ * - agentic: Multi-turn agent loop. ClaudeAgentOrchestrator.
+ */
+export type ChatRuntimeProfile = 'fast' | 'balanced' | 'agentic'
+
+/**
+ * Runtime profile metadata for UI rendering.
+ * Labels and descriptions are user-facing — no vendor names.
+ */
+export interface ChatRuntimeProfileInfo {
+  id: ChatRuntimeProfile
+  label: string
+  description: string
+  model: string
+}
+
+/**
+ * Ordered list of available profiles for UI rendering.
+ */
+export const CHAT_RUNTIME_PROFILES: readonly ChatRuntimeProfileInfo[] = [
+  { id: 'fast', label: 'Fast', description: 'Single-step, no tools', model: 'gpt-3.5-turbo' },
+  { id: 'balanced', label: 'Balanced', description: 'Multi-step with tools', model: 'gpt-4o' },
+  { id: 'agentic', label: 'Agentic', description: 'Agent loop, full reasoning', model: 'claude-sonnet-4' },
+] as const
+
+/**
+ * Default profile when none is specified in the request.
+ */
+export const DEFAULT_CHAT_RUNTIME_PROFILE: ChatRuntimeProfile = 'agentic'

package/src/index.ts

@@ -176,8 +176,13 @@ export type {
   LegacyChatInvalidatedEvent,
   LegacyChatListInvalidatedEvent,
   LegacyChatSseEvent,
+  // Runtime profile types (PRD-00229)
+  ChatRuntimeProfile,
+  ChatRuntimeProfileInfo,
 } from './chat/index'
 
+export { CHAT_RUNTIME_PROFILES, DEFAULT_CHAT_RUNTIME_PROFILE } from './chat/index'
+
 // Organization domain types
 // @see ADR-BE-XXX for design rationale (Personal vs Shared Organization Model)
 export type {
@@ -306,9 +311,14 @@ export type {
   ConfirmationResponseDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
+  ExecutionResultSummary,
+  ExecutionUndoCapability,
   ExecutionResultData,
   ExecutionResultPart,
   ExecutionResultDataPart,
+  // Undo result types (PRD-00203)
+  UndoResultData,
+  UndoResultDataPart,
   // Message lifecycle types (Phase 1 streaming)
   // @see ADR-CONT-027 for design rationale
   StreamPhase,
@@ -467,3 +477,10 @@ export type {
   UsageByUser,
   OrgUsageResponse,
 } from './usage/types'
+
+// Runtime execution telemetry types
+// @see PRD-00200 for design rationale
+export type {
+  ExecutionFailureReason,
+  RuntimeExecutionTelemetry,
+} from './usage/execution-types'

package/src/message-parts/execution.ts

@@ -2,6 +2,7 @@
  * Execution Result Surface Types
  *
  * Surfaces for displaying execution results to the user.
+ * User-initiated undo is supported with a server-enforced time window.
  *
  * EXECUTION MODE INVARIANTS:
  * - Execution occurs only after confirmation with matching actionId
@@ -9,9 +10,20 @@
  * - 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
  *
+ * INV-1: ExecutionState is single authority — no redundant status fields.
+ *        ExecutionResultData carries `state` resolved from ExecutionState.
+ * INV-2: Append-only audit model — undo creates a second row with `undo_of`
+ *        reference. Original execution row is never mutated.
+ * INV-3: Undo payload persisted server-side only — never on the wire.
+ *        Only the undo capability descriptor (availableUntil, kind) is sent.
+ * INV-4: Undo is idempotent — second call returns existing result.
+ * INV-5: actionId uniqueness per artifact — each artifact kind resolves to
+ *        at most one execution per actionId.
+ * INV-6: Undo race condition — 409 on expired window. Server rejects undo
+ *        attempts after availableUntil deadline.
+ *
  * @see DECISIONS.md for design rationale
  */
 
@@ -25,6 +37,29 @@ export interface ExecutionArtifactStatus {
   label: string;
   status: 'success' | 'failed' | 'skipped';
   error?: string;
+  /** Human-readable result summary, e.g. 'Preferred name set to Ian' */
+  resultLabel?: string;
+}
+
+/**
+ * Structured summary for generic UI rendering (executor-provided).
+ */
+export interface ExecutionResultSummary {
+  /** Human-readable title, e.g. 'Profile Updated' */
+  title: string;
+  /** Optional description, e.g. 'Preferred name is now Ian' */
+  description?: string;
+}
+
+/**
+ * Undo capability descriptor.
+ * Present only if executor supports undo for this action.
+ */
+export interface ExecutionUndoCapability {
+  /** ISO 8601 deadline — server-authoritative */
+  availableUntil: string;
+  /** Executor dispatch key, e.g. 'profile.update' */
+  kind: string;
 }
 
 /**
@@ -32,8 +67,15 @@ export interface ExecutionArtifactStatus {
  */
 export interface ExecutionResultData {
   actionId: string;
-  status: 'success' | 'failed';
+  /** Execution row ID — required for undo endpoint dispatch */
+  executionId: string;
+  /** Resolved from ExecutionState — single authority (INV-1) */
+  state: 'completed' | 'failed';
   artifacts: ExecutionArtifactStatus[];
+  /** Structured summary for generic UI rendering (executor-provided) */
+  summary: ExecutionResultSummary;
+  /** Undo capability — present only if executor supports undo. Payload is server-side only (INV-3). */
+  undo?: ExecutionUndoCapability; // { availableUntil, kind }
 }
 
 /**
@@ -51,3 +93,30 @@ export interface ExecutionResultDataPart {
   type: 'data-execution-result';
   data: ExecutionResultData;
 }
+
+/**
+ * Undo result data payload.
+ * Returned by POST /api/executions/:id/undo.
+ *
+ * AUDIT MODEL (INV-2): Original execution row stays `completed`.
+ * Undo creates a second row with `undo_of` reference.
+ * Two audit events: action + revert, never mutation.
+ */
+export interface UndoResultData {
+  /** Links back to original action */
+  actionId: string;
+  /** Original execution row ID */
+  executionId: string;
+  /** New undo audit row ID (append-only, INV-2) */
+  undoExecutionId: string;
+  status: 'success' | 'failed';
+  error?: string;
+}
+
+/**
+ * Undo result data part (wire format).
+ */
+export interface UndoResultDataPart {
+  type: 'data-undo-result';
+  data: UndoResultData;
+}

package/src/message-parts/index.ts

@@ -45,9 +45,13 @@ export type {
 // Execution result types
 export type {
   ExecutionArtifactStatus,
+  ExecutionResultSummary,
+  ExecutionUndoCapability,
   ExecutionResultData,
   ExecutionResultPart,
   ExecutionResultDataPart,
+  UndoResultData,
+  UndoResultDataPart,
 } from './execution'
 
 // Lifecycle types (Phase 1 streaming)

package/src/message-parts/wire.ts

@@ -18,7 +18,12 @@ import type {
   ConfirmationResponseData,
   ConfirmationResponseDataPart,
 } from './confirmation'
-import type { ExecutionResultData, ExecutionResultDataPart } from './execution'
+import type {
+  ExecutionResultData,
+  ExecutionResultDataPart,
+  UndoResultData,
+  UndoResultDataPart,
+} from './execution'
 import type {
   MessageStartDataPart,
   MessageCompleteDataPart,
@@ -124,6 +129,25 @@ export const WireSurfaceBuilder = {
     }
   },
 
+  /**
+   * Build an undo result data part for streaming.
+   * Reports the outcome of an undo operation.
+   *
+   * INVARIANTS:
+   * - actionId must match the original executed action
+   * - Original execution row stays immutable (INV-2 append-only)
+   * - undoExecutionId references the new undo audit row
+   *
+   * @param data - Undo result data
+   * @returns Wire-format undo result part ready for stream
+   */
+  undoResult(data: UndoResultData): UndoResultDataPart {
+    return {
+      type: 'data-undo-result',
+      data,
+    }
+  },
+
   // =========================================================================
   // Message Lifecycle Events (Phase 1)
   // =========================================================================

package/src/usage/execution-types.ts

@@ -0,0 +1,37 @@
+/**
+ * Runtime Execution Telemetry Types
+ * One execution = one user message -> full assistant response (including tool loops).
+ * See PRD-00200 for design rationale and invariants.
+ */
+
+import type { ChatRuntimeProfile } from '../chat/runtime-profile'
+
+export type ExecutionFailureReason =
+  | 'tool_error'
+  | 'timeout'
+  | 'model_error'
+  | 'budget_exceeded'
+  | 'client_disconnect'
+  | 'unknown'
+
+export interface RuntimeExecutionTelemetry {
+  executionId: string
+  orgId: string
+  chatId?: string
+  messageId?: string
+  profile: ChatRuntimeProfile
+  provider: string
+  model: string
+  stepCount: number
+  toolCallCount: number
+  tokensInput: number
+  tokensOutput: number
+  tokensTotal: number
+  costInputUsd: string   // 8 decimal places
+  costOutputUsd: string  // 8 decimal places
+  costTotalUsd: string   // 8 decimal places
+  durationMs: number
+  success: boolean
+  failureReason?: ExecutionFailureReason
+  createdAt: string // ISO 8601
+}