drizzle-cube 0.6.0 → 0.6.2

package/dist/server/adapters/sqlite-adapter.d.ts

@@ -0,0 +1,120 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { TimeGranularity } from '../types/index.js';
+import { BaseDatabaseAdapter, DatabaseCapabilities } from './base-adapter.js';
+export declare class SQLiteAdapter extends BaseDatabaseAdapter {
+    getEngineType(): 'sqlite';
+    /**
+     * Build SQLite INTERVAL from ISO 8601 duration
+     * SQLite doesn't have native interval types, so we convert to seconds
+     * for arithmetic operations on Unix timestamps
+     */
+    buildIntervalFromISO(duration: string): SQL;
+    /**
+     * Build SQLite time difference in seconds
+     * SQLite timestamps are stored as Unix seconds, so simple subtraction works
+     * Returns (end - start) as seconds
+     */
+    buildTimeDifferenceSeconds(end: SQL, start: SQL): SQL;
+    /**
+     * Build SQLite timestamp + interval expression
+     * Since SQLite stores timestamps as Unix seconds, just add the seconds
+     */
+    buildDateAddInterval(timestamp: SQL, duration: string): SQL;
+    /**
+     * Build SQLite date difference in periods
+     * SQLite uses Julian day calculations for date arithmetic
+     * Note: SQLite timestamps are stored as Unix seconds
+     */
+    buildDateDiffPeriods(startDate: SQL, endDate: SQL, unit: 'day' | 'week' | 'month'): SQL;
+    /**
+     * Build SQLite period series using recursive CTE
+     * SQLite 3.8.3+ supports recursive CTEs for generating sequences
+     */
+    buildPeriodSeriesSubquery(maxPeriod: number): SQL;
+    /**
+     * Build SQLite time dimension using date/datetime functions with modifiers
+     * For integer timestamp columns (milliseconds), first convert to datetime
+     * SQLite doesn't have DATE_TRUNC like PostgreSQL, so we use strftime and date modifiers
+     * Returns datetime strings for consistency with other databases
+     */
+    buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
+    /**
+     * SQLite has no ILIKE — use LOWER()+LIKE with the pattern lowercased in JS.
+     */
+    protected caseInsensitiveLike(fieldExpr: AnyColumn | SQL, pattern: string, negated: boolean): SQL;
+    /**
+     * SQLite regex requires loading an extension, so GLOB is used as a fallback.
+     */
+    protected regexCondition(fieldExpr: AnyColumn | SQL, value: string, negated: boolean): SQL;
+    /**
+     * Build SQLite type casting using CAST() function
+     * SQLite has dynamic typing but supports CAST for consistency
+     */
+    castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * SQLite AVG uses IFNULL rather than COALESCE for null-to-zero handling.
+     */
+    protected nullToZero(expr: SQL): SQL;
+    /**
+     * Build SQLite CASE WHEN conditional expression.
+     * Unlike the base implementation, SQLite must detect embedded SQL objects in THEN/ELSE
+     * and inline them rather than binding them as parameters.
+     */
+    buildCaseWhen(conditions: Array<{
+        when: SQL;
+        then: any;
+    }>, elseValue?: any): SQL;
+    /**
+     * Build SQLite boolean literal
+     * SQLite uses 1/0 for true/false
+     */
+    buildBooleanLiteral(value: boolean): SQL;
+    /**
+     * Preprocess calculated measure templates for SQLite-specific handling
+     *
+     * SQLite performs integer division by default (5/2 = 2 instead of 2.5).
+     * This method wraps division operands with CAST to REAL to ensure float division.
+     *
+     * Pattern matched: {measure1} / {measure2} or {measure1} / NULLIF({measure2}, 0)
+     * Transforms to: CAST({measure1} AS REAL) / ...
+     *
+     * @param calculatedSql - Template string with {member} references
+     * @returns Preprocessed template with CAST for division operations
+     */
+    preprocessCalculatedTemplate(calculatedSql: string): string;
+    /**
+     * Convert filter values to SQLite-compatible types
+     * SQLite doesn't support boolean types - convert boolean to integer (1/0)
+     * Convert Date objects to milliseconds for integer timestamp columns
+     */
+    convertFilterValue(value: any): any;
+    /**
+     * Prepare date value for SQLite integer timestamp storage
+     * Convert Date objects to milliseconds (Unix timestamp * 1000)
+     */
+    prepareDateValue(date: Date): any;
+    /**
+     * SQLite stores timestamps as integers (milliseconds)
+     */
+    isTimestampInteger(): boolean;
+    /**
+     * SQLite has limited statistical support (no native STDDEV/VARIANCE/PERCENTILE)
+     * but supports window functions since SQLite 3.25
+     */
+    getCapabilities(): DatabaseCapabilities;
+    /**
+     * SQLite does not have native STDDEV
+     * Returns null for graceful degradation
+     */
+    buildStddev(_fieldExpr: AnyColumn | SQL, _useSample?: boolean): SQL | null;
+    /**
+     * SQLite does not have native VARIANCE
+     * Returns null for graceful degradation
+     */
+    buildVariance(_fieldExpr: AnyColumn | SQL, _useSample?: boolean): SQL | null;
+    /**
+     * SQLite does not have native PERCENTILE
+     * Returns null for graceful degradation
+     */
+    buildPercentile(_fieldExpr: AnyColumn | SQL, _percentile: number): SQL | null;
+}

