@company-semantics/contracts 0.78.0 → 0.80.0

package/package.json

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

package/src/index.ts

@@ -477,3 +477,16 @@ export type {
   UsageByUser,
   OrgUsageResponse,
 } from './usage/types'
+
+// Runtime execution telemetry types
+// @see PRD-00200 for design rationale
+export type {
+  ExecutionFailureReason,
+  RuntimeExecutionTelemetry,
+  // Aggregation response types (PRD-00201)
+  ProfileStats,
+  OrgExecutionSummary,
+  DailyExecutionStats,
+  ExecutionByUser,
+  ExecutionDetail,
+} from './usage/execution-types'

package/src/usage/execution-types.ts

@@ -0,0 +1,91 @@
+/**
+ * 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'
+
+// @vocabulary-exempt reason: telemetry row is a single DB-aligned record; splitting risks consumer breakage
+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
+}
+
+// --- Aggregation response types (PRD-00201) ---
+
+export interface ProfileStats {
+  executions: number
+  percentOfTotal: number
+  avgDurationMs: number
+  totalCostUsd: string
+  avgCostPerExecution: string
+  failureRate: number
+  avgStepCount: number
+  avgToolCallCount: number
+}
+
+export interface OrgExecutionSummary {
+  dateRange: { start: string; end: string }
+  totals: {
+    executions: number
+    tokens: number
+    costUsd: string
+    avgDurationMs: number
+  }
+  byProfile: Record<ChatRuntimeProfile, ProfileStats>
+}
+
+export interface DailyExecutionStats {
+  date: string // YYYY-MM-DD
+  executions: number
+  totalCostUsd: string
+  byProfile: Record<ChatRuntimeProfile, number>
+}
+
+export interface ExecutionByUser {
+  userId: string
+  email: string
+  executions: number
+  totalCostUsd: string
+  favoriteProfile: ChatRuntimeProfile
+}
+
+export interface ExecutionDetail {
+  execution: RuntimeExecutionTelemetry
+  llmCalls: Array<{
+    callId: string
+    model: string
+    provider: string
+    tokensInput: number
+    tokensOutput: number
+    costUsd: string
+    durationMs: number
+    toolCalls: number
+  }>
+}