@kb-labs/shared-command-kit 2.15.0 → 2.17.0

package/dist/helpers/index.d.ts

@@ -613,4 +613,30 @@ declare function useCache(): ICache | undefined;
  */
 declare function isCacheAvailable(): boolean;
 
-export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore };
+/**
+ * @module @kb-labs/shared-command-kit/helpers/use-env
+ *
+ * Sandboxed environment variable access.
+ *
+ * Reads from runtimeContext (AsyncLocalStorage) when running inside
+ * a governed handler execution (worker-pool, subprocess).
+ * Falls back to process.env when no runtime context is set
+ * (direct CLI, tests, code outside handler).
+ *
+ * @example
+ * ```typescript
+ * import { useEnv } from '@kb-labs/sdk';
+ *
+ * const token = useEnv('NPM_TOKEN');
+ * const ci = useEnv('CI');
+ * ```
+ */
+/**
+ * Read an environment variable through the sandboxed runtime context.
+ *
+ * Inside a governed handler: reads through env-shim (permission-checked).
+ * Outside handler context: reads process.env directly (backward compat).
+ */
+declare function useEnv(key: string): string | undefined;
+
+export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useEnv, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore };

package/dist/helpers/index.js

@@ -1,4 +1,4 @@
-import { platformContext } from '@kb-labs/plugin-contracts';
+import { platformContext, runtimeContext } from '@kb-labs/plugin-contracts';
 import { platform } from '@kb-labs/core-runtime';
 
 var __defProp = Object.defineProperty;
@@ -271,7 +271,14 @@ function isCacheAvailable() {
   const cache = useCache();
   return !!cache;
 }
+function useEnv(key) {
+  const runtime = runtimeContext.getStore();
+  if (runtime?.env) {
+    return runtime.env(key);
+  }
+  return process.env[key];
+}
 
