@tenex-chat/backend 0.9.1

package/src/agents/execution/ToolSupervisionWrapper.ts

@@ -0,0 +1,174 @@
+/**
+ * Tool supervision wrapper for pre-tool execution checks.
+ *
+ * Intercepts tool execution to run heuristics before the tool executes.
+ * This allows the supervision system to block or modify tool calls based
+ * on configured policies (e.g., preventing certain actions without approval).
+ */
+import {
+    supervisorOrchestrator,
+    type PreToolContext,
+} from "@/agents/supervision";
+import type { ToolExecutionOptions } from "@ai-sdk/provider-utils";
+import type { Tool as CoreTool } from "ai";
+import { AgentEventDecoder } from "@/nostr/AgentEventDecoder";
+import { buildSystemPromptMessages } from "@/prompts/utils/systemPromptBuilder";
+import { NudgeService } from "@/services/nudge";
+import { getProjectContext } from "@/services/projects";
+import { RALRegistry } from "@/services/ral";
+import { getToolsObject } from "@/tools/registry";
+import type { FullRuntimeContext } from "./types";
+import { formatAnyError } from "@/lib/error-formatter";
+import { logger } from "@/utils/logger";
+
+/**
+ * Wrap tools with pre-tool supervision checks.
+ *
+ * This function intercepts each tool's execute method to run supervision
+ * heuristics before the tool actually executes. If a violation is detected,
+ * the tool execution is blocked and a message is returned to the agent.
+ *
+ * @param toolsObject - The original tools object from the tool registry
+ * @param context - The full runtime context for the execution
+ * @returns A new tools object with wrapped execute methods
+ */
+export function wrapToolsWithSupervision(
+    toolsObject: Record<string, CoreTool<unknown, unknown>>,
+    context: FullRuntimeContext
+): Record<string, CoreTool<unknown, unknown>> {
+    const wrappedTools: Record<string, CoreTool<unknown, unknown>> = {};
+    const ralRegistry = RALRegistry.getInstance();
+
+    for (const [toolName, tool] of Object.entries(toolsObject)) {
+        // Skip tools without execute function
+        if (!tool.execute) {
+            wrappedTools[toolName] = tool;
+            continue;
+        }
+
+        // Preserve the original tool's properties
+        const originalExecute = tool.execute.bind(tool);
+
+        // Create wrapped tool
+        wrappedTools[toolName] = {
+            ...tool,
+            execute: async (input: unknown, options: ToolExecutionOptions) => {
+                try {
+                    // Build PreToolContext for this tool
+                    const conversation = context.getConversation();
+                    const conversationStore = context.conversationStore;
+
+                    // Get system prompt and conversation history
+                    const projectContext = getProjectContext();
+
+                    // Fetch nudge content if triggering event has nudge tags
+                    const preToolNudgeEventIds = AgentEventDecoder.extractNudgeEventIds(context.triggeringEvent);
+                    const preToolNudgeContent = preToolNudgeEventIds.length > 0
+                        ? await NudgeService.getInstance().fetchNudges(preToolNudgeEventIds)
+                        : "";
+
+                    const systemPromptMessages = await buildSystemPromptMessages({
+                        agent: context.agent,
+                        project: projectContext.project,
+                        conversation,
+                        projectBasePath: context.projectBasePath,
+                        workingDirectory: context.workingDirectory,
+                        currentBranch: context.currentBranch,
+                        availableAgents: Array.from(projectContext.agents.values()),
+                        mcpManager: projectContext.mcpManager,
+                        agentLessons: projectContext.agentLessons,
+                        nudgeContent: preToolNudgeContent,
+                    });
+                    const systemPrompt = systemPromptMessages.map(m => m.message.content).join("\n\n");
+
+                    // Build conversation history from ConversationStore
+                    const conversationMessages = await conversationStore.buildMessagesForRal(context.agent.pubkey, context.ralNumber);
+
+                    // Get available tools
+                    const toolNames = context.agent.tools || [];
+                    const toolsForContext = toolNames.length > 0 ? getToolsObject(toolNames, context) : {};
+
+                    // Build PreToolContext
+                    const preToolContext: PreToolContext = {
+                        agentSlug: context.agent.slug,
+                        agentPubkey: context.agent.pubkey,
+                        toolName,
+                        toolArgs: input,
+                        systemPrompt,
+                        conversationHistory: conversationMessages,
+                        availableTools: toolsForContext,
+                    };
+
+                    // Run pre-tool supervision check
+                    logger.debug(`[ToolSupervisionWrapper] Running pre-tool supervision for "${toolName}"`, {
+                        agent: context.agent.slug,
+                    });
+
+                    // Build executionId for heuristic enforcement tracking
+                    const preToolExecutionId = `${context.agent.pubkey}:${context.conversationId}:${context.ralNumber}`;
+                    const supervisionResult = await supervisorOrchestrator.checkPreTool(preToolContext, preToolExecutionId);
+
+                    // If supervision detected a violation, block the tool
+                    if (supervisionResult.hasViolation && supervisionResult.correctionAction) {
+                        logger.warn(
+                            `[ToolSupervisionWrapper] Pre-tool supervision blocked "${toolName}" execution`,
+                            {
+                                agent: context.agent.slug,
+                                heuristic: supervisionResult.heuristicId,
+                                actionType: supervisionResult.correctionAction.type,
+                            }
+                        );
+
+                        // Mark this heuristic as enforced so it won't fire again in this RAL
+                        if (supervisionResult.heuristicId) {
+                            supervisorOrchestrator.markHeuristicEnforced(preToolExecutionId, supervisionResult.heuristicId);
+                        }
+
+                        // Queue correction message if available (for both inject-message and block-tool)
+                        if (
+                            supervisionResult.correctionAction.message &&
+                            supervisionResult.correctionAction.reEngage
+                        ) {
+                            ralRegistry.queueUserMessage(
+                                context.agent.pubkey,
+                                context.conversationId,
+                                context.ralNumber,
+                                supervisionResult.correctionAction.message
+                            );
+                        }
+
+                        // Return a blocked execution message
+                        return `Tool execution blocked: ${supervisionResult.correctionAction.message || "This tool cannot be executed at this time."}`;
+                    }
+
+                    // No violation - execute the original tool
+                    logger.debug(`[ToolSupervisionWrapper] Pre-tool supervision passed for "${toolName}"`, {
+                        agent: context.agent.slug,
+                    });
+
+                    return await originalExecute(input, options);
+                } catch (error) {
+                    logger.error("[ToolSupervisionWrapper] Error during pre-tool supervision check", {
+                        tool: toolName,
+                        error: formatAnyError(error),
+                    });
+                    // On supervision error, allow tool to execute (fail-safe)
+                    return await originalExecute(input, options);
+                }
+            },
+        };
+
+        // Preserve non-enumerable properties like getHumanReadableContent
+        const toolWithCustomProps = tool as CoreTool<unknown, unknown> & {
+            getHumanReadableContent?: (args: unknown) => string;
+        };
+        if (toolWithCustomProps.getHumanReadableContent) {
+            Object.defineProperty(wrappedTools[toolName], "getHumanReadableContent", {
+                value: toolWithCustomProps.getHumanReadableContent,
+                enumerable: false,
+            });
+        }
+    }
+
+    return wrappedTools;
+}

