@agentxin-ai/plugin-tool-retry 0.0.4

package/README.md

@@ -0,0 +1,77 @@
+# AgentXin Plugin: Tool Retry Middleware
+
+`@agentxin-ai/plugin-tool-retry` retries failed tool executions for AgentXin agents using JSON-serializable middleware configuration. It preserves the core LangChain retry behavior while fitting AgentXin's UI-driven plugin model.
+
+## Key Features
+
+- Retries tool failures with configurable retry count, exponential backoff, bounded jitter, and declarative error matching.
+- Can target all tools or only a configured set of tool names.
+- Returns a `ToolMessage` with `status: "error"` in `continue` mode so the agent can react gracefully.
+- Rethrows the last error in `error` mode after retries are exhausted.
+- Registers as a global middleware plugin so the strategy is available platform-wide.
+
+## Installation
+
+```bash
+pnpm add @agentxin-ai/plugin-tool-retry
+# or
+npm install @agentxin-ai/plugin-tool-retry
+```
+
+## Quick Start
+
+1. Register the plugin:
+   ```sh
+   PLUGINS=@agentxin-ai/plugin-tool-retry
+   ```
+2. Add a middleware entry using strategy `ToolRetryMiddleware`.
+3. Configure retries:
+   ```json
+   {
+     "type": "ToolRetryMiddleware",
+     "options": {
+       "toolNames": ["search_database", "query_sales_report"],
+       "maxRetries": 2,
+       "initialDelayMs": 1000,
+       "backoffFactor": 2,
+       "maxDelayMs": 60000,
+       "jitter": true,
+       "retryAllErrors": false,
+       "retryableErrorNames": ["TimeoutError"],
+       "retryableStatusCodes": [500, 503],
+       "retryableMessageIncludes": ["temporarily unavailable"],
+       "onFailure": "continue"
+     }
+   }
+   ```
+
+## Configuration
+
+| Field | Type | Description | Default |
+| ----- | ---- | ----------- | ------- |
+| `toolNames` | string[] | Tool names to retry. Empty means all tools. | `[]` |
+| `maxRetries` | number | Number of retry attempts after the initial failure. `0` disables retries. | `2` |
+| `initialDelayMs` | number | Delay before the first retry attempt, in milliseconds. | `1000` |
+| `backoffFactor` | number | Exponential multiplier applied per retry attempt. `0` keeps a constant delay. | `2` |
+| `maxDelayMs` | number | Upper bound for the computed retry delay. | `60000` |
+| `jitter` | boolean | Adds a bounded random factor to each delay to reduce synchronized retries. | `true` |
+| `retryAllErrors` | boolean | Retry every thrown error when `true`. | `true` |
+| `retryableErrorNames` | string[] | Retry only matching `error.name` values when `retryAllErrors=false`. | `[]` |
+| `retryableStatusCodes` | number[] | Retry matching HTTP-style status codes from `status`, `statusCode`, or `response.status`. | `[]` |
+| `retryableMessageIncludes` | string[] | Retry when the error message contains any configured fragment. Matching is case-insensitive. | `[]` |
+| `onFailure` | `"continue"` \| `"error"` | Return a `ToolMessage` or rethrow after retries are exhausted. | `"continue"` |
+
+## LangChain Differences
+
+- Function-based `retryOn`, function-based `onFailure`, and BaseTool instance filtering are not supported in v1.
+- Tool selection is done with plain tool-name strings so middleware configuration stays serializable.
+- Retry attempts directly re-invoke the tool handler; no extra workflow execution wrapper is added because the SDK does not expose a tool-attempt tracking primitive.
+
+## Development & Testing
+
+```bash
+NX_DAEMON=false pnpm -C /path/to/agentxin-plugins/agentxinai exec nx build @agentxin-ai/plugin-tool-retry
+NX_DAEMON=false pnpm -C /path/to/agentxin-plugins/agentxinai exec nx test @agentxin-ai/plugin-tool-retry
+```
+
+TypeScript output is emitted to `middlewares/tool-retry/dist`.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@agentxin-ai/plugin-tool-retry",
+  "version": "0.0.4",
+  "author": {
+    "name": "AgentXinAI",
+    "url": "https://agentxinai.cn"
+  },
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxin-ai/agentxin-plugins.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agentxin-ai/agentxin-plugins/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@agentxin-plugins-starter/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "zod": "3.25.67",
+    "@agentxin-ai/plugin-sdk": "^3.8.0",
+    "chalk": "4.1.2",
+    "@nestjs/common": "^11.1.6",
+    "@metad/contracts": "^3.8.0",
+    "@langchain/core": "0.3.72"
+  }
+}