@intent-systems/nexus 2026.1.5-3 → 2026.1.5-5

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

@@ -0,0 +1,316 @@
+/**
+ * ODUControlPlane - AgentControlPlane implementation using broker + ODU runtime.
+ *
+ * This implementation uses the ActiveMessageBroker to route messages between
+ * an Interaction Agent (IA) singleton and dynamically created Execution Agents (EAs).
+ *
+ * Architecture:
+ * - User messages → IA (singleton, always-on)
+ * - IA delegates tasks → EAs (created on-demand)
+ * - EAs complete and respond → IA
+ * - IA responds → User
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { loadConfig } from "../config/config.js";
+import { listAgentSessions, loadSession, resolveSessionDir, writeSessionMetadata, } from "../config/sessions.js";
+import { createSubsystemLogger } from "../logging.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId, parseAgentSessionKey, } from "../routing/session-key.js";
+import { ActiveMessageBroker } from "./broker/broker.js";
+import { ODUInteractionAgent } from "./odu/runtime.js";
+/**
+ * ODUControlPlane implements AgentControlPlane using the broker pattern.
+ *
+ * Key differences from SingleAgentControlPlane:
+ * - Creates a singleton IA per user/ODU
+ * - IA receives all messages and delegates to EAs via broker
+ * - Session continuity enables learning across tasks
+ */
+export class ODUControlPlane {
+    config;
+    workspaceDir;
+    broker;
+    logger;
+    oduConfig;
+    // Track created IAs (userId -> IA instance)
+    interactionAgents = new Map();
+    constructor(options) {
+        this.config = options?.config ?? loadConfig();
+        this.workspaceDir = options?.workspaceDir ?? process.cwd();
+        this.logger = createSubsystemLogger("odu-control-plane");
+        // Create broker instance
+        this.broker = new ActiveMessageBroker(this.config);
+        // Default ODU config (can be overridden via options)
+        this.oduConfig = options?.oduConfig ?? {
+            name: "nexus",
+            purpose: "AI operating system - universal agent orchestration",
+        };
+        this.logger.info("ODUControlPlane initialized", {
+            oduName: this.oduConfig.name,
+            workspaceDir: this.workspaceDir,
+        });
+    }
+    /**
+     * Get or create the IA for a user/session
+     */
+    getOrCreateIA(userId, sessionId) {
+        let ia = this.interactionAgents.get(userId);
+        if (!ia) {
+            this.logger.info("Creating new IA for user", { userId, sessionId });
+            ia = ODUInteractionAgent.getOrCreate({
+                userId,
+                sessionId,
+                oduPath: this.workspaceDir,
+                config: this.config,
+                oduConfig: this.oduConfig,
+                broker: this.broker,
+            });
+            this.interactionAgents.set(userId, ia);
+        }
+        return ia;
+    }
+    /**
+     * Convert session key to userId
+     * For ODU mode, we use the session key as the userId (e.g., "whatsapp:+15551234567")
+     */
+    sessionKeyToUserId(sessionKey) {
+        // In ODU mode, each session key represents a unique user/conversation
+        return sessionKey;
+    }
+    async sendMessage(options) {
+        const { sessionKey, message, agentId: optAgentId, thinkingLevel, verboseLevel, isHeartbeat, streaming, onChunk: _onChunk, onComplete, onError, } = options;
+        try {
+            // Parse session key to get agentId
+            const parsed = parseAgentSessionKey(sessionKey);
+            const agentId = normalizeAgentId(optAgentId ?? parsed?.agentId ?? DEFAULT_AGENT_ID);
+            // Convert session key to userId for ODU
+            const userId = this.sessionKeyToUserId(sessionKey);
+            // Load or create session
+            const session = await loadSession(agentId, sessionKey);
+            let sessionId;
+            if (!session) {
+                // Create new session
+                sessionId = crypto.randomUUID();
+                const sessionMetadata = {
+                    sessionId,
+                    agentId,
+                    created: new Date().toISOString(),
+                    chatType: "direct",
+                    thinkingLevel: thinkingLevel ?? this.config.agent?.thinkingDefault,
+                    verboseLevel: verboseLevel ?? this.config.agent?.verboseDefault,
+                    compactionCount: 0,
+                };
+                await writeSessionMetadata(agentId, sessionKey, sessionMetadata);
+            }
+            else {
+                sessionId = session.metadata.sessionId;
+                // Update session metadata (writeSessionMetadata handles updated timestamp)
+                await writeSessionMetadata(agentId, sessionKey, session.metadata);
+            }
+            // Get or create IA for this user
+            const _ia = this.getOrCreateIA(userId, sessionId);
+            // Build broker message
+            const brokerMessage = {
+                id: crypto.randomUUID(),
+                from: "user",
+                to: `${this.oduConfig.name}-ia`,
+                content: message,
+                priority: isHeartbeat ? "low" : "normal",
+                timestamp: Date.now(),
+                conversationId: sessionId,
+                metadata: {
+                    source: "user",
+                    sessionKey,
+                    thinkingLevel,
+                    verboseLevel,
+                    streaming,
+                },
+            };
+            // Send message via broker
+            const startTime = Date.now();
+            // For now, we send and wait for acknowledgment
+            // Future: implement streaming support
+            this.logger.debug("Sending message to IA via broker", {
+                sessionKey,
+                userId,
+                messagePreview: message.substring(0, 100),
+            });
+            let responseText = "";
+            try {
+                // Send message via broker and wait for ack
+                responseText = await this.broker.sendAndWaitForAck(brokerMessage);
+            }
+            catch (error) {
+                this.logger.error("Broker send failed", { error, sessionKey });
+                throw error;
+            }
+            const durationMs = Date.now() - startTime;
+            // Update session metadata with latest timestamp
+            const updatedSession = await loadSession(agentId, sessionKey);
+            if (updatedSession) {
+                await writeSessionMetadata(agentId, sessionKey, updatedSession.metadata);
+            }
+            // Call completion callback if provided
+            if (onComplete) {
+                onComplete();
+            }
+            // Return result
+            // Note: config.agent.model can be a string or AgentModelListConfig object
+            // For simplicity, we just use "odu" provider and don't try to extract the model string
+            return {
+                success: true,
+                sessionId,
+                payloads: [
+                    {
+                        text: responseText,
+                    },
+                ],
+                meta: {
+                    durationMs,
+                    provider: "odu",
+                    model: updatedSession?.metadata.model,
+                },
+            };
+        }
+        catch (error) {
+            this.logger.error("sendMessage failed", { error, sessionKey });
+            if (onError) {
+                onError(error);
+            }
+            return {
+                success: false,
+                error: error.message,
+            };
+        }
+    }
+    async getSession(sessionKey) {
+        try {
+            const parsed = parseAgentSessionKey(sessionKey);
+            const agentId = normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
+            const session = await loadSession(agentId, sessionKey);
+            if (!session) {
+                return null;
+            }
+            // Session metadata has 'updated' (ISO string) from new format
+            const updated = session.metadata.updated ||
+                new Date().toISOString();
+            return {
+                key: sessionKey,
+                sessionId: session.metadata.sessionId,
+                displayName: session.metadata.displayName,
+                updatedAt: new Date(updated).getTime(),
+                model: session.metadata.model,
+                usage: {
+                    inputTokens: 0, // TODO: calculate from history
+                    outputTokens: 0,
+                    totalTokens: 0,
+                },
+            };
+        }
+        catch (error) {
+            this.logger.error("getSession failed", { error, sessionKey });
+            return null;
+        }
+    }
+    async listSessions() {
+        try {
+            // List sessions for default agent
+            const agentId = DEFAULT_AGENT_ID;
+            const sessionKeys = await listAgentSessions(agentId);
+            const sessions = [];
+            // Load each session
+            for (const sessionKey of sessionKeys) {
+                const session = await loadSession(agentId, sessionKey);
+                if (session) {
+                    // Session metadata has 'updated' (ISO string) from new format
+                    const updated = session.metadata.updated ||
+                        new Date().toISOString();
+                    sessions.push({
+                        key: sessionKey,
+                        sessionId: session.metadata.sessionId,
+                        displayName: session.metadata.displayName,
+                        updatedAt: new Date(updated).getTime(),
+                        model: session.metadata.model,
+                        usage: {
+                            inputTokens: 0, // TODO: calculate from history
+                            outputTokens: 0,
+                            totalTokens: 0,
+                        },
+                    });
+                }
+            }
+            // Sort by updatedAt descending (most recent first)
+            sessions.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+            return sessions;
+        }
+        catch (error) {
+            this.logger.error("listSessions failed", { error });
+            return [];
+        }
+    }
+    async getStatus() {
+        try {
+            const sessions = await this.listSessions();
+            const runningAgents = this.broker.getRunningAgents();
+            const queues = this.broker.getAllQueues();
+            let queuedMessages = 0;
+            for (const count of queues.values()) {
+                queuedMessages += count;
+            }
+            return {
+                mode: "odu",
+                activeSessions: sessions.length,
+                queuedMessages,
+                healthy: true,
+                metadata: {
+                    runningAgents: runningAgents.length,
+                    interactionAgents: this.interactionAgents.size,
+                    oduName: this.oduConfig.name,
+                },
+            };
+        }
+        catch (error) {
+            this.logger.error("getStatus failed", { error });
+            return {
+                mode: "odu",
+                activeSessions: 0,
+                queuedMessages: 0,
+                healthy: false,
+                metadata: {
+                    error: error.message,
+                },
+            };
+        }
+    }
+    async resetSession(sessionKey) {
+        try {
+            const parsed = parseAgentSessionKey(sessionKey);
+            const agentId = normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
+            // Delete session directory
+            const sessionDir = resolveSessionDir(agentId, sessionKey);
+            await fs.rm(sessionDir, { recursive: true, force: true });
+            // Also remove IA if it exists
+            const userId = this.sessionKeyToUserId(sessionKey);
+            this.interactionAgents.delete(userId);
+            this.logger.info("Session reset", { sessionKey });
+        }
+        catch (error) {
+            this.logger.error("resetSession failed", { error, sessionKey });
+            throw error;
+        }
+    }
+    async shutdown() {
+        try {
+            this.logger.info("Shutting down ODUControlPlane");
+            // Clear all IAs
+            this.interactionAgents.clear();
+            // Broker doesn't have a shutdown method yet, but we could add one later
+            // For now, just clear our state
+            this.logger.info("ODUControlPlane shutdown complete");
+        }
+        catch (error) {
+            this.logger.error("shutdown failed", { error });
+            throw error;
+        }
+    }
+}

