@tenex-chat/backend 0.9.1

package/src/agents/supervision/types.ts

@@ -0,0 +1,171 @@
+import type { ModelMessage, ToolSet } from "ai";
+import type { TodoStatus } from "../../services/ral/types";
+
+/**
+ * When heuristic checks run relative to agent execution
+ */
+export type HeuristicTiming = "pre-tool-execution" | "post-completion";
+
+/**
+ * Result of a heuristic detection check
+ */
+export interface HeuristicDetection {
+    /** Whether the heuristic condition was triggered */
+    triggered: boolean;
+    /** Human-readable reason for the detection */
+    reason?: string;
+    /** Additional evidence that led to the detection */
+    evidence?: unknown;
+}
+
+/**
+ * Result of LLM verification of a heuristic detection
+ */
+export interface VerificationResult {
+    /** Whether the detection was confirmed as a real violation */
+    verdict: "ok" | "violation";
+    /** Explanation of the verdict */
+    explanation: string;
+    /** Optional message to inject for correction */
+    correctionMessage?: string;
+}
+
+/**
+ * Action to take when a violation is confirmed
+ */
+export interface CorrectionAction {
+    /** Type of correction to apply */
+    type: "inject-message" | "block-tool" | "suppress-publish";
+    /** Correction message to provide to the agent. Used for inject-message type and
+     *  for suppress-publish type when reEngage is true (to guide the agent on what to fix). */
+    message?: string;
+    /** Whether to re-engage the agent after correction */
+    reEngage: boolean;
+}
+
+/**
+ * Context provided to the supervisor LLM for verification
+ */
+export interface SupervisionContext {
+    /** Agent identifier slug */
+    agentSlug: string;
+    /** Agent's Nostr public key */
+    agentPubkey: string;
+    /** The agent's system prompt */
+    systemPrompt: string;
+    /** Full conversation history */
+    conversationHistory: ModelMessage[];
+    /** Tools available to the agent */
+    availableTools: ToolSet;
+    /** ID of the heuristic that triggered */
+    triggeringHeuristic: string;
+    /** Detection result from the heuristic */
+    detection: HeuristicDetection;
+}
+
+/**
+ * State tracking for supervision of an execution
+ */
+export interface SupervisionState {
+    /** Number of retry attempts made */
+    retryCount: number;
+    /** Maximum allowed retries */
+    maxRetries: number;
+    /** ID of the last triggered heuristic */
+    lastHeuristicTriggered?: string;
+    /** Set of heuristic IDs that have been enforced in this execution (in-memory only) */
+    enforcedHeuristics: Set<string>;
+}
+
+/**
+ * Context for post-completion heuristic checks
+ */
+export interface PostCompletionContext {
+    /** Agent identifier slug */
+    agentSlug: string;
+    /** Agent's Nostr public key */
+    agentPubkey: string;
+    /** The final message content from the agent */
+    messageContent: string;
+    /** Names of tools that were called during execution */
+    toolCallsMade: string[];
+    /** The agent's system prompt */
+    systemPrompt: string;
+    /** Full conversation history */
+    conversationHistory: ModelMessage[];
+    /** Tools available to the agent */
+    availableTools: ToolSet;
+    /** Whether the agent has already been nudged about todo usage in this conversation */
+    hasBeenNudgedAboutTodos: boolean;
+    /** The agent's todo items (for detailed inspection by heuristics) */
+    todos: Array<{ id: string; title: string; status: TodoStatus; description?: string }>;
+    /** Number of pending delegations the agent is waiting for (0 if none) */
+    pendingDelegationCount: number;
+}
+
+/**
+ * Context for pre-tool execution heuristic checks
+ */
+export interface PreToolContext {
+    /** Agent identifier slug */
+    agentSlug: string;
+    /** Agent's Nostr public key */
+    agentPubkey: string;
+    /** Name of the tool about to be executed */
+    toolName: string;
+    /** Arguments passed to the tool */
+    toolArgs: unknown;
+    /** The agent's system prompt */
+    systemPrompt: string;
+    /** Full conversation history */
+    conversationHistory: ModelMessage[];
+    /** Tools available to the agent */
+    availableTools: ToolSet;
+}
+
+/**
+ * Base interface for all heuristics
+ */
+export interface Heuristic<TContext> {
+    /** Unique identifier for the heuristic */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** When this heuristic runs */
+    timing: HeuristicTiming;
+    /** Optional filter to only run for specific tools (pre-tool-execution only) */
+    toolFilter?: string[];
+    /** Skip LLM verification and apply correction directly on detection (for low-stakes nudges) */
+    skipVerification?: boolean;
+    /**
+     * Detect if the heuristic condition is met
+     * @param context - The context to check
+     * @returns Detection result indicating if triggered
+     */
+    detect(context: TContext): Promise<HeuristicDetection>;
+    /**
+     * Build the prompt for the supervisor LLM to verify the detection
+     * @param context - The context that triggered detection
+     * @param detection - The detection result
+     * @returns Prompt string for the LLM
+     */
+    buildVerificationPrompt(context: TContext, detection: HeuristicDetection): string;
+    /**
+     * Build the correction message to inject back to the agent
+     * @param context - The original context
+     * @param verification - The LLM verification result
+     * @returns Message to inject
+     */
+    buildCorrectionMessage(context: TContext, verification: VerificationResult): string;
+    /**
+     * Get the correction action to take
+     * @param verification - The LLM verification result
+     * @returns The correction action
+     */
+    getCorrectionAction(verification: VerificationResult): CorrectionAction;
+}
+
+/**
+ * Maximum number of supervision retries before giving up
+ */
+export const MAX_SUPERVISION_RETRIES = 3;

