@tenex-chat/backend 0.9.1

package/src/llm/utils/claudeCodePromptCompiler.ts

@@ -0,0 +1,141 @@
+import type { ModelMessage, TextPart, ImagePart } from "ai";
+
+/**
+ * Extract text content from a message content field.
+ * Handles both string content and multimodal content (TextPart + ImagePart arrays).
+ *
+ * For multimodal content, extracts the text part and notes any images.
+ */
+function extractTextContent(content: ModelMessage["content"]): string {
+    if (typeof content === "string") {
+        return content;
+    }
+
+    if (!Array.isArray(content)) {
+        return JSON.stringify(content);
+    }
+
+    // Handle multimodal content (arrays of parts)
+    const parts: string[] = [];
+    let imageCount = 0;
+
+    for (const part of content) {
+        if ((part as TextPart).type === "text") {
+            parts.push((part as TextPart).text);
+        } else if ((part as ImagePart).type === "image") {
+            imageCount++;
+        }
+    }
+
+    // If there were images, note them at the end
+    if (imageCount > 0) {
+        parts.push(`[${imageCount} image${imageCount > 1 ? "s" : ""} attached]`);
+    }
+
+    return parts.join("\n");
+}
+
+/**
+ * System prompt type for Claude Code.
+ * Can be a string for custom system prompt, or use preset with append for
+ * Claude Code's built-in instructions plus custom content.
+ */
+export type ClaudeCodeSystemPrompt = string | {
+    type: "preset";
+    preset: "claude_code";
+    append?: string;
+};
+
+/**
+ * Compiles system messages for Claude Code's systemPrompt.append.
+ * Uses the new systemPrompt API (replacing deprecated customSystemPrompt/appendSystemPrompt).
+ *
+ * IMPORTANT: Only system messages are included in systemPrompt.append.
+ * User/assistant messages are passed separately via the messages array to streamText().
+ * This separation is critical for session resumption to work correctly - if conversation
+ * history is duplicated in both systemPrompt.append AND messages, it creates a session
+ * state that can't be reconstructed on resume.
+ *
+ * Note: Multimodal content (images) is converted to text descriptions since
+ * Claude Code uses a text-based prompt compilation approach.
+ */
+export function compileMessagesForClaudeCode(messages: ModelMessage[]): {
+    systemPrompt?: ClaudeCodeSystemPrompt;
+} {
+    if (messages.length === 0) {
+        return { systemPrompt: undefined };
+    }
+
+    // Extract only system messages - user/assistant go in messages array
+    const systemMessages = messages.filter((m) => m.role === "system");
+
+    if (systemMessages.length === 0) {
+        return { systemPrompt: undefined };
+    }
+
+    // Combine all system messages into the append content
+    const appendParts: string[] = [];
+
+    for (const msg of systemMessages) {
+        const content =
+            typeof msg.content === "string"
+                ? msg.content
+                : extractTextContent(msg.content);
+        appendParts.push(content);
+    }
+
+    const appendContent = appendParts.join("\n\n");
+
+    // Use Claude Code's built-in preset with our system content appended
+    return {
+        systemPrompt: {
+            type: "preset",
+            preset: "claude_code",
+            append: appendContent,
+        },
+    };
+}
+
+/**
+ * Converts system messages to user messages for active Claude Code sessions.
+ * When resuming a session, Claude Code doesn't receive new system messages,
+ * so we convert them to user messages to ensure they're delivered.
+ *
+ * Note: Multimodal content is preserved for user messages (they support images),
+ * but system messages with multimodal content are converted to text descriptions.
+ */
+export function convertSystemMessagesForResume(messages: ModelMessage[]): ModelMessage[] {
+    // For resuming sessions, we need to convert system messages that appear
+    // after the conversation started into user messages
+
+    // Find the first non-system message (start of conversation)
+    const conversationStartIndex = messages.findIndex((m) => m.role !== "system");
+
+    if (conversationStartIndex === -1) {
+        // All messages are system messages, no conversion needed
+        return messages;
+    }
+
+    // Convert messages, preserving order
+    const convertedMessages = messages.map((msg, index) => {
+        // Keep initial system messages as-is (they were part of initial prompt)
+        if (index < conversationStartIndex) {
+            return msg;
+        }
+
+        // Convert subsequent system messages to user messages with clear marker
+        if (msg.role === "system") {
+            // Use extractTextContent to handle multimodal content gracefully
+            const content = extractTextContent(msg.content);
+            return {
+                role: "user" as const,
+                content: `[System Context]: ${content}`,
+            };
+        }
+
+        // Keep user and assistant messages as-is (preserving multimodal content)
+        return msg;
+    });
+
+    return convertedMessages as ModelMessage[];
+}

