export declare interface ActionDescriptor {
    actionId: string;
    actionCode: string;
    actionName: string;
    description: string;
    params: Record<string, unknown>;
    needConfirm: boolean;
    riskLevel: 'safe' | 'caution' | 'danger';
}

/** A write-action pending 二次确认. */
export declare interface ActionPart {
    kind: 'action';
    actionId: string;
    title: string;
    summary?: string;
    riskLevel: RiskLevel;
    params: Record<string, string | number | boolean | null>;
}

export declare interface AiAssistantError extends Error {
    code: ErrorCode;
    retriable: boolean;
    details?: unknown;
}

export declare class AiHttpClient {
    private readonly baseUrl;
    private readonly headersProvider;
    constructor(baseUrl: string, headersProvider: () => Record<string, string>);
    getPluginConfig(systemCode: string): Promise<PluginConfig | null>;
    listModels(): Promise<ModelOption[]>;
    createConversation(systemCode: string, title?: string, modelCode?: string, sceneCode?: string): Promise<Conversation>;
    listConversations(systemCode: string, page?: number, size?: number): Promise<Conversation[]>;
    getMessages(conversationId: string): Promise<AssistantMessage[]>;
    deleteConversation(conversationId: string): Promise<void>;
    /**
     * Fork a conversation into a new branch, copying history up to and including
     * `messageId` (or the full history when omitted). Returns the new conversation.
     */
    forkConversation(conversationId: string, messageId?: string): Promise<Conversation>;
    /**
     * Soft-delete messages at (`from`, inclusive) or after (`after`, exclusive) an
     * anchor message. Returns the number of removed rows.
     */
    truncateMessages(conversationId: string, messageId: string, mode: 'from' | 'after'): Promise<number>;
    getSuggestions(systemCode: string, sceneCode?: string): Promise<string[]>;
    confirmAction(actionId: string, confirm: boolean): Promise<void>;
    submitFeedback(messageId: string, rating: number, comment?: string): Promise<void>;
    /** Explicitly cancel a live DSH turn without conflating it with SSE detach. */
    cancelChat(conversationId: string, messageId: string): Promise<boolean>;
    /**
     * Artifact workbench JSON APIs (06 spec §3.5). All conversation-scoped per
     * 02-contract-storage-api §5; binary bytes go through fetchArtifactBytes.
     */
    listArtifacts(conversationId: string, opts?: {
        cursor?: string;
        kind?: PublicArtifactKind;
        status?: PublicArtifactStatus;
    }): Promise<ArtifactListResult>;
    getArtifact(conversationId: string, artifactId: string): Promise<PublicArtifactRef>;
    getPreviewManifest(conversationId: string, artifactId: string): Promise<PagePreviewManifest>;
    /** Bounded content hydration for markdown/text/table viewers. */
    getArtifactContent(conversationId: string, artifactId: string): Promise<BoundedArtifactContent>;
    /** Preview page image URL (browser constructs it from ids per 02 §7). */
    artifactPreviewPageUrl(conversationId: string, artifactId: string, page: number, variant?: 'thumbnail' | 'full'): string;
    /** Original-file download URL (Range-capable, attachment disposition). */
    artifactDownloadUrl(conversationId: string, artifactId: string): string;
    /**
     * Binary fetch for preview pages and downloads. Auth headers ride the same
     * provider as every other call; failures map to AiHttpError with status so
     * the store can render 409/410/404 distinctly (02 §5).
     */
    fetchArtifactBytes(url: string, signal?: AbortSignal): Promise<Blob>;
    /**
     * Upload one conversation attachment (multipart). Runs text extraction
     * server-side; returns the metadata the turn request later references.
     * Deliberately uses raw fetch (not `request`): FormData must set its own
     * multipart boundary Content-Type.
     */
    uploadAttachment(conversationId: string, file: File, signal?: AbortSignal): Promise<UploadedAttachment>;
    /** 附件内容预览（文本类带提取文本；二进制类 text 为 null）。 */
    getAttachmentContent(conversationId: string, attachmentId: string): Promise<AttachmentContent>;
    health(): Promise<{
        status: string;
        service: string;
    }>;
    private request;
}

export declare class AiHttpError extends Error {
    readonly code: number;
    readonly traceId?: string;
    constructor(code: number, message: string, traceId?: string);
}

/**
 * @deprecated Use `AssistantVisibility` + `AssistantPresentation`. Legacy modes
 * are mapped for one compatibility cycle: launcher=closed, floating/focus-modal
 * =compact, drawer=docked, fullscreen=workspace.
 */
export declare type AiOpenMode = 'launcher' | 'floating' | 'drawer' | 'fullscreen' | 'focus-modal';

export declare type AiThemeMode = 'system' | 'light' | 'dark' | 'custom';

/** A backend-produced insight (never re-derived from rows on the client). */
declare interface AnalysisInsight {
    type: InsightType;
    title: string;
    detail: string;
    /** Optional references to column keys / row indices backing the insight. */
    refs?: string[];
}

/** Cursor-page list result of `GET .../artifacts` (02 §5). */
export declare interface ArtifactListResult {
    refs: PublicArtifactRef[];
    nextCursor?: string;
}

/**
 * Delivery artifact hint materialized from `presentation.attachments`.
 * Idempotent per `artifact.artifactId` so reconnect replays never duplicate.
 */
declare interface ArtifactPart {
    kind: 'artifact';
    artifact: PublicArtifactRef;
}

/** Extract browser-safe text from the canonical backend payload (and legacy fixtures). */
export declare function artifactTextContent(value: unknown): string;

/** Turn-level AskData observability restored from backend v2 event metadata. */
export declare interface AskDataObservation {
    traceId?: string;
    runId?: string;
    stageLatenciesMs?: Record<string, number>;
    schemaConfidence?: number;
    goldenHit?: boolean;
    retryReason?: string;
    rowCount?: number;
    denyReason?: string;
    sensitive?: boolean;
    [key: string]: unknown;
}

/** User-visible connectivity, independent from the current turn lifecycle. */
export declare type AssistantConnection = 'idle' | 'connecting' | 'online' | 'reconnecting' | 'offline';

/** Map transport-specific status strings to the public connection vocabulary. */
export declare function assistantConnectionFromStreamStatus(status: string): AssistantConnection;

export declare interface AssistantMessage {
    id: string;
    conversationId: string;
    role: MessageRole;
    type: MessageType;
    content: string;
    status: MessageStatus;
    createdAt: string;
    finishedAt?: string;
    metadata?: {
        chart?: ChartConfig;
        table?: TableResult;
        tools?: ToolCall[];
        sources?: SourceRef[];
        suggestions?: string[];
        actions?: ActionDescriptor[];
        metrics?: {
            label: string;
            value: string | number;
            unit?: string;
            trend?: {
                value: number;
                direction: 'up' | 'down' | 'flat';
                label?: string;
            };
            color?: 'primary' | 'success' | 'warning' | 'danger';
            icon?: string;
        };
        errorCode?: string;
        [key: string]: unknown;
    };
}

/** The three supported layouts for the single assistant shell. */
export declare type AssistantPresentation = 'compact' | 'docked' | 'workspace';

