@intent-systems/nexus 2026.1.5-11

package/dist/control-plane/odu/interaction-tools.js

@@ -0,0 +1,208 @@
+/**
+ * Interaction Agent Tools
+ *
+ * Creates tools for IAs to delegate to EAs and manage specialist agents.
+ * Ported from magic-toolbox/agentkit/tools/interaction-tools.ts
+ */
+import { listAgentSessions, loadSessionMetadata, } from "../../config/sessions.js";
+/**
+ * Create all interaction agent tools
+ *
+ * Returns tool definitions in the format expected by pi-coding-agent
+ */
+export function createInteractionTools(_context) {
+    return [
+        {
+            name: "list_my_agents",
+            description: "List all agents you can message: your own specialist agents (by short name) and external agents that have contacted you (by full name).",
+            input_schema: {
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of agents to return (default: 20)",
+                    },
+                },
+            },
+        },
+        {
+            name: "send_message_to_agent",
+            description: 'Send a message to an EA. If task_name matches an existing EA, it will be resumed with full history. If not, a new EA will be created with that name. Use priority to control urgency: "urgent"/"high" will interrupt running EA immediately, "normal" will queue the message.',
+            input_schema: {
+                type: "object",
+                properties: {
+                    task_name: {
+                        type: "string",
+                        description: 'Unique descriptive name for the EA (e.g., "magic-toolbox-worktrees", "merge-feature-branches")',
+                    },
+                    task: {
+                        type: "string",
+                        description: "Task description or message for the EA",
+                    },
+                    priority: {
+                        type: "string",
+                        enum: ["normal", "high", "urgent"],
+                        description: 'Message priority: "normal" = queue (default), "high"/"urgent" = interrupt running EA immediately. Use high/urgent when: user says "stop/wait", new info invalidates current work, critical correction needed.',
+                        default: "normal",
+                    },
+                },
+                required: ["task_name", "task"],
+            },
+        },
+        {
+            name: "inspect_agent",
+            description: "Get detailed info about a specific agent (for tie-breaking when multiple agents might match)",
+            input_schema: {
+                type: "object",
+                properties: {
+                    task_name: {
+                        type: "string",
+                        description: "The task_name of the EA to inspect",
+                    },
+                },
+                required: ["task_name"],
+            },
+        },
+    ];
+}
+/**
+ * Handle tool invocation
+ *
+ * Called when a tool is invoked by the IA
+ */
+export async function handleToolInvocation(toolName, args, context) {
+    const payload = args && typeof args === "object" ? args : {};
+    switch (toolName) {
+        case "list_my_agents":
+            return await handleListMyAgents(payload, context);
+        case "send_message_to_agent":
+            return await handleSendMessageToAgent(payload, context);
+        case "inspect_agent":
+            return await handleInspectAgent(payload, context);
+        default:
+            throw new Error(`Unknown tool: ${toolName}`);
+    }
+}
+/**
+ * Handle list_my_agents tool
+ */
+async function handleListMyAgents(args, context) {
+    const limit = typeof args.limit === "number" && Number.isFinite(args.limit)
+        ? Math.max(1, Math.trunc(args.limit))
+        : 20;
+    // Get own EAs from session storage
+    // EAs are stored as sessions with agentType: "execution" and parentSession set
+    const agentId = context.agentId.replace("-ia", ""); // Convert 'toolbox-ia' to 'toolbox'
+    const allSessions = await listAgentSessions(agentId);
+    // Load metadata for each session to check agentType
+    const eaSessions = [];
+    for (const sessionKey of allSessions.slice(0, limit)) {
+        const metadata = await loadSessionMetadata(agentId, sessionKey);
+        if (metadata && metadata.agentType === "execution") {
+            eaSessions.push({
+                sessionKey,
+                metadata,
+            });
+        }
+    }
+    // Get external callers from broker
+    const externalAgentIds = context.broker.getExternalCallers(context.agentId);
+    // Format own EAs (show short names)
+    const ownFormatted = eaSessions
+        .map((ea) => {
+        const updated = ea.metadata.updated; // New format uses 'updated' (ISO string)
+        const lastActiveDate = updated
+            ? new Date(updated).toLocaleString()
+            : "Never";
+        const taskName = ea.sessionKey; // sessionKey is the task name
+        const displayName = ea.metadata.displayName || taskName;
+        const isActive = context.broker.isAgentActive(`${context.oduName}-ea-${taskName}`);
+        const status = isActive ? "🟢 active" : "⚪ idle";
+        return `• ${displayName} (${status})\n  Last active: ${lastActiveDate}`;
+    })
+        .join("\n\n");
+    // Format external callers (show full names)
+    const externalFormatted = externalAgentIds.length > 0
+        ? externalAgentIds
+            .map((agentId) => {
+            const isActive = context.broker.isAgentActive(agentId);
+            const status = isActive ? "🟢 active" : "⚪ idle";
+            return `• ${agentId} (${status})\n  External agent - has sent you messages`;
+        })
+            .join("\n\n")
+        : "";
+    // Build response
+    let text = "";
+    if (eaSessions.length > 0) {
+        text += `Your Specialist Agents (${eaSessions.length}):\n\n${ownFormatted}`;
+    }
+    if (externalFormatted) {
+        if (text)
+            text += "\n\n---\n\n";
+        text += `External Agents (${externalAgentIds.length}):\n\n${externalFormatted}`;
+    }
+    if (!text) {
+        text =
+            "No agents found. You can create a new one with send_message_to_agent.";
+    }
+    return text;
+}
+/**
+ * Handle send_message_to_agent tool
+ */
+async function handleSendMessageToAgent(args, context) {
+    const taskName = typeof args.task_name === "string" ? args.task_name : "";
+    const task = typeof args.task === "string" ? args.task : "";
+    if (!taskName || !task) {
+        throw new Error("Invalid arguments: task_name and task are required.");
+    }
+    const priority = typeof args.priority === "string" ? args.priority : "normal";
+    // Convert task_name to fully-qualified EA agent ID
+    const eaId = `${context.oduName}-ea-${taskName}`;
+    // Send message via broker
+    await context.broker.send({
+        id: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+        from: context.agentId,
+        to: eaId,
+        content: task,
+        priority: priority,
+        timestamp: Date.now(),
+        metadata: {
+            source: "ia",
+            taskName,
+        },
+    });
+    return `Message sent to ${taskName}. The EA will process the task and report back when complete.`;
+}
+/**
+ * Handle inspect_agent tool
+ */
+async function handleInspectAgent(args, context) {
+    const taskName = typeof args.task_name === "string" ? args.task_name : "";
+    if (!taskName) {
+        throw new Error("Invalid arguments: task_name is required.");
+    }
+    const agentId = context.agentId.replace("-ia", ""); // Convert 'toolbox-ia' to 'toolbox'
+    // Load session metadata
+    const metadata = await loadSessionMetadata(agentId, taskName);
+    if (!metadata) {
+        return `EA not found: ${taskName}`;
+    }
+    const updated = metadata.updated; // New format uses 'updated' (ISO string)
+    const created = metadata.created; // New format uses 'created' (ISO string)
+    const lastActiveDate = updated ? new Date(updated).toLocaleString() : "Never";
+    const createdDate = created ? new Date(created).toLocaleString() : "Unknown";
+    const displayName = metadata.displayName || taskName;
+    // Check if agent is currently active
+    const eaId = `${context.oduName}-ea-${taskName}`;
+    const isActive = context.broker.isAgentActive(eaId);
+    const status = isActive ? "🟢 active" : "⚪ idle";
+    return `EA: ${displayName} (${status})
+
+Task Name: ${taskName}
+Created: ${createdDate}
+Last Active: ${lastActiveDate}
+Compactions: ${metadata.compactionCount || 0}
+
+This EA specializes in: ${metadata.displayName || "general tasks"}`;
+}