package/dist/server/adapters/window-function-builder.d.ts

@@ -0,0 +1,11 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { WindowFunctionType, WindowFunctionConfig } from './base-adapter.js';
+type FieldExpr = AnyColumn | SQL | null;
+/** Build the full `OVER (...)` clause from partition/order/frame components. */
+export declare function buildWindowOverClause(partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
+    field: AnyColumn | SQL;
+    direction: 'asc' | 'desc';
+}>, config?: WindowFunctionConfig): SQL;
+/** Build the window function expression for a given type and pre-built OVER clause. */
+export declare function buildWindowExpression(type: WindowFunctionType, fieldExpr: FieldExpr, over: SQL, config?: WindowFunctionConfig): SQL;
+export {};

package/dist/server/agent/chart-validation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Chart Config Validation for Agent Tool
+ *
+ * Validates chartConfig against drop zone requirements defined in the chart config registry.
+ * Auto-infers missing fields from the query structure.
+ * Builds per-chart-type guidance for the tool description.
+ */
+interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+}
+/**
+ * Validate chartConfig against the chart type's drop zone requirements.
+ */
+export declare function validateChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, _query: Record<string, unknown>): ValidationResult;
+export declare function inferChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, query: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Build per-chart-type requirements text for the agent tool description.
+ * Includes description, useCase, and drop zone requirements for each chart type.
+ */
+export declare function buildChartRequirementsDescription(allowedChartTypes: string[]): string;
+export {};

package/dist/server/agent/handler-steps.d.ts