export declare interface AssistantState {
    /** Canonical shell visibility. */
    visibility: AssistantVisibility;
    /** User-selected layout; never overwritten by responsive behavior. */
    preferredPresentation: AssistantPresentation;
    /** Layout currently rendered after responsive resolution. */
    resolvedPresentation: AssistantPresentation;
    /** Previous preferred layout for back-navigation. */
    previousPresentation: AssistantPresentation | null;
    /** User-visible connection state. */
    connection: AssistantConnection;
    /** Current turn lifecycle. */
    turnPhase: AssistantTurnPhase;
    /** Composer draft, retained across presentation changes and failures. */
    draft: string;
    /** Last transcript position for restoration after a host remount. */
    scrollAnchor: {
        conversationId: string | null;
        top: number;
        pinned: boolean;
    };
    /** Stable focus target id for presentation transitions. */
    focusedControlId: string | null;
    /** Selected artifact id for the inspector. */
    selectedArtifactId: string | null;
    /** Floating window position (px) */
    position: {
        x: number;
        y: number;
    };
    /** Floating window size (px) */
    size: {
        width: number;
        height: number;
    };
    /** Business system code */
    systemCode: string;
    /** Selected model code */
    modelCode: string;
    /** Current conversation id */
    currentConversationId: string | null;
    /** All loaded conversations */
    conversations: Conversation[];
    /** Messages keyed by conversation id */
    messagesByConversation: Record<string, AssistantMessage[]>;
    /** Tool steps keyed by message id */
    toolStepsByMessage: Record<string, ToolStep[]>;
    /** Stream connection status */
    streamStatus: 'idle' | 'connecting' | 'streaming' | 'reconnecting' | 'closed' | 'error';
    /** Last received sequence number (for ack / resume) */
    lastSeq: number;
    /** Last heartbeat timestamp */
    lastHeartbeatAt: number;
    /** Reconnect attempt counter */
    reconnectAttempt: number;
    /** Theme mode */
    themeMode: AiThemeMode;
    /** Primary color */
    primaryColor: string;
    /** Whether an error toast is currently shown */
    hasError: boolean;
    /** Last error message (transient) */
    lastError: string | null;
}

/** Canonical lifecycle for one user turn. */
export declare type AssistantTurnPhase = 'idle' | 'planning' | 'running' | 'awaiting_input' | 'complete' | 'partial' | 'failed' | 'cancelled';

/**
 * Core protocol types for AI Assistant
 */
/** Whether the assistant shell is present. The launcher represents `closed`. */
export declare type AssistantVisibility = 'closed' | 'open';

/** Attachment content preview payload. */
export declare interface AttachmentContent {
    id: string;
    name: string;
    contentType: string;
    size: number;
    extractStatus: string;
    /** 提取文本（仅文本类；二进制为 null）。 */
    text: string | null;
}

/** Bounded UTF-8 hydration returned by the managed artifact content route. */
export declare interface BoundedArtifactContent {
    schemaVersion: '1';
    artifactId: string;
    revision: number;
    format: string;
    mimeType: string;
    content: string;
}

/** Convert one legacy open mode into the canonical orthogonal state. */
export declare function canonicalPresentationFromLegacy(mode: AiOpenMode): CanonicalPresentationState;

export declare interface CanonicalPresentationState {
    visibility: AssistantVisibility;
    preferredPresentation: AssistantPresentation;
}

/**
 * Card payload — discriminated union on `kind`. Mirrors Java `sealed interface
 * CardData permits TableCard, ChartCard, MetricCard, SourceCard,
 * SuggestionCard, GlossaryCard, AnalysisCard, CitationCard`.
 */
declare type CardData = {
    kind: 'table';
    columns: ColumnDef[];
    rows: Row[];
    total: number;
    truncated?: boolean;
    evidenceId?: string;
    datasetId?: string;
    artifactId?: string;
} | {
    kind: 'chart';
    spec: ChartSpec;
    /** Original evidence row count; the chart may omit unplottable rows. */
    rowCount?: number;
    /** Source truncation or rows omitted from this chart projection. */
    truncated?: boolean;
    evidenceId?: string;
    datasetId?: string;
    artifactId?: string;
} | {
    kind: 'metric';
    items: MetricItem[];
} | {
    kind: 'source';
    items: SourceItem[];
} | {
    kind: 'suggestion';
    items: SuggestionItem[];
} | {
    kind: 'glossary';
    columns: ColumnDef[];
} | {
    kind: 'analysis';
    insights: AnalysisInsight[];
} | {
    kind: 'citation';
    items: CitationItem[];
};

/**
 * v2 protocol — card payloads (discriminated union on `kind`).
 *
 * Per REARCHITECTURE-PLAN §4.3 / §4.4: rich content is delivered through a
 * single `card` event whose `data` is a strongly-typed, `kind`-discriminated
 * union. Adding a new card = adding a new `kind` here + one frontend registry
 * entry; the core envelope (events.ts) never changes (CLAUDE.md §12 扩展预留).
 *
 * DSH emits only presentation projections; SQL is deliberately absent.
 *
 * Pure TS — zero Vue / framework dependency.
 */
/** Closed enum of card kinds. The `card` event carries one of these. */
declare type CardKind = 'table' | 'chart' | 'metric' | 'source' | 'suggestion' | 'glossary' | 'analysis' | 'citation';

/** A rich presentation card (table / chart / metric / …). */
export declare interface CardPart {
    kind: 'card';
    id: string;
    cardKind: CardKind;
    data: CardData;
    /** Correlation id shared with the tool / sibling cards of one result (v2.1). */
    group?: string;
    /** Section placement hint for Process / Answer / Artifact rendering. */
    placement?: CardPlacement;
    /** Optional answer anchor this card is attached to. */
    anchorId?: string;
    transient?: boolean;
    status?: string;
}

/** Where a card should be rendered within the Process / Answer / Artifact model. */
declare type CardPlacement = 'process' | 'answer' | 'artifact';

export declare interface CartesianSeries {
    name: string;
    values: Array<number | null>;
    /** Dual-axis only: which y-scale this series is drawn against. */
    axis?: 0 | 1;
}

export declare interface ChartArtifact {
    kind: 'chart';
    datasetRef: string;
    chartKind: Exclude<ChartKind, ''>;
    title: string;
    summary: string;
    data: ClosedChartData;
    table: ChartTableProjection;
}

export declare interface ChartConfig {
    type: 'bar' | 'line' | 'pie' | 'heatmap' | 'gantt' | 'scatter' | 'radar';
    title: string;
    data: unknown;
    options?: Record<string, unknown>;
}

/** Encoding: which column keys map to which visual channels. */
declare interface ChartEncoding {
    /** Column key for the x axis (category / time). */
    x: string;
    /** One or more column keys for the y axis (measures). For `dual-axis`,
     * these are the bar measures drawn against the left axis. */
    y: string[];
    /** Optional column key used to split into series. */
    series?: string;
    /** Radar: one explicit common upper bound for all comparable indicators. */
    radarMax?: number;
    /** dual-axis only: exactly one measure drawn against the right axis. */
    lineColumns?: string[];
    /** dual-axis only: the label and unit each axis carries. The backend refuses
     * a dual-axis chart without two distinct labels, so these are always present
     * when `lineColumns` is. */
    axisUnits?: {
        left: string;
        right: string;
    };
}

/**
 * Closed enum of neutral chart kinds. `''` means "no suitable chart — fall back
 * to table" (mirrors WrenAI's empty chart_type). Frontend maps these to ECharts.
 */
declare type ChartKind = '' | 'bar' | 'line' | 'pie' | 'scatter' | 'area' | 'grouped-bar' | 'stacked-bar' | 'radar' | 'dual-axis';

