@tenex-chat/backend 0.9.1

package/src/llm/FinishHandler.ts

@@ -0,0 +1,250 @@
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import type {
+    StepResult,
+    StreamTextOnFinishCallback,
+} from "ai";
+import type { EventEmitter } from "tseep";
+import { PROVIDER_IDS } from "./providers/provider-ids";
+import { getInvalidToolCalls } from "./utils/tool-errors";
+import { extractUsageMetadata, extractOpenRouterGenerationId } from "./providers/usage-metadata";
+import type { LLMServiceEventMap } from "./types";
+
+export interface FinishHandlerConfig {
+    provider: string;
+    model: string;
+    getModelContextWindow: () => number | undefined;
+}
+
+export interface FinishHandlerState {
+    getCachedContent: () => string;
+    clearCachedContent: () => void;
+    getLastUserMessage: () => string | undefined;
+    clearLastUserMessage: () => void;
+}
+
+/**
+ * Creates the onFinish handler for LLM streaming.
+ * Extracted from LLMService to reduce file size.
+ */
+export function createFinishHandler(
+    emitter: EventEmitter<LLMServiceEventMap>,
+    config: FinishHandlerConfig,
+    state: FinishHandlerState
+): StreamTextOnFinishCallback<Record<string, AISdkTool>> {
+    return async (e) => {
+        const onFinishStartTime = Date.now();
+        const activeSpan = trace.getActiveSpan();
+
+        // DIAGNOSTIC: Track onFinish lifecycle for debugging race conditions
+        activeSpan?.addEvent("llm.onFinish_started", {
+            "onFinish.start_time": onFinishStartTime,
+            "onFinish.finish_reason": e.finishReason,
+            "onFinish.steps_count": e.steps.length,
+            "onFinish.text_length": e.text?.length ?? 0,
+            "onFinish.cached_content_length": state.getCachedContent().length,
+        });
+
+        try {
+            recordInvalidToolCalls(e.steps, "response", config.model, config.provider);
+
+            // For streaming, use cached content if available.
+            // When cachedContentForComplete is empty but e.text has content, it means:
+            // - Content was already published as conversation event(s) via chunk-type-change
+            // - BUT we still need to re-publish it in the completion event for delegations
+            // This creates intentional duplication (conversation + completion both have same text)
+            // but ensures delegated agents receive the full response via p-tag on completion.
+            //
+            // Three-level fallback for finalMessage:
+            // 1. Use cachedContent if available (normal case)
+            // 2. Use e.text if cachedContent is empty AND e.text is non-empty (fallback when content was already published)
+            // 3. Use error message if both are empty (edge case where no content was captured)
+            const ERROR_FALLBACK_MESSAGE =
+                "There was an error capturing the work done, please review the conversation for the results";
+
+            const cachedContent = state.getCachedContent();
+            const text = e.text ?? "";
+
+            const fallbackLevel =
+                cachedContent.length > 0 ? "cached" :
+                text.length > 0 ? "text" :
+                "error";
+
+            const finalMessage =
+                fallbackLevel === "cached" ? cachedContent :
+                fallbackLevel === "text" ? text :
+                ERROR_FALLBACK_MESSAGE;
+
+            const usedFallbackToText = fallbackLevel === "text";
+            const usedErrorFallback = fallbackLevel === "error";
+
+            emitSessionCapturedFromMetadata(
+                emitter,
+                config.provider,
+                e.providerMetadata as Record<string, unknown> | undefined,
+                false
+            );
+
+            // Capture OpenRouter generation ID for trace correlation
+            const openrouterGenerationId = extractOpenRouterGenerationId(
+                e.providerMetadata as Record<string, unknown> | undefined
+            );
+            if (openrouterGenerationId) {
+                activeSpan?.setAttribute("openrouter.generation_id", openrouterGenerationId);
+            }
+
+            // Extract usage metadata using provider-specific extractor
+            const usage = extractUsageMetadata(
+                config.provider,
+                config.model,
+                e.totalUsage,
+                e.providerMetadata as Record<string, unknown> | undefined
+            );
+
+            // DIAGNOSTIC: Log right before emitting complete event
+            const beforeEmitTime = Date.now();
+            activeSpan?.addEvent("llm.complete_will_emit", {
+                "complete.message_length": finalMessage.length,
+                "complete.cached_content_length": cachedContent.length,
+                "complete.e_text_length": text.length,
+                "complete.used_fallback_to_e_text": usedFallbackToText,
+                "complete.used_error_fallback": usedErrorFallback,
+                "complete.usage_input_tokens": usage.inputTokens,
+                "complete.usage_output_tokens": usage.outputTokens,
+                "complete.finish_reason": e.finishReason,
+                "complete.ms_since_onFinish_start": beforeEmitTime - onFinishStartTime,
+            });
+
+            emitter.emit("complete", {
+                message: finalMessage,
+                steps: e.steps,
+                usage: {
+                    ...usage,
+                    contextWindow: config.getModelContextWindow(),
+                },
+                finishReason: e.finishReason,
+            });
+
+            // DIAGNOSTIC: Log after emitting complete event
+            const afterEmitTime = Date.now();
+            activeSpan?.addEvent("llm.complete_did_emit", {
+                "complete.emit_duration_ms": afterEmitTime - beforeEmitTime,
+                "complete.total_onFinish_duration_ms": afterEmitTime - onFinishStartTime,
+            });
+
+            // Log the user prompt so we can see what the LLM was answering to
+            const lastUserMessage = state.getLastUserMessage();
+            if (lastUserMessage) {
+                const truncatedPrompt = lastUserMessage.length > 2000
+                    ? lastUserMessage.substring(0, 2000) + "... [truncated]"
+                    : lastUserMessage;
+                activeSpan?.addEvent("llm.prompt", {
+                    "prompt.text": truncatedPrompt,
+                    "prompt.full_length": lastUserMessage.length,
+                    "prompt.truncated": lastUserMessage.length > 2000,
+                });
+            }
+
+            // Log the actual response text so it shows up in Jaeger's Logs section
+            // This makes it much easier to see what the LLM actually generated
+            if (e.text) {
+                // Truncate to avoid massive log entries (OTel has limits)
+                const truncatedText = e.text.length > 4000
+                    ? e.text.substring(0, 4000) + "... [truncated]"
+                    : e.text;
+                activeSpan?.addEvent("llm.response", {
+                    "response.text": truncatedText,
+                    "response.full_length": e.text.length,
+                    "response.truncated": e.text.length > 4000,
+                });
+            }
+
+            // Clear cached content after use
+            state.clearCachedContent();
+            state.clearLastUserMessage();
+        } catch (error) {
+            const errorTime = Date.now();
+            activeSpan?.addEvent("llm.onFinish_error", {
+                "error.message": error instanceof Error ? error.message : String(error),
+                "error.type": error instanceof Error ? error.constructor.name : typeof error,
+                "error.ms_since_onFinish_start": errorTime - onFinishStartTime,
+            });
+            logger.error("[LLMService] Error in onFinish handler", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    };
+}
+
+/**
+ * Record invalid tool calls to the active span
+ */
+function recordInvalidToolCalls(
+    steps: StepResult<Record<string, AISdkTool>>[],
+    logContext: "complete" | "response",
+    model: string,
+    provider: string
+): void {
+    const activeSpan = trace.getActiveSpan();
+    if (!activeSpan) {
+        return;
+    }
+
+    const invalidToolCalls = getInvalidToolCalls(steps);
+    if (invalidToolCalls.length === 0) {
+        return;
+    }
+
+    const logSuffix = logContext === "complete" ? "complete()" : "response";
+
+    activeSpan.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: `Invalid tool calls: ${invalidToolCalls.map((tc) => tc.toolName).join(", ")}`,
+    });
+    activeSpan.setAttribute("error", true);
+    activeSpan.setAttribute("error.type", "AI_InvalidToolCall");
+    activeSpan.setAttribute("error.invalid_tool_count", invalidToolCalls.length);
+    activeSpan.setAttribute(
+        "error.invalid_tools",
+        invalidToolCalls.map((tc) => tc.toolName).join(", ")
+    );
+
+    for (const invalidTool of invalidToolCalls) {
+        activeSpan.addEvent("invalid_tool_call", {
+            "tool.name": invalidTool.toolName,
+            "error.type": invalidTool.error,
+        });
+    }
+
+    logger.error(`[LLMService] Invalid tool calls detected in ${logSuffix}`, {
+        invalidToolCalls,
+        model,
+        provider,
+    });
+}
+
+/**
+ * Emit session-captured event from provider metadata
+ */
+function emitSessionCapturedFromMetadata(
+    emitter: EventEmitter<LLMServiceEventMap>,
+    provider: string,
+    providerMetadata: Record<string, unknown> | undefined,
+    recordSpanEvent: boolean
+): void {
+    if (provider === PROVIDER_IDS.CODEX_APP_SERVER) {
+        const sessionId = (
+            providerMetadata?.[PROVIDER_IDS.CODEX_APP_SERVER] as { sessionId?: string } | undefined
+        )?.sessionId;
+        if (sessionId) {
+            if (recordSpanEvent) {
+                trace.getActiveSpan()?.addEvent("llm.session_captured", {
+                    "session.id": sessionId,
+                });
+            }
+            emitter.emit("session-captured", { sessionId });
+        }
+    }
+}

