@kb-labs/core-platform 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# @kb-labs/core-platform
+
+> Pure abstractions for KB Labs platform. Zero dependencies.
+
+## Purpose
+
+This package contains **only interfaces** - no implementations with external dependencies.
+All plugins and adapters depend on these interfaces.
+
+## Structure
+
+```
+src/
+├── adapters/           # Replaceable adapter interfaces
+│   ├── analytics.ts    # IAnalytics
+│   ├── vector-store.ts # IVectorStore
+│   ├── llm.ts          # ILLM
+│   ├── embeddings.ts   # IEmbeddings
+│   ├── cache.ts        # ICache
+│   ├── storage.ts      # IStorage
+│   ├── logger.ts       # ILogger
+│   └── event-bus.ts    # IEventBus
+├── core/               # Core feature interfaces (not replaceable)
+│   ├── workflow.ts     # IWorkflowEngine
+│   ├── jobs.ts         # IJobScheduler
+│   ├── cron.ts         # ICronManager
+│   └── resources.ts    # IResourceManager
+└── noop/               # NoOp + In-memory implementations
+    ├── adapters/       # NoOpAnalytics, MemoryCache, etc.
+    └── core/           # NoOpWorkflowEngine, etc.
+```
+
+## Usage
+
+### In Plugins
+```typescript
+import type { IAnalytics, IVectorStore } from '@kb-labs/core-platform';
+
+// Get through PluginContext
+export async function handler(ctx: PluginContext) {
+  await ctx.analytics.track('event');
+  await ctx.vectorStore.search([...]);
+}
+```
+
+### In Adapters
+```typescript
+import type { IAnalytics } from '@kb-labs/core-platform';
+
+export function createAdapter(): IAnalytics {
+  return {
+    async track(event, props) { /* ... */ },
+    async identify(userId, traits) { /* ... */ },
+    async flush() { /* ... */ },
+  };
+}
+```
+
+### Using NoOp Implementations
+```typescript
+import {
+  NoOpAnalytics,
+  MemoryCache,
+  MockLLM,
+} from '@kb-labs/core-platform/noop';
+
+// For testing
+const analytics = new NoOpAnalytics();
+const cache = new MemoryCache();
+const llm = new MockLLM();
+```
+
+## Adapter Interfaces
+
+| Interface | Description | NoOp Implementation |
+|-----------|-------------|---------------------|
+| `IAnalytics` | Event tracking and user identification | `NoOpAnalytics` |
+| `IVectorStore` | Vector similarity search | `MemoryVectorStore` |
+| `ILLM` | Large language model completion | `MockLLM` |
+| `IEmbeddings` | Text embeddings generation | `MockEmbeddings` |
+| `ICache` | Key-value caching with TTL | `MemoryCache` |
+| `IStorage` | File/blob storage | `MemoryStorage` |
+| `ILogger` | Structured logging | `ConsoleLogger` |
+| `IEventBus` | Pub/sub event system | `MemoryEventBus` |
+
+## Core Feature Interfaces
+
+| Interface | Description | NoOp Implementation |
+|-----------|-------------|---------------------|
+| `IWorkflowEngine` | Workflow execution and management | `NoOpWorkflowEngine` (throws) |
+| `IJobScheduler` | Background job scheduling | `NoOpJobScheduler` (sync) |
+| `ICronManager` | Cron job registration | `NoOpCronManager` |
+| `IResourceManager` | Resource quotas and limits | `NoOpResourceManager` (unlimited) |
+
+## Rules
+
+1. **Zero external dependencies** - only TypeScript types
+2. **Export types, not implementations** - implementations in noop/
+3. **Follow Pyramid Rule** - package name = core-platform
+
+## Related Packages
+
+- `@kb-labs/core-runtime` - DI container and core implementations
+- `@kb-labs/plugin-runtime` - PluginContext using these interfaces
+
+## ADR
+
+See [ADR-0040: Platform Core Adapter Architecture](../../docs/adr/0040-platform-core-adapter-architecture.md)

