@tenex-chat/backend 0.9.1

package/src/llm/MessageProcessor.ts

@@ -0,0 +1,90 @@
+import type { ModelMessage } from "ai";
+import { PROVIDER_IDS } from "./providers/provider-ids";
+
+/**
+ * Add provider-specific cache control to messages.
+ * Only Anthropic requires explicit cache control; OpenAI and Gemini cache automatically.
+ */
+export function addCacheControl(messages: ModelMessage[], provider: string): ModelMessage[] {
+    // Only add cache control for Anthropic
+    if (provider !== PROVIDER_IDS.ANTHROPIC) {
+        return messages;
+    }
+
+    // Rough estimate: 4 characters per token (configurable if needed)
+    const CHARS_PER_TOKEN_ESTIMATE = 4;
+    const MIN_TOKENS_FOR_CACHE = 1024;
+    const minCharsForCache = MIN_TOKENS_FOR_CACHE * CHARS_PER_TOKEN_ESTIMATE;
+
+    return messages.map((msg) => {
+        // Only cache system messages and only if they're large enough
+        if (msg.role === "system" && typeof msg.content === "string" && msg.content.length > minCharsForCache) {
+            return {
+                ...msg,
+                providerOptions: {
+                    anthropic: {
+                        cacheControl: { type: "ephemeral" },
+                    },
+                },
+            };
+        }
+        return msg;
+    });
+}
+
+/**
+ * Prepare messages for sending to the LLM.
+ * Handles provider-specific transformations.
+ */
+export function prepareMessagesForRequest(messages: ModelMessage[], provider: string): ModelMessage[] {
+    let processedMessages = messages;
+
+    // For Claude Code, filter out system messages since they're passed via systemPrompt
+    if (provider === PROVIDER_IDS.CLAUDE_CODE) {
+        processedMessages = messages.filter((m) => m.role !== "system");
+    }
+
+    return addCacheControl(processedMessages, provider);
+}
+
+/**
+ * Extract the last user message text from a message array.
+ * Handles both simple string content and complex content arrays.
+ */
+export function extractLastUserMessage(messages: ModelMessage[]): string | undefined {
+    // Find the last message with role "user" (iterate from end)
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role === "user") {
+            // User messages can have string content or content array
+            if (typeof msg.content === "string") {
+                return msg.content;
+            }
+            if (Array.isArray(msg.content)) {
+                // Extract text from content parts
+                const textParts = msg.content
+                    .filter((part): part is { type: "text"; text: string } =>
+                        part.type === "text" && typeof part.text === "string"
+                    )
+                    .map((part) => part.text);
+                if (textParts.length > 0) {
+                    return textParts.join("\n");
+                }
+            }
+            // Found user message but couldn't extract text
+            return "[User message with non-text content]";
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Extract system messages from a message array and combine them.
+ * Used for providers like Claude Code that take system prompt separately.
+ */
+export function extractSystemContent(messages: ModelMessage[]): string {
+    return messages
+        .filter((m) => m.role === "system")
+        .map((m) => (typeof m.content === "string" ? m.content : JSON.stringify(m.content)))
+        .join("\n\n");
+}

package/src/llm/RecordingState.ts

@@ -0,0 +1,37 @@
+import { EventEmitter } from "tseep";
+
+/**
+ * Global recording state singleton.
+ * Controls whether the flight recorder middleware saves LLM interactions.
+ */
+class RecordingStateManager extends EventEmitter<{
+    "state-changed": (isRecording: boolean) => void;
+}> {
+    private _isRecording = false;
+
+    get isRecording(): boolean {
+        return this._isRecording;
+    }
+
+    toggle(): boolean {
+        this._isRecording = !this._isRecording;
+        this.emit("state-changed", this._isRecording);
+        return this._isRecording;
+    }
+
+    start(): void {
+        if (!this._isRecording) {
+            this._isRecording = true;
+            this.emit("state-changed", true);
+        }
+    }
+
+    stop(): void {
+        if (this._isRecording) {
+            this._isRecording = false;
+            this.emit("state-changed", false);
+        }
+    }
+}
+
+export const recordingState = new RecordingStateManager();

package/src/llm/StreamPublisher.ts

@@ -0,0 +1,40 @@
+import { logger } from "@/utils/logger";
+import type { LocalStreamChunk } from "./types";
+
+/**
+ * Interface for stream transports (Unix socket, future Nostr ephemeral)
+ */
+export interface StreamTransport {
+    write(chunk: LocalStreamChunk): void;
+    isConnected(): boolean;
+}
+
+/**
+ * Publishes AI SDK chunks to connected transports
+ * Fire-and-forget: silently drops if no transport connected
+ */
+export class StreamPublisher {
+    private transport: StreamTransport | null = null;
+
+    setTransport(transport: StreamTransport | null): void {
+        this.transport = transport;
+    }
+
+    write(chunk: LocalStreamChunk): void {
+        logger.debug("[StreamPublisher] write called", {
+            hasTransport: !!this.transport,
+            isConnected: this.transport?.isConnected() ?? false,
+            chunkType: (chunk.data as { type?: string })?.type,
+        });
+        if (this.transport?.isConnected()) {
+            this.transport.write(chunk);
+        }
+    }
+
+    isConnected(): boolean {
+        return this.transport?.isConnected() ?? false;
+    }
+}
+
+/** Singleton instance */
+export const streamPublisher = new StreamPublisher();

package/src/llm/TracingUtils.ts

@@ -0,0 +1,77 @@
+import { trace } from "@opentelemetry/api";
+import type { TelemetrySettings } from "ai";
+import { shortenConversationId } from "@/utils/conversation-id";
+
+/**
+ * Get trace correlation ID for OpenRouter.
+ * Returns a string combining trace and span IDs for unique request identification.
+ */
+export function getTraceCorrelationId(): string | undefined {
+    const span = trace.getActiveSpan();
+    if (!span) return undefined;
+    const ctx = span.spanContext();
+    return `tenex-${ctx.traceId}-${ctx.spanId}`;
+}
+
+/**
+ * @deprecated Use shortenConversationId from @/utils/conversation-id instead.
+ * This function is kept for backward compatibility but will be removed in a future version.
+ */
+export function shortenConversationIdForSpan(conversationId: string): string {
+    return shortenConversationId(conversationId);
+}
+
+/**
+ * Get OpenRouter metadata for request correlation.
+ * Includes OTL trace context plus agent and conversation identifiers.
+ */
+export function getOpenRouterMetadata(
+    agentSlug?: string,
+    conversationId?: string
+): Record<string, string> {
+    const metadata: Record<string, string> = {};
+
+    const span = trace.getActiveSpan();
+    if (span) {
+        const ctx = span.spanContext();
+        metadata.tenex_trace_id = ctx.traceId;
+        metadata.tenex_span_id = ctx.spanId;
+    }
+
+    if (agentSlug) metadata.tenex_agent = agentSlug;
+    if (conversationId) metadata.tenex_conversation = conversationId;
+
+    return metadata;
+}
+
+/**
+ * Get full telemetry configuration for AI SDK.
+ * Captures EVERYTHING for debugging - no privacy filters.
+ */
+export function getFullTelemetryConfig(config: {
+    agentSlug?: string;
+    provider: string;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    sessionId?: string;
+}): TelemetrySettings {
+    return {
+        isEnabled: true,
+        functionId: `${config.agentSlug || "unknown"}.${config.provider}.${config.model}`,
+
+        // Metadata for debugging context
+        metadata: {
+            "agent.slug": config.agentSlug || "unknown",
+            "llm.provider": config.provider,
+            "llm.model": config.model,
+            "llm.temperature": config.temperature ?? 0,
+            "llm.max_tokens": config.maxTokens ?? 0,
+            "session.id": config.sessionId ?? "unknown",
+        },
+
+        // FULL DATA - no privacy filters for debugging
+        recordInputs: true, // Capture full prompts
+        recordOutputs: true, // Capture full responses
+    };
+}

package/src/llm/chunk-validators.ts

@@ -0,0 +1,57 @@
+import { trace } from "@opentelemetry/api";
+import type { TextStreamPart } from "ai";
+import type { AISdkTool } from "@/tools/types";
+
+type StreamChunk = TextStreamPart<Record<string, AISdkTool>>;
+
+interface ChunkValidator {
+    name: string;
+    shouldIgnore: (chunk: StreamChunk) => boolean;
+}
+
+/**
+ * Validates reasoning-delta chunks with [REDACTED] content.
+ * Some LLM providers (e.g., OpenRouter with Gemini) send encrypted reasoning
+ * data that appears as "[REDACTED]" - these should be ignored.
+ */
+const redactedReasoningValidator: ChunkValidator = {
+    name: "redacted-reasoning",
+    shouldIgnore: (chunk: StreamChunk): boolean => {
+        if (chunk.type !== "reasoning-delta") {
+            return false;
+        }
+
+        // The chunk may have 'text' or 'delta' property depending on how AI SDK processes it
+        const content = (chunk as { text?: string; delta?: string }).text
+            ?? (chunk as { text?: string; delta?: string }).delta;
+
+        return content === "[REDACTED]";
+    },
+};
+
+/**
+ * All chunk validators to apply before processing
+ */
+const validators: ChunkValidator[] = [
+    redactedReasoningValidator,
+];
+
+/**
+ * Check if a chunk should be ignored based on all validators.
+ * Adds an OTL span event when a chunk is ignored for debugging.
+ *
+ * @returns true if the chunk should be ignored, false otherwise
+ */
+export function shouldIgnoreChunk(chunk: StreamChunk): boolean {
+    for (const validator of validators) {
+        if (validator.shouldIgnore(chunk)) {
+            const activeSpan = trace.getActiveSpan();
+            activeSpan?.addEvent("chunk_ignored", {
+                "chunk.type": chunk.type,
+                "validator.name": validator.name,
+            });
+            return true;
+        }
+    }
+    return false;
+}

package/src/llm/constants.ts

@@ -0,0 +1,6 @@
+/**
+ * LLM Configuration Constants
+ */
+
+// Default configuration name for agents when no llmConfig is specified
+export const DEFAULT_AGENT_LLM_CONFIG = "default";

package/src/llm/index.ts

@@ -0,0 +1,12 @@
+// Export service
+export { LLMService } from "./service";
+
+// Export factory
+export { LLMServiceFactory, llmServiceFactory } from "./LLMServiceFactory";
+
+// Export stream publisher
+export { StreamPublisher, streamPublisher, type StreamTransport } from "./StreamPublisher";
+export type { LocalStreamChunk } from "./types";
+
+// Export types
+export * from "./types";

package/src/llm/meta/MetaModelResolver.ts

@@ -0,0 +1,352 @@
+/**
+ * MetaModelResolver - Handles dynamic model selection based on keywords
+ *
+ * Meta models are virtual model configurations that select from underlying
+ * real models based on keywords in the user's message. This enables
+ * "think harder" type functionality without explicit tool calls.
+ *
+ * @example
+ * User: "ultrathink how do we implement authentication?"
+ * → Resolves to high-cost reasoning model, strips "ultrathink" from message
+ *
+ * User: "quick what's 2+2?"
+ * → Resolves to fast model, strips "quick" from message
+ */
+
+import type { MetaModelConfiguration, MetaModelVariant } from "@/services/config/types";
+import { logger } from "@/utils/logger";
+
+/**
+ * Result of resolving a meta model variant
+ */
+export interface MetaModelResolution {
+    /** The resolved variant name */
+    variantName: string;
+    /** The variant configuration */
+    variant: MetaModelVariant;
+    /** The underlying LLM configuration name to use */
+    configName: string;
+    /** The message with keywords stripped (if stripKeywords was true) */
+    strippedMessage?: string;
+    /** Keywords that were matched */
+    matchedKeywords: string[];
+    /** Optional additional system prompt from the variant */
+    systemPrompt?: string;
+}
+
+/**
+ * Options for resolving a meta model
+ */
+export interface ResolveOptions {
+    /** Whether to strip matched keywords from the message (default: true) */
+    stripKeywords?: boolean;
+}
+
+/**
+ * MetaModelResolver handles keyword detection and model resolution
+ * for meta model configurations.
+ */
+export class MetaModelResolver {
+    /**
+     * Build a keyword-to-variant lookup map from a meta model configuration.
+     * Keywords are normalized to lowercase for case-insensitive matching.
+     */
+    private static buildKeywordMap(
+        config: MetaModelConfiguration
+    ): Map<string, { variantName: string; variant: MetaModelVariant }> {
+        const keywordMap = new Map<string, { variantName: string; variant: MetaModelVariant }>();
+
+        for (const [variantName, variant] of Object.entries(config.variants)) {
+            if (variant.keywords) {
+                for (const keyword of variant.keywords) {
+                    const normalizedKeyword = keyword.toLowerCase();
+                    keywordMap.set(normalizedKeyword, { variantName, variant });
+                }
+            }
+        }
+
+        return keywordMap;
+    }
+
+    /**
+     * Find all matching keywords at the start of a message.
+     * Returns keywords in the order they appear, for proper stripping.
+     */
+    private static findMatchingKeywords(
+        message: string,
+        keywordMap: Map<string, { variantName: string; variant: MetaModelVariant }>
+    ): Array<{ keyword: string; variantName: string; variant: MetaModelVariant; position: number }> {
+        const matches: Array<{
+            keyword: string;
+            variantName: string;
+            variant: MetaModelVariant;
+            position: number;
+        }> = [];
+
+        // Get all keywords, sorted by length (longest first for proper matching)
+        const keywords = Array.from(keywordMap.keys()).sort((a, b) => b.length - a.length);
+
+        // Check the beginning of the message for keywords
+        // Keywords must be at the start or preceded by whitespace
+        const messageLower = message.toLowerCase();
+
+        for (const keyword of keywords) {
+            // Check if keyword is at the start
+            if (messageLower.startsWith(keyword)) {
+                const afterKeyword = message.charAt(keyword.length);
+                // Keyword must be followed by whitespace or end of string
+                if (!afterKeyword || /\s/.test(afterKeyword)) {
+                    const data = keywordMap.get(keyword);
+                    if (data) {
+                        matches.push({
+                            keyword,
+                            variantName: data.variantName,
+                            variant: data.variant,
+                            position: 0,
+                        });
+                    }
+                }
+            }
+
+            // Also check for keywords after initial whitespace (e.g., "  ultrathink ...")
+            const leadingWhitespaceMatch = messageLower.match(/^\s+/);
+            if (leadingWhitespaceMatch) {
+                const offset = leadingWhitespaceMatch[0].length;
+                const restLower = messageLower.substring(offset);
+                if (restLower.startsWith(keyword)) {
+                    const afterKeyword = message.charAt(offset + keyword.length);
+                    if (!afterKeyword || /\s/.test(afterKeyword)) {
+                        const data = keywordMap.get(keyword);
+                        if (data && !matches.some((m) => m.keyword === keyword)) {
+                            matches.push({
+                                keyword,
+                                variantName: data.variantName,
+                                variant: data.variant,
+                                position: offset,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        return matches;
+    }
+
+    /**
+     * Select the winning variant from a set of matches using tier-based resolution.
+     * Highest tier wins. If tiers are equal, first match wins.
+     */
+    private static selectWinningVariant(
+        matches: Array<{ keyword: string; variantName: string; variant: MetaModelVariant; position: number }>
+    ): { keyword: string; variantName: string; variant: MetaModelVariant; position: number } | null {
+        if (matches.length === 0) {
+            return null;
+        }
+
+        // Sort by tier (descending), then by position (ascending for first match)
+        const sorted = [...matches].sort((a, b) => {
+            const tierA = a.variant.tier ?? 0;
+            const tierB = b.variant.tier ?? 0;
+            if (tierB !== tierA) {
+                return tierB - tierA; // Higher tier wins
+            }
+            return a.position - b.position; // Earlier position wins if tiers equal
+        });
+
+        return sorted[0];
+    }
+
+    /**
+     * Strip matched keywords from the beginning of a message.
+     * Preserves the rest of the message content.
+     */
+    private static stripKeywordsFromMessage(
+        message: string,
+        matchedKeywords: string[]
+    ): string {
+        let result = message;
+
+        for (const keyword of matchedKeywords) {
+            // Match the keyword at the start (case-insensitive) followed by optional whitespace
+            const regex = new RegExp(`^\\s*${escapeRegExp(keyword)}\\s*`, "i");
+            result = result.replace(regex, "");
+        }
+
+        return result.trim();
+    }
+
+    /**
+     * Resolve which variant to use based on the message content.
+     *
+     * @param config The meta model configuration
+     * @param message The user's message to analyze for keywords
+     * @param options Resolution options
+     * @returns The resolved variant information, or null if using default
+     */
+    static resolve(
+        config: MetaModelConfiguration,
+        message?: string,
+        options: ResolveOptions = {}
+    ): MetaModelResolution {
+        const { stripKeywords = true } = options;
+
+        // Build keyword map
+        const keywordMap = this.buildKeywordMap(config);
+
+        // If no message provided, use default
+        if (!message) {
+            const defaultVariant = config.variants[config.default];
+            if (!defaultVariant) {
+                throw new Error(
+                    `Meta model default variant "${config.default}" not found in variants`
+                );
+            }
+            return {
+                variantName: config.default,
+                variant: defaultVariant,
+                configName: defaultVariant.model,
+                matchedKeywords: [],
+                systemPrompt: defaultVariant.systemPrompt,
+            };
+        }
+
+        // Find matching keywords
+        const matches = this.findMatchingKeywords(message, keywordMap);
+
+        // If no keywords matched, use default
+        if (matches.length === 0) {
+            const defaultVariant = config.variants[config.default];
+            if (!defaultVariant) {
+                throw new Error(
+                    `Meta model default variant "${config.default}" not found in variants`
+                );
+            }
+            return {
+                variantName: config.default,
+                variant: defaultVariant,
+                configName: defaultVariant.model,
+                matchedKeywords: [],
+                systemPrompt: defaultVariant.systemPrompt,
+            };
+        }
+
+        // Select winning variant based on tier
+        const winner = this.selectWinningVariant(matches);
+        if (!winner) {
+            // Shouldn't happen if matches.length > 0, but handle gracefully
+            const defaultVariant = config.variants[config.default];
+            return {
+                variantName: config.default,
+                variant: defaultVariant,
+                configName: defaultVariant.model,
+                matchedKeywords: [],
+                systemPrompt: defaultVariant.systemPrompt,
+            };
+        }
+
+        // Collect all matched keywords (for logging/debugging)
+        const matchedKeywords = matches.map((m) => m.keyword);
+
+        // Strip keywords if requested
+        const strippedMessage = stripKeywords
+            ? this.stripKeywordsFromMessage(message, matchedKeywords)
+            : message;
+
+        logger.debug("[MetaModelResolver] Resolved variant", {
+            variantName: winner.variantName,
+            matchedKeywords,
+            tier: winner.variant.tier ?? 0,
+            configName: winner.variant.model,
+        });
+
+        return {
+            variantName: winner.variantName,
+            variant: winner.variant,
+            configName: winner.variant.model,
+            strippedMessage,
+            matchedKeywords,
+            systemPrompt: winner.variant.systemPrompt,
+        };
+    }
+
+    /**
+     * Resolve directly to a specific variant by name.
+     * Used when there's a variant override set (e.g., via change_model tool).
+     *
+     * @param config The meta model configuration
+     * @param variantName The name of the variant to resolve to
+     * @returns The resolved variant information
+     * @throws Error if the variant doesn't exist
+     */
+    static resolveToVariant(
+        config: MetaModelConfiguration,
+        variantName: string
+    ): MetaModelResolution {
+        const variant = config.variants[variantName];
+        if (!variant) {
+            throw new Error(
+                `Meta model variant "${variantName}" not found. Available variants: ${Object.keys(config.variants).join(", ")}`
+            );
+        }
+
+        logger.debug("[MetaModelResolver] Resolved to override variant", {
+            variantName,
+            configName: variant.model,
+        });
+
+        return {
+            variantName,
+            variant,
+            configName: variant.model,
+            matchedKeywords: [],
+            systemPrompt: variant.systemPrompt,
+        };
+    }
+
+    /**
+     * Generate a system prompt fragment describing available variants.
+     * This helps the model understand what models are available and when to use them.
+     *
+     * @param config The meta model configuration
+     * @returns A system prompt fragment describing the variants
+     */
+    static generateSystemPromptFragment(config: MetaModelConfiguration): string {
+        const lines: string[] = [];
+
+        if (config.description) {
+            lines.push(config.description);
+            lines.push("");
+        }
+
+        lines.push("You have access to the following models via change_model() tool:");
+
+        for (const [variantName, variant] of Object.entries(config.variants)) {
+            const description = variant.description || `Model variant "${variantName}"`;
+            const keywords = variant.keywords?.length
+                ? ` (trigger: ${variant.keywords.join(", ")})`
+                : "";
+            lines.push(`* ${variantName}${keywords} → ${description}`);
+        }
+
+        return lines.join("\n");
+    }
+
+    /**
+     * Check if a configuration is a meta model configuration.
+     */
+    static isMetaModel(config: unknown): config is MetaModelConfiguration {
+        if (!config || typeof config !== "object") {
+            return false;
+        }
+        const c = config as Record<string, unknown>;
+        return c.provider === "meta" && typeof c.variants === "object" && typeof c.default === "string";
+    }
+}
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegExp(string: string): string {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/llm/meta/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Meta Model Module
+ *
+ * Provides dynamic model selection capabilities through "meta models".
+ * Meta models are virtual configurations that resolve to real models
+ * based on keywords in user messages.
+ *
+ * @module
+ */
+
+export { MetaModelResolver, type MetaModelResolution, type ResolveOptions } from "./MetaModelResolver";