@tenex-chat/backend 0.9.1

package/src/tools/implementations/conversation_search.ts

@@ -0,0 +1,370 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { conversationRegistry } from "@/conversations/ConversationRegistry";
+import { ConversationStore } from "@/conversations/ConversationStore";
+import type { MessageMatch } from "@/conversations/search";
+import type { AISdkTool } from "@/tools/types";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import { z } from "zod";
+import {
+    getConversationEmbeddingService,
+    type SemanticSearchResult,
+} from "@/conversations/search/embeddings";
+
+/**
+ * Search mode for conversation search
+ * - "keyword": Traditional title-based substring matching (fast, exact)
+ * - "semantic": Natural language semantic search using embeddings (slower, understands meaning)
+ * - "hybrid": Combines both approaches, semantic results first, then keyword fallback
+ * - "full-text": Full-text search across all message content (advanced)
+ */
+const SearchMode = z.enum(["keyword", "semantic", "hybrid", "full-text"]).describe(
+    "Search mode: 'keyword' (fast title matching), 'semantic' (natural language), 'hybrid' (both), or 'full-text' (all messages)"
+);
+
+const conversationSearchSchema = z.object({
+    query: z.string().describe(
+        "Search query. For keyword mode: matches against conversation titles. " +
+        "For semantic mode: natural language query like 'conversations about debugging memory issues'. " +
+        "For full-text mode: matches against all message content and titles."
+    ),
+    mode: SearchMode.optional().describe(
+        "Search mode: 'keyword' (default, fast), 'semantic' (natural language), 'hybrid' (both), or 'full-text' (comprehensive)"
+    ),
+    filters: z
+        .object({
+            agents: z
+                .array(z.string())
+                .optional()
+                .describe("Filter by agent slugs or pubkeys - conversation must include at least one (exact match)"),
+            since: z
+                .union([z.string(), z.number()])
+                .optional()
+                .describe("Return conversations with activity since this date (Unix timestamp or ISO 8601)"),
+            after: z
+                .union([z.string(), z.number()])
+                .optional()
+                .describe("Alias for 'since' - return conversations with activity after this date"),
+        })
+        .optional()
+        .describe("Optional filters to narrow search results"),
+    limit: z
+        .number()
+        .optional()
+        .default(20)
+        .describe("Maximum number of results to return. Defaults to 20."),
+    minScore: z
+        .number()
+        .optional()
+        .describe("Minimum relevance score for semantic results (0-1). Defaults to 0.3."),
+    projectId: z
+        .string()
+        .optional()
+        .describe("Filter by project ID. Use 'ALL' for all projects."),
+});
+
+type ConversationSearchInput = z.infer<typeof conversationSearchSchema>;
+
+interface ConversationSearchResult {
+    id: string;
+    projectId?: string;
+    title?: string;
+    summary?: string;
+    messageCount: number;
+    createdAt?: number;
+    lastActivity?: number;
+    matches?: MessageMatch[];
+    relevanceScore?: number; // Only present for semantic/hybrid results
+}
+
+interface ConversationSearchOutput {
+    success: boolean;
+    conversations: ConversationSearchResult[];
+    total: number;
+    query: string;
+    mode: string;
+    searchType?: "full-text" | "title-only" | "semantic" | "hybrid";
+    semanticAvailable: boolean;
+    error?: string;
+    warning?: string;
+}
+
+/**
+ * Fallback to legacy title-only search using in-memory stores.
+ */
+function legacyTitleSearch(query: string, limit: number): ConversationSearchResult[] {
+    const stores = ConversationStore.search(query);
+    return stores.slice(0, limit).map((store) => {
+        const messages = store.getAllMessages();
+        const firstMessage = messages[0];
+        const lastMessage = messages[messages.length - 1];
+
+        return {
+            id: store.id,
+            title: store.title,
+            messageCount: messages.length,
+            createdAt: firstMessage?.timestamp,
+            lastActivity: lastMessage?.timestamp,
+        };
+    });
+}
+
+/**
+ * Perform keyword-based search on conversation titles
+ */
+function keywordSearch(query: string, limit: number): ConversationSearchResult[] {
+    return legacyTitleSearch(query, limit);
+}
+
+/**
+ * Perform semantic search using embeddings
+ */
+async function semanticSearch(
+    query: string,
+    limit: number,
+    minScore: number,
+    projectId?: string
+): Promise<ConversationSearchResult[]> {
+    const conversationEmbeddingService = getConversationEmbeddingService();
+    try {
+        const results = await conversationEmbeddingService.semanticSearch(query, {
+            limit,
+            minScore,
+            projectId,
+        });
+        return results.map((result: SemanticSearchResult) => ({
+            id: result.conversationId,
+            projectId: result.projectId,
+            title: result.title,
+            summary: result.summary,
+            messageCount: result.messageCount,
+            createdAt: result.createdAt,
+            lastActivity: result.lastActivity,
+            relevanceScore: result.relevanceScore,
+        }));
+    } catch (error) {
+        logger.error("Semantic search failed, falling back to empty results", { error });
+        return [];
+    }
+}
+
+/**
+ * Perform hybrid search: semantic first, then keyword fallback
+ * Deduplicates results by conversation ID
+ */
+async function hybridSearch(
+    query: string,
+    limit: number,
+    minScore: number,
+    projectId?: string
+): Promise<ConversationSearchResult[]> {
+    const seen = new Set<string>();
+    const combined: ConversationSearchResult[] = [];
+
+    // First: semantic results (higher quality matches)
+    const semanticResults = await semanticSearch(query, limit, minScore, projectId);
+    for (const result of semanticResults) {
+        if (!seen.has(result.id)) {
+            seen.add(result.id);
+            combined.push(result);
+        }
+    }
+
+    // Second: keyword results to fill up remaining slots
+    if (combined.length < limit) {
+        const keywordResults = keywordSearch(query, limit);
+        for (const result of keywordResults) {
+            if (!seen.has(result.id) && combined.length < limit) {
+                seen.add(result.id);
+                combined.push(result);
+            }
+        }
+    }
+
+    return combined.slice(0, limit);
+}
+
+/**
+ * Perform full-text search across all messages
+ */
+async function fullTextSearch(
+    query: string,
+    filters: ConversationSearchInput["filters"],
+    limit: number
+): Promise<{ results: ConversationSearchResult[]; searchType: "full-text" | "title-only"; error?: string }> {
+    const advancedResult = conversationRegistry.searchAdvanced({ query, filters }, limit);
+
+    if (advancedResult.success) {
+        if (advancedResult.results.length > 0) {
+            return {
+                searchType: "full-text",
+                results: advancedResult.results.map((result) => ({
+                    id: result.conversationId,
+                    title: result.title,
+                    messageCount: result.messageCount,
+                    createdAt: result.createdAt,
+                    lastActivity: result.lastActivity,
+                    matches: result.matches,
+                })),
+            };
+        }
+
+        // Advanced search succeeded but no results - try legacy search too
+        const legacyResults = legacyTitleSearch(query, limit);
+        if (legacyResults.length > 0) {
+            return {
+                searchType: "title-only",
+                results: legacyResults,
+            };
+        }
+
+        // No results from either search
+        return {
+            searchType: "full-text",
+            results: [],
+        };
+    }
+
+    // Advanced search failed - try fallback
+    logger.warn("⚠️ Advanced search failed, falling back to title search", {
+        error: advancedResult.error,
+        query,
+    });
+
+    const legacyResults = legacyTitleSearch(query, limit);
+
+    return {
+        searchType: "title-only",
+        results: legacyResults,
+        error: advancedResult.error,
+    };
+}
+
+/**
+ * Check if semantic search is available
+ */
+async function isSemanticSearchAvailable(): Promise<boolean> {
+    try {
+        const conversationEmbeddingService = getConversationEmbeddingService();
+        return await conversationEmbeddingService.hasIndexedConversations();
+    } catch {
+        return false;
+    }
+}
+
+async function executeConversationSearch(
+    input: ConversationSearchInput,
+    context: ToolExecutionContext
+): Promise<ConversationSearchOutput> {
+    const { query, mode = "keyword", filters, limit = 20, minScore = 0.3, projectId } = input;
+
+    logger.info("🔍 Searching conversations", {
+        query,
+        mode,
+        filters,
+        limit,
+        minScore,
+        projectId,
+        agent: context.agent.name,
+    });
+
+    // Check semantic availability
+    const semanticAvailable = await isSemanticSearchAvailable();
+
+    // Determine effective mode
+    let effectiveMode = mode;
+    if ((mode === "semantic" || mode === "hybrid") && !semanticAvailable) {
+        logger.info("Semantic search not available, falling back to keyword search");
+        effectiveMode = "keyword";
+    }
+
+    let conversations: ConversationSearchResult[];
+    let searchType: "full-text" | "title-only" | "semantic" | "hybrid";
+    let warning: string | undefined;
+
+    switch (effectiveMode) {
+        case "semantic":
+            conversations = await semanticSearch(query, limit, minScore, projectId);
+            searchType = "semantic";
+            break;
+
+        case "hybrid":
+            conversations = await hybridSearch(query, limit, minScore, projectId);
+            searchType = "hybrid";
+            break;
+
+        case "full-text": {
+            const fullTextResult = await fullTextSearch(query, filters, limit);
+            conversations = fullTextResult.results;
+            searchType = fullTextResult.searchType;
+            if (fullTextResult.error) {
+                warning = `Full-text search failed: ${fullTextResult.error}. Showing ${fullTextResult.searchType} results.`;
+            } else if (fullTextResult.searchType === "title-only" && fullTextResult.results.length > 0) {
+                warning = "Full-text search found no results; showing title-only matches";
+            }
+            break;
+        }
+
+        case "keyword":
+        default:
+            conversations = keywordSearch(query, limit);
+            searchType = "full-text";
+            break;
+    }
+
+    logger.info("✅ Conversation search complete", {
+        query,
+        mode: effectiveMode,
+        found: conversations.length,
+        semanticAvailable,
+        agent: context.agent.name,
+    });
+
+    return {
+        success: true,
+        conversations,
+        total: conversations.length,
+        query,
+        mode: effectiveMode,
+        searchType,
+        semanticAvailable,
+        warning,
+    };
+}
+
+export function createConversationSearchTool(context: ToolExecutionContext): AISdkTool {
+    const aiTool = tool({
+        description:
+            "Search conversations with multiple search modes. Returns matching conversations with summary information including ID, title, message count, and timestamps. " +
+            "Supports four search modes: 'keyword' (fast title matching), 'semantic' (natural language understanding), 'hybrid' (both), and 'full-text' (comprehensive message search). " +
+            "Use semantic or hybrid mode for natural language queries that understand meaning.",
+
+        inputSchema: conversationSearchSchema,
+
+        execute: async (input: ConversationSearchInput) => {
+            return await executeConversationSearch(input, context);
+        },
+    });
+
+    Object.defineProperty(aiTool, "getHumanReadableContent", {
+        value: ({ query, mode, filters, limit }: ConversationSearchInput) => {
+            const parts = [`Searching conversations for "${query}"`];
+            const modeStr = mode || "keyword";
+            parts.push(`mode=${modeStr}`);
+            if (filters?.agents?.length) {
+                parts.push(`agents: ${filters.agents.join(", ")}`);
+            }
+            if (filters?.since || filters?.after) {
+                parts.push(`since: ${filters.since || filters.after}`);
+            }
+            if (limit && limit !== 20) {
+                parts.push(`limit: ${limit}`);
+            }
+            return parts.join(", ");
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return aiTool as AISdkTool;
+}

package/src/tools/implementations/delegate.ts

@@ -0,0 +1,327 @@
+/**
+ * Delegation Tool Implementation
+ *
+ * Enables agents to delegate tasks to other agents in the system.
+ *
+ * ## Circular Delegation Handling
+ *
+ * The tool detects when a delegation would create a circular chain (A→B→C→A).
+ * By default, circular delegations return a soft warning with `success: false`.
+ * Set `force: true` on an individual delegation to bypass this check.
+ *
+ * @module delegate
+ */
+import type { ToolExecutionContext } from "@/tools/types";
+import { getProjectContext } from "@/services/projects";
+import { RALRegistry } from "@/services/ral/RALRegistry";
+import type { PendingDelegation } from "@/services/ral/types";
+import type { AISdkTool } from "@/tools/types";
+import { resolveAgentSlug } from "@/services/agents";
+import { logger } from "@/utils/logger";
+import { createEventContext } from "@/services/event-context";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { wouldCreateCircularDelegation } from "@/utils/delegation-chain";
+import { ConversationStore } from "@/conversations/ConversationStore";
+import type { DelegationMarker } from "@/conversations/types";
+import { AgentEventDecoder } from "@/nostr/AgentEventDecoder";
+import { tool } from "ai";
+import { z } from "zod";
+
+const delegationItemSchema = z.object({
+  recipient: z
+    .string()
+    .describe(
+      "Agent slug (e.g., 'architect', 'claude-code', 'explore-agent'). Only agent slugs are accepted."
+    ),
+  prompt: z.string().describe("The request or task for this agent"),
+  branch: z
+    .string()
+    .optional()
+    .describe("Git branch name for worktree isolation"),
+  force: z
+    .boolean()
+    .optional()
+    .describe("Set to true to proceed even if circular delegation is detected"),
+  nudges: z
+    .array(z.string())
+    .optional()
+    .describe("Nudge event IDs to apply to this delegated agent. Nudges can modify tool availability and inject additional context."),
+});
+
+type DelegationItem = z.infer<typeof delegationItemSchema>;
+
+interface DelegateInput {
+  delegations: DelegationItem[];
+}
+
+interface CircularDelegationWarning {
+  recipient: string;
+  chain: string;
+  message: string;
+  forced?: boolean;
+}
+
+interface DelegateOutput {
+  success: boolean;
+  message: string;
+  /** Truncated delegation conversation IDs (prefixes for compact display) */
+  delegationConversationIds: string[];
+  circularDelegationWarning?: CircularDelegationWarning;
+  circularDelegationWarnings?: CircularDelegationWarning[];
+}
+
+/**
+ * Check if the agent has created a todo list.
+ * Returns { hasTodos: boolean, hasConversation: boolean } to distinguish
+ * between "no todos" and "no conversation context" cases.
+ */
+function checkTodoState(context: ToolExecutionContext): { hasTodos: boolean; hasConversation: boolean } {
+  const conversation = context.getConversation();
+  if (!conversation) {
+    // No conversation context available - skip enforcement
+    return { hasTodos: true, hasConversation: false };
+  }
+  const todos = conversation.getTodos(context.agent.pubkey);
+  return { hasTodos: todos.length > 0, hasConversation: true };
+}
+
+async function executeDelegate(
+  input: DelegateInput,
+  context: ToolExecutionContext
+): Promise<DelegateOutput> {
+  const { delegations } = input;
+
+  // ENFORCEMENT: Delegation requires a todo list
+  // Skip enforcement if no conversation context (e.g., MCP-only mode)
+  const todoState = checkTodoState(context);
+  if (todoState.hasConversation && !todoState.hasTodos) {
+    throw new Error(
+      "Delegation requires a todo list. Please use `todo_write()` to create a todo list before delegating tasks. " +
+      "This helps track work progress and ensures delegated tasks are properly documented."
+    );
+  }
+
+  if (!Array.isArray(delegations) || delegations.length === 0) {
+    throw new Error("At least one delegation is required");
+  }
+
+  const ralRegistry = RALRegistry.getInstance();
+  const pendingDelegations: PendingDelegation[] = [];
+  const circularWarnings: CircularDelegationWarning[] = [];
+
+  // Get the delegation chain from the current conversation for cycle detection
+  const conversationStore = ConversationStore.get(context.conversationId);
+  const delegationChain = conversationStore?.metadata?.delegationChain;
+
+  // Extract inherited nudges from the triggering event
+  // Nudge inheritance: any nudges on the current triggering event are automatically
+  // passed forward to delegated agents unless explicitly overridden
+  const inheritedNudges = AgentEventDecoder.extractNudgeEventIds(context.triggeringEvent);
+
+  for (const delegation of delegations) {
+    // Resolve slug to pubkey - throws if invalid
+    const resolution = resolveAgentSlug(delegation.recipient);
+    if (!resolution.pubkey) {
+      const availableSlugsStr = resolution.availableSlugs.length > 0
+        ? `Available agent slugs: ${resolution.availableSlugs.join(", ")}`
+        : "No agents available in the current project context.";
+      throw new Error(
+        `Invalid agent slug: "${delegation.recipient}". Only agent slugs are accepted. ${availableSlugsStr}`
+      );
+    }
+    const pubkey = resolution.pubkey;
+
+    // Check for circular delegation
+    if (delegationChain && wouldCreateCircularDelegation(delegationChain, pubkey)) {
+      const projectContext = getProjectContext();
+      const targetAgent = projectContext.getAgentByPubkey(pubkey);
+      const targetName = targetAgent?.slug || pubkey.substring(0, 8);
+      const chainDisplay = delegationChain.map(e => e.displayName).join(" → ");
+
+      const warning: CircularDelegationWarning = {
+        recipient: targetName,
+        chain: chainDisplay,
+        message: `"${targetName}" is already in the delegation chain (${chainDisplay}). Delegating would create a cycle.`,
+      };
+
+      if (!delegation.force) {
+        logger.info("[delegate] Circular delegation detected, skipping (no force flag)", {
+          recipient: delegation.recipient,
+          targetPubkey: pubkey.substring(0, 8),
+          chain: chainDisplay,
+        });
+        circularWarnings.push(warning);
+        continue;
+      }
+
+      // Force flag set - proceed with warning
+      logger.warn("[delegate] Circular delegation proceeding with force flag", {
+        recipient: delegation.recipient,
+        targetPubkey: pubkey.substring(0, 8),
+        chain: chainDisplay,
+      });
+      circularWarnings.push({ ...warning, forced: true });
+    }
+
+    // Publish delegation event
+    const eventContext = createEventContext(context);
+
+    // Combine inherited nudges with explicitly specified nudges
+    // Nudge inheritance: inherited nudges are always passed forward
+    // Explicit nudges are added to the inherited set (not replaced)
+    const combinedNudges = [
+      ...inheritedNudges,
+      ...(delegation.nudges || []),
+    ];
+    // Deduplicate nudges
+    const uniqueNudges = [...new Set(combinedNudges)];
+
+    const eventId = await context.agentPublisher.delegate({
+      recipient: pubkey,
+      content: delegation.prompt,
+      branch: delegation.branch,
+      nudges: uniqueNudges.length > 0 ? uniqueNudges : undefined,
+    }, eventContext);
+
+    const pendingDelegation: PendingDelegation = {
+      delegationConversationId: eventId,
+      recipientPubkey: pubkey,
+      senderPubkey: context.agent.pubkey,
+      prompt: delegation.prompt,
+      ralNumber: context.ralNumber,
+    };
+    pendingDelegations.push(pendingDelegation);
+
+    // Register immediately after publishing to prevent orphans
+    ralRegistry.mergePendingDelegations(
+      context.agent.pubkey,
+      context.conversationId,
+      context.ralNumber,
+      [pendingDelegation]
+    );
+
+    // Create pending marker immediately to show delegation in real-time
+    const parentStore = ConversationStore.get(context.conversationId);
+    if (parentStore) {
+      const initiatedAt = Math.floor(Date.now() / 1000);
+      const marker: DelegationMarker = {
+        delegationConversationId: eventId,
+        recipientPubkey: pubkey,
+        parentConversationId: context.conversationId,
+        initiatedAt,
+        status: "pending",
+      };
+
+      // Store marker locally
+      parentStore.addDelegationMarker(
+        marker,
+        context.agent.pubkey,
+        context.ralNumber
+      );
+      await parentStore.save();
+
+      // Publish marker to Nostr for verification by other agents
+      await context.agentPublisher.delegationMarker({
+        delegationConversationId: eventId,
+        recipientPubkey: pubkey,
+        parentConversationId: context.conversationId,
+        status: "pending",
+        initiatedAt,
+      });
+    }
+  }
+
+  const delegationConversationIds = pendingDelegations.map(d => shortenConversationId(d.delegationConversationId));
+  const unforcedWarnings = circularWarnings.filter(w => !w.forced);
+
+  // All delegations were circular (not forced) - return soft warning
+  if (pendingDelegations.length === 0 && unforcedWarnings.length > 0) {
+    const warningMessages = unforcedWarnings.map(w =>
+      `"${w.recipient}" is already in chain (${w.chain})`
+    ).join("; ");
+
+    return {
+      success: false,
+      message: `Circular delegation detected: ${warningMessages}. Add \`force: true\` to proceed anyway.`,
+      delegationConversationIds: [],
+      circularDelegationWarning: unforcedWarnings[0],
+      circularDelegationWarnings: unforcedWarnings,
+    };
+  }
+
+  if (pendingDelegations.length === 0) {
+    throw new Error("No delegations were published.");
+  }
+
+  logger.info("[delegate] Published delegations, agent continues without blocking", {
+    count: pendingDelegations.length,
+    delegationConversationIds,
+    circularWarningsCount: circularWarnings.length,
+    inheritedNudgesCount: inheritedNudges.length,
+  });
+
+  let message = `Delegated ${pendingDelegations.length} task(s). The agent(s) will wake you up when ready with the response(s).`;
+  if (unforcedWarnings.length > 0) {
+    const skipped = unforcedWarnings.map(w => w.recipient).join(", ");
+    message += ` Note: Skipped circular delegation(s) to: ${skipped}.`;
+  }
+
+  return {
+    success: true,
+    message,
+    delegationConversationIds,
+    ...(circularWarnings.length > 0 && {
+      circularDelegationWarning: circularWarnings[0],
+      circularDelegationWarnings: circularWarnings,
+    }),
+  };
+}
+
+export function createDelegateTool(context: ToolExecutionContext): AISdkTool {
+  const delegateSchema = z.object({
+    delegations: z
+      .array(delegationItemSchema)
+      .min(1)
+      .describe("Array of delegations to execute"),
+  });
+
+  const description = `Delegate tasks to one or more agents. Each delegation can have its own prompt and branch. IMPORTANT: Delegated agents ONLY see your prompt - they cannot see any prior conversation. Include ALL necessary context, requirements, and constraints in your prompt.
+
+Circular delegation detection: The tool detects when a delegation would create a circular chain (A→B→C→A). By default, circular delegations are skipped with a soft warning. Set \`force: true\` on an individual delegation to bypass this check.
+
+Nudge support: Pass nudge event IDs in the \`nudges\` array to apply behavioral nudges to delegated agents. Nudges can modify tool availability (only-tool, allow-tool, deny-tool) and inject additional context. Nudge inheritance: any nudges active on the current agent are automatically forwarded to all delegated agents.`;
+
+  const aiTool = tool({
+    description,
+    inputSchema: delegateSchema,
+    execute: async (input: unknown) => {
+      return await executeDelegate(input as DelegateInput, context);
+    },
+  });
+
+  Object.defineProperty(aiTool, "getHumanReadableContent", {
+    value: (args: unknown) => {
+      if (!args || typeof args !== "object" || !("delegations" in args)) {
+        return "Delegating to agent(s)";
+      }
+
+      const { delegations } = args as DelegateInput;
+
+      if (!delegations || !Array.isArray(delegations)) {
+        return "Delegating to agent(s)";
+      }
+
+      if (delegations.length === 1) {
+        const d = delegations[0];
+        return `Delegating to ${d.recipient}`;
+      }
+
+      const recipients = delegations.map((d) => d.recipient).join(", ");
+      return `Delegating ${delegations.length} tasks to: ${recipients}`;
+    },
+    enumerable: false,
+    configurable: true,
+  });
+
+  return aiTool as AISdkTool;
+}