package/dist/adapters/index.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+var ulid = require('ulid');
+
+// src/adapters/llm-types.ts
+var TIER_ORDER = [
+  "small",
+  "medium",
+  "large"
+];
+function isTierHigher(a, b) {
+  return TIER_ORDER.indexOf(a) > TIER_ORDER.indexOf(b);
+}
+function isTierLower(a, b) {
+  return TIER_ORDER.indexOf(a) < TIER_ORDER.indexOf(b);
+}
+function generateLogId() {
+  return ulid.ulid();
+}
+
+exports.TIER_ORDER = TIER_ORDER;
+exports.generateLogId = generateLogId;
+exports.isTierHigher = isTierHigher;
+exports.isTierLower = isTierLower;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/adapters/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/llm-types.ts","../../src/adapters/logger.ts"],"names":["ulid"],"mappings":";;;;;AAqIO,IAAM,UAAA,GAAiC;AAAA,EAC5C,OAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF;AAKO,SAAS,YAAA,CAAa,GAAY,CAAA,EAAqB;AAC5D,EAAA,OAAO,WAAW,OAAA,CAAQ,CAAC,CAAA,GAAI,UAAA,CAAW,QAAQ,CAAC,CAAA;AACrD;AAKO,SAAS,WAAA,CAAY,GAAY,CAAA,EAAqB;AAC3D,EAAA,OAAO,WAAW,OAAA,CAAQ,CAAC,CAAA,GAAI,UAAA,CAAW,QAAQ,CAAC,CAAA;AACrD;ACxHO,SAAS,aAAA,GAAwB;AACtC,EAAA,OAAOA,SAAA,EAAK;AACd","file":"index.cjs","sourcesContent":["/**\n * @module @kb-labs/core-platform/adapters/llm-types\n * LLM tier and capability types for adaptive model routing.\n *\n * These types define the abstract layer between plugins and LLM providers.\n * Plugins request tiers/capabilities, platform resolves to actual models.\n *\n * @example\n * ```typescript\n * import { LLMTier, LLMCapability, UseLLMOptions } from '@kb-labs/sdk';\n *\n * // Plugin requests by tier (user decides what model)\n * const llm = useLLM({ tier: 'small' });\n * const llm = useLLM({ tier: 'large', capabilities: ['reasoning'] });\n * ```\n */\n\nimport type { ILLM, LLMExecutionPolicy } from './llm.js';\n\n/**\n * Model quality tier - user-defined slots.\n *\n * Tiers are NOT tied to specific models. They are abstract slots\n * that the user fills with whatever models they want in config.\n *\n * Plugin intent:\n * - `small`  - \"This task is simple, doesn't need much\"\n * - `medium` - \"Standard task\"\n * - `large`  - \"Complex task, need maximum quality\"\n *\n * User decides what model maps to each tier in their config.\n */\nexport type LLMTier = \"small\" | \"medium\" | \"large\";\n\n/**\n * Model capabilities - task-optimized features.\n *\n * - `fast`      - Lowest latency (for real-time responses)\n * - `reasoning` - Complex reasoning (o1, opus-level thinking)\n * - `coding`    - Code-optimized (better at code generation/review)\n * - `vision`    - Image input support\n */\nexport type LLMCapability = \"reasoning\" | \"coding\" | \"vision\" | \"fast\";\n\n/**\n * Options for useLLM() - plugin-facing API.\n *\n * Plugins specify what they need abstractly.\n * Platform resolves to actual provider/model based on user config.\n */\nexport interface UseLLMOptions {\n  /**\n   * Quality tier (user-defined slot).\n   * Platform adapts if exact tier unavailable:\n   * - Escalates up (small → medium) silently\n   * - Degrades down (large → medium) with warning\n   */\n  tier?: LLMTier;\n\n  /**\n   * Required capabilities.\n   * Platform selects model that supports ALL requested capabilities.\n   */\n  capabilities?: LLMCapability[];\n\n  /**\n   * Optional execution policy applied to this bound LLM instance.\n   * Can be overridden per-call via LLMOptions.execution.\n   */\n  execution?: LLMExecutionPolicy;\n}\n\n/**\n * Resolution result from tier/capability matching.\n * Internal type used by LLMRouter.\n */\nexport interface LLMResolution {\n  /** Resolved provider ID (e.g., 'openai', 'anthropic') */\n  provider: string;\n  /** Resolved model name */\n  model: string;\n  /** Resource name for ResourceBroker (e.g., 'llm:openai') */\n  resource: string;\n  /** Original requested tier */\n  requestedTier: LLMTier | undefined;\n  /** Actual tier being used */\n  actualTier: LLMTier;\n  /** Whether this was escalated/degraded */\n  adapted: boolean;\n  /** Warning message if degraded */\n  warning?: string;\n}\n\n/**\n * Resolved adapter binding — immutable snapshot of a tier resolution.\n * Returned by resolveAdapter() to avoid global state mutation.\n */\nexport interface LLMAdapterBinding {\n  /** The concrete adapter instance (already wrapped with analytics, etc.) */\n  adapter: ILLM;\n  /** Resolved model name */\n  model: string;\n  /** Actual tier used */\n  tier: LLMTier;\n}\n\n/**\n * LLM Router interface - extends ILLM with routing capabilities.\n * Implemented by @kb-labs/llm-router.\n */\nexport interface ILLMRouter {\n  /** Get configured tier (what user set in config) */\n  getConfiguredTier(): LLMTier;\n\n  /** Resolve tier request to actual model (mutates router state — legacy) */\n  resolve(options?: UseLLMOptions): LLMResolution;\n\n  /**\n   * Resolve tier and return an immutable adapter binding.\n   * Does NOT mutate router state — safe for concurrent useLLM() calls.\n   */\n  resolveAdapter(options?: UseLLMOptions): Promise<LLMAdapterBinding>;\n\n  /** Check if capability is available */\n  hasCapability(capability: LLMCapability): boolean;\n\n  /** Get available capabilities */\n  getCapabilities(): LLMCapability[];\n}\n\n/**\n * Tier order for resolution (lowest to highest).\n */\nexport const TIER_ORDER: readonly LLMTier[] = [\n  \"small\",\n  \"medium\",\n  \"large\",\n] as const;\n\n/**\n * Check if tier A is higher than tier B.\n */\nexport function isTierHigher(a: LLMTier, b: LLMTier): boolean {\n  return TIER_ORDER.indexOf(a) > TIER_ORDER.indexOf(b);\n}\n\n/**\n * Check if tier A is lower than tier B.\n */\nexport function isTierLower(a: LLMTier, b: LLMTier): boolean {\n  return TIER_ORDER.indexOf(a) < TIER_ORDER.indexOf(b);\n}\n","/**\n * @module @kb-labs/core-platform/adapters/logger\n * Logger abstraction for structured logging.\n */\n\nimport { ulid } from \"ulid\";\n\n/**\n * Log level enumeration\n */\nexport type LogLevel = \"trace\" | \"debug\" | \"info\" | \"warn\" | \"error\" | \"fatal\";\n\n/**\n * Generate unique log ID using ULID.\n *\n * ULIDs are:\n * - Lexicographically sortable (timestamp-based)\n * - 26 characters (more compact than UUID's 36)\n * - URL-safe (base32 encoded)\n * - Monotonically increasing within same millisecond\n *\n * All logger adapters MUST use this function to ensure ID consistency.\n *\n * @returns ULID string (e.g., \"01ARZ3NDEKTSV4RRFFQ69G5FAV\")\n *\n * @example\n * ```typescript\n * const logId = generateLogId();\n * console.log(logId); // \"01HQVX5P7G3QR9Z8X5N4Y2K6E1\"\n * ```\n */\nexport function generateLogId(): string {\n  return ulid();\n}\n\n/**\n * Structured log record\n */\nexport interface LogRecord {\n  /** Unique log ID (ULID). Generated by logger adapter using generateLogId() */\n  id: string;\n  /** Timestamp (milliseconds since epoch) */\n  timestamp: number;\n  /** Log level */\n  level: LogLevel;\n  /** Log message */\n  message: string;\n  /** Structured fields (metadata) */\n  fields: Record<string, unknown>;\n  /** Source identifier (e.g., 'rest', 'workflow', 'cli') */\n  source: string;\n}\n\n/**\n * Query filters for log retrieval\n */\nexport interface LogQuery {\n  /** Minimum log level (inclusive) */\n  level?: LogLevel;\n  /** Filter by source */\n  source?: string;\n  /** Start timestamp (milliseconds since epoch) */\n  from?: number;\n  /** End timestamp (milliseconds since epoch) */\n  to?: number;\n  /** Maximum number of logs to return */\n  limit?: number;\n}\n\n/**\n * Log buffer interface for streaming/querying logs\n */\nexport interface ILogBuffer {\n  /**\n   * Append log record to buffer\n   */\n  append(record: LogRecord): void;\n\n  /**\n   * Query logs with filters\n   */\n  query(query?: LogQuery): LogRecord[];\n\n  /**\n   * Subscribe to real-time log stream\n   * @returns Unsubscribe function\n   */\n  subscribe(callback: (record: LogRecord) => void): () => void;\n\n  /**\n   * Get buffer statistics\n   */\n  getStats(): {\n    total: number;\n    bufferSize: number;\n    oldestTimestamp: number | null;\n    newestTimestamp: number | null;\n  };\n}\n\n/**\n * Logger adapter interface.\n * Implementations: @kb-labs/adapters-pino (production), ConsoleLogger (noop)\n */\nexport interface ILogger {\n  /**\n   * Log info message.\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  info(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log warning message.\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  warn(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log error message.\n   * @param message - Log message\n   * @param error - Optional error object\n   * @param meta - Optional metadata\n   */\n  error(message: string, error?: Error, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log fatal error message (critical failures).\n   * @param message - Log message\n   * @param error - Optional error object\n   * @param meta - Optional metadata\n   */\n  fatal(message: string, error?: Error, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log debug message.\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  debug(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log trace message (most verbose).\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  trace(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Create a child logger with additional context.\n   * @param bindings - Context bindings (e.g., { plugin: 'mind', tenant: 'acme' })\n   */\n  child(bindings: Record<string, unknown>): ILogger;\n\n  /**\n   * Get log buffer for streaming/querying (optional feature).\n   * Not all logger implementations support buffering.\n   * @returns Log buffer if streaming is enabled, undefined otherwise\n   */\n  getLogBuffer?(): ILogBuffer | undefined;\n\n  /**\n   * Register callback for every log event (optional feature).\n   * Used by platform to connect logger extensions (ring buffer, persistence).\n   *\n   * Extensions are called fire-and-forget (async errors are caught and logged).\n   * Multiple extensions can be registered and will be called in priority order.\n   *\n   * @param callback - Function to call on each log event\n   * @returns Unsubscribe function to remove the callback\n   *\n   * @example\n   * ```typescript\n   * const unsubscribe = logger.onLog((record) => {\n   *   ringBuffer.append(record);\n   *   persistence.write(record).catch(console.error);\n   * });\n   *\n   * // Later: unsubscribe()\n   * ```\n   */\n  onLog?(callback: (record: LogRecord) => void): () => void;\n}\n"]}