package/src/llm/LLMConfigEditor.ts

@@ -0,0 +1,154 @@
+import { config } from "@/services/ConfigService";
+import type { TenexLLMs } from "@/services/config/types";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { llmServiceFactory } from "./LLMServiceFactory";
+import { ConfigurationManager } from "./utils/ConfigurationManager";
+import { ConfigurationTester } from "./utils/ConfigurationTester";
+import { ProviderConfigUI } from "./utils/ProviderConfigUI";
+import { runProviderSetup } from "./utils/provider-setup";
+
+/**
+ * Internal type used by editor to work with providers
+ * Merges providers with llms for internal convenience
+ */
+type LLMConfigWithProviders = TenexLLMs & {
+    providers: Record<string, { apiKey: string | string[] }>;
+};
+
+/**
+ * LLM Configuration Editor - Simple menu orchestrator
+ * Note: LLM configs are now global only (no project-level llms.json)
+ */
+export class LLMConfigEditor {
+    constructor() {}
+
+    async showMainMenu(): Promise<void> {
+        const llmsConfig = await this.loadConfig();
+
+        console.log(chalk.cyan("\n=== LLM Configuration ===\n"));
+        ProviderConfigUI.displayCurrentConfig(llmsConfig);
+
+        const { action } = await inquirer.prompt([
+            {
+                type: "select",
+                name: "action",
+                message: "What would you like to do?",
+                choices: [
+                    { name: "Add new configuration", value: "add" },
+                    { name: "Create meta model", value: "addMeta" },
+                    { name: "Delete configuration", value: "delete" },
+                    {
+                        name: `Default agents' model: ${llmsConfig.default || "none"}`,
+                        value: "default",
+                    },
+                    {
+                        name: `Summarization model: ${llmsConfig.summarization || "none"}`,
+                        value: "summarization",
+                    },
+                    {
+                        name: `Supervision model: ${llmsConfig.supervision || "none"}`,
+                        value: "supervision",
+                    },
+                    {
+                        name: `Search model: ${llmsConfig.search || "none"}`,
+                        value: "search",
+                    },
+                    {
+                        name: `Prompt compilation model: ${llmsConfig.promptCompilation || "none"}`,
+                        value: "promptCompilation",
+                    },
+                    {
+                        name: `Compression model: ${llmsConfig.compression || "none"}`,
+                        value: "compression",
+                    },
+                    { name: "Test configuration", value: "test" },
+                    { name: "Exit", value: "exit" },
+                ],
+            },
+        ]);
+
+        if (action === "exit") process.exit(0);
+
+        if (action === "test") {
+            await ConfigurationTester.test(llmsConfig);
+        } else {
+            // All other actions use ConfigurationManager
+            if (action === "add") await ConfigurationManager.add(llmsConfig);
+            if (action === "addMeta") await ConfigurationManager.addMetaModel(llmsConfig);
+            if (action === "delete") await ConfigurationManager.delete(llmsConfig);
+            if (action === "default") await ConfigurationManager.setDefault(llmsConfig);
+            if (action === "summarization") await ConfigurationManager.setSummarizationModel(llmsConfig);
+            if (action === "supervision") await ConfigurationManager.setSupervisionModel(llmsConfig);
+            if (action === "search") await ConfigurationManager.setSearchModel(llmsConfig);
+            if (action === "promptCompilation") await ConfigurationManager.setPromptCompilationModel(llmsConfig);
+            if (action === "compression") await ConfigurationManager.setCompressionModel(llmsConfig);
+            await this.saveConfig(llmsConfig);
+        }
+
+        await this.showMainMenu();
+    }
+
+    async runOnboardingFlow(): Promise<void> {
+        console.log(chalk.green("\n🚀 Welcome to TENEX LLM Setup!\n"));
+
+        const llmsConfig = await this.loadConfig();
+        const globalPath = config.getGlobalPath();
+
+        // Step 1: Configure providers
+        console.log(chalk.cyan("Step 1: Configure Provider API Keys"));
+        const existingProviders = await config.loadTenexProviders(globalPath);
+        const updatedProviders = await runProviderSetup(existingProviders);
+        llmsConfig.providers = updatedProviders.providers;
+        await this.saveConfig(llmsConfig);
+
+        // Step 2: Create first configuration
+        console.log(chalk.cyan("\nStep 2: Create Your First Configuration"));
+        await ConfigurationManager.add(llmsConfig, true);
+        await this.saveConfig(llmsConfig);
+
+        // Step 3: Offer to test
+        const { shouldTest } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "shouldTest",
+                message: "Would you like to test your configuration?",
+                default: true,
+            },
+        ]);
+
+        if (shouldTest) {
+            await ConfigurationTester.test(llmsConfig);
+        }
+
+        console.log(chalk.green("\n✅ LLM configuration complete!"));
+    }
+
+    private async loadConfig(): Promise<LLMConfigWithProviders> {
+        const globalPath = config.getGlobalPath();
+
+        // Load providers and llms separately
+        const providersConfig = await config.loadTenexProviders(globalPath);
+        const llmsConfig = await config.loadTenexLLMs(globalPath);
+
+        // Merge for internal editor use
+        return {
+            ...llmsConfig,
+            providers: providersConfig.providers,
+        };
+    }
+
+    private async saveConfig(llmsConfig: LLMConfigWithProviders): Promise<void> {
+        // Split providers and llms for separate storage
+        const { providers, ...llmsWithoutProviders } = llmsConfig;
+
+        // Save providers to providers.json
+        await config.saveGlobalProviders({ providers });
+
+        // Save llms to llms.json
+        await config.saveGlobalLLMs(llmsWithoutProviders as TenexLLMs);
+
+        // Re-initialize factory with updated providers
+        await llmServiceFactory.initializeProviders(providers);
+    }
+}