package/src/agents/tool-names.ts

@@ -0,0 +1,46 @@
+import type { ToolName } from "@/tools/types";
+import { DELEGATE_TOOLS } from "./constants";
+
+export type McpToolNameParts = {
+    serverName: string;
+    toolName: string;
+};
+
+export function parseMcpToolName(toolName: string): McpToolNameParts | null {
+    if (!toolName.startsWith("mcp__")) {
+        return null;
+    }
+
+    const parts = toolName.split("__");
+    if (parts.length < 3) {
+        return null;
+    }
+
+    const serverName = parts[1];
+    const parsedToolName = parts.slice(2).join("__");
+
+    if (!serverName || !parsedToolName) {
+        return null;
+    }
+
+    return { serverName, toolName: parsedToolName };
+}
+
+export function unwrapMcpToolName(toolName: string): string {
+    const parsed = parseMcpToolName(toolName);
+    return parsed ? parsed.toolName : toolName;
+}
+
+export function formatMcpToolName(toolName: string): string {
+    const parsed = parseMcpToolName(toolName);
+    if (!parsed) {
+        return toolName;
+    }
+
+    return `${parsed.serverName}'s ${parsed.toolName.replace(/_/g, " ")}`;
+}
+
+export function isDelegateToolName(toolName: string): boolean {
+    const baseName = unwrapMcpToolName(toolName);
+    return DELEGATE_TOOLS.includes(baseName as ToolName);
+}

package/src/agents/tool-normalization.ts

