comisai 1.0.4

package/node_modules/@comis/daemon/dist/wiring/setup-mcp.js

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * MCP server connection setup: reads integrations.mcp.servers from config,
+ * creates an McpClientManager, and connects to each enabled server.
+ * Non-fatal: connection failures are logged as WARN and do not prevent
+ * daemon startup. Tools from successfully connected servers are still
+ * available to agents.
+ * @module
+ */
+import { mkdirSync } from "node:fs";
+import { safePath } from "@comis/core";
+import { createMcpClientManager } from "@comis/skills";
+// ---------------------------------------------------------------------------
+// Setup function
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the default cwd for a stdio MCP server when the config does
+ * not specify `server.cwd` explicitly. Returns a per-server output
+ * subdirectory `{workspaceDir}/output/{serverName}/` and ensures the
+ * directory exists on disk with mode 0o700. Falls back to the
+ * workspace root if directory creation fails (logged as WARN).
+ *
+ * `serverName` is already schema-validated against
+ * `/^[a-zA-Z0-9_-]+$/` (schema-integrations.ts), so no runtime
+ * sanitization is needed here.
+ */
+function resolveDefaultMcpCwd(workspaceDir, serverName, logger) {
+    if (!workspaceDir)
+        return undefined;
+    let dir;
+    try {
+        // serverName is schema-validated to /^[a-zA-Z0-9_-]+$/ so safePath
+        // won't reject it, but keep the guard for defense-in-depth.
+        dir = safePath(workspaceDir, "output", serverName);
+    }
+    catch (err) {
+        logger.warn({
+            serverName,
+            err: err instanceof Error ? err.message : String(err),
+            hint: "Falling back to workspace root cwd for MCP server",
+            errorKind: "validation",
+        }, "Rejected MCP server output dir path");
+        return workspaceDir;
+    }
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        return dir;
+    }
+    catch (err) {
+        logger.warn({
+            serverName,
+            dir,
+            err: err instanceof Error ? err.message : String(err),
+            hint: "Falling back to workspace root cwd for MCP server",
+            errorKind: "io",
+        }, "Failed to create MCP server output dir");
+        return workspaceDir;
+    }
+}
+/**
+ * Connect to configured MCP servers and return the client manager.
+ * The manager is always returned (never undefined) so that runtime
+ * `mcp.connect` / `.disconnect` / `.reconnect` / `.status` RPCs work
+ * even when zero servers were configured at startup. Individual server
+ * connection failures are logged but do not block the remaining servers
+ * or daemon startup.
+ */
+export async function setupMcp(deps) {
+    const { servers, logger } = deps;
+    // Always construct the manager. It's a pure in-memory state holder
+    // (Maps/Sets + defaults, no I/O) — constructing it unconditionally lets
+    // runtime `mcp.connect` RPCs succeed even when zero servers were
+    // configured at startup. If this throws, it's a build/deploy defect,
+    // not a runtime condition — re-raise so bootstrap surfaces the failure
+    // loudly rather than masking it behind a nulled manager.
+    const manager = createMcpClientManager({
+        logger,
+        callToolTimeoutMs: deps.callToolTimeoutMs,
+        eventBus: deps.eventBus,
+        stdioDefaultConcurrency: deps.stdioDefaultConcurrency,
+        httpDefaultConcurrency: deps.httpDefaultConcurrency,
+    });
+    try {
+        // Filter to enabled servers only, dedup by name (keep first occurrence)
+        const seen = new Set();
+        const enabledServers = servers.filter((s) => {
+            if (!s.enabled)
+                return false;
+            if (seen.has(s.name)) {
+                logger.warn({ serverName: s.name, hint: "Remove duplicate entry from integrations.mcp.servers config", errorKind: "validation" }, "Skipping duplicate MCP server name");
+                return false;
+            }
+            seen.add(s.name);
+            return true;
+        });
+        if (enabledServers.length === 0) {
+            logger.debug("No MCP servers configured or all disabled");
+            return { mcpClientManager: manager };
+        }
+        logger.info({ serverCount: enabledServers.length, serverNames: enabledServers.map((s) => s.name) }, "Connecting to MCP servers");
+        // Connect to all servers in parallel — failures are isolated per-server
+        const results = await Promise.allSettled(enabledServers.map(async (server) => {
+            if (server.transport === "sse") {
+                logger.warn({
+                    serverName: server.name,
+                    hint: 'Consider migrating transport from "sse" to "http" for Streamable HTTP servers. '
+                        + 'Use "sse" only for legacy servers that require the Server-Sent Events protocol.',
+                    errorKind: "validation",
+                }, 'MCP server uses deprecated "sse" transport');
+            }
+            if (server.transport === "stdio" && server.headers && Object.keys(server.headers).length > 0) {
+                logger.warn({
+                    serverName: server.name,
+                    hint: "Custom headers are ignored for stdio transport. Headers are only used with remote transports (sse, http).",
+                    errorKind: "validation",
+                }, "Headers configured for stdio transport (ignored)");
+            }
+            const cwd = server.cwd ?? resolveDefaultMcpCwd(deps.defaultCwd, server.name, logger);
+            const config = {
+                name: server.name,
+                transport: server.transport,
+                command: server.command,
+                args: server.args,
+                url: server.url,
+                env: server.env,
+                headers: server.headers,
+                ...(cwd ? { cwd } : {}),
+                ...(server.maxConcurrency ? { maxConcurrency: server.maxConcurrency } : {}),
+                enabled: true,
+            };
+            return { server, result: await manager.connect(config) };
+        }));
+        let connectedCount = 0;
+        let failedCount = 0;
+        for (const settled of results) {
+            if (settled.status === "rejected") {
+                // Unexpected rejection (should not happen since connect returns Result, but defensive)
+                failedCount++;
+                logger.warn({
+                    err: settled.reason instanceof Error ? settled.reason.message : String(settled.reason),
+                    hint: "Unexpected MCP connection error; check server configuration",
+                    errorKind: "dependency",
+                }, "MCP server connection rejected unexpectedly");
+                continue;
+            }
+            const { server, result } = settled.value;
+            if (result.ok) {
+                connectedCount++;
+                logger.info({
+                    serverName: server.name,
+                    transport: server.transport,
+                    toolCount: result.value.tools.length,
+                    toolNames: result.value.tools.map((t) => t.name),
+                }, `MCP server "${server.name}" connected with ${result.value.tools.length} tool(s)`);
+            }
+            else {
+                failedCount++;
+                logger.warn({
+                    serverName: server.name,
+                    transport: server.transport,
+                    err: result.error.message,
+                    hint: `Check MCP server "${server.name}" configuration (command, args, url)`,
+                    errorKind: "dependency",
+                }, `MCP server "${server.name}" connection failed`);
+            }
+        }
+        const totalTools = manager.getTools().length;
+        logger.info({ connectedCount, failedCount, totalTools }, `MCP setup complete: ${connectedCount} connected, ${failedCount} failed, ${totalTools} tool(s) available`);
+        return { mcpClientManager: manager };
+    }
+    catch (error) {
+        // Top-level safety net: MCP iteration failures must NEVER crash the daemon.
+        // The manager itself was constructed above the try-block, so runtime
+        // `mcp.connect` RPCs still work — we just lost the pre-configured servers.
+        logger.error({
+            err: error instanceof Error ? error.message : String(error),
+            hint: "MCP subsystem failed mid-setup; daemon continues with the client manager but no pre-configured servers",
+            errorKind: "dependency",
+        }, "MCP setup failed during server iteration");
+        return { mcpClientManager: manager };
+    }
+}