-export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore };
+export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useEnv, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/helpers/use-platform.ts","../../src/helpers/index.ts","../../src/helpers/use-config.ts","../../src/helpers/use-logger.ts","../../src/helpers/use-llm.ts","../../src/helpers/use-embeddings.ts","../../src/helpers/use-vector-store.ts","../../src/helpers/use-analytics.ts","../../src/helpers/use-storage.ts","../../src/helpers/use-cache.ts"],"names":["globalPlatform","usePlatform","trace","optionsWithTrace"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/helpers/use-platform\n * Platform access hook with execution-scoped context.\n *\n * Uses AsyncLocalStorage to return the correct platform for the current\n * handler execution (governed, with correct permissions and proxy adapters).\n * Falls back to global singleton for code running outside handler context.\n *\n * @example\n * ```typescript\n * import { usePlatform } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler — automatically gets the right platform\n * async handler(ctx, argv, flags) {\n *   const platform = usePlatform();\n *   const result = await platform.llm.complete('prompt');\n * }\n * ```\n */\n\nimport { platformContext } from '@kb-labs/plugin-contracts';\nimport { platform as globalPlatform } from '@kb-labs/core-runtime';\n\n/**\n * Access platform services for the current execution context.\n *\n * Priority:\n * 1. AsyncLocalStorage context (set by runInProcess) — per-execution, governed\n * 2. Global singleton fallback (core-runtime) — for code outside handler context\n *\n * @returns Platform services with correct adapters for current context\n */\nexport function usePlatform(): typeof globalPlatform {\n  return (platformContext.getStore() as typeof globalPlatform) ?? globalPlatform;\n}\n\n/**\n * Check if specific platform adapter is configured\n *\n * Useful for conditional logic based on available services.\n *\n * @param adapterName - Name of the adapter to check\n * @returns true if adapter is configured and available\n *\n * @example\n * ```typescript\n * if (isPlatformConfigured('llm')) {\n *   // Use LLM-powered feature\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isPlatformConfigured(adapterName: keyof typeof globalPlatform): boolean {\n  const platform = usePlatform();\n\n  // Check if adapter exists and is not a noop/fallback\n  const adapter = platform[adapterName];\n\n  if (!adapter) {\n    return false;\n  }\n\n  // For adapters with hasAdapter method (like platform itself)\n  if ('hasAdapter' in platform && typeof platform.hasAdapter === 'function') {\n    return platform.hasAdapter(adapterName as any);\n  }\n\n  // Fallback: check if adapter is not noop\n  // Noop adapters usually have a specific constructor name or are simple objects\n  if (typeof adapter === 'object' && adapter.constructor) {\n    const constructorName = adapter.constructor.name;\n    return !constructorName.toLowerCase().includes('noop') &&\n           !constructorName.toLowerCase().includes('fallback');\n  }\n\n  return true;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers\n * Global platform access helpers\n *\n * Provides clean, type-safe access to platform services without context drilling.\n * Similar to React hooks pattern, but for KB Labs platform.\n *\n * @example\n * ```typescript\n * import { useLLM, useLogger, useAnalytics } from '@kb-labs/shared-command-kit/helpers';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *   const llm = useLLM();\n *\n *   await logger.info('Processing started');\n *\n *   if (llm) {\n *     const result = await llm.complete('prompt');\n *     await logger.info('LLM result', { length: result.content.length });\n *   }\n * }\n * ```\n */\n\n// Platform singleton\nexport { usePlatform, isPlatformConfigured } from './use-platform';\n\n// Context types and helpers\nexport type { PluginContextV3 } from './context';\n\n// Config access\nexport { useConfig } from './use-config';\n\n// Core services\nexport { useLogger, useLoggerWithContext } from './use-logger.js';\nexport { useLLM, isLLMAvailable, getLLMTier, type LLMTier, type UseLLMOptions } from './use-llm.js';\nexport { useEmbeddings, isEmbeddingsAvailable } from './use-embeddings.js';\nexport { useVectorStore, isVectorStoreAvailable } from './use-vector-store.js';\nexport { useAnalytics, trackAnalyticsEvent } from './use-analytics.js';\nexport { useStorage } from './use-storage.js';\nexport { useCache, isCacheAvailable } from './use-cache.js';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-config\n * Global config access helper\n *\n * Provides clean access to product-specific configuration without context drilling.\n * Similar to React hooks pattern, but for KB Labs config.\n *\n * @example\n * ```typescript\n * import { useConfig } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler\n * async handler(ctx, argv, flags) {\n *   const config = await useConfig('mind');\n *\n *   if (config) {\n *     const scopes = config.scopes;\n *     // Use config...\n *   }\n * }\n * ```\n */\n\n/**\n * Access product-specific configuration from kb.config.json\n *\n * Returns ONLY the config for the specified product and profile.\n * Uses platform.config adapter (works across parent/child processes via IPC).\n * Supports both Profiles v2 and legacy config structures.\n *\n * **Security:** This function returns ONLY the product-specific config,\n * not the entire kb.config.json. This prevents cross-product config access.\n *\n * **Auto-detection:** If productId is not provided, it's automatically inferred\n * from the plugin's manifest.configSection field (passed via execution context).\n *\n * **Profiles v2 structure:**\n * ```json\n * {\n *   \"profiles\": [\n *     {\n *       \"id\": \"default\",\n *       \"products\": {\n *         \"mind\": { \"scopes\": [...] },\n *         \"workflow\": { \"maxConcurrency\": 10 }\n *       }\n *     }\n *   ]\n * }\n * ```\n *\n * **Legacy structure:**\n * ```json\n * {\n *   \"knowledge\": { \"scopes\": [...] },  // for \"mind\" product\n *   \"workflow\": { \"maxConcurrency\": 10 }\n * }\n * ```\n *\n * @param productId - Product identifier (e.g., 'mind', 'workflow', 'plugins'). Optional - auto-detected from context.\n * @param profileId - Profile identifier (defaults to 'default' or KB_PROFILE env var)\n * @returns Promise resolving to product-specific config or undefined\n *\n * @example\n * ```typescript\n * // Auto-detect from context (recommended)\n * const config = await useConfig();\n *\n * // Explicit product ID\n * const mindConfig = await useConfig('mind');\n * if (mindConfig?.scopes) {\n *   // Use scopes\n * }\n *\n * // With explicit profile\n * const workflowConfig = await useConfig('workflow', 'production');\n * ```\n */\nexport async function useConfig<T = any>(productId?: string, profileId?: string): Promise<T | undefined> {\n  // Auto-detect productId from manifest.configSection if not provided\n  let effectiveProductId = productId;\n  if (!effectiveProductId) {\n    effectiveProductId = (globalThis as any).__KB_CONFIG_SECTION__;\n  }\n\n  if (!effectiveProductId) {\n    return undefined;\n  }\n\n  const { usePlatform } = await import('./use-platform.js');\n  const platform = usePlatform();\n\n  if (!platform) {\n    return undefined;\n  }\n\n  // Returns ONLY the product-specific config, not the entire kb.config.json\n  return await platform.config.getConfig(effectiveProductId, profileId) as T | undefined;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-logger\n * Global logger access helper\n *\n * Provides clean access to structured logging without context drilling.\n *\n * @example\n * ```typescript\n * import { useLogger } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *\n *   await logger.info('Processing started');\n *   await logger.debug('Details', { userId: 123 });\n *   await logger.error('Failed', { error: err });\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { ILogger } from '@kb-labs/core-platform';\n\n/**\n * Access global logger\n *\n * Returns the platform logger with structured logging capabilities.\n * Supports child loggers with additional context.\n *\n * **Methods:**\n * - `logger.trace(message, meta?)` - Trace-level logs (most verbose)\n * - `logger.debug(message, meta?)` - Debug-level logs\n * - `logger.info(message, meta?)` - Info-level logs\n * - `logger.warn(message, meta?)` - Warning-level logs\n * - `logger.error(message, meta?)` - Error-level logs\n * - `logger.child(meta)` - Create child logger with additional context\n *\n * @returns Platform logger instance\n *\n * @example\n * ```typescript\n * const logger = useLogger();\n *\n * await logger.info('Task started', { taskId: '123' });\n * await logger.error('Task failed', { taskId: '123', error: err.message });\n *\n * // Child logger with persistent context\n * const taskLogger = logger.child({ taskId: '123', userId: 'user-1' });\n * await taskLogger.info('Step 1 completed');\n * await taskLogger.info('Step 2 completed');\n * ```\n */\nexport function useLogger(): ILogger {\n  const platform = usePlatform();\n  return platform.logger;\n}\n\n/**\n * Create child logger with additional context\n *\n * Useful for scoped logging within a specific operation.\n *\n * @param context - Additional context to attach to all log entries\n * @returns Child logger with persistent context\n *\n * @example\n * ```typescript\n * const logger = useLoggerWithContext({ operation: 'release', version: '1.0.0' });\n *\n * await logger.info('Started');  // Automatically includes operation + version\n * await logger.info('Completed');\n * ```\n */\nexport function useLoggerWithContext(context: Record<string, unknown>): ILogger {\n  const logger = useLogger();\n  return logger.child(context);\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-llm\n * Global LLM access helper with tier-based model selection.\n *\n * Provides clean access to LLM with adaptive tier routing.\n * Plugins specify tiers (small/medium/large), platform resolves to actual models.\n *\n * @example\n * ```typescript\n * import { useLLM } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   // Simple usage (uses configured default tier)\n *   const llm = useLLM();\n *\n *   // Request specific tier (platform adapts if needed)\n *   const llm = useLLM({ tier: 'small' });   // Simple tasks\n *   const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n *   // Request capabilities\n *   const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n *\n *   if (llm) {\n *     const result = await llm.complete('Explain this code');\n *     console.log(result.content);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type {\n  ILLM,\n  LLMTier,\n  LLMOptions,\n  LLMResponse,\n  LLMMessage,\n  LLMToolCallOptions,\n  LLMToolCallResponse,\n  UseLLMOptions,\n  ILLMRouter,\n  LLMAdapterBinding,\n  LLMExecutionPolicy,\n  LLMProtocolCapabilities,\n  LLMCacheDecisionTrace,\n} from '@kb-labs/core-platform';\n\n/**\n * Access global LLM adapter with tier-based selection.\n *\n * Platform automatically adapts to available models:\n * - If plugin requests 'small' but 'medium' configured → uses 'medium' (escalation)\n * - If plugin requests 'large' but 'medium' configured → uses 'medium' with warning (degradation)\n *\n * **Tiers are user-defined slots:**\n * - `small`  - Plugin says: \"This task is simple\"\n * - `medium` - Plugin says: \"Standard task\"\n * - `large`  - Plugin says: \"Complex task, need maximum quality\"\n *\n * User decides what model maps to each tier in their config.\n *\n * @param options - Optional tier and capability requirements\n * @returns LLM adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * // Simple usage (uses configured default)\n * const llm = useLLM();\n *\n * // Request specific tier\n * const llm = useLLM({ tier: 'small' });   // Simple tasks\n * const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n * // Request capabilities\n * const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n * const llm = useLLM({ capabilities: ['vision'] });\n *\n * if (llm) {\n *   const result = await llm.complete('Generate commit message');\n *   console.log(result.content);\n * }\n * ```\n */\nexport function useLLM(options?: UseLLMOptions): ILLM | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (!llm) {\n    return undefined;\n  }\n\n  // If router and options given → return immutable LazyBoundLLM (no state mutation)\n  if (options && isLLMRouter(llm)) {\n    return new LazyBoundLLM(llm, options);\n  }\n\n  return llm;\n}\n\n/**\n * Lazy adapter binding that resolves tier on first use.\n * Immutable — does NOT mutate the global LLMRouter state.\n * This fixes the race condition where useLLM({ tier: 'large' }) was immediately\n * overwritten by useLLM({ tier: 'small' }) from SmartSummarizer.\n */\nclass LazyBoundLLM implements ILLM {\n  private _resolved: Promise<LLMAdapterBinding> | null = null;\n\n  constructor(\n    private readonly router: ILLM & ILLMRouter,\n    private readonly options: UseLLMOptions,\n  ) {}\n\n  private resolve(): Promise<LLMAdapterBinding> {\n    if (!this._resolved) {\n      this._resolved = this.router.resolveAdapter(this.options);\n    }\n    return this._resolved;\n  }\n\n  private mergeExecutionPolicy(callOptions?: LLMOptions): LLMExecutionPolicy | undefined {\n    const globalPolicy = this.options.execution;\n    const localPolicy = callOptions?.execution;\n    if (!globalPolicy && !localPolicy) {\n      return undefined;\n    }\n    return {\n      ...globalPolicy,\n      ...localPolicy,\n      cache: { ...globalPolicy?.cache, ...localPolicy?.cache },\n      stream: { ...globalPolicy?.stream, ...localPolicy?.stream },\n    };\n  }\n\n  private async resolveProtocolCapabilities(adapter: ILLM): Promise<LLMProtocolCapabilities> {\n    if (!adapter.getProtocolCapabilities) {\n      return {\n        cache: { supported: false },\n        stream: { supported: true },\n      };\n    }\n    return adapter.getProtocolCapabilities();\n  }\n\n  private enforceCachePolicy(caps: LLMProtocolCapabilities, execution?: LLMExecutionPolicy): void {\n    if (execution?.cache?.mode === 'require' && !caps.cache.supported) {\n      throw new Error('CACHE_NOT_SUPPORTED: adapter does not support required cache policy');\n    }\n  }\n\n  private buildDecisionTrace(\n    caps: LLMProtocolCapabilities,\n    execution: LLMExecutionPolicy | undefined,\n    streamAppliedMode: 'prefer' | 'require' | 'off',\n    streamFallback?: 'complete',\n    reason?: string,\n  ): LLMCacheDecisionTrace {\n    const requestedCacheMode = execution?.cache?.mode ?? 'prefer';\n    const requestedStreamMode = execution?.stream?.mode ?? 'prefer';\n\n    return {\n      cacheRequestedMode: requestedCacheMode,\n      cacheSupported: caps.cache.supported,\n      cacheAppliedMode:\n        requestedCacheMode === 'require' || requestedCacheMode === 'bypass'\n          ? requestedCacheMode\n          : caps.cache.supported\n            ? 'prefer'\n            : 'bypass',\n      streamRequestedMode: requestedStreamMode,\n      streamSupported: caps.stream.supported,\n      streamAppliedMode,\n      streamFallback,\n      reason,\n    };\n  }\n\n  private withDecisionMetadata(\n    options: LLMOptions | undefined,\n    trace: LLMCacheDecisionTrace,\n  ): LLMOptions | undefined {\n    if (!options) {\n      return { metadata: { cacheDecisionTrace: trace } };\n    }\n\n    return {\n      ...options,\n      metadata: {\n        ...options.metadata,\n        cacheDecisionTrace: trace,\n      },\n    };\n  }\n\n  async complete(prompt: string, options?: LLMOptions): Promise<LLMResponse> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    return adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async *stream(prompt: string, options?: LLMOptions): AsyncIterable<string> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n\n    const streamMode = execution?.stream?.mode ?? 'prefer';\n    const canStream = caps.stream.supported;\n    const allowFallback = execution?.stream?.fallbackToComplete ?? true;\n\n    if (streamMode === 'off' || (!canStream && streamMode === 'prefer' && allowFallback)) {\n      const fallbackReason =\n        streamMode === 'off'\n          ? 'STREAM_OFF'\n          : 'STREAM_UNSUPPORTED_FALLBACK_TO_COMPLETE';\n      const trace = this.buildDecisionTrace(caps, execution, 'off', 'complete', fallbackReason);\n      const optionsWithTrace = this.withDecisionMetadata(options, trace);\n      const response = await adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n      if (response.content) {\n        yield response.content;\n      }\n      return;\n    }\n\n    if (!canStream && streamMode === 'require') {\n      throw new Error('STREAM_NOT_SUPPORTED: adapter does not support required streaming');\n    }\n\n    const trace = this.buildDecisionTrace(caps, execution, streamMode);\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    yield* adapter.stream(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async chatWithTools(\n    messages: LLMMessage[],\n    options: LLMToolCallOptions,\n  ): Promise<LLMToolCallResponse> {\n    const { adapter, model, tier } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    if (!adapter.chatWithTools) {\n      throw new Error('Current adapter does not support chatWithTools');\n    }\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace) as LLMToolCallOptions;\n    return adapter.chatWithTools(messages, {\n      ...optionsWithTrace,\n      model,\n      execution,\n      metadata: { ...optionsWithTrace.metadata, tier },\n    });\n  }\n}\n\n/**\n * Check if LLM is available.\n *\n * Useful for conditional logic (LLM-powered vs deterministic fallback).\n *\n * @returns true if LLM is configured and ready\n *\n * @example\n * ```typescript\n * if (isLLMAvailable()) {\n *   const summary = await generateWithLLM(data);\n * } else {\n *   const summary = generateDeterministic(data);\n * }\n * ```\n */\nexport function isLLMAvailable(): boolean {\n  const llm = useLLM();\n  return !!llm;\n}\n\n/**\n * Get configured LLM tier.\n *\n * Useful for diagnostics and logging.\n *\n * @returns Configured tier or undefined if LLM not available/not a router\n *\n * @example\n * ```typescript\n * const tier = getLLMTier();\n * console.log(`Using LLM tier: ${tier ?? 'default'}`);\n * ```\n */\nexport function getLLMTier(): LLMTier | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (llm && isLLMRouter(llm)) {\n    return llm.getConfiguredTier();\n  }\n\n  return undefined;\n}\n\n/**\n * Type guard for ILLMRouter.\n */\nfunction isLLMRouter(llm: ILLM): llm is ILLM & ILLMRouter {\n  return (\n    typeof (llm as unknown as ILLMRouter).getConfiguredTier === 'function' &&\n    typeof (llm as unknown as ILLMRouter).resolve === 'function'\n  );\n}\n\n// Re-export types for convenience\nexport type { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-embeddings\n * Global Embeddings access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IEmbeddings } from '@kb-labs/core-platform';\n\n/**\n * Access global Embeddings adapter\n *\n * Returns the platform embeddings adapter (OpenAI, etc.).\n * Returns undefined if embeddings is not configured (graceful degradation).\n *\n * @returns Embeddings adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const embeddings = useEmbeddings();\n *\n * if (embeddings) {\n *   const vector = await embeddings.embed('Hello, world!');\n *   console.log(vector.length); // e.g., 1536 for OpenAI\n * }\n * ```\n */\nexport function useEmbeddings(): IEmbeddings | undefined {\n  const platform = usePlatform();\n  return platform.embeddings;\n}\n\n/**\n * Check if Embeddings is available\n *\n * @returns true if embeddings is configured and ready\n *\n * @example\n * ```typescript\n * if (isEmbeddingsAvailable()) {\n *   const vector = await embeddings.embed(text);\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isEmbeddingsAvailable(): boolean {\n  const embeddings = useEmbeddings();\n  return !!embeddings;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-vector-store\n * Global VectorStore access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IVectorStore } from '@kb-labs/core-platform';\n\n/**\n * Access global VectorStore adapter\n *\n * Returns the platform vector store adapter (Qdrant, local, etc.).\n * Returns undefined if vectorStore is not configured (graceful degradation).\n *\n * @returns VectorStore adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const vectorStore = useVectorStore();\n *\n * if (vectorStore) {\n *   await vectorStore.upsert([{ id: '1', vector: [0.1, 0.2], metadata: {} }]);\n *   const results = await vectorStore.search([0.1, 0.2], 10);\n * }\n * ```\n */\nexport function useVectorStore(): IVectorStore | undefined {\n  const platform = usePlatform();\n  return platform.vectorStore;\n}\n\n/**\n * Check if VectorStore is available\n *\n * @returns true if vectorStore is configured and ready\n *\n * @example\n * ```typescript\n * if (isVectorStoreAvailable()) {\n *   await vectorStore.upsert(records);\n * } else {\n *   // Use local fallback\n * }\n * ```\n */\nexport function isVectorStoreAvailable(): boolean {\n  const vectorStore = useVectorStore();\n  return !!vectorStore;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-analytics\n * Global analytics access helper\n *\n * Provides clean access to analytics/telemetry without context drilling.\n *\n * @example\n * ```typescript\n * import { useAnalytics } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const analytics = useAnalytics();\n *\n *   if (analytics) {\n *     await analytics.track('release_started', { version: '1.0.0' });\n *     analytics.metric('release_duration_ms', 1234);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IAnalytics } from '@kb-labs/core-platform';\n\n/**\n * Access global analytics adapter\n *\n * Returns the platform analytics adapter for tracking events and metrics.\n * Returns undefined if analytics is not configured (graceful degradation).\n *\n * **Methods:**\n * - `analytics.track(event, properties?)` - Track events\n * - `analytics.metric(name, value, tags?)` - Record metrics\n *\n * **Always check availability:**\n * ```typescript\n * const analytics = useAnalytics();\n * if (analytics) {\n *   await analytics.track('event');\n * }\n * ```\n *\n * @returns Analytics adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const analytics = useAnalytics();\n *\n * if (analytics) {\n *   await analytics.track('command_executed', {\n *     command: 'release:run',\n *     duration_ms: 1234,\n *     success: true,\n *   });\n *\n *   analytics.metric('release_packages_count', 5, {\n *     project: 'kb-labs',\n *   });\n * }\n * ```\n */\nexport function useAnalytics(): IAnalytics | undefined {\n  const platform = usePlatform();\n  return platform.analytics;\n}\n\n/**\n * Track event with analytics (safe, global singleton)\n *\n * Convenience wrapper that uses global platform analytics.\n * Does nothing if analytics is not configured.\n *\n * NOTE: For context-based analytics, use trackEvent() from '../analytics/with-analytics'.\n * This helper uses global singleton, not request-scoped context.\n *\n * @param event - Event name\n * @param properties - Event properties\n *\n * @example\n * ```typescript\n * import { trackAnalyticsEvent } from '@kb-labs/shared-command-kit/helpers';\n *\n * // No need to check if analytics exists\n * await trackAnalyticsEvent('release_completed', { version: '1.0.0', packages: 5 });\n * ```\n */\nexport async function trackAnalyticsEvent(\n  event: string,\n  properties?: Record<string, unknown>\n): Promise<void> {\n  const analytics = useAnalytics();\n  if (analytics) {\n    await analytics.track(event, properties);\n  }\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-storage\n * Global storage access helper\n *\n * Provides clean access to file/blob storage adapter.\n *\n * @example\n * ```typescript\n * import { useStorage } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const storage = useStorage();\n *\n *   if (storage) {\n *     await storage.write('path/to/file.txt', 'content');\n *     const content = await storage.read('path/to/file.txt');\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IStorage } from '@kb-labs/core-platform';\n\n/**\n * Access global storage adapter\n *\n * Returns the platform storage adapter for file/blob operations.\n * Returns undefined if storage is not configured (graceful degradation).\n *\n * **Methods:**\n * - `storage.read(path)` - Read file content\n * - `storage.write(path, content)` - Write file content\n * - `storage.exists(path)` - Check if file exists\n * - `storage.delete(path)` - Delete file\n * - `storage.list(prefix?)` - List files\n *\n * **Always check availability:**\n * ```typescript\n * const storage = useStorage();\n * if (storage) {\n *   await storage.write('file.txt', 'content');\n * }\n * ```\n *\n * @returns Storage adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const storage = useStorage();\n *\n * if (storage) {\n *   // Write file\n *   await storage.write('releases/v1.0.0.json', JSON.stringify(data));\n *\n *   // Read file\n *   const content = await storage.read('releases/v1.0.0.json');\n *   const data = JSON.parse(content);\n *\n *   // Check existence\n *   const exists = await storage.exists('releases/v1.0.0.json');\n *\n *   // List files\n *   const files = await storage.list('releases/');\n * }\n * ```\n */\nexport function useStorage(): IStorage | undefined {\n  const platform = usePlatform();\n  return platform.storage;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-cache\n * Global Cache access helper\n *\n * Provides clean access to platform cache (Redis, InMemory, or custom adapter).\n *\n * @example\n * ```typescript\n * import { useCache } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const cache = useCache();\n *\n *   if (cache) {\n *     await cache.set('key', { data: 'value' }, 60000); // TTL: 60s\n *     const value = await cache.get('key');\n *     console.log(value);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type { ICache } from '@kb-labs/core-platform';\n\n/**\n * Access global cache adapter\n *\n * Returns the platform cache adapter (Redis, InMemory, or custom).\n * Returns undefined if cache is not configured (graceful degradation).\n *\n * **Methods:**\n * - `cache.set(key, value, ttlMs?)` - Store value with optional TTL\n * - `cache.get<T>(key)` - Retrieve value by key\n * - `cache.delete(key)` - Remove value\n * - `cache.clear()` - Clear all cached values\n *\n * **Always check availability:**\n * ```typescript\n * const cache = useCache();\n * if (cache) {\n *   await cache.set('query-123', result, 60000);\n * } else {\n *   // No caching, compute every time\n * }\n * ```\n *\n * @returns Cache adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const cache = useCache();\n *\n * if (cache) {\n *   // Check cache first\n *   const cached = await cache.get<QueryResult>('query-123');\n *   if (cached) {\n *     return cached;\n *   }\n *\n *   // Compute result\n *   const result = await expensiveQuery();\n *\n *   // Cache for 5 minutes\n *   await cache.set('query-123', result, 5 * 60 * 1000);\n *\n *   return result;\n * }\n * ```\n */\nexport function useCache(): ICache | undefined {\n  const platform = usePlatform();\n  return platform.cache;\n}\n\n/**\n * Check if cache is available\n *\n * Useful for conditional logic (cached vs non-cached execution).\n *\n * @returns true if cache is configured and ready\n *\n * @example\n * ```typescript\n * if (isCacheAvailable()) {\n *   // Use cached results\n *   const result = await getCachedOrCompute(key);\n * } else {\n *   // Compute every time\n *   const result = await compute();\n * }\n * ```\n */\nexport function isCacheAvailable(): boolean {\n  const cache = useCache();\n  return !!cache;\n}\n"]}
+{"version":3,"sources":["../../src/helpers/use-platform.ts","../../src/helpers/index.ts","../../src/helpers/use-config.ts","../../src/helpers/use-logger.ts","../../src/helpers/use-llm.ts","../../src/helpers/use-embeddings.ts","../../src/helpers/use-vector-store.ts","../../src/helpers/use-analytics.ts","../../src/helpers/use-storage.ts","../../src/helpers/use-cache.ts","../../src/helpers/use-env.ts"],"names":["globalPlatform","usePlatform","trace","optionsWithTrace"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/shared-command-kit/helpers/use-platform\n * Platform access hook with execution-scoped context.\n *\n * Uses AsyncLocalStorage to return the correct platform for the current\n * handler execution (governed, with correct permissions and proxy adapters).\n * Falls back to global singleton for code running outside handler context.\n *\n * @example\n * ```typescript\n * import { usePlatform } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler — automatically gets the right platform\n * async handler(ctx, argv, flags) {\n *   const platform = usePlatform();\n *   const result = await platform.llm.complete('prompt');\n * }\n * ```\n */\n\nimport { platformContext } from '@kb-labs/plugin-contracts';\nimport { platform as globalPlatform } from '@kb-labs/core-runtime';\n\n/**\n * Access platform services for the current execution context.\n *\n * Priority:\n * 1. AsyncLocalStorage context (set by runInProcess) — per-execution, governed\n * 2. Global singleton fallback (core-runtime) — for code outside handler context\n *\n * @returns Platform services with correct adapters for current context\n */\nexport function usePlatform(): typeof globalPlatform {\n  return (platformContext.getStore() as typeof globalPlatform) ?? globalPlatform;\n}\n\n/**\n * Check if specific platform adapter is configured\n *\n * Useful for conditional logic based on available services.\n *\n * @param adapterName - Name of the adapter to check\n * @returns true if adapter is configured and available\n *\n * @example\n * ```typescript\n * if (isPlatformConfigured('llm')) {\n *   // Use LLM-powered feature\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isPlatformConfigured(adapterName: keyof typeof globalPlatform): boolean {\n  const platform = usePlatform();\n\n  // Check if adapter exists and is not a noop/fallback\n  const adapter = platform[adapterName];\n\n  if (!adapter) {\n    return false;\n  }\n\n  // For adapters with hasAdapter method (like platform itself)\n  if ('hasAdapter' in platform && typeof platform.hasAdapter === 'function') {\n    return platform.hasAdapter(adapterName as any);\n  }\n\n  // Fallback: check if adapter is not noop\n  // Noop adapters usually have a specific constructor name or are simple objects\n  if (typeof adapter === 'object' && adapter.constructor) {\n    const constructorName = adapter.constructor.name;\n    return !constructorName.toLowerCase().includes('noop') &&\n           !constructorName.toLowerCase().includes('fallback');\n  }\n\n  return true;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers\n * Global platform access helpers\n *\n * Provides clean, type-safe access to platform services without context drilling.\n * Similar to React hooks pattern, but for KB Labs platform.\n *\n * @example\n * ```typescript\n * import { useLLM, useLogger, useAnalytics } from '@kb-labs/shared-command-kit/helpers';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *   const llm = useLLM();\n *\n *   await logger.info('Processing started');\n *\n *   if (llm) {\n *     const result = await llm.complete('prompt');\n *     await logger.info('LLM result', { length: result.content.length });\n *   }\n * }\n * ```\n */\n\n// Platform singleton\nexport { usePlatform, isPlatformConfigured } from './use-platform';\n\n// Context types and helpers\nexport type { PluginContextV3 } from './context';\n\n// Config access\nexport { useConfig } from './use-config';\n\n// Core services\nexport { useLogger, useLoggerWithContext } from './use-logger.js';\nexport { useLLM, isLLMAvailable, getLLMTier, type LLMTier, type UseLLMOptions } from './use-llm.js';\nexport { useEmbeddings, isEmbeddingsAvailable } from './use-embeddings.js';\nexport { useVectorStore, isVectorStoreAvailable } from './use-vector-store.js';\nexport { useAnalytics, trackAnalyticsEvent } from './use-analytics.js';\nexport { useStorage } from './use-storage.js';\nexport { useCache, isCacheAvailable } from './use-cache.js';\n\n// Runtime shims\nexport { useEnv } from './use-env.js';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-config\n * Global config access helper\n *\n * Provides clean access to product-specific configuration without context drilling.\n * Similar to React hooks pattern, but for KB Labs config.\n *\n * @example\n * ```typescript\n * import { useConfig } from '@kb-labs/shared-command-kit';\n *\n * // In any command handler\n * async handler(ctx, argv, flags) {\n *   const config = await useConfig('mind');\n *\n *   if (config) {\n *     const scopes = config.scopes;\n *     // Use config...\n *   }\n * }\n * ```\n */\n\n/**\n * Access product-specific configuration from kb.config.json\n *\n * Returns ONLY the config for the specified product and profile.\n * Uses platform.config adapter (works across parent/child processes via IPC).\n * Supports both Profiles v2 and legacy config structures.\n *\n * **Security:** This function returns ONLY the product-specific config,\n * not the entire kb.config.json. This prevents cross-product config access.\n *\n * **Auto-detection:** If productId is not provided, it's automatically inferred\n * from the plugin's manifest.configSection field (passed via execution context).\n *\n * **Profiles v2 structure:**\n * ```json\n * {\n *   \"profiles\": [\n *     {\n *       \"id\": \"default\",\n *       \"products\": {\n *         \"mind\": { \"scopes\": [...] },\n *         \"workflow\": { \"maxConcurrency\": 10 }\n *       }\n *     }\n *   ]\n * }\n * ```\n *\n * **Legacy structure:**\n * ```json\n * {\n *   \"knowledge\": { \"scopes\": [...] },  // for \"mind\" product\n *   \"workflow\": { \"maxConcurrency\": 10 }\n * }\n * ```\n *\n * @param productId - Product identifier (e.g., 'mind', 'workflow', 'plugins'). Optional - auto-detected from context.\n * @param profileId - Profile identifier (defaults to 'default' or KB_PROFILE env var)\n * @returns Promise resolving to product-specific config or undefined\n *\n * @example\n * ```typescript\n * // Auto-detect from context (recommended)\n * const config = await useConfig();\n *\n * // Explicit product ID\n * const mindConfig = await useConfig('mind');\n * if (mindConfig?.scopes) {\n *   // Use scopes\n * }\n *\n * // With explicit profile\n * const workflowConfig = await useConfig('workflow', 'production');\n * ```\n */\nexport async function useConfig<T = any>(productId?: string, profileId?: string): Promise<T | undefined> {\n  // Auto-detect productId from manifest.configSection if not provided\n  let effectiveProductId = productId;\n  if (!effectiveProductId) {\n    effectiveProductId = (globalThis as any).__KB_CONFIG_SECTION__;\n  }\n\n  if (!effectiveProductId) {\n    return undefined;\n  }\n\n  const { usePlatform } = await import('./use-platform.js');\n  const platform = usePlatform();\n\n  if (!platform) {\n    return undefined;\n  }\n\n  // Returns ONLY the product-specific config, not the entire kb.config.json\n  return await platform.config.getConfig(effectiveProductId, profileId) as T | undefined;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-logger\n * Global logger access helper\n *\n * Provides clean access to structured logging without context drilling.\n *\n * @example\n * ```typescript\n * import { useLogger } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const logger = useLogger();\n *\n *   await logger.info('Processing started');\n *   await logger.debug('Details', { userId: 123 });\n *   await logger.error('Failed', { error: err });\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { ILogger } from '@kb-labs/core-platform';\n\n/**\n * Access global logger\n *\n * Returns the platform logger with structured logging capabilities.\n * Supports child loggers with additional context.\n *\n * **Methods:**\n * - `logger.trace(message, meta?)` - Trace-level logs (most verbose)\n * - `logger.debug(message, meta?)` - Debug-level logs\n * - `logger.info(message, meta?)` - Info-level logs\n * - `logger.warn(message, meta?)` - Warning-level logs\n * - `logger.error(message, meta?)` - Error-level logs\n * - `logger.child(meta)` - Create child logger with additional context\n *\n * @returns Platform logger instance\n *\n * @example\n * ```typescript\n * const logger = useLogger();\n *\n * await logger.info('Task started', { taskId: '123' });\n * await logger.error('Task failed', { taskId: '123', error: err.message });\n *\n * // Child logger with persistent context\n * const taskLogger = logger.child({ taskId: '123', userId: 'user-1' });\n * await taskLogger.info('Step 1 completed');\n * await taskLogger.info('Step 2 completed');\n * ```\n */\nexport function useLogger(): ILogger {\n  const platform = usePlatform();\n  return platform.logger;\n}\n\n/**\n * Create child logger with additional context\n *\n * Useful for scoped logging within a specific operation.\n *\n * @param context - Additional context to attach to all log entries\n * @returns Child logger with persistent context\n *\n * @example\n * ```typescript\n * const logger = useLoggerWithContext({ operation: 'release', version: '1.0.0' });\n *\n * await logger.info('Started');  // Automatically includes operation + version\n * await logger.info('Completed');\n * ```\n */\nexport function useLoggerWithContext(context: Record<string, unknown>): ILogger {\n  const logger = useLogger();\n  return logger.child(context);\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-llm\n * Global LLM access helper with tier-based model selection.\n *\n * Provides clean access to LLM with adaptive tier routing.\n * Plugins specify tiers (small/medium/large), platform resolves to actual models.\n *\n * @example\n * ```typescript\n * import { useLLM } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   // Simple usage (uses configured default tier)\n *   const llm = useLLM();\n *\n *   // Request specific tier (platform adapts if needed)\n *   const llm = useLLM({ tier: 'small' });   // Simple tasks\n *   const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n *   // Request capabilities\n *   const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n *\n *   if (llm) {\n *     const result = await llm.complete('Explain this code');\n *     console.log(result.content);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type {\n  ILLM,\n  LLMTier,\n  LLMOptions,\n  LLMResponse,\n  LLMMessage,\n  LLMToolCallOptions,\n  LLMToolCallResponse,\n  UseLLMOptions,\n  ILLMRouter,\n  LLMAdapterBinding,\n  LLMExecutionPolicy,\n  LLMProtocolCapabilities,\n  LLMCacheDecisionTrace,\n} from '@kb-labs/core-platform';\n\n/**\n * Access global LLM adapter with tier-based selection.\n *\n * Platform automatically adapts to available models:\n * - If plugin requests 'small' but 'medium' configured → uses 'medium' (escalation)\n * - If plugin requests 'large' but 'medium' configured → uses 'medium' with warning (degradation)\n *\n * **Tiers are user-defined slots:**\n * - `small`  - Plugin says: \"This task is simple\"\n * - `medium` - Plugin says: \"Standard task\"\n * - `large`  - Plugin says: \"Complex task, need maximum quality\"\n *\n * User decides what model maps to each tier in their config.\n *\n * @param options - Optional tier and capability requirements\n * @returns LLM adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * // Simple usage (uses configured default)\n * const llm = useLLM();\n *\n * // Request specific tier\n * const llm = useLLM({ tier: 'small' });   // Simple tasks\n * const llm = useLLM({ tier: 'large' });   // Complex tasks\n *\n * // Request capabilities\n * const llm = useLLM({ tier: 'medium', capabilities: ['coding'] });\n * const llm = useLLM({ capabilities: ['vision'] });\n *\n * if (llm) {\n *   const result = await llm.complete('Generate commit message');\n *   console.log(result.content);\n * }\n * ```\n */\nexport function useLLM(options?: UseLLMOptions): ILLM | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (!llm) {\n    return undefined;\n  }\n\n  // If router and options given → return immutable LazyBoundLLM (no state mutation)\n  if (options && isLLMRouter(llm)) {\n    return new LazyBoundLLM(llm, options);\n  }\n\n  return llm;\n}\n\n/**\n * Lazy adapter binding that resolves tier on first use.\n * Immutable — does NOT mutate the global LLMRouter state.\n * This fixes the race condition where useLLM({ tier: 'large' }) was immediately\n * overwritten by useLLM({ tier: 'small' }) from SmartSummarizer.\n */\nclass LazyBoundLLM implements ILLM {\n  private _resolved: Promise<LLMAdapterBinding> | null = null;\n\n  constructor(\n    private readonly router: ILLM & ILLMRouter,\n    private readonly options: UseLLMOptions,\n  ) {}\n\n  private resolve(): Promise<LLMAdapterBinding> {\n    if (!this._resolved) {\n      this._resolved = this.router.resolveAdapter(this.options);\n    }\n    return this._resolved;\n  }\n\n  private mergeExecutionPolicy(callOptions?: LLMOptions): LLMExecutionPolicy | undefined {\n    const globalPolicy = this.options.execution;\n    const localPolicy = callOptions?.execution;\n    if (!globalPolicy && !localPolicy) {\n      return undefined;\n    }\n    return {\n      ...globalPolicy,\n      ...localPolicy,\n      cache: { ...globalPolicy?.cache, ...localPolicy?.cache },\n      stream: { ...globalPolicy?.stream, ...localPolicy?.stream },\n    };\n  }\n\n  private async resolveProtocolCapabilities(adapter: ILLM): Promise<LLMProtocolCapabilities> {\n    if (!adapter.getProtocolCapabilities) {\n      return {\n        cache: { supported: false },\n        stream: { supported: true },\n      };\n    }\n    return adapter.getProtocolCapabilities();\n  }\n\n  private enforceCachePolicy(caps: LLMProtocolCapabilities, execution?: LLMExecutionPolicy): void {\n    if (execution?.cache?.mode === 'require' && !caps.cache.supported) {\n      throw new Error('CACHE_NOT_SUPPORTED: adapter does not support required cache policy');\n    }\n  }\n\n  private buildDecisionTrace(\n    caps: LLMProtocolCapabilities,\n    execution: LLMExecutionPolicy | undefined,\n    streamAppliedMode: 'prefer' | 'require' | 'off',\n    streamFallback?: 'complete',\n    reason?: string,\n  ): LLMCacheDecisionTrace {\n    const requestedCacheMode = execution?.cache?.mode ?? 'prefer';\n    const requestedStreamMode = execution?.stream?.mode ?? 'prefer';\n\n    return {\n      cacheRequestedMode: requestedCacheMode,\n      cacheSupported: caps.cache.supported,\n      cacheAppliedMode:\n        requestedCacheMode === 'require' || requestedCacheMode === 'bypass'\n          ? requestedCacheMode\n          : caps.cache.supported\n            ? 'prefer'\n            : 'bypass',\n      streamRequestedMode: requestedStreamMode,\n      streamSupported: caps.stream.supported,\n      streamAppliedMode,\n      streamFallback,\n      reason,\n    };\n  }\n\n  private withDecisionMetadata(\n    options: LLMOptions | undefined,\n    trace: LLMCacheDecisionTrace,\n  ): LLMOptions | undefined {\n    if (!options) {\n      return { metadata: { cacheDecisionTrace: trace } };\n    }\n\n    return {\n      ...options,\n      metadata: {\n        ...options.metadata,\n        cacheDecisionTrace: trace,\n      },\n    };\n  }\n\n  async complete(prompt: string, options?: LLMOptions): Promise<LLMResponse> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    return adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async *stream(prompt: string, options?: LLMOptions): AsyncIterable<string> {\n    const { adapter, model } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n\n    const streamMode = execution?.stream?.mode ?? 'prefer';\n    const canStream = caps.stream.supported;\n    const allowFallback = execution?.stream?.fallbackToComplete ?? true;\n\n    if (streamMode === 'off' || (!canStream && streamMode === 'prefer' && allowFallback)) {\n      const fallbackReason =\n        streamMode === 'off'\n          ? 'STREAM_OFF'\n          : 'STREAM_UNSUPPORTED_FALLBACK_TO_COMPLETE';\n      const trace = this.buildDecisionTrace(caps, execution, 'off', 'complete', fallbackReason);\n      const optionsWithTrace = this.withDecisionMetadata(options, trace);\n      const response = await adapter.complete(prompt, { ...optionsWithTrace, model, execution });\n      if (response.content) {\n        yield response.content;\n      }\n      return;\n    }\n\n    if (!canStream && streamMode === 'require') {\n      throw new Error('STREAM_NOT_SUPPORTED: adapter does not support required streaming');\n    }\n\n    const trace = this.buildDecisionTrace(caps, execution, streamMode);\n    const optionsWithTrace = this.withDecisionMetadata(options, trace);\n    yield* adapter.stream(prompt, { ...optionsWithTrace, model, execution });\n  }\n\n  async chatWithTools(\n    messages: LLMMessage[],\n    options: LLMToolCallOptions,\n  ): Promise<LLMToolCallResponse> {\n    const { adapter, model, tier } = await this.resolve();\n    const execution = this.mergeExecutionPolicy(options);\n    const caps = await this.resolveProtocolCapabilities(adapter);\n    this.enforceCachePolicy(caps, execution);\n    if (!adapter.chatWithTools) {\n      throw new Error('Current adapter does not support chatWithTools');\n    }\n    const trace = this.buildDecisionTrace(caps, execution, 'off');\n    const optionsWithTrace = this.withDecisionMetadata(options, trace) as LLMToolCallOptions;\n    return adapter.chatWithTools(messages, {\n      ...optionsWithTrace,\n      model,\n      execution,\n      metadata: { ...optionsWithTrace.metadata, tier },\n    });\n  }\n}\n\n/**\n * Check if LLM is available.\n *\n * Useful for conditional logic (LLM-powered vs deterministic fallback).\n *\n * @returns true if LLM is configured and ready\n *\n * @example\n * ```typescript\n * if (isLLMAvailable()) {\n *   const summary = await generateWithLLM(data);\n * } else {\n *   const summary = generateDeterministic(data);\n * }\n * ```\n */\nexport function isLLMAvailable(): boolean {\n  const llm = useLLM();\n  return !!llm;\n}\n\n/**\n * Get configured LLM tier.\n *\n * Useful for diagnostics and logging.\n *\n * @returns Configured tier or undefined if LLM not available/not a router\n *\n * @example\n * ```typescript\n * const tier = getLLMTier();\n * console.log(`Using LLM tier: ${tier ?? 'default'}`);\n * ```\n */\nexport function getLLMTier(): LLMTier | undefined {\n  const platform = usePlatform();\n  const llm = platform.llm;\n\n  if (llm && isLLMRouter(llm)) {\n    return llm.getConfiguredTier();\n  }\n\n  return undefined;\n}\n\n/**\n * Type guard for ILLMRouter.\n */\nfunction isLLMRouter(llm: ILLM): llm is ILLM & ILLMRouter {\n  return (\n    typeof (llm as unknown as ILLMRouter).getConfiguredTier === 'function' &&\n    typeof (llm as unknown as ILLMRouter).resolve === 'function'\n  );\n}\n\n// Re-export types for convenience\nexport type { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-embeddings\n * Global Embeddings access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IEmbeddings } from '@kb-labs/core-platform';\n\n/**\n * Access global Embeddings adapter\n *\n * Returns the platform embeddings adapter (OpenAI, etc.).\n * Returns undefined if embeddings is not configured (graceful degradation).\n *\n * @returns Embeddings adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const embeddings = useEmbeddings();\n *\n * if (embeddings) {\n *   const vector = await embeddings.embed('Hello, world!');\n *   console.log(vector.length); // e.g., 1536 for OpenAI\n * }\n * ```\n */\nexport function useEmbeddings(): IEmbeddings | undefined {\n  const platform = usePlatform();\n  return platform.embeddings;\n}\n\n/**\n * Check if Embeddings is available\n *\n * @returns true if embeddings is configured and ready\n *\n * @example\n * ```typescript\n * if (isEmbeddingsAvailable()) {\n *   const vector = await embeddings.embed(text);\n * } else {\n *   // Use deterministic fallback\n * }\n * ```\n */\nexport function isEmbeddingsAvailable(): boolean {\n  const embeddings = useEmbeddings();\n  return !!embeddings;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-vector-store\n * Global VectorStore access helper\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IVectorStore } from '@kb-labs/core-platform';\n\n/**\n * Access global VectorStore adapter\n *\n * Returns the platform vector store adapter (Qdrant, local, etc.).\n * Returns undefined if vectorStore is not configured (graceful degradation).\n *\n * @returns VectorStore adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const vectorStore = useVectorStore();\n *\n * if (vectorStore) {\n *   await vectorStore.upsert([{ id: '1', vector: [0.1, 0.2], metadata: {} }]);\n *   const results = await vectorStore.search([0.1, 0.2], 10);\n * }\n * ```\n */\nexport function useVectorStore(): IVectorStore | undefined {\n  const platform = usePlatform();\n  return platform.vectorStore;\n}\n\n/**\n * Check if VectorStore is available\n *\n * @returns true if vectorStore is configured and ready\n *\n * @example\n * ```typescript\n * if (isVectorStoreAvailable()) {\n *   await vectorStore.upsert(records);\n * } else {\n *   // Use local fallback\n * }\n * ```\n */\nexport function isVectorStoreAvailable(): boolean {\n  const vectorStore = useVectorStore();\n  return !!vectorStore;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-analytics\n * Global analytics access helper\n *\n * Provides clean access to analytics/telemetry without context drilling.\n *\n * @example\n * ```typescript\n * import { useAnalytics } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const analytics = useAnalytics();\n *\n *   if (analytics) {\n *     await analytics.track('release_started', { version: '1.0.0' });\n *     analytics.metric('release_duration_ms', 1234);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IAnalytics } from '@kb-labs/core-platform';\n\n/**\n * Access global analytics adapter\n *\n * Returns the platform analytics adapter for tracking events and metrics.\n * Returns undefined if analytics is not configured (graceful degradation).\n *\n * **Methods:**\n * - `analytics.track(event, properties?)` - Track events\n * - `analytics.metric(name, value, tags?)` - Record metrics\n *\n * **Always check availability:**\n * ```typescript\n * const analytics = useAnalytics();\n * if (analytics) {\n *   await analytics.track('event');\n * }\n * ```\n *\n * @returns Analytics adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const analytics = useAnalytics();\n *\n * if (analytics) {\n *   await analytics.track('command_executed', {\n *     command: 'release:run',\n *     duration_ms: 1234,\n *     success: true,\n *   });\n *\n *   analytics.metric('release_packages_count', 5, {\n *     project: 'kb-labs',\n *   });\n * }\n * ```\n */\nexport function useAnalytics(): IAnalytics | undefined {\n  const platform = usePlatform();\n  return platform.analytics;\n}\n\n/**\n * Track event with analytics (safe, global singleton)\n *\n * Convenience wrapper that uses global platform analytics.\n * Does nothing if analytics is not configured.\n *\n * NOTE: For context-based analytics, use trackEvent() from '../analytics/with-analytics'.\n * This helper uses global singleton, not request-scoped context.\n *\n * @param event - Event name\n * @param properties - Event properties\n *\n * @example\n * ```typescript\n * import { trackAnalyticsEvent } from '@kb-labs/shared-command-kit/helpers';\n *\n * // No need to check if analytics exists\n * await trackAnalyticsEvent('release_completed', { version: '1.0.0', packages: 5 });\n * ```\n */\nexport async function trackAnalyticsEvent(\n  event: string,\n  properties?: Record<string, unknown>\n): Promise<void> {\n  const analytics = useAnalytics();\n  if (analytics) {\n    await analytics.track(event, properties);\n  }\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-storage\n * Global storage access helper\n *\n * Provides clean access to file/blob storage adapter.\n *\n * @example\n * ```typescript\n * import { useStorage } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const storage = useStorage();\n *\n *   if (storage) {\n *     await storage.write('path/to/file.txt', 'content');\n *     const content = await storage.read('path/to/file.txt');\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform';\nimport type { IStorage } from '@kb-labs/core-platform';\n\n/**\n * Access global storage adapter\n *\n * Returns the platform storage adapter for file/blob operations.\n * Returns undefined if storage is not configured (graceful degradation).\n *\n * **Methods:**\n * - `storage.read(path)` - Read file content\n * - `storage.write(path, content)` - Write file content\n * - `storage.exists(path)` - Check if file exists\n * - `storage.delete(path)` - Delete file\n * - `storage.list(prefix?)` - List files\n *\n * **Always check availability:**\n * ```typescript\n * const storage = useStorage();\n * if (storage) {\n *   await storage.write('file.txt', 'content');\n * }\n * ```\n *\n * @returns Storage adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const storage = useStorage();\n *\n * if (storage) {\n *   // Write file\n *   await storage.write('releases/v1.0.0.json', JSON.stringify(data));\n *\n *   // Read file\n *   const content = await storage.read('releases/v1.0.0.json');\n *   const data = JSON.parse(content);\n *\n *   // Check existence\n *   const exists = await storage.exists('releases/v1.0.0.json');\n *\n *   // List files\n *   const files = await storage.list('releases/');\n * }\n * ```\n */\nexport function useStorage(): IStorage | undefined {\n  const platform = usePlatform();\n  return platform.storage;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-cache\n * Global Cache access helper\n *\n * Provides clean access to platform cache (Redis, InMemory, or custom adapter).\n *\n * @example\n * ```typescript\n * import { useCache } from '@kb-labs/shared-command-kit';\n *\n * async handler(ctx, argv, flags) {\n *   const cache = useCache();\n *\n *   if (cache) {\n *     await cache.set('key', { data: 'value' }, 60000); // TTL: 60s\n *     const value = await cache.get('key');\n *     console.log(value);\n *   }\n * }\n * ```\n */\n\nimport { usePlatform } from './use-platform.js';\nimport type { ICache } from '@kb-labs/core-platform';\n\n/**\n * Access global cache adapter\n *\n * Returns the platform cache adapter (Redis, InMemory, or custom).\n * Returns undefined if cache is not configured (graceful degradation).\n *\n * **Methods:**\n * - `cache.set(key, value, ttlMs?)` - Store value with optional TTL\n * - `cache.get<T>(key)` - Retrieve value by key\n * - `cache.delete(key)` - Remove value\n * - `cache.clear()` - Clear all cached values\n *\n * **Always check availability:**\n * ```typescript\n * const cache = useCache();\n * if (cache) {\n *   await cache.set('query-123', result, 60000);\n * } else {\n *   // No caching, compute every time\n * }\n * ```\n *\n * @returns Cache adapter or undefined if not configured\n *\n * @example\n * ```typescript\n * const cache = useCache();\n *\n * if (cache) {\n *   // Check cache first\n *   const cached = await cache.get<QueryResult>('query-123');\n *   if (cached) {\n *     return cached;\n *   }\n *\n *   // Compute result\n *   const result = await expensiveQuery();\n *\n *   // Cache for 5 minutes\n *   await cache.set('query-123', result, 5 * 60 * 1000);\n *\n *   return result;\n * }\n * ```\n */\nexport function useCache(): ICache | undefined {\n  const platform = usePlatform();\n  return platform.cache;\n}\n\n/**\n * Check if cache is available\n *\n * Useful for conditional logic (cached vs non-cached execution).\n *\n * @returns true if cache is configured and ready\n *\n * @example\n * ```typescript\n * if (isCacheAvailable()) {\n *   // Use cached results\n *   const result = await getCachedOrCompute(key);\n * } else {\n *   // Compute every time\n *   const result = await compute();\n * }\n * ```\n */\nexport function isCacheAvailable(): boolean {\n  const cache = useCache();\n  return !!cache;\n}\n","/**\n * @module @kb-labs/shared-command-kit/helpers/use-env\n *\n * Sandboxed environment variable access.\n *\n * Reads from runtimeContext (AsyncLocalStorage) when running inside\n * a governed handler execution (worker-pool, subprocess).\n * Falls back to process.env when no runtime context is set\n * (direct CLI, tests, code outside handler).\n *\n * @example\n * ```typescript\n * import { useEnv } from '@kb-labs/sdk';\n *\n * const token = useEnv('NPM_TOKEN');\n * const ci = useEnv('CI');\n * ```\n */\n\nimport { runtimeContext } from '@kb-labs/plugin-contracts';\n\n/**\n * Read an environment variable through the sandboxed runtime context.\n *\n * Inside a governed handler: reads through env-shim (permission-checked).\n * Outside handler context: reads process.env directly (backward compat).\n */\nexport function useEnv(key: string): string | undefined {\n  const runtime = runtimeContext.getStore();\n  if (runtime?.env) {\n    return runtime.env(key);\n  }\n  return process.env[key];\n}\n"]}

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { FlagSchemaDefinition as FlagSchemaDefinition$1, InferFlags } from './fl
 export { ArrayFlagSchema, BaseFlagSchema, BooleanFlagSchema, FlagSchema, FlagSchemaWithInfer, FlagType, FlagValidationError, NumberFlagSchema, SafeValidationResult, StringFlagSchema, ValidationResult, defineFlags, validateFlags, validateFlagsSafe } from './flags/index.js';
 export { AnalyticsContext, AnalyticsEvents, createAnalyticsWrapper, trackEvent, withAnalytics } from './analytics/index.js';
 export { ErrorDefinition, ErrorDefinitions, FormatErrorOptions, FormattedError, PluginError, commonErrors, defineError, formatError } from './errors/index.js';
-export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore } from './helpers/index.js';
+export { getLLMTier, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isVectorStoreAvailable, trackAnalyticsEvent, useAnalytics, useCache, useConfig, useEmbeddings, useEnv, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore } from './helpers/index.js';
 import { z } from 'zod';
 export { CommandOutput } from '@kb-labs/shared-cli-ui';
 export { LLMTier, UseLLMOptions } from '@kb-labs/core-platform';

package/dist/index.js

@@ -1,4 +1,4 @@
-import { platformContext } from '@kb-labs/plugin-contracts';
+import { platformContext, runtimeContext } from '@kb-labs/plugin-contracts';
 import { platform } from '@kb-labs/core-runtime';
 import { z } from 'zod';
 import * as fs from 'fs/promises';
@@ -878,6 +878,13 @@ function isCacheAvailable() {
   const cache = useCache();
   return !!cache;
 }
+function useEnv(key) {
+  const runtime = runtimeContext.getStore();
+  if (runtime?.env) {
+    return runtime.env(key);
+  }
+  return process.env[key];
+}
 
 // src/define-system-command.ts
 function convertFlagSchema(schema2) {
@@ -1546,6 +1553,6 @@ var MessageRouter = class {
   }
 };
 
-export { FlagValidationError, MessageBuilder, MessageRouter, PluginError, array, artifactId, boolean, commandId, commonErrors, createAnalyticsWrapper, cwd, datetime, defineAction, defineCommand, defineCommandFlags, defineDestroyHandler, defineError, defineFlags, defineHandler, defineJob, defineManifest, defineMessage, defineRoute, defineSetupHandler, defineSystemCommand, defineSystemCommandGroup, defineWebSocket, defineWebhook, email, enumSchema, filePath, formatError, getLLMTier, isCLIHost, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isRESTHost, isVectorStoreAvailable, isWSHost, isWebhookHost, isWorkflowHost, json, nonNegativeInt, object, pluginId, positiveInt, schema, scopeId, text, trackAnalyticsEvent, trackEvent, url, useAnalytics, useCache, useConfig, useEmbeddings, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore, uuid, validateFlags, validateFlagsSafe, withAnalytics };
+export { FlagValidationError, MessageBuilder, MessageRouter, PluginError, array, artifactId, boolean, commandId, commonErrors, createAnalyticsWrapper, cwd, datetime, defineAction, defineCommand, defineCommandFlags, defineDestroyHandler, defineError, defineFlags, defineHandler, defineJob, defineManifest, defineMessage, defineRoute, defineSetupHandler, defineSystemCommand, defineSystemCommandGroup, defineWebSocket, defineWebhook, email, enumSchema, filePath, formatError, getLLMTier, isCLIHost, isCacheAvailable, isEmbeddingsAvailable, isLLMAvailable, isPlatformConfigured, isRESTHost, isVectorStoreAvailable, isWSHost, isWebhookHost, isWorkflowHost, json, nonNegativeInt, object, pluginId, positiveInt, schema, scopeId, text, trackAnalyticsEvent, trackEvent, url, useAnalytics, useCache, useConfig, useEmbeddings, useEnv, useLLM, useLogger, useLoggerWithContext, usePlatform, useStorage, useVectorStore, uuid, validateFlags, validateFlagsSafe, withAnalytics };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map