@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/index.js

@@ -0,0 +1,1024 @@
+import { createCodingAgent as createMastraCodingAgent } from "@mastra/core/coding-agent";
+import { webFetchTool as mastraWebFetchTool, webSearchTool as mastraWebSearchTool, } from "@mastra/core/tools";
+import { openai, createOpenAI } from "@ai-sdk/openai";
+import { anthropic, createAnthropic } from "@ai-sdk/anthropic";
+import { google } from "@ai-sdk/google";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import fsNative from "fs";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { exec } from "child_process";
+import { fileURLToPath } from "url";
+import { promisify } from "util";
+export const getSkillsDir = () => {
+    if (typeof __dirname === "string") {
+        return path.resolve(__dirname, "..", "skills");
+    }
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
+};
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
+import { Memory } from "@mastra/memory";
+import { DEFAULT_LOCAL_RUNTIME_BASE_URL, DEFAULT_LOCAL_RUNTIME_API_KEY, isLocalModelId, } from "../library/localRuntime.js";
+// MY TOOLS
+import readFileTool from "./tools/readFile.js";
+import searchFilesTool from "./tools/searchFiles.js";
+import writeFileTool from "./tools/writeFile.js";
+import editFileTool from "./tools/editFile.js";
+import listDirectoryTool from "./tools/listDirectory.js";
+import grepSearchTool from "./tools/grepSearch.js";
+import runTerminalCommandTool from "./tools/runTerminalCommand.js";
+import deleteFileTool from "./tools/deleteFile.js";
+import createDirectoryTool from "./tools/createDirectory.js";
+import renameFileTool from "./tools/renameFile.js";
+import getWorkspaceInfoTool from "./tools/getWorkspaceInfo.js";
+import getSymbolsTool from "./tools/getSymbols.js";
+import applyDiffTool from "./tools/applyDiff.js";
+import findFileContentTool from "./tools/fileContent.js";
+import queryKnowledgeGraphTool from "./tools/queryKnowledgeGraph.js";
+// LSP-based tools for code intelligence
+import getTypeInfoTool from "./tools/getTypeInfo.js";
+import findDefinitionTool from "./tools/findDefinition.js";
+import findReferencesTool from "./tools/findReferences.js";
+import getSymbolsLSPTool from "./tools/getSymbolsLSP.js";
+import getCodeCompletionTool from "./tools/getCodeCompletion.js";
+import getSignatureHelpTool from "./tools/getSignatureHelp.js";
+import getCodeActionsTool from "./tools/getCodeActions.js";
+import renameSymbolTool from "./tools/renameSymbol.js";
+import formatDocumentTool from "./tools/formatDocument.js";
+import getWorkspaceSymbolsTool from "./tools/getWorkspaceSymbols.js";
+import { taskListTool, taskOutputTool, taskStopTool, } from "./tools/backgroundTasks.js";
+// Code context tool for VS Code Copilot-style responses
+import getCodeContextTool from "./tools/getCodeContext.js";
+import { StreamErrorRetryProcessor, } from "@mastra/core/processors";
+import { MultimodalTokenLimiterProcessor } from "./utils/multimodalTokenLimiter.js";
+import { coreLsp } from "../library/lsp/coreLsp.js";
+import { executeToolWithRecovery } from "./utils/errorRecovery.js";
+import { loadSkillsFromDirectories, } from "./utils/skillsDiscovery.js";
+import { resolveModelInputTokenLimit, resolveModelSupportsVision } from "../../helpers/promptBudget.js";
+// Browser-backed fallback for providers without native web search.
+import { webSearchTool as browserWebSearchTool } from "./tools/webSearch.js";
+//for skills to be called by the workspace
+import { Workspace, LocalFilesystem, } from "@mastra/core/workspace";
+import { RequestContext } from "@mastra/core/request-context";
+import { buildMcpTools, generateMcpToolsDocs } from "./tools/mcpTools.js";
+import { enforceToolCallBudgetForTools, } from "./utils/toolCallBudget.js";
+import { resolveOpenRouterModelSettings } from "./utils/openRouterModelSettings.js";
+import { ToolResultSafetyProcessor } from "./utils/toolResultSafetyProcessor.js";
+import { CapturedWorkspaceMutationBridge } from "./utils/capturedWorkspaceMutationBridge.js";
+import { rejectUnsafeWorkspaceMutation } from "./utils/workspacePathGuard.js";
+import { CODING_AGENT_INSTRUCTIONS, createIrisWorkspaceToolsConfig, } from "./publicContracts.js";
+export { CODING_AGENT_INSTRUCTIONS, createIrisWorkspaceToolsConfig, } from "./publicContracts.js";
+const withRuntimePreToolHook = (tools) => Object.fromEntries(Object.entries(tools).map(([toolName, tool]) => {
+    if (!tool ||
+        typeof tool !== "object" ||
+        typeof tool.execute !== "function") {
+        return [toolName, tool];
+    }
+    const originalExecute = tool.execute;
+    return [toolName, {
+            ...tool,
+            execute: async (input, context) => {
+                const requestContext = context?.requestContext;
+                const onPreToolUse = requestContext?.get?.("onPreToolUse");
+                await onPreToolUse?.({
+                    toolName,
+                    toolCallId: context?.toolCallId,
+                    toolArgs: input && typeof input === "object"
+                        ? input
+                        : undefined,
+                });
+                return originalExecute(input, context);
+            },
+        }];
+}));
+const execAsync = promisify(exec);
+const validationConfigCache = new Map();
+const isEnabledByEnv = (value, defaultValue) => {
+    if (value === undefined)
+        return defaultValue;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return defaultValue;
+};
+const DEFAULT_OBSERVATIONAL_MODEL = "google/gemini-2.5-flash";
+const DEFAULT_OBSERVATIONAL_SCOPE = "resource";
+const DEFAULT_OBSERVATION_MESSAGE_TOKENS = 4_000;
+const DEFAULT_REFLECTION_OBSERVATION_TOKENS = 8_000;
+const isMemoryEnabled = (value) => value !== false;
+const asBoundedInteger = (value, fallback, min, max) => {
+    const parsed = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number.parseInt(value, 10)
+            : Number.NaN;
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.trunc(parsed)));
+};
+const resolveObservationalMemoryOption = (enabledOverride, settingsOverride) => {
+    // Observational-memory mode is controlled by app settings forwarded per request.
+    // We intentionally avoid raw env fallback here to keep behavior user-scoped.
+    const enabled = typeof enabledOverride === "boolean" ? enabledOverride : false;
+    if (!enabled)
+        return false;
+    const modelRaw = settingsOverride?.model;
+    const model = typeof modelRaw === "string" && modelRaw.trim().length > 0
+        ? modelRaw.trim()
+        : DEFAULT_OBSERVATIONAL_MODEL;
+    const scope = settingsOverride?.scope === "thread" ? "thread" : DEFAULT_OBSERVATIONAL_SCOPE;
+    const messageTokens = asBoundedInteger(settingsOverride?.observationMessageTokens, DEFAULT_OBSERVATION_MESSAGE_TOKENS, 4_000, 200_000);
+    const observationTokens = asBoundedInteger(settingsOverride?.reflectionObservationTokens, DEFAULT_REFLECTION_OBSERVATION_TOKENS, 8_000, 400_000);
+    const previousObserverTokens = asBoundedInteger(settingsOverride?.observationPreviousTokens, 0, 0, 100_000);
+    const activateAfterIdle = typeof settingsOverride?.activateAfterIdle === "string"
+        ? settingsOverride.activateAfterIdle.trim()
+        : "";
+    const activateOnProviderChange = typeof settingsOverride?.activateOnProviderChange === "boolean"
+        ? settingsOverride.activateOnProviderChange
+        : true;
+    const observationalMemory = {
+        model,
+        scope,
+        activateOnProviderChange,
+    };
+    observationalMemory.observation = {
+        messageTokens,
+        previousObserverTokens,
+    };
+    observationalMemory.reflection = {
+        observationTokens,
+    };
+    if (activateAfterIdle) {
+        observationalMemory.activateAfterIdle = activateAfterIdle;
+    }
+    return observationalMemory;
+};
+const resolvePackageManager = async (basePath) => {
+    try {
+        await fs.access(path.join(basePath, "pnpm-lock.yaml"));
+        return "pnpm";
+    }
+    catch {
+        // Keep checking other lockfiles.
+    }
+    try {
+        await fs.access(path.join(basePath, "yarn.lock"));
+        return "yarn";
+    }
+    catch {
+        // Default fallback.
+    }
+    return "npm";
+};
+const buildScriptCommand = (packageManager, script) => {
+    if (packageManager === "yarn") {
+        return `yarn -s ${script}`;
+    }
+    if (packageManager === "pnpm") {
+        return `pnpm -s run ${script}`;
+    }
+    return `npm run --silent ${script}`;
+};
+const resolveValidationConfig = async (basePath) => {
+    if (validationConfigCache.has(basePath)) {
+        return validationConfigCache.get(basePath);
+    }
+    const config = {
+        autoLint: isEnabledByEnv(process.env.IRIS_AGENT_AUTO_LINT, false),
+        autoTest: isEnabledByEnv(process.env.IRIS_AGENT_AUTO_TEST, false),
+        lintCommand: process.env.IRIS_AGENT_LINT_CMD || undefined,
+        testCommand: process.env.IRIS_AGENT_TEST_CMD || undefined,
+    };
+    if ((!config.lintCommand && config.autoLint) || (!config.testCommand && config.autoTest)) {
+        try {
+            const packageManager = await resolvePackageManager(basePath);
+            const packageJsonPath = path.join(basePath, "package.json");
+            const packageJsonContent = await fs.readFile(packageJsonPath, "utf8");
+            const packageJson = JSON.parse(packageJsonContent);
+            const scripts = packageJson.scripts || {};
+            if (!config.lintCommand && config.autoLint && typeof scripts.lint === "string") {
+                config.lintCommand = buildScriptCommand(packageManager, "lint");
+            }
+            if (!config.testCommand && config.autoTest && typeof scripts.test === "string") {
+                config.testCommand = buildScriptCommand(packageManager, "test");
+            }
+        }
+        catch {
+            // No package.json or unreadable config; keep explicit env commands only.
+        }
+    }
+    validationConfigCache.set(basePath, config);
+    return config;
+};
+const runValidationCommand = async (command, cwd) => {
+    const start = Date.now();
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            cwd,
+            timeout: 120000,
+            maxBuffer: 1024 * 1024 * 8,
+            env: process.env,
+        });
+        return {
+            enabled: true,
+            command,
+            success: true,
+            stdout: String(stdout || "").trim(),
+            stderr: String(stderr || "").trim(),
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            enabled: true,
+            command,
+            success: false,
+            stdout: String(err.stdout || "").trim(),
+            stderr: String(err.stderr || "").trim(),
+            error: err.message,
+            durationMs: Date.now() - start,
+        };
+    }
+};
+const runPostEditValidation = async (basePath) => {
+    const config = await resolveValidationConfig(basePath);
+    const result = {};
+    if (config.autoLint) {
+        if (config.lintCommand) {
+            result.lint = await runValidationCommand(config.lintCommand, basePath);
+        }
+        else {
+            result.lint = {
+                enabled: true,
+                success: false,
+                stdout: "",
+                stderr: "",
+                error: "Auto lint enabled but no lint command could be resolved",
+            };
+        }
+    }
+    if (config.autoTest) {
+        if (config.testCommand) {
+            result.test = await runValidationCommand(config.testCommand, basePath);
+        }
+        else {
+            result.test = {
+                enabled: true,
+                success: false,
+                stdout: "",
+                stderr: "",
+                error: "Auto test enabled but no test command could be resolved",
+            };
+        }
+    }
+    return Object.keys(result).length > 0 ? result : null;
+};
+/**
+ * Get the appropriate AI model provider based on model ID
+ * @param {string} modelId - The model identifier (e.g., 'gpt-4o', 'claude-3-5-sonnet', 'gemini-pro')
+ * @returns {Object} AI SDK model instance
+ */
+const getModel = (modelId) => {
+    const anthropicBetaEnv = process.env.ANTHROPIC_BETA || process.env.ANTHROPIC_BETAS || "";
+    const anthropicBetaHeader = anthropicBetaEnv
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .join(",");
+    const anthropicProvider = anthropicBetaHeader
+        ? createAnthropic({
+            headers: {
+                "anthropic-beta": anthropicBetaHeader,
+            },
+        })
+        : null;
+    const normalizedModelId = modelId.endsWith("-other")
+        ? modelId.slice(0, -"-other".length)
+        : modelId;
+    const localBaseUrl = process.env.OLLAMA_BASE_URL || DEFAULT_LOCAL_RUNTIME_BASE_URL;
+    const localApiKey = process.env.OLLAMA_API_KEY || DEFAULT_LOCAL_RUNTIME_API_KEY;
+    const localOpenAICompatible = createOpenAI({
+        baseURL: localBaseUrl,
+        apiKey: localApiKey,
+    });
+    const isHuggingFaceModelId = (candidateModelId) => {
+        const normalized = (candidateModelId || "").toLowerCase();
+        if (!normalized)
+            return false;
+        if (normalized.startsWith("huggingface/"))
+            return true;
+        // Common HuggingFace router provider suffix (e.g. "...:fireworks-ai")
+        if (normalized.endsWith(":fireworks-ai"))
+            return true;
+        return false;
+    };
+    // HuggingFace Inference Router (OpenAI-compatible)
+    if (isHuggingFaceModelId(normalizedModelId)) {
+        const hfToken = process.env.HF_TOKEN;
+        if (!hfToken) {
+            throw new Error("HuggingFace token is not configured. Set HF_TOKEN in Settings and click Save API Keys.");
+        }
+        const hfClient = createOpenAI({
+            baseURL: "https://router.huggingface.co/v1",
+            apiKey: hfToken,
+        });
+        const cleanId = normalizedModelId.startsWith("huggingface/")
+            ? normalizedModelId.slice("huggingface/".length)
+            : normalizedModelId;
+        return hfClient.chat(cleanId);
+    }
+    const resolveOpenrouterModel = (candidateModelId) => {
+        const openrouterApiKey = process.env.OPENROUTER_API_KEY;
+        if (!openrouterApiKey) {
+            throw new Error("OpenRouter API key is not configured. Set OPENROUTER_API_KEY in Settings and click Save API Keys.");
+        }
+        const isOpenRouterDebugEnabled = process.env.NODE_ENV !== "production" &&
+            process.env.OPENROUTER_DEBUG_ECHO_UPSTREAM_BODY === "1";
+        const openrouter = createOpenRouter({
+            baseURL: process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1",
+            apiKey: openrouterApiKey,
+            // Optional attribution headers surface the app on OpenRouter leaderboards.
+            headers: {
+                "HTTP-Referer": process.env.OPENROUTER_SITE_URL || "https://github.com/4onstudios/iris-agent/",
+                "X-Title": process.env.OPENROUTER_SITE_NAME || "Iris",
+            },
+            ...(isOpenRouterDebugEnabled
+                ? {
+                    fetch: async (input, init) => {
+                        const body = init?.body;
+                        if (typeof body === "string") {
+                            try {
+                                const payload = JSON.parse(body);
+                                console.debug("[openrouter] validated outgoing request", {
+                                    model: payload.model,
+                                    messageCount: payload.messages?.length ?? 0,
+                                    toolCount: payload.tools?.length ?? 0,
+                                });
+                            }
+                            catch (error) {
+                                console.error("[openrouter] invalid outgoing JSON request", error);
+                            }
+                        }
+                        return fetch(input, init);
+                    },
+                }
+                : {}),
+        });
+        const openrouterAliasMap = {
+            "openai/gpt-latest": "openrouter/free",
+            "~openai/gpt-latest": "openrouter/free",
+        };
+        let resolvedOpenrouterModelId = openrouterAliasMap[candidateModelId] || candidateModelId;
+        const debugSettings = isOpenRouterDebugEnabled
+            ? { debug: { echo_upstream_body: true } }
+            : undefined;
+        // Free provider-specific routes are frequently burst-limited upstream.
+        // Route them through OpenRouter's free router to improve availability.
+        if (resolvedOpenrouterModelId.endsWith(":free")) {
+            resolvedOpenrouterModelId = "openrouter/free";
+        }
+        if (resolvedOpenrouterModelId !== candidateModelId) {
+            console.warn(`[agent] mapped OpenRouter model alias '${candidateModelId}' -> '${resolvedOpenrouterModelId}'`);
+        }
+        return openrouter.chat(resolvedOpenrouterModelId, {
+            ...(resolveOpenRouterModelSettings(resolvedOpenrouterModelId) ?? {}),
+            ...(debugSettings ?? {}),
+        });
+    };
+    // OpenRouter unified gateway (OpenAI-compatible). Model IDs are explicitly
+    // namespaced with an `openrouter/` prefix to avoid colliding with the
+    // provider-routing heuristics below (e.g. an OpenRouter slug like
+    // `google/gemini-2.0-flash` would otherwise be routed to Google directly).
+    if (normalizedModelId.startsWith("openrouter/")) {
+        const cleanId = normalizedModelId.slice("openrouter/".length);
+        return resolveOpenrouterModel(cleanId);
+    }
+    // Explicit direct-provider namespace support.
+    // These slugs should route to the corresponding provider rather than the
+    // OpenRouter slash-model fallback below.
+    if (normalizedModelId.startsWith("openai/")) {
+        const cleanId = normalizedModelId.slice("openai/".length);
+        return openai(cleanId);
+    }
+    if (normalizedModelId.startsWith("anthropic/")) {
+        const cleanId = normalizedModelId.slice("anthropic/".length);
+        if (anthropicBetaHeader) {
+            console.warn(`[agent] using anthropic-beta header: ${anthropicBetaHeader}`);
+            return anthropicProvider(cleanId);
+        }
+        return anthropic(cleanId);
+    }
+    // Some callers may already pass a raw OpenRouter slug (e.g. xiaomi/mimo-v2.5)
+    // without the `openrouter/` namespace. Treat these as OpenRouter models.
+    if (normalizedModelId.includes("/") &&
+        !isHuggingFaceModelId(normalizedModelId) &&
+        !normalizedModelId.startsWith("openai/") &&
+        !normalizedModelId.startsWith("anthropic/") &&
+        !normalizedModelId.startsWith("google/") &&
+        !normalizedModelId.startsWith("ollama/") &&
+        !normalizedModelId.startsWith("local/")) {
+        return resolveOpenrouterModel(normalizedModelId);
+    }
+    // USB-local or self-hosted OpenAI-compatible models (e.g. Ollama)
+    if (isLocalModelId(normalizedModelId)) {
+        const cleanId = normalizedModelId.startsWith("ollama/")
+            ? normalizedModelId.slice("ollama/".length)
+            : normalizedModelId.slice("local/".length);
+        return localOpenAICompatible(cleanId);
+    }
+    // Anthropic Claude models
+    if (normalizedModelId.startsWith("claude")) {
+        if (!process.env.ANTHROPIC_API_KEY && process.env.OPENROUTER_API_KEY) {
+            return resolveOpenrouterModel(`anthropic/${normalizedModelId}`);
+        }
+        if (anthropicBetaHeader) {
+            console.warn(`[agent] using anthropic-beta header: ${anthropicBetaHeader}`);
+            return anthropicProvider(normalizedModelId);
+        }
+        return anthropic(normalizedModelId);
+    }
+    // Google Gemini models
+    if (normalizedModelId.startsWith("gemini") || normalizedModelId.startsWith("google/")) {
+        if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY && !process.env.GEMINI_API_KEY && process.env.OPENROUTER_API_KEY) {
+            const cleanId = normalizedModelId.replace("google/", "");
+            return resolveOpenrouterModel(`google/${cleanId}`);
+        }
+        const cleanId = normalizedModelId.replace("google/", "");
+        return google(cleanId);
+    }
+    // OpenAI models (default)
+    if (normalizedModelId.startsWith("gpt") ||
+        normalizedModelId.startsWith("o1") ||
+        normalizedModelId.startsWith("o3")) {
+        if (!process.env.OPENAI_API_KEY && process.env.OPENROUTER_API_KEY) {
+            return resolveOpenrouterModel(`openai/${normalizedModelId}`);
+        }
+        return openai(normalizedModelId);
+    }
+    // Default to OpenRouter if OPENROUTER_API_KEY is present, else OpenAI
+    if (!process.env.OPENAI_API_KEY && process.env.OPENROUTER_API_KEY) {
+        return resolveOpenrouterModel(normalizedModelId);
+    }
+    console.warn(`Unknown model provider for '${normalizedModelId}', defaulting to OpenAI`);
+    return openai(normalizedModelId);
+};
+const supportsMastraProviderWebSearch = (modelId) => {
+    const normalizedModelId = modelId.endsWith("-other")
+        ? modelId.slice(0, -"-other".length)
+        : modelId;
+    if (isLocalModelId(normalizedModelId) ||
+        normalizedModelId.startsWith("openrouter/") ||
+        normalizedModelId.startsWith("hf/") ||
+        normalizedModelId.startsWith("huggingface/")) {
+        return false;
+    }
+    return (normalizedModelId.startsWith("gpt") ||
+        normalizedModelId.startsWith("o1") ||
+        normalizedModelId.startsWith("o3") ||
+        normalizedModelId.startsWith("openai/") ||
+        normalizedModelId.startsWith("claude") ||
+        normalizedModelId.startsWith("anthropic/") ||
+        normalizedModelId.startsWith("gemini") ||
+        normalizedModelId.startsWith("google/"));
+};
+const toFinitePositiveInt = (value, fallback) => {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const normalized = Math.floor(value);
+    return normalized > 0 ? normalized : fallback;
+};
+const parseOptionalBooleanEnv = (value) => {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return undefined;
+};
+const parseOptionalPositiveIntEnv = (value) => {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    const normalized = Math.floor(parsed);
+    return normalized > 0 ? normalized : undefined;
+};
+const resolveStreamErrorRetryConfig = (retryConfig) => {
+    if (retryConfig !== undefined) {
+        return retryConfig;
+    }
+    const enabled = parseOptionalBooleanEnv(process.env.IRIS_AGENT_STREAM_RETRY_ENABLED);
+    const retryUnknownErrors = parseOptionalBooleanEnv(process.env.IRIS_AGENT_STREAM_RETRY_UNKNOWN_ERRORS);
+    const maxRetries = parseOptionalPositiveIntEnv(process.env.IRIS_AGENT_STREAM_RETRY_MAX_RETRIES);
+    const baseDelayMs = parseOptionalPositiveIntEnv(process.env.IRIS_AGENT_STREAM_RETRY_BASE_DELAY_MS);
+    const maxDelayMs = parseOptionalPositiveIntEnv(process.env.IRIS_AGENT_STREAM_RETRY_MAX_DELAY_MS);
+    const fromEnv = {
+        enabled,
+        retryUnknownErrors,
+        maxRetries,
+        baseDelayMs,
+        maxDelayMs,
+    };
+    return Object.values(fromEnv).some((value) => value !== undefined)
+        ? fromEnv
+        : undefined;
+};
+const buildStreamErrorRetryProcessors = (retryConfig) => {
+    if (retryConfig === undefined) {
+        return undefined;
+    }
+    if (retryConfig.enabled === false) {
+        return [];
+    }
+    const maxRetries = toFinitePositiveInt(retryConfig.maxRetries, 3);
+    const baseDelayMs = toFinitePositiveInt(retryConfig.baseDelayMs, 800);
+    const maxDelayMs = toFinitePositiveInt(retryConfig.maxDelayMs, 30_000);
+    return [
+        new StreamErrorRetryProcessor({
+            maxRetries,
+            retryUnknownErrors: retryConfig.retryUnknownErrors === true,
+            delayMs: ({ retryCount }) => Math.min(baseDelayMs * 2 ** retryCount, maxDelayMs),
+        }),
+    ];
+};
+/**
+ * Module-level cache of all skill entries, populated lazily on the first call
+ * to `loadAllSkills` and retained for the lifetime of the process.
+ *
+ * **Intentional trade-off**: skills are bundled assets that change only on
+ * deploy, so re-reading the directory on every request would add unnecessary
+ * I/O with no practical benefit in production.
+ *
+ * If you need to invalidate the cache (e.g. in tests or during development
+ * hot-reload) call the exported `resetSkillsCache()` helper.
+ */
+let _allSkillsCache = null;
+/**
+ * Invalidate the in-process skills cache so that the next call to
+ * `loadAllSkills` / `buildSkillsBlock` re-reads the skills directory.
+ * Intended for use in tests and development hot-reload scenarios.
+ */
+export function resetSkillsCache() {
+    _allSkillsCache = null;
+}
+async function loadAllSkills() {
+    if (process.env.NODE_ENV === "production" && _allSkillsCache !== null)
+        return _allSkillsCache;
+    const skills = await loadSkillsFromDirectories([getSkillsDir()]);
+    _allSkillsCache = skills;
+    return skills;
+}
+const normalizeEnabledSkills = (enabledSkills) => {
+    if (!Array.isArray(enabledSkills)) {
+        return [];
+    }
+    const normalized = enabledSkills
+        .map((value) => (typeof value === "string" ? value.trim() : ""))
+        .filter((value) => /^[a-zA-Z0-9._-]{1,80}$/.test(value));
+    return Array.from(new Set(normalized));
+};
+const resolveAgentSkillPaths = async (enabledSkills) => {
+    const normalizedEnabledSkills = normalizeEnabledSkills(enabledSkills);
+    if (normalizedEnabledSkills.length === 0) {
+        return [];
+    }
+    const all = await loadAllSkills();
+    const pathsByName = new Map(all.map((skill) => [
+        skill.name,
+        path.join(getSkillsDir(), path.basename(path.dirname(skill.location))),
+    ]));
+    return normalizedEnabledSkills
+        .map((name) => pathsByName.get(name))
+        .filter((skillPath) => Boolean(skillPath));
+};
+export const createAgentRequestContext = (enabledSkills, requestValues) => {
+    const normalizedEnabledSkills = normalizeEnabledSkills(enabledSkills);
+    const context = new RequestContext([["enabledSkills", normalizedEnabledSkills]]);
+    // Request-scoped values (workspace, model, git state) belong here rather
+    // than in the prompt: they influence behavior without polluting memory.
+    for (const [key, value] of Object.entries(requestValues || {})) {
+        if (value !== undefined) {
+            context.set(key, value);
+        }
+    }
+    return context;
+};
+/**
+ * Return the canonical list of available skills for use by the
+ * `GET /api/agent/skills` endpoint. Each entry exposes the directory-name slug
+ * as `id` (matching what the client stores in preferences) and the description
+ * sourced directly from the SKILL.md frontmatter.
+ */
+export async function getSkillsList() {
+    const all = await loadAllSkills();
+    return all.map((s) => ({ id: s.name, description: s.description }));
+}
+/**
+ * Determine the appropriate database URL for Mastra Memory storage.
+ * - Desktop (Tauri): platform-specific app data directory (macOS: ~/Library/Application Support/AIRIS)
+ * - Web/Server: external database URL from env or shared data directory
+ * - Development: ./mastra.db (relative to cwd)
+ */
+function getDefaultDbUrl() {
+    const isTauriBundled = (() => {
+        const rawValue = process.env.TAURI_BUNDLED;
+        if (!rawValue)
+            return false;
+        const normalized = rawValue.trim().toLowerCase();
+        return normalized === "1" || normalized === "true" || normalized === "yes";
+    })();
+    // Desktop Tauri app: use platform-specific app data directory
+    if (isTauriBundled) {
+        let appDataDir;
+        if (process.platform === "darwin") {
+            // macOS: ~/Library/Application Support/AIRIS
+            appDataDir = path.join(os.homedir(), "Library", "Application Support", "AIRIS");
+        }
+        else if (process.platform === "win32") {
+            // Windows: %APPDATA%\AIRIS
+            appDataDir = path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "AIRIS");
+        }
+        else {
+            // Linux: ~/.local/share/airis
+            appDataDir = path.join(os.homedir(), ".local", "share", "airis");
+        }
+        // Ensure parent directory exists before SQLite opens/creates the DB file.
+        fsNative.mkdirSync(appDataDir, { recursive: true });
+        return `file:${path.join(appDataDir, "mastra.db")}`;
+    }
+    // Web/Server deployment: check for external database
+    if (process.env.DATABASE_URL) {
+        return process.env.DATABASE_URL;
+    }
+    // Development fallback
+    return "file:./mastra.db";
+}
+export const createCodingAgent = async (modelId = "gpt-4o", workspacePath = null, options = {}) => {
+    // Skip filesystem workspace init for virtual/web paths (e.g. /workspace/*)
+    // that don't exist on the server's filesystem. The web client provides file
+    // context for those sessions, while agent-level skills still come from the
+    // app-owned skills directory.
+    const isVirtualPath = workspacePath && workspacePath.startsWith("/workspace/");
+    const basePath = workspacePath || process.cwd();
+    const mcpServers = options.mcpServers || [];
+    const terminalAutoApproveRules = options.terminalAutoApproveRules;
+    const modelInputTokenLimit = resolveModelInputTokenLimit(modelId);
+    const modelSupportsVision = resolveModelSupportsVision(modelId);
+    const resolvedStreamErrorRetryConfig = resolveStreamErrorRetryConfig(options.streamErrorRetry);
+    const configuredErrorProcessors = buildStreamErrorRetryProcessors(resolvedStreamErrorRetryConfig);
+    const errorProcessorOverrides = configuredErrorProcessors === undefined
+        ? {}
+        : { errorProcessors: configuredErrorProcessors };
+    const observationalMemoryOption = resolveObservationalMemoryOption(options.useMastraObservationalMemory, options.observationalMemorySettings);
+    const goalJudgeModelId = options.goalJudgeModelId || process.env.IRIS_AGENT_GOAL_JUDGE_MODEL || modelId;
+    const workspaceMutationBridge = new CapturedWorkspaceMutationBridge(basePath, () => runPostEditValidation(basePath));
+    let workspace;
+    if (!isVirtualPath) {
+        try {
+            workspace = new Workspace({
+                // Provide concise, token-efficient filesystem guidance.
+                // Keep filesystem guidance focused on the available capabilities.
+                filesystem: new LocalFilesystem({
+                    basePath,
+                    instructions: "Use workspaceSearch for conceptual discovery, grepSearch for exact text, and readFile before editing. Use editFile with filePath plus oldContent/newContent for small exact replacements, writeFile for full-file changes, and applyDiff for multi-hunk patches. File mutations return reversible diff metadata for user review; validate focused changes before finishing.",
+                }),
+                bm25: true,
+                tools: createIrisWorkspaceToolsConfig(workspaceMutationBridge.hooks),
+            });
+            await workspace.init();
+            console.log("Workspace initialized");
+        }
+        catch (err) {
+            const error = err;
+            console.warn("⚠️ Workspace init failed, continuing without workspace:", error.message);
+        }
+    }
+    else {
+        console.log("⚠️ Virtual/web workspace detected — skipping filesystem initialization");
+    }
+    // Create a wrapped version of getWorkspaceInfo with the correct default path
+    const wrappedGetWorkspaceInfo = {
+        ...getWorkspaceInfoTool,
+        execute: async (params) => {
+            // FORCE the workspace path if it was provided to the factory
+            // The agent often hallucinates a path like "social-bot" or "my-project"
+            // We ignore params.workspacePath to prevent these errors
+            const actualParams = {
+                ...params,
+                workspacePath: workspacePath || process.cwd(),
+            };
+            // Use error recovery for workspace info tool
+            return executeToolWithRecovery(getWorkspaceInfoTool, actualParams, {
+                maxRetries: 2,
+                workspacePath: workspacePath || process.cwd(),
+            });
+        },
+    };
+    // Helper to resolve paths relative to workspace
+    const resolvePath = (p) => {
+        if (!p)
+            return p;
+        if (path.isAbsolute(p))
+            return p;
+        return path.join(workspacePath || process.cwd(), p);
+    };
+    // Helper to wrap tools with workspace path resolution AND error recovery
+    const wrapTool = (tool, 
+    // eslint-disable-next-line no-unused-vars
+    localExecute) => {
+        return {
+            ...tool,
+            execute: async (params) => 
+            // Wrap execution with error recovery
+            (await executeToolWithRecovery({
+                ...tool,
+                // eslint-disable-next-line no-unused-vars
+                execute: localExecute,
+            }, params, {
+                maxRetries: 2,
+                workspacePath: workspacePath || process.cwd(),
+            })),
+        };
+    };
+    // Wrap tools to ensure they use the correct workspace path
+    const workspaceBasePath = workspacePath || process.cwd();
+    const rejectOutsideWorkspaceMutation = (...filePaths) => rejectUnsafeWorkspaceMutation(workspaceBasePath, Boolean(isVirtualPath), filePaths);
+    const withPostEditValidation = async (result) => {
+        if (!result || result.success !== true) {
+            return result;
+        }
+        const validation = await runPostEditValidation(workspaceBasePath);
+        if (!validation) {
+            return result;
+        }
+        return {
+            ...result,
+            validation,
+        };
+    };
+    const wrappedReadFile = wrapTool(readFileTool, async (p) => readFileTool.execute({
+        ...p,
+        filePath: resolvePath(p.filePath),
+        workspaceRoot: p.workspaceRoot || workspacePath || process.cwd(),
+    }));
+    const wrappedWriteFile = wrapTool(writeFileTool, async (p) => {
+        const filePath = resolvePath(p.filePath);
+        const rejection = await rejectOutsideWorkspaceMutation(filePath);
+        if (rejection)
+            return rejection;
+        return withPostEditValidation(await writeFileTool.execute({ ...p, filePath }));
+    });
+    const wrappedEditFile = wrapTool(editFileTool, async (p) => {
+        const filePath = resolvePath(p.filePath);
+        const rejection = await rejectOutsideWorkspaceMutation(filePath);
+        if (rejection)
+            return rejection;
+        return withPostEditValidation(await editFileTool.execute({ ...p, filePath }));
+    });
+    const wrappedDeleteFile = wrapTool(deleteFileTool, async (p) => {
+        const filePath = resolvePath(p.filePath);
+        const rejection = await rejectOutsideWorkspaceMutation(filePath);
+        if (rejection)
+            return rejection;
+        return deleteFileTool.execute({ ...p, filePath });
+    });
+    const wrappedRenameFile = wrapTool(renameFileTool, async (p) => {
+        const oldPath = resolvePath(p.oldPath);
+        const newPath = resolvePath(p.newPath);
+        const rejection = await rejectOutsideWorkspaceMutation(oldPath, newPath);
+        if (rejection)
+            return rejection;
+        return renameFileTool.execute({ ...p, oldPath, newPath });
+    });
+    const wrappedListDirectory = wrapTool(listDirectoryTool, async (p) => listDirectoryTool.execute({ ...p, dirPath: resolvePath(p.dirPath) }));
+    const wrappedCreateDirectory = wrapTool(createDirectoryTool, async (p) => {
+        const dirPath = resolvePath(p.dirPath);
+        const rejection = await rejectOutsideWorkspaceMutation(dirPath);
+        if (rejection)
+            return rejection;
+        return createDirectoryTool.execute({ ...p, dirPath });
+    });
+    const wrappedGetSymbols = wrapTool(getSymbolsTool, async (p) => getSymbolsTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedApplyDiff = wrapTool(applyDiffTool, async (p) => {
+        const filePath = resolvePath(p.filePath);
+        const rejection = await rejectOutsideWorkspaceMutation(filePath);
+        if (rejection)
+            return rejection;
+        return withPostEditValidation(await applyDiffTool.execute({ ...p, filePath }));
+    });
+    const wrappedSearchFiles = wrapTool(searchFilesTool, async (p) => searchFilesTool.execute({ ...p, cwd: workspacePath || process.cwd() }));
+    const wrappedGrepSearch = wrapTool(grepSearchTool, async (p) => grepSearchTool.execute({ ...p, cwd: workspacePath || process.cwd() }));
+    const wrappedFindFileContent = wrapTool(findFileContentTool, async (p) => findFileContentTool.execute({
+        ...p,
+        rootFolder: workspacePath || process.cwd(),
+    }));
+    const wrappedQueryKnowledgeGraph = wrapTool(queryKnowledgeGraphTool, async (p) => queryKnowledgeGraphTool.execute({
+        ...p,
+        filePath: p.filePath ? resolvePath(p.filePath) : undefined,
+    }));
+    // LSP-based tools for code intelligence
+    const wrappedGetTypeInfo = wrapTool(getTypeInfoTool, async (p) => getTypeInfoTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedFindDefinition = wrapTool(findDefinitionTool, async (p) => findDefinitionTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedFindReferences = wrapTool(findReferencesTool, async (p) => findReferencesTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedGetSymbolsLSP = wrapTool(getSymbolsLSPTool, async (p) => getSymbolsLSPTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedGetCodeCompletion = wrapTool(getCodeCompletionTool, async (p) => getCodeCompletionTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedGetSignatureHelp = wrapTool(getSignatureHelpTool, async (p) => getSignatureHelpTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedGetCodeActions = wrapTool(getCodeActionsTool, async (p) => getCodeActionsTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedRenameSymbol = wrapTool(renameSymbolTool, async (p) => renameSymbolTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedFormatDocument = wrapTool(formatDocumentTool, async (p) => formatDocumentTool.execute({ ...p, filePath: resolvePath(p.filePath) }));
+    const wrappedGetWorkspaceSymbols = wrapTool(getWorkspaceSymbolsTool, async (p) => getWorkspaceSymbolsTool.execute(p));
+    // Wrap getCodeContext tool for VS Code Copilot-style responses
+    const wrappedGetCodeContext = {
+        ...getCodeContextTool,
+        execute: async (inputData, context) => {
+            const execute = getCodeContextTool.execute;
+            if (!execute) {
+                throw new Error("getCodeContext tool is unavailable");
+            }
+            return execute({ ...inputData, cwd: workspacePath || process.cwd() }, context);
+        },
+    };
+    // Keep browser search as a fallback for local, routed, and unsupported providers.
+    const wrappedBrowserWebSearch = wrapTool(browserWebSearchTool, async (p) => browserWebSearchTool.execute(p));
+    const resolvedWebSearchTool = supportsMastraProviderWebSearch(modelId)
+        ? mastraWebSearchTool
+        : wrappedBrowserWebSearch;
+    // Initialize LSP manager with workspace path
+    if (workspacePath) {
+        coreLsp.connect(workspacePath);
+    }
+    // Discover MCP tools once for this agent instance.
+    const mcpTools = await buildMcpTools(mcpServers, basePath);
+    console.log("🧩 MCP Tools registered:", Object.keys(mcpTools));
+    if (Object.keys(mcpTools).length > 0) {
+        console.log("✅ MCP tools available to agent:", Object.keys(mcpTools).join(", "));
+        // Persist MCP tool documentation to workspace for semantic search
+        // Only document connected servers; remove docs if no servers available
+        if (workspace && mcpServers.length > 0) {
+            const mcpDocsPath = path.join(basePath, ".mcp-tools.md");
+            try {
+                const mcpDocs = await generateMcpToolsDocs(mcpServers, basePath);
+                if (mcpDocs) {
+                    // Write documentation for connected servers
+                    await fs.writeFile(mcpDocsPath, mcpDocs, "utf8");
+                    console.log("📚 MCP tool documentation persisted to:", mcpDocsPath);
+                    console.log("🔍 MCP tools documentation ready for workspace queries");
+                }
+                else {
+                    // No connected servers - remove stale documentation if it exists
+                    try {
+                        await fs.unlink(mcpDocsPath);
+                        console.log("🗑️ Removed stale MCP documentation (no servers connected)");
+                    }
+                    catch (err) {
+                        // File might not exist, that's fine
+                    }
+                }
+            }
+            catch (err) {
+                const error = err;
+                console.warn("⚠️ Failed to persist MCP tool docs:", error.message);
+            }
+        }
+    }
+    else {
+        console.log("⚠️ No MCP tools registered (mcpServers:", mcpServers.length, ")");
+    }
+    // Wrap terminal command to use workspace path as cwd
+    const wrappedRunTerminalCommand = {
+        ...runTerminalCommandTool,
+        execute: async (params) => {
+            const actualParams = {
+                ...params,
+                cwd: params.cwd || workspacePath || process.cwd(),
+                workspaceRoot: params.workspaceRoot || workspacePath || process.cwd(),
+                autoApproveRules: params.autoApproveRules || terminalAutoApproveRules,
+            };
+            // Use error recovery for terminal commands (with extended timeout handling)
+            return executeToolWithRecovery(runTerminalCommandTool, actualParams, {
+                maxRetries: 1, // Fewer retries for terminal commands
+                workspacePath: workspacePath || process.cwd(),
+                timeout: params.timeout || 30000, // Default 30s timeout
+            });
+        },
+    };
+    const runtimeTools = withRuntimePreToolHook({
+        // Local workspaces provide these through Mastra Workspace under the
+        // established Iris names. Virtual workspaces retain the client-aware tools.
+        ...(workspace
+            ? {
+                writeFile: wrappedWriteFile,
+                editFile: wrappedEditFile,
+            }
+            : {
+                readFile: wrappedReadFile,
+                listDirectory: wrappedListDirectory,
+                grepSearch: wrappedGrepSearch,
+                writeFile: wrappedWriteFile,
+                editFile: wrappedEditFile,
+                deleteFile: wrappedDeleteFile,
+                createDirectory: wrappedCreateDirectory,
+            }),
+        searchFiles: wrappedSearchFiles,
+        renameFile: wrappedRenameFile,
+        getWorkspaceInfo: wrappedGetWorkspaceInfo,
+        findFileContent: wrappedFindFileContent,
+        getSymbols: wrappedGetSymbols,
+        runTerminalCommand: wrappedRunTerminalCommand,
+        applyDiff: wrappedApplyDiff,
+        queryKnowledgeGraph: wrappedQueryKnowledgeGraph,
+        getTypeInfo: wrappedGetTypeInfo,
+        findDefinition: wrappedFindDefinition,
+        findReferences: wrappedFindReferences,
+        getSymbolsLSP: wrappedGetSymbolsLSP,
+        getCodeCompletion: wrappedGetCodeCompletion,
+        getSignatureHelp: wrappedGetSignatureHelp,
+        getCodeActions: wrappedGetCodeActions,
+        renameSymbol: wrappedRenameSymbol,
+        formatDocument: wrappedFormatDocument,
+        getWorkspaceSymbols: wrappedGetWorkspaceSymbols,
+        getCodeContext: wrappedGetCodeContext,
+        taskList: taskListTool,
+        taskOutput: taskOutputTool,
+        taskStop: taskStopTool,
+        webSearch: resolvedWebSearchTool,
+        fetchWebpage: mastraWebFetchTool,
+        ...mcpTools,
+    });
+    const agent = createMastraCodingAgent({
+        id: options.id || "custom-coding-agent",
+        name: options.name || "Coding Agent",
+        skills: async ({ requestContext }) => {
+            const enabledSkills = requestContext
+                ?.get?.("enabledSkills");
+            return resolveAgentSkillPaths(enabledSkills);
+        },
+        instructions: CODING_AGENT_INSTRUCTIONS,
+        model: getModel(modelId),
+        workspace,
+        hooks: options.hooks,
+        tools: enforceToolCallBudgetForTools(runtimeTools),
+        // Add memory for conversation context with token-aware budgeting.
+        // TokenLimiterProcessor moved to inputProcessors (new Mastra API).
+        // Memory is on by default and can be disabled only via explicit options.
+        memory: isMemoryEnabled(options.enableMemory)
+            ? new Memory({
+                storage: new LibSQLStore({
+                    id: options.storageId || "custom-coding-agent-storage",
+                    url: options.dbUrl || getDefaultDbUrl(),
+                }),
+                options: {
+                    generateTitle: true,
+                    // Bounded conversation history: prioritize recent turns over full replay.
+                    // TokenLimiterProcessor enforces input token budget; lastMessages controls
+                    // max messages to keep in context before older turns are archived.
+                    lastMessages: 20,
+                    workingMemory: { enabled: true },
+                    // Compress long-running conversations into observations instead
+                    // of replaying full history. Opt-in until embedder/model costs
+                    // are validated for local setups.
+                    observationalMemory: observationalMemoryOption,
+                },
+                vector: new LibSQLVector({
+                    id: options.vectorId || "custom-coding-agent-vector",
+                    url: options.dbUrl || getDefaultDbUrl(),
+                }),
+            })
+            : undefined,
+        goal: isMemoryEnabled(options.enableMemory)
+            ? {
+                judge: getModel(goalJudgeModelId),
+                maxRuns: options.goalMaxRuns ?? 12,
+                maxSteps: 1,
+                prompt: "Mark the objective complete only when the requested implementation is complete and applicable validation has passed. Do not accept a plan, partial implementation, or an unsupported completion claim.",
+            }
+            : undefined,
+        // Token-aware budgeting: enforce model-specific input token limits.
+        // TokenLimiterProcessor limits input tokens; outputProcessors can compress output if needed.
+        inputProcessors: [new MultimodalTokenLimiterProcessor(modelInputTokenLimit, modelSupportsVision)],
+        outputProcessors: [workspaceMutationBridge, new ToolResultSafetyProcessor()],
+        // Keep helper defaults unless explicit retry overrides are provided.
+        ...errorProcessorOverrides,
+        // Default configuration
+        defaultOptions: {
+            maxSteps: options.maxSteps ?? 50,
+            toolChoice: options.toolChoice ?? "auto",
+            ...options.defaultOptions,
+        },
+    });
+    return Object.assign(agent, {
+        takeProcessedWorkspaceResults: (generationId, toolCallIds) => workspaceMutationBridge.takeProcessedResults(generationId, toolCallIds),
+        clearProcessedWorkspaceResults: (generationId) => workspaceMutationBridge.clearProcessedResults(generationId),
+    });
+};
+// createCodingAgent is the primary export. Callers should await it explicitly
+// rather than relying on a pre-initialized instance, to ensure environment
+// variables and database connections are ready before the agent is created.