@spottoai/types-package 1.0.2-dev1138.1 → 1.0.2-dev1138.12

package/dist/ai/grounding.d.ts

@@ -0,0 +1,41 @@
+import type { EnvironmentArtifactKindV1, EnvironmentCoverageStateV1 } from '../environment/contracts.js';
+export declare const AI_CHAT_GROUNDING_LIMITS_V1: Readonly<{
+    readonly claims: 128;
+    readonly citationsPerClaim: 32;
+    readonly identifierScalars: 128;
+}>;
+export declare const AI_CHAT_GROUNDING_REASON_CODES_V1: readonly ["grounding.not-required", "grounding.claim-extraction-failed", "grounding.missing-citation", "grounding.source-unavailable", "grounding.source-stale", "grounding.generation-mismatch", "grounding.value-mismatch", "grounding.unsupported-claim"];
+export type AIChatGroundingReasonCodeV1 = (typeof AI_CHAT_GROUNDING_REASON_CODES_V1)[number];
+export type AIChatGroundingStatusV1 = 'verified' | 'unverified' | 'not-required';
+export type AIChatClaimVerificationStatusV1 = 'verified' | 'unverified';
+export type AIEnvironmentEvidenceCoverageStatusV1 = EnvironmentCoverageStateV1['status'];
+/** Client-safe environment evidence metadata with no scope, generation, storage, or runtime-handle identity. */
+export interface AIEnvironmentEvidenceMatch {
+    safeLabel: string;
+    portalRoute: string;
+    artifactKind: EnvironmentArtifactKindV1;
+    sourceCompletedAt: string;
+    coverageStatus: AIEnvironmentEvidenceCoverageStatusV1;
+    truncated: boolean;
+    citationIds: string[];
+}
+export interface AIChatClaimVerificationV1 {
+    claimId: string;
+    status: AIChatClaimVerificationStatusV1;
+    citationIds: string[];
+    reasonCode?: Exclude<AIChatGroundingReasonCodeV1, 'grounding.not-required'>;
+}
+/** Deterministic grounding result. This is evidence verification, never model confidence. */
+export interface AIChatGroundingSummary {
+    status: AIChatGroundingStatusV1;
+    method: 'deterministic-citation-and-value';
+    totalClaimCount: number;
+    verifiedClaimCount: number;
+    claims: AIChatClaimVerificationV1[];
+    reasonCode?: AIChatGroundingReasonCodeV1;
+}
+/** Strictly validates client-safe environment evidence metadata. */
+export declare const isAIEnvironmentEvidenceMatch: (value: unknown) => value is AIEnvironmentEvidenceMatch;
+/** Strictly validates deterministic summary and claim-level citation invariants. */
+export declare const isAIChatGroundingSummary: (value: unknown) => value is AIChatGroundingSummary;
+//# sourceMappingURL=grounding.d.ts.map

package/dist/ai/grounding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/ai/grounding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAIzG,eAAO,MAAM,2BAA2B;;;;EAI7B,CAAC;AAEZ,eAAO,MAAM,iCAAiC,8PASpC,CAAC;AAEX,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7F,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,YAAY,GAAG,cAAc,CAAC;AACjF,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,YAAY,CAAC;AACxE,MAAM,MAAM,qCAAqC,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC;AAEzF,gHAAgH;AAChH,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,yBAAyB,CAAC;IACxC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,qCAAqC,CAAC;IACtD,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,+BAA+B,CAAC;IACxC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC,2BAA2B,EAAE,wBAAwB,CAAC,CAAC;CAC7E;AAED,6FAA6F;AAC7F,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,kCAAkC,CAAC;IAC3C,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,yBAAyB,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,2BAA2B,CAAC;CAC1C;AAgBD,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,0BAU/B,CAAC;AAiBzC,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,sBA+BlE,CAAC"}

