@kb-labs/core-platform 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,579 @@
+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 { i as ILLM, I as IAnalytics, r as LLMProtocolCapabilities, j as LLMOptions, k as LLMResponse, x as LLMMessage, y as LLMToolCallOptions, z as LLMToolCallResponse, N as IEmbeddings, f as IVectorStore, h as VectorFilter, g as VectorSearchResult, V as VectorRecord, O as ICache, Q as IStorage, E as EventsQuery, c as EventsResponse, d as EventsStats, B as BufferStatus, D as DlqStatus, W as ILogger, P as IConfig, _ as IEventBus, a1 as IInvoke, a4 as IArtifacts } from './artifacts-DrVnkLzu.cjs';
+export { a5 as ArtifactMeta, a6 as ArtifactWriteOptions, $ as EventHandler, J as ILLMRouter, X as ILogBuffer, 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, a7 as LLMRequestMetadata, G as LLMResolution, t as LLMStreamCapability, q as LLMStreamMode, n as LLMStreamPolicy, C as LLMTier, v as LLMTool, w as LLMToolCall, Y as LogLevel, a as LogQuery, L as LogRecord, T as TIER_ORDER, a0 as Unsubscribe, U as UseLLMOptions, K as isTierHigher, M as isTierLower } from './artifacts-DrVnkLzu.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';
+export { j as CronContext, C as CronExpression, k as CronHandler, i as CronJob, h as ICronManager, d as IJobScheduler, l as IResourceManager, I as IWorkflowEngine, J as JobDefinition, g as JobFilter, e as JobHandle, f as JobStatus, o as ResourceAvailability, n as ResourceSlot, m as ResourceType, R as RetryPolicy, T as TenantQuotas, c as WorkflowFilter, W as WorkflowOptions, a as WorkflowRun, b as WorkflowStepRun } from './resources-DaufJFad.cjs';
+import './database-DGV6a1nj.cjs';
+
+/**
+ * @module @kb-labs/core-platform/wrappers/analytics-llm
+ * AnalyticsLLM - ILLM wrapper that tracks usage to analytics.
+ */
+
+/**
+ * ILLM wrapper that tracks all LLM calls to analytics.
+ *
+ * Features:
+ * - Tracks every LLM completion with token usage
+ * - Records model, prompt/completion tokens, timestamps
+ * - Transparent (implements ILLM interface)
+ * - Automatically calculates cost estimates
+ *
+ * Tracked metrics:
+ * - llm.completion.started
+ * - llm.completion.completed (with usage, duration, model)
+ * - llm.completion.error (with error details)
+ *
+ * @example
+ * ```typescript
+ * const trackedLLM = new AnalyticsLLM(realLLM, analytics);
+ *
+ * // Automatically tracked
+ * const response = await trackedLLM.complete('Hello');
+ * // → Tracks: model, tokens, duration
+ * ```
+ */
+declare class AnalyticsLLM implements ILLM {
+    private realLLM;
+    private analytics;
+    constructor(realLLM: ILLM, analytics: IAnalytics);
+    getProtocolCapabilities(): Promise<LLMProtocolCapabilities>;
+    /**
+     * Generate a completion with analytics tracking.
+     */
+    complete(prompt: string, options?: LLMOptions): Promise<LLMResponse>;
+    /**
+     * Stream a completion.
+     * Note: Streaming is harder to track token-by-token, so we track start/end only.
+     */
+    stream(prompt: string, options?: LLMOptions): AsyncIterable<string>;
+    /**
+     * Chat with native tool calling support (optional).
+     * Proxies to underlying LLM if it supports chatWithTools.
+     */
+    chatWithTools(messages: LLMMessage[], options: LLMToolCallOptions): Promise<LLMToolCallResponse>;
+    private trackCacheOutcome;
+}
+
+/**
+ * @module @kb-labs/core-platform/wrappers/analytics-embeddings
+ * Analytics wrapper for IEmbeddings that tracks usage
+ */
+
+/**
+ * Analytics wrapper for embeddings adapter.
+ * Tracks all embedding operations to analytics.
+ */
+declare class AnalyticsEmbeddings implements IEmbeddings {
+    private realEmbeddings;
+    private analytics;
+    constructor(realEmbeddings: IEmbeddings, analytics: IAnalytics);
+    get dimensions(): number;
+    getDimensions(): Promise<number>;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+
+/**
+ * @module @kb-labs/core-platform/wrappers/analytics-vector-store
+ * Analytics wrapper for IVectorStore that tracks usage
+ */
+
+/**
+ * Analytics wrapper for vector store adapter.
+ * Tracks all vector operations to analytics.
+ */
+declare class AnalyticsVectorStore implements IVectorStore {
+    private realVectorStore;
+    private analytics;
+    constructor(realVectorStore: IVectorStore, analytics: IAnalytics);
+    search(query: number[], limit: number, filter?: VectorFilter): Promise<VectorSearchResult[]>;
+    upsert(vectors: VectorRecord[]): Promise<void>;
+    delete(ids: string[]): Promise<void>;
+    count(): Promise<number>;
+    get(ids: string[]): Promise<VectorRecord[]>;
+    query(filter: VectorFilter): Promise<VectorRecord[]>;
+}
+
+/**
+ * @module @kb-labs/core-platform/wrappers/analytics-cache
+ * Analytics wrapper for ICache that tracks usage
+ */
+
+/**
+ * Analytics wrapper for cache adapter.
+ * Tracks all cache operations including hit/miss rates.
+ */
+declare class AnalyticsCache implements ICache {
+    private realCache;
+    private analytics;
+    constructor(realCache: ICache, analytics: IAnalytics);
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    zadd(key: string, score: number, member: string): Promise<void>;
+    zrangebyscore(key: string, min: number, max: number): Promise<string[]>;
+    zrem(key: string, member: string): Promise<void>;
+    setIfNotExists<T>(key: string, value: T, ttl?: number): Promise<boolean>;
+}
+
+/**
+ * @module @kb-labs/core-platform/wrappers/analytics-storage
+ * Analytics wrapper for IStorage that tracks usage
+ */
+
+/**
+ * Analytics wrapper for storage adapter.
+ * Tracks all file operations including read/write bandwidth.
+ */
+declare class AnalyticsStorage implements IStorage {
+    private realStorage;
+    private analytics;
+    constructor(realStorage: IStorage, analytics: IAnalytics);
+    read(path: string): Promise<Buffer | null>;
+    write(path: string, data: Buffer): Promise<void>;
+    delete(path: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+}
+
+/**
+ * @module @kb-labs/core-platform/wrappers/scoped-analytics
+ * Analytics wrapper that overrides source attribution for plugin execution
+ *
+ * Problem: All analytics events show source from root package.json (@kb-labs/ai-review)
+ * Solution: Use IAnalytics.setSource() to override source.product with actual plugin ID
+ *
+ * Used by: core-sandbox/handler-executor to inject plugin-specific source
+ */
+
+/**
+ * ScopedAnalytics - wraps IAnalytics to override source attribution
+ *
+ * This wrapper uses the new setSource() method to modify the analytics
+ * adapter's source before delegating all calls.
+ *
+ * Design:
+ * - Calls setSource() on underlying adapter if available (FileAnalytics, future HTTP adapters)
+ * - For adapters without setSource() (NoOpAnalytics), just delegates (no-op is fine)
+ * - Transparently delegates all IAnalytics methods
+ * - Safe to nest with other wrappers (AnalyticsEmbeddings, QueuedEmbeddings)
+ *
+ * Usage:
+ * ```typescript
+ * const scoped = new ScopedAnalytics(platform.analytics, {
+ *   product: '@kb-labs/mind',
+ *   version: '0.1.0'
+ * });
+ *
+ * await scoped.track('mind.rag-index.started', { scope: 'default' });
+ * // Event will have source.product = '@kb-labs/mind' instead of root package
+ * ```
+ */
+declare class ScopedAnalytics implements IAnalytics {
+    private readonly realAnalytics;
+    private readonly scopedSource;
+    constructor(realAnalytics: IAnalytics, scopedSource: {
+        product: string;
+        version: string;
+    });
+    track(event: string, properties?: Record<string, unknown>): Promise<void>;
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    flush(): Promise<void>;
+    getEvents(query?: EventsQuery): Promise<EventsResponse>;
+    getStats(): Promise<EventsStats>;
+    getBufferStatus(): Promise<BufferStatus | null>;
+    getDlqStatus(): Promise<DlqStatus | null>;
+    /**
+     * Get current source from underlying adapter
+     */
+    getSource(): {
+        product: string;
+        version: string;
+    } | undefined;
+    /**
+     * Delegate setSource to underlying adapter
+     */
+    setSource(source: {
+        product: string;
+        version: string;
+    }): void;
+    /**
+     * Get the scoped source (for testing/debugging)
+     */
+    getScopedSource(): {
+        product: string;
+        version: string;
+    };
+    /**
+     * Get the underlying analytics adapter (for introspection)
+     */
+    getUnderlyingAdapter(): IAnalytics;
+}
+/**
+ * Create scoped analytics wrapper
+ *
+ * @param analytics - Original analytics adapter
+ * @param scopedSource - Override source (plugin ID and version)
+ * @returns Scoped analytics wrapper
+ */
+declare function createScopedAnalytics(analytics: IAnalytics, scopedSource: {
+    product: string;
+    version: string;
+}): ScopedAnalytics;
+/**
+ * Check if adapter is already scoped
+ */
+declare function isScopedAnalytics(analytics: IAnalytics): analytics is ScopedAnalytics;
+/**
+ * Unwrap scoped analytics to get original adapter
+ */
+declare function unwrapScopedAnalytics(analytics: IAnalytics): IAnalytics;
+
+/**
+ * @module @kb-labs/core-platform/logging/prefixed-logger
+ *
+ * Prefixed logger wrapper that prevents plugins from overriding system observability fields.
+ *
+ * ## Problem
+ *
+ * When plugins call `ctx.platform.logger.child({ reqId: 'custom' })`, they can accidentally
+ * override system observability fields like `reqId`, `traceId`, `tenantId`, etc.
+ *
+ * ## Solution
+ *
+ * This wrapper automatically renames conflicting fields by adding a `plugin_` prefix:
+ * - `reqId` → `plugin_reqId`
+ * - `traceId` → `plugin_traceId`
+ * - etc.
+ *
+ * Non-conflicting fields pass through unchanged.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * const baseLogger = platform.logger.child({ reqId: 'req-123', traceId: 'trace-456' });
+ * const prefixed = createPrefixedLogger(baseLogger);
+ *
+ * // Plugin tries to override system fields
+ * const pluginLogger = prefixed.child({ reqId: 'custom', userId: '789' });
+ * pluginLogger.info('test');
+ *
+ * // Result:
+ * {
+ *   reqId: 'req-123',           // ← System field preserved
+ *   plugin_reqId: 'custom',     // ← Plugin field renamed
+ *   userId: '789',              // ← Non-conflicting field unchanged
+ *   msg: 'test'
+ * }
+ * ```
+ */
+
+/**
+ * System observability fields that should not be overridden by plugins.
+ *
+ * These fields are set by the platform based on hostContext and should remain
+ * immutable throughout the plugin execution lifecycle.
+ */
+declare const SYSTEM_LOG_FIELDS: Set<string>;
+/**
+ * Create a prefixed logger that renames conflicting fields.
+ *
+ * @param baseLogger - Base logger instance
+ * @param options - Configuration options
+ * @returns Wrapped logger with field prefixing
+ *
+ * @example
+ * ```typescript
+ * const enrichedLogger = platform.logger.child({ reqId: 'req-123' });
+ * const prefixed = createPrefixedLogger(enrichedLogger);
+ *
+ * // Plugins can't override system fields
+ * const userLogger = prefixed.child({ reqId: 'custom', foo: 'bar' });
+ * // → { reqId: 'req-123', plugin_reqId: 'custom', foo: 'bar' }
+ * ```
+ */
+declare function createPrefixedLogger(baseLogger: ILogger, options?: {
+    /** Prefix for renamed fields (default: 'plugin_') */
+    prefix?: string;
+    /** Warn in development when renaming fields (default: true) */
+    warnOnRename?: boolean;
+    /** Custom set of protected fields (default: SYSTEM_LOG_FIELDS) */
+    protectedFields?: Set<string>;
+}): ILogger;
+
+/**
+ * @module @kb-labs/core-platform/learning/history-store
+ * Abstraction for storing and querying query history.
+ */
+interface HistoryRecord {
+    id: string;
+    query: string;
+    queryHash: string;
+    scopeId: string;
+    timestamp: number;
+    topChunkIds: string[];
+    resultChunkIds: string[];
+    reasoningPlan?: unknown;
+    queryVector?: number[];
+    metadata?: Record<string, unknown>;
+}
+interface HistoryFindOptions {
+    scopeId: string;
+    queryHash?: string;
+    queryVector?: number[];
+    limit?: number;
+}
+/**
+ * History store interface.
+ * Implementations: memory, file-based (platform storage), optional vector-backed.
+ */
+interface IHistoryStore {
+    save(record: HistoryRecord): Promise<void>;
+    find(options: HistoryFindOptions): Promise<HistoryRecord[]>;
+    popular(scopeId: string, limit?: number): Promise<Array<{
+        query: string;
+        count: number;
+    }>>;
+    saveReasoningPlan?(record: HistoryRecord): Promise<void>;
+}
+
+/**
+ * @module @kb-labs/core-platform/learning/feedback-store
+ * Abstraction for storing user feedback on answers.
+ */
+type FeedbackType = 'explicit' | 'implicit' | 'self';
+interface FeedbackRecord {
+    id: string;
+    queryId: string;
+    chunkId: string;
+    scopeId: string;
+    type: FeedbackType;
+    score: number;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Feedback store interface.
+ * Implementations: memory, file-based (platform storage).
+ */
+interface IFeedbackStore {
+    save(record: FeedbackRecord): Promise<void>;
+    list(scopeId: string, limit?: number): Promise<FeedbackRecord[]>;
+}
+
+/**
+ * In-memory history store with basic similarity search.
+ * Intended as a fallback when persistent storage is not configured.
+ */
+declare class MemoryHistoryStore implements IHistoryStore {
+    private readonly entries;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    save(record: HistoryRecord): Promise<void>;
+    find(options: HistoryFindOptions): Promise<HistoryRecord[]>;
+    popular(scopeId: string, limit?: number): Promise<Array<{
+        query: string;
+        count: number;
+    }>>;
+    saveReasoningPlan(record: HistoryRecord): Promise<void>;
+    private cosineSimilarity;
+}
+
+/**
+ * In-memory feedback store. Simple FIFO with optional cap.
+ */
+declare class MemoryFeedbackStore implements IFeedbackStore {
+    private readonly entries;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    save(record: FeedbackRecord): Promise<void>;
+    list(scopeId: string, limit?: number): Promise<FeedbackRecord[]>;
+}
+
+interface FileHistoryStoreOptions {
+    basePath?: string;
+    filePrefix?: string;
+    maxRecordsPerFile?: number;
+    maxFiles?: number;
+}
+/**
+ * File-based history store using platform.storage (JSONL segments with basic rotation).
+ */
+declare class FileHistoryStore implements IHistoryStore {
+    private readonly storage;
+    private readonly basePath;
+    private readonly filePrefix;
+    private readonly maxRecordsPerFile;
+    private readonly maxFiles;
+    constructor(storage: IStorage, options?: FileHistoryStoreOptions);
+    save(record: HistoryRecord): Promise<void>;
+    find(options: HistoryFindOptions): Promise<HistoryRecord[]>;
+    popular(scopeId: string, limit?: number): Promise<Array<{
+        query: string;
+        count: number;
+    }>>;
+    saveReasoningPlan(record: HistoryRecord): Promise<void>;
+    private getWritableFile;
+    private getFilesSorted;
+    private segmentPath;
+    private enforceRotation;
+    private ensureTrailingSlash;
+    private cosineSimilarity;
+}
+
+interface FileFeedbackStoreOptions {
+    basePath?: string;
+    filePrefix?: string;
+    maxRecordsPerFile?: number;
+    maxFiles?: number;
+}
+/**
+ * File-based feedback store using platform.storage (JSONL segments with basic rotation).
+ */
+declare class FileFeedbackStore implements IFeedbackStore {
+    private readonly storage;
+    private readonly basePath;
+    private readonly filePrefix;
+    private readonly maxRecordsPerFile;
+    private readonly maxFiles;
+    constructor(storage: IStorage, options?: FileFeedbackStoreOptions);
+    save(record: FeedbackRecord): Promise<void>;
+    list(scopeId: string, limit?: number): Promise<FeedbackRecord[]>;
+    private getWritableFile;
+    private getFilesSorted;
+    private segmentPath;
+    private enforceRotation;
+    private ensureTrailingSlash;
+}
+
+/**
+ * @module @kb-labs/core-platform/runs/run-types
+ * Full-cycle run state model and event schema.
+ */
+/**
+ * Top-level full-cycle run status.
+ */
+type RunStatus = "queued" | "provisioning" | "executing" | "gating" | "human_review" | "finalizing" | "completed" | "failed" | "failed_by_review" | "cancelled";
+/**
+ * Run step status.
+ */
+type RunStepStatus = "pending" | "in_progress" | "retrying" | "skipped" | "completed" | "failed" | "cancelled";
+/**
+ * Run step definition.
+ */
+interface RunStepDefinition {
+    id: string;
+    name: string;
+    plugin?: string;
+    action?: string;
+    timeoutMs?: number;
+    retryLimit?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run creation request.
+ */
+interface CreateRunRequest {
+    taskRef: string;
+    templateId: string;
+    actorId?: string;
+    tenantId?: string;
+    priority?: "low" | "medium" | "high" | "critical";
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run record.
+ */
+interface RunRecord {
+    runId: string;
+    status: RunStatus;
+    taskRef: string;
+    templateId: string;
+    actorId?: string;
+    tenantId?: string;
+    environmentId?: string;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run step record.
+ */
+interface RunStepRecord {
+    runId: string;
+    stepId: string;
+    status: RunStepStatus;
+    attempt: number;
+    startedAt?: string;
+    completedAt?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run event type.
+ */
+type RunEventType = "run.created" | "run.status.changed" | "run.failed" | "run.completed" | "run.cancelled" | "run.review.approved" | "run.review.rejected" | "step.started" | "step.completed" | "step.failed" | "environment.provisioning" | "environment.ready" | "environment.destroyed";
+/**
+ * Timeline event for run auditability.
+ */
+interface RunEvent {
+    eventId: string;
+    runId: string;
+    type: RunEventType;
+    at: string;
+    fromStatus?: RunStatus;
+    toStatus?: RunStatus;
+    stepId?: string;
+    environmentId?: string;
+    reason?: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * Terminal run statuses.
+ */
+declare const TERMINAL_RUN_STATUSES: ReadonlySet<RunStatus>;
+
+/**
+ * @module @kb-labs/core-platform/platform-adapters
+ * Unified interface for all platform adapters.
+ * Used by IPC servers to access adapters for proxying.
+ */
+
+/**
+ * Platform adapters container interface.
+ * Provides access to all platform adapters for IPC proxying.
+ *
+ * This interface is implemented by PlatformContainer in core-runtime.
+ * IPC servers in core-ipc use this interface to access adapters.
+ */
+interface IPlatformAdapters {
+    /** Logger adapter */
+    readonly logger: ILogger;
+    /** Analytics adapter (telemetry, events) */
+    readonly analytics: IAnalytics;
+    /** Vector store adapter (Qdrant, Pinecone, etc.) */
+    readonly vectorStore: IVectorStore;
+    /** LLM adapter (OpenAI, Anthropic, etc.) */
+    readonly llm: ILLM;
+    /** Embeddings adapter (OpenAI, Cohere, etc.) */
+    readonly embeddings: IEmbeddings;
+    /** Cache adapter (Redis, in-memory, etc.) */
+    readonly cache: ICache;
+    /** Config adapter (file, env, remote, etc.) */
+    readonly config: IConfig;
+    /** Storage adapter (S3, filesystem, etc.) */
+    readonly storage: IStorage;
+    /** Event bus adapter (in-memory, Redis, etc.) */
+    readonly eventBus: IEventBus;
+    /** Invoke adapter (cross-plugin invocation) */
+    readonly invoke: IInvoke;
+    /** Artifacts adapter (build outputs, generated files) */
+    readonly artifacts: IArtifacts;
+}
+
+export { AnalyticsCache, AnalyticsEmbeddings, AnalyticsLLM, AnalyticsStorage, AnalyticsVectorStore, type CreateRunRequest, type FeedbackRecord, type FeedbackType, FileFeedbackStore, type FileFeedbackStoreOptions, FileHistoryStore, type FileHistoryStoreOptions, type HistoryFindOptions, type HistoryRecord, IAnalytics, IArtifacts, ICache, IConfig, IEmbeddings, IEventBus, type IFeedbackStore, type IHistoryStore, IInvoke, ILLM, ILogger, type IPlatformAdapters, IStorage, IVectorStore, LLMMessage, LLMOptions, LLMProtocolCapabilities, LLMResponse, LLMToolCallOptions, LLMToolCallResponse, MemoryFeedbackStore, MemoryHistoryStore, type RunEvent, type RunEventType, type RunRecord, type RunStatus, type RunStepDefinition, type RunStepRecord, type RunStepStatus, SYSTEM_LOG_FIELDS, ScopedAnalytics, TERMINAL_RUN_STATUSES, VectorFilter, VectorRecord, VectorSearchResult, createPrefixedLogger, createScopedAnalytics, isScopedAnalytics, unwrapScopedAnalytics };