@4onstudios/iris-agent 0.1.0

package/dist/api/helpers/slashCommands.js

@@ -0,0 +1,129 @@
+const REGISTERED_SLASH_COMMANDS = [
+    {
+        name: "help",
+        description: "Show available slash commands.",
+        executeImmediately: true,
+        kind: "builtin",
+    },
+    {
+        name: "compact",
+        description: "Summarize recent conversation context into a compact digest.",
+        executeImmediately: true,
+        kind: "builtin",
+    },
+    {
+        name: "run",
+        description: "Run a shell command. Example: /run npm test",
+        executeImmediately: false,
+        kind: "shell",
+        aliases: ["sh", "shell"],
+    },
+];
+const getRegisteredSlashCommand = (name) => REGISTERED_SLASH_COMMANDS.find((command) => command.name === name ||
+    Boolean(command.aliases?.includes(name)));
+export const getSlashCommandDescriptors = () => REGISTERED_SLASH_COMMANDS.map((command) => ({
+    name: command.name,
+    description: command.description,
+    executeImmediately: command.executeImmediately,
+    kind: command.kind,
+    aliases: command.aliases || [],
+}));
+export const parseSlashCommandRequest = (input) => {
+    if (!input)
+        return null;
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("/"))
+        return null;
+    if (trimmed.startsWith("//"))
+        return null;
+    const rawCommand = trimmed.slice(1).trim();
+    if (!rawCommand)
+        return null;
+    const [commandName, ...argParts] = rawCommand.split(/\s+/);
+    const name = (commandName || "").trim().toLowerCase();
+    const args = argParts.join(" ").trim();
+    if (!name)
+        return null;
+    const resolvedCommand = getRegisteredSlashCommand(name);
+    const shellCommand = resolvedCommand?.kind === "shell" ? args : rawCommand;
+    return {
+        name,
+        shellCommand,
+    };
+};
+export const isSlashCommandsFeatureEnabled = () => {
+    const raw = process.env.IRIS_ENABLE_SLASH_COMMANDS;
+    return raw === undefined
+        ? true
+        : !["0", "false", "off", "no"].includes(raw.trim().toLowerCase());
+};
+const formatSlashCommandsHelp = () => {
+    const lines = ["Available slash commands:"];
+    for (const command of REGISTERED_SLASH_COMMANDS) {
+        const aliasSuffix = command.aliases && command.aliases.length > 0
+            ? ` (aliases: ${command.aliases.map((alias) => `/${alias}`).join(", ")})`
+            : "";
+        lines.push(`- /${command.name}${aliasSuffix}: ${command.description}`);
+    }
+    return lines.join("\n");
+};
+const buildCompactDigest = (conversationHistory, contextSummary) => {
+    const recentMessages = (conversationHistory || [])
+        .filter((message) => message?.content)
+        .slice(-8);
+    const recentUserMessages = recentMessages
+        .filter((message) => message.role === "user")
+        .slice(-3)
+        .map((message) => message.content.replace(/\s+/g, " ").trim())
+        .filter(Boolean)
+        .map((text) => (text.length > 140 ? `${text.slice(0, 137)}...` : text));
+    const contextItems = (contextSummary || [])
+        .slice(-5)
+        .map((item) => item.preview.trim())
+        .filter(Boolean)
+        .map((text) => (text.length > 120 ? `${text.slice(0, 117)}...` : text));
+    const lines = [
+        "Conversation compact digest:",
+        `- Recent messages: ${recentMessages.length}`,
+        `- Context snippets: ${contextItems.length}`,
+    ];
+    if (recentUserMessages.length > 0) {
+        lines.push("- Recent user intents:");
+        for (const message of recentUserMessages) {
+            lines.push(`  - ${message}`);
+        }
+    }
+    if (contextItems.length > 0) {
+        lines.push("- Context summary excerpts:");
+        for (const item of contextItems) {
+            lines.push(`  - ${item}`);
+        }
+    }
+    if (recentUserMessages.length === 0 && contextItems.length === 0) {
+        lines.push("- No prior conversation context is available yet.");
+    }
+    return lines.join("\n");
+};
+export const executeRegisteredSlashCommand = ({ parsedCommand, conversationHistory, contextSummary, }) => {
+    const command = getRegisteredSlashCommand(parsedCommand.name);
+    if (!command || command.kind !== "builtin") {
+        return null;
+    }
+    if (command.name === "help") {
+        return {
+            success: true,
+            response: formatSlashCommandsHelp(),
+            toolCalls: [],
+            executedToolResults: [],
+        };
+    }
+    if (command.name === "compact") {
+        return {
+            success: true,
+            response: buildCompactDigest(conversationHistory, contextSummary),
+            toolCalls: [],
+            executedToolResults: [],
+        };
+    }
+    return null;
+};

