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

package/dist/control-plane/compaction.js

@@ -0,0 +1,284 @@
+import Anthropic from "@anthropic-ai/sdk";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { compactEmbeddedPiSession, } from "../agents/pi-embedded-runner.js";
+import { archiveHistory, loadHistory, resolveSessionDir, writeSummary, } from "../config/sessions.js";
+import { createSubsystemLogger } from "../logging.js";
+const log = createSubsystemLogger("compaction");
+/**
+ * Compact a session by archiving old history and generating a summary.
+ *
+ * This function:
+ * 1. Loads current history from history.jsonl
+ * 2. Optionally calls pi-agent's session.compact() if usePiAgent is true
+ * 3. Partitions history into (old messages to archive, recent messages to keep)
+ * 4. Archives old messages to archives/{n}.jsonl (incrementing n)
+ * 5. Generates an LLM-based summary (or uses pi-agent's summary if available)
+ * 6. Writes the summary to summary.md
+ * 7. Keeps recent messages in history.jsonl for continuity
+ *
+ * After compaction, the agent can reference summary.md for archived context,
+ * use recent messages in history.jsonl for immediate continuity,
+ * and search archives/ if needed (Cursor-style dynamic context discovery).
+ */
+export async function compactSession(agentId, sessionId, options = {}) {
+    try {
+        log.info(`Compacting session ${agentId}/${sessionId}`);
+        // If usePiAgent is enabled, call pi-agent's session.compact() first
+        let piAgentResult;
+        let piAgentSummary;
+        let piAgentFirstKeptEntryId;
+        if (options.usePiAgent && options.sessionFile && options.workspaceDir) {
+            log.info(`Calling pi-agent compaction for session ${agentId}/${sessionId}`);
+            piAgentResult = await compactEmbeddedPiSession({
+                sessionId,
+                sessionFile: options.sessionFile,
+                workspaceDir: options.workspaceDir,
+                agentDir: options.agentDir,
+                config: options.config,
+                customInstructions: options.customInstructions,
+            });
+            if (piAgentResult.ok && piAgentResult.compacted && piAgentResult.result) {
+                piAgentSummary = piAgentResult.result.summary;
+                piAgentFirstKeptEntryId = piAgentResult.result.firstKeptEntryId;
+                log.info(`Pi-agent compaction succeeded: ${piAgentResult.result.tokensBefore} tokens before, firstKeptEntryId: ${piAgentFirstKeptEntryId}`);
+            }
+            else {
+                log.warn(`Pi-agent compaction failed or did not compact: ${piAgentResult.reason ?? "unknown reason"}`);
+            }
+        }
+        // Load current history from our new session format
+        const history = await loadHistory(agentId, sessionId);
+        if (history.length === 0) {
+            log.info(`No history to compact for session ${agentId}/${sessionId}`);
+            return {
+                success: false,
+                error: "No history to compact",
+                piAgentResult,
+            };
+        }
+        log.debug(`Loaded ${history.length} turns for session ${agentId}/${sessionId}`);
+        // Partition history into (old messages to archive, recent messages to keep)
+        const keepRecentMessages = options.keepRecentMessages ?? 10;
+        const keepRecentTokens = options.keepRecentTokens;
+        const { toArchive, toKeep, firstKeptTurnId } = partitionHistory(history, keepRecentMessages, keepRecentTokens);
+        if (toArchive.length === 0) {
+            log.info(`No messages to archive for session ${agentId}/${sessionId} (${toKeep.length} messages below threshold)`);
+            return {
+                success: false,
+                error: "No messages to archive (all messages are recent)",
+                piAgentResult,
+            };
+        }
+        log.debug(`Partitioned ${history.length} turns: ${toArchive.length} to archive, ${toKeep.length} to keep`);
+        // Archive old messages and keep recent ones FIRST so we know the archive path
+        const archiveNumber = await archiveHistory(agentId, sessionId, toKeep);
+        const archivePath = path.join(resolveSessionDir(agentId, sessionId), "archives", `${String(archiveNumber).padStart(3, "0")}.jsonl`);
+        // Use pi-agent's summary if available, otherwise generate our own
+        let summary;
+        if (piAgentSummary) {
+            log.info("Using summary from pi-agent compaction");
+            // Add metadata header to pi-agent summary with archive path
+            summary = `# Conversation Summary
+
+Generated: ${new Date().toISOString()}
+Turns summarized: ${toArchive.length}
+Archive: ${archivePath}
+Source: pi-agent compaction
+
+---
+
+${piAgentSummary}
+`;
+        }
+        else {
+            log.info("Generating summary using Anthropic API");
+            summary = await generateSummary(toArchive, options, archivePath);
+        }
+        log.info(`Archived ${toArchive.length} turns to archives/${String(archiveNumber).padStart(3, "0")}.jsonl, kept ${toKeep.length} recent turns`);
+        // Write summary to summary.md
+        await writeSummary(agentId, sessionId, summary);
+        log.info(`Wrote summary to summary.md (${summary.length} characters)`);
+        return {
+            success: true,
+            archiveNumber,
+            summary,
+            turnsArchived: toArchive.length,
+            turnsKept: toKeep.length,
+            firstKeptTurnId: piAgentFirstKeptEntryId ?? firstKeptTurnId,
+            piAgentResult,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error(`Failed to compact session ${agentId}/${sessionId}: ${errorMessage}`);
+        return {
+            success: false,
+            error: errorMessage,
+        };
+    }
+}
+/**
+ * Partition history into (old messages to archive, recent messages to keep).
+ * Uses either token-based or message-based threshold.
+ */
+function partitionHistory(history, keepRecentMessages, keepRecentTokens) {
+    if (keepRecentTokens !== undefined) {
+        // Token-based partitioning (approximate token count using character length)
+        // Rough approximation: 1 token ≈ 4 characters
+        let tokenCount = 0;
+        let keepIndex = history.length;
+        // Work backwards from the end
+        for (let i = history.length - 1; i >= 0; i--) {
+            const turn = history[i];
+            const estimatedTokens = Math.ceil((turn.content?.length ?? 0) / 4 +
+                (turn.tool_calls
+                    ? JSON.stringify(turn.tool_calls).length / 4
+                    : 0));
+            tokenCount += estimatedTokens;
+            if (tokenCount > keepRecentTokens) {
+                // Found the split point
+                keepIndex = i + 1;
+                break;
+            }
+        }
+        const toArchive = history.slice(0, keepIndex);
+        const toKeep = history.slice(keepIndex);
+        const firstKeptTurnId = toKeep.length > 0 ? toKeep[0].turn_id : undefined;
+        return { toArchive, toKeep, firstKeptTurnId };
+    }
+    else {
+        // Message-based partitioning
+        const keepCount = Math.min(keepRecentMessages, history.length);
+        const archiveCount = history.length - keepCount;
+        const toArchive = history.slice(0, archiveCount);
+        const toKeep = history.slice(archiveCount);
+        const firstKeptTurnId = toKeep.length > 0 ? toKeep[0].turn_id : undefined;
+        return { toArchive, toKeep, firstKeptTurnId };
+    }
+}
+/**
+ * Write history to a temporary file for LLM reference (Cursor-style pattern).
+ * Returns the file path and formatted history content.
+ */
+async function writeHistoryToTempFile(history) {
+    const formattedHistory = formatHistoryForSummary(history);
+    // Create temp file in OS temp directory
+    const tmpDir = os.tmpdir();
+    const tmpFilePath = path.join(tmpDir, `nexus-history-${Date.now()}.txt`);
+    await fs.promises.writeFile(tmpFilePath, formattedHistory, "utf-8");
+    return { tmpFilePath, formattedHistory };
+}
+/**
+ * Generate a summary of conversation history using Claude.
+ * Writes history to a temp file first so the LLM can reference specific details (Cursor-style).
+ */
+async function generateSummary(history, options, archivePath) {
+    const apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        throw new Error("ANTHROPIC_API_KEY environment variable is required for compaction");
+    }
+    const anthropic = new Anthropic({ apiKey });
+    const model = options.model ?? "claude-3-5-haiku-20241022";
+    const maxTokens = options.maxTokens ?? 2000;
+    // Write history to temp file for LLM reference (Cursor-style pattern)
+    const { tmpFilePath, formattedHistory } = await writeHistoryToTempFile(history);
+    try {
+        const systemPrompt = `You are an expert at summarizing conversation history for context preservation.
+
+Your task is to create a concise, information-dense summary of the conversation history provided.
+
+Guidelines:
+- Focus on key decisions, outcomes, and important context
+- Preserve technical details that might be referenced later
+- Include any unresolved issues or pending tasks
+- Use clear, structured markdown format
+- Be comprehensive but concise (aim for 500-1500 words)
+- Start with a brief overview, then provide detailed sections as needed
+- If you need to reference specific details from the history, you can refer to line numbers (the history is formatted with timestamps)
+
+Structure your summary with:
+1. Overview (2-3 sentences)
+2. Key Topics & Decisions
+3. Technical Details (if applicable)
+4. Pending Items / Next Steps (if any)`;
+        log.debug(`Generating summary for ${history.length} turns using ${model}`);
+        log.debug(`History written to temp file: ${tmpFilePath}`);
+        const response = await anthropic.messages.create({
+            model,
+            max_tokens: maxTokens,
+            system: systemPrompt,
+            messages: [
+                {
+                    role: "user",
+                    content: `Please summarize this conversation history.
+
+The full conversation history has been written to: ${tmpFilePath}
+
+History content:
+
+${formattedHistory}`,
+                },
+            ],
+        });
+        const summaryText = response.content[0]?.type === "text" ? response.content[0].text : "";
+        if (!summaryText) {
+            throw new Error("Failed to generate summary: empty response from Claude");
+        }
+        // Add metadata header with PERMANENT archive path (not temp file)
+        // This allows agents to search the archive later if the summary lacks detail
+        const archiveNote = archivePath
+            ? `Archive: ${archivePath}`
+            : `History file: ${tmpFilePath}`;
+        const metadata = `# Conversation Summary
+
+Generated: ${new Date().toISOString()}
+Turns summarized: ${history.length}
+Model: ${model}
+${archiveNote}
+
+---
+
+${summaryText}
+`;
+        return metadata;
+    }
+    finally {
+        // Clean up temp file
+        try {
+            await fs.promises.unlink(tmpFilePath);
+            log.debug(`Cleaned up temp history file: ${tmpFilePath}`);
+        }
+        catch (error) {
+            log.warn(`Failed to clean up temp history file ${tmpFilePath}: ${error}`);
+        }
+    }
+}
+/**
+ * Format history turns into a readable format for summarization.
+ */
+function formatHistoryForSummary(history) {
+    const lines = [];
+    for (const turn of history) {
+        const timestamp = turn.timestamp
+            ? new Date(turn.timestamp).toISOString()
+            : "unknown";
+        const role = turn.role.toUpperCase();
+        lines.push(`[${timestamp}] ${role}:`);
+        if (turn.content) {
+            lines.push(turn.content);
+        }
+        if (turn.tool_calls && turn.tool_calls.length > 0) {
+            lines.push("\nTool Calls:");
+            for (const toolCall of turn.tool_calls) {
+                lines.push(`  - ${toolCall.function.name}(${toolCall.function.arguments})`);
+            }
+        }
+        if (turn.tool_call_id) {
+            lines.push(`Tool Response (call_id: ${turn.tool_call_id})`);
+        }
+        lines.push(""); // Blank line between turns
+    }
+    return lines.join("\n");
+}

