@4onstudios/iris-agent 0.1.0

package/dist/api/core/library/languageModelTools.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Language Model Tools API
+ * VS Code-compatible API for registering and managing language model tools
+ */
+import { EventEmitter } from "events";
+import type { McpServerConfig } from "./mcpSettings.js";
+/**
+ * Represents a tool that can be invoked by a language model
+ */
+export interface LanguageModelToolInformation {
+    /** Unique tool name */
+    readonly name: string;
+    /** Description for language model */
+    readonly description: string;
+    /** JSON schema for input validation */
+    readonly inputSchema?: object;
+    /** Tags for categorization */
+    readonly tags: readonly string[];
+    /** Source of the tool (mcp, native, etc.) */
+    readonly source: string;
+}
+/**
+ * Options for tool invocation
+ */
+export interface LanguageModelToolInvocationOptions<T = unknown> {
+    /** Tool input matching the schema */
+    input: T;
+    /** Optional token budget hints */
+    tokenizationOptions?: {
+        tokenBudget: number;
+        countTokens: (text: string) => Promise<number>;
+    };
+    /** Context from chat request (for UI integration) */
+    toolInvocationToken?: unknown;
+}
+/**
+ * Result from tool invocation
+ */
+export interface LanguageModelToolResult {
+    /** Content parts from the tool */
+    content: Array<{
+        type: "text" | "data" | "error";
+        value: string;
+        mimeType?: string;
+    }>;
+}
+/**
+ * A tool that can be registered and invoked
+ */
+export interface LanguageModelTool<T = unknown> {
+    /**
+     * Invoke the tool with the given input
+     */
+    invoke(options: LanguageModelToolInvocationOptions<T>, signal?: AbortSignal): Promise<LanguageModelToolResult>;
+    /**
+     * Optional preparation before invocation (for progress/confirmation)
+     */
+    prepareInvocation?(options: {
+        input: T;
+    }, signal?: AbortSignal): Promise<{
+        invocationMessage?: string;
+        confirmationMessages?: {
+            title: string;
+            message: string;
+        };
+    }>;
+}
+/**
+ * MCP Server Definition Provider
+ * Provides available MCP servers dynamically
+ */
+export interface McpServerDefinitionProvider {
+    /**
+     * Provide available MCP servers
+     */
+    provideMcpServerDefinitions(signal?: AbortSignal): Promise<McpServerConfig[]>;
+    /**
+     * Optional: resolve server before starting (e.g., for authentication)
+     */
+    resolveMcpServerDefinition?(server: McpServerConfig, signal?: AbortSignal): Promise<McpServerConfig>;
+    /**
+     * Optional: event when servers change
+     */
+    onDidChangeMcpServerDefinitions?: (listener: () => void) => () => void;
+}
+/**
+ * Disposable pattern for cleanup
+ */
+export interface Disposable {
+    dispose(): void;
+}
+/**
+ * Language Model Tools Manager
+ * Manages tool registration and discovery
+ */
+export declare class LanguageModelToolsManager extends EventEmitter {
+    private tools;
+    private toolInfo;
+    private mcpProviders;
+    private mcpServerCache;
+    private workspacePath;
+    constructor();
+    /**
+     * Set workspace path for MCP servers
+     */
+    setWorkspacePath(path: string | null): void;
+    /**
+     * Register a native tool
+     */
+    registerTool<T = unknown>(name: string, tool: LanguageModelTool<T>, info: Omit<LanguageModelToolInformation, "name" | "source">): Disposable;
+    /**
+     * Register an MCP server definition provider
+     */
+    registerMcpServerDefinitionProvider(id: string, provider: McpServerDefinitionProvider): Disposable;
+    /**
+     * Get all available tools (native + MCP)
+     */
+    getAvailableTools(signal?: AbortSignal): Promise<LanguageModelToolInformation[]>;
+    /**
+     * Invoke a tool by name
+     */
+    invokeTool(name: string, options: LanguageModelToolInvocationOptions, signal?: AbortSignal): Promise<LanguageModelToolResult>;
+    /**
+     * Invoke an MCP tool
+     */
+    private invokeMcpTool;
+    /**
+     * Get all MCP servers from all providers
+     */
+    private getAllMcpServers;
+    /**
+     * Generate MCP tool key (matches mcpTools.ts format)
+     */
+    private getMcpToolKey;
+    /**
+     * Listen for tool changes
+     */
+    onDidChangeTools(listener: () => void): Disposable;
+}
+export declare const languageModelTools: LanguageModelToolsManager;
+export default LanguageModelToolsManager;

package/dist/api/core/library/languageModelTools.js