export declare type ChartProjection = ChartProjectionSuccess | ChartProjectionFailure;

export declare interface ChartProjectionFailure {
    ok: false;
    reason: string;
    table: ChartTableProjection;
}

export declare interface ChartProjectionSuccess {
    ok: true;
    artifact: ChartArtifact;
    config: ChartConfig;
}

/**
 * Neutral, framework-agnostic chart spec. Backend owns the spec; frontend owns
 * the ECharts mapping. `data` is the full result set (rows) for plotting.
 */
declare interface ChartSpec {
    chartKind: ChartKind;
    title?: string;
    /** Stable source shared by chart, table, report, and export artifacts. */
    datasetRef?: string;
    encoding: ChartEncoding;
    /** Governance-authored display labels keyed by stable semantic column ID. */
    columnLabels?: Record<string, string>;
    data: Row[];
}

/** Compatibility helper for callers that only consume the legacy config. */
export declare function chartSpecToConfig(spec: ChartSpec): ChartConfig | null;

export declare interface ChartTableProjection {
    columns: ColumnDef[];
    rows: Row[];
    total: number;
}

export declare type ChartValue = string | number | boolean;

/** Metadata of one uploaded conversation attachment (no payload bytes). */
export declare interface ChatAttachmentRef {
    /** Backend attachment id returned by the upload endpoint. */
    id: string;
    name: string;
    /** MIME type (best-effort from the browser). */
    type: string;
    size: number;
}

/** Optional routing hints for one assistant turn. */
export declare interface ChatSendOptions {
    /** Correlates the shell's optimistic turn with the persisted user message. */
    clientRequestId?: string;
    /** Per-turn reasoning effort hint forwarded to the DSH runtime. */
    reasoningEffort?: ReasoningEffort;
    /** Attachments uploaded for this turn; the backend resolves their text. */
    attachments?: ChatAttachmentRef[];
}

/** Public request shape for the typed chat-stream endpoint. */
export declare interface ChatStreamRequest extends ChatSendOptions {
    systemCode: string;
    conversationId: string;
    message: string;
    modelCode?: string;
    pageContext?: PageContext;
}

export declare class ChunkMatcher {
    /**
     * Match parsed citations to a list of knowledge chunks.
     *
     * @param citations — output from `CitationParser.parse()`
     * @param chunks    — chunks returned by backend (should be 1-based indexed)
     * @returns chunks that were cited, with `citedBy` populated
     */
    match(citations: Citation[], chunks: KnowledgeChunk[]): MatchedChunk[];
    /**
     * Build a flat map: citation index → chunk.
     *
     * @returns Map where key is citation number and value is the matching chunk
     */
    buildIndexMap(chunks: KnowledgeChunk[]): Map<number, KnowledgeChunk>;
    /**
     * Find chunks that are NOT cited in the text (orphans).
     */
    findOrphans(citations: Citation[], chunks: KnowledgeChunk[]): KnowledgeChunk[];
}

/**
 * Knowledge-base citation parser for AI Assistant Core
 *
 * Parses [1] [2] citation markers in assistant text and
 * matches them against content chunks returned by the backend.
 */
export declare interface Citation {
    /** Raw marker text, e.g. "[1]" */
    marker: string;
    /** Numeric index, e.g. 1 */
    index: number;
    /** Start position in the source text */
    start: number;
    /** End position in the source text */
    end: number;
}

/** A knowledge-base citation entry (Phase 2 预留). */
declare interface CitationItem {
    docName: string;
    page: number;
    section: string;
    content: string;
}

export declare class CitationParser {
    /** Regex for citation markers: [1], [12], etc. */
    private static readonly MARKER_RE;
    /**
     * Extract all citation markers from a text block.
     *
     * @param text — source text containing [1], [2], … markers
     * @returns ordered list of citations with positions
     */
    parse(text: string): Citation[];
    /**
     * Strip citation markers from text, returning clean text and a mapping.
     *
     * @returns `{ text: string, citations: Citation[] }`
     */
    strip(text: string): {
        text: string;
        citations: Citation[];
    };
    /**
     * Replace citation markers with custom formatter output.
     *
     * @param text    — source text
     * @param format  — callback receiving citation index, returns replacement string
     */
    replace(text: string, format: (index: number) => string): string;
}

/** Clamp a number between min and max (inclusive). */
export declare function clamp(value: number, min: number, max: number): number;

declare interface ClarifyOption {
    value: string;
    label: string;
    description?: string;
}

/** A clarification request asking the user to choose or answer. */
export declare interface ClarifyPart {
    kind: 'clarify';
    requestId: string;
    questions: ClarifyQuestion[];
}

export declare interface ClarifyQuestion {
    id: string;
    header: string;
    question: string;
    type: 'single_select' | 'multi_select' | 'text' | 'confirm';
    required: boolean;
    options: ClarifyOption[];
}

export declare type ClosedChartData = {
    kind: 'radar';
    datasetRef: string;
    indicators: Array<{
        name: string;
        max: number;
    }>;
    series: Array<{
        name: string;
        values: number[];
    }>;
} | {
    kind: 'cartesian';
    datasetRef: string;
    categories: ChartValue[];
    series: CartesianSeries[];
    mode: 'standard' | 'grouped' | 'stacked';
    area: boolean;
    xName: string;
    yNames: string[];
    /** Present only for a dual-axis chart: two y-scales on one plot. */
    axes?: 'dual';
    /** Dual only, left then right. Always non-empty — the renderer never
     * falls back to a raw column id, because an unlabelled scale is exactly
     * what makes a dual-axis chart misread. */
    axisNames?: [string, string];
} | {
    kind: 'scatter';
    datasetRef: string;
    series: ScatterSeries[];
    xName: string;
    yName: string;
} | {
    kind: 'pie';
    datasetRef: string;
    items: Array<{
        name: ChartValue;
        value: number;
    }>;
    nameField: string;
    valueField: string;
};

/**
 * Runtime coercion for untrusted attachment payloads (stream/history/list).
 * Returns a typed ref, or null when the payload violates the contract.
 * Callers MUST skip+warn, never throw, on invalid entries (06 spec §3.3).
 */
export declare function coerceArtifactRef(value: unknown): PublicArtifactRef | null;

/** Runtime coercion for the preview manifest; null on contract violation. */
export declare function coercePagePreviewManifest(value: unknown): PagePreviewManifest | null;

/**
 * A result-table / glossary column. Semantic fields (displayName/role/...) come
 * from the backend semantic layer — never re-derived on the client.
 */
declare interface ColumnDef {
    key: string;
    title: string;
    type?: string;
    /** Business-friendly Chinese name, e.g. "设备温度". */
    displayName?: string;
    /** Semantic role for analysis/charting. */
    role?: ColumnRole;
    /** Human description, e.g. "通信状态(0正常/1异常)". */
    description?: string;
    /** Display unit, e.g. "℃", "件". */
    unit?: string;
    /** Sensitive columns are stripped before the LLM; flagged here for UI only. */
    sensitive?: boolean;
}

/** Semantic role of a result column (drives glossary + analysis). */
declare type ColumnRole = 'dimension' | 'metric' | 'time';

/** Numeric revision comparison for family/revision UI (Phase 3). */
export declare function compareRevision(a: PublicArtifactRef, b: PublicArtifactRef): number;

export declare interface Conversation {
    id: string;
    title: string;
    systemCode: string;
    sceneCode?: string;
    modelCode?: string;
    status: string;
    createdAt: string;
    updatedAt: string;
}