package/dist/control-plane/factory.js

@@ -0,0 +1,31 @@
+/**
+ * Factory for creating the appropriate AgentControlPlane implementation
+ * based on configuration.
+ */
+import { SingleAgentControlPlane } from "./single-agent.js";
+import { ODUControlPlane } from "./odu-control-plane.js";
+/**
+ * Creates an AgentControlPlane instance based on the config.
+ *
+ * @param options - Factory options (config, workspace, agent dir)
+ * @returns AgentControlPlane instance
+ * @throws Error if mode is 'odu' (not yet implemented)
+ */
+export function createControlPlane(options) {
+    const mode = options?.config?.controlPlane?.mode ?? "single";
+    switch (mode) {
+        case "single":
+            return new SingleAgentControlPlane({
+                config: options?.config,
+                workspaceDir: options?.workspaceDir,
+                agentDir: options?.agentDir,
+            });
+        case "odu":
+            return new ODUControlPlane({
+                config: options?.config,
+                workspaceDir: options?.workspaceDir,
+            });
+        default:
+            throw new Error(`Unknown control plane mode: ${mode}. Valid modes: 'single', 'odu'`);
+    }
+}

package/dist/control-plane/index.js

@@ -0,0 +1,10 @@
+/**
+ * Agent Control Plane - Abstraction layer for agent orchestration.
+ *
+ * This module provides an abstract interface for managing agent sessions
+ * and routing messages. It allows switching between different orchestration
+ * strategies without changing the Gateway (Access Plane) code.
+ */
+export { SingleAgentControlPlane } from "./single-agent.js";
+export { ODUControlPlane } from "./odu-control-plane.js";
+export { createControlPlane } from "./factory.js";

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

