{"_id":"@bugabinga/pi-ext-angel","name":"@bugabinga/pi-ext-angel","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bugabinga/pi-ext-angel","version":"0.1.0","type":"module","main":"index.ts","peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","typebox":"*"},"license":"MIT","description":"Structured advisor and command guardrail for Pi.","keywords":["pi","pi-extension"],"gitHead":"a40a427fabf644375d6aab393ae450e15079f5b5","_id":"@bugabinga/pi-ext-angel@0.1.0","_nodeVersion":"26.1.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-MbXK4L9XYZ/Vax09F4AD9oSIA+penkqLc0p5eDfpdozzD7tgFrkqrOmY3t/bdl8GE6QkYLNIHdm0Fa9lxXhdDg==","shasum":"9471b7c3319d3143435b5220f4d5c799ecff6b42","tarball":"https://registry.npmjs.org/@bugabinga/pi-ext-angel/-/pi-ext-angel-0.1.0.tgz","fileCount":5,"unpackedSize":586632,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIApLOv+7etic6uFljWt5XQ7IGVRA3sV2Vwpbr1FkUSPAAiBKNETOwWJa/ubWrnYqyeb0zkhIG/fl7aYDh67V803nnQ=="}]},"_npmUser":{"name":"bugabinga","email":"oliver+npm@bugabinga.net"},"directories":{},"maintainers":[{"name":"bugabinga","email":"oliver+npm@bugabinga.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-ext-angel_0.1.0_1779328324431_0.5359905341706961"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-21T01:52:04.215Z","0.1.0":"2026-05-21T01:52:04.614Z","modified":"2026-05-21T01:52:04.848Z"},"maintainers":[{"name":"bugabinga","email":"oliver+npm@bugabinga.net"}],"description":"Structured advisor and command guardrail for Pi.","keywords":["pi","pi-extension"],"license":"MIT","readme":"# angel\n\nStructured advisor + conditional smarts.\n\nAngel is available only when the active executor model matches a configured executor/advisor pair. By default it auto-injects advice on every 3rd tool error and gates dangerous shell commands once.\n\n## Config\n\n`~/.pi/agent/settings.json`:\n\n```json\n{\n  \"angel\": {\n    \"pairs\": [\n      {\n        \"executor\": \"zai/glm-5.1\",\n        \"advisor\": \"openai-codex/gpt-5.5\"\n      },\n      {\n        \"executor\": \"openai-codex/gpt-5.5\",\n        \"advisor\": \"zai/glm-5.1\"\n      }\n    ],\n    \"maxCallsPerTask\": 4,\n    \"enabled\": true,\n    \"autoOnErrors\": 3,\n    \"policyGate\": \"block\"\n  }\n}\n```\n\nPair fields:\n\n- `executor`: active model required for Angel availability. Matches `provider/model` or bare model id.\n- `advisor`: model Angel calls for advice. Prefer `provider/model`.\n\nIf current model is not listed as an executor, the `angel` tool is removed from active tools. `/angel` also refuses with an unavailable-model error.\n\n## Behavior\n\n- Builds fresh `AngelContextPacket` from current session: user request, system prompt, context usage, recent conversation (last 200 messages), touched files (up to 50, 30k chars each), recent tool errors, missing/truncated-source labels.\n- Calls configured advisor model for active executor.\n- Requires structured JSON-backed `AngelAdvice`.\n- Persists advice via `angel-advice` entries.\n- Injects advice into the agent loop on every `autoOnErrors`-th tool error.\n- Gates dangerous bash once per exact command; retrying the same command proceeds.\n- Keeps semantic guidance in `advisoryOnly`.\n\n## Policy Gates\n\nNo popups. When `policyGate` is `block` (default):\n\n1. Executor attempts dangerous `bash` (`rm -rf`, `sudo`, `git push`, publish, recursive chmod/chown, `dd`, `mkfs`, `curl|sh`, fork bomb)\n2. Angel blocks that exact command once\n3. Angel consults the advisor and returns advice in the block reason\n4. Executor may retry the same command if still correct\n\nThis adds conditional smarts without turning Angel into a permanent permission wall.\n\n## Tool\n\n```javascript\nangel({\n  question: \"What should I validate before editing auth?\",\n  context: \"Extra context not already visible\"\n})\n```\n\n## Commands\n\n- `/angel <question>`: manual advisor consult. Opens full advice in editor.\n- `/angel-policy`: show latest enforceable policy in editor.\n\n## Settings\n\n| Setting | Type | Default | Notes |\n|---|---|---:|---|\n| `pairs` | `{ executor, advisor }[]` | `[]` | Required for availability |\n| `maxCallsPerTask` | number | `4` | Session call budget |\n| `enabled` | boolean | `true` | Disables tool/gates if false |\n| `autoOnErrors` | number | `3` | Auto-consult every Nth failed tool result |\n| `policyGate` | `off\\|block` | `block` | Gate dangerous bash commands once |\n\n## Difference from devil\n\n- `devil`: adversarial stress-test of an idea. User-initiated.\n- `angel`: execution advisor tied to configured executor/advisor pairs, fresh max-context packet, auto-injected advice, dangerous-command gate. Suggests devil only when confidence is low and a concrete decision remains.\n\n## Demo\n\n<!-- demo:advisor_suite:start -->\n![Advisor suite](assets/advisor_suite.gif)\n<!-- demo:advisor_suite:end -->\n","readmeFilename":"README.md","_rev":"1-4eb765590995b7b485f463d05287b3eb"}