export declare interface CreateAiAssistantOptions {
    systemCode: string;
    scene?: string;
    /** Preferred shell layout. Responsive resolution never overwrites this value. */
    defaultPresentation?: AssistantPresentation;
    /** @deprecated Use `defaultPresentation`. */
    defaultMode?: AiOpenMode;
    theme?: {
        mode?: AiThemeMode;
        primaryColor?: string;
        brandColors?: {
            primary: string;
            accent: string;
        };
    };
    apiBaseUrl: string;
    apiBaseUrlMock?: string;
    modelCode?: string;
    modelOptions?: ModelOption[];
    userProvider?: () => UserInfo;
    contextProvider?: () => PageContext;
    requestHeaders?: () => Record<string, string>;
    transport?: TransportConfig;
    features?: FeaturesConfig;
    i18n?: I18nConfig;
    onError?: (err: Error) => void;
    onEvent?: (event: unknown) => void;
}

/**
 * Create a typed AI Assistant error.
 *
 * @param code      — error code from ErrorCodes
 * @param message   — human-readable message
 * @param retriable — override default retriability (optional)
 * @param details   — extra context for debugging
 */
export declare function createError(code: ErrorCode, message: string, retriable?: boolean, details?: unknown): AiAssistantError;

export declare function createInitialState(overrides?: Partial<AssistantState>): AssistantState;

export declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, waitMs: number, immediate?: boolean): DebouncedFunction<T>;

export declare interface DebouncedFunction<T extends (...args: unknown[]) => unknown> {
    (...args: Parameters<T>): ReturnType<T> | undefined;
    cancel: () => void;
    flush: () => ReturnType<T> | undefined;
}

export declare function deepClone<T>(value: T): T;

/** Promise-based sleep. */
export declare function delay(ms: number): Promise<void>;

/** Deserialize and merge with fresh initial state defaults. */
export declare function deserialize(data: unknown): AssistantState | null;

/** Convenience: deserialize from JSON string. */
export declare function deserializeFromString(json: string): AssistantState | null;

declare interface DshPresentationProjection {
    mode: 'answer' | 'partial' | 'empty' | 'clarification';
    answerText: string;
    evidenceIds: string[];
    citations: Array<{
        evidenceId: string;
        datasetId: string;
        artifactId: string;
        rowIndex: number;
        column: string;
    }>;
    cards: Array<{
        kind: 'table' | 'empty';
        evidenceId: string;
        datasetId: string;
        artifactId: string;
        columns: string[];
        columnLabels?: Record<string, string>;
        previewRows: Array<Array<string | number | boolean | null>>;
        rowCount: number;
        truncated: boolean;
    } | {
        kind: 'chart';
        evidenceId: string;
        datasetId: string;
        artifactId: string;
        chartKind: Exclude<ChartKind, ''>;
        title?: string;
        xColumn: string;
        yColumns: string[];
        seriesColumn?: string;
        radarMax?: number;
        /** dual-axis only: the single measure drawn against the right axis. */
        lineColumns?: string[];
        /** dual-axis only: the label and unit each axis carries. */
        axisUnits?: {
            left: string;
            right: string;
        };
        columns: string[];
        columnLabels?: Record<string, string>;
        previewRows: Array<Array<string | number | boolean | null>>;
        rowCount: number;
        truncated: boolean;
    } | {
        kind: 'metric';
        evidenceId: string;
        datasetId: string;
        artifactId: string;
        label: string;
        value: string;
        unit?: string;
    }>;
    /** Model-selected top-to-bottom narrative/card order. Optional for legacy replay. */
    layout?: Array<{
        kind: 'markdown';
        text: string;
    } | {
        kind: 'card';
        cardIndex: number;
    }>;
    /** Delivery artifact hints (immutable refs); optional for legacy replay. */
    attachments?: PublicArtifactRef[];
    /** Exact governed URLs selected from successful current-turn web_search results. */
    sources?: DshWebSource[];
    limitations: string[];
    questions: string[];
}

/** DSH-owned, evidence-bound presentation projection. */
declare interface DshWebSource {
    url: string;
    title?: string;
    snippet?: string;
    publishedAt?: string;
}

export declare type ErrorCode = keyof typeof ErrorCodes;

/**
 * Error system for AI Assistant Core
 *
 * All error codes with retriability classification.
 */
export declare const ErrorCodes: {
    readonly NETWORK: "NETWORK";
    readonly TIMEOUT: "TIMEOUT";
    readonly AUTH: "AUTH";
    readonly FORBIDDEN: "FORBIDDEN";
    readonly RATE_LIMIT: "RATE_LIMIT";
    readonly MODEL_UNAVAILABLE: "MODEL_UNAVAILABLE";
    readonly TOOL_FAILED: "TOOL_FAILED";
    readonly PARSE: "PARSE";
    readonly ABORTED: "ABORTED";
    readonly UNKNOWN: "UNKNOWN";
};

export declare type ExecutionMode = 'parallel' | 'serial';

export declare interface ExecutionPlan {
    mode: ExecutionMode;
    steps: Array<{
        toolName: string;
        args: Record<string, unknown>;
        title?: string;
    }>;
}

export declare interface FeaturesConfig {
    enableVoice?: boolean;
    enableFileUpload?: boolean;
    enableFullscreen?: boolean;
    enableDrawer?: boolean;
    enableKnowledge?: boolean;
    enableActionConfirm?: boolean;
}

/** Why a run finished. */
declare type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'cancelled' | 'error';

/** Format a Date or timestamp to locale string. */
export declare function formatDate(input: Date | number | string, options?: Intl.DateTimeFormatOptions): string;

/** Format a duration in milliseconds to human-readable string. */
export declare function formatDuration(ms: number): string;

/**
 * Utility functions for AI Assistant Core
 *
 * Pure TypeScript — no framework dependencies.
 */
/** Generate a short unique id with an optional prefix. */
export declare function generateId(prefix?: string): string;

export declare interface I18nConfig {
    locale?: string;
    messages?: Record<string, string>;
}

/** Factory for a blank accumulator. */
export declare function initialState(): ReduceState;

export declare interface InputAnswer {
    questionId: string;
    values: string[];
}

/** A clarification response continued as a regular DSH turn. */
export declare interface InputResponseRequest {
    action: 'accept' | 'decline' | 'cancel';
    answers: InputAnswer[];
}

/** Type of an analysis insight (drives icon/severity on the client). */
declare type InsightType = 'trend' | 'outlier' | 'comparison' | 'summary' | 'anomaly';

/**
 * Check whether an error represents a user abort.
 */
export declare function isAborted(error: unknown): boolean;

export declare function isArray<T = unknown>(value: unknown): value is T[];

/** A verified original may be downloaded while its preview is still building. */
export declare function isArtifactDownloadable(ref: PublicArtifactRef): boolean;

/** True when the manifest grants preview and the ref is usable. */
export declare function isArtifactPreviewable(ref: PublicArtifactRef): boolean;

/** True once an artifact reached a state that never regresses. */
export declare function isArtifactTerminal(status: PublicArtifactStatus): boolean;

export declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;

export declare function isNumber(value: unknown): value is number;

export declare function isObject(value: unknown): value is Record<string, unknown>;

/**
 * Check whether an error is retriable.
 */
export declare function isRetriable(error: unknown): boolean;

export declare function isString(value: unknown): value is string;

declare interface JsonObject {
    [key: string]: JsonValue;
}

