fix: 修正 WaterFlow Skill/Tool 兼容性问题 + 类型声明完善

Skill 格式修正:
- allowed_tools → allowed-tools (kebab-case)
- user_invocable → user-invocable (kebab-case)
- persona skill name: graph_memory_persona → persona (匹配目录名)
- task skill name: graph_memory_task → task (匹配目录名)

Tool 接口优化:
- installTrulyMEM: require() → ESM dynamic import
- handler: 添加 abort 信号检查
- graph_database: _platform 类型 any → Platform
- graph_database: 修复 fs null 检查和 ArrayBuffer 类型转换

类型声明完善:
- waterflow.d.ts 从 193 行扩展到 400+ 行
- 添加 SchemaType, ToolFeatures, ToolMetadata 等完整类型
- 添加 network, tools, builtinTools 等缺失字段
- 添加 waterflow/runtime/core/tools/builtin 模块声明
- 添加 waterflow/runtime/core/tools/tool_registry 模块声明

清理:
- 删除 TRACKING.md, 重构.md, migration_plan.md, todo_progress.md
- 删除 docs/integration/waterflow-design.md

ts/bundled-skills/graph_memory/SKILL.md

@@ -3,7 +3,7 @@ name: graph_memory
 description: 图记忆工具 - 让 AI 拥有真正的长期记忆能力
 when_to_use: 需要 AI 记住、回忆、管理信息或任务时
 context: inline
-allowed_tools:
+allowed-tools:
   - builtin:graph_memory
 arguments:
   - name: action
@@ -15,7 +15,7 @@ arguments:
     type: object
     required: true
     description: 操作参数
-user_invocable: true
+user-invocable: true
 ---
 
 # GraphMemory 图记忆操作

ts/bundled-skills/graph_memory/persona/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: graph_memory_persona
+name: persona
 description: 管理 AI 人设 - 更新或清除 AI 角色特征
 when_to_use: 需要修改 AI 的角色设定或清除人设时
 context: inline
-allowed_tools:
+allowed-tools:
   - builtin:graph_memory
 arguments:
   - name: action
@@ -22,7 +22,7 @@ arguments:
   - name: confirm
     type: boolean
     description: 确认清除 (用于 clear)
-user_invocable: true
+user-invocable: true
 ---
 
 # GraphMemory Persona 人设管理

ts/bundled-skills/graph_memory/task/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: graph_memory_task
+name: task
 description: 管理连续性任务 - 创建、更新、删除任务节点
 when_to_use: 需要创建或管理长期任务时
 context: inline
-allowed_tools:
+allowed-tools:
   - builtin:graph_memory
 arguments:
   - name: action
@@ -28,7 +28,7 @@ arguments:
   - name: info_node
     type: string
     description: 信息节点 (用于 link_info)
-user_invocable: true
+user-invocable: true
 ---
 
 # GraphMemory Task 任务管理

ts/src/runtime/core/graph_memory/graph_database.ts

@@ -1,4 +1,5 @@
 import initSqlJs, { type Database as SqlJsDatabase } from 'sql.js';
+import type { Platform } from 'waterflow/platform/types';
 import type { Entity, Relation, RecallParams, CommitParams, PurgeParams, RecallResult, CommitResult, PurgeResult, MemoryStats } from './types';
 import { getConfig } from './config';
 