package/dist/api/helpers/tokenUsage.d.ts

@@ -0,0 +1,19 @@
+export type TokenUsageSummary = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+};
+export declare const normalizeTokenUsage: (raw: unknown) => TokenUsageSummary | undefined;
+export declare const mergeTokenUsage: (base: TokenUsageSummary | undefined, incoming: TokenUsageSummary | undefined) => TokenUsageSummary | undefined;
+export declare const extractTokenUsageFromChunkPayload: (payload: unknown) => TokenUsageSummary | undefined;
+export declare const isTokenUsageSourceDebugEnabled: () => boolean;
+export declare const logTokenUsageSource: ({ mode, source, usage, modelId, }: {
+    mode: "stream" | "non_stream";
+    source: "final" | "stream" | "none";
+    usage: TokenUsageSummary | undefined;
+    modelId: string;
+}) => void;
+export declare const buildTokenUsageDebug: ({ mode, source, }: {
+    mode: "stream" | "non_stream";
+    source: "final" | "stream" | "none";
+}) => Record<string, unknown> | undefined;

package/dist/api/helpers/tokenUsage.js

@@ -0,0 +1,81 @@
+const asFiniteNonNegativeInt = (value) => {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    if (value < 0) {
+        return undefined;
+    }
+    return Math.round(value);
+};
+export const normalizeTokenUsage = (raw) => {
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    const record = raw;
+    const inputTokens = asFiniteNonNegativeInt(record.inputTokens) ??
+        asFiniteNonNegativeInt(record.promptTokens) ??
+        asFiniteNonNegativeInt(record.prompt_tokens);
+    const outputTokens = asFiniteNonNegativeInt(record.outputTokens) ??
+        asFiniteNonNegativeInt(record.completionTokens) ??
+        asFiniteNonNegativeInt(record.completion_tokens);
+    let totalTokens = asFiniteNonNegativeInt(record.totalTokens) ??
+        asFiniteNonNegativeInt(record.total_tokens);
+    if (totalTokens === undefined && inputTokens !== undefined && outputTokens !== undefined) {
+        totalTokens = inputTokens + outputTokens;
+    }
+    if (inputTokens === undefined && outputTokens === undefined && totalTokens === undefined) {
+        return undefined;
+    }
+    return {
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(totalTokens !== undefined ? { totalTokens } : {}),
+    };
+};
+export const mergeTokenUsage = (base, incoming) => {
+    if (!base && !incoming) {
+        return undefined;
+    }
+    return {
+        ...(base || {}),
+        ...(incoming || {}),
+    };
+};
+export const extractTokenUsageFromChunkPayload = (payload) => {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const payloadRecord = payload;
+    const nested = normalizeTokenUsage(payloadRecord.usage);
+    if (nested) {
+        return nested;
+    }
+    return normalizeTokenUsage(payload);
+};
+export const isTokenUsageSourceDebugEnabled = () => {
+    const raw = process.env.IRIS_DEBUG_TOKEN_USAGE_SOURCE;
+    if (!raw) {
+        return false;
+    }
+    return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase());
+};
+export const logTokenUsageSource = ({ mode, source, usage, modelId, }) => {
+    if (!isTokenUsageSourceDebugEnabled()) {
+        return;
+    }
+    console.log("📊 Token usage source", {
+        mode,
+        source,
+        modelId,
+        usage,
+    });
+};
+export const buildTokenUsageDebug = ({ mode, source, }) => {
+    if (!isTokenUsageSourceDebugEnabled()) {
+        return undefined;
+    }
+    return {
+        mode,
+        source,
+    };
+};