package/src/llm/utils/codex-models.ts

@@ -0,0 +1,53 @@
+/**
+ * Codex Model Discovery Utilities
+ *
+ * Provides functions to discover available Codex models and their capabilities,
+ * including supported reasoning effort levels.
+ */
+
+import { listModels } from "ai-sdk-provider-codex-app-server";
+import type { ModelInfo } from "ai-sdk-provider-codex-app-server";
+
+export interface CodexModelOption {
+    id: string;
+    displayName: string;
+    description: string;
+    supportedReasoningEfforts: string[];
+    defaultReasoningEffort: string;
+    isDefault: boolean;
+}
+
+/**
+ * List available Codex models with their reasoning effort options
+ */
+export async function listCodexModels(): Promise<CodexModelOption[]> {
+    const { models } = await listModels();
+
+    return models.map((model: ModelInfo) => ({
+        id: model.id,
+        displayName: model.displayName,
+        description: model.description,
+        supportedReasoningEfforts: model.supportedReasoningEfforts.map(
+            (e) => e.reasoningEffort
+        ),
+        defaultReasoningEffort: model.defaultReasoningEffort,
+        isDefault: model.isDefault,
+    }));
+}
+
+/**
+ * Get the default Codex model
+ */
+export async function getDefaultCodexModel(): Promise<CodexModelOption | undefined> {
+    const models = await listCodexModels();
+    return models.find((m) => m.isDefault);
+}
+
+/**
+ * Format model info for display
+ */
+export function formatCodexModel(model: CodexModelOption): string {
+    const efforts = model.supportedReasoningEfforts.join(", ");
+    const defaultMark = model.isDefault ? " (default)" : "";
+    return `${model.id}${defaultMark}\n  ${model.description}\n  Reasoning: ${efforts} (default: ${model.defaultReasoningEffort})`;
+}

package/src/llm/utils/context-window-cache.ts

@@ -0,0 +1,30 @@
+/**
+ * Context window cache for LLM models
+ * Delegates to models-dev-cache for model metadata
+ */
+
+import { getContextWindowFromModelsdev, clearModelsDevCache } from "./models-dev-cache";
+
+/**
+ * Get context window for a model
+ * Returns undefined if not found
+ */
+export function getContextWindow(provider: string, model: string): number | undefined {
+    return getContextWindowFromModelsdev(provider, model);
+}
+
+/**
+ * Resolve context window for a model (async)
+ * No-op since models-dev-cache handles loading
+ */
+export async function resolveContextWindow(_provider: string, _model: string): Promise<void> {
+    // models-dev-cache loads data at startup via ensureCacheLoaded()
+    // Nothing to do here
+}
+
+/**
+ * Clear the cache (for testing)
+ */
+export function clearCache(): void {
+    clearModelsDevCache();
+}

package/src/llm/utils/models-dev-cache.ts

