@vinhnt-sdk/tools 0.4.1 → 0.4.3

package/README.md

@@ -1,8 +1,8 @@
 # @vinhnt-sdk/tools
 
-> Version: 0.1.2-beta.0 | Status: BETA
+> Version: 0.4.2 | Status: STABLE
 
-Built-in tools for vinhnt-sdk — file, shell, git, web, search, image, and more.
+Tool framework and built-in tools for vinhnt-sdk — file, shell, git, web, search, middleware, and more.
 
 ## Install
 
@@ -14,34 +14,39 @@ npm install @vinhnt-sdk/tools
 pnpm add @vinhnt-sdk/tools
 ```
 
+## Features
+
+- **defineTool** — Define tools with Zod schemas, JSON Schema, risk levels, and annotations
+- **ToolMiddleware** — Wrap tool execution with cross-cutting concerns (logging, auth, retry)
+- **ToolHook** — Pre/post lifecycle hooks for tool calls
+- **ToolRegistry** — Tool registration, lookup, and execution with filtering
+- **LazyToolRegistry** — Lazy-load tools on first use
+- **ToolProvider** — Plugin-based tool discovery
+- **Built-in Tools** — File, shell, git, web search, glob, grep, image tools
+- **ToolSaga** — Compensation actions for multi-step tool operations
+
 ## Quick Start
 
 ```typescript
-import { defineTool, ToolRegistry } from '@vinhnt-sdk/tools';
-import type { ToolConfig, ToolDefinition } from '@vinhnt-sdk/schema';
+import { defineTool, ToolRegistry } from "@vinhnt-sdk/tools";
+import { z } from "zod";
 
-// Define a custom tool
 const calculatorTool = defineTool({
   name: "calculator",
   description: "Evaluate math expressions",
-  parameters: {
-    type: "object",
-    properties: {
-      expression: { type: "string", description: "Math expression" },
-    },
-    required: ["expression"],
-  },
+  risk: "read",
+  input: z.object({
+    expression: z.string().describe("Math expression"),
+  }),
   async execute(args, context) {
     const result = Function(`"use strict"; return (${args.expression})`)();
     return { success: true, output: String(result) };
   },
-});
+}).toDefinition();
 
-// Register tool
 const registry = new ToolRegistry();
 registry.register(calculatorTool);
 
-// Execute tool
 const result = await registry.execute("calculator", { expression: "2 + 2" });
 console.log(result.output); // "4"
 ```
@@ -51,31 +56,50 @@ console.log(result.output); // "4"
 ### Tool Definition
 
 ```typescript
-import { defineTool } from '@vinhnt-sdk/tools';
+import { defineTool } from "@vinhnt-sdk/tools";
+import { z } from "zod";
 
 const myTool = defineTool({
   name: "my-tool",
   description: "My custom tool",
-  riskLevel: "low", // "low" | "medium" | "high"
-  parameters: {
-    type: "object",
-    properties: {
-      input: { type: "string", description: "Input parameter" },
-    },
-    required: ["input"],
+  risk: "read", // "none" | "read" | "write" | "destructive" | "external"
+  input: z.object({
+    input: z.string().describe("Input parameter"),
+  }),
+  annotations: {
+    title: "My Tool",
+    readOnlyHint: true,
+    openWorldHint: false,
   },
   async execute(args, context) {
-    // args.input is the input parameter
-    // context contains sessionId, userId, etc.
     return { success: true, output: `Processed: ${args.input}` };
   },
-});
+}).toDefinition();
+```
+
+### ToolMiddleware
+
+```typescript
+import type { ToolMiddleware } from "@vinhnt-sdk/tools";
+
+const loggingMiddleware: ToolMiddleware = {
+  id: "logging",
+  async execute(tool, input, next) {
+    console.log(`Tool ${tool.id} called with`, input);
+    const result = await next(input);
+    console.log(`Tool ${tool.id} returned`, result);
+    return result;
+  },
+};
+
+// Apply middleware via ToolRegistry
+const registry = new ToolRegistry({ middleware: [loggingMiddleware] });
 ```
 
-### Tool Registry
+### ToolRegistry
 
 ```typescript
-import { ToolRegistry } from '@vinhnt-sdk/tools';
+import { ToolRegistry } from "@vinhnt-sdk/tools";
 
 const registry = new ToolRegistry();
 
@@ -98,80 +122,90 @@ const validation = registry.validate("calculator", { expression: "2 + 2" });
 
 ### Built-in Tools
 
-| Tool | Description | Risk Level |
+| Tool Factory | Description | Risk Level |
 |------|-------------|------------|
