@spottoai/types-package 1.0.2-dev1138.13 → 1.0.2-dev1138.14

package/dist/ai/grounding.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAIChatGroundingSummary = exports.isAIChatGroundedFigureV1 = exports.isAIEnvironmentEvidenceMatch = exports.AI_CHAT_GROUNDED_FIGURE_ANCHOR_ATTRIBUTE_V1 = 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,
+    figures: 128,
+    figureTextScalars: 96,
+});
+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',
+    'grounding.figure-unreferenced',
+    'grounding.reference-unresolved',
+];
+/**
+ * HTML attribute the API puts on the element wrapping each figure in the answer. Its value is the figure's
+ * `figureId`, so clients anchor provenance without matching text.
+ */
+exports.AI_CHAT_GROUNDED_FIGURE_ANCHOR_ATTRIBUTE_V1 = 'data-spotto-figure';
+const COVERAGE_STATUSES = new Set(['complete', 'partial', 'unavailable', 'stale', 'not-collected']);
+const FIGURE_KINDS = new Set(['money', 'percentage', 'quantity', 'date']);
+const FIGURE_ONLY_REASON_CODES = new Set(['grounding.figure-unreferenced', 'grounding.reference-unresolved']);
+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 CLAIM_FAILURE_REASON_CODES = new Set([...FAILURE_REASON_CODES].filter(code => !FIGURE_ONLY_REASON_CODES.has(code)));
+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' && CLAIM_FAILURE_REASON_CODES.has(value.reasonCode) && isCitationIds(value.citationIds, false);
+};
+/** Strictly validates one grounded figure. */
+const isAIChatGroundedFigureV1 = (value) => {
+    if (!(0, internal_js_1.isRecord)(value) ||
+        !(0, internal_js_1.hasExactKeys)(value, ['figureId', 'status', 'kind', 'text', 'citationIds'], ['reasonCode']) ||
+        !isIdentifier(value.figureId) ||
+        typeof value.kind !== 'string' ||
+        !FIGURE_KINDS.has(value.kind) ||
+        !(0, internal_js_1.isBoundedString)(value.text, exports.AI_CHAT_GROUNDING_LIMITS_V1.figureTextScalars, { trimmed: true, controls: true })) {
+        return false;
+    }
+    if (value.status === 'verified') {
+        return value.reasonCode === undefined && isCitationIds(value.citationIds, true);
+    }
+    return (value.status === 'unverified' &&
+        value.reasonCode === 'grounding.figure-unreferenced' &&
+        Array.isArray(value.citationIds) &&
+        value.citationIds.length === 0);
+};
+exports.isAIChatGroundedFigureV1 = isAIChatGroundedFigureV1;
+const isClaimSummary = (value) => {
+    if (value.figures !== undefined ||
+        (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' || !CLAIM_FAILURE_REASON_CODES.has(value.reasonCode))
+        return false;
+    if (value.totalClaimCount === 0)
+        return value.reasonCode === 'grounding.claim-extraction-failed';
+    return value.verifiedClaimCount < value.totalClaimCount;
+};
+const isFigureSummary = (value) => {
+    if (value.totalClaimCount !== 0 ||
+        value.verifiedClaimCount !== 0 ||
+        !Array.isArray(value.claims) ||
+        value.claims.length !== 0 ||
+        !Array.isArray(value.figures) ||
+        value.figures.length > exports.AI_CHAT_GROUNDING_LIMITS_V1.figures ||
+        !value.figures.every(exports.isAIChatGroundedFigureV1) ||
+        new Set(value.figures.map(figure => figure.figureId)).size !== value.figures.length) {
+        return false;
+    }
+    const verified = value.figures.filter(figure => figure.status === 'verified').length;
+    const unverified = value.figures.length - verified;
+    const failureReason = typeof value.reasonCode === 'string' && FAILURE_REASON_CODES.has(value.reasonCode);
+    switch (value.status) {
+        case 'not-required':
+            return value.figures.length === 0 && value.reasonCode === 'grounding.not-required';
+        case 'verified':
+            return verified > 0 && unverified === 0 && value.reasonCode === undefined;
+        case 'partial':
+            return verified > 0 && unverified > 0 && failureReason;
+        case 'unverified':
+            // Also reached with no figures left, for example when every statement with an unresolved reference was removed.
+            return verified === 0 && failureReason;
+        default:
+            return false;
+    }
+};
+/** Strictly validates deterministic summary, claim-level and figure-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', 'figures']) ||
+        (value.reasonCode !== undefined && (typeof value.reasonCode !== 'string' || !GROUNDING_REASON_CODES.has(value.reasonCode)))) {
+        return false;
+    }
+    if (value.method === 'deterministic-citation-and-value')
+        return isClaimSummary(value);
+    if (value.method === 'server-rendered-figures')
+        return isFigureSummary(value);
+    return false;
+};
+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,11 @@
 /** Common AI interfaces shared between frontend and backend */
+import type { AIChatFollowUpSuggestionV1 } from './followUps.js';
+import type { AIChatGroundingSummary, AIEnvironmentEvidenceMatch } from './grounding.js';
+import type { AIChatWorkspaceArtifact, AIChatWorkspaceArtifactDataMode, AIChatWorkspaceArtifactFailureReason, AIChatWorkspaceArtifactKind, AIChatWorkspaceArtifactPlacement } from './workspaceArtifacts.js';
+export * from './grounding.js';
+export * from './followUps.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 +117,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 +270,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 +339,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 +384,7 @@ export interface AIChatEvidenceCoverage {
     evidenceGroups: AIChatEvidenceGroup[];
     citationCoverage: AIChatCitationCoverage;
     memoryMatches?: AIChatMemoryMatch[];
+    environmentMatches?: AIEnvironmentEvidenceMatch[];
 }
 export interface AIChatRuntimeEvalSignals {
     observedLeadSpecialist?: string;
@@ -597,12 +639,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 +696,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 +757,7 @@ export interface AIChatFinalSnapshot {
     sourcePolicySummary?: AIChatSourcePolicySummary;
     queuedPrompt?: AIChatQueuedPromptState;
     evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
     reconnectState?: AIChatReconnectState;
     degradedState?: AIChatDegradedState;
     collaborationRun?: AIChatCollaborationRun;
@@ -731,6 +785,7 @@ export interface AIChatAuditArtifact {
     sourcePolicySummary?: AIChatSourcePolicySummary;
     queuedPrompt?: AIChatQueuedPromptState;
     evidenceCoverage?: AIChatEvidenceCoverage;
+    grounding?: AIChatGroundingSummary;
     reconnectState?: AIChatReconnectState;
     degradedState?: AIChatDegradedState;
     collaborationRun?: AIChatCollaborationRun;
@@ -829,6 +884,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 +947,19 @@ 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[];
+    /** Follow-up questions derived from this answer; absent when none were produced. */
+    followUpSuggestions?: AIChatFollowUpSuggestionV1[];
 }
 /**
  * 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 +993,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 +1027,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 +1070,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 +1133,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 +1209,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