@@ -0,0 +1,267 @@
+/**
+ * models.dev cache for LLM model metadata
+ *
+ * Fetches model information from https://models.dev/api.json and caches to disk.
+ * Uses stale-while-revalidate: serves cached data immediately, refreshes in background if stale.
+ */
+
+import * as path from "node:path";
+import { ensureDirectory, fileExists, readJsonFile, writeJsonFile, getFileStats } from "@/lib/fs";
+import { config } from "@/services/ConfigService";
+import { logger } from "@/utils/logger";
+
+const MODELS_DEV_API_URL = "https://models.dev/api.json";
+const CACHE_FILE_NAME = "models-dev.json";
+const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Model limits from models.dev
+ */
+export interface ModelLimits {
+    /** Context window size in tokens */
+    context: number;
+    /** Max output tokens */
+    output: number;
+}
+
+/**
+ * models.dev API response structure
+ */
+interface ModelsDevResponse {
+    [provider: string]: {
+        models: {
+            [modelId: string]: {
+                limit?: {
+                    context?: number;
+                    output?: number;
+                };
+            };
+        };
+    };
+}
+
+/**
+ * Cached data structure
+ */
+interface CacheData {
+    fetchedAt: number;
+    data: ModelsDevResponse;
+}
+
+// In-memory cache (loaded from disk)
+let cache: ModelsDevResponse | null = null;
+let cacheLoadPromise: Promise<void> | null = null;
+
+/**
+ * Provider ID mapping from our providers to models.dev providers
+ */
+const PROVIDER_MAPPING: Record<string, string | null> = {
+    anthropic: "anthropic",
+    openai: "openai",
+    openrouter: "openrouter",
+    // These providers are not in models.dev (local/custom)
+    ollama: null,
+    "claude-code": null,
+    "codex-app-server": null,
+};
+
+/**
+ * Get the cache file path
+ */
+function getCacheFilePath(): string {
+    return path.join(config.getConfigPath("cache"), CACHE_FILE_NAME);
+}
+
+/**
+ * Fetch data from models.dev API
+ */
+async function fetchFromApi(): Promise<ModelsDevResponse | null> {
+    try {
+        const response = await fetch(MODELS_DEV_API_URL);
+        if (!response.ok) {
+            logger.warn("Failed to fetch models.dev API", {
+                status: response.status,
+                statusText: response.statusText,
+            });
+            return null;
+        }
+        return (await response.json()) as ModelsDevResponse;
+    } catch (error) {
+        logger.warn("Error fetching models.dev API", { error });
+        return null;
+    }
+}
+
+/**
+ * Load cache from disk
+ */
+async function loadFromDisk(): Promise<CacheData | null> {
+    const cacheFile = getCacheFilePath();
+    if (!(await fileExists(cacheFile))) {
+        return null;
+    }
+    return readJsonFile<CacheData>(cacheFile);
+}
+
+/**
+ * Save cache to disk
+ */
+async function saveToDisk(data: ModelsDevResponse): Promise<void> {
+    const cacheFile = getCacheFilePath();
+    await ensureDirectory(path.dirname(cacheFile));
+    const cacheData: CacheData = {
+        fetchedAt: Date.now(),
+        data,
+    };
+    await writeJsonFile(cacheFile, cacheData);
+}
+
+/**
+ * Check if cache is stale (older than 24 hours)
+ */
+async function isCacheStale(): Promise<boolean> {
+    const cacheFile = getCacheFilePath();
+    const stats = await getFileStats(cacheFile);
+    if (!stats) return true;
+
+    const age = Date.now() - stats.mtimeMs;
+    return age > STALE_THRESHOLD_MS;
+}
+
+/**
+ * Refresh cache from API (runs in background)
+ */
+async function refreshInBackground(): Promise<void> {
+    const freshData = await fetchFromApi();
+    if (freshData) {
+        cache = freshData;
+        await saveToDisk(freshData);
+        logger.debug("models.dev cache refreshed");
+    }
+}
+
+/**
+ * Ensure cache is loaded (call at startup)
+ * Blocks until cache is ready. Fetches from API if no cached data exists.
+ */
+export async function ensureCacheLoaded(): Promise<void> {
+    // If already loading, wait for that
+    if (cacheLoadPromise) {
+        await cacheLoadPromise;
+        return;
+    }
+
+    // If already loaded, check for background refresh
+    if (cache) {
+        if (await isCacheStale()) {
+            // Trigger background refresh, don't wait
+            refreshInBackground().catch((err) =>
+                logger.warn("Background cache refresh failed", { error: err })
+            );
+        }
+        return;
+    }
+
+    // Start loading
+    cacheLoadPromise = (async () => {
+        // Try to load from disk first
+        const diskCache = await loadFromDisk();
+        if (diskCache?.data) {
+            cache = diskCache.data;
+            logger.debug("models.dev cache loaded from disk");
+
+            // Check if stale and trigger background refresh
+            if (await isCacheStale()) {
+                refreshInBackground().catch((err) =>
+                    logger.warn("Background cache refresh failed", { error: err })
+                );
+            }
+            return;
+        }
+
+        // No cache on disk, fetch from API
+        logger.debug("models.dev cache not found, fetching from API");
+        const freshData = await fetchFromApi();
+        if (freshData) {
+            cache = freshData;
+            await saveToDisk(freshData);
+            logger.debug("models.dev cache fetched and saved");
+        } else {
+            logger.warn("Could not load models.dev data - model limits will be unavailable");
+        }
+    })();
+
+    try {
+        await cacheLoadPromise;
+    } finally {
+        cacheLoadPromise = null;
+    }
+}
+
+/**
+ * Force refresh cache from API
+ */
+export async function refreshCache(): Promise<void> {
+    const freshData = await fetchFromApi();
+    if (freshData) {
+        cache = freshData;
+        await saveToDisk(freshData);
+        logger.info("models.dev cache force refreshed");
+    } else {
+        throw new Error("Failed to refresh models.dev cache");
+    }
+}
+
+/**
+ * Get model limits for a specific provider and model
+ *
+ * @param provider Our provider ID (e.g., "anthropic", "openai", "openrouter")
+ * @param model Model ID (e.g., "claude-opus-4-5-20251101", "gpt-4o")
+ * @returns Model limits or undefined if not found/unsupported
+ */
+export function getModelLimits(provider: string, model: string): ModelLimits | undefined {
+    if (!cache) {
+        return undefined;
+    }
+
+    // Map our provider ID to models.dev provider ID
+    const modelsDevProvider = PROVIDER_MAPPING[provider];
+    if (modelsDevProvider === null || modelsDevProvider === undefined) {
+        // Provider not supported by models.dev
+        return undefined;
+    }
+
+    const providerData = cache[modelsDevProvider];
+    if (!providerData?.models) {
+        return undefined;
+    }
+
+    const modelData = providerData.models[model];
+    if (!modelData?.limit) {
+        return undefined;
+    }
+
+    const { context, output } = modelData.limit;
+    if (context === undefined || output === undefined) {
+        return undefined;
+    }
+
+    return { context, output };
+}
+
+/**
+ * Get just the context window for a model
+ * Convenience function for backwards compatibility with context-window-cache
+ */
+export function getContextWindowFromModelsdev(provider: string, model: string): number | undefined {
+    const limits = getModelLimits(provider, model);
+    return limits?.context;
+}
+
+/**
+ * Clear in-memory cache (for testing)
+ */
+export function clearModelsDevCache(): void {
+    cache = null;
+    cacheLoadPromise = null;
+}