@@ -0,0 +1,184 @@
+import type { MCPManager } from "@/services/mcp/MCPManager";
+import { isValidToolName } from "@/tools/registry";
+import type { ToolName } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { CORE_AGENT_TOOLS, DELEGATE_TOOLS, getDelegateToolsForAgent } from "./constants";
+
+/**
+ * tool-normalization - Pure functions for processing agent tool lists
+ *
+ * ## Responsibility
+ * Centralizes all tool assignment logic that was previously scattered across:
+ * - AgentRegistry
+ * - agent-loader
+ * - Agent creation tools
+ *
+ * ## What it does
+ * Takes a raw tool list + agent context → returns final validated tool list:
+ * 1. Filter out delegate tools (managed separately)
+ * 2. Add appropriate delegate tools
+ * 3. Add core tools (all agents get these)
+ * 4. Validate tool names
+ * 5. Resolve MCP tools (check availability)
+ * 6. Return final deduplicated list
+ *
+ * ## Pure Functions
+ * All functions here are stateless and side-effect free:
+ * - Same input = same output
+ * - No external state
+ * - No mutations
+ * - Easy to test
+ *
+ * ## Usage
+ * Called during AgentInstance creation in agent-loader.ts:
+ * ```typescript
+ * const finalTools = processAgentTools(storedAgent.tools, storedAgent.slug);
+ * ```
+ *
+ * @see agent-loader for usage in instance creation
+ */
+
+/**
+ * Normalize agent tools by applying business rules:
+ * 1. Filter out delegate tools (they're managed separately)
+ * 2. Add appropriate delegate tools
+ * 3. Ensure all core tools are included
+ */
+export function normalizeAgentTools(requestedTools: string[]): string[] {
+    // Filter out delegation tools
+    const toolNames = requestedTools.filter((tool) => {
+        const typedTool = tool as ToolName;
+        return !DELEGATE_TOOLS.includes(typedTool);
+    });
+
+    // Add delegation tools
+    const delegateTools = getDelegateToolsForAgent();
+    toolNames.push(...delegateTools);
+
+    // Ensure core tools are included
+    for (const coreTool of CORE_AGENT_TOOLS) {
+        if (!toolNames.includes(coreTool)) {
+            toolNames.push(coreTool);
+        }
+    }
+
+    return toolNames;
+}
+
+/**
+ * Validate and filter tools, separating valid tools from MCP tool requests.
+ *
+ * ## Warning: Unrecognized tools are logged
+ * Tools that are neither valid static tools nor MCP tools are logged as warnings.
+ */
+export function validateAndSeparateTools(toolNames: string[]): {
+    validTools: string[];
+    mcpToolRequests: string[];
+} {
+    const validTools: string[] = [];
+    const mcpToolRequests: string[] = [];
+    const droppedTools: string[] = [];
+
+    for (const toolName of toolNames) {
+        if (isValidToolName(toolName)) {
+            validTools.push(toolName);
+        } else if (toolName.startsWith("mcp__")) {
+            mcpToolRequests.push(toolName);
+        } else {
+            // Track dropped tools to warn about them
+            droppedTools.push(toolName);
+        }
+    }
+
+    // Warn about dropped tools
+    if (droppedTools.length > 0) {
+        logger.warn(
+            `[tool-normalization] Dropping ${droppedTools.length} unrecognized tool(s): ${droppedTools.join(", ")}`
+        );
+    }
+
+    return { validTools, mcpToolRequests };
+}
+
+/**
+ * Resolve MCP tools - check if requested MCP tools are available
+ * Returns array of available MCP tool names
+ *
+ * If mcpManager is not provided, returns all requested MCP tools without validation.
+ * This allows agent loading to proceed before MCP is initialized - actual tool
+ * availability is checked at execution time in getToolsObject.
+ */
+export function resolveMCPTools(mcpToolRequests: string[], agentSlug: string, mcpManager?: MCPManager): string[] {
+    if (mcpToolRequests.length === 0) {
+        return [];
+    }
+
+    // If no MCPManager available, keep all MCP tool requests - they'll be validated at execution time
+    if (!mcpManager) {
+        return mcpToolRequests;
+    }
+
+    const availableMcpTools: string[] = [];
+
+    try {
+        const allMcpTools = mcpManager.getCachedTools();
+        for (const toolName of mcpToolRequests) {
+            if (allMcpTools[toolName]) {
+                availableMcpTools.push(toolName);
+            }
+        }
+    } catch (error) {
+        logger.debug(`Could not load MCP tools for agent "${agentSlug}":`, error);
+        // Return all requested tools on error - validation will happen at execution time
+        return mcpToolRequests;
+    }
+
+    return availableMcpTools;
+}
+
+/**
+ * Expand filesystem capability groups:
+ * - fs_read implies fs_glob + fs_grep (reading without searching is impractical)
+ * - fs_write implies fs_edit (writing without editing is impractical)
+ *
+ * This is a pure expansion — it never removes tools, only adds implied ones.
+ * Does not mutate the input array.
+ */
+export function expandFsCapabilities(tools: string[]): string[] {
+    const expanded = [...tools];
+
+    if (expanded.includes("fs_read")) {
+        if (!expanded.includes("fs_glob")) expanded.push("fs_glob");
+        if (!expanded.includes("fs_grep")) expanded.push("fs_grep");
+    }
+
+    if (expanded.includes("fs_write")) {
+        if (!expanded.includes("fs_edit")) expanded.push("fs_edit");
+    }
+
+    return expanded;
+}
+
+/**
+ * Complete tool processing pipeline:
+ * 1. Normalize (add core, delegate, filter)
+ * 2. Validate
+ * 3. Resolve MCP tools
+ * Returns final list of valid, available tool names
+ *
+ * @param mcpManager - Optional MCPManager for validating MCP tools. If not provided,
+ *                     MCP tool names are kept without validation (validated at execution time).
+ */
+export function processAgentTools(requestedTools: string[], agentSlug: string, mcpManager?: MCPManager): string[] {
+    // Step 1: Normalize
+    const normalized = normalizeAgentTools(requestedTools);
+
+    // Step 2: Validate and separate
+    const { validTools, mcpToolRequests } = validateAndSeparateTools(normalized);
+
+    // Step 3: Resolve MCP tools
+    const mcpTools = resolveMCPTools(mcpToolRequests, agentSlug, mcpManager);
+
+    // Combine and return
+    return [...validTools, ...mcpTools];
+}