package/src/agents/execution/constants.ts

@@ -0,0 +1,16 @@
+/**
+ * Configuration constants for agent execution
+ */
+export const ExecutionConfig = {
+    /** Delay in milliseconds after publishing typing indicator */
+    TOOL_INDICATOR_DELAY_MS: 100,
+
+    /** Default duration for tool execution when not tracked */
+    DEFAULT_TOOL_DURATION_MS: 1000,
+
+    /** Default timeout for shell commands in milliseconds (30 seconds) */
+    DEFAULT_COMMAND_TIMEOUT_MS: 30000,
+
+    /** Threshold for considering a phase transition as recent in milliseconds (30 seconds) */
+    RECENT_TRANSITION_THRESHOLD_MS: 30000,
+} as const;

package/src/agents/execution/index.ts

@@ -0,0 +1,3 @@
+export * from "./AgentExecutor";
+export * from "./ExecutionContextFactory";
+export * from "./types";

package/src/agents/execution/types.ts

@@ -0,0 +1,96 @@
+import type { Tool as CoreTool, ModelMessage } from "ai";
+import type { AgentInstance } from "@/agents/types";
+import type { MessageCompiler } from "@/agents/execution/MessageCompiler";
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import type { CompleteEvent } from "@/llm/types";
+import type { AgentPublisher } from "@/nostr/AgentPublisher";
+import type { MCPManager } from "@/services/mcp/MCPManager";
+import type { ToolRegistryContext } from "@/tools/types";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+
+/**
+ * Execution context for agent runs.
+ *
+ * This is the context created by createExecutionContext and enriched during execution.
+ * Runtime dependencies (agentPublisher, ralNumber, conversationStore) may not be
+ * available at creation time - they are added by prepareExecution().
+ *
+ * When passing context to tools via getToolsObject(), ensure all required fields
+ * are present (use ToolRegistryContext type to enforce this).
+ */
+export interface ExecutionContext {
+    agent: AgentInstance;
+    conversationId: string;
+    projectBasePath: string;
+    workingDirectory: string;
+    currentBranch: string;
+    triggeringEvent: NDKEvent;
+    getConversation: () => ConversationStore | undefined;
+
+    // Runtime dependencies - added by prepareExecution()
+    agentPublisher?: AgentPublisher;
+    ralNumber?: number;
+    conversationStore?: ConversationStore;
+
+    // Execution flags
+    isDelegationCompletion?: boolean;
+    hasPendingDelegations?: boolean;
+    debug?: boolean;
+    mcpManager?: MCPManager;
+}
+
+
+/**
+ * Result of executeStreaming - discriminated union for clear error handling.
+ * - 'complete': Stream finished successfully with a completion event
+ * - 'error-handled': Stream error occurred and was already published to user
+ */
+export type StreamExecutionResult =
+    | {
+          kind: "complete";
+          event: CompleteEvent;
+          aborted?: boolean;
+          /** The reason the execution was aborted (if aborted=true) */
+          abortReason?: string;
+          messageCompiler: MessageCompiler;
+          /** Accumulated LLM runtime in milliseconds (captured before RAL cleanup) */
+          accumulatedRuntime: number;
+      }
+    | { kind: "error-handled" };
+
+/**
+ * Mutable context for RAL execution state during streaming.
+ *
+ * Makes explicit the state that coordinates between prepareStep and onStopCheck
+ * callbacks. Previously this was implicit closure variables.
+ */
+export interface RALExecutionContext {
+    /**
+     * Messages accumulated from prepareStep callbacks.
+     * Updated in prepareStep (before each LLM step), read in onStopCheck.
+     * Contains messages up to but not including the current step.
+     */
+    accumulatedMessages: ModelMessage[];
+}
+
+/**
+ * Full runtime context for executor methods.
+ * Extends ToolRegistryContext with:
+ * - agent: AgentInstance (full agent type, not just ToolAgentInfo)
+ * - Execution-specific flags from ExecutionContext
+ */
+export type FullRuntimeContext = Omit<ToolRegistryContext, "agent"> & {
+    agent: AgentInstance;
+    isDelegationCompletion?: boolean;
+    hasPendingDelegations?: boolean;
+};
+
+/**
+ * Request object for LLM completion preparation.
+ * Created by prepareLLMRequest() for external callers that need to prepare
+ * an LLM request without executing it (e.g., schema extraction).
+ */
+export interface LLMCompletionRequest {
+    messages: ModelMessage[];
+    tools?: Record<string, CoreTool>;
+}