package/src/llm/utils/provider-setup.ts

@@ -0,0 +1,50 @@
+import inquirer from "inquirer";
+
+import { AI_SDK_PROVIDERS } from "@/llm/types";
+import type { ProviderCredentials, TenexProviders } from "@/services/config/types";
+import { hasApiKey } from "@/llm/providers/key-manager";
+import { ProviderConfigUI } from "@/llm/utils/ProviderConfigUI";
+
+/**
+ * Interactive flow for configuring provider credentials.
+ * Returns an updated TenexProviders object (merges into the existing map).
+ */
+export async function runProviderSetup(
+    existingProviders: TenexProviders
+): Promise<TenexProviders> {
+    const providers: Record<string, ProviderCredentials> = {
+        ...existingProviders.providers,
+    };
+
+    const choices = AI_SDK_PROVIDERS.map((provider) => {
+        const isConfigured = hasApiKey(providers[provider]?.apiKey);
+        const name = ProviderConfigUI.getProviderDisplayName(provider);
+        return {
+            name: isConfigured ? `${name} (configured)` : name,
+            value: provider,
+        };
+    });
+
+    const { selected } = await inquirer.prompt([
+        {
+            type: "checkbox",
+            name: "selected",
+            message: "Select providers to configure:",
+            choices,
+        },
+    ]);
+
+    if (!selected || selected.length === 0) {
+        return existingProviders;
+    }
+
+    for (const provider of selected) {
+        const providerConfig = await ProviderConfigUI.configureProvider(provider, providers);
+        providers[provider] = {
+            ...providers[provider],
+            apiKey: providerConfig.apiKey,
+        };
+    }
+
+    return { providers };
+}

package/src/llm/utils/tool-errors.ts

