{"_id":"@bytesbrains/pi-agent-supervisor","_rev":"4-02769808e5358e938fb030bb490d0397","name":"@bytesbrains/pi-agent-supervisor","dist-tags":{"latest":"1.3.1"},"versions":{"1.1.2":{"name":"@bytesbrains/pi-agent-supervisor","version":"1.1.2","keywords":["pi-package","pi-extension","governance","safety","supervisor","rate-limiting","audit-log"],"author":{"name":"nandal","email":"nandal@users.noreply.github.com"},"license":"MIT","_id":"@bytesbrains/pi-agent-supervisor@1.1.2","maintainers":[{"name":"nandal","email":"sandeep@nandal.in"}],"homepage":"https://github.com/nandal/pi-ext/tree/main/supervisor","bugs":{"url":"https://github.com/nandal/pi-ext/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"0b1611e3de8d6de26d01f6bdf59e00ab42cb8735","tarball":"https://registry.npmjs.org/@bytesbrains/pi-agent-supervisor/-/pi-agent-supervisor-1.1.2.tgz","fileCount":21,"integrity":"sha512-RypxROM9/qBVWgpic+O1rm/8NxN333RvflqVqHxUrXLsaCuGp9GitakHAitIrlCvE3zrXYD1i5JdG7l/+TW0AQ==","signatures":[{"sig":"MEQCIAvXc1H60pfBSX5hx8/1v+apRLb+f7cQBNS0KOfYCWRrAiArfn3+yXMl5KMdxJQuWoq9khv377wCcp1uN7tjDMh7Wg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62419},"main":"./src/index.ts","engines":{"node":">=18"},"gitHead":"1fca2cfdcbdf155b60d39efd9495773b47cb49a1","scripts":{"test":"vitest run","test:watch":"vitest"},"_npmUser":{"name":"nandal","email":"sandeep@nandal.in"},"repository":{"url":"git+https://github.com/nandal/pi-ext.git","type":"git","directory":"supervisor"},"_npmVersion":"11.3.0","description":"Runtime safety net for AI agents — blocks dangerous commands, protects files, enforces rate limits, and records sessions.","directories":{},"_nodeVersion":"24.2.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-agent-supervisor_1.1.2_1778871445157_0.9275735956229922","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@bytesbrains/pi-agent-supervisor","version":"1.2.0","keywords":["pi-package","pi-extension","governance","safety","supervisor","rate-limiting","audit-log"],"author":{"name":"nandal","email":"nandal@users.noreply.github.com"},"license":"MIT","_id":"@bytesbrains/pi-agent-supervisor@1.2.0","maintainers":[{"name":"nandal","email":"sandeep@nandal.in"}],"homepage":"https://github.com/nandal/pi-ext/tree/main/supervisor","bugs":{"url":"https://github.com/nandal/pi-ext/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"152502e6f05e5eb19bdd9d00c265be60eef873b1","tarball":"https://registry.npmjs.org/@bytesbrains/pi-agent-supervisor/-/pi-agent-supervisor-1.2.0.tgz","fileCount":21,"integrity":"sha512-LKsT2iBO1IwbLN96RqgpU90n3DyPGq8D+BqE3VCjjnQ4k4NPVIuuYIeI9/AivI1wFp9xD3CqMs8GmVB1+ImJ7w==","signatures":[{"sig":"MEUCIHCRf0DP4H+Js+fEK54s7UfSak0k9rJb2e+a5z9LxExCAiEAvtccMLEd1d2DCoTtw/vnH8dpmAr/D2uCthRki0iNM3k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62952},"main":"./src/index.ts","engines":{"node":">=18"},"gitHead":"dd8d17694ac2dc7b5429ae8171fcf6ea414e0c97","scripts":{"test":"vitest run","test:watch":"vitest"},"_npmUser":{"name":"nandal","email":"sandeep@nandal.in"},"repository":{"url":"git+https://github.com/nandal/pi-ext.git","type":"git","directory":"supervisor"},"_npmVersion":"11.3.0","description":"Runtime safety net for AI agents — blocks dangerous commands, protects files, enforces rate limits, and records sessions.","directories":{},"_nodeVersion":"24.2.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-agent-supervisor_1.2.0_1778881552980_0.20605994782330828","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@bytesbrains/pi-agent-supervisor","version":"1.3.0","keywords":["pi-package","pi-extension","governance","safety","supervisor","rate-limiting","audit-log"],"author":{"name":"nandal","email":"nandal@users.noreply.github.com"},"license":"MIT","_id":"@bytesbrains/pi-agent-supervisor@1.3.0","maintainers":[{"name":"nandal","email":"sandeep@nandal.in"}],"homepage":"https://github.com/nandal/pi-ext/tree/main/supervisor","bugs":{"url":"https://github.com/nandal/pi-ext/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"7c43bc51e85490995770874617e81bcb7bf56f76","tarball":"https://registry.npmjs.org/@bytesbrains/pi-agent-supervisor/-/pi-agent-supervisor-1.3.0.tgz","fileCount":22,"integrity":"sha512-hYDuc4V3HcAslCqXgT2QET9c4r0AR0ep17UY1/MMtvxCIX2lIXTtdQC+yjDaZ7OwaX90N0PQFILgXYqGTNRTNg==","signatures":[{"sig":"MEYCIQDDDrwrMn9FOZHWZcodxCc60clP7ZMh763uMROcBpJSYgIhAM0RzkjM8/UK6lFdCIBiyhjIuRbqEKzv5wDwUUp28bx4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64087},"main":"./src/index.ts","engines":{"node":">=18"},"gitHead":"dd8d17694ac2dc7b5429ae8171fcf6ea414e0c97","scripts":{"test":"vitest run","test:watch":"vitest"},"_npmUser":{"name":"nandal","email":"sandeep@nandal.in"},"repository":{"url":"git+https://github.com/nandal/pi-ext.git","type":"git","directory":"supervisor"},"_npmVersion":"11.3.0","description":"Runtime safety net for AI agents — blocks dangerous commands, protects files, enforces rate limits, and records sessions.","directories":{},"_nodeVersion":"24.2.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-agent-supervisor_1.3.0_1778881813014_0.6069734162086551","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"@bytesbrains/pi-agent-supervisor","version":"1.3.1","description":"Runtime safety net for AI agents — blocks dangerous commands, protects files, enforces rate limits, and records sessions.","keywords":["pi-package","pi-extension","governance","safety","supervisor","rate-limiting","audit-log"],"author":{"name":"BytesBrains Pte Ltd","url":"https://bytesbrains.com"},"repository":{"type":"git","url":"git+https://github.com/bytesbrains/pi-agent-supervisor.git"},"homepage":"https://github.com/bytesbrains/pi-agent-supervisor#readme","bugs":{"url":"https://github.com/bytesbrains/pi-agent-supervisor/issues"},"license":"MIT","main":"./src/index.ts","engines":{"node":">=18"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","typebox":"*"},"pi":{"extensions":["./src/index.ts"]},"scripts":{"test":"vitest run","test:watch":"vitest"},"devDependencies":{"vitest":"^2.0.0"},"_id":"@bytesbrains/pi-agent-supervisor@1.3.1","gitHead":"fd01a9b0ac21181e6fb54fa88ac7cbdb36949017","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-KxDH5pF1fEgxVNrP/fwtXfVvyMIOiUTY23D6kdgni0jznuzgRsIZ4VFL8sdsf4nPNx+qyoL2Sb+1KfyzzrendQ==","shasum":"424b6c820e27450f88d2e216d7838eea217b468a","tarball":"https://registry.npmjs.org/@bytesbrains/pi-agent-supervisor/-/pi-agent-supervisor-1.3.1.tgz","fileCount":22,"unpackedSize":65122,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGdSuzOIfMltCW8HUKsSrsGIRsLffW2yw6qTQjjpQAZuAiAp2+Uf+GQmQ4/3yr6eArGO+Xn2KS+QVesYP8ulI3K7YQ=="}]},"_npmUser":{"name":"nandal","email":"sandeep@nandal.in"},"directories":{},"maintainers":[{"name":"nandal","email":"sandeep@nandal.in"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-agent-supervisor_1.3.1_1783472812248_0.5292468774956536"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-15T18:57:25.080Z","modified":"2026-07-08T01:06:52.564Z","1.1.2":"2026-05-15T18:57:25.310Z","1.2.0":"2026-05-15T21:45:53.121Z","1.3.0":"2026-05-15T21:50:13.166Z","1.3.1":"2026-07-08T01:06:52.429Z"},"bugs":{"url":"https://github.com/bytesbrains/pi-agent-supervisor/issues"},"author":{"name":"BytesBrains Pte Ltd","url":"https://bytesbrains.com"},"license":"MIT","homepage":"https://github.com/bytesbrains/pi-agent-supervisor#readme","keywords":["pi-package","pi-extension","governance","safety","supervisor","rate-limiting","audit-log"],"repository":{"type":"git","url":"git+https://github.com/bytesbrains/pi-agent-supervisor.git"},"description":"Runtime safety net for AI agents — blocks dangerous commands, protects files, enforces rate limits, and records sessions.","maintainers":[{"name":"nandal","email":"sandeep@nandal.in"}],"readme":"# Agent Supervisor for Pi\n\n[![npm version](https://img.shields.io/npm/v/@bytesbrains/pi-agent-supervisor)](https://www.npmjs.com/package/@bytesbrains/pi-agent-supervisor)\n[![license](https://img.shields.io/npm/l/@bytesbrains/pi-agent-supervisor)](./LICENSE)\n\n> Runtime safety net for AI agents — blocks dangerous commands, protects sensitive files, enforces rate limits, and records sessions to an append-only audit log.\n\n## Philosophy\n\nThe other three gates handle *what* agents do (contrib, review, project). The supervisor handles *how* agents do it — in real-time, while they work.\n\n## Install\n\n```bash\npi install npm:@bytesbrains/pi-agent-supervisor\n```\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `supervisor_status()` | Show session stats — rate, errors, blocked calls |\n| `supervisor_log(tail)` | Read audit log (read-only, last N lines) |\n| `supervisor_override(reason)` | Request human override for blocked operation |\n\n## Runtime Protections\n\nThese run **passively on every tool call** — no agent action needed:\n\n| Protection | Default | Behavior |\n|---|---|---|\n| Dangerous commands | 12 patterns | Blocks `rm -rf /`, `git push --force`, `sudo`, fork bombs, etc. |\n| File protection | 6 files + 5 patterns | Blocks writes to `.env`, credentials, SSH keys, secrets |\n| Rate limiting | 50/min warn, 80/min block | Pauses agent if tool call rate exceeds threshold |\n| Error escalation | 3 consecutive | Alerts human after 3+ consecutive errors |\n| Audit logging | Enabled | Append-only log of all tool calls, errors, blocks |\n\n## Configuration\n\nCreate `.supervisorrc.yml`:\n\n```yaml\n# Blocked command patterns (comma-separated regex)\nblockedPatterns: \"rm\\\\s+-rf\\\\s+/,rm\\\\s+-rf\\\\s+~,git\\\\s+push\\\\s+.*--force,sudo,chmod\\\\s+777\"\n\n# Protected files (write blocked)\nprotectedFiles: \".env,.env.local,credentials.json,.claude/settings.local.json,.git/config\"\n\n# Protected file patterns (glob)\nprotectedPatterns: \"*.pem,*.key,id_rsa*,*secret*,*credential*\"\n\n# Rate limiting\nrateLimitPerMinute: 50     # Warn threshold\nrateLimitHardBlock: 80     # Block threshold\n\n# Error escalation\nmaxConsecutiveErrors: 3    # Escalate after this many consecutive errors\n\n# Audit log\nenableAuditLog: true\nauditLogPath: \".supervisor/audit.log\"\n```\n\n## Audit Log\n\nEvery action is recorded to an append-only log:\n\n```\n[2026-05-14T04:00:00.000Z] SESSION_START host=macbook cwd=/project\n[2026-05-14T04:00:01.000Z] CALL bash (rate: 1/min)\n[2026-05-14T04:00:02.000Z] CALL edit (rate: 2/min)\n[2026-05-14T04:00:03.000Z] BLOCK dangerous-cmd: rm -rf /tmp/*\n[2026-05-14T04:00:04.000Z] ERROR bash: command not found (consecutive: 1)\n[2026-05-14T04:00:05.000Z] SESSION_END calls=15 errors=1 blocked=1\n```\n\nThe log is **append-only** — agents cannot modify or delete it.\n\n## Examples\n\n### Blocked: Dangerous Command\n\n```\n→ bash(\"sudo rm -rf /\")\n⛔ Dangerous command blocked (pattern: \"sudo\")\n→ supervisor_override(reason=\"Need to clean deployment directory\")\nHuman confirmation required...\n```\n\n### Blocked: Protected File\n\n```\n→ write(\".env\", \"SECRET=xyz\")\n⛔ Write to protected file blocked: .env\n```\n\n### Rate Limited\n\n```\n⚠️ High tool call rate (55/50 calls/min). Slow down.\n⛔ Rate limit exceeded (85/80 calls/min). Paused.\n```\n\n## Integration\n\nInstall all four gates for full agent governance:\n\n```bash\npi install npm:@bytesbrains/pi-contrib-gate\npi install npm:@bytesbrains/pi-review-gate\npi install npm:@bytesbrains/pi-project-gate\npi install npm:@bytesbrains/pi-agent-supervisor\n```\n\n## License\n\nMIT © [nandal](https://github.com/nandal)\n\n---\n\nBuilt and maintained by [BytesBrains](https://bytesbrains.com) — AI automation & agents, engineered to production standards.\n*The model proposes, code guarantees.*\n","readmeFilename":"README.md"}