@tenex-chat/backend 0.9.1

package/src/lib/fs/filesystem.ts

@@ -0,0 +1,128 @@
+import type { Stats } from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { formatAnyError } from "@/lib/error-formatter";
+
+/**
+ * Unified file system utilities combining patterns from CLI and shared packages
+ * Provides both sync and async operations with consistent error handling
+ *
+ * @module filesystem
+ * @description
+ * This module provides a comprehensive set of file system utilities with:
+ * - Path resolution and expansion (home directory ~)
+ * - Directory and file existence checks
+ * - JSON file read/write operations
+ * - Text file operations
+ * - Directory listing and management
+ * - File copying and deletion
+ * - Consistent error handling across all operations
+ */
+
+// File operations
+export async function readFile(filePath: string, encoding?: BufferEncoding): Promise<string>;
+export async function readFile(filePath: string, encoding: null): Promise<Buffer>;
+export async function readFile(
+    filePath: string,
+    encoding?: BufferEncoding | null
+): Promise<string | Buffer> {
+    return await fsPromises.readFile(filePath, encoding as BufferEncoding | null | undefined);
+}
+
+export function expandHome(filePath: string): string {
+    if (filePath.startsWith("~")) {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return filePath;
+}
+
+export function resolvePath(filePath: string): string {
+    return path.resolve(expandHome(filePath));
+}
+
+// Directory operations
+export async function ensureDirectory(dirPath: string): Promise<void> {
+    try {
+        await fsPromises.access(dirPath);
+    } catch (err: unknown) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            await fsPromises.mkdir(dirPath, { recursive: true });
+        } else {
+            throw err;
+        }
+    }
+}
+
+export async function directoryExists(dirPath: string): Promise<boolean> {
+    try {
+        const stat = await fsPromises.stat(dirPath);
+        return stat.isDirectory();
+    } catch (err: unknown) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return false;
+        }
+        throw err;
+    }
+}
+
+// Path existence check (works for both files and directories)
+export async function pathExists(filePath: string): Promise<boolean> {
+    try {
+        await fsPromises.access(filePath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// File operations
+export async function fileExists(filePath: string): Promise<boolean> {
+    try {
+        const stat = await fsPromises.stat(filePath);
+        return stat.isFile();
+    } catch (err: unknown) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return false;
+        }
+        throw err;
+    }
+}
+
+// JSON operations with error handling
+export async function readJsonFile<T>(filePath: string): Promise<T | null> {
+    try {
+        const content = await fsPromises.readFile(resolvePath(filePath), "utf-8");
+        return JSON.parse(content) as T;
+    } catch (err: unknown) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return null;
+        }
+        // Use console.error since lib/ layer should not depend on TENEX logger
+        console.error(`Failed to read JSON file ${filePath}: ${formatAnyError(err)}`);
+        throw err;
+    }
+}
+
+export async function writeJsonFile<T>(
+    filePath: string,
+    data: T,
+    options?: { spaces?: number }
+): Promise<void> {
+    const resolvedPath = resolvePath(filePath);
+    await ensureDirectory(path.dirname(resolvedPath));
+    const spaces = options?.spaces ?? 2;
+    await fsPromises.writeFile(resolvedPath, JSON.stringify(data, null, spaces));
+}
+
+// File stats
+export async function getFileStats(filePath: string): Promise<Stats | null> {
+    try {
+        return await fsPromises.stat(resolvePath(filePath));
+    } catch (err: unknown) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}

package/src/lib/fs/index.ts

@@ -0,0 +1 @@
+export * from "./filesystem.js";

package/src/lib/json-parser.ts

@@ -0,0 +1,30 @@
+/**
+ * Safely parse JSON with markdown code block cleanup
+ * @param text The text to parse, potentially containing markdown code blocks
+ * @param context Optional context for error logging
+ * @returns Parsed object or null if parsing fails
+ */
+export function safeParseJSON<T = unknown>(text: string, context?: string): T | null {
+    try {
+        // Clean up response - remove markdown code blocks if present
+        let cleanText = text.trim();
+
+        // Remove ```json or ``` wrapper if present
+        if (cleanText.startsWith("```json")) {
+            cleanText = cleanText.replace(/^```json\s*/, "").replace(/```\s*$/, "");
+        } else if (cleanText.startsWith("```")) {
+            cleanText = cleanText.replace(/^```\s*/, "").replace(/```\s*$/, "");
+        }
+
+        return JSON.parse(cleanText);
+    } catch (error) {
+        if (context) {
+            // Use console.error since lib/ should not depend on TENEX logger
+            console.error(`[JSON Parser] Failed to parse JSON in ${context}`, {
+                error: error instanceof Error ? error.message : String(error),
+                text: text.substring(0, 200),
+            });
+        }
+        return null;
+    }
+}