@@ -0,0 +1,187 @@
+/**
+ * ODU Agent Base Classes
+ *
+ * Adapted from magic-toolbox for Nexus
+ * Wraps Nexus pi-coding-agent session API
+ */
+import { createSubsystemLogger } from '../../logging.js';
+/**
+ * Base Interaction Agent
+ *
+ * User-facing orchestrator that delegates to Execution Agents
+ * Uses message queue for handling rapid bursts of messages
+ */
+export class InteractionAgent {
+    agentId;
+    sessionId;
+    userId;
+    oduPath;
+    oduConfig;
+    config;
+    model;
+    maxTurns;
+    log;
+    // Message queue and processing state
+    messageQueue = [];
+    isProcessing = false;
+    isStreaming = false;
+    shouldInterrupt = false;
+    accumulatedResponse = '';
+    constructor(config) {
+        this.userId = config.userId;
+        this.agentId = config.agentId || `${config.oduPath || 'nexus'}-ia`;
+        this.sessionId = config.sessionId || this.agentId;
+        this.oduPath = config.oduPath || '~/nexus/home';
+        this.config = config.config;
+        this.model = config.model || 'claude-sonnet-4-5-20250929';
+        this.maxTurns = config.maxTurns || 20;
+        // Initialize ODU config (will be set by subclass)
+        this.oduConfig = {
+            name: 'nexus',
+            purpose: 'Nexus Interaction Agent',
+        };
+        this.log = createSubsystemLogger(`odu/${this.agentId}`);
+    }
+    /**
+     * Queue a message for processing
+     */
+    queueMessage(content, priority = 'normal', from) {
+        this.messageQueue.push({
+            id: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+            content,
+            priority,
+            from,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Process queued messages without adding a new message
+     * Called by broker when messages are queued externally
+     *
+     * Returns IMMEDIATE acknowledgment, then processes async in background
+     */
+    async processQueue() {
+        this.log.info('processQueue() called', {
+            queueLength: this.messageQueue.length,
+            isProcessing: this.isProcessing,
+        });
+        // If already processing, return early
+        if (this.isProcessing) {
+            return 'IA is currently processing another request';
+        }
+        // If no messages queued, return early
+        if (this.messageQueue.length === 0) {
+            return 'No messages to process';
+        }
+        // Peek at first message to generate acknowledgment
+        const firstMessage = this.messageQueue[0];
+        const ackMessage = firstMessage.from
+            ? `Acknowledged request from ${firstMessage.from}. Processing now...`
+            : 'Acknowledged. Processing...';
+        // Start processing in background (don't await!)
+        this.processQueueAsync().catch((error) => {
+            this.log.error('Background processing error', { error });
+        });
+        // Return acknowledgment immediately
+        return ackMessage;
+    }
+    /**
+     * Internal async processing (runs in background after ack sent)
+     */
+    async processQueueAsync() {
+        this.isProcessing = true;
+        try {
+            let finalResponse = '';
+            // Process all queued messages
+            while (this.messageQueue.length > 0) {
+                // Dequeue all current messages
+                const messages = this.messageQueue.splice(0);
+                // Sort by priority
+                messages.sort((a, b) => {
+                    const priorityOrder = { urgent: 0, high: 1, normal: 2, low: 3 };
+                    const aPriority = priorityOrder[a.priority] || 2;
+                    const bPriority = priorityOrder[b.priority] || 2;
+                    if (aPriority !== bPriority)
+                        return aPriority - bPriority;
+                    return a.timestamp - b.timestamp;
+                });
+                // Extract sender from first message
+                const from = messages[0].from;
+                // Combine messages
+                const combinedMessage = messages.length === 1
+                    ? messages[0].content
+                    : messages.map((m, i) => `Message ${i + 1}:\n${m.content}`).join('\n\n---\n\n');
+                // Reset interrupt flag
+                this.shouldInterrupt = false;
+                // Process the combined message with sender context
+                finalResponse = await this.processSingleMessage(combinedMessage, from);
+            }
+            this.log.info('Async processing complete', {
+                responseLength: finalResponse.length,
+            });
+        }
+        finally {
+            this.isProcessing = false;
+            this.isStreaming = false;
+        }
+    }
+    /**
+     * Interrupt current streaming operation
+     */
+    interrupt() {
+        if (this.isStreaming) {
+            this.log.info('Interrupting mid-stream', {
+                accumulatedLength: this.accumulatedResponse.length,
+            });
+            this.shouldInterrupt = true;
+            this.isStreaming = false;
+        }
+    }
+    /**
+     * Check if currently being interrupted
+     */
+    checkInterrupt() {
+        return this.shouldInterrupt;
+    }
+}
+/**
+ * Base Execution Agent
+ *
+ * Autonomous task executor with isolated workspace
+ * Executes a single task and stops (broker manages lifecycle)
+ */
+export class ExecutionAgent {
+    agentId;
+    task;
+    userId;
+    oduPath;
+    oduConfig;
+    config;
+    model;
+    maxTurns;
+    history;
+    log;
+    constructor(config) {
+        this.userId = config.userId;
+        this.task = config.task;
+        this.agentId = config.agentId || `${config.oduPath || 'nexus'}-ea-${this.task.taskName || 'task'}`;
+        this.oduPath = config.oduPath || '~/nexus/home';
+        this.config = config.config;
+        // Support model override: task.model > config.model > default Haiku 4.5
+        this.model = config.task.model || config.model || 'claude-haiku-4-5-20251001';
+        this.maxTurns = config.maxTurns || 50;
+        this.history = config.history || [];
+        // Initialize ODU config (will be set by subclass)
+        this.oduConfig = {
+            name: 'nexus',
+            purpose: 'Nexus Execution Agent',
+        };
+        this.log = createSubsystemLogger(`odu/${this.agentId}`);
+    }
+    /**
+     * Build initial prompt for the task
+     */
+    buildInitialPrompt() {
+        return this.task.description || 'Complete the task';
+    }
+}