@tenex-chat/backend 0.9.1

package/src/index.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+
+// TENEX CLI Entry Point
+// This is a CLI application - NOT a library. Zero exports.
+
+// MUST BE FIRST - Initialize OpenTelemetry before any other imports
+// Read config synchronously to check telemetry setting before importing anything else
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { initializeTelemetry } from "@/telemetry/setup";
+
+/**
+ * Get the base TENEX directory path for early initialization.
+ * Respects TENEX_BASE_DIR environment variable for running multiple isolated instances.
+ * This is a minimal inline version used before other imports are available.
+ */
+function getBasePath(): string {
+    return process.env.TENEX_BASE_DIR || join(homedir(), ".tenex");
+}
+
+interface TelemetryConfig {
+    enabled: boolean;
+    serviceName: string;
+    endpoint: string;
+}
+
+function getTelemetryConfig(): TelemetryConfig {
+    const configPath = join(getBasePath(), "config.json");
+    const defaults: TelemetryConfig = {
+        enabled: true,
+        serviceName: "tenex-daemon",
+        endpoint: "http://localhost:4318/v1/traces",
+    };
+
+    if (!existsSync(configPath)) return defaults;
+    try {
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        return {
+            enabled: config.telemetry?.enabled !== false,
+            serviceName: config.telemetry?.serviceName || defaults.serviceName,
+            endpoint: config.telemetry?.endpoint || defaults.endpoint,
+        };
+    } catch (error) {
+        // Issue #6: Make config parse errors visible to users
+        console.warn(`[TENEX] Warning: Failed to parse config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+        return defaults; // default on parse error
+    }
+}
+
+// Initialize telemetry before any other imports
+const telemetryConfig = getTelemetryConfig();
+initializeTelemetry(telemetryConfig.enabled, telemetryConfig.serviceName, telemetryConfig.endpoint);
+
+// Main execution - all imports happen AFTER telemetry is initialized
+// This ensures OpenTelemetry can properly instrument all imported modules
+async function main(): Promise<void> {
+    // Issue #1 & #4: Dynamic imports after telemetry initialization, using @/ aliases
+    const [
+        { Command },
+        { getHeuristicEngine, getDefaultHeuristics },
+        { daemonCommand },
+        { setupCommand },
+        { doctorCommand },
+        { agentCommand },
+        { handleCliError },
+    ] = await Promise.all([
+        import("commander"),
+        import("@/services/heuristics"),
+        import("@/commands/daemon"),
+        import("@/commands/setup/index"),
+        import("@/commands/doctor"),
+        import("@/commands/agent"),
+        import("@/utils/cli-error"),
+    ]);
+
+    // Initialize heuristics system with default rules
+    const heuristicEngine = getHeuristicEngine({
+        debug: process.env.DEBUG_HEURISTICS === "true",
+    });
+    for (const heuristic of getDefaultHeuristics()) {
+        heuristicEngine.register(heuristic);
+    }
+
+    // CLI setup
+    const program = new Command();
+
+    // Issue #5: Use npm_package_version with fallback
+    program
+        .name("tenex")
+        .description("TENEX Command Line Interface")
+        .version(process.env.npm_package_version || "0.8.0");
+
+    // Register subcommands
+    program.addCommand(daemonCommand);
+    program.addCommand(setupCommand);
+    program.addCommand(doctorCommand);
+    program.addCommand(agentCommand);
+
+    // Issue #2: Enable exitOverride so errors are thrown instead of calling process.exit
+    program.exitOverride();
+
+    try {
+        // Issue #2: Use parseAsync to properly catch async command errors
+        await program.parseAsync(process.argv);
+    } catch (error) {
+        // Commander throws CommanderError for --help, --version, and actual errors
+        // Check if it's a "help" or "version" exit - these are not real errors
+        if (
+            error instanceof Error &&
+            "code" in error &&
+            (error.code === "commander.helpDisplayed" || error.code === "commander.version")
+        ) {
+            // Normal exit for help/version - exit cleanly
+            process.exit(0);
+        }
+        handleCliError(error, "Fatal error in TENEX CLI");
+    }
+}
+
+// Execute CLI - this is an application, not a library
+main().catch((error) => {
+    // Fallback error handler for errors during dynamic imports
+    console.error("Fatal error during TENEX CLI initialization:", error);
+    process.exit(1);
+});

package/src/lib/agent-home.ts

@@ -0,0 +1,334 @@
+import { mkdirSync, readdirSync, realpathSync, existsSync, lstatSync, openSync, readSync, closeSync, constants as fsConstants } from "node:fs";
+import { isAbsolute, join, normalize, relative, resolve, dirname } from "node:path";
+import { getTenexBasePath } from "@/constants";
+import { logger } from "@/utils/logger";
+
+/**
+ * Error thrown when a path escapes the agent's home directory scope.
+ */
+export class HomeScopeViolationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "HomeScopeViolationError";
+    }
+}
+
+/**
+ * Maximum number of +prefixed files to inject into system prompt.
+ * Prevents prompt bloat if an agent creates many files.
+ */
+const MAX_INJECTED_FILES = 10;
+
+/**
+ * Maximum content length for injected files before truncation.
+ */
+const MAX_INJECTED_FILE_LENGTH = 1500;
+
+/**
+ * Represents a file to be injected into the agent's system prompt.
+ */
+export interface InjectedFile {
+    filename: string;
+    content: string;
+    truncated: boolean;
+}
+
+/**
+ * Get the short pubkey (first 8 characters) for an agent.
+ */
+function getShortPubkey(pubkey: string): string {
+    return pubkey.slice(0, 8);
+}
+
+/**
+ * Get the home directory path for an agent.
+ * This is the canonical source of truth for agent home directory paths.
+ */
+export function getAgentHomeDirectory(agentPubkey: string): string {
+    const shortPubkey = getShortPubkey(agentPubkey);
+    return join(getTenexBasePath(), "home", shortPubkey);
+}
+
+/**
+ * Normalize and resolve a path to prevent path traversal attacks.
+ * Resolves .., ., and normalizes the path to an absolute form.
+ * @param inputPath - The path to normalize (should be absolute)
+ * @returns The normalized absolute path
+ */
+export function normalizePath(inputPath: string): string {
+    // Resolve handles .., ., and makes the path absolute
+    const resolved = resolve(inputPath);
+    // Normalize handles redundant separators
+    return normalize(resolved);
+}
+
+/**
+ * Safely call realpathSync, returning null if it fails due to permissions or other errors.
+ */
+function safeRealpathSync(path: string): string | null {
+    try {
+        return realpathSync(path);
+    } catch {
+        // Permission denied, or other errors - fall back to normalized path
+        return null;
+    }
+}
+
+/**
+ * Resolve the real path of a file or directory, following symlinks.
+ * If the path doesn't exist, resolves the parent directory and appends the filename.
+ * This ensures symlinks are resolved even for files that will be created.
+ * Falls back to normalized path if realpath resolution fails (e.g., permission denied).
+ * @param inputPath - The path to resolve
+ * @returns The resolved real path with symlinks followed
+ */
+function resolveRealPath(inputPath: string): string {
+    const normalized = normalizePath(inputPath);
+
+    // If the path exists, resolve it directly
+    if (existsSync(normalized)) {
+        const realPath = safeRealpathSync(normalized);
+        return realPath ?? normalized;
+    }
+
+    // Path doesn't exist - resolve the parent directory instead
+    // This catches symlinks in the parent chain
+    const parentDir = dirname(normalized);
+    const filename = normalized.slice(parentDir.length + 1); // Get the filename portion
+
+    if (existsSync(parentDir)) {
+        const realParent = safeRealpathSync(parentDir);
+        return realParent ? join(realParent, filename) : normalized;
+    }
+
+    // Neither path nor parent exists - walk up until we find an existing ancestor
+    let currentPath = parentDir;
+    const pathParts: string[] = [filename];
+
+    while (currentPath && currentPath !== dirname(currentPath)) {
+        const parent = dirname(currentPath);
+        pathParts.unshift(currentPath.slice(parent.length + 1));
+        currentPath = parent;
+
+        if (existsSync(currentPath)) {
+            const realAncestor = safeRealpathSync(currentPath);
+            return realAncestor ? join(realAncestor, ...pathParts) : normalized;
+        }
+    }
+
+    // No ancestor exists, return normalized path as-is
+    return normalized;
+}
+
+/**
+ * Check if a path is within a given directory.
+ * Both paths are normalized and symlinks are resolved to prevent escape attacks.
+ * Uses path.relative for cross-platform separator handling.
+ * @param inputPath - The path to check (will be normalized, symlinks resolved)
+ * @param directory - The directory to check against (will be normalized, symlinks resolved)
+ * @returns true if path is within or equal to directory
+ */
+export function isPathWithinDirectory(inputPath: string, directory: string): boolean {
+    // Resolve symlinks to prevent symlink escape attacks
+    const realPath = resolveRealPath(inputPath);
+    const realDir = resolveRealPath(directory);
+
+    // Use path.relative for cross-platform handling
+    // If the relative path starts with ".." or is absolute, the path is outside
+    const relativePath = relative(realDir, realPath);
+
+    // Path is within directory if:
+    // 1. It doesn't start with ".." (would mean escaping the directory)
+    // 2. It's not absolute (would mean completely different path on Windows)
+    // 3. Empty string means it's the same directory
+    return !relativePath.startsWith("..") && !isAbsolute(relativePath);
+}
+
+/**
+ * Check if a path is within the agent's home directory.
+ * Normalizes the input path to prevent path traversal attacks.
+ * Used by filesystem tools to grant automatic access to agent's own home.
+ */
+export function isWithinAgentHome(inputPath: string, agentPubkey: string): boolean {
+    const homeDir = getAgentHomeDirectory(agentPubkey);
+    return isPathWithinDirectory(inputPath, homeDir);
+}
+
+/**
+ * Ensure the agent's home directory exists.
+ * Creates it if it doesn't exist.
+ * @returns true if directory exists or was created, false if creation failed
+ */
+export function ensureAgentHomeDirectory(agentPubkey: string): boolean {
+    const homeDir = getAgentHomeDirectory(agentPubkey);
+    try {
+        mkdirSync(homeDir, { recursive: true });
+        return true;
+    } catch (error) {
+        console.error("Failed to create agent home dir:", error);
+        return false;
+    }
+}
+
+/**
+ * Maximum file size to read for injected files (prevents memory spikes).
+ * We only need first MAX_INJECTED_FILE_LENGTH chars, so read slightly more to detect truncation.
+ */
+const MAX_INJECTED_FILE_READ_SIZE = MAX_INJECTED_FILE_LENGTH + 100;
+
+/**
+ * Read a bounded amount from a file safely, preventing symlink attacks and memory spikes.
+ * Uses lstat + realpath validation and bounded reads.
+ *
+ * @param filePath - Path to the file
+ * @param homeDir - The home directory (for containment validation)
+ * @param maxBytes - Maximum bytes to read
+ * @returns Object with content and whether it was truncated, or null if file should be skipped
+ */
+function safeReadBoundedFile(
+    filePath: string,
+    homeDir: string,
+    maxBytes: number
+): { content: string; truncated: boolean; fileSize: number } | null {
+    try {
+        // TOCTOU protection: Use lstat (not stat) to check actual file type without following symlinks
+        const lstats = lstatSync(filePath);
+
+        // Skip symlinks entirely (security: prevents symlink race attacks)
+        if (lstats.isSymbolicLink()) {
+            logger.warn(`Skipping symlink in agent home: ${filePath}`);
+            return null;
+        }
+
+        // Skip if not a regular file
+        if (!lstats.isFile()) {
+            return null;
+        }
+
+        // Additional safety: verify realpath is within home directory
+        // This catches any edge cases where the file might resolve outside home
+        const realPath = realpathSync(filePath);
+        const realHomeDir = realpathSync(homeDir);
+        const relativePath = relative(realHomeDir, realPath);
+        if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+            logger.warn(`Skipping file that resolves outside home: ${filePath} -> ${realPath}`);
+            return null;
+        }
+
+        const fileSize = lstats.size;
+
+        // Bounded read: Only read what we need to prevent memory spikes
+        const bytesToRead = Math.min(fileSize, maxBytes);
+        const buffer = Buffer.alloc(bytesToRead);
+
+        // Use low-level open/read for precise control
+        const fd = openSync(filePath, fsConstants.O_RDONLY);
+        try {
+            const bytesRead = readSync(fd, buffer, 0, bytesToRead, 0);
+            const content = buffer.slice(0, bytesRead).toString("utf-8");
+            const truncated = fileSize > maxBytes;
+
+            return { content, truncated, fileSize };
+        } finally {
+            closeSync(fd);
+        }
+    } catch (error) {
+        // File may have been deleted/changed between lstat and read - that's OK
+        logger.warn(`Failed to safely read file ${filePath}:`, error);
+        return null;
+    }
+}
+
+/**
+ * Get files in the agent's home directory that start with '+' prefix.
+ * These files are auto-injected into the agent's system prompt.
+ *
+ * Security:
+ * - Only reads regular files (skips symlinks and directories)
+ * - Uses lstat + realpath validation to prevent TOCTOU/symlink race attacks
+ * - Bounded reads to prevent memory spikes from large files
+ *
+ * Limits: Max 10 files, max 1500 chars per file (truncated if longer).
+ *
+ * @param agentPubkey - The agent's pubkey
+ * @returns Array of injected file objects with filename, content, and truncated flag
+ */
+export function getAgentHomeInjectedFiles(agentPubkey: string): InjectedFile[] {
+    const homeDir = getAgentHomeDirectory(agentPubkey);
+
+    // Ensure directory exists
+    if (!ensureAgentHomeDirectory(agentPubkey)) {
+        return [];
+    }
+
+    try {
+        const entries = readdirSync(homeDir, { withFileTypes: true });
+
+        // Filter for +prefixed entries that appear to be files
+        // Note: We re-validate each file before reading due to TOCTOU concerns
+        const plusCandidates = entries
+            .filter((entry) => entry.name.startsWith("+") && entry.isFile())
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .slice(0, MAX_INJECTED_FILES);
+
+        const injectedFiles: InjectedFile[] = [];
+
+        for (const entry of plusCandidates) {
+            const filePath = join(homeDir, entry.name);
+
+            // Use safe bounded read with TOCTOU protection
+            const result = safeReadBoundedFile(filePath, homeDir, MAX_INJECTED_FILE_READ_SIZE);
+            if (!result) {
+                continue; // Skip files that couldn't be safely read
+            }
+
+            // Apply the content length limit
+            const truncated = result.content.length > MAX_INJECTED_FILE_LENGTH || result.truncated;
+            const content = result.content.slice(0, MAX_INJECTED_FILE_LENGTH);
+
+            injectedFiles.push({
+                filename: entry.name,
+                content,
+                truncated,
+            });
+        }
+
+        return injectedFiles;
+    } catch (error) {
+        logger.warn("Failed to scan agent home for injected files:", error);
+        return [];
+    }
+}
+
+/**
+ * Resolve a path that must be within the agent's home directory.
+ * Accepts both relative paths (resolved against home) and absolute paths.
+ *
+ * Security: Uses isPathWithinDirectory() which handles symlinks and path traversal.
+ *
+ * @param inputPath - Relative or absolute path
+ * @param agentPubkey - The agent's pubkey
+ * @returns The resolved absolute path within the agent's home
+ * @throws HomeScopeViolationError if path escapes home directory
+ */
+export function resolveHomeScopedPath(inputPath: string, agentPubkey: string): string {
+    const homeDir = getAgentHomeDirectory(agentPubkey);
+
+    // Ensure home directory exists
+    ensureAgentHomeDirectory(agentPubkey);
+
+    // Resolve path: treat relative paths as relative to home directory
+    const resolvedPath = isAbsolute(inputPath)
+        ? inputPath
+        : join(homeDir, inputPath);
+
+    // Validate the resolved path is within home directory
+    if (!isPathWithinDirectory(resolvedPath, homeDir)) {
+        throw new HomeScopeViolationError(
+            `Path "${inputPath}" is outside your home directory. ` +
+            `You can only access files within your home directory.`
+        );
+    }
+
+    return resolvedPath;
+}

package/src/lib/error-formatter.ts

@@ -0,0 +1,200 @@
+// ToolError removed - define it locally if needed
+interface ToolError {
+    kind: "validation" | "execution" | "system";
+    message: string;
+    field?: string;
+    tool?: string;
+}
+
+/**
+ * Comprehensive error formatter that handles all error types in the codebase
+ * Consolidates error formatting logic from various parts of the system
+ */
+export function formatAnyError(error: unknown): string {
+    // Handle null/undefined
+    if (error == null) {
+        return "Unknown error";
+    }
+
+    // Handle strings
+    if (typeof error === "string") {
+        return error;
+    }
+
+    // Handle Error instances
+    if (error instanceof Error) {
+        return error.message;
+    }
+
+    // Handle objects
+    if (typeof error === "object") {
+        const errorObj = error as Record<string, unknown>;
+
+        // Check for ToolError structure (with type guard)
+        if ("kind" in errorObj && "message" in errorObj) {
+            const kind = errorObj.kind;
+            if (kind === "validation" || kind === "execution" || kind === "system") {
+                return formatToolError(errorObj as unknown as ToolError);
+            }
+        }
+
+        // Check for simple message property
+        if ("message" in errorObj && typeof errorObj.message === "string") {
+            return errorObj.message;
+        }
+
+        // Try to extract meaningful properties from the error object
+        const parts: string[] = [];
+
+        // Common error properties
+        if ("kind" in errorObj) parts.push(`kind: ${errorObj.kind}`);
+        if ("field" in errorObj) parts.push(`field: ${errorObj.field}`);
+        if ("tool" in errorObj) parts.push(`tool: ${errorObj.tool}`);
+        if ("code" in errorObj) parts.push(`code: ${errorObj.code}`);
+        if ("statusCode" in errorObj) parts.push(`statusCode: ${errorObj.statusCode}`);
+        if ("errno" in errorObj) parts.push(`errno: ${errorObj.errno}`);
+        if ("syscall" in errorObj) parts.push(`syscall: ${errorObj.syscall}`);
+
+        // If we found specific properties, use them
+        if (parts.length > 0) {
+            return parts.join(", ");
+        }
+
+        // Otherwise, try to stringify the object
+        try {
+            const str = JSON.stringify(error);
+            // Don't return huge JSON strings
+            if (str.length > 200) {
+                return "[Complex Error Object]";
+            }
+            return str;
+        } catch {
+            return "[Complex Error Object]";
+        }
+    }
+
+    // Fallback to String conversion
+    return String(error);
+}
+
+/**
+ * Format ToolError objects into human-readable strings
+ */
+export function formatToolError(error: ToolError): string {
+    switch (error.kind) {
+        case "validation":
+            // If the field is empty and message is just "Required", make it clearer
+            if (error.field === "" && error.message === "Required") {
+                return "Validation error: Missing required parameter";
+            }
+            return error.field
+                ? `Validation error in ${error.field}: ${error.message}`
+                : `Validation error: ${error.message}`;
+        case "execution":
+            return error.tool
+                ? `Execution error in ${error.tool}: ${error.message}`
+                : `Execution error: ${error.message}`;
+        case "system":
+            return `System error: ${error.message}`;
+        default: {
+            // This should never happen with proper ToolError types
+            const unknownError = error as unknown as Record<string, unknown>;
+            return (
+                (typeof unknownError.message === "string" ? unknownError.message : null) ||
+                "Unknown error"
+            );
+        }
+    }
+}
+
+// Constants for AI error markers
+const AI_API_CALL_ERROR = "AI_APICallError";
+const PROVIDER_RETURNED_ERROR = "Provider returned error";
+const OPENROUTER_MARKER = "openrouter";
+const HTTP_422_STATUS = "422";
+
+/**
+ * Generic prefixes that indicate the message itself is not meaningful
+ * and we should try to extract details from toString() instead.
+ * These will be checked with startsWith, so "AI_APICallError" will match
+ * "AI_APICallError: some details" etc.
+ */
+const GENERIC_ERROR_PREFIXES = [
+    AI_API_CALL_ERROR,
+    PROVIDER_RETURNED_ERROR,
+    HTTP_422_STATUS,
+    "Unprocessable Entity",
+    "Error:",
+] as const;
+
+/**
+ * Check if an error message is meaningful enough to use directly,
+ * or if it's a generic wrapper that requires regex extraction for details.
+ *
+ * A message is considered "meaningful" if:
+ * 1. It's not empty
+ * 2. It doesn't start with any known generic prefix
+ * 3. It's not just the error class name
+ */
+export function isMeaningfulAiMessage(message: string | undefined): boolean {
+    if (!message || message.trim() === "") {
+        return false;
+    }
+
+    const trimmedMessage = message.trim();
+
+    // Check if message starts with any generic prefix
+    for (const prefix of GENERIC_ERROR_PREFIXES) {
+        if (trimmedMessage.startsWith(prefix)) {
+            return false;
+        }
+    }
+
+    // Check for HTTP status code patterns (e.g., "422", "500 Internal Server Error")
+    if (/^\d{3}\b/.test(trimmedMessage)) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Format error for stream/execution errors from LLM providers
+ */
+export function formatStreamError(error: unknown): { message: string; errorType: string } {
+    let errorMessage = "An error occurred while processing your request.";
+    let errorType = "system";
+
+    if (error instanceof Error) {
+        const errorStr = error.toString();
+        if (
+            errorStr.includes(AI_API_CALL_ERROR) ||
+            errorStr.includes(PROVIDER_RETURNED_ERROR) ||
+            errorStr.includes(HTTP_422_STATUS) ||
+            errorStr.includes(OPENROUTER_MARKER)
+        ) {
+            errorType = "ai_api";
+
+            // Check if error.message is meaningful (not a generic wrapper)
+            // Claude Code errors often have the real error in error.message
+            if (isMeaningfulAiMessage(error.message)) {
+                errorMessage = `AI Error: ${error.message}`;
+            } else {
+                // Fall back to regex extraction for OpenRouter-style errors
+                const providerMatch = errorStr.match(/provider_name":"([^"]+)"/);
+                const provider = providerMatch ? providerMatch[1] : "AI provider";
+                errorMessage = `Failed to process request with ${provider}. The AI service returned an error.`;
+
+                // Add raw error details if available
+                const rawMatch = errorStr.match(/raw":"([^"]+)"/);
+                if (rawMatch) {
+                    errorMessage += ` Details: ${rawMatch[1]}`;
+                }
+            }
+        } else {
+            errorMessage = `Error: ${error.message}`;
+        }
+    }
+
+    return { message: errorMessage, errorType };
+}