package/dist/control-plane/odu/prompt-loader.js

@@ -0,0 +1,95 @@
+/**
+ * Prompt Loader for ODU System Prompts
+ *
+ * Loads prompt templates from files and substitutes {{variable}} patterns.
+ * Similar to magic-toolbox/agentkit/prompts/loader.ts
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveUserPath } from "../../utils.js";
+/**
+ * Cache for loaded prompts (performance optimization)
+ */
+const promptCache = new Map();
+/**
+ * Load a prompt template from file and substitute variables
+ *
+ * @param promptPath - Path to .md file (relative to nexus root, workspace, or absolute)
+ * @param variables - Variables to substitute (e.g., { oduName: "Toolbox", oduPurpose: "..." })
+ * @returns Loaded prompt with variables substituted
+ */
+export async function loadPrompt(promptPath, variables = {}) {
+    // Resolve prompt path with precedence:
+    // 1. Absolute path (if provided)
+    // 2. Workspace prompts/ directory
+    // 3. Nexus bundled prompts/ directory
+    const resolvedPath = await resolvePromptPath(promptPath);
+    // Check cache first
+    const cacheKey = resolvedPath;
+    let template = promptCache.get(cacheKey);
+    if (!template) {
+        // Load from file
+        template = await fs.readFile(resolvedPath, "utf-8");
+        // Cache the template
+        promptCache.set(cacheKey, template);
+    }
+    // Substitute {{variable}} patterns
+    return substituteVariables(template, variables);
+}
+/**
+ * Resolve prompt path with precedence:
+ * 1. Absolute path (if provided)
+ * 2. Workspace prompts/ directory (if exists)
+ * 3. Nexus bundled prompts/ directory
+ *
+ * @param promptPath - Path to .md file (can be relative or absolute)
+ * @returns Absolute path to prompt file
+ */
+async function resolvePromptPath(promptPath) {
+    // If absolute path, use directly
+    if (path.isAbsolute(promptPath)) {
+        return promptPath;
+    }
+    // Try workspace prompts/ directory first
+    const workspacePath = path.join(resolveUserPath("~/nexus/home"), "prompts", promptPath);
+    try {
+        await fs.access(workspacePath);
+        return workspacePath;
+    }
+    catch {
+        // Workspace path doesn't exist, try nexus bundled prompts
+    }
+    // Try nexus bundled prompts/ directory
+    // (Resolve relative to this file's directory)
+    const nexusRootPath = path.resolve(new URL(import.meta.url).pathname, "../../../..");
+    const bundledPath = path.join(nexusRootPath, "prompts", promptPath);
+    try {
+        await fs.access(bundledPath);
+        return bundledPath;
+    }
+    catch {
+        throw new Error(`Prompt file not found: ${promptPath} (tried workspace and bundled prompts)`);
+    }
+}
+/**
+ * Substitute {{variable}} patterns in template
+ *
+ * @param template - Template string with {{variable}} patterns
+ * @param variables - Variables to substitute
+ * @returns Template with variables substituted
+ */
+function substituteVariables(template, variables) {
+    let result = template;
+    // Replace all {{variable}} patterns
+    for (const [key, value] of Object.entries(variables)) {
+        const pattern = new RegExp(`\\{\\{${key}\\}\\}`, "g");
+        result = result.replace(pattern, value);
+    }
+    return result;
+}
+/**
+ * Clear the prompt cache (useful for testing or hot-reloading)
+ */
+export function clearPromptCache() {
+    promptCache.clear();
+}