@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/helpers/use-llm.ts

@@ -0,0 +1,316 @@
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-llm
+ * Global LLM access helper with tier-based model selection.
+ *
+ * Provides clean access to LLM with adaptive tier routing.
+ * Plugins specify tiers (small/medium/large), platform resolves to actual models.
+ *
+ * @example
+ * ```typescript
+ * import { useLLM } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   // Simple usage (uses configured default tier)
+ *   const llm = useLLM();
+ *
+ *   // Request specific tier (platform adapts if needed)
+ *   const llm = useLLM({ tier: 'small' });   // Simple tasks
+ *   const llm = useLLM({ tier: 'large' });   // Complex tasks
+ *
+ *   // Request capabilities
+ *   const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });
+ *
+ *   if (llm) {
+ *     const result = await llm.complete('Explain this code');
+ *     console.log(result.content);
+ *   }
+ * }
+ * ```
+ */
+
+import { usePlatform } from './use-platform.js';
+import type {
+  ILLM,
+  LLMTier,
+  LLMOptions,
+  LLMResponse,
+  LLMMessage,
+  LLMToolCallOptions,
+  LLMToolCallResponse,
+  UseLLMOptions,
+  ILLMRouter,
+  LLMAdapterBinding,
+  LLMExecutionPolicy,
+  LLMProtocolCapabilities,
+  LLMCacheDecisionTrace,
+} from '@kb-labs/core-platform';
+
+/**
+ * Access global LLM adapter with tier-based selection.
+ *
+ * Platform automatically adapts to available models:
+ * - If plugin requests 'small' but 'medium' configured → uses 'medium' (escalation)
+ * - If plugin requests 'large' but 'medium' configured → uses 'medium' with warning (degradation)
+ *
+ * **Tiers are user-defined slots:**
+ * - `small`  - Plugin says: "This task is simple"
+ * - `medium` - Plugin says: "Standard task"
+ * - `large`  - Plugin says: "Complex task, need maximum quality"
+ *
+ * User decides what model maps to each tier in their config.
+ *
+ * @param options - Optional tier and capability requirements
+ * @returns LLM adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (uses configured default)
+ * const llm = useLLM();
+ *
+ * // Request specific tier
+ * const llm = useLLM({ tier: 'small' });   // Simple tasks
+ * const llm = useLLM({ tier: 'large' });   // Complex tasks
+ *
+ * // Request capabilities
+ * const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });
+ * const llm = useLLM({ capabilities: ['vision'] });
+ *
+ * if (llm) {
+ *   const result = await llm.complete('Generate commit message');
+ *   console.log(result.content);
+ * }
+ * ```
+ */
+export function useLLM(options?: UseLLMOptions): ILLM | undefined {
+  const platform = usePlatform();
+  const llm = platform.llm;
+
+  if (!llm) {
+    return undefined;
+  }
+
+  // If router and options given → return immutable LazyBoundLLM (no state mutation)
+  if (options && isLLMRouter(llm)) {
+    return new LazyBoundLLM(llm, options);
+  }
+
+  return llm;
+}
+
+/**
+ * Lazy adapter binding that resolves tier on first use.
+ * Immutable — does NOT mutate the global LLMRouter state.
+ * This fixes the race condition where useLLM({ tier: 'large' }) was immediately
+ * overwritten by useLLM({ tier: 'small' }) from SmartSummarizer.
+ */
+class LazyBoundLLM implements ILLM {
+  private _resolved: Promise<LLMAdapterBinding> | null = null;
+
+  constructor(
+    private readonly router: ILLM & ILLMRouter,
+    private readonly options: UseLLMOptions,
+  ) {}
+
+  private resolve(): Promise<LLMAdapterBinding> {
+    if (!this._resolved) {
+      this._resolved = this.router.resolveAdapter(this.options);
+    }
+    return this._resolved;
+  }
+
+  private mergeExecutionPolicy(callOptions?: LLMOptions): LLMExecutionPolicy | undefined {
+    const globalPolicy = this.options.execution;
+    const localPolicy = callOptions?.execution;
+    if (!globalPolicy && !localPolicy) {
+      return undefined;
+    }
+    return {
+      ...globalPolicy,
+      ...localPolicy,
+      cache: { ...globalPolicy?.cache, ...localPolicy?.cache },
+      stream: { ...globalPolicy?.stream, ...localPolicy?.stream },
+    };
+  }
+
+  private async resolveProtocolCapabilities(adapter: ILLM): Promise<LLMProtocolCapabilities> {
+    if (!adapter.getProtocolCapabilities) {
+      return {
+        cache: { supported: false },
+        stream: { supported: true },
+      };
+    }
+    return adapter.getProtocolCapabilities();
+  }
+
+  private enforceCachePolicy(caps: LLMProtocolCapabilities, execution?: LLMExecutionPolicy): void {
+    if (execution?.cache?.mode === 'require' && !caps.cache.supported) {
+      throw new Error('CACHE_NOT_SUPPORTED: adapter does not support required cache policy');
+    }
+  }
+
+  private buildDecisionTrace(
+    caps: LLMProtocolCapabilities,
+    execution: LLMExecutionPolicy | undefined,
+    streamAppliedMode: 'prefer' | 'require' | 'off',
+    streamFallback?: 'complete',
+    reason?: string,
+  ): LLMCacheDecisionTrace {
+    const requestedCacheMode = execution?.cache?.mode ?? 'prefer';
+    const requestedStreamMode = execution?.stream?.mode ?? 'prefer';
+
+    return {
+      cacheRequestedMode: requestedCacheMode,
+      cacheSupported: caps.cache.supported,
+      cacheAppliedMode:
+        requestedCacheMode === 'require' || requestedCacheMode === 'bypass'
+          ? requestedCacheMode
+          : caps.cache.supported
+            ? 'prefer'
+            : 'bypass',
+      streamRequestedMode: requestedStreamMode,
+      streamSupported: caps.stream.supported,
+      streamAppliedMode,
+      streamFallback,
+      reason,
+    };
+  }
+
+  private withDecisionMetadata(
+    options: LLMOptions | undefined,
+    trace: LLMCacheDecisionTrace,
+  ): LLMOptions | undefined {
+    if (!options) {
+      return { metadata: { cacheDecisionTrace: trace } };
+    }
+
+    return {
+      ...options,
+      metadata: {
+        ...options.metadata,
+        cacheDecisionTrace: trace,
+      },
+    };
+  }
+
+  async complete(prompt: string, options?: LLMOptions): Promise<LLMResponse> {
+    const { adapter, model } = await this.resolve();
+    const execution = this.mergeExecutionPolicy(options);
+    const caps = await this.resolveProtocolCapabilities(adapter);
+    this.enforceCachePolicy(caps, execution);
+    const trace = this.buildDecisionTrace(caps, execution, 'off');
+    const optionsWithTrace = this.withDecisionMetadata(options, trace);
+    return adapter.complete(prompt, { ...optionsWithTrace, model, execution });
+  }
+
+  async *stream(prompt: string, options?: LLMOptions): AsyncIterable<string> {
+    const { adapter, model } = await this.resolve();
+    const execution = this.mergeExecutionPolicy(options);
+    const caps = await this.resolveProtocolCapabilities(adapter);
+    this.enforceCachePolicy(caps, execution);
+
+    const streamMode = execution?.stream?.mode ?? 'prefer';
+    const canStream = caps.stream.supported;
+    const allowFallback = execution?.stream?.fallbackToComplete ?? true;
+
+    if (streamMode === 'off' || (!canStream && streamMode === 'prefer' && allowFallback)) {
+      const fallbackReason =
+        streamMode === 'off'
+          ? 'STREAM_OFF'
+          : 'STREAM_UNSUPPORTED_FALLBACK_TO_COMPLETE';
+      const trace = this.buildDecisionTrace(caps, execution, 'off', 'complete', fallbackReason);
+      const optionsWithTrace = this.withDecisionMetadata(options, trace);
+      const response = await adapter.complete(prompt, { ...optionsWithTrace, model, execution });
+      if (response.content) {
+        yield response.content;
+      }
+      return;
+    }
+
+    if (!canStream && streamMode === 'require') {
+      throw new Error('STREAM_NOT_SUPPORTED: adapter does not support required streaming');
+    }
+
+    const trace = this.buildDecisionTrace(caps, execution, streamMode);
+    const optionsWithTrace = this.withDecisionMetadata(options, trace);
+    yield* adapter.stream(prompt, { ...optionsWithTrace, model, execution });
+  }
+
+  async chatWithTools(
+    messages: LLMMessage[],
+    options: LLMToolCallOptions,
+  ): Promise<LLMToolCallResponse> {
+    const { adapter, model, tier } = await this.resolve();
+    const execution = this.mergeExecutionPolicy(options);
+    const caps = await this.resolveProtocolCapabilities(adapter);
+    this.enforceCachePolicy(caps, execution);
+    if (!adapter.chatWithTools) {
+      throw new Error('Current adapter does not support chatWithTools');
+    }
+    const trace = this.buildDecisionTrace(caps, execution, 'off');
+    const optionsWithTrace = this.withDecisionMetadata(options, trace) as LLMToolCallOptions;
+    return adapter.chatWithTools(messages, {
+      ...optionsWithTrace,
+      model,
+      execution,
+      metadata: { ...optionsWithTrace.metadata, tier },
+    });
+  }
+}
+
+/**
+ * Check if LLM is available.
+ *
+ * Useful for conditional logic (LLM-powered vs deterministic fallback).
+ *
+ * @returns true if LLM is configured and ready
+ *
+ * @example
+ * ```typescript
+ * if (isLLMAvailable()) {
+ *   const summary = await generateWithLLM(data);
+ * } else {
+ *   const summary = generateDeterministic(data);
+ * }
+ * ```
+ */
+export function isLLMAvailable(): boolean {
+  const llm = useLLM();
+  return !!llm;
+}
+
+/**
+ * Get configured LLM tier.
+ *
+ * Useful for diagnostics and logging.
+ *
+ * @returns Configured tier or undefined if LLM not available/not a router
+ *
+ * @example
+ * ```typescript
+ * const tier = getLLMTier();
+ * console.log(`Using LLM tier: ${tier ?? 'default'}`);
+ * ```
+ */
+export function getLLMTier(): LLMTier | undefined {
+  const platform = usePlatform();
+  const llm = platform.llm;
+
+  if (llm && isLLMRouter(llm)) {
+    return llm.getConfiguredTier();
+  }
+
+  return undefined;
+}
+
+/**
+ * Type guard for ILLMRouter.
+ */
+function isLLMRouter(llm: ILLM): llm is ILLM & ILLMRouter {
+  return (
+    typeof (llm as unknown as ILLMRouter).getConfiguredTier === 'function' &&
+    typeof (llm as unknown as ILLMRouter).resolve === 'function'
+  );
+}
+
+// Re-export types for convenience
+export type { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';

package/packages/shared-command-kit/src/helpers/use-logger.ts

@@ -0,0 +1,77 @@
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-logger
+ * Global logger access helper
+ *
+ * Provides clean access to structured logging without context drilling.
+ *
+ * @example
+ * ```typescript
+ * import { useLogger } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const logger = useLogger();
+ *
+ *   await logger.info('Processing started');
+ *   await logger.debug('Details', { userId: 123 });
+ *   await logger.error('Failed', { error: err });
+ * }
+ * ```
+ */
+
+import { usePlatform } from './use-platform';
+import type { ILogger } from '@kb-labs/core-platform';
+
+/**
+ * Access global logger
+ *
+ * Returns the platform logger with structured logging capabilities.
+ * Supports child loggers with additional context.
+ *
+ * **Methods:**
+ * - `logger.trace(message, meta?)` - Trace-level logs (most verbose)
+ * - `logger.debug(message, meta?)` - Debug-level logs
+ * - `logger.info(message, meta?)` - Info-level logs
+ * - `logger.warn(message, meta?)` - Warning-level logs
+ * - `logger.error(message, meta?)` - Error-level logs
+ * - `logger.child(meta)` - Create child logger with additional context
+ *
+ * @returns Platform logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = useLogger();
+ *
+ * await logger.info('Task started', { taskId: '123' });
+ * await logger.error('Task failed', { taskId: '123', error: err.message });
+ *
+ * // Child logger with persistent context
+ * const taskLogger = logger.child({ taskId: '123', userId: 'user-1' });
+ * await taskLogger.info('Step 1 completed');
+ * await taskLogger.info('Step 2 completed');
+ * ```
+ */
+export function useLogger(): ILogger {
+  const platform = usePlatform();
+  return platform.logger;
+}
+
+/**
+ * Create child logger with additional context
+ *
+ * Useful for scoped logging within a specific operation.
+ *
+ * @param context - Additional context to attach to all log entries
+ * @returns Child logger with persistent context
+ *
+ * @example
+ * ```typescript
+ * const logger = useLoggerWithContext({ operation: 'release', version: '1.0.0' });
+ *
+ * await logger.info('Started');  // Automatically includes operation + version
+ * await logger.info('Completed');
+ * ```
+ */
+export function useLoggerWithContext(context: Record<string, unknown>): ILogger {
+  const logger = useLogger();
+  return logger.child(context);
+}

package/packages/shared-command-kit/src/helpers/use-platform.ts

@@ -0,0 +1,111 @@
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-platform
+ * Global platform singleton access helper
+ *
+ * Provides clean access to platform services without context drilling.
+ * Similar to React hooks pattern, but for KB Labs platform.
+ *
+ * @example
+ * ```typescript
+ * import { usePlatform } from '@kb-labs/shared-command-kit';
+ *
+ * // In any command handler
+ * async handler(ctx, argv, flags) {
+ *   const platform = usePlatform();
+ *
+ *   if (platform.llm) {
+ *     const result = await platform.llm.complete('prompt');
+ *   }
+ *
+ *   await platform.logger.info('Task completed');
+ * }
+ * ```
+ */
+
+import { platform as globalPlatform } from '@kb-labs/core-runtime';
+
+/**
+ * Access global platform singleton
+ *
+ * Returns the initialized platform object with all registered adapters.
+ * This is the single source of truth for platform services.
+ *
+ * **What's available:**
+ * - `platform.llm` - LLM adapter (OpenAI, Anthropic, etc.)
+ * - `platform.embeddings` - Embeddings adapter
+ * - `platform.vectorStore` - Vector storage (Qdrant, local, etc.)
+ * - `platform.storage` - File/blob storage
+ * - `platform.cache` - Caching layer
+ * - `platform.analytics` - Analytics/telemetry
+ * - `platform.logger` - Structured logging
+ * - `platform.eventBus` - Event system
+ * - `platform.workflows` - Workflow engine
+ * - `platform.jobs` - Background jobs
+ * - `platform.cron` - Scheduled tasks
+ * - `platform.resources` - Resource management
+ * - `platform.invoke` - Plugin invocation
+ * - `platform.artifacts` - Build artifacts
+ *
+ * **Graceful degradation:**
+ * Always check if adapter is available before using:
+ * ```typescript
+ * const platform = usePlatform();
+ * if (platform.llm) {
+ *   // Use LLM
+ * } else {
+ *   // Fallback logic
+ * }
+ * ```
+ *
+ * **Multi-tenancy:**
+ * Currently returns global singleton (single-tenant).
+ * Future: Will support tenant-scoped platform via AsyncLocalStorage.
+ *
+ * @returns Global platform singleton
+ */
+export function usePlatform(): typeof globalPlatform {
+  return globalPlatform;
+}
+
+/**
+ * Check if specific platform adapter is configured
+ *
+ * Useful for conditional logic based on available services.
+ *
+ * @param adapterName - Name of the adapter to check
+ * @returns true if adapter is configured and available
+ *
+ * @example
+ * ```typescript
+ * if (isPlatformConfigured('llm')) {
+ *   // Use LLM-powered feature
+ * } else {
+ *   // Use deterministic fallback
+ * }
+ * ```
+ */
+export function isPlatformConfigured(adapterName: keyof typeof globalPlatform): boolean {
+  const platform = usePlatform();
+
+  // Check if adapter exists and is not a noop/fallback
+  const adapter = platform[adapterName];
+
+  if (!adapter) {
+    return false;
+  }
+
+  // For adapters with hasAdapter method (like platform itself)
+  if ('hasAdapter' in platform && typeof platform.hasAdapter === 'function') {
+    return platform.hasAdapter(adapterName as any);
+  }
+
+  // Fallback: check if adapter is not noop
+  // Noop adapters usually have a specific constructor name or are simple objects
+  if (typeof adapter === 'object' && adapter.constructor) {
+    const constructorName = adapter.constructor.name;
+    return !constructorName.toLowerCase().includes('noop') &&
+           !constructorName.toLowerCase().includes('fallback');
+  }
+
+  return true;
+}

package/packages/shared-command-kit/src/helpers/use-resource-broker.ts

@@ -0,0 +1,106 @@
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-resource-broker
+ * Global ResourceBroker access helper
+ *
+ * Provides clean access to ResourceBroker for queue and rate limiting.
+ *
+ * @example
+ * ```typescript
+ * import { useResourceBroker } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const broker = useResourceBroker();
+ *
+ *   // Get statistics
+ *   const stats = broker.getStats();
+ *   console.log(`Queue size: ${stats.queueSize}`);
+ * }
+ * ```
+ */
+
+import { usePlatform } from './use-platform.js';
+import type { IResourceBroker } from '@kb-labs/core-resource-broker';
+
+/**
+ * Access global ResourceBroker
+ *
+ * Returns the platform ResourceBroker for queue management, rate limiting,
+ * and retry logic for heavy operations (LLM, embeddings, vector store).
+ *
+ * **Features:**
+ * - Priority queue (high/normal/low)
+ * - Rate limiting with configurable backend
+ * - Automatic retry with exponential backoff
+ * - Per-resource statistics
+ *
+ * **Note:** Most plugins don't need this directly.
+ * Use `useLLM()`, `useEmbeddings()`, etc. which automatically
+ * route through the ResourceBroker.
+ *
+ * @returns ResourceBroker instance
+ * @throws Error if ResourceBroker not initialized
+ *
+ * @example
+ * ```typescript
+ * const broker = useResourceBroker();
+ *
+ * // Get queue statistics
+ * const stats = broker.getStats();
+ * console.log(`Total requests: ${stats.totalRequests}`);
+ * console.log(`Queue size: ${stats.queueSize}`);
+ *
+ * // Check if resource is registered
+ * if (broker.hasResource('llm')) {
+ *   console.log('LLM is available for queueing');
+ * }
+ * ```
+ */
+export function useResourceBroker(): IResourceBroker {
+  const platform = usePlatform();
+  return platform.resourceBroker;
+}
+
+/**
+ * Check if ResourceBroker is available
+ *
+ * Useful for conditional logic when ResourceBroker may not be initialized.
+ *
+ * @returns true if ResourceBroker is initialized and ready
+ *
+ * @example
+ * ```typescript
+ * if (isResourceBrokerAvailable()) {
+ *   const broker = useResourceBroker();
+ *   const stats = broker.getStats();
+ * } else {
+ *   console.log('ResourceBroker not initialized');
+ * }
+ * ```
+ */
+export function isResourceBrokerAvailable(): boolean {
+  const platform = usePlatform();
+  return platform.hasResourceBroker;
+}
+
+/**
+ * Get ResourceBroker statistics
+ *
+ * Convenience helper to get statistics without handling the broker directly.
+ *
+ * @returns ResourceBroker statistics or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const stats = getResourceBrokerStats();
+ * if (stats) {
+ *   console.log(`LLM requests: ${stats.resources.llm?.totalRequests ?? 0}`);
+ *   console.log(`Queue size: ${stats.queueSize}`);
+ * }
+ * ```
+ */
+export function getResourceBrokerStats() {
+  if (!isResourceBrokerAvailable()) {
+    return undefined;
+  }
+  return useResourceBroker().getStats();
+}

package/packages/shared-command-kit/src/helpers/use-storage.ts

@@ -0,0 +1,71 @@
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-storage
+ * Global storage access helper
+ *
+ * Provides clean access to file/blob storage adapter.
+ *
+ * @example
+ * ```typescript
+ * import { useStorage } from '@kb-labs/shared-command-kit';
+ *
+ * async handler(ctx, argv, flags) {
+ *   const storage = useStorage();
+ *
+ *   if (storage) {
+ *     await storage.write('path/to/file.txt', 'content');
+ *     const content = await storage.read('path/to/file.txt');
+ *   }
+ * }
+ * ```
+ */
+
+import { usePlatform } from './use-platform';
+import type { IStorage } from '@kb-labs/core-platform';
+
+/**
+ * Access global storage adapter
+ *
+ * Returns the platform storage adapter for file/blob operations.
+ * Returns undefined if storage is not configured (graceful degradation).
+ *
+ * **Methods:**
+ * - `storage.read(path)` - Read file content
+ * - `storage.write(path, content)` - Write file content
+ * - `storage.exists(path)` - Check if file exists
+ * - `storage.delete(path)` - Delete file
+ * - `storage.list(prefix?)` - List files
+ *
+ * **Always check availability:**
+ * ```typescript
+ * const storage = useStorage();
+ * if (storage) {
+ *   await storage.write('file.txt', 'content');
+ * }
+ * ```
+ *
+ * @returns Storage adapter or undefined if not configured
+ *
+ * @example
+ * ```typescript
+ * const storage = useStorage();
+ *
+ * if (storage) {
+ *   // Write file
+ *   await storage.write('releases/v1.0.0.json', JSON.stringify(data));
+ *
+ *   // Read file
+ *   const content = await storage.read('releases/v1.0.0.json');
+ *   const data = JSON.parse(content);
+ *
+ *   // Check existence
+ *   const exists = await storage.exists('releases/v1.0.0.json');
+ *
+ *   // List files
+ *   const files = await storage.list('releases/');
+ * }
+ * ```
+ */
+export function useStorage(): IStorage | undefined {
+  const platform = usePlatform();
+  return platform.storage;
+}