{"_id":"@agentxin-ai/plugin-tool-call-limit","name":"@agentxin-ai/plugin-tool-call-limit","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@agentxin-ai/plugin-tool-call-limit","version":"0.0.1","author":{"name":"AgentXinAI","url":"https://agentxinai.cn"},"license":"AGPL-3.0","repository":{"type":"git","url":"git+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"}},"dependencies":{"tslib":"^2.3.0"},"peerDependencies":{"zod":"3.25.67","@agentxin-ai/plugin-sdk":"^3.7.0","chalk":"4.1.2","@nestjs/common":"^11.1.6","@metad/contracts":"^3.7.0","@langchain/core":"0.3.72"},"_id":"@agentxin-ai/plugin-tool-call-limit@0.0.1","description":"`@agentxin-ai/plugin-tool-call-limit` enforces tool call quotas for [AgentXin AI](https://github.com/agentxin-ai/agentxin) agents. It tracks tool usage per thread and per run, blocking or ending execution once limits are exceeded while surfacing clear fee","homepage":"https://github.com/agentxin-ai/agentxin-plugins#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-No4gbmwkJp1J6xvaRoX3ehWgjVWilPXjEIDyYglS5/+dI8hZWYO0ScDnc/5PkLOPZ0AoDYuSlv3HpTAPnVHVug==","shasum":"54ac2dcc6447f87d9846a349957228dd2c3d19f7","tarball":"https://registry.npmjs.org/@agentxin-ai/plugin-tool-call-limit/-/plugin-tool-call-limit-0.0.1.tgz","fileCount":2,"unpackedSize":4933,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDYFvpTnp+PJqNjmR9wbET4xEeYvP87kjUxnkI3MLNxEgIgelBw7HW2Obagl4ilD7Hxqzv4w3zZrJvD84HHCZyIFY4="}]},"_npmUser":{"name":"agentxin-ai","email":"1304040880@qq.com"},"directories":{},"maintainers":[{"name":"agentxin-ai","email":"1304040880@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-tool-call-limit_0.0.1_1773917538924_0.709756643379494"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T10:52:18.865Z","0.0.1":"2026-03-19T10:52:19.067Z","modified":"2026-03-19T10:52:19.302Z"},"maintainers":[{"name":"agentxin-ai","email":"1304040880@qq.com"}],"description":"`@agentxin-ai/plugin-tool-call-limit` enforces tool call quotas for [AgentXin AI](https://github.com/agentxin-ai/agentxin) agents. It tracks tool usage per thread and per run, blocking or ending execution once limits are exceeded while surfacing clear fee","homepage":"https://github.com/agentxin-ai/agentxin-plugins#readme","repository":{"type":"git","url":"git+https://github.com/agentxin-ai/agentxin-plugins.git"},"author":{"name":"AgentXinAI","url":"https://agentxinai.cn"},"bugs":{"url":"https://github.com/agentxin-ai/agentxin-plugins/issues"},"license":"AGPL-3.0","readme":"# AgentXin Plugin: Tool Call Limit Middleware\n\n`@agentxin-ai/plugin-tool-call-limit` enforces tool call quotas for [AgentXin AI](https://github.com/agentxin-ai/agentxin) agents. It tracks tool usage per thread and per run, blocking or ending execution once limits are exceeded while surfacing clear feedback to both the model and the user.\n\n## Key Features\n\n- Enforce tool call budgets per thread (persistent) and per run (per invocation), with optional per-tool targeting.\n- Three exit behaviors: `continue` (strip blocked calls, keep going), `error` (throw), and `end` (stop the run with a final message).\n- Injects tool-level error messages so the model knows a limit was hit; adds user-facing notices for blocked calls.\n- Guards against misconfigured tool filters and prevents “end” exits when other tools would continue running.\n- Ships as a global NestJS module that slots directly into the AgentXin middleware pipeline.\n\n## Installation\n\n```bash\npnpm add @agentxin-ai/plugin-tool-call-limit\n# or\nnpm install @agentxin-ai/plugin-tool-call-limit\n```\n\n> **Note**: Ensure the host already provides `@agentxin-ai/plugin-sdk`, `@nestjs/common@^11`, `@langchain/core@^0.3`, `zod`, `chalk`, and `@metad/contracts` as peer/runtime deps.\n\n## Quick Start\n\n1. **Register the Plugin**  \n   - Global env-based loading:\n     ```sh\n     PLUGINS=@agentxin-ai/plugin-tool-call-limit\n     ```\n   - Or install dynamically via the system plugin management UI (manual add from the interface).  \n   The plugin registers the global `ToolCallLimitPlugin` module.\n2. **Attach the Middleware**  \n   In the AgentXin console (or agent definition), add a middleware entry using strategy `ToolCallLimitMiddleware`.\n3. **Set Limits and Exit Behavior**  \n   Example middleware block:\n   ```json\n   {\n     \"type\": \"ToolCallLimitMiddleware\",\n     \"options\": {\n       \"toolName\": null,\n       \"threadLimit\": 50,\n       \"runLimit\": 5,\n       \"exitBehavior\": \"continue\"\n     }\n   }\n   ```\n   Set `toolName` to target a specific tool, or leave `null` to count all tool calls. Provide at least one limit; `runLimit` cannot exceed `threadLimit`.\n\n## Configuration\n\n| Field | Type | Description | Default |\n| ----- | ---- | ----------- | ------- |\n| `toolName` | string \\| null | Tool name to limit; `null` applies limits to all tool calls. | `null` |\n| `threadLimit` | number \\| null | Max tool calls per thread (persists across runs). | `null` (no thread cap) |\n| `runLimit` | number \\| null | Max tool calls per run (reset each invocation). | `null` (no run cap) |\n| `exitBehavior` | `\"continue\"` \\| `\"error\"` \\| `\"end\"` | How to react when limits are hit: `continue` blocks excess calls and keeps the run alive; `error` throws; `end` stops the run and returns a final message (only when no other tools would continue). | `\"continue\"` |\n\n> Rules  \n> - At least one of `threadLimit` or `runLimit` must be provided.  \n> - If both are set, `runLimit` must be less than or equal to `threadLimit`.\n\n## Behavior Notes\n\n- Run counts reset at the start of each invocation; thread counts accumulate for the conversation/thread.\n- Blocked tool calls are replaced with `ToolMessage` errors so the model avoids retrying them; user-facing AI messages describe the limit that was hit.\n- For `exitBehavior=\"end\"`, the middleware requires all tool calls to match the filter; otherwise it rejects the configuration to avoid partial execution.\n- Non-matching tools are allowed and not counted, with warnings to help catch misconfigured `toolName` filters.\n\n## Development & Testing\n\n```bash\nnpm install\nnpx nx build @agentxin-ai/plugin-tool-call-limit\nnpx nx test @agentxin-ai/plugin-tool-call-limit\n```\n\nTypeScript output lands in `packages/tool-call-limit/dist`. Validate middleware behavior in a staging agent before publishing.\n\n## License\n\nThis project follows the [AGPL-3.0 License](../../../LICENSE) located at the repository root.\n","readmeFilename":"README.md","_rev":"1-976b5667a51db40cf07fce9262168b6d"}