@tenex-chat/backend 0.9.1

package/src/tools/implementations/delegate_crossproject.ts

@@ -0,0 +1,209 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { agentStorage } from "@/agents/AgentStorage";
+import { getDaemon } from "@/daemon";
+import { getNDK } from "@/nostr/ndkClient";
+import { PendingDelegationsRegistry, RALRegistry } from "@/services/ral";
+import type { PendingDelegation } from "@/services/ral/types";
+import type { AISdkTool } from "@/tools/types";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { logger } from "@/utils/logger";
+import { NDKEvent, NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
+import { tool } from "ai";
+import { z } from "zod";
+
+const delegateCrossProjectSchema = z.object({
+    content: z.string().describe("The content of the chat message to send"),
+    projectId: z
+        .string()
+        .describe(
+            "The project ID (dTag) to delegate to. Use project_list to discover available projects."
+        ),
+    agentSlug: z
+        .string()
+        .describe(
+            "The slug of the agent within the target project to delegate to. Use project_list to see available agents."
+        ),
+});
+
+type DelegateCrossProjectInput = z.infer<typeof delegateCrossProjectSchema>;
+
+interface DelegateCrossProjectOutput {
+    success: boolean;
+    message: string;
+    delegationConversationId: string;
+}
+
+/**
+ * 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 executeDelegateCrossProject(
+    input: DelegateCrossProjectInput,
+    context: ToolExecutionContext
+): Promise<DelegateCrossProjectOutput> {
+    const { content, projectId, agentSlug } = 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."
+        );
+    }
+
+    // Get known projects from daemon
+    const daemon = getDaemon();
+    const knownProjects = daemon.getKnownProjects();
+    const activeRuntimes = daemon.getActiveRuntimes();
+
+    // Find project by id (dTag) - projectId in knownProjects is "31933:pubkey:dTag"
+    let project = null;
+    let fullProjectId = "";
+    for (const [pId, p] of knownProjects) {
+        const dTag = pId.split(":")[2];
+        if (dTag === projectId) {
+            project = p;
+            fullProjectId = pId;
+            break;
+        }
+    }
+
+    if (!project) {
+        throw new Error(
+            `Project '${projectId}' not found. Use project_list to see available projects.`
+        );
+    }
+
+    // Find agent pubkey
+    let agentPubkey: string | null = null;
+
+    // Try runtime first (if project is running)
+    const runtime = activeRuntimes.get(fullProjectId);
+    if (runtime) {
+        const runtimeContext = runtime.getContext();
+        const agentMap = runtimeContext?.agentRegistry.getAllAgentsMap();
+        if (agentMap) {
+            for (const agent of agentMap.values()) {
+                if (agent.slug === agentSlug) {
+                    agentPubkey = agent.pubkey;
+                    break;
+                }
+            }
+        }
+    }
+
+    // Fall back to storage
+    if (!agentPubkey) {
+        const agents = await agentStorage.getProjectAgents(projectId);
+        const agent = agents.find((a) => a.slug === agentSlug);
+        if (agent) {
+            const signer = new NDKPrivateKeySigner(agent.nsec);
+            agentPubkey = signer.pubkey;
+        }
+    }
+
+    if (!agentPubkey) {
+        throw new Error(
+            `Agent '${agentSlug}' not found in project '${projectId}'. Use project_list to see available agents.`
+        );
+    }
+
+    const ndk = getNDK();
+
+    logger.info("[delegate_crossproject] Publishing cross-project delegation", {
+        agent: context.agent.name,
+        targetProject: projectId,
+        targetAgent: agentSlug,
+        recipientPubkey: agentPubkey.substring(0, 8),
+    });
+
+    // Create delegation event
+    const chatEvent = new NDKEvent(ndk);
+    chatEvent.kind = 1;
+    chatEvent.content = content;
+    chatEvent.tags.push(["p", agentPubkey]);
+    // Add "a" tag referencing the target project
+    chatEvent.tags.push(["a", `31933:${project.pubkey}:${projectId}`]);
+
+    await context.agent.sign(chatEvent);
+    await chatEvent.publish();
+
+    // Register with PendingDelegationsRegistry for q-tag correlation
+    PendingDelegationsRegistry.register(context.agent.pubkey, context.conversationId, chatEvent.id);
+
+    // Register pending delegation in RALRegistry for response routing
+    // Uses atomic merge to safely handle concurrent delegation calls
+    const ralRegistry = RALRegistry.getInstance();
+    const newDelegation: PendingDelegation = {
+        type: "external" as const,
+        delegationConversationId: chatEvent.id,
+        recipientPubkey: agentPubkey,
+        senderPubkey: context.agent.pubkey,
+        prompt: content,
+        projectId: fullProjectId,
+        ralNumber: context.ralNumber,
+    };
+
+    ralRegistry.mergePendingDelegations(
+        context.agent.pubkey,
+        context.conversationId,
+        context.ralNumber,
+        [newDelegation]
+    );
+
+    logger.info("[delegate_crossproject] Delegation registered, agent continues without blocking", {
+        delegationConversationId: chatEvent.id,
+    });
+
+    // Return normal result - agent continues without blocking
+    return {
+        success: true,
+        message: `Delegated to agent '${agentSlug}' in project '${projectId}'. The agent will respond when ready.`,
+        delegationConversationId: shortenConversationId(chatEvent.id),
+    };
+}
+
+export function createDelegateCrossProjectTool(context: ToolExecutionContext): AISdkTool {
+    const aiTool = tool({
+        description: `Delegate a task to an agent in another project. Use project_list first to discover available projects and their agents.
+
+When using this tool, provide context to the recipient, introduce yourself and explain you are an agent and the project you are working on.`,
+        inputSchema: delegateCrossProjectSchema,
+        execute: async (input: DelegateCrossProjectInput) => {
+            return await executeDelegateCrossProject(input, context);
+        },
+    });
+
+    Object.defineProperty(aiTool, "getHumanReadableContent", {
+        value: (args: unknown) => {
+            if (!args || typeof args !== "object") {
+                return "Delegating to cross-project agent";
+            }
+
+            const { projectId, agentSlug } = args as Partial<DelegateCrossProjectInput>;
+
+            if (!projectId || !agentSlug) {
+                return "Delegating to cross-project agent";
+            }
+
+            return `Delegating to agent '${agentSlug}' in project '${projectId}'`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return aiTool as AISdkTool;
+}

package/src/tools/implementations/delegate_followup.ts

@@ -0,0 +1,300 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { getNDK } from "@/nostr";
+import { RALRegistry } from "@/services/ral/RALRegistry";
+import type { AISdkTool } from "@/tools/types";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { logger } from "@/utils/logger";
+import { isHexPrefix, resolvePrefixToId, PREFIX_LENGTH } from "@/utils/nostr-entity-parser";
+import { createEventContext } from "@/services/event-context";
+import { tool } from "ai";
+import { nip19 } from "nostr-tools";
+import { z } from "zod";
+
+/**
+ * Attempts to decode a NIP-19 event ID format to a hex event ID.
+ * Supports: note1..., nevent1..., with or without 'nostr:' prefix.
+ *
+ * @param input - A potential NIP-19 event ID
+ * @returns The decoded 64-char hex event ID, or null if not a valid NIP-19 event format
+ */
+function decodeNip19EventId(input: string): string | null {
+  try {
+    // Strip nostr: prefix if present
+    let cleaned = input.trim();
+    if (cleaned.toLowerCase().startsWith("nostr:")) {
+      cleaned = cleaned.substring(6);
+    }
+
+    // Only attempt decode for note1 or nevent1 prefixes
+    if (!cleaned.startsWith("note1") && !cleaned.startsWith("nevent1")) {
+      return null;
+    }
+
+    const decoded = nip19.decode(cleaned);
+
+    if (decoded.type === "note") {
+      return (decoded.data as string).toLowerCase();
+    }
+
+    if (decoded.type === "nevent") {
+      return (decoded.data as { id: string }).id.toLowerCase();
+    }
+
+    // Other NIP-19 types (npub, nprofile, naddr) are not valid event IDs
+    return null;
+  } catch {
+    // Not a valid NIP-19 format
+    return null;
+  }
+}
+
+/**
+ * Checks if a string is a 64-character hex ID.
+ */
+function isFullHexId(input: string): boolean {
+  return /^[0-9a-fA-F]{64}$/.test(input.trim());
+}
+
+/**
+ * Fallback resolver for 12-char hex prefixes when PrefixKVStore is not initialized.
+ *
+ * This handles edge cases where:
+ * 1. MCP-only execution mode - PrefixKVStore may not be initialized in pure MCP contexts
+ * 2. Timing races with event indexing - the event may exist in RAL but not yet indexed in KV store
+ *
+ * Scans RALRegistry.pending and RALRegistry.completed for matching delegation conversation IDs.
+ * Returns the full 64-char canonical delegation ID if a unique match is found, null otherwise.
+ * Note: Unlike PrefixKVStore, this fallback already canonicalizes followup IDs.
+ *
+ * @param prefix - 12-character hex prefix to resolve
+ * @param ralRegistry - RALRegistry instance to scan
+ * @returns Full 64-char canonical delegation ID if unique match found, null otherwise
+ */
+function resolveFromRALFallback(prefix: string, ralRegistry: RALRegistry): string | null {
+  const normalizedPrefix = prefix.toLowerCase();
+  return ralRegistry.resolveDelegationPrefix(normalizedPrefix);
+}
+
+/**
+ * Attempts to resolve a 12-char hex prefix to a full delegation conversation ID.
+ * Uses PrefixKVStore first, falls back to RALRegistry scan if needed.
+ *
+ * IMPORTANT: This function always returns the canonical delegation conversation ID.
+ * When PrefixKVStore resolves a followup event ID prefix, the result is canonicalized
+ * to the original delegation conversation ID. This ensures consistent behavior across
+ * daemon mode (PrefixKVStore available) and MCP-only mode (RAL fallback only).
+ *
+ * @param prefix - 12-character hex prefix to resolve
+ * @returns Full 64-char canonical delegation ID or null if not found
+ */
+function resolveDelegationPrefix(prefix: string): string | null {
+  const ralRegistry = RALRegistry.getInstance();
+
+  // Try PrefixKVStore first (primary resolution path)
+  const resolved = resolvePrefixToId(prefix);
+  if (resolved) {
+    // Post-resolution canonicalization: PrefixKVStore may return a followup event ID
+    // when the user provides a followup ID prefix. Canonicalize to the original
+    // delegation conversation ID for consistent e-tag and routing behavior.
+    const canonicalized = ralRegistry.canonicalizeDelegationId(resolved);
+    if (canonicalized !== resolved) {
+      logger.info("[delegate_followup] Canonicalized followup ID from PrefixKVStore", {
+        followupId: resolved.substring(0, PREFIX_LENGTH),
+        canonicalId: canonicalized.substring(0, PREFIX_LENGTH),
+      });
+    }
+    return canonicalized;
+  }
+
+  // Fallback: scan RALRegistry for matching delegation conversation IDs
+  // This handles MCP-only execution mode and timing races with event indexing
+  // Note: RAL fallback already canonicalizes followup IDs internally
+  const fallbackResolved = resolveFromRALFallback(prefix, ralRegistry);
+
+  if (fallbackResolved) {
+    // Use info level - MCP-only execution is an expected deployment mode, not a warning condition.
+    // PrefixKVStore may intentionally not be initialized in pure MCP contexts.
+    logger.info("[delegate_followup] Resolved prefix via RAL fallback", {
+      prefix: prefix.substring(0, PREFIX_LENGTH),
+      resolvedId: fallbackResolved.substring(0, PREFIX_LENGTH),
+    });
+    return fallbackResolved;
+  }
+
+  return null;
+}
+
+const delegateFollowupSchema = z.object({
+  delegation_conversation_id: z
+    .string()
+    .describe(
+      "The ID of the delegation to follow up on. Accepts: delegationConversationId (from delegate response), " +
+        "followupEventId (from delegate_followup response), full 64-char hex, 12-char prefix, or NIP-19 formats " +
+        "(note1..., nevent1...) with or without 'nostr:' prefix. Followup IDs are automatically canonicalized " +
+        "to the original delegation conversation ID."
+    ),
+  message: z.string().describe("Your follow-up question or clarification request"),
+});
+
+type DelegateFollowupInput = z.infer<typeof delegateFollowupSchema>;
+
+interface DelegateFollowupOutput {
+  success: boolean;
+  message: string;
+  delegationConversationId: string;
+  followupEventId: string;
+}
+
+async function executeDelegateFollowup(
+  input: DelegateFollowupInput,
+  context: ToolExecutionContext
+): Promise<DelegateFollowupOutput> {
+  const { delegation_conversation_id: inputConversationId, message } = input;
+
+  // Resolve input to full canonical delegation conversation ID.
+  // Handles all input formats: 12-char prefixes, full 64-char hex, NIP-19 formats.
+  // All formats are canonicalized to the original delegation conversation ID.
+  const ralRegistry = RALRegistry.getInstance();
+  let delegation_conversation_id = inputConversationId;
+
+  // Step 1: Handle 12-char hex prefix resolution
+  if (isHexPrefix(inputConversationId)) {
+    const resolved = resolveDelegationPrefix(inputConversationId);
+    if (!resolved) {
+      throw new Error(
+        `Could not resolve prefix "${inputConversationId}" to a delegation. Valid inputs include: ` +
+          "delegationConversationId (from delegate response), followupEventId (from delegate_followup response), " +
+          "full 64-char hex IDs, 12-char prefixes, or NIP-19 formats (note1..., nevent1...) with or without 'nostr:' prefix. " +
+          "The prefix may be ambiguous or no matching delegation was found."
+      );
+    }
+    delegation_conversation_id = resolved;
+  }
+  // Step 2: Handle NIP-19 formats (nostr:nevent1..., note1..., etc.)
+  else {
+    const decodedNip19 = decodeNip19EventId(inputConversationId);
+    if (decodedNip19) {
+      // Successfully decoded NIP-19 to hex, now canonicalize
+      const canonicalized = ralRegistry.canonicalizeDelegationId(decodedNip19);
+      if (canonicalized !== decodedNip19) {
+        logger.info("[delegate_followup] Canonicalized NIP-19 followup ID", {
+          inputFormat: inputConversationId.substring(0, 20) + "...",
+          decodedHex: decodedNip19.substring(0, PREFIX_LENGTH),
+          canonicalId: canonicalized.substring(0, PREFIX_LENGTH),
+        });
+      }
+      delegation_conversation_id = canonicalized;
+    }
+    // Step 3: Handle full 64-char hex IDs that might be followup event IDs
+    else if (isFullHexId(inputConversationId)) {
+      const normalized = inputConversationId.toLowerCase();
+      const canonicalized = ralRegistry.canonicalizeDelegationId(normalized);
+      if (canonicalized !== normalized) {
+        logger.info("[delegate_followup] Canonicalized full hex followup ID", {
+          followupId: normalized.substring(0, PREFIX_LENGTH),
+          canonicalId: canonicalized.substring(0, PREFIX_LENGTH),
+        });
+      }
+      delegation_conversation_id = canonicalized;
+    }
+    // Step 4: Unknown format - pass through unchanged with debug hint
+    else {
+      logger.debug("[delegate_followup] Unknown input format, using as-is", {
+        input: inputConversationId.substring(0, 20),
+      });
+    }
+  }
+
+  // Find the delegation in conversation storage (persists even after RAL is cleared)
+  const delegationInfo = ralRegistry.findDelegation(delegation_conversation_id);
+
+  let recipientPubkey = delegationInfo?.pending?.recipientPubkey ?? delegationInfo?.completed?.recipientPubkey;
+
+  // Fall back to NDK fetch if not found locally (e.g., external delegations or stale state)
+  if (!recipientPubkey) {
+    const ndk = getNDK();
+    const delegationEvent = await ndk.fetchEvent(delegation_conversation_id);
+
+    if (!delegationEvent) {
+      throw new Error(
+        `Could not fetch delegation conversation ${delegation_conversation_id}. Check the delegationConversationIds from your delegate call.`
+      );
+    }
+
+    recipientPubkey = delegationEvent.tagValue("p") ?? undefined;
+  }
+
+  if (!recipientPubkey) {
+    throw new Error(
+      `Delegation conversation ${delegation_conversation_id} has no recipient. Cannot determine who to send follow-up to.`
+    );
+  }
+
+  // Always use the CURRENT RAL number from context.
+  // The delegation's stored ralNumber refers to the RAL that created it, which may have
+  // been cleared since then. We need to register on the CURRENT RAL so it resumes correctly.
+  const effectiveRalNumber = context.ralNumber;
+
+  logger.info("[delegate_followup] Publishing follow-up", {
+    fromAgent: context.agent.slug,
+    delegationConversationId: delegation_conversation_id,
+    recipientPubkey: recipientPubkey.substring(0, 8),
+  });
+
+  const eventContext = createEventContext(context);
+  const followupEventId = await context.agentPublisher.delegateFollowup({
+    recipient: recipientPubkey,
+    content: message,
+    delegationEventId: delegation_conversation_id,
+  }, eventContext);
+
+  // Register the followup as a pending delegation for response routing
+  // Use atomic merge to safely handle concurrent delegation calls
+  // Note: followup delegations use the same delegationConversationId as the original,
+  // but include the followupEventId for routing responses to the new event
+  const newDelegation = {
+    type: "followup" as const,
+    delegationConversationId: delegation_conversation_id,
+    recipientPubkey,
+    senderPubkey: context.agent.pubkey,
+    prompt: message,
+    followupEventId,
+    ralNumber: effectiveRalNumber,
+  };
+
+  // Use atomic merge - this handles concurrent updates safely and merges
+  // the followupEventId into existing entries instead of dropping them
+  ralRegistry.mergePendingDelegations(
+    context.agent.pubkey,
+    context.conversationId,
+    effectiveRalNumber,
+    [newDelegation]
+  );
+
+  // Return normal result - agent continues without blocking
+  return {
+    success: true,
+    message: "Follow-up sent. The agent will respond when ready.",
+    delegationConversationId: shortenConversationId(delegation_conversation_id),
+    followupEventId, // Keep full event ID - this is a Nostr event ID, not a conversation ID
+  };
+}
+
+export function createDelegateFollowupTool(context: ToolExecutionContext): AISdkTool {
+  const aiTool = tool({
+    description:
+      "Send a follow-up question to an agent you previously delegated to. Use after delegate to ask clarifying questions about their response.",
+    inputSchema: delegateFollowupSchema,
+    execute: async (input: DelegateFollowupInput) => {
+      return await executeDelegateFollowup(input, context);
+    },
+  });
+
+  Object.defineProperty(aiTool, "getHumanReadableContent", {
+    value: () => "Sending follow-up question",
+    enumerable: false,
+    configurable: true,
+  });
+
+  return aiTool as AISdkTool;
+}

package/src/tools/implementations/fs_edit.ts

@@ -0,0 +1,162 @@
+import { readFile, writeFile } from "node:fs/promises";
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import { isPathWithinDirectory, isWithinAgentHome } from "@/lib/agent-home";
+import { formatAnyError } from "@/lib/error-formatter";
+import {
+    createExpectedError,
+    type ExpectedErrorResult,
+    getFsErrorDescription,
+    isExpectedFsError,
+} from "@/tools/utils";
+import { tool } from "ai";
+import { z } from "zod";
+
+const editSchema = z.object({
+    path: z
+        .string()
+        .describe("The absolute path to the file to edit"),
+    description: z
+        .string()
+        .min(1, "Description is required and cannot be empty")
+        .describe(
+            "REQUIRED: A clear, concise description of why you're editing this file (5-10 words). Helps provide human-readable context for the operation."
+        ),
+    old_string: z.string().describe("The exact text to replace"),
+    new_string: z.string().describe("The text to replace it with (must be different from old_string)"),
+    replace_all: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Replace all occurrences of old_string (default false)"),
+    allowOutsideWorkingDirectory: z
+        .boolean()
+        .optional()
+        .describe("Set to true to edit files outside the working directory. Required when path is not within the project."),
+});
+
+/**
+ * Core implementation of the edit functionality
+ */
+async function executeEdit(
+    path: string,
+    oldString: string,
+    newString: string,
+    replaceAll: boolean,
+    workingDirectory: string,
+    agentPubkey: string,
+    allowOutsideWorkingDirectory?: boolean,
+): Promise<string | ExpectedErrorResult> {
+    if (!path.startsWith("/")) {
+        throw new Error(`Path must be absolute, got: ${path}`);
+    }
+
+    // Check if path is within working directory (using secure path normalization)
+    const isWithinWorkDir = isPathWithinDirectory(path, workingDirectory);
+
+    // Always allow access to agent's home directory without requiring allowOutsideWorkingDirectory
+    const isInAgentHome = isWithinAgentHome(path, agentPubkey);
+
+    if (!isWithinWorkDir && !isInAgentHome && !allowOutsideWorkingDirectory) {
+        return `Path "${path}" is outside your working directory "${workingDirectory}". If this was intentional, retry with allowOutsideWorkingDirectory: true`;
+    }
+
+    // Read the file
+    const content = await readFile(path, "utf-8");
+
+    // Check if old_string exists - return as expected error since this is user input validation
+    if (!content.includes(oldString)) {
+        return createExpectedError(
+            `old_string not found in ${path}. Make sure you're using the exact string from the file.`
+        );
+    }
+
+    let newContent: string;
+    let replacementCount: number;
+
+    if (replaceAll) {
+        // Replace all occurrences
+        const regex = new RegExp(oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+        newContent = content.replace(regex, newString);
+        replacementCount = (content.match(regex) || []).length;
+    } else {
+        // Check for uniqueness
+        const firstIndex = content.indexOf(oldString);
+        const lastIndex = content.lastIndexOf(oldString);
+
+        // Multiple matches - return as expected error since this is user input validation
+        if (firstIndex !== lastIndex) {
+            return createExpectedError(
+                `old_string appears multiple times in ${path}. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance.`
+            );
+        }
+
+        // Replace single occurrence
+        newContent = content.replace(oldString, newString);
+        replacementCount = 1;
+    }
+
+    // Write the file
+    await writeFile(path, newContent, "utf-8");
+
+    return `Successfully replaced ${replacementCount} occurrence(s) in ${path}`;
+}
+
+/**
+ * Create an AI SDK tool for editing files
+ */
+export function createFsEditTool(context: ToolExecutionContext): AISdkTool {
+    const toolInstance = tool({
+        description:
+            "Performs exact string replacements in files. The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string. Path must be absolute. Editing outside the working directory requires allowOutsideWorkingDirectory: true.",
+
+        inputSchema: editSchema,
+
+        execute: async ({
+            path,
+            description: _description,
+            old_string,
+            new_string,
+            replace_all = false,
+            allowOutsideWorkingDirectory,
+        }: {
+            path: string;
+            description: string;
+            old_string: string;
+            new_string: string;
+            replace_all?: boolean;
+            allowOutsideWorkingDirectory?: boolean;
+        }) => {
+            try {
+                // Validate input - same strings is an expected user error
+                if (old_string === new_string) {
+                    return createExpectedError("old_string and new_string must be different");
+                }
+
+                const result = await executeEdit(path, old_string, new_string, replace_all, context.workingDirectory, context.agent.pubkey, allowOutsideWorkingDirectory);
+                // executeEdit may return an ExpectedErrorResult for validation errors
+                return result;
+            } catch (error: unknown) {
+                // Expected errors (file not found, permission denied, etc.) return error-text
+                // This ensures the error is properly communicated to the LLM without stream failures
+                if (isExpectedFsError(error)) {
+                    const code = (error as NodeJS.ErrnoException).code;
+                    const description = getFsErrorDescription(code);
+                    return createExpectedError(`${description}: ${path}`);
+                }
+
+                // Unexpected errors still throw (they'll be caught by the SDK)
+                throw new Error(`Failed to edit ${path}: ${formatAnyError(error)}`, { cause: error });
+            }
+        },
+    });
+
+    Object.defineProperty(toolInstance, "getHumanReadableContent", {
+        value: ({ path, description }: { path: string; description: string }) => {
+            return `Editing ${path} (${description})`;
+        },
+        enumerable: false,
+        configurable: true,
+    });
+
+    return toolInstance as AISdkTool;
+}