@tenex-chat/backend 0.9.1

package/src/llm/providers/agent/CodexAppServerProvider.ts

@@ -0,0 +1,214 @@
+/**
+ * Codex App Server Provider
+ *
+ * OpenAI Codex using app-server mode with JSON-RPC for mid-execution
+ * message injection support.
+ */
+
+import {
+    createCodexAppServer,
+    type CodexAppServerSettings,
+    type Session,
+    type McpServerConfigOrSdk,
+} from "ai-sdk-provider-codex-app-server";
+import type { LanguageModelUsage } from "ai";
+import { logger } from "@/utils/logger";
+import { trace } from "@opentelemetry/api";
+import type { LanguageModelUsageWithCostUsd } from "../../types";
+import type {
+    ProviderInitConfig,
+    ProviderMetadata,
+    ProviderRuntimeContext,
+} from "../types";
+import { AgentProvider, type AgentProviderFunction } from "../base/AgentProvider";
+import { CodexAppServerToolsAdapter } from "./CodexAppServerToolsAdapter";
+import { PROVIDER_IDS } from "../provider-ids";
+
+/**
+ * Codex App Server-specific metadata structure
+ */
+interface CodexAppServerProviderMetadata {
+    costUsd?: number;
+    sessionId?: string;
+}
+
+/**
+ * AI SDK usage with optional extended fields
+ */
+interface ExtendedUsage extends LanguageModelUsage {
+    cachedInputTokens?: number;
+    reasoningTokens?: number;
+}
+
+/**
+ * Codex App Server provider implementation
+ *
+ * Unlike CodexCliProvider which uses one-shot execution, this provider
+ * uses app-server mode for persistent threads and mid-execution injection.
+ */
+export class CodexAppServerProvider extends AgentProvider {
+    static readonly METADATA: ProviderMetadata = AgentProvider.createMetadata(
+        PROVIDER_IDS.CODEX_APP_SERVER,
+        "Codex App Server",
+        "OpenAI Codex with app-server mode and mid-execution injection",
+        "agent",
+        "gpt-5.1-codex-max",
+        {
+            streaming: true,
+            toolCalling: true,
+            builtInTools: true,
+            sessionResumption: true,
+            requiresApiKey: false,
+            mcpSupport: true,
+        },
+        "https://openai.com/codex"
+    );
+
+    private currentSession: Session | null = null;
+
+    get metadata(): ProviderMetadata {
+        return CodexAppServerProvider.METADATA;
+    }
+
+    /**
+     * Get the current session for mid-execution injection
+     */
+    getSession(): Session | null {
+        return this.currentSession;
+    }
+
+    /**
+     * Create the Codex App Server provider function
+     */
+    protected createProviderFunction(_config: ProviderInitConfig): AgentProviderFunction {
+        return createCodexAppServer({
+            defaultSettings: {},
+        }) as AgentProviderFunction;
+    }
+
+    /**
+     * Create the agent settings for Codex App Server
+     */
+    protected createAgentSettings(
+        context: ProviderRuntimeContext,
+        _modelId: string
+    ): CodexAppServerSettings {
+        trace.getActiveSpan()?.addEvent("llm_factory.creating_codex_app_server", {
+            "agent.name": context.agentName ?? "",
+            "session.id": context.sessionId ?? "",
+        });
+
+        const toolNames = context.tools ? Object.keys(context.tools) : [];
+        const regularTools = toolNames.filter((name) => !name.startsWith("mcp__"));
+
+        logger.debug("[CodexAppServerProvider] Tool analysis", {
+            agentName: context.agentName,
+            totalToolNames: toolNames.length,
+            regularTools: regularTools.length,
+        });
+
+        // Build mcpServers configuration - can include SdkMcpServer for in-process tools
+        const mcpServersConfig: Record<string, McpServerConfigOrSdk> = {};
+
+        // Create TENEX SDK MCP server if we have TENEX tools
+        if (context.tools && regularTools.length > 0) {
+            const tenexServer = CodexAppServerToolsAdapter.createSdkMcpServer(
+                context.tools,
+                { agentName: context.agentName }
+            );
+            if (tenexServer) {
+                mcpServersConfig.tenex = tenexServer;
+                logger.debug("[CodexAppServerProvider] Added TENEX SDK MCP server", {
+                    toolCount: regularTools.length,
+                });
+            }
+        }
+
+        // Add configured MCP servers (stdio format)
+        const mcpConfig = context.mcpConfig;
+        if (mcpConfig?.enabled && mcpConfig.servers) {
+            for (const [serverName, serverConfig] of Object.entries(mcpConfig.servers)) {
+                mcpServersConfig[serverName] = {
+                    transport: "stdio",
+                    command: serverConfig.command,
+                    args: serverConfig.args,
+                    env: serverConfig.env,
+                };
+            }
+
+            trace.getActiveSpan()?.addEvent("llm_factory.codex_app_server_mcp_added", {
+                "mcp.server_count": Object.keys(mcpConfig.servers).length,
+                "mcp.servers": Object.keys(mcpConfig.servers).join(", "),
+            });
+        }
+
+        const settings: CodexAppServerSettings = {
+            cwd: context.workingDirectory,
+            mcpServers: mcpServersConfig,
+            approvalMode: "on-failure",
+            sandboxMode: "workspace-write",
+            threadMode: "stateless",
+            reasoningEffort: context.reasoningEffort,
+            verbose: false,
+            logger: {
+                warn: (message: string) => logger.warn("[CodexAppServer]", message),
+                error: (message: string) => logger.error("[CodexAppServer]", message),
+                info: (message: string) => logger.info("[CodexAppServer]", message),
+                debug: (message: string) => logger.debug("[CodexAppServer]", message),
+            },
+            onSessionCreated: (session: Session) => {
+                this.currentSession = session;
+                logger.info("[CodexAppServerProvider] Session created", {
+                    threadId: session.threadId,
+                    reasoningEffort: context.reasoningEffort,
+                });
+                trace.getActiveSpan()?.addEvent("codex_app_server.session_created", {
+                    "session.threadId": session.threadId,
+                    "reasoning.effort": context.reasoningEffort ?? "default",
+                });
+            },
+        };
+
+        if (context.sessionId) {
+            settings.resume = context.sessionId;
+        }
+
+        return settings;
+    }
+
+    /**
+     * Codex App Server is always available (no API key required)
+     */
+    isAvailable(): boolean {
+        return this._initialized;
+    }
+
+    /**
+     * Extract usage metadata from Codex App Server provider response
+     */
+    static extractUsageMetadata(
+        model: string,
+        totalUsage: LanguageModelUsage | undefined,
+        providerMetadata: Record<string, unknown> | undefined
+    ): LanguageModelUsageWithCostUsd {
+        const metadata = providerMetadata?.[PROVIDER_IDS.CODEX_APP_SERVER] as CodexAppServerProviderMetadata | undefined;
+        const extendedUsage = totalUsage as ExtendedUsage | undefined;
+
+        const inputTokens = totalUsage?.inputTokens;
+        const outputTokens = totalUsage?.outputTokens;
+        const totalTokens = totalUsage?.totalTokens ??
+            (inputTokens !== undefined && outputTokens !== undefined
+                ? inputTokens + outputTokens
+                : undefined);
+
+        return {
+            model,
+            inputTokens,
+            outputTokens,
+            totalTokens,
+            costUsd: metadata?.costUsd,
+            cachedInputTokens: extendedUsage?.cachedInputTokens,
+            reasoningTokens: extendedUsage?.reasoningTokens,
+        } as LanguageModelUsageWithCostUsd;
+    }
+}