/**
 * RFC 6902 JSON Patch op (subset) used by `card.patch` for in-place updates.
 * Kept narrow on purpose; the transitional path may instead re-send the full
 * `card` with the same id.
 */
declare interface JsonPatchOp {
    op: 'add' | 'remove' | 'replace';
    path: string;
    value?: string | number | boolean | null | Record<string, unknown> | unknown[];
}

declare type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];

export declare interface KnowledgeChunk {
    /** Chunk index (1-based, matching citation numbers) */
    index: number;
    /** Source title or document name */
    title: string;
    /** Chunk text content */
    content: string;
    /** Optional source URL or identifier */
    source?: string;
    /** Relevance score (0–1) */
    score?: number;
}

/** Return the stable legacy mode used by deprecated public callbacks. */
export declare function legacyModeFromCanonical(visibility: AssistantVisibility, presentation: AssistantPresentation): AiOpenMode;

export declare interface MatchedChunk extends KnowledgeChunk {
    /** Citation markers that reference this chunk */
    citedBy: number[];
}

/** Internal indexes for the current (last) message. */
declare interface MessageIndexes {
    /** partId → latest writable index in `parts` for text/reasoning parts */
    byPartId: Map<string, number>;
    /** toolCallId → index in `parts` for tool parts */
    byToolCallId: Map<string, number>;
    /** card.id → index in `parts` for card parts */
    byCardId: Map<string, number>;
    /** planId -> index in `parts`; later snapshots replace the first one in place. */
    byPlanId: Map<string, number>;
    /** requestId -> clarification index; repeated input.required updates in place. */
    byRequestId: Map<string, number>;
}

export declare type MessageRole = 'user' | 'assistant' | 'system' | 'tool';

/**
 * Complete snapshot of a single assistant message at a point in time.
 * Parts are ordered by the `seq` of their originating start event.
 */
export declare interface MessageSnapshot {
    messageId: string;
    conversationId: string;
    status: RunStatus;
    parts: Part[];
    usage?: Usage;
    finishReason?: FinishReason;
    /** Wall-clock latency reported by the backend on `run.finish`. */
    latencyMs?: number;
    /** AskData turn observability restored from persisted v2 event metadata. */
    observation?: AskDataObservation;
    /** Backend run error metadata, preserved so hosts can show retry affordances. */
    error?: {
        code: string;
        message: string;
        retriable: boolean;
    };
    /** Timestamp (ms) when `run.start` was received. */
    startedAt: number;
}

export declare type MessageStatus = 'pending' | 'streaming' | 'success' | 'failed';

export declare type MessageType = 'text' | 'markdown' | 'chart' | 'table' | 'tool' | 'error' | 'metric' | 'action' | 'source' | 'v2_event';

/** A single KPI / metric tile. Multiple tiles share one metric card. */
declare interface MetricItem {
    label: string;
    value: string | number;
    unit?: string;
    trend?: MetricTrend;
    /** Display format hint, e.g. "percent", "currency", "integer". */
    format?: string;
}

/** A trend annotation on a metric value. */
declare interface MetricTrend {
    value: number;
    direction: TrendDirection;
    label?: string;
}

export declare interface ModelOption {
    code: string;
    name: string;
    supportStream: boolean;
    supportToolCall: boolean;
    bestFor?: Array<'analysis' | 'knowledge' | 'general'>;
    maxTokens?: number;
}

export declare interface OrchestratorOptions {
    registry: ToolRegistry;
    onStepStart?: (step: ToolStep) => void;
    onStepProgress?: (stepId: string, percent: number, message?: string) => void;
    onStepComplete?: (step: ToolStep) => void;
    onStepError?: (step: ToolStep, error: Error) => void;
}

export declare interface PageContext {
    systemCode: string;
    pageCode: string;
    pageName?: string;
    routePath: string;
    selectedDeviceIds?: string[];
    selectedWorkOrderIds?: string[];
    selectedScheduleDate?: string;
    filters?: Record<string, unknown>;
    extras?: Record<string, unknown>;
}

/**
 * Page preview manifest served by `GET .../artifacts/{id}/preview` (02 §7).
 * `defaultPage` is 1-based and must sit within [1, pageCount].
 */
export declare interface PagePreviewManifest {
    schemaVersion: '1';
    artifactId: string;
    revision: number;
    pageCount: number;
    defaultPage: number;
    pages: Array<{
        page: number;
        width: number;
        height: number;
        checksum: string;
        thumbnailAvailable: boolean;
    }>;
}

/** Discriminated union of all renderable parts of an assistant turn. */
export declare type Part = TextPart | ReasoningPart | ToolPart | CardPart | StagePart | PlanPart | ActionPart | ClarifyPart | PresentationPart | ArtifactPart;

/** Latest backend-owned execution-plan snapshot for this turn. */
export declare interface PlanPart {
    kind: 'plan';
    runId: string;
    messageId: string;
    planId: string;
    planName: string;
    state: string;
    version: number;
    tasks: PlanTraceTask[];
}

/** One task in the request-local plan trace exposed only through the trace lane. */
declare interface PlanTraceTask {
    id: string;
    name: string;
    dependsOn: string[];
    state: string;
    priority?: 'high' | 'medium' | 'low';
    outcome?: string;
    toolCallId?: string;
    toolName?: string;
}

export declare interface PluginConfig {
    systemCode: string;
    defaultMode: string;
    themeStrategy: string;
    themePreset: string;
    primaryColor: string;
    defaultModelCode: string;
    enableFullscreen: boolean;
    enableDrawer: boolean;
    enableKnowledge: boolean;
    rateLimitPerHour: number;
}

/** Authoritative presentation event metadata retained alongside renderable cards. */
declare interface PresentationPart {
    kind: 'presentation';
    projection: DshPresentationProjection;
}

/** Closed vNext progress lifecycle vocabulary. */
declare type ProgressStatus = 'STARTED' | 'PROGRESSING' | 'RETRYING' | 'AWAITING_INPUT' | 'COMPLETED' | 'FAILED' | 'CANCELLED';

/**
 * Validate and project the neutral protocol spec without accepting renderer
 * options, formatter functions, or HTML. Every plotted value is read directly
 * from the same immutable row projection used by the fallback table.
 */
export declare function projectChartSpec(input: unknown): ChartProjection;

/**
 * Artifact workbench contracts (public, browser-safe).
 *
 * Field shapes mirror `docs/2026-08-28-sidebar-artifact-workbench/02-contract-storage-api.md`
 * §2/§7. Pure TypeScript, zero dependencies, shared by reducer/store/viewers.
 */
/** Delivery kinds surfaced by the artifact workbench. */
export declare type PublicArtifactKind = 'presentation' | 'document' | 'spreadsheet' | 'image' | 'text' | 'code' | 'data' | 'archive' | 'unknown';

export declare type PublicArtifactProgressStatus = Extract<PublicArtifactStatus, 'queued' | 'generating' | 'validating' | 'previewing'>;

/** Minimal public projection of one immutable artifact version (02 §2). */
export declare interface PublicArtifactRef {
    schemaVersion: '1';
    artifactId: string;
    artifactFamilyId?: string;
    revision?: number;
    kind: PublicArtifactKind;
    format: string;
    status: PublicArtifactStatus;
    displayName: string;
    mimeType?: string;
    size?: number;
    checksum?: string;
    originMessageId?: string;
    deliveryGroupId?: string;
    supersedesArtifactId?: string;
    preview: {
        strategy: 'pages' | 'image' | 'markdown' | 'text' | 'table' | 'none';
        pageCount?: number;
        state?: 'pending' | 'ready' | 'failed' | 'unavailable';
        failure?: {
            code: string;
            safeMessage: string;
        };
    };
    capabilities: Array<'preview' | 'download' | 'revise'>;
    createdAt: string;
    expiresAt: string;
}