package/src/agents/types/index.ts

@@ -0,0 +1,2 @@
+export * from "./runtime";
+export * from "./storage";

package/src/agents/types/runtime.ts

@@ -0,0 +1,74 @@
+import type { AgentMetadataStore } from "@/services/agents";
+import type { LLMService } from "@/llm/service";
+import type { MCPConfig, MCPServerConfig } from "@/llm/providers/types";
+import type { OnStreamStartCallback } from "@/llm/types";
+import type { NDKEvent, NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
+import type { Tool as CoreTool } from "ai";
+import type { AgentProjectConfig } from "./storage";
+
+/**
+ * Simplified agent representation for UI display and selection.
+ */
+export interface AgentSummary {
+    name: string;
+    role: string;
+    pubkey: string;
+}
+
+/**
+ * Complete agent configuration and identity used during execution.
+ */
+export interface AgentInstance {
+    name: string;
+    pubkey: string;
+    signer: NDKPrivateKeySigner;
+    role: string;
+    description?: string;
+    instructions?: string;
+    customInstructions?: string; // Custom system prompt instructions
+    useCriteria?: string;
+    llmConfig: string;
+    tools: string[];
+    eventId?: string;
+    slug: string;
+    useAISDKAgent?: boolean; // Feature flag: use AI SDK Agent class instead of traditional AgentExecutor
+    maxAgentSteps?: number; // Maximum steps for AI SDK Agent agentic loop (default: 10)
+    /** Agent-specific MCP server configurations */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Project-scoped PM override flags.
+     * Key is project dTag, value is true if this agent is PM for that project.
+     */
+    pmOverrides?: Record<string, boolean>;
+    /**
+     * Global PM designation flag.
+     * When true, this agent is designated as PM for ALL projects where it exists.
+     * Set via kind 24020 TenexAgentConfigUpdate event with ["pm"] tag (without a-tag).
+     * Takes precedence over pmOverrides and project tag designations.
+     */
+    isPM?: boolean;
+    /**
+     * Per-project configuration overrides.
+     * Key is project dTag, value contains project-specific settings including isPM.
+     * Set via kind 24020 TenexAgentConfigUpdate events WITH an a-tag specifying the project.
+     */
+    projectOverrides?: Record<string, AgentProjectConfig>;
+    createMetadataStore(conversationId: string): AgentMetadataStore;
+    createLLMService(options?: {
+        tools?: Record<string, CoreTool>;
+        sessionId?: string;
+        workingDirectory?: string;
+        /** MCP configuration to pass to the provider */
+        mcpConfig?: MCPConfig;
+        /** Conversation ID for OpenRouter correlation */
+        conversationId?: string;
+        /**
+         * Override the config name to use (for meta model resolution).
+         * If provided, uses this config instead of the agent's llmConfig.
+         */
+        resolvedConfigName?: string;
+        /** Callback invoked when Claude Code stream starts, providing the message injector */
+        onStreamStart?: OnStreamStartCallback;
+    }): LLMService;
+    sign(event: NDKEvent): Promise<void>;
+}

package/src/agents/types/storage.ts

@@ -0,0 +1,145 @@
+import type { MCPServerConfig } from "@/llm/providers/types";
+
+/**
+ * Default agent configuration block.
+ * Stored under the `default` key in agent JSON files.
+ * A 24020 event with no a-tag writes to this block.
+ */
+export interface AgentDefaultConfig {
+    /** Default LLM model configuration string (e.g., "anthropic:claude-sonnet-4") */
+    model?: string;
+    /** Default tools list for this agent */
+    tools?: string[];
+}
+
+/**
+ * Per-project configuration override block.
+ * Stored under `projectOverrides[projectDTag]` in agent JSON files.
+ * A 24020 event with an a-tag writes to this block.
+ *
+ * Tools can use delta syntax:
+ * - "+tool" adds a tool on top of defaults
+ * - "-tool" removes a tool from defaults
+ * - Plain "tool" (no prefix) = full replacement list
+ */
+export interface AgentProjectConfig {
+    /** Project-specific model override (when set, overrides default.model) */
+    model?: string;
+    /**
+     * Project-specific tools.
+     * Can be a full replacement list or a delta (using +/- prefix).
+     * If any entry has +/- prefix, treated as delta applied to default tools.
+     * Empty array or undefined means: use defaults.
+     */
+    tools?: string[];
+    /**
+     * Project-scoped PM designation.
+     * When true, this agent is designated as PM for this specific project.
+     * Set via kind 24020 event with ["pm"] tag and an a-tag.
+     */
+    isPM?: boolean;
+}
+
+/**
+ * Project-scoped configuration for an agent (legacy schema).
+ * Used by agents written before the new `default`/`projectOverrides` schema.
+ *
+ * @deprecated Prefer `AgentProjectConfig` with `projectOverrides` field.
+ */
+export interface ProjectScopedConfig {
+    /** Project-scoped LLM configuration string. */
+    llmConfig?: string;
+    /** Project-scoped tools list. */
+    tools?: string[];
+    /** Project-scoped PM designation. */
+    isPM?: boolean;
+}
+
+/**
+ * Agent data stored in JSON files (.tenex/agents/*.json).
+ */
+export interface StoredAgentData {
+    name: string;
+    role: string;
+    description?: string;
+    instructions?: string;
+    useCriteria?: string;
+    /** Agent-specific MCP server configurations */
+    mcpServers?: Record<string, MCPServerConfig>;
+
+    /**
+     * The d-tag of the source agent definition event (kind:4199).
+     * Used by AgentDefinitionMonitor to detect when a newer version
+     * of the same definition is published.
+     * Backward-compatible: agents without this field are silently ignored.
+     */
+    definitionDTag?: string;
+
+    /**
+     * The pubkey of the author of the source agent definition event.
+     * Used by AgentDefinitionMonitor to verify that incoming definition
+     * updates come from the original (or whitelisted) author.
+     */
+    definitionAuthor?: string;
+
+    /**
+     * The `created_at` timestamp of the source agent definition event.
+     * Used by AgentDefinitionMonitor to ensure only strictly newer
+     * definition events trigger upgrades, preventing rollbacks from
+     * older events arriving out of order.
+     */
+    definitionCreatedAt?: number;
+
+    /**
+     * Legacy top-level LLM config field.
+     * @deprecated Use `default.model` instead.
+     */
+    llmConfig?: string;
+
+    /**
+     * Legacy top-level tools field.
+     * @deprecated Use `default.tools` instead.
+     */
+    tools?: string[];
+
+    /**
+     * Default configuration block.
+     * Written by kind 24020 events WITHOUT an a-tag.
+     * Fields here are the global fallback when no project-specific override exists.
+     */
+    default?: AgentDefaultConfig;
+
+    /**
+     * Per-project configuration overrides.
+     * Key is project dTag, value is the project-specific delta override.
+     * Written by kind 24020 events WITH an a-tag.
+     *
+     * Tools stored here use delta syntax ("+tool" / "-tool") or full replacement.
+     * See ConfigResolver for resolution logic.
+     */
+    projectOverrides?: Record<string, AgentProjectConfig>;
+
+    /**
+     * Legacy project-scoped configurations (old schema).
+     * @deprecated Use `projectOverrides` instead.
+     */
+    projectConfigs?: Record<string, ProjectScopedConfig>;
+}
+
+/**
+ * Agent configuration including sensitive data from the registry.
+ */
+export interface AgentConfig extends StoredAgentData {
+    nsec: string;
+    eventId?: string;
+    pubkey?: string;
+}
+
+/**
+ * Agent configuration used during creation flows where nsec may be provided later.
+ */
+export interface AgentConfigOptionalNsec extends StoredAgentData {
+    nsec?: string;
+    eventId?: string;
+    pubkey?: string;
+}

package/src/commands/agent/import/index.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+import { openclawImportCommand } from "./openclaw";
+
+export const importCommand = new Command("import")
+    .description("Import agents from external sources")
+    .addCommand(openclawImportCommand);

package/src/commands/agent/import/openclaw-distiller.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { llmServiceFactory } from "@/llm/LLMServiceFactory";
+import type { LLMConfiguration } from "@/services/config/types";
+import type { OpenClawWorkspaceFiles } from "./openclaw-reader";
+
+const DistilledIdentitySchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    role: z.string(),
+    useCriteria: z.string(),
+    instructions: z.string(),
+});
+export type DistilledAgentIdentity = z.infer<typeof DistilledIdentitySchema>;
+
+export function buildDistillationPrompt(files: OpenClawWorkspaceFiles): string {
+    const sections: string[] = [];
+
+    if (files.soul) {
+        sections.push(`<SOUL.md>\n${files.soul}\n</SOUL.md>`);
+    }
+    if (files.identity) {
+        sections.push(`<IDENTITY.md>\n${files.identity}\n</IDENTITY.md>`);
+    }
+    if (files.agents) {
+        sections.push(`<AGENTS.md>\n${files.agents}\n</AGENTS.md>`);
+    }
+
+    return `You are extracting a portable agent identity from an OpenClaw installation.
+Given these workspace files, return a JSON object with exactly these fields:
+
+- name: the agent's display name (string)
+- description: one-sentence description of who this agent is (string)
+- role: short phrase describing expertise/personality, e.g. "personal AI assistant" (string)
+- useCriteria: when this agent should be selected over others (string)
+- instructions: a clean, platform-agnostic system prompt capturing the agent's
+  personality, behavioral guidelines, and identity. Discard anything specific
+  to OpenClaw: heartbeat polling, HEARTBEAT_OK responses, workspace file reading
+  rituals, emoji reaction guidance, silence tokens, tool-specific commands,
+  and memory file management instructions. (string)
+
+${sections.join("\n\n")}`;
+}
+
+export async function distillAgentIdentity(
+    files: OpenClawWorkspaceFiles,
+    llmConfig: LLMConfiguration
+): Promise<DistilledAgentIdentity> {
+    const service = llmServiceFactory.createService(llmConfig);
+    const prompt = buildDistillationPrompt(files);
+
+    const { object } = await service.generateObject(
+        [{ role: "user", content: prompt }],
+        DistilledIdentitySchema
+    );
+
+    return object;
+}