@@ -0,0 +1,207 @@
+/**
+ * Language Model Tools API
+ * VS Code-compatible API for registering and managing language model tools
+ */
+import { EventEmitter } from "events";
+import { listMcpServerTools, executeMcpToolByKey } from "../agent/tools/mcpTools.js";
+/**
+ * Language Model Tools Manager
+ * Manages tool registration and discovery
+ */
+export class LanguageModelToolsManager extends EventEmitter {
+    tools = new Map();
+    toolInfo = new Map();
+    mcpProviders = new Map();
+    mcpServerCache = new Map();
+    workspacePath = null;
+    constructor() {
+        super();
+    }
+    /**
+     * Set workspace path for MCP servers
+     */
+    setWorkspacePath(path) {
+        this.workspacePath = path;
+        // Clear cache when workspace changes
+        this.mcpServerCache.clear();
+        this.emit("toolsChanged");
+    }
+    /**
+     * Register a native tool
+     */
+    registerTool(name, tool, info) {
+        this.tools.set(name, tool);
+        this.toolInfo.set(name, {
+            name,
+            description: info.description,
+            inputSchema: info.inputSchema,
+            tags: info.tags,
+            source: "native",
+        });
+        this.emit("toolsChanged");
+        return {
+            dispose: () => {
+                this.tools.delete(name);
+                this.toolInfo.delete(name);
+                this.emit("toolsChanged");
+            },
+        };
+    }
+    /**
+     * Register an MCP server definition provider
+     */
+    registerMcpServerDefinitionProvider(id, provider) {
+        this.mcpProviders.set(id, provider);
+        // Listen for changes if provider supports it
+        let unsubscribe;
+        if (provider.onDidChangeMcpServerDefinitions) {
+            unsubscribe = provider.onDidChangeMcpServerDefinitions(() => {
+                this.mcpServerCache.delete(id);
+                this.emit("toolsChanged");
+            });
+        }
+        this.emit("toolsChanged");
+        return {
+            dispose: () => {
+                this.mcpProviders.delete(id);
+                this.mcpServerCache.delete(id);
+                if (unsubscribe)
+                    unsubscribe();
+                this.emit("toolsChanged");
+            },
+        };
+    }
+    /**
+     * Get all available tools (native + MCP)
+     */
+    async getAvailableTools(signal) {
+        const tools = [];
+        // Add native tools
+        tools.push(...Array.from(this.toolInfo.values()));
+        // Add MCP tools from all providers
+        const mcpServers = await this.getAllMcpServers(signal);
+        const workspacePath = this.workspacePath || process.cwd();
+        for (const server of mcpServers) {
+            if (!server.enabled)
+                continue;
+            try {
+                const serverTools = await listMcpServerTools(server, workspacePath);
+                for (const tool of serverTools) {
+                    const toolKey = this.getMcpToolKey(server.name, tool.name);
+                    tools.push({
+                        name: toolKey,
+                        description: tool.description || `MCP tool: ${tool.name}`,
+                        inputSchema: tool.inputSchema,
+                        tags: ["mcp", server.name],
+                        source: `mcp:${server.name}`,
+                    });
+                }
+            }
+            catch (error) {
+                console.error(`Failed to list tools from ${server.name}:`, error);
+            }
+        }
+        return tools;
+    }
+    /**
+     * Invoke a tool by name
+     */
+    async invokeTool(name, options, signal) {
+        // Check if it's a native tool
+        const nativeTool = this.tools.get(name);
+        if (nativeTool) {
+            return nativeTool.invoke(options, signal);
+        }
+        // Check if it's an MCP tool
+        if (name.startsWith("mcp_")) {
+            return this.invokeMcpTool(name, options, signal);
+        }
+        throw new Error(`Tool '${name}' not found`);
+    }
+    /**
+     * Invoke an MCP tool
+     */
+    async invokeMcpTool(toolKey, options, signal) {
+        const mcpServers = await this.getAllMcpServers(signal);
+        const workspacePath = this.workspacePath || process.cwd();
+        const result = await executeMcpToolByKey(mcpServers, workspacePath, toolKey, options.input);
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: "error",
+                        value: result.error || "MCP tool execution failed",
+                    },
+                ],
+            };
+        }
+        // At this point, result.success is true, so we can safely access optional content
+        // TypeScript can't narrow the union type properly, so we explicitly cast
+        const successResult = result;
+        // Convert MCP result to LanguageModelToolResult format
+        const content = [];
+        if (Array.isArray(successResult.content)) {
+            for (const item of successResult.content) {
+                if (typeof item === "object" && item !== null) {
+                    const mcpItem = item;
+                    if (mcpItem.text) {
+                        content.push({
+                            type: "text",
+                            value: mcpItem.text,
+                        });
+                    }
+                    else if (mcpItem.message) {
+                        content.push({
+                            type: "text",
+                            value: mcpItem.message,
+                        });
+                    }
+                }
+            }
+        }
+        if (content.length === 0 && successResult.content !== undefined) {
+            content.push({
+                type: "text",
+                value: JSON.stringify(successResult.content, null, 2),
+            });
+        }
+        return { content };
+    }
+    /**
+     * Get all MCP servers from all providers
+     */
+    async getAllMcpServers(signal) {
+        const allServers = [];
+        for (const [id, provider] of this.mcpProviders.entries()) {
+            // Check cache first
+            let servers = this.mcpServerCache.get(id);
+            if (!servers) {
+                servers = await provider.provideMcpServerDefinitions(signal);
+                this.mcpServerCache.set(id, servers);
+            }
+            allServers.push(...servers);
+        }
+        return allServers;
+    }
+    /**
+     * Generate MCP tool key (matches mcpTools.ts format)
+     */
+    getMcpToolKey(serverName, toolName) {
+        const safeToken = (value) => value.replace(/[^a-zA-Z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80);
+        return `mcp_${safeToken(serverName)}_${safeToken(toolName)}`;
+    }
+    /**
+     * Listen for tool changes
+     */
+    onDidChangeTools(listener) {
+        this.on("toolsChanged", listener);
+        return {
+            dispose: () => {
+                this.off("toolsChanged", listener);
+            },
+        };
+    }
+}
+// Singleton instance
+export const languageModelTools = new LanguageModelToolsManager();
+export default LanguageModelToolsManager;

