@tenex-chat/backend 0.9.1

package/src/agents/ConfigResolver.ts

@@ -0,0 +1,229 @@
+/**
+ * ConfigResolver - Utility module for resolving effective agent configuration.
+ *
+ * Handles the merging of default config with project-scoped delta overrides.
+ *
+ * ## Tool Delta Syntax
+ * Project overrides can use delta syntax for tools:
+ * - "+tool" - add this tool on top of defaults
+ * - "-tool" - remove this tool from defaults
+ * - Plain "tool" (no prefix) - full replacement (entire list is the effective tools)
+ *
+ * If any tool uses delta syntax, the whole list is treated as delta.
+ * If no tool uses delta syntax, the whole list is a full replacement.
+ *
+ * ## Dedup Logic
+ * When a project override field is identical to the default, the override is cleared.
+ * This keeps overrides minimal and avoids redundant entries.
+ *
+ * @example
+ * const resolver = new ConfigResolver({
+ *   defaultConfig: { model: 'modelA', tools: ['tool1', 'tool2'] },
+ *   projectConfigs: {
+ *     projectA: { model: 'modelB', tools: ['-tool1', '+tool4'] },
+ *     projectB: { tools: ['+tool5'] }
+ *   }
+ * });
+ *
+ * // projectA: model=modelB, tools=[tool2, tool4]
+ * resolver.resolveEffectiveConfig('projectA');
+ *
+ * // projectB: model=modelA (default), tools=[tool1, tool2, tool5]
+ * resolver.resolveEffectiveConfig('projectB');
+ */
+
+import type { AgentDefaultConfig, AgentProjectConfig } from "@/agents/types";
+export type { AgentDefaultConfig, AgentProjectConfig };
+
+export interface ResolvedAgentConfig {
+    /** The effective model for this project context */
+    model?: string;
+    /** The effective tools list (fully resolved, no +/- prefixes) */
+    tools?: string[];
+}
+
+/**
+ * Apply delta tools to a base tool list.
+ * "+tool" adds, "-tool" removes. Order: apply removals first, then additions.
+ *
+ * @param baseTools - The default tools to apply delta to
+ * @param delta - Array of tools with "+"/"-" prefixes
+ * @returns The resolved tool list
+ */
+export function applyToolsDelta(baseTools: string[], delta: string[]): string[] {
+    const removals = new Set(
+        delta.filter((t) => t.startsWith("-")).map((t) => t.slice(1))
+    );
+    const additions = delta.filter((t) => t.startsWith("+")).map((t) => t.slice(1));
+
+    const result = baseTools.filter((t) => !removals.has(t));
+
+    for (const tool of additions) {
+        if (!result.includes(tool)) {
+            result.push(tool);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Resolve the effective tools for a project given defaults and a project override.
+ *
+ * @param defaultTools - Default tools from agent's default config
+ * @param projectTools - Override from project config (may use delta syntax or be full replacement)
+ * @returns The effective tools list
+ */
+export function resolveEffectiveTools(
+    defaultTools: string[] | undefined,
+    projectTools: string[] | undefined
+): string[] | undefined {
+    if (!projectTools || projectTools.length === 0) {
+        return defaultTools;
+    }
+
+    const base = defaultTools ?? [];
+    return applyToolsDelta(base, projectTools);
+}
+
+/**
+ * Resolve the effective model for a project given defaults and a project override.
+ *
+ * @param defaultModel - Default model from agent's default config
+ * @param projectModel - Override from project config
+ * @returns The effective model
+ */
+export function resolveEffectiveModel(
+    defaultModel: string | undefined,
+    projectModel: string | undefined
+): string | undefined {
+    return projectModel ?? defaultModel;
+}
+
+/**
+ * Resolve the full effective config for an agent in a specific project context.
+ */
+export function resolveEffectiveConfig(
+    defaultConfig: AgentDefaultConfig,
+    projectConfig: AgentProjectConfig | undefined
+): ResolvedAgentConfig {
+    const effectiveModel = resolveEffectiveModel(defaultConfig.model, projectConfig?.model);
+    const effectiveTools = resolveEffectiveTools(defaultConfig.tools, projectConfig?.tools);
+
+    return {
+        model: effectiveModel,
+        tools: effectiveTools,
+    };
+}
+
+/**
+ * Compute the minimal delta representation of a full tool list relative to a set of defaults.
+ *
+ * This is the inverse of applyToolsDelta: given a desired full list and the current defaults,
+ * produce the smallest delta (+tool/-tool) that when applied to defaults yields the desired list.
+ *
+ * Used when storing project-scoped tool overrides: kind 24020 events carry a full list,
+ * but the storage layer stores deltas for project overrides.
+ *
+ * ## Algorithm
+ * - Tools in desired but NOT in defaults → "+tool" additions
+ * - Tools in defaults but NOT in desired → "-tool" removals
+ * - Tools in both → no entry needed (they're already in defaults)
+ *
+ * @param defaultTools - The agent's default tools list
+ * @param desiredTools - The full tool list to achieve
+ * @returns Delta array (may contain "+tool" and "-tool" entries), or empty array if no change
+ */
+export function computeToolsDelta(defaultTools: string[], desiredTools: string[]): string[] {
+    const defaultSet = new Set(defaultTools);
+    const desiredSet = new Set(desiredTools);
+
+    const delta: string[] = [];
+
+    // Tools to remove: in defaults but not in desired
+    for (const tool of defaultTools) {
+        if (!desiredSet.has(tool)) {
+            delta.push(`-${tool}`);
+        }
+    }
+
+    // Tools to add: in desired but not in defaults
+    for (const tool of desiredTools) {
+        if (!defaultSet.has(tool)) {
+            delta.push(`+${tool}`);
+        }
+    }
+
+    return delta;
+}
+
+/**
+ * Deduplicate a project config against the default config.
+ *
+ * If a project override value is identical to the effective default, remove it
+ * from the override (it's redundant). This keeps overrides minimal.
+ *
+ * For tools: we compare the fully-resolved tool list. If the resolved tools
+ * equal the default tools, clear the project override.
+ *
+ * Also handles no-op delta dedup: if a stored delta becomes a no-op against
+ * the current defaults (e.g., "+tool" where tool is already in defaults),
+ * it is cleaned up since the user is explicitly confirming the tool should be available.
+ *
+ * @param defaultConfig - Agent's default config
+ * @param projectConfig - Project override config to deduplicate
+ * @returns Cleaned project config (may be empty object if all fields were identical to default)
+ */
+export function deduplicateProjectConfig(
+    defaultConfig: AgentDefaultConfig,
+    projectConfig: AgentProjectConfig
+): AgentProjectConfig {
+    const cleaned: AgentProjectConfig = { ...projectConfig };
+
+    // Dedup model: if project model == default model, clear it
+    if (cleaned.model !== undefined && cleaned.model === defaultConfig.model) {
+        delete cleaned.model;
+    }
+
+    // Dedup tools: resolve, normalize delta, and compare
+    if (cleaned.tools !== undefined) {
+        const defaultToolsResolved = defaultConfig.tools ?? [];
+        const resolvedProjectTools = resolveEffectiveTools(defaultConfig.tools, cleaned.tools);
+
+        // Compare resolved tools to default tools (order-insensitive)
+        if (arraysEqualUnordered(resolvedProjectTools ?? [], defaultToolsResolved)) {
+            delete cleaned.tools;
+        } else {
+            // Normalize: recompute the minimal delta from the fully-resolved tool list.
+            cleaned.tools = computeToolsDelta(defaultToolsResolved, resolvedProjectTools ?? []);
+        }
+    }
+
+    return cleaned;
+}
+
+/**
+ * Check if two arrays contain the same elements in the same order.
+ */
+export function arraysEqual<T>(a: T[], b: T[]): boolean {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) return false;
+    }
+    return true;
+}
+
+/**
+ * Check if two arrays contain the same elements (order-independent).
+ * Used for tool list comparison where order doesn't matter for dedup.
+ */
+export function arraysEqualUnordered<T>(a: T[], b: T[]): boolean {
+    if (a.length !== b.length) return false;
+    const setA = new Set(a);
+    const setB = new Set(b);
+    if (setA.size !== setB.size) return false;
+    for (const item of setA) {
+        if (!setB.has(item)) return false;
+    }
+    return true;
+}

package/src/agents/agent-installer.ts

@@ -0,0 +1,236 @@
+import { agentStorage, createStoredAgent, type StoredAgent } from "@/agents/AgentStorage";
+import { AgentNotFoundError, AgentValidationError } from "@/agents/errors";
+import { installAgentScripts } from "@/agents/script-installer";
+import { DEFAULT_AGENT_LLM_CONFIG } from "@/llm/constants";
+import { getNDK } from "@/nostr";
+import { logger } from "@/utils/logger";
+import { toKebabCase } from "@/lib/string";
+import type NDK from "@nostr-dev-kit/ndk";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
+import { NDKAgentDefinition } from "@/events/NDKAgentDefinition";
+
+/**
+ * agent-installer - Pure Nostr operations for fetching agent definitions
+ *
+ * ## Responsibility
+ * Fetches agent definition events from Nostr relays and saves them to storage.
+ * - Fetches events by event ID
+ * - Validates event structure
+ * - Parses event into StoredAgent format
+ * - Generates private keys for agents
+ * - Installs bundled files from kind 1063 (NIP-94) events via e-tags
+ * - Saves to AgentStorage
+ *
+ * ## Architecture
+ * - **agent-installer** (this): Pure Nostr operations only
+ * - **script-installer**: Handles downloading and installing bundled scripts
+ * - **AgentStorage**: Handles persistence (uses this)
+ * - **agent-loader**: Orchestrates the full loading flow (uses this)
+ *
+ * ## Separation of Concerns
+ * This module is ONLY about Nostr:
+ * - No registry logic
+ * - No project logic
+ * - No in-memory state
+ * - Just: fetch → validate → parse → install scripts → save
+ *
+ * ## Usage
+ * Typically called by agent-loader when an agent is not found in storage.
+ * Can also be used standalone to pre-install agents.
+ *
+ * @example
+ * // Install agent from Nostr
+ * const stored = await installAgentFromNostr('nostr:event123', 'my-agent');
+ * console.log('Installed:', stored.name);
+ *
+ * @see agent-loader for the complete loading orchestration
+ * @see AgentStorage for persistence operations
+ * @see script-installer for bundled script installation
+ */
+
+/**
+ * Validate that an NDK event is a valid agent definition event
+ */
+function validateAgentEvent(agentDef: NDKAgentDefinition): void {
+    // Check if event has required fields
+    if (!agentDef.id) {
+        throw new AgentValidationError("Agent event missing ID");
+    }
+
+    // Check if event has a title tag (agents should have titles)
+    if (!agentDef.title || agentDef.title.trim() === "") {
+        throw new AgentValidationError("Agent event missing title tag");
+    }
+
+    // Check if event has instructions
+    if (!agentDef.instructions || agentDef.instructions.trim() === "") {
+        logger.warn(`Agent event ${agentDef.id} has no instructions`);
+    }
+}
+
+/**
+ * Parse an NDK agent definition event into StoredAgent data structure
+ */
+interface ParsedAgentEvent {
+    eventId: string;
+    slug: string;
+    name: string;
+    role: string;
+    description: string;
+    instructions: string;
+    useCriteria: string;
+    defaultConfig: { model: string; tools?: string[] };
+    definitionDTag?: string;
+    definitionAuthor?: string;
+    definitionCreatedAt?: number;
+}
+
+function parseAgentEvent(event: NDKEvent, slug: string): ParsedAgentEvent {
+    // Wrap in NDKAgentDefinition to use proper accessors
+    const agentDef = NDKAgentDefinition.from(event);
+
+    // Validate before parsing
+    validateAgentEvent(agentDef);
+
+    const title = agentDef.title || "Unnamed Agent";
+    const description = agentDef.description || "";
+    const role = agentDef.role || "assistant";
+    const instructions = agentDef.instructions || "";
+    const useCriteria = agentDef.useCriteria || "";
+
+    // Extract definition tracking metadata for auto-upgrade monitoring
+    const definitionDTag = event.tagValue("d") || undefined;
+    const definitionAuthor = event.pubkey || undefined;
+
+    // Extract tool requirements from the agent definition event
+    const toolTags = event.tags
+        .filter((tag) => tag[0] === "tool" && tag[1])
+        .map((tag) => tag[1]);
+
+    if (toolTags.length > 0) {
+        logger.info(`Agent "${title}" requests access to ${toolTags.length} tool(s):`, toolTags);
+    }
+
+    return {
+        eventId: event.id,
+        slug,
+        name: title,
+        role,
+        description,
+        instructions,
+        useCriteria,
+        defaultConfig: {
+            model: DEFAULT_AGENT_LLM_CONFIG,
+            tools: toolTags.length > 0 ? toolTags : undefined,
+        },
+        definitionDTag,
+        definitionAuthor,
+        definitionCreatedAt: event.created_at,
+    };
+}
+
+/**
+ * Install an agent from an already-fetched NDKEvent.
+ *
+ * Core installation logic: validate → parse → generate keys → install scripts → save → return
+ *
+ * @param event - The NDKEvent containing the agent definition
+ * @param customSlug - Optional custom slug (defaults to kebab-case of agent name)
+ * @param ndk - Optional NDK instance (uses default if not provided, needed for script downloads)
+ * @returns The saved StoredAgent (with generated private key)
+ * @throws AgentValidationError if event structure is invalid
+ */
+export async function installAgentFromNostrEvent(
+    event: NDKEvent,
+    customSlug?: string,
+    ndk?: NDK
+): Promise<StoredAgent> {
+    const ndkInstance = ndk || getNDK();
+
+    // Check if an agent with this eventId already exists
+    // This preserves user configuration (llmConfig, pmOverrides, etc.)
+    if (event.id) {
+        const existingAgent = await agentStorage.getAgentByEventId(event.id);
+        if (existingAgent) {
+            logger.debug(
+                `Agent with eventId ${event.id} already exists as "${existingAgent.slug}", ` +
+                `preserving existing configuration`
+            );
+            return existingAgent;
+        }
+    }
+
+    const agentDef = NDKAgentDefinition.from(event);
+
+    // Generate slug: prefer customSlug > event's d-tag > derived from title
+    const slug = customSlug || agentDef.slug || toKebabCase(agentDef.title || "unnamed-agent");
+
+    // Parse and validate the event into agent data
+    const agentData = parseAgentEvent(event, slug);
+
+    // Generate a new private key for this agent
+    const signer = NDKPrivateKeySigner.generate();
+
+    // Install bundled files from kind 1063 events (referenced via e-tags)
+    const fileETags = agentDef.getETags();
+    if (fileETags.length > 0) {
+        logger.info(`Agent "${agentData.name}" has ${fileETags.length} bundled file(s)`);
+        const fileResults = await installAgentScripts(fileETags, signer.pubkey, ndkInstance);
+
+        const failures = fileResults.filter((r) => !r.success);
+        if (failures.length > 0) {
+            logger.warn(`${failures.length} file(s) failed to install for agent "${agentData.name}"`, {
+                failures: failures.map((f) => ({ path: f.relativePath, error: f.error })),
+            });
+        }
+    }
+
+    const storedAgent = createStoredAgent({
+        nsec: signer.nsec,
+        slug: agentData.slug,
+        name: agentData.name,
+        role: agentData.role,
+        description: agentData.description,
+        instructions: agentData.instructions,
+        useCriteria: agentData.useCriteria,
+        defaultConfig: agentData.defaultConfig,
+        eventId: agentData.eventId,
+        definitionDTag: agentData.definitionDTag,
+        definitionAuthor: agentData.definitionAuthor,
+        definitionCreatedAt: agentData.definitionCreatedAt,
+    });
+
+    await agentStorage.saveAgent(storedAgent);
+    logger.info(`Installed agent "${agentData.name}" (${slug}) from Nostr event ${event.id}`);
+
+    return storedAgent;
+}
+
+/**
+ * Fetch an agent definition event from Nostr by ID and install it.
+ *
+ * @param eventId - The Nostr event ID (with or without "nostr:" prefix)
+ * @param customSlug - Optional custom slug (defaults to kebab-case of agent name)
+ * @param ndk - Optional NDK instance (uses default if not provided)
+ * @returns The saved StoredAgent (with generated private key)
+ * @throws AgentNotFoundError if event not found on relays
+ * @throws AgentValidationError if event structure is invalid
+ */
+export async function installAgentFromNostr(
+    eventId: string,
+    customSlug?: string,
+    ndk?: NDK
+): Promise<StoredAgent> {
+    const ndkInstance = ndk || getNDK();
+    const cleanEventId = eventId.startsWith("nostr:") ? eventId.substring(6) : eventId;
+
+    logger.debug(`Fetching agent event ${cleanEventId} from Nostr relays`);
+    const agentEvent = await ndkInstance.fetchEvent(cleanEventId, { groupable: false });
+
+    if (!agentEvent) {
+        throw new AgentNotFoundError(cleanEventId);
+    }
+
+    return installAgentFromNostrEvent(agentEvent, customSlug, ndkInstance);
+}