package/dist/adapters/index.d.cts

@@ -0,0 +1,125 @@
+export { d as AdapterCapabilities, b as AdapterDependency, c as AdapterExtension, e as AdapterFactory, A as AdapterManifest, a as AdapterType, t as AttachWorkspaceRequest, y as CaptureSnapshotRequest, C as CreateEnvironmentRequest, n as EnvironmentDescriptor, m as EnvironmentEndpoint, l as EnvironmentLease, p as EnvironmentProviderCapabilities, k as EnvironmentResources, j as EnvironmentStatus, o as EnvironmentStatusResult, h as ExecuteOptions, E as ExecutionRequest, g as ExecutionResult, i as IEnvironmentProvider, f as IExecutionBackend, I as ILogPersistence, x as ISnapshotProvider, q as IWorkspaceProvider, L as LogPersistenceConfig, M as MaterializeWorkspaceRequest, R as RestoreSnapshotRequest, B as RestoreSnapshotResult, z as SnapshotDescriptor, F as SnapshotGarbageCollectRequest, G as SnapshotGarbageCollectResult, H as SnapshotProviderCapabilities, S as SnapshotStatus, D as SnapshotStatusResult, u as WorkspaceAttachment, s as WorkspaceDescriptor, r as WorkspaceMount, w as WorkspaceProviderCapabilities, W as WorkspaceStatus, v as WorkspaceStatusResult } from '../snapshot-provider-nE9wuc1C.cjs';
+import { L as LogRecord, a as LogQuery } from '../artifacts-DrVnkLzu.cjs';
+export { A as AnalyticsContext, b as AnalyticsEvent, a5 as ArtifactMeta, a6 as ArtifactWriteOptions, B as BufferStatus, e as DailyStats, D as DlqStatus, $ as EventHandler, E as EventsQuery, c as EventsResponse, d as EventsStats, I as IAnalytics, a4 as IArtifacts, O as ICache, P as IConfig, N as IEmbeddings, _ as IEventBus, a1 as IInvoke, i as ILLM, J as ILLMRouter, X as ILogBuffer, W as ILogger, Q as IStorage, f as IVectorStore, a2 as InvokeRequest, a3 as InvokeResponse, H as LLMAdapterBinding, s as LLMCacheCapability, u as LLMCacheDecisionTrace, o as LLMCacheMode, m as LLMCachePolicy, p as LLMCacheScope, F as LLMCapability, l as LLMExecutionPolicy, x as LLMMessage, j as LLMOptions, r as LLMProtocolCapabilities, G as LLMResolution, k as LLMResponse, t as LLMStreamCapability, q as LLMStreamMode, n as LLMStreamPolicy, C as LLMTier, v as LLMTool, w as LLMToolCall, y as LLMToolCallOptions, z as LLMToolCallResponse, Y as LogLevel, S as StatsQuery, R as StorageMetadata, T as TIER_ORDER, a0 as Unsubscribe, U as UseLLMOptions, h as VectorFilter, V as VectorRecord, g as VectorSearchResult, Z as generateLogId, K as isTierHigher, M as isTierLower } from '../artifacts-DrVnkLzu.cjs';
+export { B as BaseDocument, D as DocumentFilter, c as DocumentUpdate, F as FilterOperators, d as FindOptions, g as IDatabaseProvider, b as IDocumentDatabase, e as IKeyValueDatabase, I as ISQLDatabase, f as ITimeSeriesDatabase, S as SQLQueryResult, a as SQLTransaction, T as TimeSeriesPoint } from '../database-DGV6a1nj.cjs';
+export { I as ILogReader, L as LogCapabilities, a as LogQueryOptions, b as LogQueryResult, c as LogSearchOptions, d as LogSearchResult, e as LogStats } from '../log-reader-BVohbSMB.cjs';
+
+/**
+ * @module @kb-labs/core-platform/adapters/log-ring-buffer
+ * Ring buffer adapter interface for real-time log streaming.
+ *
+ * Purpose:
+ * - In-memory buffer with fixed size and TTL
+ * - Real-time subscription support (SSE)
+ * - Low latency access to recent logs
+ *
+ * Not for:
+ * - Historical queries (use ILogPersistence)
+ * - Cross-process log aggregation
+ * - Long-term storage
+ */
+
+/**
+ * Ring buffer for real-time log streaming.
+ *
+ * Design:
+ * - Fixed-size circular buffer (default 1000 logs)
+ * - Automatic eviction of oldest logs when buffer is full
+ * - Time-to-live expiration (default 1 hour)
+ * - Real-time subscription support for SSE streaming
+ *
+ * @example
+ * ```typescript
+ * const buffer = createRingBufferAdapter({ maxSize: 1000, ttl: 3600000 });
+ *
+ * // Append logs
+ * buffer.append({ timestamp: Date.now(), level: 'info', message: 'Hello' });
+ *
+ * // Subscribe to real-time stream
+ * const unsubscribe = buffer.subscribe((log) => {
+ *   console.log('New log:', log);
+ * });
+ *
+ * // Query recent logs
+ * const recentErrors = buffer.query({ level: 'error' });
+ * ```
+ */
+interface ILogRingBuffer {
+    /**
+     * Append log record to buffer.
+     * Evicts oldest record if buffer is full.
+     *
+     * @param record - Log record to append
+     */
+    append(record: LogRecord): void;
+    /**
+     * Query logs from buffer.
+     *
+     * @param query - Optional filter (level, timestamp range, source)
+     * @returns Array of logs matching query (most recent first)
+     */
+    query(query?: LogQuery): LogRecord[];
+    /**
+     * Subscribe to real-time log events.
+     * Callback is called for each new log record appended to buffer.
+     *
+     * @param callback - Called for each new log record
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = buffer.subscribe((log) => {
+     *   if (log.level === 'error') {
+     *     notifyUser(log);
+     *   }
+     * });
+     *
+     * // Later: stop subscription
+     * unsubscribe();
+     * ```
+     */
+    subscribe(callback: (record: LogRecord) => void): () => void;
+    /**
+     * Get buffer statistics.
+     *
+     * @returns Buffer stats including size, capacity, and eviction count
+     */
+    getStats(): {
+        /** Current number of logs in buffer */
+        size: number;
+        /** Maximum buffer size */
+        maxSize: number;
+        /** Timestamp of oldest log in buffer (0 if empty) */
+        oldestTimestamp: number;
+        /** Timestamp of newest log in buffer (0 if empty) */
+        newestTimestamp: number;
+        /** Total number of logs evicted due to size/TTL */
+        evictions: number;
+    };
+    /**
+     * Clear all logs from buffer.
+     * Useful for testing or manual cleanup.
+     */
+    clear(): void;
+}
+/**
+ * Configuration for log ring buffer adapter.
+ */
+interface LogRingBufferConfig {
+    /**
+     * Maximum number of logs to keep in memory.
+     * When buffer is full, oldest log is evicted.
+     *
+     * @default 1000
+     */
+    maxSize?: number;
+    /**
+     * Time-to-live for logs in milliseconds.
+     * Logs older than this are automatically evicted.
+     *
+     * @default 3600000 (1 hour)
+     */
+    ttl?: number;
+}
+
+export { type ILogRingBuffer, LogQuery, LogRecord, type LogRingBufferConfig };