package/src/llm/LLMServiceFactory.ts

@@ -0,0 +1,230 @@
+/**
+ * LLM Service Factory
+ *
+ * Factory for creating LLM services with proper provider initialization.
+ * This module provides a simplified interface that delegates to the
+ * modular ProviderRegistry for actual provider management.
+ *
+ * @see src/llm/providers for individual provider implementations
+ */
+
+import type { LLMConfiguration } from "@/services/config/types";
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import type { LanguageModel, ProviderRegistryProvider } from "ai";
+import type { ClaudeCodeSettings } from "ai-sdk-provider-claude-code";
+
+import { LLMService } from "./service";
+import {
+    providerRegistry,
+    type MCPConfig,
+    type ProviderPoolConfig,
+    type ProviderRuntimeContext,
+} from "./providers";
+import { PROVIDER_IDS } from "./providers/provider-ids";
+import type { OnStreamStartCallback } from "./types";
+
+/**
+ * Factory for creating LLM services with proper provider initialization
+ *
+ * This factory provides a high-level interface for:
+ * - Initializing providers from configuration
+ * - Creating LLMService instances
+ * - Checking provider availability
+ *
+ * The actual provider management is delegated to the ProviderRegistry.
+ */
+export class LLMServiceFactory {
+    private initialized = false;
+
+    /**
+     * Initialize providers from configuration
+     *
+     * @param providerConfigs Map of provider names to their configurations
+     * @param options Additional options for initialization
+     */
+    async initializeProviders(
+        providerConfigs: Record<string, { apiKey: string | string[] }>
+    ): Promise<void> {
+        // Convert to ProviderPoolConfig format
+        // apiKey can be a single string or an array — KeyManager handles the rest
+        const configs: Record<string, ProviderPoolConfig> = {};
+        for (const [name, config] of Object.entries(providerConfigs)) {
+            const hasKey = Array.isArray(config?.apiKey)
+                ? config.apiKey.length > 0
+                : !!config?.apiKey;
+
+            if (hasKey) {
+                configs[name] = {
+                    apiKey: config.apiKey,
+                };
+            }
+        }
+
+        // Also ensure agent providers are initialized (they don't need API keys).
+        // Add them with empty configs if not already present.
+        const agentProviders = [PROVIDER_IDS.CLAUDE_CODE, PROVIDER_IDS.CODEX_APP_SERVER];
+        for (const providerId of agentProviders) {
+            if (!configs[providerId]) {
+                configs[providerId] = {};
+            }
+        }
+
+        // Initialize through the registry (which has its own tracing span)
+        const results = await providerRegistry.initialize(configs);
+
+        // Log initialization failures
+        const failed = results.filter(r => !r.success);
+        if (failed.length > 0) {
+            for (const f of failed) {
+                logger.error(`[LLMServiceFactory] Failed to initialize provider ${f.providerId}`, {
+                    error: f.error,
+                });
+            }
+        }
+
+        this.initialized = true;
+    }
+
+    /**
+     * Create an LLM service from a resolved configuration
+     *
+     * @param config LLM configuration
+     * @param context Optional runtime context for agents
+     */
+    createService(
+        config: LLMConfiguration,
+        context?: {
+            tools?: Record<string, AISdkTool>;
+            agentName?: string;
+            sessionId?: string;
+            /** Working directory path for agent execution */
+            workingDirectory?: string;
+            /** MCP configuration - passed from services layer to providers */
+            mcpConfig?: MCPConfig;
+            /** Conversation ID for OpenRouter correlation */
+            conversationId?: string;
+            /** Callback invoked when Claude Code stream starts, providing the message injector */
+            onStreamStart?: OnStreamStartCallback;
+        }
+    ): LLMService {
+        if (!this.initialized) {
+            throw new Error("LLMServiceFactory not initialized. Call initializeProviders first.");
+        }
+
+        // Convert agent name to slug format for telemetry
+        const agentSlug = context?.agentName
+            ? context.agentName.toLowerCase().replace(/\s+/g, "-")
+            : undefined;
+
+        // Determine the actual provider (mock mode handling)
+        const actualProvider = process.env.USE_MOCK_LLM === "true" ? "mock" : config.provider;
+
+        // Build the runtime context for the provider
+        const runtimeContext: ProviderRuntimeContext = {
+            tools: context?.tools,
+            agentName: context?.agentName,
+            sessionId: context?.sessionId,
+            workingDirectory: context?.workingDirectory,
+            mcpConfig: context?.mcpConfig,
+            reasoningEffort: (config as { reasoningEffort?: "none" | "low" | "medium" | "high" | "xhigh" }).reasoningEffort,
+            onStreamStart: context?.onStreamStart,
+        };
+
+        // Get the provider from the registry
+        const provider = providerRegistry.getProvider(actualProvider);
+
+        if (!provider) {
+            const available = providerRegistry.getAvailableProviders().map(p => p.id);
+            throw new Error(
+                `Provider "${actualProvider}" not available. ` +
+                `Initialized providers: ${available.length > 0 ? available.join(", ") : "none"}`
+            );
+        }
+
+        // Create the model from the provider
+        const modelResult = provider.createModel(config.model, runtimeContext);
+
+        // Get capabilities from provider metadata
+        const capabilities = provider.metadata.capabilities;
+
+        // For agent providers (claude-code, codex-app-server), use their provider function
+        if (modelResult.bypassRegistry && modelResult.providerFunction) {
+            return new LLMService(
+                null,
+                actualProvider,
+                config.model,
+                capabilities,
+                config.temperature,
+                config.maxTokens,
+                modelResult.providerFunction as (model: string, options?: ClaudeCodeSettings) => LanguageModel,
+                modelResult.agentSettings as ClaudeCodeSettings,
+                context?.sessionId,
+                agentSlug,
+                context?.conversationId
+            );
+        }
+
+        // For standard providers, use the AI SDK registry
+        const registry = providerRegistry.getAiSdkRegistry();
+
+        return new LLMService(
+            registry,
+            actualProvider,
+            config.model,
+            capabilities,
+            config.temperature,
+            config.maxTokens,
+            undefined,
+            undefined,
+            context?.sessionId,
+            agentSlug,
+            context?.conversationId
+        );
+    }
+
+    /**
+     * Check if a provider is available
+     */
+    hasProvider(providerName: string): boolean {
+        return providerRegistry.hasProvider(providerName);
+    }
+
+    /**
+     * Get the AI SDK provider registry
+     * Useful for direct access to language models
+     */
+    getRegistry(): ProviderRegistryProvider {
+        if (!this.initialized) {
+            throw new Error("LLMServiceFactory not initialized. Call initializeProviders first.");
+        }
+        return providerRegistry.getAiSdkRegistry();
+    }
+
+    /**
+     * Get list of available providers
+     */
+    getAvailableProviders(): string[] {
+        return providerRegistry.getAvailableProviders().map(p => p.id);
+    }
+
+    /**
+     * Get list of all registered providers (even if not initialized)
+     */
+    getRegisteredProviders(): string[] {
+        return providerRegistry.getRegisteredProviders().map(p => p.id);
+    }
+
+    /**
+     * Reset the factory (mainly for testing)
+     */
+    reset(): void {
+        providerRegistry.reset();
+        this.initialized = false;
+    }
+}
+
+/**
+ * Export singleton instance
+ */
+export const llmServiceFactory = new LLMServiceFactory();