@frost1994/agentic-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,904 @@
+export declare interface ActionDescriptor {
+    actionId: string;
+    actionCode: string;
+    actionName: string;
+    description: string;
+    params: Record<string, unknown>;
+    needConfirm: boolean;
+    riskLevel: 'safe' | 'caution' | 'danger';
+}
+
+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): Promise<Conversation>;
+    listConversations(systemCode: string, page?: number, size?: number): Promise<Conversation[]>;
+    getMessages(conversationId: string): Promise<AssistantMessage[]>;
+    deleteConversation(conversationId: string): Promise<void>;
+    getSuggestions(systemCode: string, sceneCode?: string): Promise<string[]>;
+    confirmAction(actionId: string, confirm: boolean): Promise<void>;
+    listDataSources(): Promise<DataSourceItem[]>;
+    listTables(dataSourceCode: string): Promise<TableInfo[]>;
+    submitFeedback(messageId: string, rating: number, comment?: string): Promise<void>;
+    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);
+}
+
+/**
+ * Core protocol types for AI Assistant
+ */
+export declare type AiOpenMode = 'launcher' | 'floating' | 'drawer' | 'fullscreen' | 'focus-modal';
+
+export declare type AiThemeMode = 'system' | 'light' | 'dark' | 'custom';
+
+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;
+        };
+        sql?: {
+            sql: string;
+            dialect: 'mysql' | 'postgresql';
+            tables: string[];
+            estimatedRows: number;
+            isReadonly: boolean;
+            isSensitive: boolean;
+            data: TableResult;
+            explanation?: string;
+        };
+        errorCode?: string;
+        [key: string]: unknown;
+    };
+}
+
+export declare interface AssistantState {
+    /** UI visibility */
+    visible: boolean;
+    /** Current display mode */
+    mode: AiOpenMode;
+    /** Previous mode before switch (for back-navigation) */
+    previousMode: AiOpenMode | 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;
+}
+
+export declare interface ChartConfig {
+    type: 'bar' | 'line' | 'pie' | 'heatmap' | 'gantt' | 'scatter';
+    title: string;
+    data: unknown;
+    options?: Record<string, unknown>;
+}
+
+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;
+}
+
+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;
+
+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;
+    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 interface DataSourceItem {
+    code: string;
+    name: string;
+    type: string;
+    description?: string;
+}
+
+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;
+
+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 SQL_FORBIDDEN: "SQL_FORBIDDEN";
+    readonly SQL_SENSITIVE: "SQL_SENSITIVE";
+    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;
+    enableText2Sql?: boolean;
+    enableActionConfirm?: boolean;
+}
+
+/** 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>;
+}
+
+/**
+ * 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[];
+
+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;
+
+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;
+}
+
+export declare interface MatchedChunk extends KnowledgeChunk {
+    /** Citation markers that reference this chunk */
+    citedBy: number[];
+}
+
+export declare type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+
+export declare type MessageStatus = 'pending' | 'streaming' | 'success' | 'failed';
+
+export declare type MessageType = 'text' | 'markdown' | 'chart' | 'table' | 'tool' | 'error' | 'sql' | 'metric' | 'action' | 'source';
+
+export declare interface ModelOption {
+    code: string;
+    name: string;
+    supportStream: boolean;
+    supportToolCall: boolean;
+    bestFor?: Array<'text2sql' | '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>;
+}
+
+export declare interface PluginConfig {
+    systemCode: string;
+    defaultMode: string;
+    themeStrategy: string;
+    themePreset: string;
+    primaryColor: string;
+    defaultModelCode: string;
+    enableFullscreen: boolean;
+    enableDrawer: boolean;
+    enableKnowledge: boolean;
+    enableText2Sql: boolean;
+    rateLimitPerHour: number;
+}
+
+export declare function reducer(state: AssistantState, action: StateAction): AssistantState;
+
+export declare interface RegisteredTool {
+    definition: ToolDefinition;
+    executor: ToolExecutor;
+}
+
+/** 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, 'streamStatus' | 'lastSeq' | 'lastHeartbeatAt' | 'reconnectAttempt' | 'hasError' | 'lastError'>;
+}
+
+/** Convenience: serialize to JSON string. */
+export declare function serializeToString(state: AssistantState): string;
+
+export declare interface SourceRef {
+    table: string;
+    query: string;
+    rowCount: number;
+    durationMs: number;
+    timestamp: string;
+}
+
+export declare class SqlGuard {
+    private readonly sensitiveTables;
+    private readonly allowedOperations;
+    private readonly rejectComments;
+    private readonly rejectUnion;
+    private readonly readOnlyAccount;
+    constructor(options?: SqlGuardOptions);
+    /**
+     * Validate a SQL string against all guard rules.
+     *
+     * Checks (in order):
+     * 1. Read-only account enforcement
+     * 2. Comment detection (SQL injection vector)
+     * 3. UNION / stacked query detection
+     * 4. Operation type whitelist
+     * 5. Sensitive table access
+     */
+    validate(sql: string): SqlGuardResult;
+    /** Quick check: does the SQL contain any forbidden pattern? */
+    isSafe(sql: string): boolean;
+    /** Check if a whole word exists in the text. */
+    private _hasWord;
+    /** Detect the primary SQL operation (first keyword). */
+    private _detectOperation;
+    /** Count semicolons that are outside quoted string literals. */
+    private _countSemicolonsOutsideStrings;
+    private _escapeRegex;
+}
+
+export declare interface SqlGuardOptions {
+    /** Table names that are off-limits */
+    sensitiveTables?: string[];
+    /** Allowed SQL operations (default: ['SELECT']) */
+    allowedOperations?: string[];
+    /** Whether to reject SQL containing comments */
+    rejectComments?: boolean;
+    /** Whether to reject UNION / stacked queries */
+    rejectUnion?: boolean;
+    /** Whether this guard represents a read-only DB account */
+    readOnlyAccount?: boolean;
+}
+
+/**
+ * SQL Guard — client-side SQL validation for AI Assistant Core
+ *
+ * Detects dangerous patterns before sending SQL to the backend.
+ * This is a **defence-in-depth** layer; the backend must also enforce
+ * read-only constraints and parameterised queries.
+ */
+export declare interface SqlGuardResult {
+    /** Whether the SQL passes all checks */
+    allowed: boolean;
+    /** Human-readable reason when blocked */
+    reason?: string;
+    /** Sanitised SQL (if applicable) */
+    sanitizedSql?: 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 90000) */
+    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';
+
+export declare type StateAction = {
+    type: 'OPEN';
+    mode?: AiOpenMode;
+} | {
+    type: 'CLOSE';
+} | {
+    type: 'TOGGLE';
+} | {
+    type: 'SWITCH_MODE';
+    mode: AiOpenMode;
+} | {
+    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>;
+};
+
+/**
+ * StreamEvent union type — SSE protocol between frontend and backend
+ */
+export declare type StreamEvent = {
+    type: 'open';
+    conversationId: string;
+    messageId: string;
+} | {
+    type: 'text.delta';
+    messageId: string;
+    seq: number;
+    content: string;
+} | {
+    type: 'text.done';
+    messageId: string;
+    seq: number;
+} | {
+    type: 'tool.start';
+    messageId: string;
+    step: {
+        stepId: string;
+        toolName: string;
+        title: string;
+    };
+} | {
+    type: 'tool.progress';
+    messageId: string;
+    stepId: string;
+    percent?: number;
+    message?: string;
+} | {
+    type: 'tool.result';
+    messageId: string;
+    stepId: string;
+    result: unknown;
+} | {
+    type: 'chart';
+    messageId: string;
+    chart: unknown;
+} | {
+    type: 'table';
+    messageId: string;
+    table: unknown;
+} | {
+    type: 'sql';
+    messageId: string;
+    sql: unknown;
+} | {
+    type: 'metric';
+    messageId: string;
+    metrics: unknown[];
+} | {
+    type: 'action';
+    messageId: string;
+    actions: unknown[];
+} | {
+    type: 'source';
+    messageId: string;
+    sources: unknown[];
+} | {
+    type: 'suggestion';
+    messageId: string;
+    suggestions: string[];
+} | {
+    type: 'risk';
+    messageId: string;
+    warnings: string[];
+} | {
+    type: 'error';
+    messageId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+} | {
+    type: 'done';
+    conversationId: string;
+    messageId: string;
+    totalTokens?: number;
+} | {
+    type: 'heartbeat';
+    ts: number;
+};
+
+export declare interface TableInfo {
+    tableName: string;
+    tableComment?: string;
+    columns?: Array<{
+        columnName: string;
+        columnType: string;
+        columnComment?: string;
+        sensitive?: boolean;
+    }>;
+}
+
+export declare interface TableResult {
+    columns: {
+        key: string;
+        title: string;
+        type?: string;
+    }[];
+    rows: Record<string, unknown>[];
+    total?: number;
+}
+
+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>;
+
+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;
+}
+
+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;
+}
+
+export declare interface ToolStep {
+    stepId: string;
+    toolName: string;
+    title: string;
+    status: 'pending' | 'running' | 'success' | 'error';
+    args?: Record<string, unknown>;
+    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;
+}
+
+export declare interface UserInfo {
+    userId: string;
+    username: string;
+    roles: string[];
+    orgId?: string;
+    areaPermissions?: string[];
+    dataScope?: 'all' | 'org' | 'area' | 'self';
+}
+
+export { }