@spottoai/types-package 1.0.2-beta.42 → 1.0.2-beta.421

package/dist/ai/index.d.ts

@@ -1,31 +1,44 @@
-export type AIResponseStatus = 'complete' | 'needs_clarification' | 'needs_more_metrics';
+/** Common AI interfaces shared between frontend and backend */
+import type { AIChatGroundingSummary, AIEnvironmentEvidenceMatch } from './grounding.js';
+import type { AIChatWorkspaceArtifact, AIChatWorkspaceArtifactDataMode, AIChatWorkspaceArtifactFailureReason, AIChatWorkspaceArtifactKind, AIChatWorkspaceArtifactPlacement } from './workspaceArtifacts.js';
+export * from './grounding.js';
+export * from './conversationHistory.js';
+export * from './workspaceArtifacts.js';
+export type AIResponseStatus = 'complete' | 'needsClarification' | 'needsMoreMetrics';
 export type RecommendationPillar = 'Cost Optimization' | 'Performance Efficiency' | 'Security' | 'Reliability' | 'Operational Excellence';
-export type RecommendationType = 'advisor' | 'custom' | 'ai_generated';
+export type RecommendationType = 'advisor' | 'custom' | 'aiGenerated';
 export interface RecommendationAction {
     action: 'fix';
-    recommendation_id: string;
+    recommendationId: string;
 }
 export interface AIRecommendation {
-    priority_rank: number;
+    priorityRank: number;
     pillar: RecommendationPillar;
     description: string;
     type: RecommendationType;
-    reference_ids: string[];
+    referenceIds: string[];
     actions: RecommendationAction[];
 }
 export interface StructuredAIResponse {
     status: AIResponseStatus;
-    clarification_request: string | null;
-    metrics_request: string[];
-    friendly_message: string;
+    clarificationRequest: string | null;
+    metricsRequest: string[];
+    friendlyMessage: string;
     recommendations: AIRecommendation[];
 }
 export interface PageContext {
     pageType: 'resource-detail' | 'recommendation-detail' | 'dashboard' | string;
+    pageId?: string;
+    tabName?: string;
+    companyId: string;
+    subscriptionIds?: string[];
+    cloudAccountId?: string;
+    resourceIds?: string[];
     resourceId?: string;
     recommendationId?: string;
-    subscriptionId?: string;
     pageUrl?: string;
+    uiState?: Record<string, unknown>;
+    contextHash?: string;
 }
 export interface AIMessage {
     role: 'user' | 'assistant';
@@ -34,4 +47,1297 @@ export interface AIMessage {
     structuredResponse?: StructuredAIResponse;
     responseId?: string;
 }
+export type AIChatMode = 'page' | 'workspace';
+export type AIChatResponseMode = 'fast' | 'thinking';
+export type AIChatResolvedResponseMode = AIChatResponseMode | 'adaptive';
+export type AIChatOutputContract = 'customerDecisionBrief';
+export interface AICustomerDecisionBriefOutput {
+    headline: string;
+    businessOutcomes: [string, string];
+    costOfDelay: [string, string];
+    decisionRequired: string;
+}
+export interface AICustomerDecisionBriefContractOutput {
+    contract: 'customerDecisionBrief';
+    value: AICustomerDecisionBriefOutput;
+}
+export type AIChatContractOutput = AICustomerDecisionBriefContractOutput;
+type AIWorkspaceScopePolicyOutcome = 'accepted' | 'intersected' | 'rejected';
+interface AIWorkspaceScopeAllAuthorizedRequest {
+    mode: 'allAuthorized';
+    companyIds?: never;
+    subscriptionIds?: never;
+    resourceIds?: never;
+    includeChildCompanies?: boolean;
+}
+type AIWorkspaceScopeExplicitIdentifiers = {
+    companyIds: string[];
+    subscriptionIds?: string[];
+    resourceIds?: string[];
+} | {
+    companyIds?: string[];
+    subscriptionIds: string[];
+    resourceIds?: string[];
+} | {
+    companyIds?: string[];
+    subscriptionIds?: string[];
+    resourceIds: string[];
+};
+type AIWorkspaceScopeExplicitRequest = {
+    mode: 'explicit';
+    includeChildCompanies?: boolean;
+} & AIWorkspaceScopeExplicitIdentifiers;
+export type AIWorkspaceScopeRequest = AIWorkspaceScopeAllAuthorizedRequest | AIWorkspaceScopeExplicitRequest;
+export interface AIResolvedWorkspaceScope {
+    companyIds: string[];
+    subscriptionIds: string[];
+    resourceIds: string[];
+    policyOutcome: AIWorkspaceScopePolicyOutcome;
+    rejectedCompanyIds?: string[];
+    rejectedSubscriptionIds?: string[];
+    rejectedResourceIds?: string[];
+}
+export type AIChatSkillId = string;
+export type AIChatDomain = 'cost' | 'performance' | 'security' | 'reliability' | 'governance' | 'operations' | 'general';
+export type AIChatIntentLabel = 'askSummary' | 'investigateCost' | 'investigateSecurity' | 'investigateReliability' | 'investigateGovernance' | 'executeAction' | 'explainRecommendation' | 'unknown';
+export type AIChatComplexity = 'simple' | 'standard' | 'complex';
+export interface AIChatClassificationIntent {
+    label: AIChatIntentLabel;
+    confidence: number;
+}
+export interface AIChatClassificationResult {
+    version: string;
+    intents: AIChatClassificationIntent[];
+    complexity: AIChatComplexity;
+    requiresTools: boolean;
+    suggestedSkillPackIds: AIChatSkillId[];
+}
+type AIChatRoutingReasonCode = 'AI_SKILL_CLASSIFIER_SELECTED' | 'AI_SKILL_CLASSIFIER_LOW_CONFIDENCE' | 'AI_SKILL_FALLBACK_DEFAULT';
+type AIChatScopeReasonCode = 'AI_SCOPE_EMPTY_REQUEST' | 'AI_SCOPE_EMPTY_EFFECTIVE' | 'AI_SCOPE_REDUCED_UNAUTHORIZED_MEMBERS' | 'AI_SCOPE_INVALID';
+type AIChatApprovalReasonCode = 'AI_MUTATION_CONFIRMATION_REQUIRED' | 'AI_MUTATION_CONFIRMATION_EXPIRED' | 'AI_MUTATION_CONFIRMATION_REJECTED';
+type AIChatDegradedReasonCode = 'AI_MCP_PROVIDER_UNAVAILABLE' | 'AI_MCP_PROVIDER_TIMEOUT' | 'AI_MCP_PARTIAL_FAILURE' | 'AI_TOOL_TIMEOUT' | 'AI_TOOL_PARTIAL_FAILURE'
+/** A tool result was withheld or summarised because it exceeded the model-visible size budget; no tool failed. */
+ | 'AI_TOOL_RESULT_COMPACTED'
+/** An analysis role (specialist, critic, synthesis) ran past its model-call timeout; no tool failed. */
+ | 'AI_SPECIALIST_TIMEOUT'
+/** The interactive analysis turn budget was exhausted; the answer was finished from the results so far. */
+ | 'AI_ANALYSIS_BUDGET_EXHAUSTED'
+/** The model refused the request as larger than its context; the turn retried with a compacted request. */
+ | 'AI_MODEL_CONTEXT_EXCEEDED'
+/** The provider failed while generating (Azure "model produced invalid content" / server_error); retried with a compacted request. */
+ | 'AI_MODEL_INVALID_OUTPUT'
+/** One model call of the generic loop ran past its wall-clock timeout; retried with a compacted request. */
+ | 'AI_MODEL_CALL_TIMEOUT' | 'AI_DEGRADED_NO_PATH';
+type AIChatOrchestrationReasonCode = 'AI_ROUTE_GENERIC' | 'AI_ROUTE_ANALYSIS' | 'AI_ROUTE_GENERIC_FALLBACK_MEDIUM_CONFIDENCE' | 'AI_ROUTE_CLARIFY_LOW_CONFIDENCE' | 'AI_PLAN_CREATED' | 'AI_PLAN_NO_ELIGIBLE_SPECIALISTS' | 'AI_SPECIALIST_STARTED' | 'AI_SPECIALIST_COMPLETED' | 'AI_SPECIALIST_FAILED' | 'AI_SYNTHESIS_COMPLETED' | 'AI_SYNTHESIS_CONFLICT_DETECTED' | 'AI_CRITIC_SKIPPED' | 'AI_CRITIC_PASS' | 'AI_CRITIC_REVISE' | 'AI_REVISION_LOOP_LIMIT_REACHED';
+export type AIChatReasonCode = AIChatRoutingReasonCode | AIChatScopeReasonCode | AIChatApprovalReasonCode | AIChatDegradedReasonCode | AIChatOrchestrationReasonCode;
+export type AIRouteReasonCode = 'route.low_confidence' | 'route.page_context_sufficient' | 'route.cross_domain_analysis_required' | 'route.retrieval_required' | 'route.missing_required_inputs' | `route.${string}`;
+export type AIToolReasonCode = 'tool.not_authorized' | 'tool.out_of_scope' | 'tool.missing_required_arguments' | 'tool.requires_confirmation' | 'tool.not_applicable_to_page' | `tool.${string}`;
+export type AIFreshnessReasonCode = 'freshness.current' | 'freshness.stale_source' | 'freshness.partial_data' | 'freshness.refresh_in_progress' | `freshness.${string}`;
+export type AISchemaReasonCode = 'schema.parse_failed' | 'schema.validation_failed' | 'schema.missing_required_field' | 'schema.invalid_enum_value' | `schema.${string}`;
+export type AIReasonCode = AIRouteReasonCode | AIToolReasonCode | AIFreshnessReasonCode | AISchemaReasonCode;
+export interface AISchemaIssue {
+    reasonCode: AISchemaReasonCode;
+    fieldPath?: string;
+    detail?: string;
+}
+export interface AIChatSkillClassificationCandidate {
+    skillId: AIChatSkillId;
+    score: number;
+    reasonCodes: AIChatReasonCode[];
+}
+export interface AIChatSkillClassificationResult {
+    classifierVersion: string;
+    selectedSkillPackId?: AIChatSkillId;
+    candidates: AIChatSkillClassificationCandidate[];
+    reasonCodes?: AIChatReasonCode[];
+}
+export type AIChatRoutingStrategy = 'singleAgent' | 'fanout';
+export interface AIChatRoutingSubtaskPlan {
+    subtaskId: string;
+    domain: AIChatDomain;
+    title: string;
+    skillPackId?: AIChatSkillId;
+}
+export interface AIChatRoutingDecision {
+    strategy: AIChatRoutingStrategy;
+    selectedMode: AIChatMode;
+    selectedSkillPackIds: AIChatSkillId[];
+    reasonCodes: AIChatReasonCode[];
+    subtasks?: AIChatRoutingSubtaskPlan[];
+}
+export type AIChatSkillRouteSource = 'auto' | 'default';
+export type AIChatSkillRoutePolicyOutcome = 'accepted' | 'fallback' | 'rejected';
+export interface AIChatSkillRouteTarget {
+    skillPackId: AIChatSkillId;
+    skillPackVersion: string;
+    routeSource: AIChatSkillRouteSource;
+    policyOutcome: AIChatSkillRoutePolicyOutcome;
+}
+export interface AIChatSkillRoutingFallback {
+    fromSkillPackId?: AIChatSkillId;
+    toRoute: AIChatSkillRouteTarget;
+    reasonCode: AIChatReasonCode;
+}
+export interface AIChatSkillRoutingDecision {
+    selectedSkillPackId?: AIChatSkillId;
+    route: AIChatSkillRouteTarget;
+    reasonCodes: AIChatReasonCode[];
+    fallback?: AIChatSkillRoutingFallback;
+}
+export type AIChatClassificationMetadata = AIChatClassificationResult | AIChatSkillClassificationResult;
+export type AIChatRoutingMetadata = AIChatRoutingDecision | AIChatSkillRoutingDecision;
+export type AIEntityType = 'company' | 'subscription' | 'resource' | 'recommendation' | string;
+export interface AIEntityRef {
+    id: string;
+    label?: string;
+    type: AIEntityType;
+}
+export type AIPageIntentHint = 'thisPage' | 'theseRows' | 'thisResource' | 'crossPage';
+export interface AIPageFreshness {
+    capturedAt: string;
+    dataAsOf?: string;
+    isStale?: boolean;
+    stalenessReason?: string;
+    reasonCode?: AIFreshnessReasonCode;
+}
+export interface AIChatPageSnapshot {
+    pageType: string;
+    pageId?: string;
+    pageUrl?: string;
+    companyId?: string;
+    title?: string;
+    summary?: string;
+    routePath?: string;
+    tab?: string;
+    view?: string;
+    selectedEntities: AIEntityRef[];
+    scopeLabels: {
+        company?: string;
+        subscriptions?: string[];
+        resources?: string[];
+    };
+    uiState?: Record<string, unknown>;
+    loadedDataHints?: string[];
+    intentHints?: AIPageIntentHint[];
+    freshness?: AIPageFreshness;
+}
+export type AIChatMutationMode = 'read' | 'writeRequiresApproval' | 'writeBlocked';
+export interface AIChatToolAffordanceEntry {
+    toolName: string;
+    title?: string;
+    reasonCode?: AIReasonCode;
+    reason?: string;
+    missingArgs?: string[];
+    requiresApproval?: boolean;
+}
+export interface AIChatBlockedToolAffordanceEntry extends AIChatToolAffordanceEntry {
+    blockReasonCode?: AIReasonCode;
+    blockReason?: string;
+}
+export interface AIChatToolAffordanceSnapshot {
+    availableTools: AIChatToolAffordanceEntry[];
+    applicableTools: AIChatToolAffordanceEntry[];
+    deferredTools: AIChatToolAffordanceEntry[];
+    writeTools: AIChatToolAffordanceEntry[];
+    blockedTools: AIChatBlockedToolAffordanceEntry[];
+}
+/**
+ * Canonical route taxonomy shared by UI, API, and persisted artifacts.
+ * These lowerCamelCase values are the only target-state route names.
+ */
+export type AIOrchestrationPath = 'clarify' | 'pageAnswer' | 'genericToolLoop' | 'analysisWithRetrieval';
+export interface AIRouterDomainScore {
+    name: 'cost' | 'performance' | 'reliability' | 'security' | 'operations' | string;
+    confidence: number;
+}
+export interface AIRouterOutput {
+    path: AIOrchestrationPath;
+    confidence: number;
+    entitiesInFocus: string[];
+    domains: AIRouterDomainScore[];
+    needsRetrieval: boolean;
+    missingInputs: string[];
+    reasonCode?: AIRouteReasonCode;
+    whyThisPath?: string;
+    complexity?: AIChatComplexity;
+}
+export type AIPlannerPriority = 'P1' | 'P2' | 'P3';
+export interface AIPlannerWorkItem {
+    workItemId: string;
+    domain: string;
+    task: string;
+    priority: AIPlannerPriority;
+}
+/**
+ * Filter intent for a planned retrieval step: when the step's result comes back capped or
+ * withheld, the retrieval executor issues `query_tool_result` over the held complete result with
+ * this query (same grammar as the tool, without `callId`).
+ */
+export interface AIRetrievalStepQuery {
+    path?: string;
+    where?: Array<{
+        field: string;
+        op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startsWith' | 'in' | 'exists';
+        value?: unknown;
+    }>;
+    search?: string;
+    fields?: string[];
+    sort?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    limit?: number;
+    offset?: number;
+}
+export interface AIPlannerRetrievalStep {
+    retrievalId: string;
+    toolName: string;
+    purpose: string;
+    arguments: Record<string, unknown>;
+    required: boolean;
+    query?: AIRetrievalStepQuery;
+}
+export interface AIPlannerOutput {
+    investigationGoal: string;
+    decisionToSupport: string;
+    workItems: AIPlannerWorkItem[];
+    retrievalPlan: AIPlannerRetrievalStep[];
+    successCriteria: string[];
+}
+export type AICitationSourceType = 'toolResult' | 'pageData' | 'document' | 'metric' | 'log' | string;
+export interface AIEvidencePayloadMeta {
+    payloadShape?: 'summary' | 'compact' | 'full';
+    truncated?: boolean;
+    truncationReasonCode?: AIReasonCode;
+    estimatedItemCount?: number;
+}
+export interface AIChatCitation {
+    citationId: string;
+    sourceType: AICitationSourceType;
+    title: string;
+    locator: string;
+    snippet?: string;
+    toolName?: string;
+    retrievedAt: string;
+}
+export interface AIChatAssistantProfileSummary {
+    profileId: string;
+    title: string;
+    description?: string;
+    mode?: AIChatMode;
+    selectedSkillPackId?: AIChatSkillId;
+    capabilityLabels: string[];
+    allowsMutations: boolean;
+    allowLearnMcp?: boolean;
+}
+export interface AIChatToolPolicySummary {
+    mode: 'readOnly' | 'approvalRequired' | 'mixed';
+    availableToolCount?: number;
+    mutationToolCount?: number;
+    approvalRequired: boolean;
+    summary: string;
+}
+export type AIChatRetrievalSourceType = 'operational' | 'memory' | 'knowledge' | 'external' | 'environment';
+export interface AIChatSourcePolicySummary {
+    sourceTypes: AIChatRetrievalSourceType[];
+    externalSourceEnabled: boolean;
+    summary: string;
+}
+export type AIChatQueueId = string;
+export interface AIChatQueuedPromptState {
+    queueId: AIChatQueueId;
+    text: string;
+    status: 'queued' | 'sending' | 'cancelled' | 'completed' | 'failed';
+    queuedAt: string;
+    replacedPromptId?: AIChatQueueId;
+}
+export interface AIChatMemorySourceSummary {
+    conversationId: string;
+    title?: string;
+    matchedAt?: string;
+}
+export interface AIChatMemoryMatch {
+    memoryId: string;
+    source: AIChatMemorySourceSummary;
+    score: number;
+    summary: string;
+    citationIds?: string[];
+}
+export interface AIChatEvidenceGroup {
+    groupId: string;
+    title: string;
+    sourceType: AIChatRetrievalSourceType;
+    citationIds: string[];
+    itemCount?: number;
+}
+export type AIChatNoCitationReasonCode = 'citation.not_required' | 'citation.insufficient_evidence' | 'citation.source_unavailable' | `citation.${string}`;
+export interface AIChatCitationCoverage {
+    required: boolean;
+    satisfied: boolean;
+    citationCount: number;
+    noCitationReasonCode?: AIChatNoCitationReasonCode;
+}
+export interface AIChatEvidenceCoverage {
+    sourceTypes: AIChatRetrievalSourceType[];
+    evidenceGroups: AIChatEvidenceGroup[];
+    citationCoverage: AIChatCitationCoverage;
+    memoryMatches?: AIChatMemoryMatch[];
+    environmentMatches?: AIEnvironmentEvidenceMatch[];
+}
+export interface AIChatRuntimeEvalSignals {
+    observedLeadSpecialist?: string;
+    observedSkillIds: string[];
+    observedSpecialistDomains: string[];
+    observedToolNames: string[];
+    observedEvidenceKinds: string[];
+    observedWorkflowOutcomes: string[];
+    retrievalExecuted: boolean;
+    followupPassExecuted: boolean;
+    evidenceEntryCount: number;
+    evidenceGapCount: number;
+    sourceTypes: AIChatRetrievalSourceType[];
+    memoryMatchCount: number;
+    recommendationDetected: boolean;
+    tradeoffDiscussionDetected: boolean;
+    uncertaintyLanguageDetected: boolean;
+    clarificationObserved: boolean;
+    contextSufficientForAnswering: boolean;
+}
+export interface AIChatReconnectState {
+    status: 'connected' | 'reconnecting' | 'resumed' | 'restarted' | 'degraded';
+    message?: string;
+    resumedRunId?: string;
+    resumedTurnId?: string;
+    updatedAt: string;
+}
+export interface AIChatDegradedState {
+    degraded: boolean;
+    reasonCodes?: AIChatReasonCode[];
+    summary?: string;
+}
+export type AIChatCollaborationStatus = 'spawned' | 'running' | 'completed' | 'cancelled' | 'degraded' | 'failed';
+export type AIChatCollaborationRole = 'planner' | 'retrieval' | 'specialist' | 'critic' | 'subAgent' | 'synthesis';
+export interface AIChatCollaborationItem {
+    collaborationId: string;
+    parentCollaborationId?: string;
+    title: string;
+    role: AIChatCollaborationRole;
+    status: AIChatCollaborationStatus;
+    startedAt?: string;
+    updatedAt: string;
+    endedAt?: string;
+    summary?: string;
+    citationIds?: string[];
+    reasonCode?: AIReasonCode;
+}
+export interface AIChatCollaborationRun {
+    runId: string;
+    status: AIChatCollaborationStatus;
+    items: AIChatCollaborationItem[];
+    startedAt: string;
+    updatedAt: string;
+    endedAt?: string;
+    summary?: string;
+}
+export interface AIChatToolExecutionError {
+    message: string;
+    reasonCode?: AIReasonCode;
+    retryable?: boolean;
+    details?: unknown;
+}
+export interface AIChatToolExecutionResult {
+    ok: boolean;
+    data?: unknown;
+    error?: AIChatToolExecutionError;
+    truncated?: boolean;
+}
+export interface AIToolError extends AIChatToolExecutionError {
+    code: string;
+}
+export interface AIToolResult extends AIChatToolExecutionResult {
+    toolName: string;
+    error?: AIToolError;
+    payloadMeta?: AIEvidencePayloadMeta;
+}
+export interface AIToolCall {
+    callId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+}
+export interface AIRetrievalExecutionStep {
+    retrievalId: string;
+    toolName: string;
+    argsHash: string;
+    startedAt: string;
+    endedAt?: string;
+    status: 'ok' | 'error' | 'skipped';
+    summary?: string;
+    callId?: string;
+    error?: AIToolError;
+    citationIds: string[];
+}
+export interface AIEvidenceEntry {
+    evidenceId: string;
+    sourceTool: string;
+    argsHash: string;
+    timestamp: string;
+    status: 'ok' | 'error' | 'partial';
+    summary: string;
+    citationIds: string[];
+    domains?: string[];
+    payloadMeta?: AIEvidencePayloadMeta;
+}
+export interface AIEvidenceGap {
+    gapId: string;
+    description: string;
+    blocking: boolean;
+    suggestedFollowup?: string;
+}
+export interface AIEvidenceLabelMap {
+    companies?: Record<string, string>;
+    subscriptions?: Record<string, string>;
+    resources?: Record<string, string>;
+    recommendations?: Record<string, string>;
+}
+export interface AIEvidenceBundle {
+    bundleId: string;
+    entries: AIEvidenceEntry[];
+    citations: AIChatCitation[];
+    labelMap: AIEvidenceLabelMap;
+    gaps: AIEvidenceGap[];
+    createdAt: string;
+}
+export interface AIRetrievalExecution {
+    retrievalPlan: AIPlannerRetrievalStep[];
+    executionSteps: AIRetrievalExecutionStep[];
+    followupPassExecuted: boolean;
+    evidenceBundle: AIEvidenceBundle;
+}
+export interface AISpecialistAction {
+    title: string;
+    risk: 'low' | 'medium' | 'high';
+    effort: 'low' | 'medium' | 'high';
+}
+export interface AISpecialistTradeoff {
+    withDomain: string;
+    summary: string;
+}
+export interface AISpecialistOutput {
+    specialistId: string;
+    domain: string;
+    topFindings: string[];
+    evidence: string[];
+    actions: AISpecialistAction[];
+    tradeoffs: AISpecialistTradeoff[];
+    assumptions: string[];
+    dataGaps: string[];
+    followupRetrieval: AIPlannerRetrievalStep[];
+    confidence: number;
+}
+export interface AISynthesisOutput {
+    recommendedPlan: string;
+    alternatives: string[];
+    keyActions: string[];
+    risks: string[];
+    evidenceTrace: string[];
+    unresolvedGaps: string[];
+    confidence: number;
+    disagreement: boolean;
+    customerDecisionBrief?: AICustomerDecisionBriefOutput;
+}
+export interface AICriticOutput {
+    verdict: 'PASS' | 'REVISE';
+    confidence: number;
+    reason: string;
+    issues: string[];
+    rerunAgents: string[];
+}
+export type AIHtmlLitePolicy = 'htmlLite';
+export interface AIFormatterOutput {
+    policy: AIHtmlLitePolicy;
+    answerHtml: string;
+    answerText: string;
+    citations: AIChatCitation[];
+    labelFirstApplied: boolean;
+    normalizationHash: string;
+}
+export type AIChatTurnPhase = 'intake' | 'contextResolved' | 'skillResolved' | 'planning' | 'executing' | 'awaitingApproval' | 'formatting' | 'finalizing' | 'completed' | 'errored' | 'cancelled';
+export type AIChatTurnStatus = 'running' | 'waiting' | 'completed' | 'errored' | 'cancelled';
+export type AIChatRunStatus = 'queued' | 'running' | 'paused' | 'resuming' | 'completed' | 'failed' | 'cancelled';
+export type AIChatRunPauseReason = 'approvalRequired' | 'toolInputRequired' | 'stalled' | 'reconnectRequired' | 'policyIntervention' | `pause.${string}`;
+export type AIChatRunResumeReason = 'approvalDecision' | 'reconnect' | 'manual' | 'retry' | `resume.${string}`;
+export interface AIChatRunState {
+    runId: string;
+    status: AIChatRunStatus;
+    updatedAt: string;
+    startedAt?: string;
+    pausedAt?: string;
+    resumedAt?: string;
+    completedAt?: string;
+    pauseReason?: AIChatRunPauseReason;
+    resumeReason?: AIChatRunResumeReason;
+    terminalReasonCode?: AIReasonCode;
+    terminalMessage?: string;
+}
+export interface AIChatPausedRunInfo {
+    runId: string;
+    pauseReason: AIChatRunPauseReason;
+    pausedAt: string;
+    approvalChallengeId?: string;
+    pendingApprovals?: AIChatApprovalRecord[];
+}
+export interface AIChatTurnState {
+    runId: string;
+    turnId: string;
+    phase: AIChatTurnPhase;
+    status: AIChatTurnStatus;
+    updatedAt: string;
+    responseMode?: AIChatResolvedResponseMode;
+    path?: AIOrchestrationPath;
+    analysisConfidence?: number;
+    selectedSkillPackId?: AIChatSkillId;
+}
+export type AIChatCommentaryKind = 'preamble' | 'progress' | 'finding' | 'handoff';
+export interface AIChatCommentaryEntry {
+    commentaryId: string;
+    kind: AIChatCommentaryKind;
+    text: string;
+    timestamp: string;
+    phase?: AIChatTurnPhase;
+    progressId?: string;
+}
+export type AIChatPlanStepStatus = 'pending' | 'running' | 'completed' | 'blocked';
+export interface AIChatPlanStep {
+    stepId: string;
+    label: string;
+    status: AIChatPlanStepStatus;
+    summary?: string;
+    domain?: AIChatDomain;
+}
+export interface AIChatPlanSnapshot {
+    planId: string;
+    goal?: string;
+    updatedAt: string;
+    steps: AIChatPlanStep[];
+}
+export type AIChatProgressCategory = 'context' | 'routing' | 'planning' | 'retrieval' | 'toolExecution' | 'subtask' | 'approval' | 'formatting' | 'finalization';
+export type AIChatProgressStatus = 'pending' | 'running' | 'completed' | 'blocked' | 'failed' | 'skipped';
+export interface AIChatProgressEntry {
+    progressId: string;
+    category: AIChatProgressCategory;
+    status: AIChatProgressStatus;
+    title: string;
+    detail?: string;
+    timestamp: string;
+    phase?: AIChatTurnPhase;
+    stepId?: string;
+    callId?: string;
+    subtaskId?: string;
+    collaborationId?: string;
+    reasonCode?: AIReasonCode;
+}
+export type AIChatApprovalState = 'pending' | 'approved' | 'rejected' | 'consumed' | 'expired' | 'completed' | 'failed';
+export interface AIChatApprovalActionPreview {
+    /** Normalized tool arguments as the server will execute them; credentials redacted, recipients and destinations visible. */
+    arguments: Record<string, unknown>;
+    /** The exact payload hash bound to this challenge; the server matches it before executing. */
+    payloadHash?: string;
+    /** True when the arguments were too large to show in full. */
+    truncated?: boolean;
+}
+export interface AIChatApprovalRecord {
+    runId: string;
+    challengeId: string;
+    state: AIChatApprovalState;
+    actionSummary: string;
+    actionType?: string;
+    /** What the approver is actually approving. Present on approvalRequired/runPaused events. */
+    actionPreview?: AIChatApprovalActionPreview;
+    requiredRole: string;
+    riskLevel: 'low' | 'medium' | 'high';
+    idempotencyKey: string;
+    createdAt: string;
+    decidedAt?: string;
+    expiresAt?: string;
+    updatedAt?: string;
+    detail?: string;
+}
+export interface AIChatSkillPackDescriptor {
+    skillId: AIChatSkillId;
+    version: string;
+    title: string;
+    description?: string;
+    domains: AIChatDomain[];
+    supportedModes: AIChatMode[];
+    intentSignals: string[];
+    toolPolicy: {
+        allowedToolNames?: string[];
+        blockedToolNames?: string[];
+        allowMcpProviders?: boolean;
+        allowedMcpCapabilities?: string[];
+        blockedMcpCapabilities?: string[];
+        allowMutations: boolean;
+    };
+    approvalPolicy: {
+        required: boolean;
+        requiredRole?: string;
+        defaultRiskLevel?: 'low' | 'medium' | 'high';
+    };
+    uxHints?: {
+        commentaryStyle?: 'compact' | 'standard';
+        showPlanByDefault?: boolean;
+        preferredProgressCategories?: AIChatProgressCategory[];
+    };
+    fallbackPath?: AIOrchestrationPath;
+    enabled: boolean;
+}
+export interface AIChatToolDescriptor {
+    toolName: string;
+    source: 'internal' | 'mcp' | `mcp:${string}` | string;
+    retrievalSourceType?: AIChatRetrievalSourceType;
+    providerId?: string;
+    providerTitle?: string;
+    providerCapabilities?: string[];
+    title: string;
+    description: string;
+    domains?: AIChatDomain[];
+    mutationMode: AIChatMutationMode;
+    approvalRequirement?: {
+        required: boolean;
+        requiredRole?: string;
+        riskLevel?: 'low' | 'medium' | 'high';
+    };
+    scopeHints?: {
+        chatModes?: AIChatMode[];
+        requiresWorkspaceScope?: boolean;
+        pageTypes?: string[];
+    };
+    evidenceKinds?: string[];
+    resultShape?: string;
+    usageHints?: string[];
+    avoidWhen?: string[];
+}
+export interface AIChatTurnSnapshot {
+    run: AIChatRunState;
+    turn: AIChatTurnState;
+    selectedSkillPack?: AIChatSkillPackDescriptor;
+    assistantProfileSummary?: AIChatAssistantProfileSummary;
+    toolPolicySummary?: AIChatToolPolicySummary;
+    sourcePolicySummary?: AIChatSourcePolicySummary;
+    queuedPrompt?: AIChatQueuedPromptState;
+    plan?: AIChatPlanSnapshot;
+    commentaryEntries?: AIChatCommentaryEntry[];
+    progressEntries?: AIChatProgressEntry[];
+    approvalRecords?: AIChatApprovalRecord[];
+    toolDescriptors?: AIChatToolDescriptor[];
+    evidenceCoverage?: AIChatEvidenceCoverage;
+    reconnectState?: AIChatReconnectState;
+    degradedState?: AIChatDegradedState;
+    collaborationRun?: AIChatCollaborationRun;
+}
+export interface AIChatFinalSnapshot {
+    /**
+     * Authoritative final turn state. Additional stage outputs are additive sidecars.
+     */
+    run: AIChatRunState;
+    turnSnapshot: AIChatTurnSnapshot;
+    pageSnapshot?: AIChatPageSnapshot;
+    toolAffordanceSnapshot?: AIChatToolAffordanceSnapshot;
+    router?: AIRouterOutput;
+    planner?: AIPlannerOutput;
+    retrieval?: AIRetrievalExecution;
+    specialistOutputs?: AISpecialistOutput[];
+    synthesis?: AISynthesisOutput;
+    critic?: AICriticOutput;
+    formatter?: AIFormatterOutput;
+    assistantProfileSummary?: AIChatAssistantProfileSummary;
+    toolPolicySummary?: AIChatToolPolicySummary;
+    sourcePolicySummary?: AIChatSourcePolicySummary;
+    queuedPrompt?: AIChatQueuedPromptState;
+    evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
+    reconnectState?: AIChatReconnectState;
+    degradedState?: AIChatDegradedState;
+    collaborationRun?: AIChatCollaborationRun;
+    runtimeEvalSignals?: AIChatRuntimeEvalSignals;
+}
+export interface AIChatAuditArtifact {
+    conversationId: string;
+    runId: string;
+    turnId: string;
+    createdAt: string;
+    turnSnapshot: AIChatTurnSnapshot;
+    snapshots?: {
+        pageSnapshot?: AIChatPageSnapshot;
+        toolAffordanceSnapshot?: AIChatToolAffordanceSnapshot;
+    };
+    router?: AIRouterOutput;
+    planner?: AIPlannerOutput;
+    retrieval?: AIRetrievalExecution;
+    specialists?: AISpecialistOutput[];
+    synthesis?: AISynthesisOutput;
+    critic?: AICriticOutput;
+    formatter?: AIFormatterOutput;
+    assistantProfileSummary?: AIChatAssistantProfileSummary;
+    toolPolicySummary?: AIChatToolPolicySummary;
+    sourcePolicySummary?: AIChatSourcePolicySummary;
+    queuedPrompt?: AIChatQueuedPromptState;
+    evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
+    reconnectState?: AIChatReconnectState;
+    degradedState?: AIChatDegradedState;
+    collaborationRun?: AIChatCollaborationRun;
+    analysisConfidence?: number;
+    runtimeEvalSignals?: AIChatRuntimeEvalSignals;
+}
+export interface AIChatApprovalDecision {
+    challengeId: string;
+    decision: 'approve' | 'reject';
+    idempotencyKey: string;
+    submittedAt?: string;
+}
+export interface AIChatRunResumeDirective {
+    reason: AIChatRunResumeReason;
+    note?: string;
+}
+export interface AIChatApprovalSubmissionRequest {
+    conversationId: string;
+    runId: string;
+    decision: AIChatApprovalDecision;
+    resume?: AIChatRunResumeDirective & {
+        mode?: 'immediate' | 'manual';
+    };
+}
+interface AIChatRequestBase {
+    conversationId?: string;
+    runId?: string;
+    contextHash?: string;
+    responseMode?: AIChatResponseMode;
+    queuedPrompt?: AIChatQueuedPromptState;
+    /**
+     * Live chat transport is streaming-only. Non-streaming requests are not part
+     * of the target shared contract.
+     */
+    stream: true;
+}
+interface AIChatRunStartRequestPage extends AIChatRequestBase {
+    action: 'start';
+    chatMode: 'page';
+    input: string;
+    pageContext: PageContext;
+    outputContract?: AIChatOutputContract;
+    workspaceScope?: never;
+    runId?: never;
+}
+interface AIChatRunStartRequestWorkspace extends AIChatRequestBase {
+    action: 'start';
+    chatMode: 'workspace';
+    input: string;
+    /**
+     * Workspace turns may still include page context when launched from a page,
+     * but pure workspace turns rely on workspaceScope alone.
+     */
+    pageContext?: PageContext;
+    outputContract?: never;
+    workspaceScope: AIWorkspaceScopeRequest;
+}
+export type AIChatRunStartRequest = AIChatRunStartRequestPage | AIChatRunStartRequestWorkspace;
+export interface AIChatRunResumeRequest extends AIChatRequestBase {
+    action: 'resume';
+    conversationId: string;
+    runId: string;
+    chatMode?: AIChatMode;
+    pageContext?: PageContext;
+    workspaceScope?: AIWorkspaceScopeRequest;
+    outputContract?: never;
+    input?: string;
+    approvalDecision?: AIChatApprovalDecision;
+    resume: AIChatRunResumeDirective;
+}
+export type AIChatRunRequest = AIChatRunStartRequest | AIChatRunResumeRequest;
+export type AIChatRequest = AIChatRunRequest;
+export interface AIConversationScopeMetadata {
+    chatMode?: AIChatMode;
+    resolvedWorkspaceScope?: AIResolvedWorkspaceScope;
+    selectedSkillPackIds?: AIChatSkillId[];
+}
+export interface AIConversationRoutingMetadata extends AIConversationScopeMetadata {
+    classification?: AIChatClassificationMetadata;
+    routing?: AIChatRoutingMetadata;
+}
+export interface AIConversationListItem extends AIConversationRoutingMetadata {
+    id: string;
+    summary?: string;
+    messageCount: number;
+    lastResponseTime?: Date | string;
+    pageUrl?: string;
+    pageType?: string;
+}
+export type AIChatConversationFeedback = 'ThumbsUp' | 'ThumbsDown';
+export interface AIChatConversationFeedbackUpdateRequest {
+    feedback: AIChatConversationFeedback | null;
+}
+export interface AIChatConversationFeedbackUpdateResponse {
+    conversationId: string;
+    feedback: AIChatConversationFeedback | null;
+    updatedAt: string;
+}
+/** Maximum length of the optional free-text comment attached to per-turn feedback. */
+export declare const AI_CHAT_TURN_FEEDBACK_COMMENT_MAX_LENGTH = 1000;
+/**
+ * Number of per-turn feedback records retained on a conversation. The conversation blob stays the
+ * authoritative record, so the newest records win once the bound is reached.
+ */
+export declare const AI_CHAT_TURN_FEEDBACK_MAX_RECORDS = 200;
+/**
+ * Durable per-question feedback for a single answered turn (review finding U-12).
+ *
+ * `turnId` is the public identifier used by the mutation endpoint and by the Portal, while
+ * `questionIndex` is the zero-based index of the user message the turn answered and `responseId`
+ * is retained as internal mapping metadata for transcript reconciliation.
+ */
+export interface AIChatTurnFeedback {
+    turnId: string;
+    questionIndex: number;
+    responseId?: string;
+    feedback: AIChatConversationFeedback | null;
+    comment?: string;
+    submittedAt: string;
+    updatedAt: string;
+}
+export interface AIChatTurnFeedbackUpdateRequest {
+    feedback: AIChatConversationFeedback | null;
+    comment?: string;
+}
+export interface AIChatTurnFeedbackUpdateResponse {
+    conversationId: string;
+    turnId: string;
+    feedback: AIChatConversationFeedback | null;
+    comment?: string;
+    updatedAt: string;
+}
+export interface AIChatUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface AIChatTerminalSnapshot {
+    conversationId: string;
+    runId: string;
+    run: AIChatRunState;
+    turnSnapshot: AIChatTurnSnapshot;
+    finalSnapshot?: AIChatFinalSnapshot;
+    auditArtifact?: AIChatAuditArtifact;
+    runtimeEvalSignals?: AIChatRuntimeEvalSignals;
+    resolvedResponseMode?: AIChatResolvedResponseMode;
+    chatMode?: AIChatMode;
+    resolvedScope?: AIResolvedWorkspaceScope;
+    classification?: AIChatClassificationMetadata;
+    routing?: AIChatRoutingMetadata;
+    structuredResponse?: StructuredAIResponse;
+    contractOutput?: AIChatContractOutput;
+    usage?: AIChatUsage;
+    answer?: string;
+    completionReason?: string;
+    citations?: AIChatCitation[];
+    assistantProfileSummary?: AIChatAssistantProfileSummary;
+    toolPolicySummary?: AIChatToolPolicySummary;
+    sourcePolicySummary?: AIChatSourcePolicySummary;
+    queuedPrompt?: AIChatQueuedPromptState;
+    evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
+    reconnectState?: AIChatReconnectState;
+    degradedState?: AIChatDegradedState;
+    collaborationRun?: AIChatCollaborationRun;
+    /** Optional while pre-workspace producers and consumers drain. */
+    workspaceArtifacts?: AIChatWorkspaceArtifact[];
+}
+/**
+ * Canonical lowerCamelCase SSE event vocabulary for the target chat runtime.
+ */
+export type AIChatCanonicalStreamEventName = 'runStarted' | 'runStatus' | 'runPaused' | 'runResumed' | 'runCompleted' | 'runFailed' | 'scopeResolved' | 'pageSnapshotBuilt' | 'toolAffordanceBuilt' | 'routingStarted' | 'routingCompleted' | 'planCreated' | 'planUpdated' | 'commentary' | 'progressUpdate' | 'guardrailTriggered' | 'toolCall' | 'toolResult' | 'toolError' | 'approvalRequired' | 'approvalStateChanged' | 'formatterStarted' | 'formatterCompleted' | 'message' | 'answerDraft' | 'answerDraftReset' | 'citation' | 'artifactStarted' | 'artifactCompleted' | 'artifactFailed' | 'error' | 'ping' | 'turnDiagnostics';
+/**
+ * Legacy terminal event accepted only during the runCompleted migration.
+ * New producers and protocol assertions must use AIChatCanonicalStreamEventName.
+ */
+export type AIChatCompatibilityStreamEventName = 'done';
+export type AIChatStreamEventName = AIChatCanonicalStreamEventName | AIChatCompatibilityStreamEventName;
+export interface AIChatStreamEventBase {
+    event: AIChatStreamEventName;
+    sequence: number;
+    conversationId: string;
+    runId: string;
+    turnId: string;
+    timestamp: string;
+}
+export interface AIChatRunStartedEvent extends AIChatStreamEventBase {
+    event: 'runStarted';
+    run: AIChatRunState;
+    chatMode: AIChatMode;
+    requestedScope?: AIWorkspaceScopeRequest;
+}
+export interface AIChatRunStatusEvent extends AIChatStreamEventBase {
+    event: 'runStatus';
+    run: AIChatRunState;
+    phase?: AIChatTurnPhase;
+}
+export interface AIChatRunPausedEvent extends AIChatStreamEventBase {
+    event: 'runPaused';
+    run: AIChatRunState;
+    pauseReason: AIChatRunPauseReason;
+    approval?: AIChatApprovalRecord;
+    pendingApprovals?: AIChatApprovalRecord[];
+    reconnectState?: AIChatReconnectState;
+}
+/**
+ * The active run failed. Sent immediately before the terminal `error` event when the conversation has an
+ * active run to mark failed, so clients can update run state before the error is shown.
+ */
+export interface AIChatRunFailedEvent extends AIChatStreamEventBase {
+    event: 'runFailed';
+    run: AIChatRunState;
+}
+export interface AIChatRunResumedEvent extends AIChatStreamEventBase {
+    event: 'runResumed';
+    run: AIChatRunState;
+    resumeReason: AIChatRunResumeReason;
+}
+export interface AIChatScopeResolvedEvent extends AIChatStreamEventBase {
+    event: 'scopeResolved';
+    chatMode: AIChatMode;
+    requestedScope?: AIWorkspaceScopeRequest;
+    resolvedScope: AIResolvedWorkspaceScope;
+}
+export interface AIChatPageSnapshotBuiltEvent extends AIChatStreamEventBase {
+    event: 'pageSnapshotBuilt';
+    snapshot: AIChatPageSnapshot;
+}
+export interface AIChatToolAffordanceBuiltEvent extends AIChatStreamEventBase {
+    event: 'toolAffordanceBuilt';
+    toolAffordanceSnapshot: AIChatToolAffordanceSnapshot;
+}
+export interface AIChatRoutingStartedEvent extends AIChatStreamEventBase {
+    event: 'routingStarted';
+    requestedMode?: AIChatMode;
+}
+export interface AIChatRoutingCompletedEvent extends AIChatStreamEventBase {
+    event: 'routingCompleted';
+    path: AIOrchestrationPath;
+    /**
+     * @deprecated Numeric routing confidence is no longer emitted on the client lane
+     * (architecture decision 16 - visible verified grounding without numeric confidence).
+     * It remains on the persisted orchestration artifacts and the audit artifact.
+     */
+    confidence?: number;
+    domains?: AIRouterDomainScore[];
+    missingInputs: string[];
+    reasonCode?: AIReasonCode;
+    whyThisPath?: string;
+    /**
+     * Pre-routing latency readout. Present only when turn diagnostics are enabled (local and dev API hosts,
+     * or `AI_CHAT_TURN_DIAGNOSTICS=true`). Content-free.
+     */
+    diagnostics?: AIChatRoutingDiagnostics;
+    /**
+     * @deprecated No longer emitted on the client lane; kept for backwards compatibility with
+     * clients that still read it.
+     */
+    analysisConfidence?: number;
+    needsRetrieval?: boolean;
+    selectedSkillPackIds?: AIChatSkillId[];
+    complexity?: AIChatComplexity;
+}
+export interface AIChatPlanCreatedEvent extends AIChatStreamEventBase {
+    event: 'planCreated';
+    plan: AIChatPlanSnapshot;
+}
+export interface AIChatPlanUpdatedEvent extends AIChatStreamEventBase {
+    event: 'planUpdated';
+    plan: AIChatPlanSnapshot;
+}
+export interface AIChatCommentaryEvent extends AIChatStreamEventBase {
+    event: 'commentary';
+    entry: AIChatCommentaryEntry;
+}
+export interface AIChatProgressUpdateEvent extends AIChatStreamEventBase {
+    event: 'progressUpdate';
+    progress: AIChatProgressEntry;
+}
+export interface AIChatToolCallEvent extends AIChatStreamEventBase {
+    event: 'toolCall';
+    callId: string;
+    /** Customer-facing tool display name. */
+    toolName: string;
+    /** Registered tool name (for example `environment_read`). Use it for state keys and tool-specific handling. */
+    canonicalToolName?: string;
+    arguments: Record<string, unknown>;
+}
+export interface AIChatToolResultEvent extends AIChatStreamEventBase {
+    event: 'toolResult';
+    callId: string;
+    /** Customer-facing tool display name. */
+    toolName: string;
+    /** Registered tool name (for example `environment_read`). Use it for state keys and tool-specific handling. */
+    canonicalToolName?: string;
+    result: AIChatToolExecutionResult;
+}
+export interface AIChatToolErrorEvent extends AIChatStreamEventBase {
+    event: 'toolError';
+    callId: string;
+    /** Customer-facing tool display name. */
+    toolName: string;
+    /** Registered tool name (for example `environment_read`). Use it for state keys and tool-specific handling. */
+    canonicalToolName?: string;
+    error: AIChatToolExecutionError;
+}
+/** Where a guardrail decision was taken. */
+export type AIChatGuardrailStage = 'input' | 'toolResult' | 'output';
+/** What the guardrail did: let the content through, block the request, redact content, or replace the answer with a safe fallback. */
+export type AIChatGuardrailAction = 'allow' | 'block' | 'redact' | 'fallback';
+/**
+ * A guardrail changed the turn: an input was blocked, untrusted or unsafe content was withheld, or the
+ * answer was replaced with a fallback. `message` is customer-safe and never repeats the blocked content.
+ */
+export interface AIChatGuardrailTriggeredEvent extends AIChatStreamEventBase {
+    event: 'guardrailTriggered';
+    stage: AIChatGuardrailStage;
+    action: AIChatGuardrailAction;
+    /** Machine category, for example `prompt_injection`, `internal_state_disclosure` or `unsupported_mutation_claim`. */
+    category: string;
+    reasonCode?: string;
+    message: string;
+}
+export interface AIChatApprovalRequiredEvent extends AIChatStreamEventBase {
+    event: 'approvalRequired';
+    run: AIChatRunState;
+    approval: AIChatApprovalRecord;
+}
+export interface AIChatApprovalStateChangedEvent extends AIChatStreamEventBase {
+    event: 'approvalStateChanged';
+    run: AIChatRunState;
+    approval: AIChatApprovalRecord;
+}
+export interface AIChatFormatterStartedEvent extends AIChatStreamEventBase {
+    event: 'formatterStarted';
+    policy?: AIHtmlLitePolicy;
+}
+export interface AIChatFormatterCompletedEvent extends AIChatStreamEventBase {
+    event: 'formatterCompleted';
+    formatter?: AIFormatterOutput;
+}
+export interface AIChatMessageEvent extends AIChatStreamEventBase {
+    event: 'message';
+    delta: string;
+}
+/**
+ * Provisional answer text streamed while the model is still writing the answer.
+ *
+ * A draft is not authoritative: it has not been formatted, claim-verified or persisted, so clients render
+ * it as escaped plain text, visibly marked as a draft, and never parse it. Producers release only answer
+ * prose that has passed the output guardrail rules, never structured output or evidence handles. The first `message` delta or any
+ * terminal or pausing event (`runCompleted`, `runPaused`, `error`) supersedes it. Clients that do not
+ * recognize the event ignore it.
+ */
+export interface AIChatAnswerDraftEvent extends AIChatStreamEventBase {
+    event: 'answerDraft';
+    /** Plain-text fragment appended to the current draft. */
+    delta: string;
+}
+/**
+ * Why the current draft was discarded: the drafted text was preamble before a tool call (`toolCall`), the
+ * provider response failed before it completed (`error`), or the drafted text matched an output guardrail
+ * rule, so the final answer will be a guardrail fallback (`outputGuardrail`). Text matching the rule is
+ * never sent as a draft; the reset withdraws the prose drafted before it.
+ */
+export type AIChatAnswerDraftResetReason = 'toolCall' | 'error' | 'outputGuardrail';
+/** Discards the current answer draft. Later `answerDraft` deltas start a new draft. */
+export interface AIChatAnswerDraftResetEvent extends AIChatStreamEventBase {
+    event: 'answerDraftReset';
+    reason: AIChatAnswerDraftResetReason;
+}
+export interface AIChatCitationEvent extends AIChatStreamEventBase {
+    event: 'citation';
+    citation: AIChatCitation;
+}
+export interface AIChatWorkspaceArtifactStartedEvent extends AIChatStreamEventBase {
+    event: 'artifactStarted';
+    artifactId: string;
+    kind: AIChatWorkspaceArtifactKind;
+    dataMode: AIChatWorkspaceArtifactDataMode;
+    title: string;
+    placement: AIChatWorkspaceArtifactPlacement;
+}
+export interface AIChatWorkspaceArtifactCompletedEvent extends AIChatStreamEventBase {
+    event: 'artifactCompleted';
+    artifactId: string;
+    artifact: AIChatWorkspaceArtifact;
+}
+export interface AIChatWorkspaceArtifactFailedEvent extends AIChatStreamEventBase {
+    event: 'artifactFailed';
+    artifactId: string;
+    reasonCode: AIChatWorkspaceArtifactFailureReason;
+}
+export interface AIChatRunCompletedEvent extends AIChatStreamEventBase {
+    event: 'runCompleted';
+    run: AIChatRunState;
+    terminalSnapshot: AIChatTerminalSnapshot;
+}
+/**
+ * @deprecated Compatibility-only parser shape. New producers must emit
+ * AIChatRunCompletedEvent with its required terminalSnapshot.
+ */
+export interface AIChatDoneEvent extends AIChatStreamEventBase {
+    event: 'done';
+    run: AIChatRunState;
+    terminalSnapshot: AIChatTerminalSnapshot;
+    responseId?: string;
+    answer?: string;
+    turnSnapshot?: AIChatTurnSnapshot;
+    finalSnapshot?: AIChatFinalSnapshot | null;
+    completionReason?: string;
+    structuredResponse?: StructuredAIResponse;
+    citations?: AIChatCitation[];
+    routing?: AIChatRoutingMetadata;
+    chatMode?: AIChatMode;
+    resolvedScope?: AIResolvedWorkspaceScope;
+    assistantProfileSummary?: AIChatAssistantProfileSummary;
+    toolPolicySummary?: AIChatToolPolicySummary;
+    sourcePolicySummary?: AIChatSourcePolicySummary;
+    queuedPrompt?: AIChatQueuedPromptState;
+    evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
+    reconnectState?: AIChatReconnectState;
+    degradedState?: AIChatDegradedState;
+    collaborationRun?: AIChatCollaborationRun;
+}
+/** Secret-free record of the provider failure behind a failed turn (status, provider code, bounded message, stage, route, elapsed). */
+export interface AIChatProviderErrorDiagnostics {
+    status?: number;
+    providerCode?: string;
+    message?: string;
+    stage?: string;
+    route?: string;
+    elapsedMs?: number;
+    requestId?: string;
+}
+/** The failure context a failed turn carries on its terminal `error` event (additive; also persisted with the turn). */
+export interface AIChatFailureContext {
+    stage?: string;
+    reasonCode?: string;
+    terminalOutcomeCode?: string;
+    completionReason?: string;
+    retryable?: boolean;
+    toolName?: string;
+    callId?: string;
+    errorCode?: string;
+    capturedAt?: string;
+    providerError?: AIChatProviderErrorDiagnostics;
+}
+export interface AIChatErrorEvent extends AIChatStreamEventBase {
+    event: 'error';
+    run: AIChatRunState;
+    code: string;
+    message: string;
+    retryable: boolean;
+    /** Machine reason code for the failure (mirrors `code` when the failure has one). */
+    reasonCode?: string;
+    /** Diagnosable failure context: stage, route and the provider error behind it. */
+    failureContext?: AIChatFailureContext;
+}
+export interface AIChatPingEvent extends AIChatStreamEventBase {
+    event: 'ping';
+}
+/** Outcome of one provider model call. */
+export type AIChatModelCallStatus = 'ok' | 'error' | 'aborted' | 'incomplete' | 'interrupted';
+/**
+ * Content-free timing and token record for one provider model call in a turn. Times are milliseconds; start
+ * times are measured from request receipt.
+ */
+export interface AIChatModelCallRecord {
+    /** `guardrail`, `planner`, `specialist:<domain>`, `synthesis`, `synthesisRepair`, `critic`, `generic`, `default`, ... */
+    stage: string;
+    model?: string;
+    /** Reasoning effort requested by Spotto (`omitted` when none was sent). */
+    requestedEffort?: string;
+    /** Reasoning effort the provider reports it used. */
+    effectiveEffort?: string;
+    startedAtMs: number;
+    elapsedMs: number;
+    /** Time to provider response headers. */
+    headersMs?: number;
+    /** Time to the first output text delta (streamed calls). */
+    firstTextMs?: number;
+    /** Generic loop only: time from the previous boundary (loop start or previous call end, including tool execution) to `response.created`. */
+    beforeCreatedMs?: number;
+    /** Provider-reported processing time, when returned. */
+    providerProcessingMs?: number;
+    streamed: boolean;
+    status: AIChatModelCallStatus;
+    httpStatus?: number;
+    attempts?: number;
+    maxOutputTokens?: number;
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    providerRegion?: string;
+}
+/** Summed model-call counters for one stage or for the whole turn. */
+export interface AIChatLatencyTotals {
+    calls: number;
+    elapsedMs: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+}
+/** Content-free annotation value recorded on a turn's latency ledger (for example the routing decision or continuity mode). */
+export type AIChatLatencyAnnotationValue = string | number | boolean | string[];
+/**
+ * Content-free latency summary of one chat turn: phase marks, per-stage totals and per-call records. Carried
+ * by `turnDiagnostics` and persisted with the turn (`timings.latency` in the turn sidecar).
+ */
+export interface AIChatTurnLatencySummary {
+    /** Epoch milliseconds of request receipt. */
+    originEpochMs: number;
+    /** Milliseconds from request receipt to when the summary was taken. */
+    capturedAtMs: number;
+    /** First occurrence of each named phase or stream event, in milliseconds from request receipt (for example `runStarted`, `message`). */
+    marks: Record<string, number>;
+    /** Totals per stage; all `specialist:<domain>` calls are summed under `specialists`. */
+    stages: Record<string, AIChatLatencyTotals>;
+    totals: AIChatLatencyTotals;
+    modelCalls: AIChatModelCallRecord[];
+    /** Model calls not recorded because the per-turn record limit was reached. */
+    modelCallsTruncated?: number;
+    annotations?: Record<string, AIChatLatencyAnnotationValue>;
+}
+/** Pre-routing subset of the latency summary carried on `routingCompleted` when turn diagnostics are enabled. */
+export interface AIChatRoutingDiagnostics {
+    marks: Record<string, number>;
+    modelCalls: AIChatModelCallRecord[];
+    annotations?: Record<string, AIChatLatencyAnnotationValue>;
+}
+/** Turn latency summary plus the turn context needed to read it. */
+export interface AIChatTurnDiagnostics extends AIChatTurnLatencySummary {
+    /** Host name of the model provider endpoint (never a key or full URL). */
+    providerHost?: string;
+    routePath?: AIOrchestrationPath;
+    responseMode?: AIChatResolvedResponseMode;
+    chatMode?: AIChatMode;
+}
+/**
+ * Developer diagnostics for the turn, sent once immediately before the terminal event. Emitted only on local
+ * and dev API hosts, or when `AI_CHAT_TURN_DIAGNOSTICS=true`; production clients must not depend on it.
+ */
+export interface AIChatTurnDiagnosticsEvent extends AIChatStreamEventBase {
+    event: 'turnDiagnostics';
+    diagnostics: AIChatTurnDiagnostics;
+}
+export type AIChatCanonicalStreamEvent = AIChatRunStartedEvent | AIChatRunStatusEvent | AIChatRunPausedEvent | AIChatRunResumedEvent | AIChatRunCompletedEvent | AIChatRunFailedEvent | AIChatScopeResolvedEvent | AIChatPageSnapshotBuiltEvent | AIChatToolAffordanceBuiltEvent | AIChatRoutingStartedEvent | AIChatRoutingCompletedEvent | AIChatPlanCreatedEvent | AIChatPlanUpdatedEvent | AIChatCommentaryEvent | AIChatProgressUpdateEvent | AIChatGuardrailTriggeredEvent | AIChatToolCallEvent | AIChatToolResultEvent | AIChatToolErrorEvent | AIChatApprovalRequiredEvent | AIChatApprovalStateChangedEvent | AIChatFormatterStartedEvent | AIChatFormatterCompletedEvent | AIChatMessageEvent | AIChatAnswerDraftEvent | AIChatAnswerDraftResetEvent | AIChatCitationEvent | AIChatWorkspaceArtifactStartedEvent | AIChatWorkspaceArtifactCompletedEvent | AIChatWorkspaceArtifactFailedEvent | AIChatErrorEvent | AIChatPingEvent | AIChatTurnDiagnosticsEvent;
+/**
+ * Includes the deprecated done event so clients can parse streams during the
+ * migration. Use AIChatCanonicalStreamEvent for producers and contract gates.
+ */
+export type AIChatStreamEvent = AIChatCanonicalStreamEvent | AIChatDoneEvent;
 //# sourceMappingURL=index.d.ts.map