package/src/llm/providers/agent/CodexAppServerToolsAdapter.ts

@@ -0,0 +1,91 @@
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { createSdkMcpServer, tool, type SdkMcpServer, type Tool, type ToolDefinition } from "ai-sdk-provider-codex-app-server";
+import { z, type ZodRawShape } from "zod";
+
+/**
+ * Converts TENEX tools to Codex App Server SDK MCP server format.
+ *
+ * This adapter uses createSdkMcpServer which handles HTTP server lifecycle
+ * automatically - the user API is identical to Claude Code's createSdkMcpServer.
+ */
+export class CodexAppServerToolsAdapter {
+    /**
+     * Create an SDK MCP server from TENEX tools
+     * Pass the result directly to mcpServers in provider settings.
+     */
+    static createSdkMcpServer(
+        tools: Record<string, AISdkTool>,
+        context: { agentName?: string }
+    ): SdkMcpServer | undefined {
+        const localTools = Object.entries(tools);
+
+        logger.debug("[CodexAppServerToolsAdapter] Input tools analysis:", {
+            totalTools: Object.keys(tools).length,
+            localToolsCount: localTools.length,
+            localToolNames: localTools.map(([name]) => name),
+            agentName: context.agentName,
+        });
+
+        if (localTools.length === 0) {
+            return undefined;
+        }
+
+        const codexTools = this.convertTools(localTools, tools);
+
+        logger.info("[CodexAppServerToolsAdapter] Creating SDK MCP server:", {
+            serverName: "tenex",
+            toolCount: codexTools.length,
+            toolNames: localTools.map(([name]) => name),
+        });
+
+        return createSdkMcpServer({
+            name: "tenex",
+            tools: codexTools,
+        });
+    }
+
+    /**
+     * Convert TENEX tools to Codex Tool format
+     */
+    private static convertTools(
+        localTools: [string, AISdkTool][],
+        allTools: Record<string, AISdkTool>
+    ): Tool[] {
+        return localTools.map(([name, tenexTool]) => {
+            let zodSchema: unknown = z.object({});
+
+            if (tenexTool.inputSchema) {
+                const schema = tenexTool.inputSchema;
+                if (schema && typeof schema === "object" && "shape" in schema) {
+                    const shape = (schema as z.ZodObject<ZodRawShape>).shape;
+                    zodSchema = z.object(shape);
+                } else if (schema && typeof schema === "object" && !("_def" in schema)) {
+                    zodSchema = z.object(schema as unknown as ZodRawShape);
+                }
+            }
+
+            return tool<unknown, unknown>({
+                name,
+                description: tenexTool.description || `Execute ${name}`,
+                parameters: zodSchema as ToolDefinition<unknown, unknown>["parameters"],
+                execute: async (args: unknown) => {
+                    const executeTool = allTools[name];
+                    if (!executeTool?.execute) {
+                        throw new Error(`Tool ${name} not found or has no execute function`);
+                    }
+
+                    logger.debug(`[CodexAppServerToolsAdapter] Executing tool ${name}`);
+
+                    const result = await executeTool.execute(args, {
+                        abortSignal: new AbortController().signal,
+                        toolCallId: "tool-call-" + Date.now(),
+                        messages: [],
+                    });
+
+                    return result;
+                },
+            });
+        });
+    }
+}

