@within-7/minto 0.3.9 → 0.4.0

package/dist/Tool.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/Tool.ts"],
-  "sourcesContent": ["import { z } from 'zod'\nimport * as React from 'react'\nimport type { UserQuestion, UserAnswer } from './types/askUserQuestion'\nimport type {\n  ToolUseOptions,\n  ResponseState,\n  ValidationResult as CoreValidationResult,\n} from './types/core'\n\n/**\n * Core Tool interface for Minto's extensible tool system\n * Provides standardized contract for all tool implementations\n *\n * IMPORTANT: Tool descriptions can be either:\n * - A string (synchronous, preferred for adapters)\n * - An async function (for dynamic descriptions)\n * - An async function that accepts input (for context-aware descriptions)\n *\n * Use getToolDescription() helper for safe synchronous access.\n */\n\nexport type SetToolJSXFn = (\n  jsx: {\n    jsx: React.ReactNode | null\n    shouldHidePromptInput: boolean\n  } | null,\n) => void\n\n/**\n * Function type for asking the user questions\n */\nexport type AskUserFn = (questions: UserQuestion[]) => Promise<UserAnswer[]>\n\nexport interface ToolUseContext {\n  messageId: string | undefined\n  agentId?: string\n  /** The tool_use ID from the API (for tracking concurrent executions) */\n  toolUseId?: string\n  safeMode?: boolean\n  abortController: AbortController\n  readFileTimestamps: { [filePath: string]: number }\n  options?: ToolUseOptions\n  responseState?: ResponseState\n}\n\nexport interface ExtendedToolUseContext extends ToolUseContext {\n  setToolJSX: SetToolJSXFn\n  askUser?: AskUserFn\n}\n\n// Re-export for backward compatibility\nexport type ValidationResult = CoreValidationResult\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface Tool<\n  TInput extends z.ZodObject<any> = z.ZodObject<any>,\n  TOutput = any,\n> {\n  name: string\n  /**\n   * Tool description - can be:\n   * - A string (synchronous, best for adapters)\n   * - An async function returning string (for dynamic descriptions)\n   * - An async function accepting input (for context-aware descriptions)\n   *\n   * Use getToolDescription() for safe synchronous access in adapters.\n   */\n  description?: string | ((input?: z.infer<TInput>) => Promise<string>)\n  /**\n   * Cached description for synchronous access.\n   * Populated by cacheToolDescriptions() at startup.\n   */\n  cachedDescription?: string\n  inputSchema: TInput\n  inputJSONSchema?: Record<string, unknown>\n  prompt: (options?: { safeMode?: boolean }) => Promise<string>\n  /**\n   * User-facing name for display. Can optionally accept input for context.\n   */\n  userFacingName?: (input?: z.infer<TInput>) => string\n  isEnabled: () => Promise<boolean>\n  /**\n   * Whether this tool only reads data (no side effects).\n   * Can optionally accept input to determine based on parameters.\n   */\n  isReadOnly: (input?: z.infer<TInput>) => boolean\n  /**\n   * Whether this tool is safe to run concurrently with other tools.\n   * Can optionally accept input to determine based on parameters.\n   */\n  isConcurrencySafe: (input?: z.infer<TInput>) => boolean\n  needsPermissions: (input?: z.infer<TInput>) => boolean\n  /**\n   * Whether this tool requires user interaction (e.g., confirmation dialogs).\n   */\n  requiresUserInteraction?: (input?: z.infer<TInput>) => boolean\n  validateInput?: (\n    input: z.infer<TInput>,\n    context?: ToolUseContext,\n  ) => Promise<ValidationResult>\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  renderResultForAssistant: (output: TOutput) => string | any[]\n  renderToolUseMessage: (\n    input: z.infer<TInput>,\n    options: { verbose: boolean },\n  ) => string | React.ReactElement | null\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  renderToolUseRejectedMessage?: (...args: any[]) => React.ReactElement | null\n  /**\n   * Render the tool result for display.\n   * @param output - The tool output\n   * @param options - Rendering options including verbose mode\n   */\n  renderToolResultMessage?: (\n    output: TOutput,\n    options?: { verbose: boolean },\n  ) => React.ReactNode\n  call: (\n    input: z.infer<TInput>,\n    context: ToolUseContext,\n  ) => AsyncGenerator<\n    | {\n        type: 'result'\n        data: TOutput\n        resultForAssistant?: string | any[]\n        /**\n         * New messages to add to the conversation\n         */\n        newMessages?: unknown[]\n        /**\n         * Context modifier for modifying context during execution\n         */\n        contextModifier?: {\n          modifyContext: (ctx: ToolUseContext) => ToolUseContext\n        }\n      }\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    | {\n        type: 'progress'\n        content: any\n        normalizedMessages?: any[]\n        tools?: any[]\n      },\n    void,\n    unknown\n  >\n}\n\n/**\n * Get tool description synchronously.\n * Returns cached description if available, or falls back to string description,\n * or a default value if description is async and not cached.\n *\n * @param tool - The tool to get description from\n * @returns The tool description string\n */\nexport function getToolDescription(tool: Tool): string {\n  // First check cached description\n  if (tool.cachedDescription) {\n    return tool.cachedDescription\n  }\n\n  // If description is a string, return it directly\n  if (typeof tool.description === 'string') {\n    return tool.description\n  }\n\n  // Fallback for async descriptions that haven't been cached\n  return `Tool: ${tool.name}`\n}\n\n/**\n * Get tool description asynchronously.\n * Always returns the actual description, resolving async functions if needed.\n *\n * @param tool - The tool to get description from\n * @param input - Optional input for context-aware descriptions\n * @returns Promise resolving to the tool description string\n */\nexport async function getToolDescriptionAsync(\n  tool: Tool,\n  input?: unknown,\n): Promise<string> {\n  if (typeof tool.description === 'string') {\n    return tool.description\n  }\n\n  if (typeof tool.description === 'function') {\n    return await tool.description(input)\n  }\n\n  return `Tool: ${tool.name}`\n}\n\n/**\n * Cache descriptions for all tools.\n * Should be called at startup to ensure synchronous access works.\n *\n * @param tools - Array of tools to cache descriptions for\n */\nexport async function cacheToolDescriptions(tools: Tool[]): Promise<void> {\n  await Promise.all(\n    tools.map(async tool => {\n      if (typeof tool.description === 'function' && !tool.cachedDescription) {\n        try {\n          tool.cachedDescription = await tool.description()\n        } catch (error) {\n          // Fallback on error\n          tool.cachedDescription = `Tool: ${tool.name}`\n        }\n      } else if (\n        typeof tool.description === 'string' &&\n        !tool.cachedDescription\n      ) {\n        tool.cachedDescription = tool.description\n      }\n    }),\n  )\n}\n"],
-  "mappings": "AA4JO,SAAS,mBAAmB,MAAoB;AAErD,MAAI,KAAK,mBAAmB;AAC1B,WAAO,KAAK;AAAA,EACd;AAGA,MAAI,OAAO,KAAK,gBAAgB,UAAU;AACxC,WAAO,KAAK;AAAA,EACd;AAGA,SAAO,SAAS,KAAK,IAAI;AAC3B;AAUA,eAAsB,wBACpB,MACA,OACiB;AACjB,MAAI,OAAO,KAAK,gBAAgB,UAAU;AACxC,WAAO,KAAK;AAAA,EACd;AAEA,MAAI,OAAO,KAAK,gBAAgB,YAAY;AAC1C,WAAO,MAAM,KAAK,YAAY,KAAK;AAAA,EACrC;AAEA,SAAO,SAAS,KAAK,IAAI;AAC3B;AAQA,eAAsB,sBAAsB,OAA8B;AACxE,QAAM,QAAQ;AAAA,IACZ,MAAM,IAAI,OAAM,SAAQ;AACtB,UAAI,OAAO,KAAK,gBAAgB,cAAc,CAAC,KAAK,mBAAmB;AACrE,YAAI;AACF,eAAK,oBAAoB,MAAM,KAAK,YAAY;AAAA,QAClD,SAAS,OAAO;AAEd,eAAK,oBAAoB,SAAS,KAAK,IAAI;AAAA,QAC7C;AAAA,MACF,WACE,OAAO,KAAK,gBAAgB,YAC5B,CAAC,KAAK,mBACN;AACA,aAAK,oBAAoB,KAAK;AAAA,MAChC;AAAA,IACF,CAAC;AAAA,EACH;AACF;",
+  "sourcesContent": ["import { z } from 'zod'\nimport * as React from 'react'\nimport type { UserQuestion, UserAnswer } from './types/askUserQuestion'\nimport type {\n  ToolUseOptions,\n  ResponseState,\n  ValidationResult as CoreValidationResult,\n} from './types/core'\n\n/**\n * Core Tool interface for Minto's extensible tool system\n * Provides standardized contract for all tool implementations\n *\n * IMPORTANT: Tool descriptions can be either:\n * - A string (synchronous, preferred for adapters)\n * - An async function (for dynamic descriptions)\n * - An async function that accepts input (for context-aware descriptions)\n *\n * Use getToolDescription() helper for safe synchronous access.\n */\n\nexport type SetToolJSXFn = (\n  jsx: {\n    jsx: React.ReactNode | null\n    shouldHidePromptInput: boolean\n  } | null,\n) => void\n\n/**\n * Function type for asking the user questions\n */\nexport type AskUserFn = (questions: UserQuestion[]) => Promise<UserAnswer[]>\n\nexport interface ToolUseContext {\n  messageId: string | undefined\n  agentId?: string\n  /** The tool_use ID from the API (for tracking concurrent executions) */\n  toolUseId?: string\n  safeMode?: boolean\n  abortController: AbortController\n  readFileTimestamps: { [filePath: string]: number }\n  options?: ToolUseOptions\n  responseState?: ResponseState\n}\n\nexport interface ExtendedToolUseContext extends ToolUseContext {\n  setToolJSX: SetToolJSXFn\n  askUser?: AskUserFn\n}\n\n// Re-export for backward compatibility\nexport type ValidationResult = CoreValidationResult\n\n/**\n * Tool interface \u2014 non-generic to avoid variance issues with tool collections.\n *\n * Individual tool implementations use `satisfies Tool` for type checking\n * at the definition site, with their own schema-inferred types internally.\n * The non-generic interface allows tools to be collected in Tool[] arrays\n * without requiring `as unknown as Tool` casts.\n */\n/* eslint-disable @typescript-eslint/no-explicit-any -- Intentional: non-generic interface uses `any`\n   for tool-specific input/output types. Individual tools use concrete types via `satisfies Tool`. */\nexport interface Tool {\n  name: string\n  /**\n   * Tool description - can be:\n   * - A string (synchronous, best for adapters)\n   * - An async function returning string (for dynamic descriptions)\n   * - An async function accepting input (for context-aware descriptions)\n   *\n   * Use getToolDescription() for safe synchronous access in adapters.\n   */\n  description?: string | ((input?: any) => Promise<string>)\n  /**\n   * Cached description for synchronous access.\n   * Populated by cacheToolDescriptions() at startup.\n   */\n  cachedDescription?: string\n  inputSchema: z.ZodObject<any>\n  inputJSONSchema?: Record<string, unknown>\n  prompt: (options?: { safeMode?: boolean }) => Promise<string>\n  /** User-facing name for display. Can optionally accept input for context. */\n  userFacingName?: (input?: any) => string\n  isEnabled: () => Promise<boolean>\n  /** Whether this tool only reads data (no side effects). */\n  isReadOnly: (input?: any) => boolean\n  /** Whether this tool is safe to run concurrently with other tools. */\n  isConcurrencySafe: (input?: any) => boolean\n  needsPermissions: (input?: any) => boolean\n  /** Whether this tool requires user interaction (e.g., confirmation dialogs). */\n  requiresUserInteraction?: (input?: any) => boolean\n  validateInput?: (\n    input: any,\n    context?: ToolUseContext,\n  ) => Promise<ValidationResult>\n  renderResultForAssistant: (output: any) => string | any[]\n  renderToolUseMessage: (\n    input: any,\n    options: { verbose: boolean },\n  ) => string | React.ReactElement | null\n  renderToolUseRejectedMessage?: (...args: any[]) => React.ReactElement | null\n  /** Render the tool result for display. */\n  renderToolResultMessage?: (\n    output: any,\n    options?: { verbose: boolean },\n  ) => React.ReactNode\n  call: (\n    input: any,\n    context: ToolUseContext,\n  ) => AsyncGenerator<\n    | {\n        type: 'result'\n        data: any\n        resultForAssistant?: string | any[]\n        newMessages?: unknown[]\n        contextModifier?: {\n          modifyContext: (ctx: ToolUseContext) => ToolUseContext\n        }\n      }\n    | {\n        type: 'progress'\n        content: any\n        normalizedMessages?: any[]\n        tools?: any[]\n      },\n    void,\n    unknown\n  >\n}\n/* eslint-enable @typescript-eslint/no-explicit-any */\n\n/**\n * Get tool description synchronously.\n * Returns cached description if available, or falls back to string description,\n * or a default value if description is async and not cached.\n *\n * @param tool - The tool to get description from\n * @returns The tool description string\n */\nexport function getToolDescription(tool: Tool): string {\n  // First check cached description\n  if (tool.cachedDescription) {\n    return tool.cachedDescription\n  }\n\n  // If description is a string, return it directly\n  if (typeof tool.description === 'string') {\n    return tool.description\n  }\n\n  // Fallback for async descriptions that haven't been cached\n  return `Tool: ${tool.name}`\n}\n\n/**\n * Get tool description asynchronously.\n * Always returns the actual description, resolving async functions if needed.\n *\n * @param tool - The tool to get description from\n * @param input - Optional input for context-aware descriptions\n * @returns Promise resolving to the tool description string\n */\nexport async function getToolDescriptionAsync(\n  tool: Tool,\n  input?: unknown,\n): Promise<string> {\n  if (typeof tool.description === 'string') {\n    return tool.description\n  }\n\n  if (typeof tool.description === 'function') {\n    return await tool.description(input)\n  }\n\n  return `Tool: ${tool.name}`\n}\n\n/**\n * Cache descriptions for all tools.\n * Should be called at startup to ensure synchronous access works.\n *\n * @param tools - Array of tools to cache descriptions for\n */\nexport async function cacheToolDescriptions(tools: Tool[]): Promise<void> {\n  await Promise.all(\n    tools.map(async tool => {\n      if (typeof tool.description === 'function' && !tool.cachedDescription) {\n        try {\n          tool.cachedDescription = await tool.description()\n        } catch (error) {\n          // Fallback on error\n          tool.cachedDescription = `Tool: ${tool.name}`\n        }\n      } else if (\n        typeof tool.description === 'string' &&\n        !tool.cachedDescription\n      ) {\n        tool.cachedDescription = tool.description\n      }\n    }),\n  )\n}\n"],
+  "mappings": "AA4IO,SAAS,mBAAmB,MAAoB;AAErD,MAAI,KAAK,mBAAmB;AAC1B,WAAO,KAAK;AAAA,EACd;AAGA,MAAI,OAAO,KAAK,gBAAgB,UAAU;AACxC,WAAO,KAAK;AAAA,EACd;AAGA,SAAO,SAAS,KAAK,IAAI;AAC3B;AAUA,eAAsB,wBACpB,MACA,OACiB;AACjB,MAAI,OAAO,KAAK,gBAAgB,UAAU;AACxC,WAAO,KAAK;AAAA,EACd;AAEA,MAAI,OAAO,KAAK,gBAAgB,YAAY;AAC1C,WAAO,MAAM,KAAK,YAAY,KAAK;AAAA,EACrC;AAEA,SAAO,SAAS,KAAK,IAAI;AAC3B;AAQA,eAAsB,sBAAsB,OAA8B;AACxE,QAAM,QAAQ;AAAA,IACZ,MAAM,IAAI,OAAM,SAAQ;AACtB,UAAI,OAAO,KAAK,gBAAgB,cAAc,CAAC,KAAK,mBAAmB;AACrE,YAAI;AACF,eAAK,oBAAoB,MAAM,KAAK,YAAY;AAAA,QAClD,SAAS,OAAO;AAEd,eAAK,oBAAoB,SAAS,KAAK,IAAI;AAAA,QAC7C;AAAA,MACF,WACE,OAAO,KAAK,gBAAgB,YAC5B,CAAC,KAAK,mBACN;AACA,aAAK,oBAAoB,KAAK;AAAA,MAChC;AAAA,IACF,CAAC;AAAA,EACH;AACF;",
   "names": []
 }