/** Artifact lifecycle statuses (02 §2). */
export declare type PublicArtifactStatus = 'queued' | 'generating' | 'validating' | 'previewing' | 'ready' | 'failed' | 'cancelled' | 'expired';

export declare type PublicArtifactTerminalStatus = Extract<PublicArtifactStatus, 'ready' | 'failed' | 'cancelled' | 'expired'>;

/** DeepSeek reasoning-effort levels accepted by the gateway contract. */
export declare type ReasoningEffort = 'low' | 'medium' | 'high';

/** Safe public analysis summary. Raw provider chain-of-thought is never materialized. */
export declare interface ReasoningPart {
    kind: 'reasoning';
    partId: string;
    text: string;
}

/**
 * Pure fold: given the current accumulator state and one v2 `StreamEvent`,
 * return the next state. Never mutates `state`. Unknown event types are
 * ignored silently.
 */
export declare function reduce(state: ReduceState, event: StreamEvent): ReduceState;

/**
 * Convenience fold: reduce an entire ordered sequence of events from scratch.
 * Equivalent to `events.reduce(reduce, initialState())`.
 */
export declare function reduceAll(events: StreamEvent[]): ReduceState;

export declare function reducer(state: AssistantState, action: StateAction): AssistantState;

/**
 * Accumulator state for `reduce`. Plain / serialisable (Maps are the only
 * non-JSON-native field; callers that need JSON-round-trip should serialise
 * them separately).
 */
export declare interface ReduceState {
    /** Ordered list of assistant messages produced so far. */
    messages: MessageSnapshot[];
    /** Last `seq` accepted (used for duplicate/OOO filtering). */
    lastSeq: number;
    /* Excluded from this release type: _idx */
}

export declare interface RegisteredTool {
    definition: ToolDefinition;
    executor: ToolExecutor;
}

/**
 * Resolve layout for the current viewport without mutating user preference.
 * Below 900px every preferred layout becomes the full-viewport workspace.
 */
export declare function resolveAssistantPresentation(preferred: AssistantPresentation, viewportWidth: number): AssistantPresentation;

/**
 * Viewer strategy for a ref. A declared `preview.strategy` wins when it is
 * meaningful; otherwise the format whitelist decides (02 §6.1). Unknown
 * formats degrade to `none` (metadata + download only).
 */
export declare function resolvePreviewStrategy(ref: PublicArtifactRef): PublicArtifactRef['preview']['strategy'];

/** Risk level for a proposed write action (Action Center 二次确认). */
declare type RiskLevel = 'safe' | 'caution' | 'danger';

/** A single result row: column key → cell value. */
declare type Row = Record<string, string | number | boolean | null>;

/** Status of an assistant message lifetime (v2 reducer). */
export declare type RunStatus = 'streaming' | 'complete' | 'cancelled' | 'error';

export declare interface ScatterSeries {
    name: string;
    points: Array<[number, number]>;
}

/** Serialize state to JSON-safe object (excludes transient stream fields). */
export declare function serialize(state: AssistantState): SerializedState;

export declare interface SerializedState {
    version: number;
    state: Omit<AssistantState, 'connection' | 'turnPhase' | 'streamStatus' | 'lastSeq' | 'lastHeartbeatAt' | 'reconnectAttempt' | 'hasError' | 'lastError'>;
}

/** Convenience: serialize to JSON string. */
export declare function serializeToString(state: AssistantState): string;

/**
 * A data-source provenance entry. Discriminated on `kind` to remove the v1
 * polymorphism where `table` was sometimes a real table, sometimes a tool name.
 */
declare type SourceItem = {
    kind: 'table';
    name: string;
    query?: string;
    rowCount: number | null;
    durationMs: number;
    timestamp: string;
} | {
    kind: 'tool';
    name: string;
    query?: string;
    rowCount: number | null;
    durationMs: number;
    timestamp: string;
} | {
    kind: 'web';
    url: string;
    title?: string;
    snippet?: string;
    publishedAt?: string;
};

export declare interface SourceRef {
    table: string;
    query: string;
    rowCount: number;
    durationMs: number;
    timestamp: string;
}

export declare class SseClient {
    private reader;
    private abortCtrl;
    private heartbeatTimer;
    private timeoutTimer;
    private reconnect;
    private lastSeq;
    private buffer;
    private status;
    private options;
    private destroyed;
    /** Current connection status */
    get connectionStatus(): SseConnectionStatus;
    /** Current reconnect attempt count */
    get reconnectAttempt(): number;
    /** Last acknowledged sequence number */
    get currentSeq(): number;
    start(options: SseClientOptions): Promise<void>;
    /** Abort the current connection (does not destroy). */
    abort(): void;
    /** Permanently destroy — no further connections allowed. */
    destroy(): void;
    private _connect;
    private _processChunk;
    private _processLine;
    private _parseEvent;
    private _startHeartbeat;
    private _handleHeartbeat;
    private _handleError;
    private _scheduleReconnect;
    private _resetReconnect;
    private _setStatus;
    private _cancelReader;
    private _clearTimers;
    private _clearHeartbeat;
    private _clearReconnectTimer;
}

export declare interface SseClientOptions {
    /** Target URL */
    url: string;
    /** POST body */
    body: unknown;
    /** Request headers */
    headers: Record<string, string>;
    /** Abort signal for cancellation */
    signal?: AbortSignal;
    /** Called for every parsed stream event */
    onEvent?: (event: unknown) => void;
    /** Called on unrecoverable errors */
    onError?: (error: Error) => void;
    /** Called when connection status changes */
    onStatusChange?: (status: SseConnectionStatus) => void;
    /** Heartbeat timeout in ms (default 15000) */
    heartbeatMs?: number;
    /** Request timeout in ms (default 180000) */
    timeoutMs?: number;
    /** Reconnect config */
    reconnect?: {
        max: number;
        baseMs: number;
        maxMs?: number;
        resetOnSuccessMs?: number;
    };
    /** Last acknowledged sequence number (for resume) */
    lastSeq?: number;
    /**
     * Resume hook, consulted ONLY when re-establishing a dropped stream (i.e. on a
     * reconnect attempt, never the initial connect). Returns the additive body
     * fields that let the backend replay from where the client left off —
     * typically `{ conversationId, messageId, lastSeq }`. These are merged over the
     * base body so the same `/chat/stream` endpoint serves both fresh sends and
     * resumes (the 14-endpoint contract stays frozen). Any `lastSeq` returned here
     * takes precedence over the client's internally tracked seq.
     */
    resume?: () => Record<string, unknown> | undefined;
}

/**
 * SSE Client for AI Assistant Core
 *
 * Uses fetch + ReadableStream (not EventSource) to support:
 * - POST requests with custom headers
 * - AbortController cancellation
 * - Custom event parsing and heartbeat handling
 * - Sequence-based ack / resume protocol
 * - Exponential backoff reconnection
 */
export declare type SseConnectionStatus = 'idle' | 'connecting' | 'streaming' | 'reconnecting' | 'closed' | 'error';