package/dist/adapters/index.d.ts

@@ -0,0 +1,125 @@
+export { d as AdapterCapabilities, b as AdapterDependency, c as AdapterExtension, e as AdapterFactory, A as AdapterManifest, a as AdapterType, t as AttachWorkspaceRequest, y as CaptureSnapshotRequest, C as CreateEnvironmentRequest, n as EnvironmentDescriptor, m as EnvironmentEndpoint, l as EnvironmentLease, p as EnvironmentProviderCapabilities, k as EnvironmentResources, j as EnvironmentStatus, o as EnvironmentStatusResult, h as ExecuteOptions, E as ExecutionRequest, g as ExecutionResult, i as IEnvironmentProvider, f as IExecutionBackend, I as ILogPersistence, x as ISnapshotProvider, q as IWorkspaceProvider, L as LogPersistenceConfig, M as MaterializeWorkspaceRequest, R as RestoreSnapshotRequest, B as RestoreSnapshotResult, z as SnapshotDescriptor, F as SnapshotGarbageCollectRequest, G as SnapshotGarbageCollectResult, H as SnapshotProviderCapabilities, S as SnapshotStatus, D as SnapshotStatusResult, u as WorkspaceAttachment, s as WorkspaceDescriptor, r as WorkspaceMount, w as WorkspaceProviderCapabilities, W as WorkspaceStatus, v as WorkspaceStatusResult } from '../snapshot-provider--COac4P-.js';
+import { L as LogRecord, a as LogQuery } from '../artifacts-DrVnkLzu.js';
+export { A as AnalyticsContext, b as AnalyticsEvent, a5 as ArtifactMeta, a6 as ArtifactWriteOptions, B as BufferStatus, e as DailyStats, D as DlqStatus, $ as EventHandler, E as EventsQuery, c as EventsResponse, d as EventsStats, I as IAnalytics, a4 as IArtifacts, O as ICache, P as IConfig, N as IEmbeddings, _ as IEventBus, a1 as IInvoke, i as ILLM, J as ILLMRouter, X as ILogBuffer, W as ILogger, Q as IStorage, f as IVectorStore, a2 as InvokeRequest, a3 as InvokeResponse, H as LLMAdapterBinding, s as LLMCacheCapability, u as LLMCacheDecisionTrace, o as LLMCacheMode, m as LLMCachePolicy, p as LLMCacheScope, F as LLMCapability, l as LLMExecutionPolicy, x as LLMMessage, j as LLMOptions, r as LLMProtocolCapabilities, G as LLMResolution, k as LLMResponse, t as LLMStreamCapability, q as LLMStreamMode, n as LLMStreamPolicy, C as LLMTier, v as LLMTool, w as LLMToolCall, y as LLMToolCallOptions, z as LLMToolCallResponse, Y as LogLevel, S as StatsQuery, R as StorageMetadata, T as TIER_ORDER, a0 as Unsubscribe, U as UseLLMOptions, h as VectorFilter, V as VectorRecord, g as VectorSearchResult, Z as generateLogId, K as isTierHigher, M as isTierLower } from '../artifacts-DrVnkLzu.js';
+export { B as BaseDocument, D as DocumentFilter, c as DocumentUpdate, F as FilterOperators, d as FindOptions, g as IDatabaseProvider, b as IDocumentDatabase, e as IKeyValueDatabase, I as ISQLDatabase, f as ITimeSeriesDatabase, S as SQLQueryResult, a as SQLTransaction, T as TimeSeriesPoint } from '../database-DGV6a1nj.js';
+export { I as ILogReader, L as LogCapabilities, a as LogQueryOptions, b as LogQueryResult, c as LogSearchOptions, d as LogSearchResult, e as LogStats } from '../log-reader-uOHBLBax.js';
+
+/**
+ * @module @kb-labs/core-platform/adapters/log-ring-buffer
+ * Ring buffer adapter interface for real-time log streaming.
+ *
+ * Purpose:
+ * - In-memory buffer with fixed size and TTL
+ * - Real-time subscription support (SSE)
+ * - Low latency access to recent logs
+ *
+ * Not for:
+ * - Historical queries (use ILogPersistence)
+ * - Cross-process log aggregation
+ * - Long-term storage
+ */
+
+/**
+ * Ring buffer for real-time log streaming.
+ *
+ * Design:
+ * - Fixed-size circular buffer (default 1000 logs)
+ * - Automatic eviction of oldest logs when buffer is full
+ * - Time-to-live expiration (default 1 hour)
+ * - Real-time subscription support for SSE streaming
+ *
+ * @example
+ * ```typescript
+ * const buffer = createRingBufferAdapter({ maxSize: 1000, ttl: 3600000 });
+ *
+ * // Append logs
+ * buffer.append({ timestamp: Date.now(), level: 'info', message: 'Hello' });
+ *
+ * // Subscribe to real-time stream
+ * const unsubscribe = buffer.subscribe((log) => {
+ *   console.log('New log:', log);
+ * });
+ *
+ * // Query recent logs
+ * const recentErrors = buffer.query({ level: 'error' });
+ * ```
+ */
+interface ILogRingBuffer {
+    /**
+     * Append log record to buffer.
+     * Evicts oldest record if buffer is full.
+     *
+     * @param record - Log record to append
+     */
+    append(record: LogRecord): void;
+    /**
+     * Query logs from buffer.
+     *
+     * @param query - Optional filter (level, timestamp range, source)
+     * @returns Array of logs matching query (most recent first)
+     */
+    query(query?: LogQuery): LogRecord[];
+    /**
+     * Subscribe to real-time log events.
+     * Callback is called for each new log record appended to buffer.
+     *
+     * @param callback - Called for each new log record
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = buffer.subscribe((log) => {
+     *   if (log.level === 'error') {
+     *     notifyUser(log);
+     *   }
+     * });
+     *
+     * // Later: stop subscription
+     * unsubscribe();
+     * ```
+     */
+    subscribe(callback: (record: LogRecord) => void): () => void;
+    /**
+     * Get buffer statistics.
+     *
+     * @returns Buffer stats including size, capacity, and eviction count
+     */
+    getStats(): {
+        /** Current number of logs in buffer */
+        size: number;
+        /** Maximum buffer size */
+        maxSize: number;
+        /** Timestamp of oldest log in buffer (0 if empty) */
+        oldestTimestamp: number;
+        /** Timestamp of newest log in buffer (0 if empty) */
+        newestTimestamp: number;
+        /** Total number of logs evicted due to size/TTL */
+        evictions: number;
+    };
+    /**
+     * Clear all logs from buffer.
+     * Useful for testing or manual cleanup.
+     */
+    clear(): void;
+}
+/**
+ * Configuration for log ring buffer adapter.
+ */
+interface LogRingBufferConfig {
+    /**
+     * Maximum number of logs to keep in memory.
+     * When buffer is full, oldest log is evicted.
+     *
+     * @default 1000
+     */
+    maxSize?: number;
+    /**
+     * Time-to-live for logs in milliseconds.
+     * Logs older than this are automatically evicted.
+     *
+     * @default 3600000 (1 hour)
+     */
+    ttl?: number;
+}
+
+export { type ILogRingBuffer, LogQuery, LogRecord, type LogRingBufferConfig };