package/dist/api/core/library/localRuntime.d.ts

@@ -0,0 +1,23 @@
+export declare const API_KEYS_STORAGE_KEY = "settings.apiKeys";
+export declare const DEFAULT_LOCAL_RUNTIME_BASE_URL = "http://127.0.0.1:11434/v1";
+export declare const DEFAULT_LOCAL_RUNTIME_API_KEY = "ollama";
+export type LocalRuntimeHealthResult = {
+    ok: boolean;
+    message: string;
+    probeUrl: string;
+    /** True when the probe was aborted due to timeout (as opposed to a hard connection error). */
+    timedOut?: boolean;
+};
+export declare const isLocalModelId: (modelId: string) => boolean;
+export declare const getLocalRuntimeConfigFromStorage: () => {
+    baseUrl: string;
+    apiKey: string;
+};
+export declare const checkLocalRuntimeConnection: (baseUrl: string, apiKey?: string, timeoutMs?: number) => Promise<LocalRuntimeHealthResult>;
+/**
+ * Check local runtime connection with built-in caching to avoid repeated probes.
+ * Uses a short TTL (60s for successful, 5s for failed) to prevent latency regressions
+ * during repeated chat invocations while still allowing quick error recovery.
+ * All probes use HEALTH_CHECK_TIMEOUT_MS regardless of host.
+ */
+export declare const checkLocalRuntimeConnectionCached: (baseUrl: string, apiKey?: string) => Promise<LocalRuntimeHealthResult>;

package/dist/api/core/library/localRuntime.js