package/node_modules/@comis/daemon/dist/wiring/setup-media.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Media services setup: ffmpeg detection, temp directory, concurrency
+ * semaphore, audio converter, TTS provider, vision provider registry,
+ * and link understanding runner.
+ * Extracted from daemon.ts steps 6.6.8 through 6.6.8.2 to isolate media
+ * service initialization from the main wiring sequence.
+ * @module
+ */
+import type { AppContainer, TTSPort, TranscriptionPort, VisionProvider, FileExtractionPort, WrapExternalContentOptions } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import { type LinkRunner, type FfmpegCapabilities, type MediaTempManager, type MediaSemaphore, type AudioConverter, type SsrfGuardedFetcher } from "@comis/skills";
+/** All services produced by the media setup phase. */
+export interface MediaResult {
+    /** Text-to-speech adapter (optional -- config/key may be missing). */
+    ttsAdapter?: TTSPort;
+    /** Vision provider registry keyed by provider name (optional). */
+    visionRegistry?: Map<string, VisionProvider>;
+    /** Link understanding pipeline runner. */
+    linkRunner: LinkRunner;
+    /** FFmpeg/ffprobe detection result from startup. */
+    ffmpegCapabilities: FfmpegCapabilities;
+    /** Managed temp directory for media scratch files. */
+    mediaTempManager: MediaTempManager;
+    /** Global concurrency limiter for media operations. */
+    mediaSemaphore: MediaSemaphore;
+    /** Audio converter -- only created if ffmpeg is available. */
+    audioConverter?: AudioConverter;
+    /** Speech-to-text transcriber (optional -- config/key may be missing). */
+    transcriber?: TranscriptionPort;
+    /** SSRF-guarded HTTP fetch utility for safe remote media downloads. */
+    ssrfFetcher: SsrfGuardedFetcher;
+    /** File extractor for document attachment processing (optional -- disabled by config). */
+    fileExtractor?: FileExtractionPort;
+}
+/**
+ * Create media services: ffmpeg detection, temp directory with cleanup,
+ * concurrency semaphore, audio converter, TTS provider (factory selects
+ * by config), vision provider registry (auto-discover by API key), and
+ * link understanding runner (detect, fetch, format pipeline).
+ * @param deps.container    - Bootstrap output (config, event bus, secret manager)
+ * @param deps.skillsLogger - Module-bound logger for skills subsystem
+ */
+export declare function setupMedia(deps: {
+    container: AppContainer;
+    skillsLogger: ComisLogger;
+    /** Optional callback for suspicious content detection */
+    onSuspiciousContent?: WrapExternalContentOptions["onSuspiciousContent"];
+}): Promise<MediaResult>;