package/dist/api/routes/fileRoutes.d.ts

@@ -0,0 +1,2 @@
+import type { RequestHandler, Router } from "express";
+export declare const registerFileRoutes: (router: Router, requireDesktopAuth: RequestHandler) => void;

package/dist/api/routes/fileRoutes.js

@@ -0,0 +1,108 @@
+import fs from "fs/promises";
+import path from "path";
+export const registerFileRoutes = (router, requireDesktopAuth) => {
+    // POST /api/agent/write-file - Write file content (for revert/undo operations)
+    router.post("/write-file", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, content, workspaceRoot } = req.body;
+            if (!filePath) {
+                return res.status(400).json({ error: "File path is required" });
+            }
+            if (content === undefined || content === null) {
+                return res.status(400).json({ error: "Content is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            // Resolve path and guard against traversal outside workspace
+            const absolutePath = path.isAbsolute(filePath)
+                ? filePath
+                : path.join(workspacePath, filePath);
+            const resolvedWorkspace = path.resolve(workspacePath);
+            const resolvedTarget = path.resolve(absolutePath);
+            if (!resolvedTarget.startsWith(resolvedWorkspace + path.sep) &&
+                resolvedTarget !== resolvedWorkspace) {
+                return res.status(400).json({ error: "Path outside workspace" });
+            }
+            await fs.writeFile(resolvedTarget, content, "utf8");
+            return res.json({ success: true, path: filePath });
+        }
+        catch (error) {
+            const err = error;
+            console.error("Write file error:", error);
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to write file" });
+        }
+    });
+    // POST /api/agent/delete-file - Delete file (for undoing newly created files)
+    router.post("/delete-file", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, workspaceRoot } = req.body;
+            if (!filePath) {
+                return res.status(400).json({ error: "File path is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            // Resolve path and guard against traversal outside workspace
+            const absolutePath = path.isAbsolute(filePath)
+                ? filePath
+                : path.join(workspacePath, filePath);
+            const resolvedWorkspace = path.resolve(workspacePath);
+            const resolvedTarget = path.resolve(absolutePath);
+            if (!resolvedTarget.startsWith(resolvedWorkspace + path.sep) &&
+                resolvedTarget !== resolvedWorkspace) {
+                return res.status(400).json({ error: "Path outside workspace" });
+            }
+            try {
+                await fs.unlink(resolvedTarget);
+            }
+            catch (error) {
+                const err = error;
+                // If already missing, treat as success for idempotent undo behavior.
+                if (err.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+            return res.json({ success: true, path: filePath });
+        }
+        catch (error) {
+            const err = error;
+            console.error("Delete file error:", error);
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to delete file" });
+        }
+    });
+    // POST /api/agent/read-file - Read file content (for web workspace)
+    router.post("/read-file", async (req, res) => {
+        try {
+            const { filePath, workspaceRoot } = req.body;
+            if (!filePath) {
+                return res.status(400).json({ error: "File path is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            const isWebWorkspace = workspacePath.startsWith("/workspace/");
+            if (isWebWorkspace) {
+                return res.status(400).json({
+                    error: "Cannot read files from web workspace. File content must be provided by the client.",
+                });
+            }
+            // Resolve file path relative to workspace
+            const absolutePath = path.isAbsolute(filePath)
+                ? filePath
+                : path.join(workspacePath, filePath);
+            const content = await fs.readFile(absolutePath, "utf8");
+            return res.json({
+                success: true,
+                content,
+                path: filePath,
+            });
+        }
+        catch (error) {
+            const err = error;
+            console.error("Read file error:", error);
+            return res.status(500).json({
+                success: false,
+                error: err.message || "Failed to read file",
+            });
+        }
+    });
+};

package/dist/api/routes/lspDocumentRoutes.d.ts

@@ -0,0 +1,4 @@
+import type { NextFunction, Request, Response, Router } from "express";
+type AuthMiddleware = (req: Request, res: Response, next: NextFunction) => void;
+export declare const registerLspDocumentRoutes: (router: Router, requireDesktopAuth: AuthMiddleware) => void;
+export {};

package/dist/api/routes/lspDocumentRoutes.js

@@ -0,0 +1,84 @@
+import path from "path";
+import { coreLsp } from "../core/library/lsp/coreLsp.js";
+const resolveAbsolutePath = (workspacePath, filePath) => path.isAbsolute(filePath) ? filePath : path.join(workspacePath, filePath);
+export const registerLspDocumentRoutes = (router, requireDesktopAuth) => {
+    router.post("/lsp/document/open", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, workspaceRoot, text } = req.body;
+            if (typeof filePath !== "string" || filePath.trim().length === 0) {
+                return res.status(400).json({ success: false, error: "filePath is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            const absolutePath = resolveAbsolutePath(workspacePath, filePath);
+            coreLsp.setRootPath(workspacePath);
+            const opened = await coreLsp.openDocument(absolutePath, typeof text === "string" ? text : undefined);
+            return res.json({ success: opened });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to open LSP document" });
+        }
+    });
+    router.post("/lsp/document/change", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, workspaceRoot, text } = req.body;
+            if (typeof filePath !== "string" || filePath.trim().length === 0) {
+                return res.status(400).json({ success: false, error: "filePath is required" });
+            }
+            if (typeof text !== "string") {
+                return res.status(400).json({ success: false, error: "text is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            const absolutePath = resolveAbsolutePath(workspacePath, filePath);
+            coreLsp.setRootPath(workspacePath);
+            const changed = await coreLsp.changeDocument(absolutePath, text);
+            return res.json({ success: changed });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to change LSP document" });
+        }
+    });
+    router.post("/lsp/document/save", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, workspaceRoot } = req.body;
+            if (typeof filePath !== "string" || filePath.trim().length === 0) {
+                return res.status(400).json({ success: false, error: "filePath is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            const absolutePath = resolveAbsolutePath(workspacePath, filePath);
+            coreLsp.setRootPath(workspacePath);
+            const saved = await coreLsp.saveDocument(absolutePath);
+            return res.json({ success: saved });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to save LSP document" });
+        }
+    });
+    router.post("/lsp/document/close", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, workspaceRoot } = req.body;
+            if (typeof filePath !== "string" || filePath.trim().length === 0) {
+                return res.status(400).json({ success: false, error: "filePath is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            const absolutePath = resolveAbsolutePath(workspacePath, filePath);
+            coreLsp.setRootPath(workspacePath);
+            const closed = await coreLsp.closeDocument(absolutePath);
+            return res.json({ success: closed });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to close LSP document" });
+        }
+    });
+};

package/dist/api/routes/lspHierarchyRoutes.d.ts

@@ -0,0 +1,4 @@
+import type { NextFunction, Request, Response, Router } from "express";
+type AuthMiddleware = (req: Request, res: Response, next: NextFunction) => void;
+export declare const registerLspHierarchyRoutes: (router: Router, requireDesktopAuth: AuthMiddleware) => void;
+export {};

package/dist/api/routes/lspHierarchyRoutes.js

@@ -0,0 +1,122 @@
+import path from "path";
+import { coreLsp } from "../core/library/lsp/coreLsp.js";
+const resolveAbsolutePath = (workspacePath, filePath) => path.isAbsolute(filePath) ? filePath : path.join(workspacePath, filePath);
+export const registerLspHierarchyRoutes = (router, requireDesktopAuth) => {
+    router.post("/lsp/call-hierarchy/prepare", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, workspaceRoot, line, character } = req.body;
+            if (typeof filePath !== "string" || filePath.trim().length === 0) {
+                return res.status(400).json({ success: false, error: "filePath is required" });
+            }
+            if (typeof line !== "number" || typeof character !== "number") {
+                return res.status(400).json({ success: false, error: "line and character are required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            const absolutePath = resolveAbsolutePath(workspacePath, filePath);
+            coreLsp.setRootPath(workspacePath);
+            const items = await coreLsp.prepareCallHierarchy(absolutePath, line, character);
+            return res.json({ success: true, items: Array.isArray(items) ? items : [] });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to prepare call hierarchy" });
+        }
+    });
+    router.post("/lsp/call-hierarchy/incoming", requireDesktopAuth, async (req, res) => {
+        try {
+            const { workspaceRoot, item } = req.body;
+            if (!item || typeof item !== "object") {
+                return res.status(400).json({ success: false, error: "item is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            coreLsp.setRootPath(workspacePath);
+            const calls = await coreLsp.getIncomingCalls(item);
+            return res.json({ success: true, calls: Array.isArray(calls) ? calls : [] });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to get incoming calls" });
+        }
+    });
+    router.post("/lsp/call-hierarchy/outgoing", requireDesktopAuth, async (req, res) => {
+        try {
+            const { workspaceRoot, item } = req.body;
+            if (!item || typeof item !== "object") {
+                return res.status(400).json({ success: false, error: "item is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            coreLsp.setRootPath(workspacePath);
+            const calls = await coreLsp.getOutgoingCalls(item);
+            return res.json({ success: true, calls: Array.isArray(calls) ? calls : [] });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to get outgoing calls" });
+        }
+    });
+    router.post("/lsp/type-hierarchy/prepare", requireDesktopAuth, async (req, res) => {
+        try {
+            const { filePath, workspaceRoot, line, character } = req.body;
+            if (typeof filePath !== "string" || filePath.trim().length === 0) {
+                return res.status(400).json({ success: false, error: "filePath is required" });
+            }
+            if (typeof line !== "number" || typeof character !== "number") {
+                return res.status(400).json({ success: false, error: "line and character are required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            const absolutePath = resolveAbsolutePath(workspacePath, filePath);
+            coreLsp.setRootPath(workspacePath);
+            const items = await coreLsp.prepareTypeHierarchy(absolutePath, line, character);
+            return res.json({ success: true, items: Array.isArray(items) ? items : [] });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to prepare type hierarchy" });
+        }
+    });
+    router.post("/lsp/type-hierarchy/supertypes", requireDesktopAuth, async (req, res) => {
+        try {
+            const { workspaceRoot, item } = req.body;
+            if (!item || typeof item !== "object") {
+                return res.status(400).json({ success: false, error: "item is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            coreLsp.setRootPath(workspacePath);
+            const items = await coreLsp.getTypeHierarchySupertypes(item);
+            return res.json({ success: true, items: Array.isArray(items) ? items : [] });
+        }
+        catch (error) {
+            const err = error;
+            return res.status(500).json({
+                success: false,
+                error: err.message || "Failed to get type hierarchy supertypes",
+            });
+        }
+    });
+    router.post("/lsp/type-hierarchy/subtypes", requireDesktopAuth, async (req, res) => {
+        try {
+            const { workspaceRoot, item } = req.body;
+            if (!item || typeof item !== "object") {
+                return res.status(400).json({ success: false, error: "item is required" });
+            }
+            const workspacePath = workspaceRoot || process.cwd();
+            coreLsp.setRootPath(workspacePath);
+            const items = await coreLsp.getTypeHierarchySubtypes(item);
+            return res.json({ success: true, items: Array.isArray(items) ? items : [] });
+        }
+        catch (error) {
+            const err = error;
+            return res
+                .status(500)
+                .json({ success: false, error: err.message || "Failed to get type hierarchy subtypes" });
+        }
+    });
+};

package/dist/api/routes/lspPositionRoutes.d.ts

@@ -0,0 +1,4 @@
+import type { NextFunction, Request, Response, Router } from "express";
+type AuthMiddleware = (req: Request, res: Response, next: NextFunction) => void;
+export declare const registerLspPositionRoutes: (router: Router, requireDesktopAuth: AuthMiddleware) => void;
+export {};