-| `file_read` | Read file contents | medium |
-| `file_write` | Write to files | high |
-| `file_edit` | Edit files | high |
-| `shell_exec` | Execute shell commands | high |
-| `git_status` | Get git status | low |
-| `git_diff` | Get git diff | low |
-| `git_log` | Get git log | low |
-| `web_search` | Search the web | low |
-| `web_fetch` | Fetch web pages | medium |
-| `image_gen` | Generate images | low |
-| `lint` | Lint code | low |
+| `createReadFileTool` | Read file contents | read |
+| `createWriteFileTool` | Write to files | destructive |
+| `createEditFileTool` | Edit files | destructive |
+| `createApplyPatchTool` | Apply patches | destructive |
+| `createListDirectoryTool` | List directory contents | read |
+| `createShellTool` | Execute shell commands | external |
+| `createGlobFilesTool` | Find files by pattern | read |
+| `createGrepFilesTool` | Search file contents | read |
+| `createWebSearchTool` | Search the web | external |
+| `createWebFetchTool` | Fetch web pages | external |
+| `createGitStatusTool` | Get git status | read |
+| `createGitDiffTool` | Get git diff | read |
+| `createGitLogTool` | Get git log | read |
+| `createGitCommitTool` | Create git commits | write |
+| `createReadImageTool` | Read image files | read |
+| `createQuestionTool` | Ask user questions | read |
+| `createTodoWriteTool` | Write todo items | write |
 
 ## Dependencies
 
-- `@vinhnt-sdk/schema` workspace:*
+- `@vinhnt-sdk/schema` >=0.5.0
+- `@vinhnt-sdk/guard` workspace:*
+- `@vinhnt-sdk/sandbox` workspace:*
 - `@vinhnt-sdk/security` workspace:*
 - `zod` ^4.4.3
 
-## Peer Dependencies
+## Usage Examples
 
-- `@vinhnt-sdk/core` workspace:* (optional)
+### Tool Middleware Pattern
 
-## Usage Examples
+```typescript
+import type { ToolMiddleware, ToolDefinition, ToolExecutionResult } from "@vinhnt-sdk/tools";
+
+const authMiddleware: ToolMiddleware = {
+  id: "auth",
+  async execute(tool, input, next) {
+    // Check permissions before execution
+    if (tool.risk === "destructive") {
+      const approved = await checkApproval(tool.id);
+      if (!approved) {
+        return { status: "denied", reason: "Not approved" };
+      }
+    }
+    return next(input);
+  },
+};
+```
 
-### Create Custom Tool
+### Tool Hooks
 
 ```typescript
-import { defineTool } from '@vinhnt-sdk/tools';
-
-const weatherTool = defineTool({
-  name: "weather",
-  description: "Get weather for a location",
-  parameters: {
-    type: "object",
-    properties: {
-      location: { type: "string", description: "City name" },
-    },
-    required: ["location"],
+import type { ToolHook } from "@vinhnt-sdk/tools";
+
+const auditHook: ToolHook = {
+  id: "audit",
+  async pre({ toolId, tool, input }) {
+    await logAudit(toolId, "start", input);
+    return null; // Continue execution
   },
-  async execute(args) {
-    // Fetch weather data
-    const weather = await fetchWeather(args.location);
-    return {
-      success: true,
-      output: {
-        temperature: weather.temp,
-        condition: weather.condition,
-      },
-    };
+  async post({ toolId, tool, input, result }) {
+    await logAudit(toolId, "end", { input, result });
+    return null; // Don't modify result
   },
-});
+};
 ```
 
-### Use Tool in Agent
+### ToolSaga (Compensation)
 
 ```typescript
-import { AgentKernel } from '@vinhnt-sdk/core';
-import { defineTool } from '@vinhnt-sdk/tools';
+import { ToolSaga } from "@vinhnt-sdk/tools";
 
-const kernel = new AgentKernel({
-  model: yourModelProvider,
-  store: yourStore,
-  tools: [calculatorTool, weatherTool],
-});
+const saga = new ToolSaga();
 
-const handle = kernel.createRunHandle("What's the weather in Tokyo?", {
-  sessionId: "session-1",
-  agentId: "assistant",
-  userId: "user-1",
+// Register steps with compensation
+saga.addStep({
+  tool: "create-file",
+  input: { path: "/tmp/file.txt", content: "hello" },
+  compensate: { tool: "delete-file", input: { path: "/tmp/file.txt" } },
 });
 
-const result = await handle.completed;
+// Execute all steps; compensate on failure
+const result = await saga.execute(context);
 ```
 
 ## License

package/dist/context.d.ts