package/node_modules/@comis/daemon/dist/wiring/setup-media.js

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Media services setup: ffmpeg detection, temp directory, concurrency
+ * semaphore, audio converter, TTS provider, vision provider registry,
+ * and link understanding runner.
+ * Extracted from daemon.ts steps 6.6.8 through 6.6.8.2 to isolate media
+ * service initialization from the main wiring sequence.
+ * @module
+ */
+import { createTTSProvider, createSTTProvider, createFallbackTranscription, createVisionProviderRegistry, selectVisionProvider, createLinkRunner, detectFfmpeg, createMediaTempManager, createMediaSemaphore, createAudioConverter, createSsrfGuardedFetcher, createFileExtractor, createPdfExtractor, createCompositeFileExtractor, createPdfPageRenderer, } from "@comis/skills";
+// ---------------------------------------------------------------------------
+// Setup function
+// ---------------------------------------------------------------------------
+/**
+ * Create media services: ffmpeg detection, temp directory with cleanup,
+ * concurrency semaphore, audio converter, TTS provider (factory selects
+ * by config), vision provider registry (auto-discover by API key), and
+ * link understanding runner (detect, fetch, format pipeline).
+ * @param deps.container    - Bootstrap output (config, event bus, secret manager)
+ * @param deps.skillsLogger - Module-bound logger for skills subsystem
+ */
+export async function setupMedia(deps) {
+    const { container, skillsLogger } = deps;
+    const mediaConfig = container.config.integrations.media;
+    // 6.6.8.pre1. ffmpeg/ffprobe availability detection
+    const ffmpegCapabilities = await detectFfmpeg();
+    // Log each binary separately per user decision (not a single combined message)
+    if (!ffmpegCapabilities.ffmpegAvailable) {
+        skillsLogger.warn({
+            hint: "Install ffmpeg for audio format conversion (voice messages will pass through raw without conversion)",
+            errorKind: "dependency",
+        }, "ffmpeg not found — media conversion disabled");
+    }
+    else {
+        skillsLogger.debug({ version: ffmpegCapabilities.ffmpegVersion }, "ffmpeg detected");
+    }
+    if (!ffmpegCapabilities.ffprobeAvailable) {
+        skillsLogger.warn({
+            hint: "Install ffprobe for audio codec verification and duration extraction (falling back to music-metadata)",
+            errorKind: "dependency",
+        }, "ffprobe not found — codec verification disabled");
+    }
+    else {
+        skillsLogger.debug({ version: ffmpegCapabilities.ffprobeVersion }, "ffprobe detected");
+    }
+    // 6.6.8.pre2. Managed temp directory
+    const infraConfig = mediaConfig.infrastructure;
+    const mediaTempManager = createMediaTempManager({
+        ttlMs: infraConfig.tempFileTtlMs,
+        cleanupIntervalMs: infraConfig.tempCleanupIntervalMs,
+    }, skillsLogger);
+    const initResult = await mediaTempManager.init();
+    if (initResult.ok) {
+        mediaTempManager.startCleanupInterval();
+        skillsLogger.debug({
+            managedDir: mediaTempManager.getManagedDir(),
+            ttlMs: infraConfig.tempFileTtlMs,
+            cleanupIntervalMs: infraConfig.tempCleanupIntervalMs,
+        }, "Media temp directory initialized");
+    }
+    else {
+        skillsLogger.warn({
+            err: initResult.error.message,
+            hint: "Media temp directory creation failed — file-based media operations may fail",
+            errorKind: "resource",
+        }, "Media temp directory initialization failed");
+    }
+    // 6.6.8.pre3. Concurrency semaphore
+    const mediaSemaphore = createMediaSemaphore(infraConfig.concurrencyLimit);
+    skillsLogger.debug({ concurrencyLimit: infraConfig.concurrencyLimit }, "Media concurrency semaphore initialized");
+    // 6.6.8.pre4. AudioConverter — only if ffmpeg available
+    let audioConverter;
+    if (ffmpegCapabilities.ffmpegAvailable) {
+        audioConverter = createAudioConverter({ logger: skillsLogger });
+        skillsLogger.debug("Audio converter initialized");
+    }
+    // 6.6.8.pre4.5. SSRF-guarded fetcher — safe remote media downloads
+    const ssrfFetcher = createSsrfGuardedFetcher({ maxBytes: infraConfig.maxRemoteFetchBytes }, skillsLogger);
+    skillsLogger.debug({ maxBytes: infraConfig.maxRemoteFetchBytes }, "SSRF-guarded fetcher initialized");
+    // 6.6.8.pre5. STT provider — factory selects from config
+    let transcriber;
+    const sttResult = createSTTProvider(mediaConfig.transcription, container.secretManager);
+    if (sttResult.ok) {
+        // Build fallback chain if configured
+        const fallbackProviders = [];
+        for (const fbProvider of mediaConfig.transcription.fallbackProviders) {
+            const fbConfig = { ...mediaConfig.transcription, provider: fbProvider };
+            const fbResult = createSTTProvider(fbConfig, container.secretManager);
+            if (fbResult.ok)
+                fallbackProviders.push(fbResult.value);
+        }
+        if (fallbackProviders.length > 0) {
+            transcriber = createFallbackTranscription([sttResult.value, ...fallbackProviders], skillsLogger);
+            skillsLogger.info({
+                provider: mediaConfig.transcription.provider,
+                fallbackCount: fallbackProviders.length,
+            }, "STT service initialized with fallback chain");
+        }
+        else {
+            transcriber = sttResult.value;
+            skillsLogger.info({ provider: mediaConfig.transcription.provider }, "STT service initialized");
+        }
+    }
+    else {
+        skillsLogger.warn({
+            err: sttResult.error.message,
+            hint: "Configure STT provider in integrations.media.transcription section",
+            errorKind: "config",
+        }, "STT service not configured");
+    }
+    // 6.6.8. TTS adapter — factory selects provider from config
+    let ttsAdapter;
+    const ttsResult = createTTSProvider(mediaConfig.tts, container.secretManager);
+    if (ttsResult.ok) {
+        ttsAdapter = ttsResult.value;
+        skillsLogger.debug({ provider: mediaConfig.tts.provider }, "TTS service initialized");
+    }
+    else {
+        skillsLogger.warn({ err: ttsResult.error.message, hint: "Configure TTS provider in integrations.media.tts section", errorKind: "config" }, "TTS service not configured");
+    }
+    // 6.6.8.1. Vision provider registry — auto-discover providers by API key
+    // Service creation decoupled from vision.enabled flag:
+    // Registry always created when API keys are valid so on-demand tools
+    // (describe_image, describe_video) can use it even when auto-preprocessing is off.
+    let visionRegistry;
+    {
+        const registry = createVisionProviderRegistry({
+            secretManager: container.secretManager,
+            config: mediaConfig.vision,
+        });
+        if (registry.size > 0) {
+            visionRegistry = registry;
+            skillsLogger.debug({ providers: [...registry.keys()], autoEnabled: mediaConfig.vision.enabled }, "Vision provider registry initialized");
+        }
+        else {
+            skillsLogger.debug("No vision providers configured (no API keys found)");
+        }
+    }
+    // 6.6.8.2. Link understanding runner — detect, fetch, format pipeline
+    const linkRunner = createLinkRunner({
+        config: mediaConfig.linkUnderstanding,
+        logger: skillsLogger,
+        onSuspiciousContent: deps.onSuspiciousContent,
+    });
+    if (mediaConfig.linkUnderstanding.enabled) {
+        skillsLogger.debug("Link understanding pipeline enabled");
+    }
+    // 6.6.8.3. File extractor -- text + PDF document extraction
+    // Service creation decoupled from documentExtraction.enabled flag:
+    // Extractor always created so on-demand tools (extract_document) can use it
+    // even when auto-preprocessing is off.
+    const docExtractionConfig = mediaConfig.documentExtraction;
+    let fileExtractor;
+    {
+        const textExtractor = createFileExtractor({
+            config: docExtractionConfig,
+            logger: skillsLogger,
+        });
+        // Wire vision provider and page renderer for PDF image fallback
+        let pdfVisionProvider;
+        let pdfPageRenderer;
+        if (docExtractionConfig.pdfImageFallback && visionRegistry) {
+            const selected = selectVisionProvider(visionRegistry, "image");
+            if (selected) {
+                pdfVisionProvider = selected;
+                pdfPageRenderer = createPdfPageRenderer({ logger: skillsLogger });
+                skillsLogger.debug({ provider: selected.id }, "PDF image fallback enabled with vision provider");
+            }
+            else {
+                skillsLogger.warn({
+                    hint: "Enable a vision provider (OpenAI, Anthropic, or Google) with an API key to use PDF image fallback",
+                    errorKind: "config",
+                }, "PDF image fallback enabled but no vision provider available");
+            }
+        }
+        const pdfExtractor = createPdfExtractor({
+            config: docExtractionConfig,
+            logger: skillsLogger,
+            visionProvider: pdfVisionProvider,
+            pdfPageRenderer,
+        });
+        fileExtractor = createCompositeFileExtractor({
+            textExtractor,
+            pdfExtractor,
+        });
+        skillsLogger.debug({ supportedMimes: fileExtractor.supportedMimes.length, autoEnabled: docExtractionConfig.enabled }, "File extractor initialized");
+    }
+    return {
+        ttsAdapter, visionRegistry, linkRunner,
+        ffmpegCapabilities, mediaTempManager, mediaSemaphore, audioConverter,
+        transcriber, ssrfFetcher, fileExtractor,
+    };
+}

