@agentxin-ai/plugin-model-retry 0.0.5

package/README.md

@@ -0,0 +1,79 @@
+# AgentXin Plugin: Model Retry Middleware
+
+`@agentxin-ai/plugin-model-retry` adds retry logic around AgentXin agent model calls. It keeps LangChain-style retry semantics while exposing only JSON-serializable configuration that can be edited in the AgentXin middleware UI.
+
+## Key Features
+
+- Retries failed model calls with configurable retry count, exponential backoff, max delay, and optional jitter.
+- Supports platform-safe retry matching by error name, HTTP status code, and message substring.
+- Returns an `AIMessage` when retries are exhausted in `continue` mode, or rethrows the last error in `error` mode.
+- Wraps retry attempts with `WrapWorkflowNodeExecutionCommand` so middleware-level execution tracking remains visible in AgentXin.
+- Registers as a global middleware plugin so the strategy is available across the platform.
+- Treats `AIMessage.response_metadata.finish_reason === "network_error"` as a retryable model failure, even when the provider returns a message instead of throwing.
+- Treats empty `AIMessage` results with no `tool_calls` and no `invalid_tool_calls` as retryable model failures.
+
+## Installation
+
+```bash
+pnpm add @agentxin-ai/plugin-model-retry
+# or
+npm install @agentxin-ai/plugin-model-retry
+```
+
+## Quick Start
+
+1. Register the plugin:
+   ```sh
+   PLUGINS=@agentxin-ai/plugin-model-retry
+   ```
+2. Add a middleware entry using strategy `ModelRetryMiddleware`.
+3. Configure retries:
+   ```json
+   {
+     "type": "ModelRetryMiddleware",
+     "options": {
+       "maxRetries": 2,
+       "initialDelayMs": 1000,
+       "backoffFactor": 2,
+       "maxDelayMs": 60000,
+       "jitter": true,
+       "retryAllErrors": false,
+       "retryableErrorNames": ["RateLimitError"],
+       "retryableStatusCodes": [429, 503],
+       "retryableMessageIncludes": ["timeout", "temporarily unavailable"],
+       "onFailure": "continue"
+     }
+   }
+   ```
+
+## Configuration
+
+| Field | Type | Description | Default |
+| ----- | ---- | ----------- | ------- |
+| `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 an `AIMessage` or rethrow after retries are exhausted. | `"continue"` |
+
+## LangChain Differences
+
+- Function-based `retryOn` and `onFailure` are intentionally not supported because AgentXin middleware configuration must remain serializable.
+- Retry matching uses declarative JSON fields instead of runtime classes or callback functions.
+- Retry attempts are execution-tracked with AgentXin workflow commands, but no model client is recreated during retries.
+- Provider responses that finish with `network_error` are normalized into an internal `ModelNetworkError` and routed through the same retry policy.
+- Provider responses with empty content and no tool call payload are normalized into an internal `ModelEmptyResponseError` and routed through the same retry policy.
+
+## Development & Testing
+
+```bash
+NX_DAEMON=false pnpm -C /path/to/agentxin-plugins/agentxinai exec nx build @agentxin-ai/plugin-model-retry
+NX_DAEMON=false pnpm -C /path/to/agentxin-plugins/agentxinai exec nx test @agentxin-ai/plugin-model-retry
+```
+
+TypeScript output is emitted to `middlewares/model-retry/dist`.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@agentxin-ai/plugin-model-retry",
+  "version": "0.0.5",
+  "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.1",
+    "chalk": "4.1.2",
+    "@nestjs/common": "^11.1.6",
+    "@nestjs/cqrs": "^11.0.3",
+    "@metad/contracts": "^3.8.1",
+    "@langchain/core": "0.3.72"
+  }
+}