@@ -0,0 +1,144 @@
+export const API_KEYS_STORAGE_KEY = "settings.apiKeys";
+export const DEFAULT_LOCAL_RUNTIME_BASE_URL = "http://127.0.0.1:11434/v1";
+export const DEFAULT_LOCAL_RUNTIME_API_KEY = "ollama";
+// Cache for health check results to avoid repeated probes.
+// Keyed by normalized baseUrl + a non-reversible fingerprint of apiKey.
+// This avoids storing raw secrets in memory while preventing cache collisions
+// across different keys for the same endpoint.
+const HEALTH_CHECK_CACHE = new Map();
+const HEALTH_CHECK_CACHE_MAX_SIZE = 8; // evict oldest entry when exceeded
+const HEALTH_CHECK_TTL_MS = 60000; // Cache for 60 seconds
+const HEALTH_CHECK_FAILED_TTL_MS = 5000; // Cache failures for 5 seconds only
+const HEALTH_CHECK_TIMEOUT_MS = 1500; // 1500ms balances cold-start tolerance vs. latency
+export const isLocalModelId = (modelId) => modelId.startsWith("ollama/") || modelId.startsWith("local/");
+const trimTrailingSlash = (value) => value.replace(/\/$/, "");
+// Produces a short, non-reversible fingerprint of the API key so that cache
+// entries for different keys on the same baseUrl are not conflated, without
+// retaining the raw secret in the Map key.
+const fingerprintApiKey = (apiKey) => {
+    if (!apiKey)
+        return "";
+    let hash = 5381;
+    for (let i = 0; i < apiKey.length; i++) {
+        hash = (((hash << 5) + hash) ^ apiKey.charCodeAt(i)) >>> 0;
+    }
+    return hash.toString(36);
+};
+const normalizeBaseUrl = (value) => {
+    const trimmed = (value || "").trim();
+    if (!trimmed)
+        return DEFAULT_LOCAL_RUNTIME_BASE_URL;
+    const candidate = trimTrailingSlash(trimmed);
+    try {
+        const parsed = new URL(candidate);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return DEFAULT_LOCAL_RUNTIME_BASE_URL;
+        }
+        return candidate;
+    }
+    catch {
+        return DEFAULT_LOCAL_RUNTIME_BASE_URL;
+    }
+};
+const buildProbeUrl = (baseUrl) => {
+    const normalized = normalizeBaseUrl(baseUrl);
+    return `${normalized}/models`;
+};
+export const getLocalRuntimeConfigFromStorage = () => {
+    if (typeof window === "undefined") {
+        return {
+            baseUrl: DEFAULT_LOCAL_RUNTIME_BASE_URL,
+            apiKey: DEFAULT_LOCAL_RUNTIME_API_KEY,
+        };
+    }
+    try {
+        const raw = localStorage.getItem(API_KEYS_STORAGE_KEY);
+        const parsed = raw ? JSON.parse(raw) : {};
+        return {
+            baseUrl: normalizeBaseUrl(parsed?.OLLAMA_BASE_URL),
+            apiKey: (parsed?.OLLAMA_API_KEY || DEFAULT_LOCAL_RUNTIME_API_KEY).trim(),
+        };
+    }
+    catch {
+        return {
+            baseUrl: DEFAULT_LOCAL_RUNTIME_BASE_URL,
+            apiKey: DEFAULT_LOCAL_RUNTIME_API_KEY,
+        };
+    }
+};
+export const checkLocalRuntimeConnection = async (baseUrl, apiKey, timeoutMs = 3000) => {
+    const probeUrl = buildProbeUrl(baseUrl);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const headers = {};
+        if (apiKey && apiKey.trim().length > 0) {
+            headers.Authorization = `Bearer ${apiKey.trim()}`;
+        }
+        const res = await fetch(probeUrl, {
+            method: "GET",
+            headers,
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            return {
+                ok: false,
+                message: `Runtime responded with HTTP ${res.status}`,
+                probeUrl,
+            };
+        }
+        const payload = (await res.json().catch(() => ({})));
+        const modelCount = Array.isArray(payload?.data) ? payload.data.length : undefined;
+        return {
+            ok: true,
+            message: modelCount !== undefined ? `Connected (${modelCount} model${modelCount === 1 ? "" : "s"} available)` : "Connected",
+            probeUrl,
+        };
+    }
+    catch (err) {
+        const timedOut = err instanceof Error && err.name === "AbortError";
+        const message = timedOut ? "Connection timed out" : err instanceof Error ? err.message : "Connection failed";
+        return {
+            ok: false,
+            message,
+            probeUrl,
+            timedOut,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+/**
+ * Check local runtime connection with built-in caching to avoid repeated probes.
+ * Uses a short TTL (60s for successful, 5s for failed) to prevent latency regressions
+ * during repeated chat invocations while still allowing quick error recovery.
+ * All probes use HEALTH_CHECK_TIMEOUT_MS regardless of host.
+ */
+export const checkLocalRuntimeConnectionCached = async (baseUrl, apiKey) => {
+    const cacheKey = `${normalizeBaseUrl(baseUrl)}:${fingerprintApiKey(apiKey)}`;
+    const cached = HEALTH_CHECK_CACHE.get(cacheKey);
+    // Return cached result if still valid
+    if (cached) {
+        const age = Date.now() - cached.timestamp;
+        const ttl = cached.result.ok ? HEALTH_CHECK_TTL_MS : HEALTH_CHECK_FAILED_TTL_MS;
+        if (age < ttl) {
+            return cached.result;
+        }
+    }
+    // Cache miss or expired - perform fresh check
+    const result = await checkLocalRuntimeConnection(baseUrl, apiKey, HEALTH_CHECK_TIMEOUT_MS);
+    // Don't cache timeout failures — the runtime may just be slow to start;
+    // the next invocation should retry immediately rather than hitting a stale negative.
+    if (!result.timedOut) {
+        // Evict the oldest entry before inserting when the cache is at capacity.
+        if (!HEALTH_CHECK_CACHE.has(cacheKey) && HEALTH_CHECK_CACHE.size >= HEALTH_CHECK_CACHE_MAX_SIZE) {
+            const oldestKey = HEALTH_CHECK_CACHE.keys().next().value;
+            if (oldestKey !== undefined) {
+                HEALTH_CHECK_CACHE.delete(oldestKey);
+            }
+        }
+        HEALTH_CHECK_CACHE.set(cacheKey, { result, timestamp: Date.now() });
+    }
+    return result;
+};