package/dist/adapters/index.js

@@ -0,0 +1,21 @@
+import { ulid } from 'ulid';
+
+// src/adapters/llm-types.ts
+var TIER_ORDER = [
+  "small",
+  "medium",
+  "large"
+];
+function isTierHigher(a, b) {
+  return TIER_ORDER.indexOf(a) > TIER_ORDER.indexOf(b);
+}
+function isTierLower(a, b) {
+  return TIER_ORDER.indexOf(a) < TIER_ORDER.indexOf(b);
+}
+function generateLogId() {
+  return ulid();
+}
+
+export { TIER_ORDER, generateLogId, isTierHigher, isTierLower };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/llm-types.ts","../../src/adapters/logger.ts"],"names":[],"mappings":";;;AAqIO,IAAM,UAAA,GAAiC;AAAA,EAC5C,OAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF;AAKO,SAAS,YAAA,CAAa,GAAY,CAAA,EAAqB;AAC5D,EAAA,OAAO,WAAW,OAAA,CAAQ,CAAC,CAAA,GAAI,UAAA,CAAW,QAAQ,CAAC,CAAA;AACrD;AAKO,SAAS,WAAA,CAAY,GAAY,CAAA,EAAqB;AAC3D,EAAA,OAAO,WAAW,OAAA,CAAQ,CAAC,CAAA,GAAI,UAAA,CAAW,QAAQ,CAAC,CAAA;AACrD;ACxHO,SAAS,aAAA,GAAwB;AACtC,EAAA,OAAO,IAAA,EAAK;AACd","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/core-platform/adapters/llm-types\n * LLM tier and capability types for adaptive model routing.\n *\n * These types define the abstract layer between plugins and LLM providers.\n * Plugins request tiers/capabilities, platform resolves to actual models.\n *\n * @example\n * ```typescript\n * import { LLMTier, LLMCapability, UseLLMOptions } from '@kb-labs/sdk';\n *\n * // Plugin requests by tier (user decides what model)\n * const llm = useLLM({ tier: 'small' });\n * const llm = useLLM({ tier: 'large', capabilities: ['reasoning'] });\n * ```\n */\n\nimport type { ILLM, LLMExecutionPolicy } from './llm.js';\n\n/**\n * Model quality tier - user-defined slots.\n *\n * Tiers are NOT tied to specific models. They are abstract slots\n * that the user fills with whatever models they want in config.\n *\n * Plugin intent:\n * - `small`  - \"This task is simple, doesn't need much\"\n * - `medium` - \"Standard task\"\n * - `large`  - \"Complex task, need maximum quality\"\n *\n * User decides what model maps to each tier in their config.\n */\nexport type LLMTier = \"small\" | \"medium\" | \"large\";\n\n/**\n * Model capabilities - task-optimized features.\n *\n * - `fast`      - Lowest latency (for real-time responses)\n * - `reasoning` - Complex reasoning (o1, opus-level thinking)\n * - `coding`    - Code-optimized (better at code generation/review)\n * - `vision`    - Image input support\n */\nexport type LLMCapability = \"reasoning\" | \"coding\" | \"vision\" | \"fast\";\n\n/**\n * Options for useLLM() - plugin-facing API.\n *\n * Plugins specify what they need abstractly.\n * Platform resolves to actual provider/model based on user config.\n */\nexport interface UseLLMOptions {\n  /**\n   * Quality tier (user-defined slot).\n   * Platform adapts if exact tier unavailable:\n   * - Escalates up (small → medium) silently\n   * - Degrades down (large → medium) with warning\n   */\n  tier?: LLMTier;\n\n  /**\n   * Required capabilities.\n   * Platform selects model that supports ALL requested capabilities.\n   */\n  capabilities?: LLMCapability[];\n\n  /**\n   * Optional execution policy applied to this bound LLM instance.\n   * Can be overridden per-call via LLMOptions.execution.\n   */\n  execution?: LLMExecutionPolicy;\n}\n\n/**\n * Resolution result from tier/capability matching.\n * Internal type used by LLMRouter.\n */\nexport interface LLMResolution {\n  /** Resolved provider ID (e.g., 'openai', 'anthropic') */\n  provider: string;\n  /** Resolved model name */\n  model: string;\n  /** Resource name for ResourceBroker (e.g., 'llm:openai') */\n  resource: string;\n  /** Original requested tier */\n  requestedTier: LLMTier | undefined;\n  /** Actual tier being used */\n  actualTier: LLMTier;\n  /** Whether this was escalated/degraded */\n  adapted: boolean;\n  /** Warning message if degraded */\n  warning?: string;\n}\n\n/**\n * Resolved adapter binding — immutable snapshot of a tier resolution.\n * Returned by resolveAdapter() to avoid global state mutation.\n */\nexport interface LLMAdapterBinding {\n  /** The concrete adapter instance (already wrapped with analytics, etc.) */\n  adapter: ILLM;\n  /** Resolved model name */\n  model: string;\n  /** Actual tier used */\n  tier: LLMTier;\n}\n\n/**\n * LLM Router interface - extends ILLM with routing capabilities.\n * Implemented by @kb-labs/llm-router.\n */\nexport interface ILLMRouter {\n  /** Get configured tier (what user set in config) */\n  getConfiguredTier(): LLMTier;\n\n  /** Resolve tier request to actual model (mutates router state — legacy) */\n  resolve(options?: UseLLMOptions): LLMResolution;\n\n  /**\n   * Resolve tier and return an immutable adapter binding.\n   * Does NOT mutate router state — safe for concurrent useLLM() calls.\n   */\n  resolveAdapter(options?: UseLLMOptions): Promise<LLMAdapterBinding>;\n\n  /** Check if capability is available */\n  hasCapability(capability: LLMCapability): boolean;\n\n  /** Get available capabilities */\n  getCapabilities(): LLMCapability[];\n}\n\n/**\n * Tier order for resolution (lowest to highest).\n */\nexport const TIER_ORDER: readonly LLMTier[] = [\n  \"small\",\n  \"medium\",\n  \"large\",\n] as const;\n\n/**\n * Check if tier A is higher than tier B.\n */\nexport function isTierHigher(a: LLMTier, b: LLMTier): boolean {\n  return TIER_ORDER.indexOf(a) > TIER_ORDER.indexOf(b);\n}\n\n/**\n * Check if tier A is lower than tier B.\n */\nexport function isTierLower(a: LLMTier, b: LLMTier): boolean {\n  return TIER_ORDER.indexOf(a) < TIER_ORDER.indexOf(b);\n}\n","/**\n * @module @kb-labs/core-platform/adapters/logger\n * Logger abstraction for structured logging.\n */\n\nimport { ulid } from \"ulid\";\n\n/**\n * Log level enumeration\n */\nexport type LogLevel = \"trace\" | \"debug\" | \"info\" | \"warn\" | \"error\" | \"fatal\";\n\n/**\n * Generate unique log ID using ULID.\n *\n * ULIDs are:\n * - Lexicographically sortable (timestamp-based)\n * - 26 characters (more compact than UUID's 36)\n * - URL-safe (base32 encoded)\n * - Monotonically increasing within same millisecond\n *\n * All logger adapters MUST use this function to ensure ID consistency.\n *\n * @returns ULID string (e.g., \"01ARZ3NDEKTSV4RRFFQ69G5FAV\")\n *\n * @example\n * ```typescript\n * const logId = generateLogId();\n * console.log(logId); // \"01HQVX5P7G3QR9Z8X5N4Y2K6E1\"\n * ```\n */\nexport function generateLogId(): string {\n  return ulid();\n}\n\n/**\n * Structured log record\n */\nexport interface LogRecord {\n  /** Unique log ID (ULID). Generated by logger adapter using generateLogId() */\n  id: string;\n  /** Timestamp (milliseconds since epoch) */\n  timestamp: number;\n  /** Log level */\n  level: LogLevel;\n  /** Log message */\n  message: string;\n  /** Structured fields (metadata) */\n  fields: Record<string, unknown>;\n  /** Source identifier (e.g., 'rest', 'workflow', 'cli') */\n  source: string;\n}\n\n/**\n * Query filters for log retrieval\n */\nexport interface LogQuery {\n  /** Minimum log level (inclusive) */\n  level?: LogLevel;\n  /** Filter by source */\n  source?: string;\n  /** Start timestamp (milliseconds since epoch) */\n  from?: number;\n  /** End timestamp (milliseconds since epoch) */\n  to?: number;\n  /** Maximum number of logs to return */\n  limit?: number;\n}\n\n/**\n * Log buffer interface for streaming/querying logs\n */\nexport interface ILogBuffer {\n  /**\n   * Append log record to buffer\n   */\n  append(record: LogRecord): void;\n\n  /**\n   * Query logs with filters\n   */\n  query(query?: LogQuery): LogRecord[];\n\n  /**\n   * Subscribe to real-time log stream\n   * @returns Unsubscribe function\n   */\n  subscribe(callback: (record: LogRecord) => void): () => void;\n\n  /**\n   * Get buffer statistics\n   */\n  getStats(): {\n    total: number;\n    bufferSize: number;\n    oldestTimestamp: number | null;\n    newestTimestamp: number | null;\n  };\n}\n\n/**\n * Logger adapter interface.\n * Implementations: @kb-labs/adapters-pino (production), ConsoleLogger (noop)\n */\nexport interface ILogger {\n  /**\n   * Log info message.\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  info(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log warning message.\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  warn(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log error message.\n   * @param message - Log message\n   * @param error - Optional error object\n   * @param meta - Optional metadata\n   */\n  error(message: string, error?: Error, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log fatal error message (critical failures).\n   * @param message - Log message\n   * @param error - Optional error object\n   * @param meta - Optional metadata\n   */\n  fatal(message: string, error?: Error, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log debug message.\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  debug(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Log trace message (most verbose).\n   * @param message - Log message\n   * @param meta - Optional metadata\n   */\n  trace(message: string, meta?: Record<string, unknown>): void;\n\n  /**\n   * Create a child logger with additional context.\n   * @param bindings - Context bindings (e.g., { plugin: 'mind', tenant: 'acme' })\n   */\n  child(bindings: Record<string, unknown>): ILogger;\n\n  /**\n   * Get log buffer for streaming/querying (optional feature).\n   * Not all logger implementations support buffering.\n   * @returns Log buffer if streaming is enabled, undefined otherwise\n   */\n  getLogBuffer?(): ILogBuffer | undefined;\n\n  /**\n   * Register callback for every log event (optional feature).\n   * Used by platform to connect logger extensions (ring buffer, persistence).\n   *\n   * Extensions are called fire-and-forget (async errors are caught and logged).\n   * Multiple extensions can be registered and will be called in priority order.\n   *\n   * @param callback - Function to call on each log event\n   * @returns Unsubscribe function to remove the callback\n   *\n   * @example\n   * ```typescript\n   * const unsubscribe = logger.onLog((record) => {\n   *   ringBuffer.append(record);\n   *   persistence.write(record).catch(console.error);\n   * });\n   *\n   * // Later: unsubscribe()\n   * ```\n   */\n  onLog?(callback: (record: LogRecord) => void): () => void;\n}\n"]}