package/dist/control-plane/single-agent.js

@@ -0,0 +1,249 @@
+/**
+ * SingleAgentControlPlane - Wraps the current NexusBot embedded agent behavior.
+ *
+ * This implementation maintains the existing single-agent-per-session pattern.
+ * No behavior changes - just adapting the existing code to the AgentControlPlane interface.
+ */
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveNexusAgentDir } from "../agents/agent-paths.js";
+import { queueEmbeddedPiMessage } from "../agents/pi-embedded.js";
+import { runEmbeddedPiAgent, } from "../agents/pi-embedded-runner.js";
+import { buildWorkspaceSkillSnapshot } from "../agents/skills.js";
+import { loadConfig } from "../config/config.js";
+import { listAgentSessions, loadSession, resolveSessionDir, writeSessionMetadata, } from "../config/sessions.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId, parseAgentSessionKey, } from "../routing/session-key.js";
+/**
+ * SingleAgentControlPlane wraps the existing runEmbeddedPiAgent function
+ * to implement the AgentControlPlane interface.
+ *
+ * This maintains the current behavior where each session has its own
+ * embedded agent, and messages are processed through the existing
+ * runEmbeddedPiAgent flow.
+ */
+export class SingleAgentControlPlane {
+    config;
+    workspaceDir;
+    agentDir;
+    constructor(options) {
+        this.config = options?.config ?? loadConfig();
+        this.workspaceDir = options?.workspaceDir ?? process.cwd();
+        this.agentDir = options?.agentDir ?? resolveNexusAgentDir();
+    }
+    async sendMessage(options) {
+        const { sessionKey, message, agentId: optAgentId, thinkingLevel, verboseLevel, isHeartbeat: _isHeartbeat, streaming, onChunk, onComplete, onError, } = options;
+        try {
+            // Parse session key to get agentId and sessionId
+            const parsed = parseAgentSessionKey(sessionKey);
+            const agentId = normalizeAgentId(optAgentId ?? parsed?.agentId ?? DEFAULT_AGENT_ID);
+            // In the new format, we use sessionKey as the directory name for O(1) lookup
+            // The sessionId in metadata is still a UUID for uniqueness
+            const existingSession = await loadSession(agentId, sessionKey);
+            let sessionId;
+            let sessionEntry;
+            if (!existingSession) {
+                // Create new session
+                sessionId = randomUUID(); // Internal UUID
+                sessionEntry = {
+                    sessionId,
+                    updatedAt: Date.now(),
+                    thinkingLevel: thinkingLevel ?? this.config.agent?.thinkingDefault,
+                    verboseLevel: verboseLevel ?? this.config.agent?.verboseDefault,
+                };
+                // Write initial metadata
+                // Directory name = sessionKey, sessionId in metadata = UUID
+                await writeSessionMetadata(agentId, sessionKey, {
+                    ...sessionEntry,
+                    created: new Date().toISOString(),
+                });
+            }
+            else {
+                sessionId = existingSession.metadata.sessionId;
+                sessionEntry = existingSession.metadata;
+            }
+            const sessionDir = resolveSessionDir(agentId, sessionKey);
+            const sessionFile = path.join(sessionDir, "history.jsonl");
+            // If streaming and already has an active agent, try to queue the message
+            if (streaming && queueEmbeddedPiMessage(sessionId, message)) {
+                return {
+                    success: true,
+                    sessionId,
+                };
+            }
+            // Load skills snapshot
+            const skillsSnapshot = buildWorkspaceSkillSnapshot(this.workspaceDir, {
+                config: this.config,
+            });
+            // Build callbacks for streaming/chunks
+            const partialPayloads = [];
+            const onPartialReply = async (payload) => {
+                if (onChunk) {
+                    onChunk({
+                        type: "text",
+                        content: payload.text,
+                        metadata: { mediaUrls: payload.mediaUrls },
+                    });
+                }
+                partialPayloads.push(payload);
+            };
+            const onToolResult = async (payload) => {
+                if (onChunk) {
+                    onChunk({
+                        type: "tool",
+                        content: payload.text,
+                        metadata: { mediaUrls: payload.mediaUrls },
+                    });
+                }
+            };
+            // Run the embedded agent
+            const runId = randomUUID();
+            const result = await runEmbeddedPiAgent({
+                sessionId,
+                sessionKey,
+                sessionFile,
+                workspaceDir: this.workspaceDir,
+                agentDir: this.agentDir,
+                config: this.config,
+                skillsSnapshot,
+                prompt: message,
+                provider: sessionEntry.providerOverride,
+                model: sessionEntry.modelOverride,
+                authProfileId: sessionEntry.authProfileOverride,
+                thinkLevel: thinkingLevel,
+                verboseLevel: verboseLevel,
+                timeoutMs: (this.config.agent?.timeoutSeconds ?? 600) * 1000,
+                runId,
+                onPartialReply: streaming ? onPartialReply : undefined,
+                onToolResult: streaming ? onToolResult : undefined,
+            });
+            // Call onComplete if provided
+            if (onComplete) {
+                onComplete();
+            }
+            // Convert result to SendMessageResult
+            // Note: EmbeddedPiRunResult doesn't have an error field; errors are thrown as exceptions
+            return {
+                success: true,
+                sessionId,
+                payloads: result.payloads,
+                meta: {
+                    durationMs: result.meta.durationMs,
+                    provider: result.meta.agentMeta?.provider,
+                    model: result.meta.agentMeta?.model,
+                    usage: result.meta.agentMeta?.usage,
+                },
+            };
+        }
+        catch (error) {
+            if (onError) {
+                onError(error);
+            }
+            return {
+                success: false,
+                error: error.message,
+            };
+        }
+    }
+    async getSession(sessionKey) {
+        try {
+            const parsed = parseAgentSessionKey(sessionKey);
+            const agentId = normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
+            // Load session from new format
+            const session = await loadSession(agentId, sessionKey);
+            if (!session) {
+                return null;
+            }
+            const entry = session.metadata;
+            return {
+                key: sessionKey,
+                sessionId: entry.sessionId,
+                displayName: entry.displayName,
+                updatedAt: entry.updatedAt,
+                model: entry.model,
+                usage: {
+                    inputTokens: entry.inputTokens,
+                    outputTokens: entry.outputTokens,
+                    totalTokens: entry.totalTokens,
+                },
+                entry,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async listSessions() {
+        try {
+            const agentId = DEFAULT_AGENT_ID;
+            // List all session keys (directory names) for the agent using new format
+            const sessionKeys = await listAgentSessions(agentId);
+            const sessions = [];
+            for (const sessionKey of sessionKeys) {
+                // Load each session (sessionKey is the directory name)
+                const session = await loadSession(agentId, sessionKey);
+                if (session) {
+                    const entry = session.metadata;
+                    sessions.push({
+                        key: sessionKey, // sessionKey is the directory name
+                        sessionId: entry.sessionId, // UUID from metadata
+                        displayName: entry.displayName,
+                        updatedAt: entry.updatedAt,
+                        model: entry.model,
+                        usage: {
+                            inputTokens: entry.inputTokens,
+                            outputTokens: entry.outputTokens,
+                            totalTokens: entry.totalTokens,
+                        },
+                        entry,
+                    });
+                }
+            }
+            // Sort by updatedAt descending (most recent first)
+            sessions.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+            return sessions;
+        }
+        catch {
+            return [];
+        }
+    }
+    async getStatus() {
+        try {
+            const sessions = await this.listSessions();
+            return {
+                mode: "single",
+                activeSessions: sessions.length,
+                healthy: true,
+            };
+        }
+        catch (error) {
+            return {
+                mode: "single",
+                activeSessions: 0,
+                healthy: false,
+                metadata: {
+                    error: error.message,
+                },
+            };
+        }
+    }
+    async resetSession(sessionKey) {
+        const parsed = parseAgentSessionKey(sessionKey);
+        const agentId = normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
+        // Remove the session directory (new format)
+        const sessionDir = resolveSessionDir(agentId, sessionKey);
+        try {
+            await fs.promises.rm(sessionDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            // If directory doesn't exist, that's fine
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+    async shutdown() {
+        // Single agent mode doesn't need cleanup
+        // Future: could flush any pending operations
+    }
+}

package/dist/control-plane/types.js

@@ -0,0 +1,11 @@
+/**
+ * AgentControlPlane - Abstract interface for agent orchestration.
+ *
+ * This interface allows swapping between different agent control strategies:
+ * - SingleAgentControlPlane: Current NexusBot behavior (one agent per session)
+ * - ODUControlPlane: Orchestration Domain Unit pattern (Interaction Agent + Execution Agents)
+ *
+ * The Gateway (Access Plane) interacts with agents through this interface,
+ * not directly with agent implementations.
+ */
+export {};