@@ -0,0 +1,78 @@
+import type { AISdkTool } from "@/tools/types";
+import type { StepResult } from "ai";
+
+/**
+ * Extract invalid tool calls from step results.
+ * Used to detect and report dynamic tool validation errors.
+ */
+export function getInvalidToolCalls(
+    steps: StepResult<Record<string, AISdkTool>>[]
+): Array<{ toolName: string; error: string }> {
+    const invalidToolCalls: Array<{ toolName: string; error: string }> = [];
+
+    for (const step of steps) {
+        if (step.toolCalls) {
+            for (const toolCall of step.toolCalls) {
+                // Check if this is a dynamic tool call that's invalid
+                if (
+                    "dynamic" in toolCall &&
+                    toolCall.dynamic === true &&
+                    toolCall.invalid === true &&
+                    toolCall.error
+                ) {
+                    const error =
+                        typeof toolCall.error === "object" &&
+                        toolCall.error !== null &&
+                        "name" in toolCall.error
+                            ? (toolCall.error as { name: string }).name
+                            : "Unknown error";
+                    invalidToolCalls.push({
+                        toolName: toolCall.toolName,
+                        error,
+                    });
+                }
+            }
+        }
+    }
+
+    return invalidToolCalls;
+}
+
+/**
+ * Check if a tool result indicates an error.
+ * AI SDK wraps tool execution errors in error-text or error-json formats.
+ */
+export function isToolResultError(result: unknown): boolean {
+    if (typeof result !== "object" || result === null) {
+        return false;
+    }
+    const res = result as Record<string, unknown>;
+    // Check for AI SDK's known error formats
+    return (
+        (res.type === "error-text" && typeof res.text === "string") ||
+        (res.type === "error-json" && typeof res.json === "object")
+    );
+}
+
+/**
+ * Extract error details from tool result for better logging.
+ * Returns null if the result is not an error format.
+ */
+export function extractErrorDetails(result: unknown): { message: string; type: string } | null {
+    if (typeof result !== "object" || result === null) {
+        return null;
+    }
+    const res = result as Record<string, unknown>;
+
+    if (res.type === "error-text" && typeof res.text === "string") {
+        return { message: res.text, type: "error-text" };
+    }
+
+    if (res.type === "error-json" && typeof res.json === "object") {
+        const errorJson = res.json as Record<string, unknown>;
+        const message = errorJson.message || errorJson.error || JSON.stringify(errorJson);
+        return { message: String(message), type: "error-json" };
+    }
+
+    return null;
+}

package/src/llm/utils/usage.ts

@@ -0,0 +1,74 @@
+import type { LanguageModelUsage } from "ai";
+import type { LanguageModelUsageWithCostUsd } from "../types";
+
+interface OpenRouterUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    cost?: number;
+    promptTokensDetails?: {
+        cachedTokens?: number;
+    };
+    completionTokensDetails?: {
+        reasoningTokens?: number;
+    };
+}
+
+interface StepProviderMetadata {
+    openrouter?: {
+        usage?: OpenRouterUsage;
+    };
+    [key: string]: unknown;
+}
+
+type StepUsage = Partial<Pick<LanguageModelUsage, "inputTokens" | "outputTokens">>;
+
+export interface StepWithProviderMetadata {
+    usage?: StepUsage;
+    providerMetadata?: StepProviderMetadata;
+}
+
+/**
+ * Calculate cumulative usage from an array of steps.
+ * Returns undefined if no steps provided.
+ * Extracts token counts, cost, and detailed token breakdowns from OpenRouter providerMetadata.
+ */
+export function calculateCumulativeUsage(
+    steps: StepWithProviderMetadata[]
+): LanguageModelUsageWithCostUsd | undefined {
+    if (steps.length === 0) {
+        return undefined;
+    }
+
+    const inputTokens = steps.reduce((sum, step) => {
+        const openrouterUsage = step.providerMetadata?.openrouter?.usage;
+        return sum + (openrouterUsage?.promptTokens ?? step.usage?.inputTokens ?? 0);
+    }, 0);
+    const outputTokens = steps.reduce((sum, step) => {
+        const openrouterUsage = step.providerMetadata?.openrouter?.usage;
+        return sum + (openrouterUsage?.completionTokens ?? step.usage?.outputTokens ?? 0);
+    }, 0);
+    const costUsd = steps.reduce((sum, step) => {
+        const openrouterUsage = step.providerMetadata?.openrouter?.usage;
+        return sum + (openrouterUsage?.cost ?? 0);
+    }, 0);
+    const cachedInputTokens = steps.reduce((sum, step) => {
+        const openrouterUsage = step.providerMetadata?.openrouter?.usage;
+        return sum + (openrouterUsage?.promptTokensDetails?.cachedTokens ?? 0);
+    }, 0);
+    const reasoningTokens = steps.reduce((sum, step) => {
+        const openrouterUsage = step.providerMetadata?.openrouter?.usage;
+        return sum + (openrouterUsage?.completionTokensDetails?.reasoningTokens ?? 0);
+    }, 0);
+
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens: inputTokens + outputTokens,
+        costUsd: costUsd > 0 ? costUsd : undefined,
+        cachedInputTokens: cachedInputTokens > 0 ? cachedInputTokens : undefined,
+        reasoningTokens: reasoningTokens > 0 ? reasoningTokens : undefined,
+        inputTokenDetails: { noCacheTokens: undefined, cacheReadTokens: undefined, cacheWriteTokens: undefined },
+        outputTokenDetails: { textTokens: undefined, reasoningTokens: undefined },
+    } as LanguageModelUsageWithCostUsd;
+}