{"_id":"@577-industries/tool-guardrails","name":"@577-industries/tool-guardrails","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@577-industries/tool-guardrails","version":"1.0.0","description":"4-level guardrail middleware (none/log/pause/block) for AI agent tools with human-in-the-loop approval workflow","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit"},"keywords":["guardrails","ai-safety","agent","governance","middleware","approval","human-in-the-loop","tools"],"author":{"name":"577 Industries"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/577-industries/tool-guardrails.git"},"homepage":"https://www.577industries.com/forge","devDependencies":{"@types/node":"^25.4.0","tsup":"^8.4.0","typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"@577-industries/tool-guardrails@1.0.0","gitHead":"04d4426cf8d32e259e4f0d1a9912d33634468adc","bugs":{"url":"https://github.com/577-industries/tool-guardrails/issues"},"_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-q5VGrrLLVMm1xJRxpM5fEFnIsH3cgdvH+bOQ5RrlLfZh3BNP84imPJi/T3TGR7QkRHOUidl5BC7K5m5Atcm7xw==","shasum":"6a56cf966ee14ef1734fd395b903efae099ffa8b","tarball":"https://registry.npmjs.org/@577-industries/tool-guardrails/-/tool-guardrails-1.0.0.tgz","fileCount":7,"unpackedSize":37155,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFTqFduZgLR82+aZPKGFGcDEKyFB14YkUyikvSQ3Rlb0AiEAxZAApVug4dHY07HipYKjMNGfWYmT2W+W3mrEhHsZYIE="}]},"_npmUser":{"name":"577industries","email":"t.waweru@577industries.com"},"directories":{},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tool-guardrails_1.0.0_1773252951432_0.7546242391622251"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T18:15:51.268Z","1.0.0":"2026-03-11T18:15:51.591Z","modified":"2026-03-11T18:15:51.986Z"},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"description":"4-level guardrail middleware (none/log/pause/block) for AI agent tools with human-in-the-loop approval workflow","homepage":"https://www.577industries.com/forge","keywords":["guardrails","ai-safety","agent","governance","middleware","approval","human-in-the-loop","tools"],"repository":{"type":"git","url":"git+https://github.com/577-industries/tool-guardrails.git"},"author":{"name":"577 Industries"},"bugs":{"url":"https://github.com/577-industries/tool-guardrails/issues"},"license":"Apache-2.0","readme":"# @577-industries/tool-guardrails\r\n\r\n[![npm version](https://img.shields.io/npm/v/@577-industries/tool-guardrails)](https://www.npmjs.com/package/@577-industries/tool-guardrails)\r\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\r\n\r\nA 4-level guardrail middleware for AI agent tools with human-in-the-loop approval workflow. Wrap any tool with governance controls — from silent passthrough to full blocking. Zero runtime dependencies.\r\n\r\nImplements the core algorithm described in the **\"Governed Autonomy Framework\"** patent (January 2026) by 577 Industries.\r\n\r\n## How It Works\r\n\r\n```\r\n  Tool Call\r\n      │\r\n      ▼\r\n  ┌──────────────────┐\r\n  │  Get Level for   │\r\n  │  this tool       │\r\n  └────────┬─────────┘\r\n           │\r\n     ┌─────┼──────┬──────────┐\r\n     │     │      │          │\r\n   none   log   pause      block\r\n     │     │      │          │\r\n   pass  execute  create   reject\r\n   thru  + emit   pending   + emit\r\n         event    op +      event\r\n                  emit\r\n```\r\n\r\n## Quick Start\r\n\r\n```bash\r\nnpm install @577-industries/tool-guardrails\r\n```\r\n\r\n```typescript\r\nimport { GuardrailMiddleware } from \"@577-industries/tool-guardrails\";\r\n\r\nconst middleware = new GuardrailMiddleware({\r\n  rules: {\r\n    read_data: \"none\",      // unrestricted\r\n    write_data: \"log\",      // execute + emit event\r\n    deploy: \"pause\",        // requires human approval\r\n    delete_prod: \"block\",   // always rejected\r\n  },\r\n});\r\n\r\n// Wrap your tools\r\nconst wrappedTool = middleware.wrap({\r\n  name: \"deploy\",\r\n  execute: async (args) => deployToProduction(args),\r\n});\r\n\r\n// Tool call gets paused — returns operation ID\r\nconst result = await wrappedTool.execute({ env: \"prod\" });\r\n// { success: false, paused: true, operationId: \"abc123...\" }\r\n\r\n// Human approves\r\nawait middleware.approve(result.operationId, \"tech-lead\");\r\n```\r\n\r\n## API Reference\r\n\r\n### `GuardrailMiddleware`\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `new GuardrailMiddleware(config)` | Create middleware with rules and options |\r\n| `getLevel(toolName)` | Get effective guardrail level for a tool |\r\n| `wrap(tool)` | Wrap a single tool with guardrail enforcement |\r\n| `wrapAll(tools)` | Wrap multiple tools |\r\n| `approve(opId, by)` | Approve a pending operation |\r\n| `reject(opId, by)` | Reject a pending operation |\r\n| `expireStale()` | Expire all past-due pending operations |\r\n| `getOperationStore()` | Access the underlying operation store |\r\n\r\n### Events\r\n\r\n| Event | When |\r\n|-------|------|\r\n| `tool:executed` | Tool ran successfully (log level) |\r\n| `tool:blocked` | Tool call was rejected (block level) |\r\n| `tool:paused` | Tool call pending approval (pause level) |\r\n| `operation:approved` | Pending operation was approved |\r\n| `operation:rejected` | Pending operation was rejected |\r\n| `operation:expired` | Pending operation expired |\r\n\r\n### `PendingOperationStore` Interface\r\n\r\nImplement for custom persistence (database, Redis, etc.):\r\n\r\n```typescript\r\ninterface PendingOperationStore {\r\n  create(op): Promise<PendingOperation>;\r\n  get(id): Promise<PendingOperation | null>;\r\n  approve(id, by): Promise<PendingOperation>;\r\n  reject(id, by): Promise<PendingOperation>;\r\n  expire(id): Promise<PendingOperation>;\r\n  listPending(): Promise<PendingOperation[]>;\r\n  expireStale(): Promise<PendingOperation[]>;\r\n}\r\n```\r\n\r\nBuilt-in: `InMemoryOperationStore` (default).\r\n\r\n## Architecture\r\n\r\nThe guardrail system resolves levels through a two-tier lookup:\r\n\r\n1. **Per-tool rule** — check `rules[toolName]`\r\n2. **Default level** — fall back to `defaultLevel` (default: `\"log\"`)\r\n\r\nBased on the [\"Governed Autonomy Framework\" patent](https://www.577industries.com/forge) by 577 Industries.\r\n\r\n---\r\n\r\nExtracted from [FORGE OS](https://www.577industries.com) by **577 Industries**.\r\n","readmeFilename":"README.md","_rev":"1-ee5056130cd6664f9547bbca5d80032a"}