/** A deterministic pipeline stage progress notification (v2.1 additive). */
export declare interface StagePart {
    kind: 'stage';
    stageId: string;
    /** Source event sequence; current-stage selection must use this, not array order. */
    seq?: number;
    label: string;
    /** Open-enum phase hint, e.g. 'schema-linking' | 'dsl-gen' | 'execute'. */
    phase?: string;
    progress?: number;
    /** Correlation id shared with the producing tool / cards (v2.1). */
    group?: string;
    /** Stable vNext identity; legacy stage events omit it. */
    progressId?: string;
    /** Stable capability / plan step identity. */
    stepId?: string;
    status?: ProgressStatus;
    attempt?: number;
    elapsedMs?: number;
    safeSummary?: string;
    occurredAt?: string;
}

export declare type StateAction = {
    type: 'OPEN';
    presentation?: AssistantPresentation;
    mode?: AiOpenMode;
} | {
    type: 'CLOSE';
} | {
    type: 'TOGGLE';
} | {
    type: 'SET_VISIBILITY';
    visibility: AssistantVisibility;
} | {
    type: 'SWITCH_PRESENTATION';
    presentation: AssistantPresentation;
    viewportWidth?: number;
} | {
    type: 'RESOLVE_PRESENTATION';
    viewportWidth: number;
}
/** @deprecated Dispatch `SWITCH_PRESENTATION`. */
| {
    type: 'SWITCH_MODE';
    mode: AiOpenMode;
} | {
    type: 'SET_CONNECTION';
    connection: AssistantConnection;
} | {
    type: 'SET_TURN_PHASE';
    phase: AssistantTurnPhase;
} | {
    type: 'SET_DRAFT';
    draft: string;
} | {
    type: 'SET_SCROLL_ANCHOR';
    conversationId: string | null;
    top: number;
    pinned: boolean;
} | {
    type: 'SET_FOCUSED_CONTROL';
    id: string | null;
} | {
    type: 'SELECT_ARTIFACT';
    id: string | null;
} | {
    type: 'SET_POSITION';
    x: number;
    y: number;
} | {
    type: 'SET_SIZE';
    width: number;
    height: number;
} | {
    type: 'SET_SYSTEM_CODE';
    systemCode: string;
} | {
    type: 'SET_MODEL_CODE';
    modelCode: string;
} | {
    type: 'SET_CONVERSATION';
    id: string | null;
} | {
    type: 'ADD_CONVERSATION';
    conversation: Conversation;
} | {
    type: 'SET_CONVERSATIONS';
    conversations: Conversation[];
} | {
    type: 'APPEND_MESSAGE';
    conversationId: string;
    message: AssistantMessage;
} | {
    type: 'APPEND_DELTA';
    conversationId: string;
    messageId: string;
    delta: string;
} | {
    type: 'UPDATE_MESSAGE_STATUS';
    conversationId: string;
    messageId: string;
    status: MessageStatus;
} | {
    type: 'SET_MESSAGES';
    conversationId: string;
    messages: AssistantMessage[];
} | {
    type: 'APPEND_TOOL_STEP';
    messageId: string;
    step: ToolStep;
} | {
    type: 'UPDATE_TOOL_STEP';
    messageId: string;
    stepId: string;
    patch: Partial<ToolStep>;
} | {
    type: 'SET_STREAM_STATUS';
    status: AssistantState['streamStatus'];
} | {
    type: 'SET_LAST_SEQ';
    seq: number;
} | {
    type: 'SET_HEARTBEAT';
    ts: number;
} | {
    type: 'INCREMENT_RECONNECT';
} | {
    type: 'RESET_RECONNECT';
} | {
    type: 'SET_THEME';
    mode: AiThemeMode;
} | {
    type: 'SET_PRIMARY_COLOR';
    color: string;
} | {
    type: 'SET_ERROR';
    error: string | null;
} | {
    type: 'HYDRATE';
    state: Partial<AssistantState>;
};

/**
 * The full v2 stream-event union. Discriminated on `type`; every member carries
 * a monotonic `seq`.
 */
declare type StreamEvent = {
    type: 'run.start';
    seq: number;
    conversationId: string;
    messageId: string;
} | {
    type: 'run.finish';
    seq: number;
    reason: FinishReason;
    usage: Usage;
    latencyMs: number;
} | {
    type: 'run.error';
    seq: number;
    code: string;
    message: string;
    retriable: boolean;
} | {
    type: 'text.start';
    seq: number;
    partId: string;
} | {
    type: 'text.delta';
    seq: number;
    partId: string;
    delta: string;
} | {
    type: 'text.end';
    seq: number;
    partId: string;
}
/** Evidence-checked but provisional narrative, replaced by final presentation. */
| {
    type: 'answer.preview';
    seq: number;
    previewId: string;
    text: string;
} | {
    type: 'narration.start';
    seq: number;
    partId: string;
} | {
    type: 'narration.delta';
    seq: number;
    partId: string;
    delta: string;
} | {
    type: 'narration.end';
    seq: number;
    partId: string;
} | {
    type: 'reasoning.start';
    seq: number;
    partId: string;
} | {
    type: 'reasoning.delta';
    seq: number;
    partId: string;
    delta: string;
} | {
    type: 'reasoning.end';
    seq: number;
    partId: string;
} | {
    type: 'tool.start';
    seq: number;
    toolCallId: string;
    toolName: string;
    group?: string;
} | {
    type: 'tool.input.delta';
    seq: number;
    toolCallId: string;
    delta: string;
} | {
    type: 'tool.input';
    seq: number;
    toolCallId: string;
    input: JsonObject;
} | {
    type: 'tool.executing';
    seq: number;
    toolCallId: string;
} | {
    type: 'tool.output';
    seq: number;
    toolCallId: string;
    output: ToolOutput;
    status: ToolStatus;
} | {
    type: 'tool.error';
    seq: number;
    toolCallId: string;
    error: string;
    diagnostic?: ToolFailureDiagnostic;
} | {
    type: 'presentation';
    seq: number;
    payload: DshPresentationProjection;
} | {
    type: 'stage';
    seq: number;
    stageId: string;
    label: string;
    /** Open-enum phase hint, e.g. 'schema-linking' | 'dsl-gen' | 'execute'. */
    phase?: string;
    progress?: number;
    group?: string;
    progressId?: string;
    stepId?: string;
    status?: ProgressStatus;
    attempt?: number;
    elapsedMs?: number;
    safeSummary?: string;
    occurredAt?: string;
} | {
    type: 'plan.trace';
    seq: number;
    runId: string;
    messageId: string;
    planId: string;
    planName: string;
    state: string;
    version: number;
    tasks: PlanTraceTask[];
} | {
    type: 'card';
    seq: number;
    id: string;
    kind: CardKind;
    data: CardData;
    status?: string;
    group?: string;
    transient?: boolean;
    placement?: CardPlacement;
    anchorId?: string;
} | {
    type: 'card.patch';
    seq: number;
    id: string;
    patch: JsonPatchOp[];
} | {
    type: 'action.proposed';
    seq: number;
    actionId: string;
    title: string;
    summary?: string;
    riskLevel: RiskLevel;
    params: Record<string, string | number | boolean | null>;
} | {
    type: 'clarify';
    seq: number;
    requestId: string;
    questions: ClarifyQuestion[];
};

/** Convenience: the closed set of v2 event `type` discriminants. */
declare type StreamEventType = StreamEvent['type'];