package/node_modules/@comis/daemon/dist/wiring/setup-memory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Memory and embedding subsystem setup: embedding provider, caching,
+ * SQLite memory adapter, fingerprint-based reindexing, background batch
+ * indexing, session store, memory API, and embedding queue.
+ * Extracted from daemon.ts steps 6.5 through 6.5.4 plus session store
+ * and memory API creation to isolate the most complex independent
+ * subsystem from the main wiring sequence.
+ * @module
+ */
+import type { AppContainer, EmbeddingPort } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import { SqliteMemoryAdapter, createSessionStore, createEmbeddingQueue, type MemoryApi } from "@comis/memory";
+/** All services produced by the memory/embedding setup phase. */
+export interface MemoryResult {
+    /** Dispose callback for embedding cache chain: L1 -> L2 -> provider. */
+    disposeEmbedding?: () => Promise<void>;
+    /** Cached embedding provider wrapper (optional). */
+    cachedPort?: EmbeddingPort;
+    /** SQLite memory adapter with FTS5 + vector search. */
+    memoryAdapter: SqliteMemoryAdapter;
+    /** Raw better-sqlite3 database handle (needed for shutdown close + startup banner). */
+    db: ReturnType<SqliteMemoryAdapter["getDb"]>;
+    /** Session persistence store. */
+    sessionStore: ReturnType<typeof createSessionStore>;
+    /** High-level memory query/store API. */
+    memoryApi: MemoryApi;
+    /** Background embedding queue for new entries (optional). */
+    embeddingQueue?: ReturnType<typeof createEmbeddingQueue>;
+    /** Background indexing promise for shutdown coordination (optional). */
+    backgroundIndexingPromise?: Promise<unknown>;
+    /** Embedding cache stats accessor for memory.embeddingCache RPC */
+    embeddingCacheStats?: () => import("@comis/memory").EmbeddingCacheStats;
+    /** Embedding circuit breaker state accessor for memory persistence operations. */
+    embeddingCircuitBreakerState?: () => import("@comis/agent").CircuitState;
+}
+/**
+ * Wraps an EmbeddingPort with a circuit breaker that blocks calls when the
+ * provider has failed repeatedly. Cache layers sit above this decorator so
+ * cache hits bypass the breaker entirely.
+ * @param inner  - The raw embedding provider to protect
+ * @param cb     - A CircuitBreaker instance (threshold + reset already configured)
+ * @param logger - Logger for diagnostics (unused in hot path to avoid log spam)
+ */
+export declare function createEmbeddingCircuitBreaker(inner: EmbeddingPort, cb: import("@comis/agent").CircuitBreaker, logger: ComisLogger): EmbeddingPort;
+/**
+ * Create the full memory and embedding subsystem: embedding provider with
+ * auto-selection (local-first, remote fallback), caching, SQLite memory
+ * adapter with adjusted dimensions, fingerprint-based reindexing, background
+ * batch indexing for startup, session store, memory API, and embedding queue.
+ * @param deps.container    - Bootstrap output (config, event bus, secret manager)
+ * @param deps.memoryLogger - Module-bound logger for memory subsystem
+ */
+export declare function setupMemory(deps: {
+    container: AppContainer;
+    memoryLogger: ComisLogger;
+}): Promise<MemoryResult>;