@nuvin/nuvin-core 1.5.2 → 1.6.1

package/dist/index.js

@@ -33,7 +33,8 @@ var AgentEventTypes = {
   SubAgentStarted: "sub_agent_started",
   SubAgentToolCall: "sub_agent_tool_call",
   SubAgentToolResult: "sub_agent_tool_result",
-  SubAgentCompleted: "sub_agent_completed"
+  SubAgentCompleted: "sub_agent_completed",
+  SubAgentMetrics: "sub_agent_metrics"
 };
 
 // src/metrics.ts
@@ -375,6 +376,391 @@ var PersistingConsoleEventPort = class {
   }
 };
 
+// src/tools/tool-call-parser.ts
+function parseJSON(jsonString) {
+  try {
+    const parsed = JSON.parse(jsonString || "{}");
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return {
+        success: false,
+        error: "Parsed JSON must be an object, not an array or primitive"
+      };
+    }
+    return { success: true, data: parsed };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Invalid JSON syntax"
+    };
+  }
+}
+
+// src/tools/tool-validators.ts
+var validateBashToolParams = (params) => {
+  const errors = [];
+  if (!params.cmd || typeof params.cmd !== "string") {
+    errors.push('Required parameter "cmd" must be a non-empty string');
+  }
+  if (params.cwd !== void 0 && typeof params.cwd !== "string") {
+    errors.push('Parameter "cwd" must be a string');
+  }
+  if (params.timeoutMs !== void 0) {
+    if (typeof params.timeoutMs !== "number" || params.timeoutMs < 1) {
+      errors.push('Parameter "timeoutMs" must be a positive number');
+    }
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      cmd: params.cmd,
+      cwd: params.cwd,
+      timeoutMs: params.timeoutMs,
+      description: params.description
+    }
+  };
+};
+var validateFileReadParams = (params) => {
+  const errors = [];
+  if (!params.path || typeof params.path !== "string") {
+    errors.push('Required parameter "path" must be a non-empty string');
+  }
+  if (params.lineStart !== void 0) {
+    if (typeof params.lineStart !== "number" || params.lineStart < 1) {
+      errors.push('Parameter "lineStart" must be a positive integer');
+    }
+  }
+  if (params.lineEnd !== void 0) {
+    if (typeof params.lineEnd !== "number" || params.lineEnd < 1) {
+      errors.push('Parameter "lineEnd" must be a positive integer');
+    }
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      path: params.path,
+      lineStart: params.lineStart,
+      lineEnd: params.lineEnd,
+      description: params.description
+    }
+  };
+};
+var validateFileEditParams = (params) => {
+  const errors = [];
+  if (!params.file_path || typeof params.file_path !== "string") {
+    errors.push('Required parameter "file_path" must be a non-empty string');
+  }
+  if (!params.old_text || typeof params.old_text !== "string") {
+    errors.push('Required parameter "old_text" must be a string');
+  }
+  if (params.new_text === void 0 || typeof params.new_text !== "string") {
+    errors.push('Required parameter "new_text" must be a string');
+  }
+  if (params.dry_run !== void 0 && typeof params.dry_run !== "boolean") {
+    errors.push('Parameter "dry_run" must be a boolean');
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      file_path: params.file_path,
+      old_text: params.old_text,
+      new_text: params.new_text,
+      dry_run: params.dry_run,
+      description: params.description
+    }
+  };
+};
+var validateFileNewParams = (params) => {
+  const errors = [];
+  if (!params.file_path || typeof params.file_path !== "string") {
+    errors.push('Required parameter "file_path" must be a non-empty string');
+  }
+  if (params.content === void 0 || typeof params.content !== "string") {
+    errors.push('Required parameter "content" must be a string');
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      file_path: params.file_path,
+      content: params.content,
+      description: params.description
+    }
+  };
+};
+var validateDirLsParams = (params) => {
+  const errors = [];
+  if (params.path !== void 0 && typeof params.path !== "string") {
+    errors.push('Parameter "path" must be a string');
+  }
+  if (params.limit !== void 0) {
+    if (typeof params.limit !== "number" || params.limit < 1) {
+      errors.push('Parameter "limit" must be a positive integer');
+    }
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      path: params.path,
+      limit: params.limit,
+      description: params.description
+    }
+  };
+};
+var validateWebSearchParams = (params) => {
+  const errors = [];
+  if (!params.query || typeof params.query !== "string") {
+    errors.push('Required parameter "query" must be a non-empty string');
+  }
+  if (params.count !== void 0) {
+    if (typeof params.count !== "number" || params.count < 1 || params.count > 50) {
+      errors.push('Parameter "count" must be a number between 1 and 50');
+    }
+  }
+  if (params.offset !== void 0) {
+    if (typeof params.offset !== "number" || params.offset < 0) {
+      errors.push('Parameter "offset" must be a non-negative number');
+    }
+  }
+  if (params.domains !== void 0) {
+    if (!Array.isArray(params.domains) || !params.domains.every((d) => typeof d === "string")) {
+      errors.push('Parameter "domains" must be an array of strings');
+    }
+  }
+  if (params.recencyDays !== void 0) {
+    if (typeof params.recencyDays !== "number" || params.recencyDays < 1) {
+      errors.push('Parameter "recencyDays" must be a positive number');
+    }
+  }
+  if (params.lang !== void 0 && typeof params.lang !== "string") {
+    errors.push('Parameter "lang" must be a string');
+  }
+  if (params.region !== void 0 && typeof params.region !== "string") {
+    errors.push('Parameter "region" must be a string');
+  }
+  if (params.safe !== void 0 && typeof params.safe !== "boolean") {
+    errors.push('Parameter "safe" must be a boolean');
+  }
+  if (params.type !== void 0) {
+    if (params.type !== "web" && params.type !== "images") {
+      errors.push('Parameter "type" must be either "web" or "images"');
+    }
+  }
+  if (params.hydrateMeta !== void 0 && typeof params.hydrateMeta !== "boolean") {
+    errors.push('Parameter "hydrateMeta" must be a boolean');
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      query: params.query,
+      count: params.count,
+      offset: params.offset,
+      domains: params.domains,
+      recencyDays: params.recencyDays,
+      lang: params.lang,
+      region: params.region,
+      safe: params.safe,
+      type: params.type,
+      hydrateMeta: params.hydrateMeta,
+      description: params.description
+    }
+  };
+};
+var validateWebFetchParams = (params) => {
+  const errors = [];
+  if (!params.url || typeof params.url !== "string") {
+    errors.push('Required parameter "url" must be a non-empty string');
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      url: params.url,
+      description: params.description
+    }
+  };
+};
+var validateTodoWriteParams = (params) => {
+  const errors = [];
+  if (!params.todos || !Array.isArray(params.todos)) {
+    errors.push('Required parameter "todos" must be an array');
+  } else {
+    for (let i = 0; i < params.todos.length; i++) {
+      const todo = params.todos[i];
+      if (typeof todo !== "object" || todo === null) {
+        errors.push(`todos[${i}] must be an object`);
+        continue;
+      }
+      if (!todo.id || typeof todo.id !== "string") {
+        errors.push(`todos[${i}].id must be a non-empty string`);
+      }
+      if (!todo.content || typeof todo.content !== "string") {
+        errors.push(`todos[${i}].content must be a non-empty string`);
+      }
+      if (!todo.status || !["pending", "in_progress", "completed"].includes(todo.status)) {
+        errors.push(`todos[${i}].status must be one of: pending, in_progress, completed`);
+      }
+      if (!todo.priority || !["high", "medium", "low"].includes(todo.priority)) {
+        errors.push(`todos[${i}].priority must be one of: high, medium, low`);
+      }
+      if (todo.createdAt !== void 0 && typeof todo.createdAt !== "string") {
+        errors.push(`todos[${i}].createdAt must be a string`);
+      }
+    }
+  }
+  if (params.description !== void 0 && typeof params.description !== "string") {
+    errors.push('Parameter "description" must be a string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      todos: params.todos,
+      description: params.description
+    }
+  };
+};
+var validateAssignTaskParams = (params) => {
+  const errors = [];
+  if (!params.agent || typeof params.agent !== "string") {
+    errors.push('Required parameter "agent" must be a non-empty string');
+  }
+  if (!params.task || typeof params.task !== "string") {
+    errors.push('Required parameter "task" must be a non-empty string');
+  }
+  if (!params.description || typeof params.description !== "string") {
+    errors.push('Required parameter "description" must be a non-empty string');
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    data: {
+      agent: params.agent,
+      task: params.task,
+      description: params.description
+    }
+  };
+};
+var toolValidators = {
+  bash_tool: validateBashToolParams,
+  file_read: validateFileReadParams,
+  file_edit: validateFileEditParams,
+  file_new: validateFileNewParams,
+  dir_ls: validateDirLsParams,
+  web_search: validateWebSearchParams,
+  web_fetch: validateWebFetchParams,
+  todo_write: validateTodoWriteParams,
+  assign_task: validateAssignTaskParams
+};
+
+// src/tools/tool-call-converter.ts
+function convertToolCall(toolCall, options = {}) {
+  const { strict = false } = options;
+  const parseResult = parseJSON(toolCall.function.arguments);
+  if (!parseResult.success) {
+    return {
+      valid: false,
+      error: parseResult.error,
+      errorType: "parse",
+      callId: toolCall.id,
+      toolName: toolCall.function.name,
+      rawArguments: toolCall.function.arguments
+    };
+  }
+  const toolName = toolCall.function.name;
+  const parameters = parseResult.data;
+  const validator = toolValidators[toolName];
+  if (validator) {
+    const validationResult = validator(parameters);
+    if (!validationResult.valid) {
+      if (strict) {
+        return {
+          valid: false,
+          error: `Validation failed: ${validationResult.errors.join("; ")}`,
+          errorType: "validation",
+          callId: toolCall.id,
+          toolName: toolCall.function.name,
+          rawArguments: toolCall.function.arguments
+        };
+      }
+      console.warn(`[ToolCallConverter] Validation warnings for ${toolName}:`, validationResult.errors);
+    }
+  }
+  return {
+    valid: true,
+    invocation: {
+      id: toolCall.id,
+      name: toolCall.function.name,
+      parameters
+    }
+  };
+}
+function convertToolCalls(toolCalls, options = {}) {
+  const { strict = false, throwOnError = true } = options;
+  const invocations = [];
+  for (const tc of toolCalls) {
+    const result = convertToolCall(tc, { strict });
+    if (!result.valid) {
+      const errorMsg = `Tool call ${result.callId} (${result.toolName}): ${result.error}`;
+      if (throwOnError) {
+        throw new Error(errorMsg);
+      }
+      console.error(`[ToolCallConverter] ${errorMsg}`);
+      invocations.push({
+        id: result.callId,
+        name: result.toolName,
+        parameters: {}
+      });
+    } else {
+      invocations.push(result.invocation);
+    }
+  }
+  return invocations;
+}
+
 // src/orchestrator.ts
 var removeAttachmentTokens = (value, attachments) => {
   return attachments.reduce((acc, attachment) => {
@@ -629,37 +1015,30 @@ var AgentOrchestrator = class {
     if (!_llm) {
       throw new Error("LLM provider not set");
     }
-    if (opts.retry) {
-      providerMsgs = this.context.toProviderMessages(history, this.cfg.systemPrompt, []);
-      userMessages = [];
-      userDisplay = "[Retry]";
-      enhanced = [];
+    const normalized = typeof content === "string" ? { text: content, displayText: content, attachments: [] } : {
+      text: content.text ?? "",
+      displayText: content.displayText,
+      attachments: Array.isArray(content.attachments) ? content.attachments : []
+    };
+    const attachments = normalized.attachments;
+    enhanced = this.reminders.enhance(normalized.text, { conversationId: convo });
+    const enhancedCombined = enhanced.join("\n");
+    const messageParts = buildMessageParts(enhancedCombined, attachments);
+    let userContent;
+    if (attachments.length > 0 || messageParts.some((part) => part.type === "image")) {
+      userContent = { type: "parts", parts: messageParts };
+    } else if (messageParts.length === 1 && messageParts[0]?.type === "text") {
+      userContent = messageParts[0].text;
+    } else if (messageParts.length > 0) {
+      userContent = { type: "parts", parts: messageParts };
     } else {
-      const normalized = typeof content === "string" ? { text: content, displayText: content, attachments: [] } : {
-        text: content.text ?? "",
-        displayText: content.displayText,
-        attachments: Array.isArray(content.attachments) ? content.attachments : []
-      };
-      const attachments = normalized.attachments;
-      enhanced = this.reminders.enhance(normalized.text, { conversationId: convo });
-      const enhancedCombined = enhanced.join("\n");
-      const messageParts = buildMessageParts(enhancedCombined, attachments);
-      let userContent;
-      if (attachments.length > 0 || messageParts.some((part) => part.type === "image")) {
-        userContent = { type: "parts", parts: messageParts };
-      } else if (messageParts.length === 1 && messageParts[0]?.type === "text") {
-        userContent = messageParts[0].text;
-      } else if (messageParts.length > 0) {
-        userContent = { type: "parts", parts: messageParts };
-      } else {
-        userContent = enhancedCombined;
-      }
-      providerMsgs = this.context.toProviderMessages(history, this.cfg.systemPrompt, [userContent]);
-      userDisplay = resolveDisplayText(normalized.text, attachments, normalized.displayText);
-      const userTimestamp = this.clock.iso();
-      userMessages = [{ id: this.ids.uuid(), role: "user", content: userContent, timestamp: userTimestamp }];
-      await this.memory.append(convo, userMessages);
+      userContent = enhancedCombined;
     }
+    providerMsgs = this.context.toProviderMessages(history, this.cfg.systemPrompt, [userContent]);
+    userDisplay = resolveDisplayText(normalized.text, attachments, normalized.displayText);
+    const userTimestamp = this.clock.iso();
+    userMessages = [{ id: this.ids.uuid(), role: "user", content: userContent, timestamp: userTimestamp }];
+    await this.memory.append(convo, userMessages);
     if (opts.signal?.aborted) throw new Error("Aborted");
     const toolDefs = this.tools.getToolDefinitions(this.cfg.enabledTools ?? []);
     const toolNames = toolDefs.map((t) => t.function.name);
@@ -812,7 +1191,14 @@ var AgentOrchestrator = class {
       };
       const toolResultMsgs = [];
       for (const tr of toolResults) {
-        const contentStr = tr.status === "error" ? String(tr.result) : typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result);
+        let contentStr;
+        if (tr.status === "error") {
+          contentStr = tr.result;
+        } else if (tr.type === "text") {
+          contentStr = tr.result;
+        } else {
+          contentStr = JSON.stringify(tr.result, null, 2);
+        }
         toolResultMsgs.push({
           id: tr.id,
           role: "tool",
@@ -838,7 +1224,14 @@ var AgentOrchestrator = class {
         tool_calls: approvedCalls
       });
       for (const tr of toolResults) {
-        const contentStr = tr.status === "error" ? String(tr.result) : typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result);
+        let contentStr;
+        if (tr.status === "error") {
+          contentStr = tr.result;
+        } else if (tr.type === "text") {
+          contentStr = tr.result;
+        } else {
+          contentStr = JSON.stringify(tr.result, null, 2);
+        }
         accumulatedMessages.push({ role: "tool", content: contentStr, tool_call_id: tr.id, name: tr.name });
       }
       if (opts.signal?.aborted) throw new Error("Aborted");
@@ -978,14 +1371,9 @@ var AgentOrchestrator = class {
     }
   }
   toInvocations(toolCalls) {
-    return toolCalls.map((tc) => {
-      let parameters = {};
-      try {
-        parameters = JSON.parse(tc.function.arguments || "{}");
-      } catch {
-        parameters = {};
-      }
-      return { id: tc.id, name: tc.function.name, parameters };
+    return convertToolCalls(toolCalls, {
+      strict: this.cfg.strictToolValidation ?? false,
+      throwOnError: true
     });
   }
 };
@@ -1543,6 +1931,18 @@ var TodoStore = class {
   }
 };
 
+// src/tools/result-helpers.ts
+function okText(result, metadata) {
+  return { status: "success", type: "text", result, metadata };
+}
+function okJson(result, metadata) {
+  return { status: "success", type: "json", result, metadata };
+}
+function err(result, metadata, errorReason) {
+  const finalMetadata = errorReason ? { ...metadata, errorReason } : metadata;
+  return { status: "error", type: "text", result, metadata: finalMetadata };
+}
+
 // src/tools/TodoWriteTool.ts
 var TodoWriteTool = class {
   constructor(store) {
@@ -1634,28 +2034,28 @@ When in doubt, use this tool. Being proactive with task management demonstrates
     const todos = params?.todos;
     const ctx = context;
     if (!Array.isArray(todos) || todos.length === 0) {
-      return { status: "error", type: "text", result: 'Parameter "todos" must be a non-empty array' };
+      return err('Parameter "todos" must be a non-empty array', void 0, "invalid_input" /* InvalidInput */);
     }
     for (let i = 0; i < todos.length; i++) {
       const t = todos[i];
       if (!t) continue;
       if (!t.content || typeof t.content !== "string" || !t.content.trim()) {
-        return { status: "error", type: "text", result: `Todo ${i + 1}: content required` };
+        return err(`Todo ${i + 1}: content required`, void 0, "invalid_input" /* InvalidInput */);
       }
       if (!["pending", "in_progress", "completed"].includes(String(t.status))) {
-        return { status: "error", type: "text", result: `Todo ${i + 1}: invalid status` };
+        return err(`Todo ${i + 1}: invalid status`, void 0, "invalid_input" /* InvalidInput */);
       }
       if (!["high", "medium", "low"].includes(String(t.priority))) {
-        return { status: "error", type: "text", result: `Todo ${i + 1}: invalid priority` };
+        return err(`Todo ${i + 1}: invalid priority`, void 0, "invalid_input" /* InvalidInput */);
       }
       if (!t.id || typeof t.id !== "string" || !t.id.trim()) {
-        return { status: "error", type: "text", result: `Todo ${i + 1}: id required` };
+        return err(`Todo ${i + 1}: id required`, void 0, "invalid_input" /* InvalidInput */);
       }
     }
     const ids = todos.map((t) => t.id);
     const unique = new Set(ids);
     if (unique.size !== ids.length) {
-      return { status: "error", type: "text", result: "Todo items must have unique IDs" };
+      return err("Todo items must have unique IDs", void 0, "invalid_input" /* InvalidInput */);
     }
     const conversationId = ctx?.sessionId || ctx?.conversationId || "default";
     const nowIso = (/* @__PURE__ */ new Date()).toISOString();
@@ -1694,17 +2094,13 @@ All todo items are now completed! Ask about next steps. Completed list:
 Your todo list has changed. DO NOT mention this explicitly to the user. Latest contents:
 [${serialized}].
 </system-reminder>`;
-    return {
-      status: "success",
-      type: "text",
-      result: systemReminder,
-      metadata: {
-        recentChanges: true,
-        stats,
-        progress: `${progress}%`,
-        allCompleted
-      }
-    };
+    return okText(systemReminder, {
+      recentChanges: true,
+      stats,
+      progress: `${progress}%`,
+      allCompleted,
+      conversationId
+    });
   }
 };
 
@@ -1919,21 +2315,35 @@ var WebSearchTool = class {
     };
   }
   provider = new GoogleCseProvider();
+  /**
+   * Execute web search using Google Programmable Search Engine
+   *
+   * @param params - Search query and optional filters (domains, recency, language, region)
+   * @param ctx - Execution context with optional abort signal
+   * @returns Structured JSON with search results including title, URL, snippet, and metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await webSearchTool.execute({
+   *   query: 'TypeScript discriminated unions',
+   *   count: 10,
+   *   lang: 'en'
+   * });
+   * if (result.status === 'success' && result.type === 'json') {
+   *   console.log(result.result.count); // number of results
+   *   result.result.items.forEach(item => {
+   *     console.log(`${item.title}: ${item.url}`);
+   *   });
+   * }
+   * ```
+   */
   async execute(params, ctx) {
     if (ctx?.signal?.aborted) {
-      return {
-        type: "text",
-        status: "error",
-        result: "Search aborted by user"
-      };
+      return err("Search aborted by user", void 0, "aborted" /* Aborted */);
     }
     const query = typeof params.query === "string" ? params.query : "";
     if (!query) {
-      return {
-        type: "text",
-        status: "error",
-        result: "Missing required parameter: query"
-      };
+      return err("Missing required parameter: query", void 0, "invalid_input" /* InvalidInput */);
     }
     const p = {
       query: String(params.query ?? "").trim(),
@@ -1948,14 +2358,10 @@ var WebSearchTool = class {
       hydrateMeta: params.hydrateMeta ?? false
     };
     if (!p.query) {
-      return { status: "error", type: "text", result: "Missing 'query'" };
+      return err("Missing 'query'", void 0, "invalid_input" /* InvalidInput */);
     }
     if (!process.env.GOOGLE_CSE_KEY || !process.env.GOOGLE_CSE_CX) {
-      return {
-        status: "error",
-        type: "text",
-        result: "GOOGLE_CSE_KEY and GOOGLE_CSE_CX are required for this tool (Google CSE only)."
-      };
+      return err("GOOGLE_CSE_KEY and GOOGLE_CSE_CX are required for this tool (Google CSE only).", void 0, "invalid_input" /* InvalidInput */);
     }
     try {
       let results = await this.provider.search(p, ctx?.signal);
@@ -1969,23 +2375,30 @@ var WebSearchTool = class {
         seen.add(k);
         return true;
       }).slice(0, p.count);
-      return {
-        status: "success",
-        type: "json",
-        result: {
-          engine: this.provider.name,
-          count: results.length,
-          items: results
-        }
-      };
+      const appliedFilters = {};
+      if (p.domains.length > 0) appliedFilters.domains = p.domains;
+      if (p.recencyDays > 0) appliedFilters.recencyDays = p.recencyDays;
+      if (p.lang && p.lang !== "en") appliedFilters.lang = p.lang;
+      if (p.region) appliedFilters.region = p.region;
+      return okJson({
+        engine: this.provider.name,
+        count: results.length,
+        items: results,
+        query: p.query,
+        appliedFilters: Object.keys(appliedFilters).length > 0 ? appliedFilters : void 0
+      }, {
+        offset: p.offset,
+        totalRequested: p.count,
+        hydrated: p.hydrateMeta
+      });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       const isAborted = message.includes("aborted by user");
-      return {
-        status: "error",
-        type: "text",
-        result: isAborted ? "Search aborted by user" : message.slice(0, 500)
-      };
+      return err(
+        isAborted ? "Search aborted by user" : message.slice(0, 500),
+        void 0,
+        isAborted ? "aborted" /* Aborted */ : "unknown" /* Unknown */
+      );
     }
   }
 };
@@ -2024,10 +2437,10 @@ var WebFetchTool = class {
   async execute(params, ctx) {
     const target = String(params.url ?? "");
     if (!target) {
-      return { status: "error", type: "text", result: "URL parameter is required" };
+      return err("URL parameter is required", void 0, "invalid_input" /* InvalidInput */);
     }
     if (ctx?.signal?.aborted) {
-      return { status: "error", type: "text", result: "Fetch aborted by user" };
+      return err("Fetch aborted by user", void 0, "aborted" /* Aborted */);
     }
     try {
       const res = await fetch(target, {
@@ -2037,33 +2450,41 @@ var WebFetchTool = class {
         signal: ctx?.signal
       });
       if (!res.ok) {
-        return {
-          status: "error",
-          type: "text",
-          result: `HTTP ${res.status} ${res.statusText}`
-        };
+        return err(`HTTP ${res.status} ${res.statusText}`, { url: target }, "network_error" /* NetworkError */);
       }
       const contentType = res.headers.get("content-type") || "";
       const text = await res.text();
+      const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
+      let finalText;
+      let format;
       if (contentType.includes("application/json")) {
-        const markdown = `\`\`\`json
+        finalText = `\`\`\`json
 ${text}
 \`\`\``;
-        return { status: "success", type: "text", result: markdown };
+        format = "json";
       } else if (contentType.includes("text/html")) {
-        const markdown = this.turndownService.turndown(text);
-        return { status: "success", type: "text", result: markdown };
+        finalText = this.turndownService.turndown(text);
+        format = "markdown";
       } else {
-        return { status: "success", type: "text", result: text };
+        finalText = text;
+        format = "text";
       }
+      return okText(finalText, {
+        url: target,
+        contentType,
+        statusCode: res.status,
+        format,
+        size: text.length,
+        fetchedAt
+      });
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       const isAborted = errorMessage.includes("aborted") || error.name === "AbortError";
-      return {
-        status: "error",
-        type: "text",
-        result: isAborted ? "Fetch aborted by user" : errorMessage
-      };
+      return err(
+        isAborted ? "Fetch aborted by user" : errorMessage,
+        { url: target },
+        isAborted ? "aborted" /* Aborted */ : "network_error" /* NetworkError */
+      );
     }
   }
 };
@@ -2071,17 +2492,6 @@ ${text}
 // src/tools/FileReadTool.ts
 import { promises as fs3 } from "fs";
 import * as path3 from "path";
-
-// src/tools/result-helpers.ts
-function ok(result, metadata) {
-  return { status: "success", type: "text", result, metadata };
-}
-function err(result, metadata, errorReason) {
-  const finalMetadata = errorReason ? { ...metadata, errorReason } : metadata;
-  return { status: "error", type: "text", result, metadata: finalMetadata };
-}
-
-// src/tools/FileReadTool.ts
 var FileReadTool = class {
   name = "file_read";
   rootDir;
@@ -2114,24 +2524,45 @@ var FileReadTool = class {
       parameters: this.parameters
     };
   }
+  /**
+   * Read file contents with optional line range selection
+   *
+   * @param params - File path and optional line range (lineStart, lineEnd)
+   * @param context - Execution context with optional workspace directory
+   * @returns File content as text with metadata including path, size, and line range
+   *
+   * @example
+   * ```typescript
+   * const result = await fileReadTool.execute({ path: 'package.json' });
+   * if (result.status === 'success' && result.type === 'text') {
+   *   console.log(result.result); // file contents
+   *   console.log(result.metadata?.path); // resolved file path
+   *   console.log(result.metadata?.size); // file size in bytes
+   * }
+   * ```
+   */
   async execute(params, context) {
     try {
       if (!params.path || typeof params.path !== "string") {
-        return err('Parameter "path" must be a non-empty string');
+        return err('Parameter "path" must be a non-empty string', void 0, "invalid_input" /* InvalidInput */);
       }
       const abs = this.resolveSafePath(params.path, context);
       const st = await fs3.stat(abs).catch(() => null);
-      if (!st || !st.isFile()) return err(`File not found: ${params.path}`);
+      if (!st || !st.isFile()) return err(`File not found: ${params.path}`, { path: params.path }, "not_found" /* NotFound */);
       if (st.size > this.maxBytesHard) {
-        return err(`File too large (${st.size} bytes). Hard cap is ${this.maxBytesHard} bytes.`);
+        return err(`File too large (${st.size} bytes). Hard cap is ${this.maxBytesHard} bytes.`, { path: params.path }, "invalid_input" /* InvalidInput */);
       }
       const payload = await fs3.readFile(abs);
       let text = payload.toString("utf8");
+      const bomStripped = text.charCodeAt(0) === 65279;
       text = stripUtfBom(text);
       const metadata = {
         path: params.path,
         created: st.birthtime.toISOString(),
-        modified: st.mtime.toISOString()
+        modified: st.mtime.toISOString(),
+        size: st.size,
+        encoding: "utf8",
+        bomStripped
       };
       if (params.lineStart || params.lineEnd) {
         const lines = text.split(/\r?\n/);
@@ -2144,17 +2575,19 @@ var FileReadTool = class {
           return `${lineNum}\u2502${line}`;
         });
         const slice = numberedLines.join("\n");
-        return ok(slice, {
+        return okText(slice, {
           ...metadata,
-          linesTotal: totalLines,
-          lineStart: lo,
-          lineEnd: hi
+          lineRange: {
+            lineStart: lo,
+            lineEnd: hi,
+            linesTotal: totalLines
+          }
         });
       }
-      return ok(text, metadata);
+      return okText(text, metadata);
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
-      return err(message);
+      return err(message, { path: params.path }, "unknown" /* Unknown */);
     }
   }
   // ---------- helpers ----------
@@ -2209,16 +2642,22 @@ var FileNewTool = class {
   }
   async execute(p, ctx) {
     try {
-      if (!p.file_path?.trim()) return err('Parameter "file_path" is required.');
-      if (typeof p.content !== "string") return err('"content" must be a string.');
+      if (!p.file_path?.trim()) return err('Parameter "file_path" is required.', void 0, "invalid_input" /* InvalidInput */);
+      if (typeof p.content !== "string") return err('"content" must be a string.', void 0, "invalid_input" /* InvalidInput */);
       const abs = this.resolveSafePath(p.file_path, ctx);
+      const existsBefore = await fs4.stat(abs).then(() => true).catch(() => false);
       await fs4.mkdir(path4.dirname(abs), { recursive: true });
       const bytes = Buffer.from(p.content, "utf8");
       await this.writeAtomic(abs, bytes);
-      return ok(`File written at ${p.file_path}.`, { file_path: p.file_path, bytes: bytes.length });
+      return okText(`File written at ${p.file_path}.`, {
+        file_path: p.file_path,
+        bytes: bytes.length,
+        created: (/* @__PURE__ */ new Date()).toISOString(),
+        overwritten: existsBefore
+      });
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
-      return err(message);
+      return err(message, void 0, "unknown" /* Unknown */);
     }
   }
   // helpers
@@ -2295,21 +2734,21 @@ var FileEditTool = class {
   }
   async execute(p, ctx) {
     try {
-      if (!p.file_path?.trim()) return err('Parameter "file_path" is required.');
+      if (!p.file_path?.trim()) return err('Parameter "file_path" is required.', void 0, "invalid_input" /* InvalidInput */);
       const abs = resolveAbsoluteWithinRoot(p.file_path, ctx, this.rootDir);
       if (typeof p.old_text !== "string") {
-        return err("old_text must be a string.");
+        return err("old_text must be a string.", void 0, "invalid_input" /* InvalidInput */);
       }
       if (typeof p.new_text !== "string") {
-        return err("new_text must be a string.");
+        return err("new_text must be a string.", void 0, "invalid_input" /* InvalidInput */);
       }
       const st = await fs5.stat(abs).catch(() => null);
       const exists = !!st && st.isFile();
       if (!exists || !st) {
-        return err("File does not exist. Use a file creation tool to create new files.");
+        return err("File does not exist. Use a file creation tool to create new files.", void 0, "not_found" /* NotFound */);
       }
       if (st.size > this.maxBytes) {
-        return err(`File too large (${st.size} bytes). Cap is ${this.maxBytes}.`);
+        return err(`File too large (${st.size} bytes). Cap is ${this.maxBytes}.`, void 0, "invalid_input" /* InvalidInput */);
       }
       const originalBytes = await fs5.readFile(abs);
       const originalEol = detectEol(originalBytes) ?? "lf";
@@ -2322,14 +2761,16 @@ var FileEditTool = class {
         const preview = oldTextLF.slice(0, 100).replace(/\n/g, "\\n");
         return err(
           `old_text not found in file. Make sure it matches exactly including whitespace.
-Searching for: "${preview}${oldTextLF.length > 100 ? "..." : ""}"`
+Searching for: "${preview}${oldTextLF.length > 100 ? "..." : ""}"`,
+          void 0,
+          "not_found" /* NotFound */
         );
       }
       const resultLF = originalLF.slice(0, idx) + newTextLF + originalLF.slice(idx + oldTextLF.length);
       const finalText = convertEol(resultLF, originalEol);
       const finalBytes = Buffer.from(finalText, "utf8");
       if (finalBytes.length > this.maxBytes) {
-        return err(`Resulting file too large (${finalBytes.length} bytes). Cap is ${this.maxBytes}.`);
+        return err(`Resulting file too large (${finalBytes.length} bytes). Cap is ${this.maxBytes}.`, void 0, "invalid_input" /* InvalidInput */);
       }
       const beforeSha = sha256(originalBytes);
       const afterSha = sha256(finalBytes);
@@ -2338,10 +2779,13 @@ Searching for: "${preview}${oldTextLF.length > 100 ? "..." : ""}"`
         await atomicWrite(abs, finalBytes);
       }
       const lineNumbers = this.calculateLineNumbers(originalLF, oldTextLF, newTextLF, idx);
-      return ok(
+      return okText(
         noChange ? "No changes (content identical)." : p.dry_run ? "Validated (dry run: no write)." : "Edit applied successfully.",
         {
           path: showPath(abs, this.rootDir),
+          created: st.birthtime.toISOString(),
+          modified: st.mtime.toISOString(),
+          size: st.size,
           eol: originalEol,
           oldTextLength: oldTextLF.length,
           newTextLength: newTextLF.length,
@@ -2349,11 +2793,12 @@ Searching for: "${preview}${oldTextLF.length > 100 ? "..." : ""}"`
           beforeSha,
           afterSha,
           dryRun: !!p.dry_run,
-          lineNumbers
+          lineNumbers,
+          noChange
         }
       );
     } catch (e) {
-      return err(e instanceof Error ? e.message : String(e));
+      return err(e instanceof Error ? e.message : String(e), void 0, "unknown" /* Unknown */);
     }
   }
   calculateLineNumbers(originalText, oldText, newText, matchIndex) {
@@ -2500,6 +2945,23 @@ var BashTool = class {
       parameters: this.parameters
     };
   }
+  /**
+   * Execute bash command with timeout protection
+   *
+   * @param p - Command parameters including cmd, cwd, and optional timeout
+   * @param ctx - Execution context with optional abort signal
+   * @returns Structured result with command output and execution metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await bashTool.execute({ cmd: 'ls -la' });
+   * if (result.status === 'success' && result.type === 'text') {
+   *   console.log(result.result); // command output
+   *   console.log(result.metadata?.code); // exit code
+   *   console.log(result.metadata?.cwd); // working directory
+   * }
+   * ```
+   */
   async execute(p, ctx) {
     try {
       return await this.execOnce(p, ctx?.signal);
@@ -2618,7 +3080,7 @@ ${output}` : "";
         }
         return err(output, metadata);
       }
-      return ok(output, { code, signal: exitSignal, cwd });
+      return okText(output, { code, signal: exitSignal, cwd, stripped: stripAnsi });
     } catch (e) {
       if (timer) clearTimeout(timer);
       const message = e instanceof Error ? e.message : String(e);
@@ -2701,7 +3163,7 @@ var DirLsTool = class {
       name: this.name,
       description: [
         "List files and directories in a specified directory.",
-        "Returns entries sorted alphabetically by name in ls -la format.",
+        "Returns entries sorted alphabetically by name as structured JSON.",
         "",
         "Typical uses:",
         "1) List all files in current directory",
@@ -2733,6 +3195,25 @@ var DirLsTool = class {
       return 0;
     }
   }
+  /**
+   * List directory contents as structured JSON
+   *
+   * @param params - Directory path and optional limit
+   * @param context - Execution context with optional workspace directory
+   * @returns Structured JSON with directory entries including name, type, size, and metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await dirLsTool.execute({ path: 'src/tools', limit: 50 });
+   * if (result.status === 'success' && result.type === 'json') {
+   *   console.log(result.result.path); // 'src/tools'
+   *   console.log(result.result.total); // number of entries
+   *   result.result.entries.forEach(entry => {
+   *     console.log(`${entry.name} (${entry.type}): ${entry.size} bytes`);
+   *   });
+   * }
+   * ```
+   */
   async execute(params, context) {
     try {
       const targetPath = params.path ?? ".";
@@ -2741,10 +3222,10 @@ var DirLsTool = class {
       const abs = this.resolveSafePath(targetPath, context);
       const st = await fs7.stat(abs).catch(() => null);
       if (!st) {
-        return err(`Directory not found: ${targetPath}`);
+        return err(`Directory not found: ${targetPath}`, void 0, "not_found" /* NotFound */);
       }
       if (!st.isDirectory()) {
-        return err(`Path is not a directory: ${targetPath}`);
+        return err(`Path is not a directory: ${targetPath}`, void 0, "invalid_input" /* InvalidInput */);
       }
       const entries = await fs7.readdir(abs);
       const results = [];
@@ -2781,40 +3262,23 @@ var DirLsTool = class {
         results.push(dirEntry);
       }
       results.sort((a, b) => a.name.localeCompare(b.name));
-      const lines = results.map((entry) => this.formatAsLsLine(entry));
-      const output = lines.join("\n");
-      return ok(output);
+      const result = okJson(
+        {
+          path: targetPath,
+          entries: results,
+          truncated: entries.length > limit,
+          total: results.length
+        },
+        {
+          limit,
+          includeHidden
+        }
+      );
+      return result;
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
-      return err(message);
-    }
-  }
-  formatAsLsLine(entry) {
-    const mode = entry.mode ? this.formatMode(entry.mode) : "----------";
-    const size = entry.size !== void 0 ? entry.size.toString().padStart(10) : "         0";
-    const date = entry.mtime ? new Date(entry.mtime) : /* @__PURE__ */ new Date();
-    const month = date.toLocaleString("en-US", { month: "short" });
-    const day = date.getDate().toString().padStart(2);
-    const time = `${date.getHours().toString().padStart(2, "0")}:${date.getMinutes().toString().padStart(2, "0")}`;
-    const dateStr = `${month} ${day} ${time}`;
-    const typeIndicator = entry.type === "directory" ? "/" : entry.type === "symlink" ? "@" : "";
-    const name = `${entry.name}${typeIndicator}`;
-    return `${mode} ${size} ${dateStr} ${name}`;
-  }
-  formatMode(mode) {
-    const fileType = (mode & 61440) === 16384 ? "d" : (mode & 61440) === 40960 ? "l" : "-";
-    const perms = [
-      mode & 256 ? "r" : "-",
-      mode & 128 ? "w" : "-",
-      mode & 64 ? "x" : "-",
-      mode & 32 ? "r" : "-",
-      mode & 16 ? "w" : "-",
-      mode & 8 ? "x" : "-",
-      mode & 4 ? "r" : "-",
-      mode & 2 ? "w" : "-",
-      mode & 1 ? "x" : "-"
-    ];
-    return fileType + perms.join("");
+      return err(message, void 0, "unknown" /* Unknown */);
+    }
   }
   resolveSafePath(target, context) {
     const baseFromCtx = context?.workspaceRoot || context?.cwd || this.rootDir;
@@ -2892,7 +3356,7 @@ var AgentRegistry = class {
       systemPrompt: partial.systemPrompt,
       tools,
       temperature: partial.temperature ?? 0.7,
-      maxTokens: partial.maxTokens ?? 4e3,
+      maxTokens: partial.maxTokens ?? 64e3,
       provider: partial.provider,
       model: partial.model,
       topP: partial.topP,
@@ -3084,20 +3548,55 @@ ${agentList}`,
     };
   }
   /**
-   * Execute task delegation
+   * Delegate a task to a specialist agent for focused execution
+   *
+   * @param params - Agent ID and task description to delegate
+   * @param context - Execution context including delegation depth tracking
+   * @returns Delegation result with comprehensive metrics including cost breakdown
+   *
+   * @example
+   * ```typescript
+   * const result = await assignTool.execute({
+   *   agent: 'code-reviewer',
+   *   task: 'Review the changes in src/tools/*.ts',
+   *   description: 'Code review of tool implementations'
+   * });
+   * if (result.status === 'success' && result.type === 'text') {
+   *   console.log(result.result); // Agent's response
+   *   console.log(result.metadata.metrics?.totalCost); // Cost in USD
+   *   console.log(result.metadata.executionTimeMs); // Duration
+   *   console.log(result.metadata.toolCallsExecuted); // Number of tool calls
+   * }
+   * ```
    */
   async execute(params, context) {
     if (!params.agent || typeof params.agent !== "string") {
-      return err('Parameter "agent" is required and must be a string');
+      return err('Parameter "agent" is required and must be a string', void 0, "invalid_input" /* InvalidInput */);
     }
     if (!params.task || typeof params.task !== "string") {
-      return err('Parameter "task" is required and must be a string');
+      return err('Parameter "task" is required and must be a string', void 0, "invalid_input" /* InvalidInput */);
     }
     const outcome = await this.delegationService.delegate(params, context);
     if (!outcome.success || !outcome.summary) {
-      return err(outcome.error ?? "Failed to delegate task.");
+      const isNotFound = outcome.error?.includes("not found");
+      const isPolicyDenied = outcome.error?.includes("policy") || outcome.error?.includes("denied");
+      return err(
+        outcome.error ?? "Failed to delegate task.",
+        {
+          agentId: params.agent,
+          agentNotFound: isNotFound,
+          policyDenied: isPolicyDenied,
+          delegationDepth: context?.delegationDepth
+        },
+        "unknown" /* Unknown */
+      );
     }
-    return ok(outcome.summary, outcome.metadata);
+    const metadata = outcome.metadata;
+    return okText(outcome.summary, {
+      ...metadata,
+      taskDescription: params.task,
+      delegationDepth: (context?.delegationDepth ?? 0) + 1
+    });
   }
 };
 
@@ -3224,6 +3723,7 @@ var AgentManager = class {
         result: "Sub-agent execution aborted by user",
         metadata: {
           agentId,
+          agentName: config.agentName,
           toolCallsExecuted: 0,
           executionTimeMs: 0,
           errorMessage: "Aborted before execution"
@@ -3237,13 +3737,14 @@ var AgentManager = class {
         result: `Maximum delegation depth (${MAX_DELEGATION_DEPTH}) exceeded`,
         metadata: {
           agentId,
+          agentName: config.agentName,
           toolCallsExecuted: 0,
           executionTimeMs: Date.now() - startTime,
           errorMessage: "Max delegation depth exceeded"
         }
       };
     }
-    this.eventCallback?.({
+    await this.eventCallback?.({
       type: AgentEventTypes.SubAgentStarted,
       conversationId: config.conversationId ?? "default",
       messageId: config.messageId ?? "",
@@ -3262,7 +3763,7 @@ var AgentManager = class {
         events.push(event);
         if (event.type === AgentEventTypes.ToolCalls) {
           for (const toolCall of event.toolCalls) {
-            this.eventCallback?.({
+            await this.eventCallback?.({
               type: AgentEventTypes.SubAgentToolCall,
               conversationId: config.conversationId ?? "default",
               messageId: config.messageId ?? "",
@@ -3273,7 +3774,7 @@ var AgentManager = class {
             });
           }
         } else if (event.type === AgentEventTypes.ToolResult) {
-          this.eventCallback?.({
+          await this.eventCallback?.({
             type: AgentEventTypes.SubAgentToolResult,
             conversationId: config.conversationId ?? "default",
             messageId: config.messageId ?? "",
@@ -3300,6 +3801,16 @@ var AgentManager = class {
       // Specialists run autonomously
       reasoningEffort: freshConfig.reasoningEffort ?? this.delegatingConfig.reasoningEffort
     };
+    const metricsPort = new InMemoryMetricsPort((snapshot) => {
+      this.eventCallback?.({
+        type: AgentEventTypes.SubAgentMetrics,
+        conversationId: config.conversationId ?? "default",
+        messageId: config.messageId ?? "",
+        agentId: config.agentId,
+        toolCallId: config.toolCallId ?? "",
+        metrics: snapshot
+      });
+    });
     const llm = this.resolveLLM(config);
     const specialistOrchestrator = new AgentOrchestrator(specialistConfig, {
       memory,
@@ -3310,7 +3821,8 @@ var AgentManager = class {
       clock: new SystemClock(),
       cost: new SimpleCost(),
       reminders: new NoopReminders(),
-      events: eventPort
+      events: eventPort,
+      metrics: metricsPort
     });
     this.activeAgents.set(agentId, specialistOrchestrator);
     try {
@@ -3325,7 +3837,8 @@ var AgentManager = class {
           totalTokens += event.usage.total_tokens;
         }
       }
-      this.eventCallback?.({
+      const snapshot = metricsPort.getSnapshot();
+      await this.eventCallback?.({
         type: AgentEventTypes.SubAgentCompleted,
         conversationId: config.conversationId ?? "default",
         messageId: config.messageId ?? "",
@@ -3340,11 +3853,13 @@ var AgentManager = class {
         result: response.content || "",
         metadata: {
           agentId,
+          agentName: config.agentName,
           tokensUsed: totalTokens || response.metadata?.totalTokens,
           toolCallsExecuted,
           executionTimeMs,
           conversationHistory,
-          events
+          events,
+          metrics: snapshot
         }
       };
     } catch (error) {
@@ -3353,7 +3868,7 @@ var AgentManager = class {
       const isTimeout = error instanceof Error && error.message.includes("timeout");
       const isAborted = error instanceof Error && (error.message.includes("aborted") || error.name === "AbortError");
       const status = isTimeout ? "timeout" : isAborted ? "error" : "error";
-      this.eventCallback?.({
+      await this.eventCallback?.({
         type: AgentEventTypes.SubAgentCompleted,
         conversationId: config.conversationId ?? "default",
         messageId: config.messageId ?? "",
@@ -3368,6 +3883,7 @@ var AgentManager = class {
         result: errorMessage,
         metadata: {
           agentId,
+          agentName: config.agentName,
           toolCallsExecuted: events.filter((e) => e.type === "tool_calls").length,
           executionTimeMs,
           errorMessage,
@@ -3541,10 +4057,12 @@ var DefaultDelegationResultFormatter = class {
       summary: result.result,
       metadata: {
         agentId,
+        agentName: result.metadata.agentName,
         status: result.status,
         executionTimeMs: result.metadata.executionTimeMs,
         toolCallsExecuted: result.metadata.toolCallsExecuted,
-        tokensUsed: result.metadata.tokensUsed
+        tokensUsed: result.metadata.tokensUsed,
+        metrics: result.metadata.metrics
       }
     };
   }
@@ -3803,6 +4321,121 @@ var CompositeToolPort = class {
   }
 };
 
+// src/tools/tool-params.ts
+function parseToolArguments(args) {
+  if (typeof args === "string") {
+    try {
+      return JSON.parse(args);
+    } catch {
+      return {};
+    }
+  }
+  return args;
+}
+function isBashToolArgs(args) {
+  return "cmd" in args && typeof args.cmd === "string";
+}
+function isFileReadArgs(args) {
+  return "path" in args && typeof args.path === "string";
+}
+function isFileEditArgs(args) {
+  return "file_path" in args && "old_text" in args && "new_text" in args;
+}
+function isFileNewArgs(args) {
+  return "file_path" in args && "content" in args;
+}
+function isTodoWriteArgs(args) {
+  return "todos" in args && Array.isArray(args.todos);
+}
+function isAssignTaskArgs(args) {
+  return "agent" in args && "task" in args && "description" in args;
+}
+function isWebSearchArgs(args) {
+  return "query" in args && typeof args.query === "string";
+}
+function isWebFetchArgs(args) {
+  return "url" in args && typeof args.url === "string";
+}
+function isDirLsArgs(args) {
+  return !("cmd" in args) && !("url" in args) && !("query" in args) && !("todos" in args) && !("agent" in args) && !("file_path" in args) && !("content" in args);
+}
+
+// src/tools/type-guards.ts
+function isSuccess(result) {
+  return result.status === "success";
+}
+function isError(result) {
+  return result.status === "error";
+}
+function isTextResult(result) {
+  return result.type === "text";
+}
+function isJsonResult(result) {
+  return result.type === "json";
+}
+function isSuccessText(result) {
+  return result.status === "success" && result.type === "text";
+}
+function isSuccessJson(result) {
+  return result.status === "success" && result.type === "json";
+}
+
+// src/tools/tool-type-guards.ts
+function isBashResult(result) {
+  return result.name === "bash_tool";
+}
+function isBashSuccess(result) {
+  return result.name === "bash_tool" && result.status === "success" && result.type === "text";
+}
+function isFileReadResult(result) {
+  return result.name === "file_read";
+}
+function isFileReadSuccess(result) {
+  return result.name === "file_read" && result.status === "success" && result.type === "text";
+}
+function isFileEditResult(result) {
+  return result.name === "file_edit";
+}
+function isFileEditSuccess(result) {
+  return result.name === "file_edit" && result.status === "success" && result.type === "text";
+}
+function isFileNewResult(result) {
+  return result.name === "file_new";
+}
+function isFileNewSuccess(result) {
+  return result.name === "file_new" && result.status === "success" && result.type === "text";
+}
+function isDirLsResult(result) {
+  return result.name === "dir_ls";
+}
+function isDirLsSuccess(result) {
+  return result.name === "dir_ls" && result.status === "success" && result.type === "json";
+}
+function isWebSearchResult(result) {
+  return result.name === "web_search";
+}
+function isWebSearchSuccess(result) {
+  return result.name === "web_search" && result.status === "success" && result.type === "json";
+}
+function isWebFetchResult(result) {
+  return result.name === "web_fetch";
+}
+function isWebFetchSuccess(result) {
+  return result.name === "web_fetch" && result.status === "success" && result.type === "text";
+}
+function isTodoWriteResult(result) {
+  return result.name === "todo_write";
+}
+function isTodoWriteSuccess(result) {
+  return result.name === "todo_write" && result.status === "success" && result.type === "text";
+}
+function isAssignResult(result) {
+  return result.name === "assign_task";
+}
+function isAssignSuccess(result) {
+  return result.name === "assign_task" && result.status === "success" && result.type === "text";
+}
+
 // src/agent-file-persistence.ts
 import * as fs8 from "fs";
 import * as path7 from "path";
@@ -3927,6 +4560,16 @@ var AgentFilePersistence = class {
   }
 };
 
+// src/sub-agent-types.ts
+function parseSubAgentToolCallArguments(argsString) {
+  if (!argsString) return {};
+  try {
+    return JSON.parse(argsString);
+  } catch {
+    return {};
+  }
+}
+
 // src/llm-providers/llm-utils.ts
 function mergeChoices(choices) {
   const contentParts = [];
@@ -3984,9 +4627,11 @@ var BaseLLM = class {
   transport = null;
   apiUrl;
   enablePromptCaching = false;
+  retryConfig;
   constructor(apiUrl, options) {
     this.apiUrl = apiUrl;
     this.enablePromptCaching = options?.enablePromptCaching ?? false;
+    this.retryConfig = options?.retry;
   }
   transformUsage(rawUsage) {
     if (!rawUsage) return void 0;
@@ -4649,6 +5294,206 @@ function createTransport(inner, defaultBaseUrl, apiKey, baseUrl, version, custom
   return new SimpleBearerAuthTransport(inner, defaultBaseUrl, apiKey, baseUrl, version, customHeaders);
 }
 
+// src/transports/backoff.ts
+function calculateBackoff(attempt, baseDelayMs, maxDelayMs, multiplier, jitterFactor) {
+  const exponentialDelay = baseDelayMs * multiplier ** attempt;
+  const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+  const jitterRange = cappedDelay * jitterFactor;
+  const jitter = jitterRange * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(cappedDelay + jitter));
+}
+function parseRetryAfterHeader(header) {
+  if (!header) return null;
+  const seconds = parseInt(header, 10);
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return seconds * 1e3;
+  }
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) {
+    const delayMs = date - Date.now();
+    return delayMs > 0 ? delayMs : null;
+  }
+  return null;
+}
+
+// src/transports/error-classification.ts
+var DEFAULT_RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504];
+var RETRYABLE_NETWORK_ERRORS = [
+  "econnrefused",
+  "enotfound",
+  "etimedout",
+  "econnreset",
+  "epipe",
+  "network",
+  "fetch failed",
+  "socket hang up"
+];
+var NON_RETRYABLE_PATTERNS = [
+  "invalid",
+  "unauthorized",
+  "forbidden",
+  "not found",
+  "bad request",
+  "api key",
+  "authentication",
+  "permission",
+  "invalid_api_key",
+  "insufficient_quota"
+];
+function isRetryableStatusCode(status, retryableStatusCodes = DEFAULT_RETRYABLE_STATUS_CODES) {
+  return retryableStatusCodes.includes(status);
+}
+function isRetryableError(error, retryableStatusCodes = DEFAULT_RETRYABLE_STATUS_CODES) {
+  if (!error) return false;
+  if (error instanceof Error && error.name === "AbortError") {
+    return false;
+  }
+  if (error instanceof LLMError) {
+    if (error.statusCode) {
+      return isRetryableStatusCode(error.statusCode, retryableStatusCodes);
+    }
+    return error.isRetryable;
+  }
+  const err2 = error;
+  const statusCode = err2.statusCode ?? err2.status;
+  if (statusCode) {
+    return isRetryableStatusCode(statusCode, retryableStatusCodes);
+  }
+  const message = err2.message?.toLowerCase() || "";
+  const code = err2.code?.toLowerCase() || "";
+  for (const pattern of NON_RETRYABLE_PATTERNS) {
+    if (message.includes(pattern) || code.includes(pattern)) {
+      return false;
+    }
+  }
+  for (const networkError of RETRYABLE_NETWORK_ERRORS) {
+    if (message.includes(networkError) || code.includes(networkError)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/transports/retry-transport.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  baseDelayMs: 1e3,
+  maxDelayMs: 6e4,
+  backoffMultiplier: 2,
+  jitterFactor: 0.2,
+  retryableStatusCodes: [429, 500, 502, 503, 504]
+};
+var AbortError = class _AbortError extends Error {
+  constructor(message = "Operation aborted") {
+    super(message);
+    this.name = "AbortError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _AbortError);
+    }
+  }
+};
+var sleep = (ms, signal) => {
+  return new Promise((resolve6, reject) => {
+    if (signal?.aborted) {
+      reject(new AbortError("Operation aborted"));
+      return;
+    }
+    const timeout = setTimeout(resolve6, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timeout);
+        reject(new AbortError("Operation aborted during retry delay"));
+      },
+      { once: true }
+    );
+  });
+};
+var RetryTransport = class {
+  constructor(inner, config = {}) {
+    this.inner = inner;
+    this.config = { ...DEFAULT_RETRY_CONFIG, ...config };
+  }
+  config;
+  async get(url, headers, signal) {
+    return this.executeWithRetry(() => this.inner.get(url, headers, signal), signal);
+  }
+  async post(url, body, headers, signal) {
+    return this.executeWithRetry(() => this.inner.post(url, body, headers, signal), signal);
+  }
+  async executeWithRetry(fn, signal) {
+    let lastError;
+    let attempt = 0;
+    while (attempt <= this.config.maxRetries) {
+      if (signal?.aborted) {
+        throw new AbortError("Operation aborted before execution");
+      }
+      try {
+        const response = await fn();
+        if (this.isRetryableResponse(response)) {
+          const error = new Error(`HTTP ${response.status}`);
+          error.status = response.status;
+          if (attempt < this.config.maxRetries) {
+            const delayMs = this.getDelayForResponse(response, attempt);
+            this.config.onRetry?.(attempt + 1, error, delayMs);
+            await sleep(delayMs, signal);
+            attempt++;
+            continue;
+          }
+          lastError = error;
+          break;
+        }
+        return response;
+      } catch (error) {
+        if (error instanceof AbortError || error instanceof Error && error.name === "AbortError") {
+          throw error;
+        }
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (!isRetryableError(lastError, this.config.retryableStatusCodes)) {
+          throw lastError;
+        }
+        if (attempt < this.config.maxRetries) {
+          const delayMs = calculateBackoff(
+            attempt,
+            this.config.baseDelayMs,
+            this.config.maxDelayMs,
+            this.config.backoffMultiplier,
+            this.config.jitterFactor
+          );
+          this.config.onRetry?.(attempt + 1, lastError, delayMs);
+          await sleep(delayMs, signal);
+          attempt++;
+        } else {
+          break;
+        }
+      }
+    }
+    if (lastError) {
+      this.config.onExhausted?.(lastError, attempt + 1);
+      throw lastError;
+    }
+    throw new Error("Retry exhausted without error");
+  }
+  isRetryableResponse(response) {
+    return isRetryableStatusCode(response.status, this.config.retryableStatusCodes);
+  }
+  getDelayForResponse(response, attempt) {
+    const headers = "headers" in response && response.headers instanceof Headers ? response.headers : null;
+    const retryAfter = headers?.get("retry-after") ?? null;
+    const retryAfterMs = parseRetryAfterHeader(retryAfter);
+    if (retryAfterMs !== null) {
+      return Math.min(retryAfterMs, this.config.maxDelayMs);
+    }
+    return calculateBackoff(
+      attempt,
+      this.config.baseDelayMs,
+      this.config.maxDelayMs,
+      this.config.backoffMultiplier,
+      this.config.jitterFactor
+    );
+  }
+};
+
 // src/llm-providers/model-limits.ts
 function normalizeModelLimits(provider, model) {
   switch (provider.toLowerCase()) {
@@ -4766,7 +5611,7 @@ function normalizeModelInfo(provider, model) {
 var GithubLLM = class extends BaseLLM {
   opts;
   constructor(opts = {}) {
-    super(opts.apiUrl ?? "https://api.individual.githubcopilot.com");
+    super(opts.apiUrl ?? "https://api.individual.githubcopilot.com", { retry: opts.retry });
     this.opts = opts;
   }
   createTransport() {
@@ -4777,11 +5622,15 @@ var GithubLLM = class extends BaseLLM {
       maxFileSize: 5 * 1024 * 1024,
       captureResponseBody: true
     });
-    return new GithubAuthTransport(base, {
+    const authTransport = new GithubAuthTransport(base, {
       baseUrl: this.opts.apiUrl,
       apiKey: this.opts.apiKey,
       accessToken: this.opts.accessToken
     });
+    if (this.retryConfig) {
+      return new RetryTransport(authTransport, this.retryConfig);
+    }
+    return authTransport;
   }
   transformUsage(rawUsage) {
     if (!rawUsage) return void 0;
@@ -5400,8 +6249,8 @@ var GenericLLM = class extends BaseLLM {
   providerName;
   customHeaders;
   constructor(baseUrl, modelConfig, opts = {}, customHeaders) {
-    const { enablePromptCaching = false, includeUsage = false, providerName = "unknown", ...restOpts } = opts;
-    super(opts.apiUrl || baseUrl, { enablePromptCaching });
+    const { enablePromptCaching = false, includeUsage = false, providerName = "unknown", retry, ...restOpts } = opts;
+    super(opts.apiUrl || baseUrl, { enablePromptCaching, retry });
     this.includeUsage = includeUsage;
     this.modelConfig = modelConfig;
     this.providerName = providerName;
@@ -5416,7 +6265,7 @@ var GenericLLM = class extends BaseLLM {
       maxFileSize: 5 * 1024 * 1024,
       captureResponseBody: true
     });
-    return createTransport(
+    const authTransport = createTransport(
       base,
       this.apiUrl,
       this.opts.apiKey,
@@ -5424,6 +6273,10 @@ var GenericLLM = class extends BaseLLM {
       this.opts.version,
       this.customHeaders
     );
+    if (this.retryConfig) {
+      return new RetryTransport(authTransport, this.retryConfig);
+    }
+    return authTransport;
   }
   async getModels(signal) {
     if (this.modelConfig === false) {
@@ -5731,7 +6584,11 @@ var MCPToolPort = class {
           try {
             const res = await this.client.callTool({ name: original, arguments: c.parameters || {} });
             const flat = flattenMcpContent(res.content);
-            return { id: c.id, name: c.name, status: "success", type: flat.type, result: flat.value };
+            if (flat.type === "text") {
+              return { id: c.id, name: c.name, status: "success", type: "text", result: flat.value };
+            } else {
+              return { id: c.id, name: c.name, status: "success", type: "json", result: flat.value };
+            }
           } catch (err2) {
             const message = err2 instanceof Error ? err2.message : String(err2);
             return { id: c.id, name: c.name, status: "error", type: "text", result: message };
@@ -5810,6 +6667,7 @@ function isValidConfig(value) {
 }
 export {
   AGENT_CREATOR_SYSTEM_PROMPT,
+  AbortError,
   AgentEventTypes,
   AgentFilePersistence,
   AgentManager,
@@ -5822,6 +6680,7 @@ export {
   ConversationContext,
   ConversationStore,
   CoreMCPClient,
+  DEFAULT_RETRY_CONFIG,
   DefaultDelegationPolicy,
   DefaultDelegationResultFormatter,
   DefaultDelegationService,
@@ -5841,6 +6700,7 @@ export {
   NoopReminders,
   PersistedMemory,
   PersistingConsoleEventPort,
+  RetryTransport,
   RuntimeEnv,
   SimpleContextBuilder,
   SimpleCost,
@@ -5850,19 +6710,63 @@ export {
   buildAgentCreationPrompt,
   buildInjectedSystem,
   canonicalizeTerminalPaste,
+  convertToolCall,
+  convertToolCalls,
   createEmptySnapshot,
   createLLM,
+  err,
   generateFolderTree,
   getAvailableProviders,
   getFallbackLimits,
   getProviderLabel,
+  isAssignResult,
+  isAssignSuccess,
+  isAssignTaskArgs,
+  isBashResult,
+  isBashSuccess,
+  isBashToolArgs,
+  isDirLsArgs,
+  isDirLsResult,
+  isDirLsSuccess,
+  isError,
+  isFileEditArgs,
+  isFileEditResult,
+  isFileEditSuccess,
+  isFileNewArgs,
+  isFileNewResult,
+  isFileNewSuccess,
+  isFileReadArgs,
+  isFileReadResult,
+  isFileReadSuccess,
+  isJsonResult,
+  isRetryableError,
+  isRetryableStatusCode,
+  isSuccess,
+  isSuccessJson,
+  isSuccessText,
+  isTextResult,
+  isTodoWriteArgs,
+  isTodoWriteResult,
+  isTodoWriteSuccess,
+  isWebFetchArgs,
+  isWebFetchResult,
+  isWebFetchSuccess,
+  isWebSearchArgs,
+  isWebSearchResult,
+  isWebSearchSuccess,
   loadMCPConfig,
   normalizeModelInfo,
   normalizeModelLimits,
   normalizeNewlines,
+  okJson,
+  okText,
+  parseJSON,
+  parseSubAgentToolCallArguments,
+  parseToolArguments,
   renderTemplate,
   resolveBackspaces,
   resolveCarriageReturns,
   stripAnsiAndControls,
-  supportsGetModels
+  supportsGetModels,
+  toolValidators
 };