@johpaz/hive-sdk 0.1.4 → 0.1.6

package/packages/core/src/tools/cron/index.ts

@@ -9,8 +9,9 @@
  */
 
 import type { Tool } from "../types";
-import { getDb } from "../../storage/SQLiteStorage.ts";
-import { logger } from "../../utils/logger.ts";
+import { col, toIndexable } from "../../storage/hive";
+import type { UserDoc, UserIdentityDoc, ChannelDoc, CronJobDoc, TaskRunDoc } from "../../storage/collections";
+import { logger } from "../../utils/logger";
 import { Cron } from "croner";
 
 const log = logger.child("CronTools");
@@ -25,59 +26,71 @@ export function getSchedulerInstance(): any {
   return _scheduler;
 }
 
-function getUserTimezone(): string {
-  const db = getDb();
-  const user = db.query("SELECT timezone FROM users LIMIT 1").get() as { timezone: string } | undefined;
-  return user?.timezone || "UTC";
+async function getUserTimezone(): Promise<string> {
+  const usersCol = await col<UserDoc>("users");
+  const userEntry = (await usersCol.scan({ limit: 1 }))[0];
+  return userEntry?.doc.timezone || "UTC";
 }
 
-export function resolveBestChannel(userId: string, explicitChannel?: string): string {
-  const db = getDb();
-
-  const user = db.query("SELECT preferred_cron_channel FROM users WHERE id = ? LIMIT 1").get(userId) as {
-    preferred_cron_channel: string;
-  } | undefined;
+export async function resolveBestChannel(userId: string, explicitChannel?: string): Promise<string> {
+  const usersCol = await col<UserDoc>("users");
+  const userEntry = await usersCol.get(userId);
+  const preferredCronChannel = userEntry?.doc.preferred_cron_channel;
+
+  const identitiesCol = await col<UserIdentityDoc>("userIdentities");
+  const identityEntries = await identitiesCol.scan({ prefix: `${userId}:` });
+  const allIdentityChannels = identityEntries.map(e => e.doc.channel);
+
+  const channelsCol = await col<ChannelDoc>("channels");
+  const activeChannels: string[] = [];
+  for (const channel of new Set(allIdentityChannels)) {
+    const channelEntry = await channelsCol.get(channel);
+    if (channelEntry?.doc.active && channelEntry.doc.status === "connected") {
+      activeChannels.push(channel);
+    }
+  }
 
-  const activeChannels = db.query(`
-    SELECT ui.channel FROM user_identities ui
-    JOIN channels c ON c.id = ui.channel
-    WHERE ui.user_id = ? AND c.active = 1 AND c.status = 'connected'
-  `).all(userId) as { channel: string }[];
+  log.debug(`[resolveBestChannel] userId=${userId}, explicit=${explicitChannel}, preferred=${preferredCronChannel}, activeChannels=[${activeChannels.join(", ")}]`);
 
-  const identities = activeChannels.length > 0
-    ? activeChannels
-    : db.query("SELECT channel FROM user_identities WHERE user_id = ?").all(userId) as { channel: string }[];
+  const identities = activeChannels.length > 0 ? activeChannels : allIdentityChannels;
 
   if (identities.length === 0) {
+    log.warn(`[resolveBestChannel] No identities found for user ${userId}, falling back to webchat`);
     return "webchat";
   }
 
   let bestChannel = "";
 
   if (explicitChannel && explicitChannel !== "system") {
-    if (identities.some((i) => i.channel === explicitChannel)) {
+    if (identities.includes(explicitChannel)) {
       bestChannel = explicitChannel;
+      log.info(`[resolveBestChannel] Using explicit channel: ${bestChannel}`);
     }
   }
 
-  if (!bestChannel && user?.preferred_cron_channel && user.preferred_cron_channel !== "auto") {
-    if (identities.some((i) => i.channel === user.preferred_cron_channel)) {
-      bestChannel = user.preferred_cron_channel;
+  if (!bestChannel && preferredCronChannel && preferredCronChannel !== "auto") {
+    if (identities.includes(preferredCronChannel)) {
+      bestChannel = preferredCronChannel;
+      log.info(`[resolveBestChannel] Using preferred_cron_channel: ${bestChannel}`);
+    } else {
+      log.warn(`[resolveBestChannel] preferred_cron_channel=${preferredCronChannel} not in identities=[${identities.join(", ")}]`);
     }
   }
 
   if (!bestChannel) {
     const preferred = ["telegram", "discord", "slack", "whatsapp", "webchat"];
     for (const p of preferred) {
-      if (identities.some((i) => i.channel === p)) {
+      if (identities.includes(p)) {
         bestChannel = p;
+        log.info(`[resolveBestChannel] Using fallback priority: ${bestChannel}`);
         break;
       }
     }
   }
 
   if (!bestChannel) {
-    bestChannel = identities[0].channel;
+    bestChannel = identities[0];
+    log.info(`[resolveBestChannel] Using first identity: ${bestChannel}`);
   }
 
   return bestChannel;
@@ -87,7 +100,7 @@ export function resolveBestChannel(userId: string, explicitChannel?: string): st
 
 export const cronCreateTool: Tool = {
   name: "cron.create",
-  description: "Create a new cron job. Use for recurring reminders, daily reports, automated checks. Spanish: crear tarea programada, agendar recordatorio, programar reporte",
+  description: "Create a Hive scheduled automation: a recurring cron job or one-shot future execution. Spanish: crear automatización programada, programar tarea recurrente, ejecutar después, programar reporte",
   parameters: {
     type: "object",
     properties: {
@@ -108,7 +121,7 @@ export const cronCreateTool: Tool = {
     required: ["name", "task", "task_type"],
   },
   execute: async (params: Record<string, unknown>) => {
-    const timezone = getUserTimezone();
+    const timezone = await getUserTimezone();
 
     const name = params.name as string | undefined;
     const task = params.task as string | undefined;
@@ -165,7 +178,7 @@ export const cronCreateTool: Tool = {
 
     try {
       if (_scheduler) {
-        const result = _scheduler.create({
+        const result = await _scheduler.create({
           name,
           task,
           task_type,
@@ -191,24 +204,36 @@ export const cronCreateTool: Tool = {
           message: `Job "${name}" scheduled. Next run: ${result.nextRun ? new Date(result.nextRun).toLocaleString() : "unknown"}`,
         };
       } else {
-        const db = getDb();
+        const cronJobsCol = await col<CronJobDoc>("cronJobs");
         const id = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
         const now = new Date().toISOString();
         const payloadJson = JSON.stringify(payloadObj || { prompt: task });
 
-        db.query(`
-          INSERT INTO cron_jobs (
-            id, name, task, task_type, cron_expression, fire_at, timezone,
-            start_at, stop_at, dom_and_dow,
-            payload, agent_id, tool_name, max_runs, channel,
-            status, created_at, updated_at
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)
-        `).run(
-          id, name, task, task_type, cron_expression || null, fire_at || null, timezone,
-          start_at || null, stop_at || null, dom_and_dow ? 1 : 0,
-          payloadJson, agent_id || null, tool_name || null, max_runs || null, channel,
-          now, now
-        );
+        await cronJobsCol.put(id, {
+          id, name, task, task_type,
+          cron_expression: cron_expression || null,
+          fire_at: fire_at || null,
+          timezone,
+          start_at: start_at || null,
+          stop_at: stop_at || null,
+          dom_and_dow: dom_and_dow ? 1 : 0,
+          max_runs: max_runs || null,
+          protect: 1,
+          interval_sec: null,
+          agent_id: toIndexable(agent_id || null),
+          channel,
+          payload: payloadJson,
+          tool_name: tool_name || null,
+          status: "active",
+          run_count: 0,
+          error_count: 0,
+          last_error: null,
+          created_at: now,
+          updated_at: now,
+          last_run_at: null,
+          next_run_at: null,
+          completed_at: null,
+        }, { expectedVersion: 0 });
 
         return {
           ok: true,
@@ -236,28 +261,17 @@ export const cronListTool: Tool = {
     },
   },
   execute: async (params: Record<string, unknown>) => {
-    const db = getDb();
-
     const status = params.status as string | undefined;
     const task_type = params.task_type as string | undefined;
 
     try {
-      let query = "SELECT * FROM cron_jobs WHERE 1=1";
-      const args: any[] = [];
-
-      if (status) {
-        query += " AND status = ?";
-        args.push(status);
-      }
+      const cronJobsCol = await col<CronJobDoc>("cronJobs");
+      let tasks = (await cronJobsCol.scan({})).map(e => e.doc);
 
-      if (task_type) {
-        query += " AND task_type = ?";
-        args.push(task_type);
-      }
+      if (status) tasks = tasks.filter(t => t.status === status);
+      if (task_type) tasks = tasks.filter(t => t.task_type === task_type);
 
-      query += " ORDER BY next_run_at ASC";
-
-      const tasks = db.query(query).all(...args) as any[];
+      tasks.sort((a, b) => (a.next_run_at ?? "").localeCompare(b.next_run_at ?? ""));
 
       return {
         ok: true,
@@ -336,42 +350,40 @@ export const cronUpdateTool: Tool = {
 
     try {
       if (_scheduler) {
-        const success = _scheduler.update(task_id, changes);
+        const success = await _scheduler.update(task_id, changes);
         if (success) {
           return { ok: true, message: `Job "${task_id}" updated` };
         } else {
           return { ok: false, error: `Job "${task_id}" not found` };
         }
       } else {
-        const db = getDb();
-        const fields: string[] = [];
-        const values: any[] = [];
-
-        if (changes.name !== undefined) { fields.push("name = ?"); values.push(changes.name); }
-        if (changes.task !== undefined) { fields.push("task = ?"); values.push(changes.task); }
-        if (changes.cron_expression !== undefined) { fields.push("cron_expression = ?"); values.push(changes.cron_expression); }
-        if (changes.fire_at !== undefined) { fields.push("fire_at = ?"); values.push(changes.fire_at); }
-        if (changes.payload !== undefined) { fields.push("payload = ?"); values.push(JSON.stringify(changes.payload)); }
-        if (changes.channel !== undefined) { fields.push("channel = ?"); values.push(changes.channel); }
-        if (changes.max_runs !== undefined) { fields.push("max_runs = ?"); values.push(changes.max_runs); }
-        if (changes.start_at !== undefined) { fields.push("start_at = ?"); values.push(changes.start_at); }
-        if (changes.stop_at !== undefined) { fields.push("stop_at = ?"); values.push(changes.stop_at); }
-        if (changes.dom_and_dow !== undefined) { fields.push("dom_and_dow = ?"); values.push(changes.dom_and_dow ? 1 : 0); }
-        if (changes.agent_id !== undefined) { fields.push("agent_id = ?"); values.push(changes.agent_id); }
-        if (changes.tool_name !== undefined) { fields.push("tool_name = ?"); values.push(changes.tool_name); }
-
-        if (fields.length === 0) {
+        const cronJobsCol = await col<CronJobDoc>("cronJobs");
+        const existing = await cronJobsCol.get(task_id);
+        if (!existing) {
+          return { ok: false, error: `Job "${task_id}" not found` };
+        }
+
+        const patch: Partial<CronJobDoc> = {};
+        if (changes.name !== undefined) patch.name = changes.name as string;
+        if (changes.task !== undefined) patch.task = changes.task as string;
+        if (changes.cron_expression !== undefined) patch.cron_expression = changes.cron_expression as string;
+        if (changes.fire_at !== undefined) patch.fire_at = changes.fire_at as string;
+        if (changes.payload !== undefined) patch.payload = JSON.stringify(changes.payload);
+        if (changes.channel !== undefined) patch.channel = changes.channel as string;
+        if (changes.max_runs !== undefined) patch.max_runs = changes.max_runs as number;
+        if (changes.start_at !== undefined) patch.start_at = changes.start_at as string;
+        if (changes.stop_at !== undefined) patch.stop_at = changes.stop_at as string;
+        if (changes.dom_and_dow !== undefined) patch.dom_and_dow = changes.dom_and_dow ? 1 : 0;
+        if (changes.agent_id !== undefined) patch.agent_id = toIndexable(changes.agent_id as string);
+        if (changes.tool_name !== undefined) patch.tool_name = changes.tool_name as string;
+
+        if (Object.keys(patch).length === 0) {
           return { ok: true, message: "No changes to apply" };
         }
 
-        values.push(task_id);
-        const result = db.query(`UPDATE cron_jobs SET ${fields.join(", ")} WHERE id = ?`).run(...values);
+        await cronJobsCol.put(task_id, { ...existing.doc, ...patch }, { expectedVersion: existing.version });
 
-        if (result.changes > 0) {
-          return { ok: true, message: `Job "${task_id}" updated (scheduler not active)` };
-        } else {
-          return { ok: false, error: `Job "${task_id}" not found` };
-        }
+        return { ok: true, message: `Job "${task_id}" updated (scheduler not active)` };
       }
     } catch (err) {
       log.error(`[update] Failed: ${(err as Error).message}`);
@@ -401,23 +413,20 @@ export const cronPauseTool: Tool = {
 
     try {
       if (_scheduler) {
-        const success = _scheduler.pause(task_id);
+        const success = await _scheduler.pause(task_id);
         if (success) {
           return { ok: true, message: `Job "${task_id}" paused` };
         } else {
           return { ok: false, error: `Job "${task_id}" not found or already paused` };
         }
       } else {
-        const db = getDb();
-        const result = db.query(
-          "UPDATE cron_jobs SET status = 'paused' WHERE id = ?"
-        ).run(task_id);
-
-        if (result.changes > 0) {
-          return { ok: true, message: `Job "${task_id}" paused (scheduler not active)` };
-        } else {
+        const cronJobsCol = await col<CronJobDoc>("cronJobs");
+        const existing = await cronJobsCol.get(task_id);
+        if (!existing) {
           return { ok: false, error: `Job "${task_id}" not found` };
         }
+        await cronJobsCol.put(task_id, { ...existing.doc, status: "paused" }, { expectedVersion: existing.version });
+        return { ok: true, message: `Job "${task_id}" paused (scheduler not active)` };
       }
     } catch (err) {
       log.error(`[pause] Failed: ${(err as Error).message}`);
@@ -447,23 +456,20 @@ export const cronResumeTool: Tool = {
 
     try {
       if (_scheduler) {
-        const success = _scheduler.resume(task_id);
+        const success = await _scheduler.resume(task_id);
         if (success) {
           return { ok: true, message: `Job "${task_id}" resumed` };
         } else {
           return { ok: false, error: `Job "${task_id}" not found or already active` };
         }
       } else {
-        const db = getDb();
-        const result = db.query(
-          "UPDATE cron_jobs SET status = 'active' WHERE id = ?"
-        ).run(task_id);
-
-        if (result.changes > 0) {
-          return { ok: true, message: `Job "${task_id}" resumed (scheduler not active)` };
-        } else {
+        const cronJobsCol = await col<CronJobDoc>("cronJobs");
+        const existing = await cronJobsCol.get(task_id);
+        if (!existing) {
           return { ok: false, error: `Job "${task_id}" not found` };
         }
+        await cronJobsCol.put(task_id, { ...existing.doc, status: "active" }, { expectedVersion: existing.version });
+        return { ok: true, message: `Job "${task_id}" resumed (scheduler not active)` };
       }
     } catch (err) {
       log.error(`[resume] Failed: ${(err as Error).message}`);
@@ -493,23 +499,20 @@ export const cronDeleteTool: Tool = {
 
     try {
       if (_scheduler) {
-        const success = _scheduler.delete(task_id);
+        const success = await _scheduler.delete(task_id);
         if (success) {
           return { ok: true, message: `Job "${task_id}" deleted` };
         } else {
           return { ok: false, error: `Job "${task_id}" not found` };
         }
       } else {
-        const db = getDb();
-        const result = db.query(
-          "DELETE FROM cron_jobs WHERE id = ?"
-        ).run(task_id);
-
-        if (result.changes > 0) {
-          return { ok: true, message: `Job "${task_id}" deleted (scheduler not active)` };
-        } else {
+        const cronJobsCol = await col<CronJobDoc>("cronJobs");
+        const existing = await cronJobsCol.get(task_id);
+        if (!existing) {
           return { ok: false, error: `Job "${task_id}" not found` };
         }
+        await cronJobsCol.delete(task_id);
+        return { ok: true, message: `Job "${task_id}" deleted (scheduler not active)` };
       }
     } catch (err) {
       log.error(`[delete] Failed: ${(err as Error).message}`);
@@ -577,13 +580,12 @@ export const cronHistoryTool: Tool = {
     }
 
     try {
-      const db = getDb();
-      const runs = db.query(`
-        SELECT * FROM task_runs
-        WHERE task_id = ?
-        ORDER BY started_at DESC
-        LIMIT ?
-      `).all(task_id, limit) as any[];
+      const taskRunsCol = await col<TaskRunDoc>("taskRuns");
+      const runs = (await taskRunsCol.scan({}))
+        .map(e => e.doc)
+        .filter(r => r.task_id === task_id)
+        .sort((a, b) => b.started_at.localeCompare(a.started_at))
+        .slice(0, limit);
 
       return {
         ok: true,
@@ -619,8 +621,3 @@ export function createTools(): Tool[] {
     cronHistoryTool,
   ];
 }
-
-/**
- * Alias for backward compatibility
- */
-export const createCronTools = createTools;

package/packages/core/src/tools/index.ts

@@ -1,6 +1,6 @@
 /**
- * Tools Registry - Exports all 66 tools
- * 
+ * Tools Registry
+ *
  * Import this to get all tools:
  * import { createAllTools } from "./tools";
  */
@@ -11,29 +11,20 @@ import type { Config } from "../config/loader.ts";
 // Filesystem (7)
 import * as filesystem from "./filesystem/index.ts";
 
-// Web (9)
+// Web (10)
 import * as web from "./web/index.ts";
 
-// Projects (8)
-import * as projects from "./projects/index.ts";
-
-// Cron (7) - Croner-based scheduler tools
+// Cron (8) - Croner-based scheduler tools
 import * as cron from "./cron/index.ts";
 
 // CLI (1)
 import * as cli from "./cli/index.ts";
 
-// Agents (14)
+// Agents (15)
 import * as agents from "./agents/index.ts";
 
-// Canvas (7)
-import * as canvas from "./canvas/index.ts";
-
-// Codebridge (3)
-import * as codebridge from "./codebridge/index.ts";
-
-// Voice (2)
-import * as voice from "./voice/index.ts";
+// A2UI (4)
+import * as a2ui from "./a2ui/index.ts";
 
 // Core (4)
 import * as core from "./core/index.ts";
@@ -41,40 +32,56 @@ import * as core from "./core/index.ts";
 // Office (8)
 import * as office from "./office/index.ts";
 
-// Meeting (4)
-import * as meeting from "./meeting/index.ts";
+// API (1) - HTTP client for REST APIs
+import * as api from "./api/index.ts";
+
+// ─── Tools de la aplicación ──────────────────────────────────────────────────
+//
+// Punto de extensión propio del SDK: hive trae todas sus tools compiladas, pero
+// acá `defineTool()` existe justamente para que la app aporte las suyas. Sin
+// esto, una tool de usuario sólo se le podía anunciar al modelo (via
+// `extraTools` del agent loop) pero no tenía ejecutor asociado, así que la
+// llamada moría con "no matching executor found in allTools".
+
+const appTools = new Map<string, Tool>();
+
+/** Registra una tool de la aplicación para que entre en el loadout del agente. */
+export function registerAppTool(tool: Tool): void {
+  appTools.set(tool.name, tool);
+}
+
+/** Quita todas las tools registradas por la app (útil entre tests). */
+export function clearAppTools(): void {
+  appTools.clear();
+}
+
+/** Tools registradas por la app, en orden de registro. */
+export function listAppTools(): Tool[] {
+  return Array.from(appTools.values());
+}
 
 /**
- * Creates all 70 tools with proper configuration
+ * Creates all tools with proper configuration
  */
 export function createAllTools(config: Config): Tool[] {
   return [
     // FILESYSTEM (7)
     ...filesystem.createTools(),
 
-    // WEB (9)
+    // WEB (10)
     ...web.createTools(),
 
-    // PROJECTS (8)
-    ...projects.createTools(),
-
-    // CRON (7)
+    // CRON (8)
     ...cron.createTools(),
 
     // CLI (1)
     ...cli.createTools(),
 
-    // AGENTS (14)
+    // AGENTS (15)
     ...agents.createTools(),
 
-    // CANVAS (7 + A2UI 4)
-    ...canvas.createTools(config),
-
-    // CODEBRIDGE (3)
-    ...codebridge.createTools(),
-
-    // VOICE (2)
-    ...voice.createTools(),
+    // A2UI (4)
+    ...a2ui.createTools(config),
 
     // CORE (4)
     ...core.createTools(),
@@ -82,8 +89,13 @@ export function createAllTools(config: Config): Tool[] {
     // OFFICE (8)
     ...office.createTools(),
 
-    // MEETING (4)
-    ...meeting.createTools(),
+    // API (1)
+    ...api.createTools(),
+
+    // Las de la app van últimas: si una comparte nombre con una nativa, gana la
+    // nativa, porque el selector busca por nombre y no queremos que registrar
+    // una tool desde afuera secuestre `fs_read` o `task_delegate`.
+    ...listAppTools(),
   ];
 }
 
@@ -96,26 +108,20 @@ export function createToolsByCategory(category: string, config: Config): Tool[]
       return filesystem.createTools();
     case "web":
       return web.createTools();
-    case "projects":
-      return projects.createTools();
     case "cron":
       return cron.createTools();
     case "cli":
       return cli.createTools();
     case "agents":
       return agents.createTools();
-    case "canvas":
-      return canvas.createTools(config);
-    case "codebridge":
-      return codebridge.createTools();
-    case "voice":
-      return voice.createTools();
+    case "a2ui":
+      return a2ui.createTools(config);
     case "core":
       return core.createTools();
     case "office":
       return office.createTools();
-    case "meeting":
-      return meeting.createTools();
+    case "api":
+      return api.createTools();
     default:
       return [];
   }
@@ -139,7 +145,6 @@ export {
 export {
   webSearchTool,
   webFetchTool,
-  apiRequestTool,
   browserNavigateTool,
   browserScreenshotTool,
   browserClickTool,
@@ -147,19 +152,9 @@ export {
   browserExtractTool,
   browserScriptTool,
   browserWaitTool,
+  artifactInspectTool,
 } from "./web/index.ts";
 
-export {
-  projectCreateTool,
-  projectListTool,
-  projectUpdateTool,
-  projectDoneTool,
-  projectFailTool,
-  taskCreateTool,
-  taskUpdateTool,
-  taskEvaluateTool,
-} from "./projects/index.ts";
-
 export {
   cronCreateTool,
   cronListTool,
@@ -185,33 +180,19 @@ export {
   agentFindTool,
   agentArchiveTool,
   taskDelegateTool,
-  taskDelegateCodeTool,
+  taskReviseTool,
+  taskListTool,
   taskStatusTool,
   busPublishTool,
   busReadTool,
-  projectUpdatesTool,
 } from "./agents/index.ts";
 
 export {
-  canvasRenderTool,
-  canvasAskTool,
-  canvasConfirmTool,
-  canvasShowCardTool,
-  canvasShowProgressTool,
-  canvasShowListTool,
-  canvasClearTool,
-} from "./canvas/index.ts";
-
-export {
-  codebridgeLaunchTool,
-  codebridgeStatusTool,
-  codebridgeCancelTool,
-} from "./codebridge/index.ts";
-
-export {
-  voiceTranscribeTool,
-  voiceSpeakTool,
-} from "./voice/index.ts";
+  createA2UISurfaceTool,
+  createA2UIUpdateComponentsTool,
+  createA2UIUpdateDataModelTool,
+  createA2UIDeleteSurfaceTool,
+} from "./a2ui/index.ts";
 
 export {
   searchKnowledgeTool,
@@ -230,3 +211,7 @@ export {
   officeLeerPptxTool,
   officeEscribirPptxTool,
 } from "./office/index.ts";
+
+export {
+  apiRequestTool,
+} from "./api/index.ts";

package/packages/core/src/tools/office/office-escribir-xlsx.ts

@@ -38,7 +38,9 @@ export const officeEscribirXlsxTool: Tool = {
           type: "object",
           properties: {
             nombre: { type: "string" },
-            datos: { type: "array" },
+            // datos puede ser array de objetos o array de arrays (aoa) — el tool
+            // acepta ambos en runtime (ver Array.isArray(datos[0]) más abajo).
+            datos: { type: "array", items: { type: "object" } },
             encabezados: { type: "array", items: { type: "string" } },
           },
         },

package/packages/core/src/tools/types.ts

@@ -2,7 +2,7 @@
  * Tool Type Definitions
  * Shared across all tool categories
  * 
- * These types are used by all 52 native tools in Hive
+ * These types are shared by every native tool in Hive.
  */
 
 export interface Tool {
@@ -13,6 +13,8 @@ export interface Tool {
     properties: Record<string, ToolParameter>;
     required?: string[];
   };
+  /** Per-tool timeout (ms) override. Falls back to config.tools.timeouts[name] → workerPool.toolTimeoutMs. */
+  timeoutMs?: number;
   execute: (
     params: Record<string, unknown>,
     config?: any