package/dist/ai/grounding.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAIChatGroundingSummary = exports.isAIEnvironmentEvidenceMatch = exports.AI_CHAT_GROUNDING_REASON_CODES_V1 = exports.AI_CHAT_GROUNDING_LIMITS_V1 = void 0;
+const internal_js_1 = require("../environment/internal.js");
+const validation_js_1 = require("../environment/validation.js");
+exports.AI_CHAT_GROUNDING_LIMITS_V1 = Object.freeze({
+    claims: 128,
+    citationsPerClaim: 32,
+    identifierScalars: 128,
+});
+exports.AI_CHAT_GROUNDING_REASON_CODES_V1 = [
+    'grounding.not-required',
+    'grounding.claim-extraction-failed',
+    'grounding.missing-citation',
+    'grounding.source-unavailable',
+    'grounding.source-stale',
+    'grounding.generation-mismatch',
+    'grounding.value-mismatch',
+    'grounding.unsupported-claim',
+];
+const COVERAGE_STATUSES = new Set(['complete', 'partial', 'unavailable', 'stale', 'not-collected']);
+const GROUNDING_REASON_CODES = new Set(exports.AI_CHAT_GROUNDING_REASON_CODES_V1);
+const FAILURE_REASON_CODES = new Set(exports.AI_CHAT_GROUNDING_REASON_CODES_V1.filter(code => code !== 'grounding.not-required'));
+const isIdentifier = (value) => (0, internal_js_1.isBoundedString)(value, exports.AI_CHAT_GROUNDING_LIMITS_V1.identifierScalars, { trimmed: true, controls: true });
+const isCitationIds = (value, requireOne) => Array.isArray(value) &&
+    value.length <= exports.AI_CHAT_GROUNDING_LIMITS_V1.citationsPerClaim &&
+    (!requireOne || value.length > 0) &&
+    value.every(isIdentifier) &&
+    new Set(value).size === value.length;
+/** Strictly validates client-safe environment evidence metadata. */
+const isAIEnvironmentEvidenceMatch = (value) => (0, internal_js_1.isRecord)(value) &&
+    (0, internal_js_1.hasExactKeys)(value, ['safeLabel', 'portalRoute', 'artifactKind', 'sourceCompletedAt', 'coverageStatus', 'truncated', 'citationIds']) &&
+    (0, validation_js_1.isEnvironmentSafeLabelV1)(value.safeLabel) &&
+    (0, validation_js_1.isEnvironmentPortalRouteV1)(value.portalRoute) &&
+    (0, validation_js_1.isEnvironmentArtifactKindV1)(value.artifactKind) &&
+    (0, internal_js_1.isCanonicalUtcTimestamp)(value.sourceCompletedAt) &&
+    typeof value.coverageStatus === 'string' &&
+    COVERAGE_STATUSES.has(value.coverageStatus) &&
+    typeof value.truncated === 'boolean' &&
+    isCitationIds(value.citationIds, true);
+exports.isAIEnvironmentEvidenceMatch = isAIEnvironmentEvidenceMatch;
+const isAIChatClaimVerificationV1 = (value) => {
+    if (!(0, internal_js_1.isRecord)(value) ||
+        !(0, internal_js_1.hasExactKeys)(value, ['claimId', 'status', 'citationIds'], ['reasonCode']) ||
+        !isIdentifier(value.claimId) ||
+        (value.status !== 'verified' && value.status !== 'unverified')) {
+        return false;
+    }
+    if (value.status === 'verified') {
+        return value.reasonCode === undefined && isCitationIds(value.citationIds, true);
+    }
+    return typeof value.reasonCode === 'string' && FAILURE_REASON_CODES.has(value.reasonCode) && isCitationIds(value.citationIds, false);
+};
+/** Strictly validates deterministic summary and claim-level citation invariants. */
+const isAIChatGroundingSummary = (value) => {
+    if (!(0, internal_js_1.isRecord)(value) ||
+        !(0, internal_js_1.hasExactKeys)(value, ['status', 'method', 'totalClaimCount', 'verifiedClaimCount', 'claims'], ['reasonCode']) ||
+        value.method !== 'deterministic-citation-and-value' ||
+        (value.status !== 'verified' && value.status !== 'unverified' && value.status !== 'not-required') ||
+        !(0, internal_js_1.isNonNegativeInteger)(value.totalClaimCount) ||
+        !(0, internal_js_1.isNonNegativeInteger)(value.verifiedClaimCount) ||
+        !Array.isArray(value.claims) ||
+        value.claims.length > exports.AI_CHAT_GROUNDING_LIMITS_V1.claims ||
+        !value.claims.every(isAIChatClaimVerificationV1) ||
+        new Set(value.claims.map(claim => claim.claimId)).size !== value.claims.length ||
+        value.totalClaimCount !== value.claims.length) {
+        return false;
+    }
+    const verifiedClaimCount = value.claims.filter(claim => claim.status === 'verified').length;
+    if (value.verifiedClaimCount !== verifiedClaimCount)
+        return false;
+    if (value.status === 'verified') {
+        return value.totalClaimCount > 0 && value.verifiedClaimCount === value.totalClaimCount && value.reasonCode === undefined;
+    }
+    if (value.status === 'not-required') {
+        return value.totalClaimCount === 0 && value.verifiedClaimCount === 0 && value.reasonCode === 'grounding.not-required';
+    }
+    if (typeof value.reasonCode !== 'string' || !GROUNDING_REASON_CODES.has(value.reasonCode) || value.reasonCode === 'grounding.not-required') {
+        return false;
+    }
+    if (value.totalClaimCount === 0)
+        return value.reasonCode === 'grounding.claim-extraction-failed';
+    return value.verifiedClaimCount < value.totalClaimCount;
+};
+exports.isAIChatGroundingSummary = isAIChatGroundingSummary;
+//# sourceMappingURL=grounding.js.map

package/dist/ai/grounding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding.js","sourceRoot":"","sources":["../../src/ai/grounding.ts"],"names":[],"mappings":"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"}

package/dist/ai/index.d.ts

