@kb-labs/core-platform 1.0.0

package/dist/artifacts-DrVnkLzu.d.ts

@@ -0,0 +1,1374 @@
+/**
+ * @module @kb-labs/core-platform/adapters/analytics
+ * Analytics abstraction for tracking events and user identification.
+ */
+/**
+ * Query parameters for fetching analytics events
+ */
+interface EventsQuery {
+    type?: string | string[];
+    source?: string;
+    actor?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Analytics event structure (matches kb.v1 schema from @kb-labs/analytics)
+ */
+interface AnalyticsEvent {
+    id: string;
+    schema: "kb.v1";
+    type: string;
+    ts: string;
+    ingestTs: string;
+    source: {
+        product: string;
+        version: string;
+    };
+    runId: string;
+    actor?: {
+        type: "user" | "agent" | "ci";
+        id?: string;
+        name?: string;
+    };
+    ctx?: Record<string, string | number | boolean | null>;
+    payload?: unknown;
+    hashMeta?: {
+        algo: "hmac-sha256";
+        saltId: string;
+    };
+}
+/**
+ * Response for events query
+ */
+interface EventsResponse {
+    events: AnalyticsEvent[];
+    total: number;
+    hasMore: boolean;
+}
+/**
+ * Aggregated statistics across events
+ */
+interface EventsStats {
+    totalEvents: number;
+    byType: Record<string, number>;
+    bySource: Record<string, number>;
+    byActor: Record<string, number>;
+    timeRange: {
+        from: string;
+        to: string;
+    };
+}
+/**
+ * Daily aggregated statistics for time-series visualization
+ */
+interface DailyStats {
+    date: string;
+    count: number;
+    metrics?: Record<string, number>;
+    breakdown?: string;
+}
+/**
+ * Extended query for getDailyStats — adds time bucketing and breakdown support on top of EventsQuery.
+ * Adapters implement what they can; unsupported fields are silently ignored (graceful degradation).
+ */
+interface StatsQuery extends EventsQuery {
+    /**
+     * Time bucket granularity. Default: 'day'.
+     * Controls the format of DailyStats.date in the response.
+     */
+    groupBy?: "hour" | "day" | "week" | "month";
+    /**
+     * Dot-notation path to a field to split results by (e.g. 'payload.model', 'payload.tier', 'source.product').
+     * When specified, each time bucket returns multiple DailyStats rows — one per unique value of this field.
+     * Rows include a `breakdown` field with the field value.
+     * Adapters that do not support breakdownBy return data without breakdown (no error).
+     */
+    breakdownBy?: string;
+    /**
+     * Specific payload metric field names to aggregate (e.g. ['totalCost', 'totalTokens']).
+     * When omitted, adapters aggregate all metrics they know about for the given event type.
+     */
+    metrics?: string[];
+}
+/**
+ * WAL buffer status (if applicable)
+ */
+interface BufferStatus {
+    segments: number;
+    totalSizeBytes: number;
+    oldestEventTs: string | null;
+    newestEventTs: string | null;
+}
+/**
+ * Dead-Letter Queue status (if applicable)
+ */
+interface DlqStatus {
+    failedEvents: number;
+    oldestFailureTs: string | null;
+}
+/**
+ * Context for analytics events (automatically populated).
+ * Adapters use this to enrich events with source, actor, and runId.
+ */
+interface AnalyticsContext {
+    /**
+     * Source of events (product name and version).
+     * Automatically extracted from package.json.
+     */
+    source: {
+        product: string;
+        version: string;
+    };
+    /**
+     * Run ID for correlating events in a single execution.
+     * Automatically generated per-execution (e.g., CLI invocation, REST request).
+     */
+    runId: string;
+    /**
+     * Actor performing the action (user, agent, CI).
+     * Auto-detected from environment (git config, CI env vars, etc).
+     */
+    actor?: {
+        type: "user" | "agent" | "ci";
+        id?: string;
+        name?: string;
+    };
+    /**
+     * Tenant ID for multi-tenancy support.
+     */
+    tenantId?: string;
+    /**
+     * Additional context (workspace path, branch, etc).
+     */
+    ctx?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Analytics adapter interface.
+ * Implementations: @kb-labs/analytics-adapter (production), NoOpAnalytics (noop)
+ */
+interface IAnalytics {
+    /**
+     * Track an analytics event.
+     * @param event - Event name (e.g., 'user.signup', 'workflow.completed')
+     * @param properties - Optional event properties
+     */
+    track(event: string, properties?: Record<string, unknown>): Promise<void>;
+    /**
+     * Identify a user for analytics tracking.
+     * @param userId - Unique user identifier
+     * @param traits - Optional user traits (name, email, etc.)
+     */
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    /**
+     * Flush all pending analytics events.
+     * Call before process exit to ensure all events are sent.
+     */
+    flush(): Promise<void>;
+    /**
+     * Get analytics events (optional - for reading/visualization).
+     * Not implemented by NoOpAnalytics.
+     */
+    getEvents?(query?: EventsQuery): Promise<EventsResponse>;
+    /**
+     * Get aggregated statistics (optional - for dashboards).
+     * Not implemented by NoOpAnalytics.
+     */
+    getStats?(): Promise<EventsStats>;
+    /**
+     * Get buffer status (optional - for monitoring).
+     * Returns null if buffer not applicable (e.g., HTTP-only analytics).
+     */
+    getBufferStatus?(): Promise<BufferStatus | null>;
+    /**
+     * Get DLQ status (optional - for monitoring).
+     * Returns null if DLQ not applicable.
+     */
+    getDlqStatus?(): Promise<DlqStatus | null>;
+    /**
+     * Get current source attribution (optional).
+     *
+     * Returns the current source (product name and version) used for events.
+     * This is useful for saving and restoring source in nested plugin execution.
+     *
+     * @returns Current source, or undefined if not available
+     *
+     * Implementation notes:
+     * - FileAnalytics: Returns current context.source
+     * - NoOpAnalytics: Not needed (no events tracked)
+     * - Future HTTP/Cloud adapters: Should implement this
+     *
+     * @example
+     * ```typescript
+     * const analytics = platform.analytics;
+     * const originalSource = analytics.getSource?.();
+     *
+     * try {
+     *   analytics.setSource?.({ product: '@kb-labs/mind', version: '0.1.0' });
+     *   await analytics.track('mind.event', {...});
+     * } finally {
+     *   if (originalSource) {
+     *     analytics.setSource?.(originalSource);
+     *   }
+     * }
+     * ```
+     */
+    getSource?(): {
+        product: string;
+        version: string;
+    } | undefined;
+    /**
+     * Override source attribution for scoped execution (optional).
+     *
+     * This method allows wrapping analytics adapters to override the source
+     * (product name and version) for events tracked during plugin execution.
+     *
+     * Use case: When a plugin (@kb-labs/mind) runs in a subprocess, we want
+     * analytics events to show source.product = '@kb-labs/mind' instead of
+     * the root package (@kb-labs/ai-review).
+     *
+     * @param source - New source to use for future events
+     *
+     * Implementation notes:
+     * - FileAnalytics: Updates internal context.source
+     * - NoOpAnalytics: Not needed (no events tracked)
+     * - Future HTTP/Cloud adapters: Should implement this
+     *
+     * @example
+     * ```typescript
+     * const analytics = platform.analytics;
+     * if (analytics.setSource) {
+     *   analytics.setSource({
+     *     product: '@kb-labs/mind',
+     *     version: '0.1.0'
+     *   });
+     * }
+     * await analytics.track('mind.rag-index.started', {...});
+     * // Event will have source.product = '@kb-labs/mind'
+     * ```
+     */
+    setSource?(source: {
+        product: string;
+        version: string;
+    }): void;
+    /**
+     * Get time-bucketed aggregated statistics (optional - for time-series visualization).
+     *
+     * Groups events by time bucket and returns aggregated counts and metrics.
+     * Useful for rendering charts and graphs.
+     *
+     * @param query - StatsQuery extending EventsQuery with groupBy, breakdownBy, metrics
+     * @returns Array of stats sorted by date ascending. When breakdownBy is used,
+     *          multiple rows per time bucket are returned (one per unique breakdown value).
+     *
+     * Implementation notes:
+     * - FileAnalytics: Groups events in memory using date-fns; supports all StatsQuery fields
+     * - PostgresAnalytics: Uses SQL GROUP BY + date_trunc() for efficiency
+     * - NoOpAnalytics: Not implemented (returns empty array)
+     * - Adapters that don't support breakdownBy/groupBy silently ignore those fields
+     *
+     * The metrics object contains aggregated values specific to the event type:
+     * - LLM events: totalTokens, totalCost, avgDurationMs
+     * - Embeddings events: totalTokens, totalCost, avgDurationMs
+     * - VectorStore events: totalSearches, totalUpserts, totalDeletes, avgDurationMs
+     * - Cache events: totalHits, totalMisses, totalSets, hitRate
+     * - Storage events: totalBytesRead, totalBytesWritten, avgDurationMs
+     *
+     * @example
+     * ```typescript
+     * // Basic daily stats
+     * const daily = await analytics.getDailyStats?.({
+     *   type: 'llm.completion.completed',
+     *   from: '2026-01-01T00:00:00Z',
+     *   to: '2026-01-31T23:59:59Z',
+     * });
+     * // [{ date: '2026-01-01', count: 45, metrics: { totalTokens: 12500, totalCost: 2.34 } }, ...]
+     *
+     * // Hourly breakdown by model
+     * const byModel = await analytics.getDailyStats?.({
+     *   type: ['llm.chatWithTools.completed', 'llm.completion.completed'],
+     *   groupBy: 'hour',
+     *   breakdownBy: 'payload.model',
+     *   metrics: ['totalCost', 'totalTokens'],
+     * });
+     * // [
+     * //   { date: '2026-01-01T10', count: 12, breakdown: 'gpt-4o-mini', metrics: { totalCost: 0.05 } },
+     * //   { date: '2026-01-01T10', count: 3,  breakdown: 'gpt-5.1-codex-max', metrics: { totalCost: 1.20 } },
+     * // ]
+     * ```
+     */
+    getDailyStats?(query?: StatsQuery): Promise<DailyStats[]>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/vector-store
+ * Vector store abstraction for semantic search operations.
+ */
+/**
+ * Vector record for storage.
+ */
+interface VectorRecord {
+    /** Unique identifier */
+    id: string;
+    /** Embedding vector */
+    vector: number[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Search result from vector store.
+ */
+interface VectorSearchResult {
+    /** Record identifier */
+    id: string;
+    /** Similarity score (0-1, higher is more similar) */
+    score: number;
+    /** Record metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Filter for vector search.
+ */
+interface VectorFilter {
+    /** Field name to filter on */
+    field: string;
+    /** Filter operator */
+    operator: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin";
+    /** Filter value */
+    value: unknown;
+}
+/**
+ * Vector store adapter interface.
+ * Implementations: @kb-labs/mind-qdrant (production), MemoryVectorStore (noop)
+ */
+interface IVectorStore {
+    /**
+     * Search for similar vectors.
+     * @param query - Query embedding vector
+     * @param limit - Maximum number of results
+     * @param filter - Optional metadata filter
+     */
+    search(query: number[], limit: number, filter?: VectorFilter): Promise<VectorSearchResult[]>;
+    /**
+     * Upsert vectors into the store.
+     * @param vectors - Array of vector records to upsert
+     */
+    upsert(vectors: VectorRecord[]): Promise<void>;
+    /**
+     * Delete vectors by IDs.
+     * @param ids - Array of vector IDs to delete
+     */
+    delete(ids: string[]): Promise<void>;
+    /**
+     * Get total count of vectors in the store.
+     */
+    count(): Promise<number>;
+    /**
+     * Get vectors by IDs (optional method for bulk retrieval).
+     * Allows any plugin to retrieve multiple vectors efficiently.
+     * @param ids - Array of vector IDs to retrieve
+     * @returns Array of vector records
+     */
+    get?(ids: string[]): Promise<VectorRecord[]>;
+    /**
+     * Query vectors by metadata filter (optional method for advanced filtering).
+     * Allows any plugin to retrieve vectors based on custom metadata criteria.
+     * @param filter - Metadata filter to apply
+     * @returns Array of matching vector records
+     */
+    query?(filter: VectorFilter): Promise<VectorRecord[]>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/llm-types
+ * LLM tier and capability types for adaptive model routing.
+ *
+ * These types define the abstract layer between plugins and LLM providers.
+ * Plugins request tiers/capabilities, platform resolves to actual models.
+ *
+ * @example
+ * ```typescript
+ * import { LLMTier, LLMCapability, UseLLMOptions } from '@kb-labs/sdk';
+ *
+ * // Plugin requests by tier (user decides what model)
+ * const llm = useLLM({ tier: 'small' });
+ * const llm = useLLM({ tier: 'large', capabilities: ['reasoning'] });
+ * ```
+ */
+
+/**
+ * Model quality tier - user-defined slots.
+ *
+ * Tiers are NOT tied to specific models. They are abstract slots
+ * that the user fills with whatever models they want in config.
+ *
+ * Plugin intent:
+ * - `small`  - "This task is simple, doesn't need much"
+ * - `medium` - "Standard task"
+ * - `large`  - "Complex task, need maximum quality"
+ *
+ * User decides what model maps to each tier in their config.
+ */
+type LLMTier = "small" | "medium" | "large";
+/**
+ * Model capabilities - task-optimized features.
+ *
+ * - `fast`      - Lowest latency (for real-time responses)
+ * - `reasoning` - Complex reasoning (o1, opus-level thinking)
+ * - `coding`    - Code-optimized (better at code generation/review)
+ * - `vision`    - Image input support
+ */
+type LLMCapability = "reasoning" | "coding" | "vision" | "fast";
+/**
+ * Options for useLLM() - plugin-facing API.
+ *
+ * Plugins specify what they need abstractly.
+ * Platform resolves to actual provider/model based on user config.
+ */
+interface UseLLMOptions {
+    /**
+     * Quality tier (user-defined slot).
+     * Platform adapts if exact tier unavailable:
+     * - Escalates up (small → medium) silently
+     * - Degrades down (large → medium) with warning
+     */
+    tier?: LLMTier;
+    /**
+     * Required capabilities.
+     * Platform selects model that supports ALL requested capabilities.
+     */
+    capabilities?: LLMCapability[];
+    /**
+     * Optional execution policy applied to this bound LLM instance.
+     * Can be overridden per-call via LLMOptions.execution.
+     */
+    execution?: LLMExecutionPolicy;
+}
+/**
+ * Resolution result from tier/capability matching.
+ * Internal type used by LLMRouter.
+ */
+interface LLMResolution {
+    /** Resolved provider ID (e.g., 'openai', 'anthropic') */
+    provider: string;
+    /** Resolved model name */
+    model: string;
+    /** Resource name for ResourceBroker (e.g., 'llm:openai') */
+    resource: string;
+    /** Original requested tier */
+    requestedTier: LLMTier | undefined;
+    /** Actual tier being used */
+    actualTier: LLMTier;
+    /** Whether this was escalated/degraded */
+    adapted: boolean;
+    /** Warning message if degraded */
+    warning?: string;
+}
+/**
+ * Resolved adapter binding — immutable snapshot of a tier resolution.
+ * Returned by resolveAdapter() to avoid global state mutation.
+ */
+interface LLMAdapterBinding {
+    /** The concrete adapter instance (already wrapped with analytics, etc.) */
+    adapter: ILLM;
+    /** Resolved model name */
+    model: string;
+    /** Actual tier used */
+    tier: LLMTier;
+}
+/**
+ * LLM Router interface - extends ILLM with routing capabilities.
+ * Implemented by @kb-labs/llm-router.
+ */
+interface ILLMRouter {
+    /** Get configured tier (what user set in config) */
+    getConfiguredTier(): LLMTier;
+    /** Resolve tier request to actual model (mutates router state — legacy) */
+    resolve(options?: UseLLMOptions): LLMResolution;
+    /**
+     * Resolve tier and return an immutable adapter binding.
+     * Does NOT mutate router state — safe for concurrent useLLM() calls.
+     */
+    resolveAdapter(options?: UseLLMOptions): Promise<LLMAdapterBinding>;
+    /** Check if capability is available */
+    hasCapability(capability: LLMCapability): boolean;
+    /** Get available capabilities */
+    getCapabilities(): LLMCapability[];
+}
+/**
+ * Tier order for resolution (lowest to highest).
+ */
+declare const TIER_ORDER: readonly LLMTier[];
+/**
+ * Check if tier A is higher than tier B.
+ */
+declare function isTierHigher(a: LLMTier, b: LLMTier): boolean;
+/**
+ * Check if tier A is lower than tier B.
+ */
+declare function isTierLower(a: LLMTier, b: LLMTier): boolean;
+
+/**
+ * @module @kb-labs/core-platform/adapters/llm
+ * LLM (Large Language Model) abstraction for text generation.
+ */
+/**
+ * Metadata for LLM request tracking and analytics.
+ * Passed through the chain from LLMRouter to AnalyticsLLM.
+ */
+interface LLMRequestMetadata {
+    /** Tier used for this request */
+    tier?: LLMTier;
+    /** Provider identifier (e.g., 'openai', 'anthropic') */
+    provider?: string;
+    /** Resource name in broker (e.g., 'llm:openai') */
+    resource?: string;
+    /** Cache/stream decision trace produced by runtime policy orchestrator */
+    cacheDecisionTrace?: LLMCacheDecisionTrace;
+}
+/**
+ * Cache policy modes for prompt/context caching.
+ */
+type LLMCacheMode = "prefer" | "require" | "bypass";
+/**
+ * Abstract cache scopes (adapter maps this to vendor-specific API).
+ */
+type LLMCacheScope = "prefix" | "segments" | "full_request";
+/**
+ * Streaming policy modes.
+ */
+type LLMStreamMode = "prefer" | "require" | "off";
+/**
+ * Cache policy requested by caller.
+ */
+interface LLMCachePolicy {
+    /** prefer (default), require, bypass */
+    mode?: LLMCacheMode;
+    /** Abstract scope selector for adapter mapping */
+    scope?: LLMCacheScope;
+    /** Requested TTL in seconds (best effort) */
+    ttlSec?: number;
+    /** Optional stable key hint for deterministic cache reuse */
+    key?: string;
+}
+/**
+ * Streaming policy requested by caller.
+ */
+interface LLMStreamPolicy {
+    /** prefer (default), require, off */
+    mode?: LLMStreamMode;
+    /**
+     * If streaming is unavailable and mode=prefer,
+     * fallback to complete() and emit a single chunk.
+     */
+    fallbackToComplete?: boolean;
+}
+/**
+ * Unified execution policy (vendor-agnostic).
+ */
+interface LLMExecutionPolicy {
+    cache?: LLMCachePolicy;
+    stream?: LLMStreamPolicy;
+}
+/**
+ * Cache capability descriptor for adapter protocol negotiation.
+ */
+interface LLMCacheCapability {
+    supported: boolean;
+    protocol?: "auto_prefix" | "explicit_breakpoints" | "explicit_handle";
+    scopes?: LLMCacheScope[];
+}
+/**
+ * Stream capability descriptor for adapter protocol negotiation.
+ */
+interface LLMStreamCapability {
+    supported: boolean;
+}
+/**
+ * Adapter protocol capabilities.
+ */
+interface LLMProtocolCapabilities {
+    cache: LLMCacheCapability;
+    stream: LLMStreamCapability;
+}
+/**
+ * Runtime trace of cache/stream decision applied before adapter call.
+ */
+interface LLMCacheDecisionTrace {
+    cacheRequestedMode: LLMCacheMode;
+    cacheSupported: boolean;
+    cacheAppliedMode: LLMCacheMode;
+    streamRequestedMode: LLMStreamMode;
+    streamSupported: boolean;
+    streamAppliedMode: LLMStreamMode;
+    streamFallback?: "complete";
+    reason?: string;
+}
+/**
+ * Options for LLM completion.
+ */
+interface LLMOptions {
+    /** Model identifier (e.g., 'gpt-4', 'claude-3-opus') */
+    model?: string;
+    /** Sampling temperature (0-2) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Stop sequences */
+    stop?: string[];
+    /** System prompt/instruction */
+    systemPrompt?: string;
+    /** Metadata for analytics and observability (set by LLMRouter) */
+    metadata?: LLMRequestMetadata;
+    /** Vendor-agnostic runtime execution policy (cache/stream semantics) */
+    execution?: LLMExecutionPolicy;
+}
+/**
+ * LLM completion response.
+ */
+interface LLMResponse {
+    /** Generated text content */
+    content: string;
+    /** Token usage statistics */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        /**
+         * Prompt tokens served from cache (provider-reported, optional).
+         * Example: OpenAI cached prompt tokens, Anthropic cache_read_input_tokens.
+         */
+        cacheReadTokens?: number;
+        /**
+         * Prompt tokens written to cache (provider-reported, optional).
+         * Example: Anthropic cache_creation_input_tokens.
+         */
+        cacheWriteTokens?: number;
+        /**
+         * Provider-reported billable prompt tokens (if available).
+         * If absent, analytics can derive estimates from cacheReadTokens and pricing rules.
+         */
+        billablePromptTokens?: number;
+        /**
+         * Optional vendor-specific usage data for advanced analytics.
+         */
+        providerUsage?: Record<string, unknown>;
+    };
+    /** Model used for generation */
+    model: string;
+}
+/**
+ * Tool definition for native tool calling.
+ */
+interface LLMTool {
+    /** Tool name (must be valid identifier) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for tool input parameters */
+    inputSchema: Record<string, any>;
+}
+/**
+ * Tool call from LLM.
+ */
+interface LLMToolCall {
+    /** Unique call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool input (validated against schema) */
+    input: unknown;
+}
+/**
+ * Message in a conversation.
+ */
+interface LLMMessage {
+    /** Message role */
+    role: "system" | "user" | "assistant" | "tool";
+    /** Message content (text or tool results) */
+    content: string;
+    /** Tool call ID (for tool role - identifies which tool call this result belongs to) */
+    toolCallId?: string;
+    /** Tool calls made by assistant (for assistant role - when LLM requests tool execution) */
+    toolCalls?: LLMToolCall[];
+    /** Metadata from tool execution (e.g., reflection results, file counts, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for native tool calling.
+ */
+interface LLMToolCallOptions extends LLMOptions {
+    /** Available tools */
+    tools: LLMTool[];
+    /**
+     * Control tool usage:
+     * - 'auto': LLM decides whether to call tools
+     * - 'required': LLM must call at least one tool
+     * - 'none': LLM cannot call tools (text-only response)
+     * - { type: 'function', function: { name: 'tool_name' } }: Force specific tool
+     */
+    toolChoice?: "auto" | "required" | "none" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+}
+/**
+ * Response from native tool calling.
+ */
+interface LLMToolCallResponse extends LLMResponse {
+    /** Tool calls requested by LLM (if any) */
+    toolCalls?: LLMToolCall[];
+}
+/**
+ * LLM adapter interface.
+ * Implementations: @kb-labs/shared-openai, @kb-labs/shared-anthropic (production), MockLLM (noop)
+ */
+interface ILLM {
+    /**
+     * Generate a completion for the given prompt.
+     * @param prompt - Text prompt
+     * @param options - Optional generation options
+     */
+    complete(prompt: string, options?: LLMOptions): Promise<LLMResponse>;
+    /**
+     * Stream a completion for the given prompt.
+     * @param prompt - Text prompt
+     * @param options - Optional generation options
+     */
+    stream(prompt: string, options?: LLMOptions): AsyncIterable<string>;
+    /**
+     * Optional protocol capability handshake.
+     * When omitted, callers should assume: stream=true, cache=false.
+     */
+    getProtocolCapabilities?(): LLMProtocolCapabilities | Promise<LLMProtocolCapabilities>;
+    /**
+     * Chat with native tool calling support (optional).
+     *
+     * If implemented, enables native LLM tool calling (e.g., OpenAI function calling, Claude tool use).
+     * If not implemented, AgentExecutor falls back to text-based tool prompting.
+     *
+     * @param messages - Conversation history
+     * @param options - Options including tools and tool choice
+     * @returns Response with optional tool calls
+     */
+    chatWithTools?(messages: LLMMessage[], options: LLMToolCallOptions): Promise<LLMToolCallResponse>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/embeddings
+ * Embeddings abstraction for text-to-vector conversion.
+ */
+/**
+ * Embeddings adapter interface.
+ * Implementations: @kb-labs/shared-openai (production), MockEmbeddings (noop)
+ */
+interface IEmbeddings {
+    /**
+     * Generate embedding vector for a single text.
+     * @param text - Input text
+     * @returns Embedding vector
+     */
+    embed(text: string): Promise<number[]>;
+    /**
+     * Generate embedding vectors for multiple texts.
+     * @param texts - Array of input texts
+     * @returns Array of embedding vectors (same order as input)
+     */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Dimension of the embedding vectors.
+     */
+    readonly dimensions: number;
+    /**
+     * Get the dimensions of the embeddings.
+     * This method is needed for IPC/Unix Socket transport to access the dimensions property.
+     * Implementations should return the same value as the dimensions property.
+     */
+    getDimensions(): Promise<number>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/cache
+ * Cache abstraction for key-value storage with TTL support.
+ */
+/**
+ * Cache adapter interface.
+ * Implementations: @kb-labs/core-redis (production), MemoryCache (noop)
+ */
+interface ICache {
+    /**
+     * Get a value from cache.
+     * @param key - Cache key
+     * @returns Cached value or null if not found/expired
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set a value in cache.
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Time to live in milliseconds (optional)
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a value from cache.
+     * @param key - Cache key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear cache entries matching a pattern.
+     * @param pattern - Glob pattern (e.g., 'user:*')
+     */
+    clear(pattern?: string): Promise<void>;
+    /**
+     * Add member to sorted set with score.
+     * @param key - Sorted set key
+     * @param score - Numeric score (typically timestamp)
+     * @param member - Member to add
+     */
+    zadd(key: string, score: number, member: string): Promise<void>;
+    /**
+     * Get members from sorted set by score range.
+     * @param key - Sorted set key
+     * @param min - Minimum score (inclusive)
+     * @param max - Maximum score (inclusive)
+     * @returns Array of members in score order
+     */
+    zrangebyscore(key: string, min: number, max: number): Promise<string[]>;
+    /**
+     * Remove member from sorted set.
+     * @param key - Sorted set key
+     * @param member - Member to remove
+     */
+    zrem(key: string, member: string): Promise<void>;
+    /**
+     * Set key-value pair only if key does not exist (atomic operation).
+     * Used for distributed locking and preventing race conditions.
+     * @param key - Cache key
+     * @param value - Value to set
+     * @param ttl - Time to live in milliseconds (optional)
+     * @returns true if value was set, false if key already exists
+     */
+    setIfNotExists<T>(key: string, value: T, ttl?: number): Promise<boolean>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/storage
+ * Storage abstraction for file/blob operations.
+ */
+/**
+ * Metadata for storage objects.
+ * Used by listWithMetadata() and stat().
+ */
+interface StorageMetadata {
+    /** File path */
+    path: string;
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp (ISO 8601) */
+    lastModified: string;
+    /** Content type (MIME) - optional */
+    contentType?: string;
+    /** ETag for versioning - optional */
+    etag?: string;
+}
+/**
+ * Storage adapter interface.
+ * Implementations: @kb-labs/core-fs (production), MemoryStorage (noop)
+ *
+ * **Backward compatibility:**
+ * - Core methods (read, write, delete, list, exists) are required
+ * - Extended methods (readStream, writeStream, copy, move, listWithMetadata, stat) are optional
+ * - Adapters can implement extended methods for better performance
+ */
+interface IStorage {
+    /**
+     * Read file contents.
+     * @param path - File path
+     * @returns File contents or null if not found
+     */
+    read(path: string): Promise<Buffer | null>;
+    /**
+     * Write file contents.
+     * @param path - File path
+     * @param data - File contents
+     */
+    write(path: string, data: Buffer): Promise<void>;
+    /**
+     * Delete a file.
+     * @param path - File path
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * List files matching a prefix.
+     * @param prefix - Path prefix (e.g., 'docs/')
+     * @returns Array of file paths
+     */
+    list(prefix: string): Promise<string[]>;
+    /**
+     * Check if a file exists.
+     * @param path - File path
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Read file as stream (for large files).
+     * @param path - File path
+     * @returns Readable stream or null if not found
+     *
+     * **Optional:** If not implemented, runtime will fallback to read() + buffer wrapping.
+     */
+    readStream?(path: string): Promise<NodeJS.ReadableStream | null>;
+    /**
+     * Write file from stream (for large files).
+     * @param path - File path
+     * @param stream - Readable stream
+     *
+     * **Optional:** If not implemented, runtime will fallback to stream → buffer → write().
+     */
+    writeStream?(path: string, stream: NodeJS.ReadableStream): Promise<void>;
+    /**
+     * Copy file within storage.
+     * @param sourcePath - Source file path
+     * @param destPath - Destination file path
+     *
+     * **Optional:** If not implemented, runtime will fallback to read() + write().
+     */
+    copy?(sourcePath: string, destPath: string): Promise<void>;
+    /**
+     * Move file within storage.
+     * @param sourcePath - Source file path
+     * @param destPath - Destination file path
+     *
+     * **Optional:** If not implemented, runtime will fallback to copy() + delete().
+     */
+    move?(sourcePath: string, destPath: string): Promise<void>;
+    /**
+     * List files with metadata (size, lastModified, etc).
+     * @param prefix - Path prefix (e.g., 'docs/')
+     * @returns Array of file metadata
+     *
+     * **Optional:** If not implemented, runtime will fallback to list() + stat() for each file.
+     */
+    listWithMetadata?(prefix: string): Promise<StorageMetadata[]>;
+    /**
+     * Get file metadata without reading contents.
+     * @param path - File path
+     * @returns File metadata or null if not found
+     *
+     * **Optional:** If not implemented, runtime will fallback to exists() + read() (inefficient).
+     */
+    stat?(path: string): Promise<StorageMetadata | null>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/config
+ * Configuration adapter interface
+ *
+ * Provides access to kb.config.json with product-specific extraction.
+ * Supports both Profiles v2 and legacy config structures.
+ */
+/**
+ * Configuration adapter interface.
+ *
+ * Provides product-specific configuration from kb.config.json.
+ * This adapter is available through platform.config and can be accessed
+ * via IPC in child processes.
+ *
+ * @example
+ * ```typescript
+ * // Get Mind product config
+ * const mindConfig = await platform.config.getConfig('mind');
+ * console.log(mindConfig.scopes);
+ *
+ * // Get Workflow config with specific profile
+ * const workflowConfig = await platform.config.getConfig('workflow', 'production');
+ * ```
+ */
+interface IConfig {
+    /**
+     * Get product-specific configuration.
+     *
+     * Extracts configuration for the specified product from kb.config.json.
+     * Supports both Profiles v2 structure and legacy structure.
+     *
+     * **Profiles v2 structure:**
+     * ```json
+     * {
+     *   "profiles": [
+     *     {
+     *       "id": "default",
+     *       "products": {
+     *         "mind": { "scopes": [...] },
+     *         "workflow": { "maxConcurrency": 10 }
+     *       }
+     *     }
+     *   ]
+     * }
+     * ```
+     *
+     * **Legacy structure:**
+     * ```json
+     * {
+     *   "knowledge": { "scopes": [...] },  // for "mind" product
+     *   "workflow": { "maxConcurrency": 10 }
+     * }
+     * ```
+     *
+     * @param productId - Product identifier (e.g., 'mind', 'workflow', 'plugins')
+     * @param profileId - Profile identifier (defaults to 'default' or KB_PROFILE env var)
+     * @returns Product-specific config or undefined if not found
+     */
+    getConfig(productId: string, profileId?: string): Promise<any>;
+    /**
+     * Get raw kb.config.json data.
+     *
+     * Returns the entire config object without any product/profile extraction.
+     * Useful for custom parsing or when you need access to multiple products.
+     *
+     * @returns Raw config object or undefined if not loaded
+     */
+    getRawConfig(): Promise<any>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/logger
+ * Logger abstraction for structured logging.
+ */
+/**
+ * Log level enumeration
+ */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/**
+ * Generate unique log ID using ULID.
+ *
+ * ULIDs are:
+ * - Lexicographically sortable (timestamp-based)
+ * - 26 characters (more compact than UUID's 36)
+ * - URL-safe (base32 encoded)
+ * - Monotonically increasing within same millisecond
+ *
+ * All logger adapters MUST use this function to ensure ID consistency.
+ *
+ * @returns ULID string (e.g., "01ARZ3NDEKTSV4RRFFQ69G5FAV")
+ *
+ * @example
+ * ```typescript
+ * const logId = generateLogId();
+ * console.log(logId); // "01HQVX5P7G3QR9Z8X5N4Y2K6E1"
+ * ```
+ */
+declare function generateLogId(): string;
+/**
+ * Structured log record
+ */
+interface LogRecord {
+    /** Unique log ID (ULID). Generated by logger adapter using generateLogId() */
+    id: string;
+    /** Timestamp (milliseconds since epoch) */
+    timestamp: number;
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Structured fields (metadata) */
+    fields: Record<string, unknown>;
+    /** Source identifier (e.g., 'rest', 'workflow', 'cli') */
+    source: string;
+}
+/**
+ * Query filters for log retrieval
+ */
+interface LogQuery {
+    /** Minimum log level (inclusive) */
+    level?: LogLevel;
+    /** Filter by source */
+    source?: string;
+    /** Start timestamp (milliseconds since epoch) */
+    from?: number;
+    /** End timestamp (milliseconds since epoch) */
+    to?: number;
+    /** Maximum number of logs to return */
+    limit?: number;
+}
+/**
+ * Log buffer interface for streaming/querying logs
+ */
+interface ILogBuffer {
+    /**
+     * Append log record to buffer
+     */
+    append(record: LogRecord): void;
+    /**
+     * Query logs with filters
+     */
+    query(query?: LogQuery): LogRecord[];
+    /**
+     * Subscribe to real-time log stream
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: (record: LogRecord) => void): () => void;
+    /**
+     * Get buffer statistics
+     */
+    getStats(): {
+        total: number;
+        bufferSize: number;
+        oldestTimestamp: number | null;
+        newestTimestamp: number | null;
+    };
+}
+/**
+ * Logger adapter interface.
+ * Implementations: @kb-labs/adapters-pino (production), ConsoleLogger (noop)
+ */
+interface ILogger {
+    /**
+     * Log info message.
+     * @param message - Log message
+     * @param meta - Optional metadata
+     */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log warning message.
+     * @param message - Log message
+     * @param meta - Optional metadata
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log error message.
+     * @param message - Log message
+     * @param error - Optional error object
+     * @param meta - Optional metadata
+     */
+    error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    /**
+     * Log fatal error message (critical failures).
+     * @param message - Log message
+     * @param error - Optional error object
+     * @param meta - Optional metadata
+     */
+    fatal(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    /**
+     * Log debug message.
+     * @param message - Log message
+     * @param meta - Optional metadata
+     */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log trace message (most verbose).
+     * @param message - Log message
+     * @param meta - Optional metadata
+     */
+    trace(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Create a child logger with additional context.
+     * @param bindings - Context bindings (e.g., { plugin: 'mind', tenant: 'acme' })
+     */
+    child(bindings: Record<string, unknown>): ILogger;
+    /**
+     * Get log buffer for streaming/querying (optional feature).
+     * Not all logger implementations support buffering.
+     * @returns Log buffer if streaming is enabled, undefined otherwise
+     */
+    getLogBuffer?(): ILogBuffer | undefined;
+    /**
+     * Register callback for every log event (optional feature).
+     * Used by platform to connect logger extensions (ring buffer, persistence).
+     *
+     * Extensions are called fire-and-forget (async errors are caught and logged).
+     * Multiple extensions can be registered and will be called in priority order.
+     *
+     * @param callback - Function to call on each log event
+     * @returns Unsubscribe function to remove the callback
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = logger.onLog((record) => {
+     *   ringBuffer.append(record);
+     *   persistence.write(record).catch(console.error);
+     * });
+     *
+     * // Later: unsubscribe()
+     * ```
+     */
+    onLog?(callback: (record: LogRecord) => void): () => void;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/event-bus
+ * Event bus abstraction for pub/sub messaging.
+ */
+/**
+ * Event handler function type.
+ */
+type EventHandler<T> = (event: T) => Promise<void>;
+/**
+ * Unsubscribe function returned by subscribe.
+ */
+type Unsubscribe = () => void;
+/**
+ * Event bus adapter interface.
+ * Implementations: MemoryEventBus (noop), can be extended with Redis/Kafka
+ */
+interface IEventBus {
+    /**
+     * Publish an event to a topic.
+     * @param topic - Event topic (e.g., 'workflow.completed')
+     * @param event - Event payload
+     */
+    publish<T>(topic: string, event: T): Promise<void>;
+    /**
+     * Subscribe to events on a topic.
+     * @param topic - Event topic (supports wildcards: 'workflow.*')
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     */
+    subscribe<T>(topic: string, handler: EventHandler<T>): Unsubscribe;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/invoke
+ * Inter-plugin invocation adapter interface.
+ */
+/**
+ * Request to invoke another plugin command.
+ */
+interface InvokeRequest {
+    /** Target plugin ID (e.g., 'mind-engine') */
+    pluginId: string;
+    /** Command to execute (e.g., 'rag-query') */
+    command: string;
+    /** Input payload for the command */
+    input?: unknown;
+    /** Timeout in milliseconds (optional) */
+    timeout?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from plugin invocation.
+ */
+interface InvokeResponse<T = unknown> {
+    /** Whether the invocation succeeded */
+    success: boolean;
+    /** Result data (if success) */
+    data?: T;
+    /** Error message (if failure) */
+    error?: string;
+    /** Execution metadata (duration, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Inter-plugin invocation adapter.
+ *
+ * Allows plugins to call commands from other plugins.
+ * The runtime enforces permissions and sandboxing.
+ *
+ * @example
+ * ```typescript
+ * // In plugin A, call plugin B
+ * const response = await ctx.platform.invoke?.call({
+ *   pluginId: 'plugin-b',
+ *   command: 'process-data',
+ *   input: { data: [...] },
+ * });
+ *
+ * if (response?.success) {
+ *   console.log(response.data);
+ * }
+ * ```
+ */
+interface IInvoke {
+    /**
+     * Invoke a command in another plugin.
+     *
+     * @param request - Invocation request
+     * @returns Response with result or error
+     */
+    call<T = unknown>(request: InvokeRequest): Promise<InvokeResponse<T>>;
+    /**
+     * Check if a plugin/command is available for invocation.
+     *
+     * @param pluginId - Target plugin ID
+     * @param command - Command name (optional, checks plugin availability)
+     * @returns True if available
+     */
+    isAvailable(pluginId: string, command?: string): Promise<boolean>;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/artifacts
+ * Artifact storage interface.
+ */
+/**
+ * Artifact metadata.
+ */
+interface ArtifactMeta {
+    /** Artifact key/path */
+    key: string;
+    /** Content type (e.g., 'application/json') */
+    contentType?: string;
+    /** Size in bytes */
+    size?: number;
+    /** Creation timestamp */
+    createdAt?: Date;
+    /** Last modified timestamp */
+    updatedAt?: Date;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Artifact write options.
+ */
+interface ArtifactWriteOptions {
+    /** Content type */
+    contentType?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** TTL in seconds (optional expiration) */
+    ttl?: number;
+}
+/**
+ * Artifact storage interface.
+ * Provides structured storage for plugin outputs.
+ */
+interface IArtifacts {
+    /**
+     * Write an artifact.
+     * @param key - Artifact key/path
+     * @param data - Data to write (will be serialized)
+     * @param options - Write options
+     */
+    write(key: string, data: unknown, options?: ArtifactWriteOptions): Promise<void>;
+    /**
+     * Read an artifact.
+     * @param key - Artifact key/path
+     * @returns Artifact data or null if not found
+     */
+    read<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Check if artifact exists.
+     * @param key - Artifact key/path
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Delete an artifact.
+     * @param key - Artifact key/path
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List artifacts by prefix.
+     * @param prefix - Key prefix
+     * @returns List of artifact metadata
+     */
+    list(prefix: string): Promise<ArtifactMeta[]>;
+    /**
+     * Get artifact metadata.
+     * @param key - Artifact key/path
+     */
+    getMeta(key: string): Promise<ArtifactMeta | null>;
+}
+
+export { type EventHandler as $, type AnalyticsContext as A, type BufferStatus as B, type LLMTier as C, type DlqStatus as D, type EventsQuery as E, type LLMCapability as F, type LLMResolution as G, type LLMAdapterBinding as H, type IAnalytics as I, type ILLMRouter as J, isTierHigher as K, type LogRecord as L, isTierLower as M, type IEmbeddings as N, type ICache as O, type IConfig as P, type IStorage as Q, type StorageMetadata as R, type StatsQuery as S, TIER_ORDER as T, type UseLLMOptions as U, type VectorRecord as V, type ILogger as W, type ILogBuffer as X, type LogLevel as Y, generateLogId as Z, type IEventBus as _, type LogQuery as a, type Unsubscribe as a0, type IInvoke as a1, type InvokeRequest as a2, type InvokeResponse as a3, type IArtifacts as a4, type ArtifactMeta as a5, type ArtifactWriteOptions as a6, type LLMRequestMetadata as a7, type AnalyticsEvent as b, type EventsResponse as c, type EventsStats as d, type DailyStats as e, type IVectorStore as f, type VectorSearchResult as g, type VectorFilter as h, type ILLM as i, type LLMOptions as j, type LLMResponse as k, type LLMExecutionPolicy as l, type LLMCachePolicy as m, type LLMStreamPolicy as n, type LLMCacheMode as o, type LLMCacheScope as p, type LLMStreamMode as q, type LLMProtocolCapabilities as r, type LLMCacheCapability as s, type LLMStreamCapability as t, type LLMCacheDecisionTrace as u, type LLMTool as v, type LLMToolCall as w, type LLMMessage as x, type LLMToolCallOptions as y, type LLMToolCallResponse as z };