package/src/lib/string.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts a string to kebab-case format
+ * @param str - The input string to convert
+ * @returns The kebab-case formatted string
+ * @example
+ * toKebabCase("HelloWorld") // "hello-world"
+ * toKebabCase("hello_world") // "hello-world"
+ * toKebabCase("Hello World") // "hello-world"
+ */
+export function toKebabCase(str: string): string {
+    return str
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .toLowerCase();
+}

package/src/lib/time.ts

@@ -0,0 +1,74 @@
+/**
+ * Time formatting utilities
+ */
+
+/**
+ * Format a timestamp into a human-readable "time ago" string (long form)
+ * Example: "2 hours ago", "45 minutes ago"
+ */
+export function formatTimeAgo(timestamp: number): string {
+    const now = Date.now();
+    const diff = now - timestamp;
+    const seconds = Math.floor(diff / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const weeks = Math.floor(days / 7);
+    const months = Math.floor(days / 30);
+
+    if (months > 0) {
+        return `${months} month${months > 1 ? "s" : ""} ago`;
+    }
+    if (weeks > 0) {
+        return `${weeks} week${weeks > 1 ? "s" : ""} ago`;
+    }
+    if (days > 0) {
+        return `${days} day${days > 1 ? "s" : ""} ago`;
+    }
+    if (hours > 0) {
+        return `${hours} hour${hours > 1 ? "s" : ""} ago`;
+    }
+    if (minutes > 0) {
+        return `${minutes} minute${minutes > 1 ? "s" : ""} ago`;
+    }
+    if (seconds > 30) {
+        return `${seconds} seconds ago`;
+    }
+    return "just now";
+}
+
+/**
+ * Format a Unix timestamp (in seconds) into a short relative time string
+ * Example: "2h ago", "45m ago", "3d ago"
+ * @param timestampSeconds - Unix timestamp in seconds
+ */
+export function formatRelativeTimeShort(timestampSeconds: number): string {
+    const now = Math.floor(Date.now() / 1000);
+    const diff = now - timestampSeconds;
+
+    if (diff < 60) {
+        return "just now";
+    } else if (diff < 3600) {
+        const minutes = Math.floor(diff / 60);
+        return `${minutes}m ago`;
+    } else if (diff < 86400) {
+        const hours = Math.floor(diff / 3600);
+        return `${hours}h ago`;
+    } else {
+        const days = Math.floor(diff / 86400);
+        return `${days}d ago`;
+    }
+}
+
+/**
+ * Format uptime from a start time
+ */
+export function formatUptime(startTime: Date | null): string {
+    if (!startTime) return "N/A";
+    const now = new Date();
+    const diff = now.getTime() - startTime.getTime();
+    const hours = Math.floor(diff / 3600000);
+    const minutes = Math.floor((diff % 3600000) / 60000);
+    const seconds = Math.floor((diff % 60000) / 1000);
+    return `${hours}h ${minutes}m ${seconds}s`;
+}

package/src/llm/ChunkHandler.ts

@@ -0,0 +1,277 @@
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { trace } from "@opentelemetry/api";
+import type { TextStreamPart } from "ai";
+import type { EventEmitter } from "tseep";
+import { shouldIgnoreChunk } from "./chunk-validators";
+import type { LanguageModelUsageWithCostUsd, LLMServiceEventMap } from "./types";
+
+export interface ChunkHandlerState {
+    previousChunkType?: string;
+    cachedContentForComplete: string;
+    getCurrentStepUsage: () => LanguageModelUsageWithCostUsd | undefined;
+    getModelContextWindow: () => number | undefined;
+}
+
+/**
+ * Handles streaming chunks from the LLM.
+ * Extracted from LLMService to reduce file size.
+ */
+export class ChunkHandler {
+    private state: ChunkHandlerState;
+    private emitter: EventEmitter<LLMServiceEventMap>;
+
+    constructor(
+        emitter: EventEmitter<LLMServiceEventMap>,
+        state: ChunkHandlerState
+    ) {
+        this.emitter = emitter;
+        this.state = state;
+    }
+
+    /**
+     * Main entry point for handling incoming chunks
+     */
+    handleChunk(event: { chunk: TextStreamPart<Record<string, AISdkTool>> }): void {
+        const chunk = event.chunk;
+
+        // Validate chunk before any processing - some LLMs send chunks that should be ignored
+        if (shouldIgnoreChunk(chunk)) {
+            return;
+        }
+
+        // Emit raw-chunk event for consumers (e.g., local streaming)
+        logger.debug("[LLMService] emitting raw-chunk", { chunkType: chunk.type });
+        this.emitter.emit("raw-chunk", { chunk: event.chunk });
+
+        // Emit chunk-type-change event BEFORE processing the new chunk
+        // This allows listeners to flush buffers before new content of a different type arrives
+        if (this.state.previousChunkType !== undefined && this.state.previousChunkType !== chunk.type) {
+            this.emitter.emit("chunk-type-change", {
+                from: this.state.previousChunkType,
+                to: chunk.type,
+            });
+            // Clear cached content after emitting chunk-type-change.
+            // IMPORTANT: AgentExecutor listens to chunk-type-change and publishes the content
+            // buffer as a kind:1 event BEFORE this clearing happens. Without that publish,
+            // interim text (e.g., "I'll fetch that naddr...") would be lost.
+            // See: src/agents/execution/AgentExecutor.ts chunk-type-change handler
+            this.state.cachedContentForComplete = "";
+        }
+
+        // Update previousChunkType AFTER emitting the change event
+        this.state.previousChunkType = chunk.type;
+
+        switch (chunk.type) {
+            case "text-delta":
+                this.handleTextDelta(chunk.text);
+                break;
+            case "reasoning-delta": {
+                // Handle reasoning-delta separately - emit reasoning event
+                // The AI SDK may transform our custom reasoning-delta chunks
+                // to use 'text' property instead of 'delta'
+                interface ReasoningDeltaChunk {
+                    delta?: string;
+                    text?: string;
+                }
+                const reasoningChunk = chunk as ReasoningDeltaChunk;
+                const reasoningContent = reasoningChunk.delta || reasoningChunk.text;
+                if (reasoningContent) {
+                    this.handleReasoningDelta(reasoningContent);
+                }
+                break;
+            }
+            case "tool-call":
+                this.handleToolCall(chunk.toolCallId, chunk.toolName, chunk.input);
+                break;
+            case "tool-result":
+                this.handleToolResult(chunk.toolCallId, chunk.toolName, chunk.output);
+                break;
+            case "tool-error": {
+                this.handleToolError(chunk.toolCallId, chunk.toolName, chunk.error);
+                break;
+            }
+            case "tool-input-start":
+                // Tool input is starting to stream
+                trace.getActiveSpan()?.addEvent("llm.tool_input_start", {
+                    "tool.call_id": chunk.id,
+                    "tool.name": chunk.toolName,
+                });
+                break;
+            case "tool-input-delta":
+                // Tool input is being incrementally streamed - too verbose for traces
+                break;
+            case "reasoning-start":
+                trace.getActiveSpan()?.addEvent("llm.reasoning_start", {
+                    "reasoning.id": chunk.id,
+                });
+                break;
+            case "reasoning-end":
+                trace.getActiveSpan()?.addEvent("llm.reasoning_end", {
+                    "reasoning.id": chunk.id,
+                });
+                break;
+            case "error": {
+                // Extract detailed error information
+                const errorMsg =
+                    chunk.error instanceof Error ? chunk.error.message : String(chunk.error);
+                const errorStack = chunk.error instanceof Error ? chunk.error.stack : undefined;
+
+                logger.error("[LLMService] ❌ Error chunk received", {
+                    errorMessage: errorMsg,
+                    errorStack,
+                    errorType: chunk.error?.constructor?.name,
+                    fullError: chunk.error,
+                });
+                this.emitter.emit("stream-error", { error: chunk.error });
+                break;
+            }
+            default:
+                // Record unknown chunk types for debugging
+                trace.getActiveSpan()?.addEvent("llm.unknown_chunk_type", {
+                    "chunk.type": chunk.type,
+                });
+        }
+    }
+
+    private handleTextDelta(text: string): void {
+        this.emitter.emit("content", { delta: text });
+        this.state.cachedContentForComplete += text;
+    }
+
+    private handleReasoningDelta(text: string): void {
+        // Skip useless "[REDACTED]" reasoning events
+        if (text.trim() === "[REDACTED]") {
+            return;
+        }
+        this.emitter.emit("reasoning", { delta: text });
+    }
+
+    private handleToolCall(toolCallId: string, toolName: string, args: unknown): void {
+        trace.getActiveSpan()?.addEvent("llm.tool_will_execute", {
+            "tool.name": toolName,
+            "tool.call_id": toolCallId,
+        });
+        const usage = this.state.getCurrentStepUsage();
+        this.emitter.emit("tool-will-execute", {
+            toolName,
+            toolCallId,
+            args,
+            usage: usage
+                ? { ...usage, contextWindow: this.state.getModelContextWindow() }
+                : undefined,
+        });
+    }
+
+    private handleToolResult(toolCallId: string, toolName: string, result: unknown): void {
+        const hasError = isToolResultError(result);
+
+        if (hasError) {
+            const errorDetails = extractErrorDetails(result);
+            logger.error(`[LLMService] Tool '${toolName}' execution failed`, {
+                toolCallId,
+                toolName,
+                errorType: errorDetails?.type || "unknown",
+                errorMessage: errorDetails?.message || "No error details available",
+            });
+        }
+
+        trace.getActiveSpan()?.addEvent("llm.tool_did_execute", {
+            "tool.name": toolName,
+            "tool.call_id": toolCallId,
+            "tool.error": hasError,
+        });
+
+        this.emitter.emit("tool-did-execute", {
+            toolName,
+            toolCallId,
+            result,
+            error: hasError,
+        });
+    }
+
+    private handleToolError(toolCallId: string, toolName: string, error: unknown): void {
+        // Handle tool execution errors - emit as tool-did-execute with error flag
+        const errorMsg =
+            error instanceof Error ? error.message : String(error);
+        const errorStack = error instanceof Error ? (error as Error).stack : undefined;
+
+        logger.error(`[LLMService] Tool '${toolName}' threw an error`, {
+            toolCallId,
+            toolName,
+            error: errorMsg,
+            stack: errorStack,
+        });
+
+        // Log BOTH error event AND execution complete event for consistency
+        const activeSpan = trace.getActiveSpan();
+        activeSpan?.addEvent("llm.tool_error", {
+            "tool.name": toolName,
+            "tool.call_id": toolCallId,
+            "tool.error_message": errorMsg,
+            "tool.error_type": error?.constructor?.name || "Error",
+        });
+
+        // IMPORTANT: Also log tool_did_execute for error cases
+        // This ensures trace analysis can find tool completion regardless of success/failure
+        activeSpan?.addEvent("llm.tool_did_execute", {
+            "tool.name": toolName,
+            "tool.call_id": toolCallId,
+            "tool.error": true,
+            "tool.error_message": errorMsg.substring(0, 200),
+        });
+
+        // Emit tool-did-execute with error info so it gets persisted to conversation
+        // Format the error as a result object that the LLM can understand
+        this.emitter.emit("tool-did-execute", {
+            toolName,
+            toolCallId,
+            result: {
+                type: "error-text",
+                text: `Tool execution failed: ${errorMsg}`,
+            },
+            error: true,
+        });
+    }
+
+    /**
+     * Get the current cached content
+     */
+    getCachedContent(): string {
+        return this.state.cachedContentForComplete;
+    }
+
+    /**
+     * Clear the cached content
+     */
+    clearCachedContent(): void {
+        this.state.cachedContentForComplete = "";
+    }
+}
+
+/**
+ * Check if a tool result indicates an error
+ */
+function isToolResultError(result: unknown): boolean {
+    if (result && typeof result === "object") {
+        const obj = result as Record<string, unknown>;
+        return obj.type === "error-text" || obj.type === "error";
+    }
+    return false;
+}
+
+/**
+ * Extract error details from a tool result
+ */
+function extractErrorDetails(result: unknown): { type: string; message: string } | undefined {
+    if (result && typeof result === "object") {
+        const obj = result as Record<string, unknown>;
+        if (obj.type === "error-text" || obj.type === "error") {
+            return {
+                type: String(obj.type),
+                message: String(obj.text || obj.message || "Unknown error"),
+            };
+        }
+    }
+    return undefined;
+}