package/src/llm/providers/agent/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Agent Providers Index
+ *
+ * Exports all agent-based providers.
+ */
+
+export { ClaudeCodeProvider } from "./ClaudeCodeProvider";
+export { ClaudeCodeToolsAdapter } from "./ClaudeCodeToolsAdapter";
+export { CodexAppServerProvider } from "./CodexAppServerProvider";
+export { CodexAppServerToolsAdapter } from "./CodexAppServerToolsAdapter";

package/src/llm/providers/base/AgentProvider.ts

@@ -0,0 +1,107 @@
+/**
+ * Agent Provider - Base class for agent-based LLM providers
+ *
+ * Agent providers (like claude-code, codex-app-server) have their own
+ * execution model with built-in tools and session management.
+ */
+
+import type { LanguageModel } from "ai";
+import type {
+    ProviderInitConfig,
+    ProviderRuntimeContext,
+    ProviderModelResult,
+} from "../types";
+import { BaseProvider } from "./BaseProvider";
+
+/**
+ * Configuration type for agent provider functions
+ */
+export type AgentProviderFunction<TSettings = unknown> = (
+    model: string,
+    options?: TSettings
+) => LanguageModel;
+
+/**
+ * Base class for agent-based providers
+ *
+ * Agent providers:
+ * - Have their own built-in tools
+ * - Support session resumption
+ * - Bypass the standard AI SDK registry
+ * - Create provider functions instead of provider instances
+ */
+export abstract class AgentProvider extends BaseProvider {
+    protected providerFunction: AgentProviderFunction | null = null;
+
+    /**
+     * Agent providers don't use the standard provider instance
+     */
+    getProviderInstance(): null {
+        return null;
+    }
+
+    /**
+     * Get the provider function for creating models
+     */
+    getProviderFunction(): AgentProviderFunction | null {
+        return this.providerFunction;
+    }
+
+    /**
+     * Create the agent settings for the provider
+     * Must be implemented by subclasses
+     */
+    protected abstract createAgentSettings(
+        context: ProviderRuntimeContext,
+        modelId: string
+    ): unknown;
+
+    /**
+     * Create the provider function
+     * Must be implemented by subclasses
+     */
+    protected abstract createProviderFunction(config: ProviderInitConfig): AgentProviderFunction;
+
+    /**
+     * Initialize the agent provider
+     */
+    async initialize(config: ProviderInitConfig): Promise<void> {
+        this.config = config;
+        this.providerFunction = this.createProviderFunction(config);
+        this._initialized = true;
+    }
+
+    /**
+     * Agent providers don't create a standard provider instance
+     */
+    protected createProviderInstance(_config: ProviderInitConfig): null {
+        return null;
+    }
+
+    /**
+     * Create a language model using the provider function
+     */
+    createModel(modelId: string, context?: ProviderRuntimeContext): ProviderModelResult {
+        if (!this.providerFunction) {
+            throw new Error(`Provider ${this.metadata.id} not initialized`);
+        }
+
+        const settings = this.createAgentSettings(context || {}, modelId);
+        const model = this.providerFunction(modelId, settings);
+
+        return {
+            model,
+            providerFunction: this.providerFunction,
+            bypassRegistry: true,
+            agentSettings: settings,
+        };
+    }
+
+    /**
+     * Reset the provider state
+     */
+    reset(): void {
+        super.reset();
+        this.providerFunction = null;
+    }
+}