package/src/agents/execution/utils.ts

@@ -0,0 +1,26 @@
+import type { ModelMessage } from "ai";
+
+/**
+ * Extract the text content from the last user message in the conversation.
+ * Handles both simple string content and complex content arrays (with text parts).
+ */
+export function extractLastUserMessage(messages: ModelMessage[]): string | undefined {
+    // Find the last user message
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role === "user") {
+            // Handle simple string content
+            if (typeof msg.content === "string") {
+                return msg.content;
+            }
+            // Handle complex content arrays (e.g., [{ type: "text", text: "hello" }])
+            if (Array.isArray(msg.content)) {
+                const textParts = msg.content
+                    .filter((part): part is { type: "text"; text: string } => part.type === "text")
+                    .map(part => part.text);
+                return textParts.join("\n");
+            }
+        }
+    }
+    return undefined;
+}

package/src/agents/index.ts

@@ -0,0 +1,4 @@
+export { AgentRegistry } from "./AgentRegistry";
+export * from "./execution";
+export type { AgentInstance, AgentSummary } from "./types/runtime";
+export type { AgentConfig, AgentConfigOptionalNsec, StoredAgentData } from "./types/storage";

package/src/agents/script-installer.ts

@@ -0,0 +1,266 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type NDK from "@nostr-dev-kit/ndk";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { getAgentHomeDirectory } from "@/lib/agent-home";
+import { ensureDirectory } from "@/lib/fs";
+import { logger } from "@/utils/logger";
+
+/**
+ * Information about a script file from a NIP-94 (kind 1063) event
+ */
+export interface ScriptFileInfo {
+    eventId: string;
+    url: string;
+    relativePath: string;
+    mimeType?: string;
+    sha256?: string;
+}
+
+/**
+ * Result of downloading and installing a script
+ */
+export interface ScriptInstallResult {
+    eventId: string;
+    relativePath: string;
+    absolutePath: string;
+    success: boolean;
+    error?: string;
+}
+
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Extract script file information from a kind 1063 (NIP-94 file metadata) event.
+ *
+ * Expected tags:
+ * - ["url", "https://blossom.server/sha256"] - Required: Blossom download URL
+ * - ["name", "scripts/research.py"] - Required: Relative filepath from agent's home
+ * - ["m", "text/x-python"] - Optional: MIME type
+ * - ["x", "sha256hash"] - Optional: SHA-256 hash for verification
+ *
+ * @param event - The kind 1063 event to extract info from
+ * @returns Script file info or null if required tags are missing
+ */
+export function extractScriptFileInfo(event: NDKEvent): ScriptFileInfo | null {
+    if (event.kind !== 1063) {
+        logger.warn(`Expected kind 1063 event, got kind ${event.kind}`);
+        return null;
+    }
+
+    const url = event.tagValue("url");
+    const relativePath = event.tagValue("name");
+
+    if (!url || !relativePath) {
+        logger.warn(`Kind 1063 event ${event.id} missing required tags`, {
+            hasUrl: !!url,
+            hasName: !!relativePath,
+        });
+        return null;
+    }
+
+    return {
+        eventId: event.id,
+        url,
+        relativePath,
+        mimeType: event.tagValue("m") || undefined,
+        sha256: event.tagValue("x") || undefined,
+    };
+}
+
+/**
+ * Download a file from a Blossom URL
+ *
+ * @param url - The Blossom URL to download from
+ * @returns The downloaded file content as a Buffer
+ */
+async function downloadFile(url: string): Promise<Buffer> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+
+    try {
+        const response = await fetch(url, {
+            headers: {
+                "User-Agent": "TENEX/1.0 (Script Installer)",
+            },
+            signal: controller.signal,
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+        }
+
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`Download timed out after ${DOWNLOAD_TIMEOUT_MS}ms`);
+        }
+        throw error;
+    } finally {
+        clearTimeout(timeout);
+    }
+}
+
+/**
+ * Install a single script file to the agent's home directory.
+ *
+ * @param scriptInfo - Information about the script to install
+ * @param agentPubkey - The agent's public key (determines home directory)
+ * @returns Result of the installation
+ */
+export async function installScriptFile(
+    scriptInfo: ScriptFileInfo,
+    agentPubkey: string
+): Promise<ScriptInstallResult> {
+    const homeDir = getAgentHomeDirectory(agentPubkey);
+    const absolutePath = path.join(homeDir, scriptInfo.relativePath);
+
+    try {
+        // Security check: ensure the path doesn't escape the home directory
+        const normalizedPath = path.normalize(absolutePath);
+        const normalizedHome = path.normalize(homeDir);
+        if (!normalizedPath.startsWith(normalizedHome)) {
+            throw new Error(
+                `Security violation: path "${scriptInfo.relativePath}" would escape agent home directory`
+            );
+        }
+
+        // Create parent directories
+        const parentDir = path.dirname(absolutePath);
+        await ensureDirectory(parentDir);
+
+        // Download the file
+        logger.debug(`Downloading script from ${scriptInfo.url}`);
+        const content = await downloadFile(scriptInfo.url);
+
+        // TODO: Verify SHA-256 hash if provided
+        // if (scriptInfo.sha256) {
+        //     const hash = crypto.createHash('sha256').update(content).digest('hex');
+        //     if (hash !== scriptInfo.sha256) {
+        //         throw new Error(`SHA-256 mismatch: expected ${scriptInfo.sha256}, got ${hash}`);
+        //     }
+        // }
+
+        // Write the file
+        await fs.writeFile(absolutePath, content);
+
+        // Make script executable if it's a script file
+        const ext = path.extname(scriptInfo.relativePath).toLowerCase();
+        const scriptExtensions = [".sh", ".py", ".rb", ".pl", ".js", ".ts"];
+        if (scriptExtensions.includes(ext)) {
+            await fs.chmod(absolutePath, 0o755);
+        }
+
+        logger.info(`Installed script: ${scriptInfo.relativePath}`, {
+            eventId: scriptInfo.eventId,
+            absolutePath,
+            size: content.length,
+        });
+
+        return {
+            eventId: scriptInfo.eventId,
+            relativePath: scriptInfo.relativePath,
+            absolutePath,
+            success: true,
+        };
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to install script: ${scriptInfo.relativePath}`, {
+            eventId: scriptInfo.eventId,
+            error: errorMessage,
+        });
+
+        return {
+            eventId: scriptInfo.eventId,
+            relativePath: scriptInfo.relativePath,
+            absolutePath,
+            success: false,
+            error: errorMessage,
+        };
+    }
+}
+
+/**
+ * Fetch and install all scripts referenced by e-tags in an agent definition.
+ *
+ * @param scriptETags - Array of script e-tag references from the agent definition
+ * @param agentPubkey - The agent's public key
+ * @param ndk - NDK instance for fetching events
+ * @returns Array of installation results
+ */
+export async function installAgentScripts(
+    scriptETags: Array<{ eventId: string; relayUrl?: string }>,
+    agentPubkey: string,
+    ndk: NDK
+): Promise<ScriptInstallResult[]> {
+    if (scriptETags.length === 0) {
+        return [];
+    }
+
+    logger.info(`Installing ${scriptETags.length} script(s) for agent`, {
+        agentPubkey: agentPubkey.substring(0, 8),
+    });
+
+    const results: ScriptInstallResult[] = [];
+
+    for (const scriptRef of scriptETags) {
+        try {
+            // Fetch the 1063 event
+            logger.debug(`Fetching script event ${scriptRef.eventId}`);
+            const event = await ndk.fetchEvent(scriptRef.eventId, { groupable: false });
+
+            if (!event) {
+                results.push({
+                    eventId: scriptRef.eventId,
+                    relativePath: "unknown",
+                    absolutePath: "unknown",
+                    success: false,
+                    error: `Could not fetch event ${scriptRef.eventId}`,
+                });
+                continue;
+            }
+
+            // Extract script info
+            const scriptInfo = extractScriptFileInfo(event);
+            if (!scriptInfo) {
+                results.push({
+                    eventId: scriptRef.eventId,
+                    relativePath: "unknown",
+                    absolutePath: "unknown",
+                    success: false,
+                    error: "Event is not a valid kind 1063 file metadata event",
+                });
+                continue;
+            }
+
+            // Install the script
+            const result = await installScriptFile(scriptInfo, agentPubkey);
+            results.push(result);
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            results.push({
+                eventId: scriptRef.eventId,
+                relativePath: "unknown",
+                absolutePath: "unknown",
+                success: false,
+                error: errorMessage,
+            });
+        }
+    }
+
+    // Log summary
+    const successCount = results.filter((r) => r.success).length;
+    const failCount = results.filter((r) => !r.success).length;
+
+    if (failCount > 0) {
+        logger.warn(`Script installation completed with errors`, {
+            success: successCount,
+            failed: failCount,
+        });
+    } else {
+        logger.info(`All scripts installed successfully`, { count: successCount });
+    }
+
+    return results;
+}