@@ -0,0 +1,37 @@
+import { AgentSSEEvent, AgentHistoryMessage, AgentConfig } from './types.js';
+import { ContentBlock, InternalMessage, ToolResult, LLMProvider } from './providers/types.js';
+import { ToolExecutionResult } from './tools.js';
+type AgentObservability = AgentConfig['observability'];
+type ToolExecutorMap = Map<string, (input: Record<string, unknown>) => Promise<ToolExecutionResult>>;
+/** Push provider-formatted tool results onto the message list (array or single). */
+export declare function pushFormattedResults(messages: InternalMessage[], formatted: unknown): void;
+/** Run an observability callback, swallowing any error (must never break the agent). */
+export declare function safeObserve(fn: (() => void) | undefined): void;
+/** Rebuild conversation messages from stored history (e.g. after notebook reload). */
+export declare function rebuildMessagesFromHistory(history: AgentHistoryMessage[] | undefined, provider: LLMProvider): InternalMessage[];
+/** Accumulated result of consuming one assistant generation stream. */
+export interface ConsumedStream {
+    contentBlocks: ContentBlock[];
+    stopReason: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/**
+ * Consume a provider's normalized stream, accumulating the assistant's content
+ * blocks and yielding text/tool SSE events. Returns the accumulated blocks,
+ * stop reason and token usage.
+ */
+export declare function consumeAssistantStream(provider: LLMProvider, stream: AsyncIterable<unknown>): AsyncGenerator<AgentSSEEvent, ConsumedStream>;
+/** Context shared across tool executions within a single turn. */
+export interface ToolExecContext {
+    executor: ToolExecutorMap;
+    observability: AgentObservability;
+    traceId: string;
+    turn: number;
+}
+/**
+ * Execute all tool-use blocks in the assistant's response, yielding their SSE
+ * events and returning the collected ToolResults.
+ */
+export declare function executeToolCalls(contentBlocks: ContentBlock[], ctx: ToolExecContext): AsyncGenerator<AgentSSEEvent, ToolResult[]>;
+export {};

package/dist/server/agent/handler.d.ts

@@ -0,0 +1,25 @@
+import { SemanticLayerCompiler } from '../compiler.js';
+import { SecurityContext } from '../types/index.js';
+import { AgentConfig, AgentSSEEvent, AgentHistoryMessage } from './types.js';
+/**
+ * Handle an agent chat request, yielding SSE events as the agent works.
+ *
+ * Uses the configured LLM provider with streaming for edge-runtime compatibility.
+ * Implements a manual agentic loop: send messages → stream response → execute
+ * tool calls → append results → repeat until the model stops requesting tools.
+ */
+export declare function handleAgentChat(options: {
+    message: string;
+    sessionId?: string;
+    history?: AgentHistoryMessage[];
+    semanticLayer: SemanticLayerCompiler;
+    securityContext: SecurityContext;
+    agentConfig: AgentConfig;
+    apiKey: string;
+    /** Per-request context appended to the system prompt (e.g. user info, tenant context) */
+    systemContext?: string;
+    /** Per-request overrides from client headers (take precedence over agentConfig) */
+    providerOverride?: string;
+    modelOverride?: string;
+    baseURLOverride?: string;
+}): AsyncGenerator<AgentSSEEvent>;

package/dist/server/agent/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Agent Module - Public Exports
+ * Agentic AI notebook handler for drizzle-cube
+ */
+export { handleAgentChat } from './handler.js';
+export { getToolDefinitions, createToolExecutor } from './tools.js';
+export type { ToolExecutionResult } from './tools.js';
+export { buildAgentSystemPrompt } from './system-prompt.js';
+export { createProvider } from './providers/index.js';
+export type { LLMProvider, ProviderName } from './providers/index.js';
+export type { AgentChatRequest, AgentConfig, AgentObservabilityHooks, AgentSSEEvent, AgentHistoryMessage, AgentHistoryToolCall, PortletBlockData, MarkdownBlockData, DashboardSavedData } from './types.js';

package/dist/server/agent/providers/anthropic.d.ts

@@ -0,0 +1,24 @@
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types.js';
+export declare class AnthropicProvider implements LLMProvider {
+    private client;
+    constructor(apiKey: string);
+    private apiKey;
+    private initialized;
+    private ensureClient;
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    formatTools(tools: ToolDefinition[]): unknown[];
+    formatMessages(messages: InternalMessage[], system: string): {
+        messages: unknown[];
+        system?: string;
+    };
+    formatToolResults(results: ToolResult[]): unknown;
+    shouldContinue(stopReason: string): boolean;
+    formatError(error: unknown): string;
+}

package/dist/server/agent/providers/factory.d.ts

@@ -0,0 +1,12 @@
+import { LLMProvider } from './types.js';
+export type ProviderName = 'anthropic' | 'openai' | 'google';
+/**
+ * Create an LLM provider instance.
+ *
+ * @param provider - Provider name ('anthropic', 'openai', 'google')
+ * @param apiKey - API key for the provider
+ * @param options - Optional configuration (e.g. baseURL for OpenAI-compatible services)
+ */
+export declare function createProvider(provider: ProviderName, apiKey: string, options?: {
+    baseURL?: string;
+}): Promise<LLMProvider>;

package/dist/server/agent/providers/google.d.ts

@@ -0,0 +1,23 @@
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types.js';
+export declare class GoogleProvider implements LLMProvider {
+    private apiKey;
+    private sdk;
+    private initialized;
+    constructor(apiKey: string);
+    private ensureSDK;
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    formatTools(tools: ToolDefinition[]): unknown[];
+    formatMessages(messages: InternalMessage[], _system: string): {
+        messages: unknown[];
+    };
+    formatToolResults(results: ToolResult[]): unknown;
+    shouldContinue(stopReason: string): boolean;
+    formatError(error: unknown): string;
+}

package/dist/server/agent/providers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * LLM Provider exports
+ */
+export type { LLMProvider, ToolDefinition, InternalMessage, ContentBlock, ToolResult, NormalizedEvent } from './types.js';
+export type { ProviderName } from './factory.js';
+export { createProvider } from './factory.js';

package/dist/server/agent/providers/openai.d.ts

@@ -0,0 +1,26 @@
+import { LLMProvider, ToolDefinition, InternalMessage, ToolResult, NormalizedEvent } from './types.js';
+export declare class OpenAIProvider implements LLMProvider {
+    private client;
+    private apiKey;
+    private baseURL?;
+    private initialized;
+    constructor(apiKey: string, options?: {
+        baseURL?: string;
+    });
+    private ensureClient;
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    formatTools(tools: ToolDefinition[]): unknown[];
+    formatMessages(messages: InternalMessage[], system: string): {
+        messages: unknown[];
+    };
+    formatToolResults(results: ToolResult[]): unknown[];
+    shouldContinue(stopReason: string): boolean;
+    formatError(error: unknown): string;
+}

package/dist/server/agent/providers/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * LLM Provider Abstraction Types
+ * Provider-agnostic interfaces for multi-provider LLM support in the agentic notebook.
+ */
+/**
+ * Generic tool definition (provider-agnostic).
+ * Each provider's formatTools() wraps this in its own format.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Provider-agnostic internal message format.
+ * The handler uses this for the conversation history; providers convert on the way in/out.
+ */
+export interface InternalMessage {
+    role: 'user' | 'assistant' | 'tool_result';
+    content: string | ContentBlock[];
+}
+export interface ContentBlock {
+    type: 'text' | 'tool_use';
+    text?: string;
+    id?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    /** Provider-specific metadata (e.g. Gemini thoughtSignature) */
+    metadata?: Record<string, unknown>;
+}
+export interface ToolResult {
+    toolUseId: string;
+    /** Tool name — needed by some providers (e.g. Gemini's functionResponse) */
+    toolName?: string;
+    content: string;
+    isError?: boolean;
+}
+/**
+ * Normalized stream events consumed by the handler's agentic loop.
+ * Every provider must emit these — the handler never sees raw provider events.
+ */
+export type NormalizedEvent = {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'tool_use_start';
+    id: string;
+    name: string;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'tool_input_delta';
+    json: string;
+} | {
+    type: 'tool_use_end';
+    id?: string;
+    input?: Record<string, unknown>;
+} | {
+    type: 'message_meta';
+    inputTokens?: number;
+    outputTokens?: number;
+    stopReason: string;
+};
+/**
+ * The core provider interface.
+ * Each LLM provider implements these 7 methods to integrate with the agentic loop.
+ */
+export interface LLMProvider {
+    /** Create a streaming API call and return the raw iterable. */
+    createStream(params: {
+        model: string;
+        maxTokens: number;
+        system: string;
+        tools: ToolDefinition[];
+        messages: InternalMessage[];
+    }): Promise<AsyncIterable<unknown>>;
+    /** Parse the raw stream into normalized events the handler understands. */
+    parseStreamEvents(stream: AsyncIterable<unknown>): AsyncGenerator<NormalizedEvent>;
+    /** Convert generic tool definitions to provider-specific format. */
+    formatTools(tools: ToolDefinition[]): unknown[];
+    /** Convert internal messages + system prompt to provider-specific format. */
+    formatMessages(messages: InternalMessage[], system: string): {
+        messages: unknown[];
+        system?: string;
+    };
+    /** Convert tool results to provider-specific format for appending as a user message. */
+    formatToolResults(results: ToolResult[]): unknown;
+    /** Return true if the stop reason means the model wants to continue (tool use). */
+    shouldContinue(stopReason: string): boolean;
+    /** Format a provider-specific error into a user-friendly message. */
+    formatError(error: unknown): string;
+}

package/dist/server/agent/system-prompt.d.ts

@@ -0,0 +1,5 @@
+import { CubeMetadata } from '../types/index.js';
+/**
+ * Build the full system prompt for the agent
+ */
+export declare function buildAgentSystemPrompt(metadata: CubeMetadata[]): string;

package/dist/server/agent/tools.d.ts

@@ -0,0 +1,28 @@
+import { SemanticLayerCompiler } from '../compiler.js';
+import { SecurityContext } from '../types/index.js';
+import { AgentSSEEvent } from './types.js';
+import { ToolDefinition } from './providers/types.js';
+/**
+ * Result of executing a tool call
+ */
+export interface ToolExecutionResult {
+    /** String content to return as tool_result */
+    result: string;
+    /** Whether the tool call errored */
+    isError?: boolean;
+    /** Optional SSE event to emit as a side effect (add_portlet, add_markdown) */
+    sideEffect?: AgentSSEEvent;
+}
+/**
+ * Returns the array of tool definitions for the Anthropic Messages API.
+ * Plain JSON schema — no Zod dependency.
+ */
+export declare function getToolDefinitions(): ToolDefinition[];
+/**
+ * Create a tool executor map that closes over the semantic layer and security context.
+ * Returns a Map<toolName, handler> where each handler takes parsed input and returns a result.
+ */
+export declare function createToolExecutor(options: {
+    semanticLayer: SemanticLayerCompiler;
+    securityContext: SecurityContext;
+}): Map<string, (input: Record<string, unknown>) => Promise<ToolExecutionResult>>;

package/dist/server/agent/types.d.ts

@@ -0,0 +1,192 @@
+import { ChartType, ChartAxisConfig, ChartDisplayConfig, DashboardConfig } from '../../client/types.js';
+/**
+ * A tool call from a prior conversation turn (for history replay)
+ */
+export interface AgentHistoryToolCall {
+    id: string;
+    name: string;
+    input?: unknown;
+    result?: unknown;
+    status: 'running' | 'complete' | 'error';
+}
+/**
+ * A message from a prior conversation (for history replay)
+ */
+export interface AgentHistoryMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    toolCalls?: AgentHistoryToolCall[];
+}
+/**
+ * Request body for the agent chat endpoint
+ */
+export interface AgentChatRequest {
+    /** User message to send to the agent */
+    message: string;
+    /** Session ID for multi-turn conversations */
+    sessionId?: string;
+    /** Prior conversation history for session continuity (e.g. after notebook reload) */
+    history?: AgentHistoryMessage[];
+}
+/**
+ * Observability hooks for tracing agent chat lifecycle events.
+ * Called synchronously (fire-and-forget) — implementations should not throw.
+ */
+export interface AgentObservabilityHooks {
+    /** Called once when agent chat starts */
+    onChatStart?: (event: {
+        traceId: string;
+        sessionId?: string;
+        message: string;
+        model: string;
+        historyLength: number;
+    }) => void;
+    /** Called after each LLM API call completes */
+    onGenerationEnd?: (event: {
+        traceId: string;
+        turn: number;
+        model: string;
+        stopReason: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        durationMs: number;
+        /** Messages array sent to the API */
+        input?: unknown;
+        /** Assistant content blocks from the response */
+        output?: unknown;
+    }) => void;
+    /** Called after each tool execution */
+    onToolEnd?: (event: {
+        traceId: string;
+        turn: number;
+        toolName: string;
+        toolUseId: string;
+        isError: boolean;
+        durationMs: number;
+    }) => void;
+    /** Called when agent chat completes */
+    onChatEnd?: (event: {
+        traceId: string;
+        sessionId?: string;
+        totalTurns: number;
+        durationMs: number;
+        error?: string;
+    }) => void;
+}
+/**
+ * Agent configuration options (provided in adapter options).
+ * Supports multiple LLM providers — defaults to Anthropic for backward compatibility.
+ * All providers use direct HTTP API calls — no subprocess spawning, fully edge-runtime compatible.
+ */
+export interface AgentConfig {
+    /**
+     * LLM provider to use (default: 'anthropic').
+     * - 'anthropic': Claude models via @anthropic-ai/sdk
+     * - 'openai': OpenAI models via openai SDK (also supports Groq, Together, Mistral, Ollama via baseURL)
+     * - 'google': Gemini models via @google/generative-ai
+     */
+    provider?: 'anthropic' | 'openai' | 'google';
+    /**
+     * Base URL for OpenAI-compatible providers.
+     * Only used when provider is 'openai'. Examples:
+     * - Groq: 'https://api.groq.com/openai/v1'
+     * - Together: 'https://api.together.xyz/v1'
+     * - Ollama: 'http://localhost:11434/v1'
+     */
+    baseURL?: string;
+    /** Server-side API key for the selected provider */
+    apiKey?: string;
+    /** Model to use (default depends on provider: 'claude-sonnet-4-6' for Anthropic, 'gpt-4.1-mini' for OpenAI, 'gemini-3-flash-preview' for Google) */
+    model?: string;
+    /** Maximum agentic turns per request (default: 25) */
+    maxTurns?: number;
+    /** Maximum tokens per response (default: 4096) */
+    maxTokens?: number;
+    /** Allow X-Agent-Api-Key header to override server apiKey */
+    allowClientApiKey?: boolean;
+    /** Optional observability hooks for tracing */
+    observability?: AgentObservabilityHooks;
+    /**
+     * Build per-request system context for the LLM prompt from the authenticated security context.
+     * Called on every agent chat request with the resolved security context.
+     * The returned string is appended to the system prompt under "## User Context".
+     *
+     * @example
+     * buildSystemContext: (securityContext) =>
+     *   `User: ${securityContext.userName}, Role: ${securityContext.role}`
+     */
+    buildSystemContext?: (securityContext: Record<string, unknown>) => string | undefined;
+}
+/**
+ * Data for an add_portlet tool call
+ */
+export interface PortletBlockData {
+    id: string;
+    title: string;
+    query: string;
+    chartType: ChartType;
+    chartConfig?: ChartAxisConfig;
+    displayConfig?: ChartDisplayConfig;
+}
+/**
+ * Data for an add_markdown tool call
+ */
+export interface MarkdownBlockData {
+    id: string;
+    title?: string;
+    content: string;
+}
+/**
+ * Data emitted when the agent saves a dashboard via the save_as_dashboard tool.
+ * The client receives this via SSE and can persist the config however it chooses.
+ */
+export interface DashboardSavedData {
+    title: string;
+    description?: string;
+    dashboardConfig: DashboardConfig;
+}
+/**
+ * SSE events emitted by the agent handler
+ */
+export type AgentSSEEvent = {
+    type: 'text_delta';
+    data: string;
+} | {
+    type: 'tool_use_start';
+    data: {
+        id: string;
+        name: string;
+        input?: unknown;
+    };
+} | {
+    type: 'tool_use_result';
+    data: {
+        id: string;
+        name: string;
+        result?: unknown;
+        isError?: boolean;
+    };
+} | {
+    type: 'add_portlet';
+    data: PortletBlockData;
+} | {
+    type: 'add_markdown';
+    data: MarkdownBlockData;
+} | {
+    type: 'dashboard_saved';
+    data: DashboardSavedData;
+} | {
+    type: 'turn_complete';
+    data: Record<string, never>;
+} | {
+    type: 'done';
+    data: {
+        sessionId: string;
+        traceId?: string;
+    };
+} | {
+    type: 'error';
+    data: {
+        message: string;
+    };
+};