@@ -6,7 +7,7 @@ export class GraphDatabase {
   private db: SqlJsDatabase | null = null;
   private sessionId: string;
   private initPromise: Promise<void> | null = null;
-  private _platform: any = null;
+  private _platform: Platform | null = null;
 
   constructor(sessionId?: string) {
     this.sessionId = sessionId || `session-${Date.now()}`;
@@ -20,10 +21,15 @@ export class GraphDatabase {
 
     try {
       const dbPath = this._platform.path.join(this._platform.getCwd(), getConfig().dbPath);
-      const exists = await this._platform.fs.exists(dbPath);
-      if (exists) {
-        const data = await this._platform.fs.readFile(dbPath, { encoding: 'binary' });
-        this.db = new SQL.Database(data as Uint8Array);
+      const fs = this._platform.fs;
+      if (fs) {
+        const exists = await fs.exists(dbPath);
+        if (exists) {
+          const data = await fs.readFile(dbPath, { encoding: 'binary' });
+          this.db = new SQL.Database(new Uint8Array(data as ArrayBuffer));
+        } else {
+          this.db = new SQL.Database();
+        }
       } else {
         this.db = new SQL.Database();
       }
@@ -39,16 +45,18 @@ export class GraphDatabase {
 
     try {
       const platform = this._platform;
+      const fs = platform.fs;
+      if (!fs) return;
       const dbPath = platform.path.join(platform.getCwd(), getConfig().dbPath);
       const dir = platform.path.dirname(dbPath);
-      const dirExists = await platform.fs.exists(dir);
+      const dirExists = await fs.exists(dir);
       if (!dirExists) {
-        await platform.fs.mkdir(dir, true);
+        await fs.mkdir(dir, true);
       }
       const data = this.db.export();
-      await platform.fs.writeFile(dbPath, new Uint8Array(data), { encoding: 'binary' });
+      await fs.writeFile(dbPath, data.buffer as ArrayBuffer, { encoding: 'binary' });
     } catch (error) {
-      this._platform.getLogger().error(`[GraphDatabase] Save failed: ${error}`);
+      console.error(`[GraphDatabase] Save failed: ${error}`);
     }
   }
 

ts/src/runtime/core/tools/builtin/graph_memory_tool.ts

@@ -102,6 +102,10 @@ export class GraphMemoryTool implements Tool {
   }
 
   async handler(params: ToolInput, context: ToolExecutionContext): Promise<ToolOutput> {
+    if (context.abortController?.signal?.aborted) {
+      throw new Error('Operation aborted');
+    }
+
     const action = params.action as string;
     const actionParams = params.params as Record<string, unknown>;
     const logger = context?.logger;

ts/src/runtime/core/tools/builtin/index.ts

@@ -11,8 +11,8 @@ export function registerGraphMemoryTool(
   registry.register(createGraphMemoryTool(sessionId));
 }
 
-export function installTrulyMEM(platform: Platform, sessionId?: string) {
-  const { initializeToolRegistry } = require('waterflow/runtime/core/tools/builtin');
+export async function installTrulyMEM(platform: Platform, sessionId?: string) {
+  const { initializeToolRegistry } = await import('waterflow/runtime/core/tools/builtin');
   const registry = initializeToolRegistry(platform);
   registerGraphMemoryTool(registry, sessionId);
   return registry;

ts/src/types/waterflow.d.ts

@@ -1,12 +1,25 @@
 declare module 'waterflow/platform' {
-  import type { Platform } from 'waterflow/platform/types';
+  import type { Platform, CreatePlatformOptions, PlatformCapabilities } from 'waterflow/platform/types';
   export function getPlatform(): Platform;
-  export function hasCapability(capability: string): boolean;
-  export function initPlatform(options?: any): Platform;
+  export function hasCapability(capability: keyof PlatformCapabilities): boolean;
+  export function initPlatform(options?: CreatePlatformOptions): Platform;
   export function resetPlatform(): void;
 }
 
 declare module 'waterflow/platform/types' {
+  export type BufferSource = ArrayBuffer | ArrayBufferView;
+  export type RuntimeType = 'node' | 'web' | 'harmony' | 'unknown';
+  export type OSType = 'windows' | 'macos' | 'linux' | 'android' | 'ios' | 'harmony' | 'unknown';
+
+  export interface PlatformCapabilities {
+    fileSystem: boolean;
+    processExecution: boolean;
+    network: boolean;
+    storage: boolean;
+    webSocket: boolean;
+    workers: boolean;
+  }
+
   export interface PlatformAbortSignal {
     readonly aborted: boolean;
     readonly reason?: unknown;
@@ -19,26 +32,107 @@ declare module 'waterflow/platform/types' {
     abort(reason?: unknown): void;
   }
 
-  export interface PathOperations {
-    join(...paths: string[]): string;
-    dirname(p: string): string;
-    basename(p: string, ext?: string): string;
-    extname(p: string): string;
-    normalize(p: string): string;
-    isAbsolute(p: string): boolean;
-    resolve(...paths: string[]): string;
-    relative(from: string, to: string): string;
+  export interface PlatformTextEncoder {
+    encode(input?: string): Uint8Array;
+    encodeInto(src: string, dest: Uint8Array): { read: number; written: number };
   }
 
-  export interface FileReadOptions {
-    encoding?: 'utf-8' | 'binary';
-    start?: number;
-    end?: number;
+  export interface PlatformTextDecoder {
+    decode(input?: BufferSource): string;
   }
 
-  export interface FileWriteOptions {
-    encoding?: 'utf-8' | 'binary';
-    append?: boolean;
+  export interface PlatformURL {
+    href: string;
+    origin: string;
+    protocol: string;
+    host: string;
+    hostname: string;
+    port: string;
+    pathname: string;
+    search: string;
+    hash: string;
+    toString(): string;
+    toJSON(): string;
+  }
+
+  export interface PlatformGlobals {
+    TextEncoder: new (encoding?: string) => PlatformTextEncoder;
+    TextDecoder: new (encoding?: string) => PlatformTextDecoder;
+    URL: new (url: string) => { href: string; pathname: string; toString(): string };
+    randomUUID(): string;
+    now(): number;
+    btoa(data: string): string;
+    atob(data: string): string;
+  }
+
+  export interface GlobOptions {
+    cwd?: string;
+    ignore?: string[];
+    absolute?: boolean;
+    dot?: boolean;
+    onlyFiles?: boolean;
+    onlyDirectories?: boolean;
+    deep?: number;
+    ignoreCase?: boolean;
+  }
+
+  export interface GlobResult {
+    path: string;
+    isFile: boolean;
+    isDirectory: boolean;
+  }
+
+  export interface GlobTool {
+    glob(pattern: string, options?: GlobOptions): Promise<string[]>;
+    globWithInfo(pattern: string, options?: GlobOptions): Promise<GlobResult[]>;
+    isMatch(path: string, pattern: string): boolean;
+    search(pattern: string, basePath?: string): Promise<string[]>;
+  }
+
+  export interface GrepOptions {
+    cwd?: string;
+    ignoreCase?: boolean;
+    multiline?: boolean;
+    glob?: string | string[];
+    include?: string[];
+    exclude?: string[];
+    context?: number;
+    beforeContext?: number;
+    afterContext?: number;
+    headLimit?: number;
+  }
+
+  export interface GrepMatch {
+    path: string;
+    line: number;
+    column?: number;
+    content: string;
+  }
+
+  export interface GrepSearchOptions {
+    pattern: string;
+    path?: string;
+    glob?: string | string[];
+    ignoreCase?: boolean;
+    context?: number;
+    outputMode?: 'content' | 'files_with_matches' | 'count';
+    maxResults?: number;
+  }
+
+  export interface GrepSearchResult {
+    lines: string[];
+  }
+
+  export interface GrepTool {
+    grep(pattern: string | RegExp, options?: GrepOptions): Promise<GrepMatch[]>;
+    grepFiles(pattern: string | RegExp, options?: GrepOptions): Promise<string[]>;
+    grepCount(pattern: string | RegExp, options?: GrepOptions): Promise<number>;
+    search(options: GrepSearchOptions): Promise<GrepSearchResult>;
+  }
+
+  export interface PlatformTools {
+    glob: GlobTool | null;
+    grep: GrepTool | null;
   }
 
   export interface FileInfo {
@@ -47,22 +141,35 @@ declare module 'waterflow/platform/types' {
     isFile: boolean;
     isDirectory: boolean;
     size: number;
-    modifiedTime: number;
-    createdTime: number;
+    modifiedTime?: number;
+    createdTime?: number;
+  }
+
+  export interface FileReadOptions {
+    encoding?: 'utf-8' | 'binary' | 'base64';
+    start?: number;
+    end?: number;
+  }
+
+  export interface FileWriteOptions {
+    encoding?: 'utf-8' | 'binary' | 'base64';
+    append?: boolean;
+    createDir?: boolean;
   }
 
   export interface FileSystemOperations {
-    readFile(filePath: string, options?: FileReadOptions): Promise<string | ArrayBuffer>;
-    writeFile(filePath: string, data: string | ArrayBuffer, options?: FileWriteOptions): Promise<void>;
-    appendFile(filePath: string, data: string, options?: FileWriteOptions): Promise<void>;
-    deleteFile(filePath: string): Promise<void>;
-    exists(filePath: string): Promise<boolean>;
-    stat(filePath: string): Promise<FileInfo>;
-    readdir(dirPath: string): Promise<FileInfo[]>;
-    mkdir(dirPath: string, recursive?: boolean): Promise<void>;
-    rmdir(dirPath: string, recursive?: boolean): Promise<void>;
+    readFile(path: string, options?: FileReadOptions): Promise<string | ArrayBuffer>;
+    writeFile(path: string, data: string | ArrayBuffer, options?: FileWriteOptions): Promise<void>;
+    appendFile(path: string, data: string, options?: FileWriteOptions): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileInfo>;
+    readdir(path: string): Promise<FileInfo[]>;
+    mkdir(path: string, recursive?: boolean): Promise<void>;
+    rmdir(path: string, recursive?: boolean): Promise<void>;
     copy(src: string, dest: string): Promise<void>;
     move(src: string, dest: string): Promise<void>;
+    watch?(path: string, callback: (event: string, filename: string) => void): () => void;
   }
 
   export interface ProcessResult {
@@ -76,12 +183,17 @@ declare module 'waterflow/platform/types' {
     cwd?: string;
     env?: Record<string, string>;
     timeout?: number;
+    input?: string;
+    shell?: boolean;
     maxBuffer?: number;
   }
 
   export interface ProcessOperations {
     exec(command: string, options?: ProcessOptions): Promise<ProcessResult>;
     execFile(file: string, args: string[], options?: ProcessOptions): Promise<ProcessResult>;
+    spawn?(command: string, args: string[], options?: ProcessOptions): AsyncIterable<string>;
+    which?(command: string): Promise<string | null>;
+    kill?(pid: number, signal?: string): Promise<boolean>;
   }
 
   export interface StorageOperations {
@@ -92,85 +204,56 @@ declare module 'waterflow/platform/types' {
     keys(): Promise<string[]>;
   }
 
-  export interface PlatformGlobals {
-    TextEncoder: typeof TextEncoder;
-    TextDecoder: typeof TextDecoder;
-    URL: typeof URL;
-    randomUUID(): string;
-    now(): number;
-    btoa(data: string): string;
-    atob(data: string): string;
+  export interface PathOperations {
+    join(...paths: string[]): string;
+    dirname(path: string): string;
+    basename(path: string, ext?: string): string;
+    extname(path: string): string;
+    normalize(path: string): string;
+    isAbsolute(path: string): boolean;
+    resolve(...paths: string[]): string;
+    relative(from: string, to: string): string;
   }
 
-  export interface Logger {
-    info(msg: string, ...args: unknown[]): void;
-    warn(msg: string, ...args: unknown[]): void;
-    error(msg: string, ...args: unknown[]): void;
-    debug(msg: string, ...args: unknown[]): void;
+  export interface PlatformResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    ok: boolean;
+    text(): Promise<string>;
+    json(): Promise<any>;
+    arrayBuffer(): Promise<ArrayBuffer>;
   }
 
-  export interface Platform {
-    readonly path: PathOperations;
-    readonly fs: FileSystemOperations;
-    readonly process: ProcessOperations;
-    readonly storage: StorageOperations;
-    readonly globals: PlatformGlobals;
-    getInfo(): { runtime: string; os: string; version: string; arch: string; hostname: string };
-    createAbortController(): PlatformAbortController;
-    getEnv(key: string): string | undefined;
-    getAllEnv(): Record<string, string>;
-    setEnv(key: string, value: string): void;
-    getCwd(): string;
-    setCwd(p: string): void;
-    exit(code: number): void;
-    getLogger(): Logger;
-  }
-}
-
-declare module 'waterflow/runtime/core/tools/tool_interface' {
-  import type { PlatformAbortController, Logger } from 'waterflow/platform/types';
-
-  export type ToolCategory = 'file' | 'code' | 'search' | 'execute' | 'network' | 'analysis' | 'generation' | 'communication' | 'mcp' | 'custom';
-  export type PermissionLevel = 'safe' | 'moderate' | 'dangerous' | 'restricted';
-  export type ToolInput = Record<string, unknown>;
-  export type ToolOutput = string | Record<string, unknown> | void;
-
-  export interface SchemaProperty {
-    type: string;
-    description: string;
-    enum?: string[];
-    minimum?: number;
-    maximum?: number;
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    default?: unknown;
-    examples?: unknown[];
-    items?: SchemaProperty;
-    properties?: Record<string, SchemaProperty>;
+  export interface PlatformFetchRequestInit {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+    headers?: Record<string, string>;
+    body?: string | ArrayBuffer | Record<string, string | ArrayBuffer>;
+    timeout?: number;
   }
 
-  export interface ToolInputSchema {
-    type: 'object';
-    properties: Record<string, SchemaProperty>;
-    required?: string[];
-    additionalProperties?: boolean;
+  export interface PlatformWebSocket {
+    readonly readyState: number;
+    readonly url: string;
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (event: any) => void): void;
+    removeEventListener(type: string, listener: (event: any) => void): void;
   }
 
-  export interface ToolOutputSchema {
-    type: 'object';
-    properties: Record<string, SchemaProperty>;
-    format?: 'json' | 'text' | 'markdown' | 'binary';
-    maxSize?: number;
-    maxLines?: number;
+  export interface NetworkOperations {
+    fetch(url: string, options?: PlatformFetchRequestInit): Promise<PlatformResponse>;
+    fetchStream?(url: string, options?: PlatformFetchRequestInit): AsyncGenerator<ArrayBuffer, PlatformResponse, unknown>;
+    connectWebSocket?(url: string, protocols?: string[]): Promise<PlatformWebSocket>;
   }
 
-  export interface ToolExecutionContext {
-    toolCallId: string;
-    workingDirectory: string;
-    abortController: PlatformAbortController;
-    config: { timeout?: number };
-    logger: Logger;
+  export interface PlatformInfo {
+    runtime: RuntimeType;
+    os: OSType;
+    version?: string;
+    arch?: string;
+    hostname?: string;
+    capabilities: PlatformCapabilities;
   }
 
   export interface Tool {
@@ -181,13 +264,370 @@ declare module 'waterflow/runtime/core/tools/tool_interface' {
     readonly inputSchema: ToolInputSchema;
     readonly outputSchema?: ToolOutputSchema;
     readonly handler: (params: ToolInput, context: ToolExecutionContext) => Promise<ToolOutput>;
-    readonly permissionLevel: PermissionLevel;
-    readonly alwaysLoad?: boolean;
-    readonly shouldDefer?: boolean;
+    readonly permissionLevel: ToolPermissionLevel;
+    readonly requiredPermissions?: string[];
+    readonly features?: ToolFeatures;
+    readonly metadata?: ToolMetadata;
     readonly isMcp?: boolean;
-    readonly prompt?: (options: any) => Promise<string>;
-    readonly features?: string[];
-    readonly metadata?: Record<string, unknown>;
+    readonly shouldDefer?: boolean;
+    readonly alwaysLoad?: boolean;
     readonly searchHint?: string;
+    prompt?(options: ToolPromptOptions): Promise<string>;
+  }
+
+  export interface Platform {
+    getInfo(): PlatformInfo;
+    createAbortController(): PlatformAbortController;
+    readonly path: PathOperations;
+    readonly fs: FileSystemOperations | null;
+    readonly process: ProcessOperations | null;
+    readonly storage: StorageOperations;
+    readonly network: NetworkOperations;
+    readonly globals: PlatformGlobals;
+    readonly tools: PlatformTools;
+    readonly builtinTools: Tool[];
+    getEnv(key: string): string | undefined;
+    getAllEnv?(): Record<string, string>;
+    setEnv?(key: string, value: string): void;
+    getCwd(): string;
+    setCwd?(path: string): void;
+    exit?(code: number): void;
+  }
+
+  export interface CreatePlatformOptions {
+    storagePath?: string;
+    storageType?: 'localStorage' | 'indexedDB';
+    dbName?: string;
+    context?: any;
+    storageName?: string;
+  }
+
+  export type ToolInput = Record<string, unknown>;
+  export type ToolOutput = string | Record<string, unknown> | void;
+
+  export type ToolPermissionLevel = 'safe' | 'moderate' | 'dangerous' | 'restricted';
+  export type ToolCategory = 'file' | 'code' | 'search' | 'execute' | 'network' | 'analysis' | 'generation' | 'communication' | 'custom';
+
+  export interface ToolSchemaProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    description: string;
+    enum?: string[];
+    default?: unknown;
+    examples?: unknown[];
+    items?: ToolSchemaProperty;
+    properties?: Record<string, ToolSchemaProperty>;
+  }
+
+  export interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, ToolSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+  }
+
+  export interface ToolExecutionContext {
+    toolCallId: string;
+    workingDirectory: string;
+    additionalWorkingDirectories?: string[];
+    abortController: PlatformAbortController;
+    config: {
+      timeout?: number;
+      maxOutputSize?: number;
+      allowedDirectories?: string[];
+    };
+    logger: {
+      info(message: string, ...args: unknown[]): void;
+      warn(message: string, ...args: unknown[]): void;
+      error(message: string, ...args: unknown[]): void;
+      debug(message: string, ...args: unknown[]): void;
+    };
+  }
+
+  export interface BuiltinTool {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: ToolCategory;
+    readonly inputSchema: ToolInputSchema;
+    readonly permissionLevel: ToolPermissionLevel;
+    handler(params: ToolInput, context: ToolExecutionContext): Promise<ToolOutput>;
+  }
+}
+
+declare module 'waterflow/runtime/core/tools/tool_interface' {
+  import type { PlatformAbortController } from 'waterflow/platform/types';
+  import type { AgentId } from 'waterflow/shared/types/agent';
+  import type { WorkflowRunner } from 'waterflow/runtime/core/workflow/types';
+  import type { WorkflowRegistryImpl } from 'waterflow/runtime/core/workflow/workflow_registry';
+  import type { AgentRegistryImpl } from 'waterflow/runtime/core/workflow/agent_registry';
+  import type { AgentExecutor } from 'waterflow/runtime/core/agent/agent_executor';
+  import type { MCPClient } from 'waterflow/runtime/core/tools/mcp/mcp_client';
+
+  export type ToolCategory =
+    | 'file'
+    | 'code'
+    | 'search'
+    | 'execute'
+    | 'network'
+    | 'analysis'
+    | 'generation'
+    | 'communication'
+    | 'mcp'
+    | 'custom';
+
+  export type PermissionLevel =
+    | 'safe'
+    | 'moderate'
+    | 'dangerous'
+    | 'restricted';
+
+  export type SchemaType =
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'boolean'
+    | 'array'
+    | 'object';
+
+  export interface SchemaProperty {
+    type: SchemaType;
+    description: string;
+    enum?: string[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    default?: any;
+    examples?: any[];
+    suggestedSource?: 'context' | 'literal' | 'file';
+    items?: SchemaProperty;
+    properties?: Record<string, SchemaProperty>;
+    additionalProperties?: boolean | SchemaProperty;
+  }
+
+  export interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, SchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+    semanticHints?: Record<string, string>;
+  }
+
+  export interface ToolOutputSchema {
+    type: 'object';
+    properties: Record<string, SchemaProperty>;
+    format?: 'json' | 'text' | 'markdown' | 'binary';
+    maxSize?: number;
+    maxLines?: number;
+  }
+
+  export type ToolInput = Record<string, unknown>;
+  export type ToolOutput = string | Record<string, unknown> | void;
+
+  export interface Logger {
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+  }
+
+  export interface ToolConfig {
+    timeout?: number;
+    maxOutputSize?: number;
+    allowedDirectories?: string[];
+  }
+
+  export interface ToolExecutionContext {
+    toolCallId: string;
+    agentId?: AgentId;
+    workingDirectory: string;
+    additionalWorkingDirectories?: string[] | undefined;
+    abortController: PlatformAbortController;
+    config: ToolConfig;
+    logger: Logger;
+    workflowRunner?: WorkflowRunner | undefined;
+    workflowRegistry?: WorkflowRegistryImpl | undefined;
+    agentExecutor?: AgentExecutor | undefined;
+    agentRegistry?: AgentRegistryImpl | undefined;
+    allowedAgentTypes?: string[] | undefined;
+    mcpClients?: Map<string, MCPClient> | undefined;
+    tools?: Tool[] | undefined;
+  }
+
+  export type ToolHandler = (
+    params: ToolInput,
+    context: ToolExecutionContext
+  ) => Promise<ToolOutput>;
+
+  export interface ToolFeatures {
+    isAsync?: boolean;
+    isStreamable?: boolean;
+    isCacheable?: boolean;
+    requiresConfirmation?: boolean;
+    supportsProgress?: boolean;
+    supportsCancellation?: boolean;
+    producesFiles?: boolean;
+    producesImages?: boolean;
+    producesStructuredOutput?: boolean;
+    requiresMcp?: boolean;
+    requiresNetwork?: boolean;
+  }
+
+  export interface ToolExample {
+    description: string;
+    input: ToolInput;
+    output: ToolOutput;
+    explanation?: string;
+  }
+
+  export interface ToolMetadata {
+    source: 'builtin' | 'mcp' | 'plugin' | 'external';
+    version?: string;
+    author?: string;
+    documentationUrl?: string;
+    examples?: ToolExample[];
+    estimatedDuration?: number;
+    estimatedTokens?: number;
+    compatibleModels?: string[];
+    incompatibleModels?: string[];
+  }
+
+  export interface ToolPromptOptions {
+    tools: Tool[];
+    agentRegistry?: AgentRegistryImpl | undefined;
+    workflowRegistry?: WorkflowRegistryImpl | undefined;
+    allowedAgentTypes?: string[] | undefined;
+  }
+
+  export interface Tool {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: ToolCategory;
+    readonly inputSchema: ToolInputSchema;
+    readonly outputSchema?: ToolOutputSchema;
+    readonly handler: ToolHandler;
+    readonly permissionLevel: PermissionLevel;
+    readonly requiredPermissions?: string[];
+    readonly features?: ToolFeatures;
+    readonly metadata?: ToolMetadata;
+    readonly isMcp?: boolean;
+    readonly shouldDefer?: boolean;
+    readonly alwaysLoad?: boolean;
+    readonly searchHint?: string;
+    prompt?(options: ToolPromptOptions): Promise<string>;
+  }
+
+  export interface ToolExecutionError {
+    type: ToolErrorType;
+    message: string;
+    code?: string;
+    details?: Record<string, unknown>;
+  }
+
+  export type ToolErrorType =
+    | 'validation_error'
+    | 'permission_denied'
+    | 'timeout'
+    | 'execution_error'
+    | 'network_error'
+    | 'mcp_error'
+    | 'unknown_error';
+
+  export interface ToolExecutionResult {
+    success: boolean;
+    toolId: string;
+    toolCallId: string;
+    output: ToolOutput;
+    error?: ToolExecutionError;
+    metadata: {
+      duration: number;
+      tokensUsed?: number;
+      cached?: boolean;
+      retryCount?: number;
+    };
+  }
+
+  export interface ToolCall {
+    id: string;
+    toolId: string;
+    toolName: string;
+    input: ToolInput;
+    callerId: AgentId | string;
+    callerType: 'agent' | 'workflow' | 'main';
+  }
+
+  export function createTextOutput(text: string): ToolOutput;
+  export function createJSONOutput(data: Record<string, unknown>): ToolOutput;
+  export function createErrorOutput(message: string, code?: string, details?: Record<string, unknown>): ToolOutput;
+}
+
+declare module 'waterflow/runtime/core/tools/builtin' {
+  import type { Platform } from 'waterflow/platform/types';
+  import type { Tool } from 'waterflow/runtime/core/tools/tool_interface';
+  import { ToolRegistry } from 'waterflow/runtime/core/tools/tool_registry';
+
+  export const FRAMEWORK_TOOLS: Tool[];
+  export function initializeToolRegistry(platform: Platform): ToolRegistry;
+  export function getFrameworkTools(): Tool[];
+}
+
+declare module 'waterflow/runtime/core/tools/tool_registry' {
+  import type { Tool, ToolCategory, ToolInput } from 'waterflow/runtime/core/tools/tool_interface';
+
+  export interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+  }
+
+  export interface ToolSearchResult {
+    tool: Tool;
+    relevanceScore: number;
+    matchReason: string;
+  }
+
+  export interface SearchOptions {
+    category?: ToolCategory;
+    permissionLevel?: string;
+    limit?: number;
+  }
+
+  export interface RegistryStatistics {
+    totalTools: number;
+    byCategory: Record<string, number>;
+    bySource: Record<string, number>;
+    byPermissionLevel: Record<string, number>;
+  }
+
+  export interface ToolDefinitionExtended {
+    id: string;
+    name: string;
+    description: string;
+    parameters: {
+      type: 'object';
+      properties: Record<string, any>;
+      required?: string[];
+      additionalProperties?: boolean;
+    };
+    execute: (params: Record<string, any>) => Promise<any>;
+  }
+
+  export class ToolRegistry {
+    register(tool: Tool | ToolDefinitionExtended): void;
+    registerAll(tools: (Tool | ToolDefinitionExtended)[]): void;
+    unregister(toolId: string): void;
+    get(toolId: string): Tool | ToolDefinitionExtended | undefined;
+    getByName(name: string): Tool | ToolDefinitionExtended | undefined;
+    has(toolId: string): boolean;
+    size(): number;
+    listAll(): (Tool | ToolDefinitionExtended)[];
+    listByCategory(category: ToolCategory): (Tool | ToolDefinitionExtended)[];
+    listByPermissionLevel(level: string): (Tool | ToolDefinitionExtended)[];
+    search(query: string, options?: SearchOptions): ToolSearchResult[];
+    isAvailable(toolId: string, context?: any): boolean;
+    validateInput(toolId: string, input: ToolInput): ValidationResult;
+    clear(): void;
+    getStatistics(): RegistryStatistics;
   }
 }