package/src/llm/providers/base/BaseProvider.ts

@@ -0,0 +1,114 @@
+/**
+ * Base Provider - Abstract base class for all LLM providers
+ *
+ * Provides common functionality for provider implementations.
+ */
+
+import type {
+    ILLMProvider,
+    ProviderInitConfig,
+    ProviderMetadata,
+    ProviderRuntimeContext,
+    ProviderModelResult,
+    ProviderCapabilities,
+    ProviderCategory,
+} from "../types";
+
+/**
+ * Abstract base class for LLM providers
+ */
+export abstract class BaseProvider implements ILLMProvider {
+    protected config: ProviderInitConfig | null = null;
+    protected _initialized = false;
+
+    /**
+     * Get provider metadata - must be implemented by subclasses
+     */
+    abstract get metadata(): ProviderMetadata;
+
+    /**
+     * Create the underlying provider instance
+     * Called during initialization for standard providers
+     */
+    protected abstract createProviderInstance(config: ProviderInitConfig): unknown | null;
+
+    /**
+     * Provider instance storage
+     */
+    protected providerInstance: unknown | null = null;
+
+    /**
+     * Initialize the provider with configuration
+     */
+    async initialize(config: ProviderInitConfig): Promise<void> {
+        this.config = config;
+        this.providerInstance = this.createProviderInstance(config);
+        this._initialized = true;
+    }
+
+    /**
+     * Check if the provider is initialized
+     */
+    isInitialized(): boolean {
+        return this._initialized;
+    }
+
+    /**
+     * Check if the provider is available
+     */
+    isAvailable(): boolean {
+        return this._initialized;
+    }
+
+    /**
+     * Get the AI SDK provider instance
+     */
+    getProviderInstance(): unknown | null {
+        return this.providerInstance;
+    }
+
+    /**
+     * Create a language model - must be implemented by subclasses
+     */
+    abstract createModel(modelId: string, context?: ProviderRuntimeContext): ProviderModelResult;
+
+    /**
+     * Reset the provider state
+     */
+    reset(): void {
+        this.config = null;
+        this.providerInstance = null;
+        this._initialized = false;
+    }
+
+    /**
+     * Helper to create metadata
+     */
+    protected static createMetadata(
+        id: string,
+        displayName: string,
+        description: string,
+        category: ProviderCategory,
+        defaultModel: string,
+        capabilities?: Partial<ProviderCapabilities>,
+        documentationUrl?: string
+    ): ProviderMetadata {
+        return {
+            id,
+            displayName,
+            description,
+            category,
+            defaultModel,
+            documentationUrl,
+            capabilities: {
+                streaming: true,
+                toolCalling: true,
+                builtInTools: false,
+                sessionResumption: false,
+                requiresApiKey: true,
+                mcpSupport: false,
+                ...capabilities,
+            },
+        };
+    }
+}

package/src/llm/providers/base/StandardProvider.ts

@@ -0,0 +1,38 @@
+/**
+ * Standard Provider - Base class for standard AI SDK providers
+ *
+ * Standard providers use AI SDK's createProviderRegistry and follow
+ * the standard language model pattern.
+ */
+
+import type { ProviderRuntimeContext, ProviderModelResult } from "../types";
+import { BaseProvider } from "./BaseProvider";
+
+/**
+ * Base class for standard AI SDK providers
+ *
+ * Standard providers:
+ * - Use AI SDK's provider packages (@ai-sdk/openai, @ai-sdk/anthropic, etc.)
+ * - Are registered in createProviderRegistry
+ * - Use the registry.languageModel() pattern
+ */
+export abstract class StandardProvider extends BaseProvider {
+    /**
+     * Create a language model using the standard registry pattern
+     */
+    createModel(modelId: string, _context?: ProviderRuntimeContext): ProviderModelResult {
+        if (!this.providerInstance) {
+            throw new Error(`Provider ${this.metadata.id} not initialized`);
+        }
+
+        // Standard providers get their model from the AI SDK registry
+        // The actual model creation is done by the registry in LLMService
+        const provider = this.providerInstance as { languageModel: (id: string) => unknown };
+        const model = provider.languageModel(modelId);
+
+        return {
+            model: model as import("ai").LanguageModel,
+            bypassRegistry: false,
+        };
+    }
+}