@@ -16,6 +16,12 @@ export interface ToolContext {
     readonly parentContext?: RequestContext;
     /** Environment variables for subprocess execution (shell tool) */
     readonly env: Record<string, string>;
+    /**
+     * The active workspace root for this run.
+     * Tools should resolve file paths relative to this directory.
+     * Falls back to AgentKernelConfig.workspaceRoot if not set per-run.
+     */
+    readonly workspaceRoot?: string;
     /**
      * Request human approval for a permission-bound operation.
      * Returns the user's decision: "once" (allow once), "always" (approve forever), or "reject".

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC;IAExC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,sGAAsG;QACtG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,IAAI,CAAC;IAET;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEnD,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC;IAExC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,sGAAsG;QACtG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,IAAI,CAAC;IAET;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEnD,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClD"}

package/dist/index.d.ts

@@ -7,10 +7,11 @@ export { defineTool, toolToDefinition, zodSchemaToNestedJsonSchema } from "./def
 export { commandPattern, prefix } from "./arity.js";
 export type { ToolDefinitionLike } from "@vinhnt-sdk/schema";
 export type { ToolDefinition, ToolRisk, ToolAnnotations } from "./definitions.js";
+export { KNOWN_TOOL_RISKS } from "./definitions.js";
 export type { ToolFilter, ToolPermissionRule, ToolMaterialization } from "./registry.js";
 export { ToolRegistry } from "./registry.js";
 export type { ToolContext, PermissionReply } from "./context.js";
-export type { ToolHook, ToolExecutionResult } from "./types.js";
+export type { ToolHook, ToolExecutionResult, ToolMiddleware } from "./types.js";
 export type { JsonSchema7Object, JsonSchemaProperty } from "./json-schema.js";
 export { validateInput } from "./validate.js";
 export { ToolInputError } from "./validate.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -4,6 +4,7 @@
  */
 export { defineTool, toolToDefinition, zodSchemaToNestedJsonSchema } from "./define-tool.js";
 export { commandPattern, prefix } from "./arity.js";
+export { KNOWN_TOOL_RISKS } from "./definitions.js";
 export { ToolRegistry } from "./registry.js";
 // === Validation ===
 export { validateInput } from "./validate.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAQpD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAW7C,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,eAAe;AAEf,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,iBAAiB;AAEjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAwB;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,0BAA0B;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAMxE,eAAe;AAEf,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,qBAAqB;AAErB,OAAO,EACL,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAC3D,oBAAoB,EAAE,uBAAuB,EAC7C,gBAAgB,EAAE,WAAW,EAAE,qBAAqB,GACrD,MAAM,iBAAiB,CAAC;AAGzB,sBAAsB;AAEtB,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEhF,uBAAuB;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG1D,qBAAqB;AAErB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEpF,uBAAuB;AAEvB,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,oBAAoB;AAEpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGvG,oBAAoB;AAEpB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE/G,sBAAsB;AAEtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,sBAAsB;AAEtB,OAAO,EAAE,uBAAuB,IAAI,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEtF,2BAA2B;AAE3B,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAKpD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAW7C,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,eAAe;AAEf,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,iBAAiB;AAEjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAwB;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,0BAA0B;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAMxE,eAAe;AAEf,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,qBAAqB;AAErB,OAAO,EACL,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAC3D,oBAAoB,EAAE,uBAAuB,EAC7C,gBAAgB,EAAE,WAAW,EAAE,qBAAqB,GACrD,MAAM,iBAAiB,CAAC;AAGzB,sBAAsB;AAEtB,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEhF,uBAAuB;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG1D,qBAAqB;AAErB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEpF,uBAAuB;AAEvB,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,oBAAoB;AAEpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGvG,oBAAoB;AAEpB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE/G,sBAAsB;AAEtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,sBAAsB;AAEtB,OAAO,EAAE,uBAAuB,IAAI,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEtF,2BAA2B;AAE3B,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types.d.ts

@@ -29,4 +29,26 @@ export interface ToolHook {
         result: ToolExecutionResult;
     }): Promise<ToolExecutionResult | null>;
 }
+/**
+ * Tool middleware — wraps tool execution with cross-cutting concerns.
+ *
+ * Inspired by Mastra's tool middleware pattern.
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: ToolMiddleware = {
+ *   id: "logging",
+ *   execute: async (tool, input, next) => {
+ *     console.log(`Tool ${tool.id} called with`, input);
+ *     const result = await next(input);
+ *     console.log(`Tool ${tool.id} returned`, result);
+ *     return result;
+ *   },
+ * };
+ * ```
+ */
+export interface ToolMiddleware {
+    readonly id: string;
+    execute(tool: ToolDefinition, input: unknown, next: (input: unknown) => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,kCAAkC;AAClC,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GACnE,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,mBAAmB,CAAA;KAAE,GACjG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACvC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,kCAAkC;AAClC,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GACnE,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,mBAAmB,CAAA;KAAE,GACjG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CACL,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,mBAAmB,CAAC,GACrD,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinhnt-sdk/tools",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Built-in tools for VNT Agent — file, shell, git, web, search, image, and more",
   "license": "MIT",
   "type": "module",
@@ -45,11 +45,11 @@
     "access": "public"
   },
   "dependencies": {
+    "@vinhnt-sdk/schema": ">=0.5.0",
     "zod": "^4.4.3",
-    "@vinhnt-sdk/guard": "0.4.1",
-    "@vinhnt-sdk/sandbox": "0.4.1",
-    "@vinhnt-sdk/security": "0.4.1",
-    "@vinhnt-sdk/schema": "0.4.1"
+    "@vinhnt-sdk/guard": "0.4.2",
+    "@vinhnt-sdk/security": "0.4.2",
+    "@vinhnt-sdk/sandbox": "0.4.2"
   },
   "scripts": {
     "build": "tsc -b",