@@ -1,4 +1,9 @@
 /** 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' | 'aiGenerated';
@@ -110,7 +115,19 @@ export interface AIChatClassificationResult {
 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' | 'AI_DEGRADED_NO_PATH';
+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}`;
@@ -251,12 +268,34 @@ export interface AIPlannerWorkItem {
     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;
@@ -298,7 +337,7 @@ export interface AIChatToolPolicySummary {
     approvalRequired: boolean;
     summary: string;
 }
-export type AIChatRetrievalSourceType = 'operational' | 'memory' | 'knowledge' | 'external';
+export type AIChatRetrievalSourceType = 'operational' | 'memory' | 'knowledge' | 'external' | 'environment';
 export interface AIChatSourcePolicySummary {
     sourceTypes: AIChatRetrievalSourceType[];
     externalSourceEnabled: boolean;
@@ -343,6 +382,7 @@ export interface AIChatEvidenceCoverage {
     evidenceGroups: AIChatEvidenceGroup[];
     citationCoverage: AIChatCitationCoverage;
     memoryMatches?: AIChatMemoryMatch[];
+    environmentMatches?: AIEnvironmentEvidenceMatch[];
 }
 export interface AIChatRuntimeEvalSignals {
     observedLeadSpecialist?: string;
@@ -597,12 +637,22 @@ export interface AIChatProgressEntry {
     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;
@@ -644,6 +694,7 @@ export interface AIChatSkillPackDescriptor {
 export interface AIChatToolDescriptor {
     toolName: string;
     source: 'internal' | 'mcp' | `mcp:${string}` | string;
+    retrievalSourceType?: AIChatRetrievalSourceType;
     providerId?: string;
     providerTitle?: string;
     providerCapabilities?: string[];
@@ -704,6 +755,7 @@ export interface AIChatFinalSnapshot {
     sourcePolicySummary?: AIChatSourcePolicySummary;
     queuedPrompt?: AIChatQueuedPromptState;
     evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
     reconnectState?: AIChatReconnectState;
     degradedState?: AIChatDegradedState;
     collaborationRun?: AIChatCollaborationRun;
@@ -731,6 +783,7 @@ export interface AIChatAuditArtifact {
     sourcePolicySummary?: AIChatSourcePolicySummary;
     queuedPrompt?: AIChatQueuedPromptState;
     evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
     reconnectState?: AIChatReconnectState;
     degradedState?: AIChatDegradedState;
     collaborationRun?: AIChatCollaborationRun;
@@ -829,6 +882,40 @@ export interface AIChatConversationFeedbackUpdateResponse {
     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;
@@ -858,14 +945,17 @@ export interface AIChatTerminalSnapshot {
     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' | 'scopeResolved' | 'pageSnapshotBuilt' | 'toolAffordanceBuilt' | 'routingStarted' | 'routingCompleted' | 'planCreated' | 'planUpdated' | 'commentary' | 'progressUpdate' | 'toolCall' | 'toolResult' | 'toolError' | 'approvalRequired' | 'approvalStateChanged' | 'formatterStarted' | 'formatterCompleted' | 'message' | 'citation' | 'error' | 'ping';
+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.
@@ -899,6 +989,14 @@ export interface AIChatRunPausedEvent extends AIChatStreamEventBase {
     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;
@@ -925,11 +1023,25 @@ export interface AIChatRoutingStartedEvent extends AIChatStreamEventBase {
 export interface AIChatRoutingCompletedEvent extends AIChatStreamEventBase {
     event: 'routingCompleted';
     path: AIOrchestrationPath;
-    confidence: number;
+    /**
+     * @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[];
@@ -954,21 +1066,47 @@ export interface AIChatProgressUpdateEvent extends AIChatStreamEventBase {
 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;
@@ -991,10 +1129,54 @@ 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;
@@ -1023,25 +1205,139 @@ export interface AIChatDoneEvent extends AIChatStreamEventBase {
     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';
 }
-export type AIChatCanonicalStreamEvent = AIChatRunStartedEvent | AIChatRunStatusEvent | AIChatRunPausedEvent | AIChatRunResumedEvent | AIChatRunCompletedEvent | AIChatScopeResolvedEvent | AIChatPageSnapshotBuiltEvent | AIChatToolAffordanceBuiltEvent | AIChatRoutingStartedEvent | AIChatRoutingCompletedEvent | AIChatPlanCreatedEvent | AIChatPlanUpdatedEvent | AIChatCommentaryEvent | AIChatProgressUpdateEvent | AIChatToolCallEvent | AIChatToolResultEvent | AIChatToolErrorEvent | AIChatApprovalRequiredEvent | AIChatApprovalStateChangedEvent | AIChatFormatterStartedEvent | AIChatFormatterCompletedEvent | AIChatMessageEvent | AIChatCitationEvent | AIChatErrorEvent | AIChatPingEvent;
+/** 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;
-export {};
 //# sourceMappingURL=index.d.ts.map