package/src/llm/providers/base/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Base Providers Index
+ *
+ * Exports base classes for provider implementations.
+ */
+
+export { BaseProvider } from "./BaseProvider";
+export { StandardProvider } from "./StandardProvider";
+export { AgentProvider, type AgentProviderFunction } from "./AgentProvider";

package/src/llm/providers/index.ts

@@ -0,0 +1,106 @@
+/**
+ * LLM Providers Module
+ *
+ * This module provides a modular, extensible system for LLM providers.
+ * Each provider implements the ILLMProvider interface and registers
+ * itself with the ProviderRegistry.
+ *
+ * ## Architecture
+ *
+ * - **Standard Providers**: Use AI SDK's provider packages and createProviderRegistry
+ *   Examples: OpenRouter, Anthropic, OpenAI, Ollama
+ *
+ * - **Agent Providers**: Have built-in tools and session management
+ *   Examples: Claude Code, Codex CLI
+ *
+ * ## Adding a New Provider
+ *
+ * 1. Create a new provider class extending StandardProvider or AgentProvider
+ * 2. Implement the required abstract methods
+ * 3. Add the provider to the ALL_PROVIDERS array below
+ * 4. The provider will be automatically registered and available
+ *
+ * @module
+ */
+
+// Export types
+export * from "./types";
+
+// Export provider ID constants
+export { PROVIDER_IDS, type ProviderId } from "./provider-ids";
+
+// Export base classes
+export * from "./base";
+
+// Export registry
+export { ProviderRegistry, providerRegistry } from "./registry";
+
+// Export key manager
+export { KeyManager, keyManager, type KeyManagerConfig, resolveApiKey, hasApiKey } from "./key-manager";
+
+// Export standard providers
+export {
+    OpenRouterProvider,
+    AnthropicProvider,
+    OpenAIProvider,
+    OllamaProvider,
+} from "./standard";
+
+// Export agent providers
+export { ClaudeCodeProvider, CodexAppServerProvider } from "./agent";
+
+// Import for registration
+import type { ProviderRegistration } from "./types";
+import { OpenRouterProvider } from "./standard/OpenRouterProvider";
+import { AnthropicProvider } from "./standard/AnthropicProvider";
+import { OpenAIProvider } from "./standard/OpenAIProvider";
+import { OllamaProvider } from "./standard/OllamaProvider";
+import { ClaudeCodeProvider } from "./agent/ClaudeCodeProvider";
+import { CodexAppServerProvider } from "./agent/CodexAppServerProvider";
+import { providerRegistry } from "./registry";
+
+/**
+ * All available provider registrations
+ *
+ * Each provider exposes static metadata to avoid wasteful instantiation.
+ * Add new providers to this array to make them available.
+ */
+export const ALL_PROVIDER_REGISTRATIONS: ProviderRegistration[] = [
+    // Standard providers
+    {
+        Provider: OpenRouterProvider,
+        metadata: OpenRouterProvider.METADATA,
+    },
+    {
+        Provider: AnthropicProvider,
+        metadata: AnthropicProvider.METADATA,
+    },
+    {
+        Provider: OpenAIProvider,
+        metadata: OpenAIProvider.METADATA,
+    },
+    {
+        Provider: OllamaProvider,
+        metadata: OllamaProvider.METADATA,
+    },
+    // Agent providers
+    {
+        Provider: ClaudeCodeProvider,
+        metadata: ClaudeCodeProvider.METADATA,
+    },
+    {
+        Provider: CodexAppServerProvider,
+        metadata: CodexAppServerProvider.METADATA,
+    },
+];
+
+/**
+ * Register all providers with the registry
+ * This is called automatically on module load
+ */
+export function registerAllProviders(): void {
+    providerRegistry.registerAll(ALL_PROVIDER_REGISTRATIONS);
+}
+
+// Auto-register all providers on module load
+registerAllProviders();