/** A structured follow-up suggestion (programmatically routable). */
declare interface SuggestionItem {
    text: string;
    /** Optional intent code for programmatic routing. */
    intent?: string;
    /** Optional pre-filled params for the routed intent. */
    params?: Record<string, string | number | boolean | null>;
}

/**
 * A result-table column. The semantic fields (displayName/description/role) are
 * optional and backward-compatible: when the backend populates them from the
 * registered column metadata (ColumnConfigDTO) they drive the 字段说明 glossary
 * and the table-header tooltip; when absent the table renders exactly as before.
 */
export declare interface TableColumn {
    key: string;
    title: string;
    type?: string;
    /** Business-friendly Chinese name (e.g. "虚拟温度") for the glossary. */
    displayName?: string;
    /** Human description of the column (e.g. "设备ID", "通信状态(0正常/1异常)"). */
    description?: string;
    /** Semantic role for analysis: dimension / metric / time. */
    role?: 'dimension' | 'metric' | 'time';
}

export declare interface TableResult {
    columns: TableColumn[];
    rows: Record<string, unknown>[];
    total?: number;
}

/** A streamed text block (main reply or continuation). */
export declare interface TextPart {
    kind: 'text';
    partId: string;
    text: string;
    provisional?: boolean;
}

export declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, waitMs: number, options?: {
    leading?: boolean;
    trailing?: boolean;
}): ThrottledFunction<T>;

export declare interface ThrottledFunction<T extends (...args: unknown[]) => unknown> {
    (...args: Parameters<T>): ReturnType<T> | undefined;
    cancel: () => void;
}

export declare interface ToolCall {
    name: string;
    args: Record<string, unknown>;
    result?: unknown;
    status: 'pending' | 'running' | 'success' | 'error';
    durationMs?: number;
}

export declare interface ToolDefinition {
    name: string;
    description: string;
    parameters: Record<string, unknown>;
}

export declare type ToolExecutor = (args: Record<string, unknown>) => Promise<unknown>;

/** Bounded server-classified failure facts; never raw provider/tool output. */
declare interface ToolFailureDiagnostic {
    failureType?: 'configuration' | 'transient_model' | 'planning' | 'execution';
    retryable?: boolean;
    automaticRecoveryAttempted?: boolean;
    retryExhausted?: boolean;
    replanAllowed?: boolean;
    diagnosticCode?: string;
    budgetExceeded?: boolean;
    inputRequired?: boolean;
    terminal?: boolean;
}

export declare class ToolOrchestrator {
    private readonly registry;
    private readonly onStepStart?;
    private readonly onStepComplete?;
    private readonly onStepError?;
    constructor(options: OrchestratorOptions);
    /**
     * Execute a plan of tool steps.
     *
     * - `serial`:  steps run one after another; if one fails, abort the rest.
     * - `parallel`: steps run concurrently; all results collected regardless of individual failures.
     */
    execute(plan: ExecutionPlan): Promise<ToolStep[]>;
    /** Execute a single tool step. */
    executeSingle(toolName: string, args: Record<string, unknown>, title?: string): Promise<ToolStep>;
    private executeSerial;
    private executeParallel;
}

/**
 * Structured tool result (replaces v1's perpetually-null `result`). Always a
 * populated object describing what the tool did.
 */
declare interface ToolOutput {
    executed: boolean;
    rowCount?: number;
    durationMs?: number;
    /** Optional human-readable summary of the tool outcome. */
    summary?: string;
    /** Optional structured payload (kept open for tool-specific extras). */
    data?: Record<string, unknown>;
}

/** A tool invocation with full lifecycle state. */
export declare interface ToolPart {
    kind: 'tool';
    toolCallId: string;
    toolName: string;
    status: ToolPartStatus;
    /** Correlation id shared with the result cards / stages of this tool call (v2.1). */
    group?: string;
    /** Accumulated raw JSON string of the input (from `tool.input.delta`). */
    inputRaw?: string;
    /** Authoritative parsed input (from `tool.input`). */
    input?: JsonObject;
    output?: ToolOutput;
    outputStatus?: ToolStatus;
    error?: string;
    diagnostic?: ToolFailureDiagnostic;
}

/** Status of a tool call across its state machine. */
export declare type ToolPartStatus = 'pending' | 'input-streaming' | 'input-ready' | 'executing' | 'output-available' | 'output-error';

export declare class ToolRegistry {
    private readonly tools;
    /** Register a tool with its definition and executor. */
    register(definition: ToolDefinition, executor: ToolExecutor): void;
    /** Unregister a tool by name. */
    unregister(name: string): boolean;
    /** Look up a registered tool. */
    get(name: string): RegisteredTool | undefined;
    /** Check whether a tool is registered. */
    has(name: string): boolean;
    /** List all registered tool names. */
    list(): string[];
    /** Get all definitions (for sending to LLM). */
    getDefinitions(): ToolDefinition[];
    /** Clear all registrations. */
    clear(): void;
}

/** Tool-call lifecycle status carried by `tool.output`. */
declare type ToolStatus = 'output-available' | 'output-error';

export declare interface ToolStep {
    stepId: string;
    toolName: string;
    title: string;
    status: 'pending' | 'running' | 'success' | 'error';
    args?: Record<string, unknown>;
    /** User-facing explanation of why this step is being run. Not hidden chain-of-thought. */
    reason?: string;
    /** Character offset in the assistant text where this tool step entered the turn. */
    contentOffset?: number;
    result?: unknown;
    durationMs?: number;
    message?: string;
    percent?: number;
}

export declare interface TransportConfig {
    type: 'sse' | 'ws';
    heartbeatMs?: number;
    timeoutMs?: number;
    reconnect?: {
        max: number;
        baseMs: number;
        maxMs?: number;
        resetOnSuccessMs?: number;
    };
    fetchFallback?: boolean;
}

/** Direction of a metric trend. */
declare type TrendDirection = 'up' | 'down' | 'flat';

/** Server view of one uploaded conversation attachment. */
export declare interface UploadedAttachment {
    id: string;
    name: string;
    contentType: string;
    size: number;
    /** text | unsupported | failed — whether the backend extracted text. */
    extractStatus: 'extracted' | 'unsupported' | 'failed';
}

/** Token usage, filled authoritatively on `run.finish` (fixes v1 durationMs=0). */
declare interface Usage {
    prompt: number;
    completion: number;
    total: number;
}

export declare interface UserInfo {
    userId: string;
    username: string;
    roles: string[];
    orgId?: string;
    areaPermissions?: string[];
    dataScope?: 'all' | 'org' | 'area' | 'self';
}

declare namespace v2 {
    export {
        StreamEvent,
        StreamEventType,
        Usage,
        FinishReason,
        ToolStatus,
        ProgressStatus,
        CardPlacement,
        ToolOutput,
        ToolFailureDiagnostic,
        JsonValue,
        JsonObject,
        PlanTraceTask,
        ClarifyOption,
        ClarifyQuestion,
        InputAnswer,
        InputResponseRequest,
        RiskLevel,
        JsonPatchOp,
        DshPresentationProjection,
        DshWebSource,
        CardData,
        CardKind,
        ColumnRole,
        ColumnDef,
        Row,
        ChartKind,
        ChartEncoding,
        ChartSpec,
        TrendDirection,
        MetricTrend,
        MetricItem,
        SourceItem,
        SuggestionItem,
        InsightType,
        AnalysisInsight,
        CitationItem
    }
}
export { v2 }

export { }