{"_id":"@bytesbrains/pi-tool-awareness-gate","_rev":"2-a2b0bc0d54612d12bc7d06eab030df6d","name":"@bytesbrains/pi-tool-awareness-gate","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.3":{"name":"@bytesbrains/pi-tool-awareness-gate","version":"1.0.3","keywords":["pi-package","pi-extension","tool-awareness","quality-signals","limitation-detection","agent-protocol","observability"],"author":{"name":"nandal","email":"nandal@users.noreply.github.com"},"license":"MIT","_id":"@bytesbrains/pi-tool-awareness-gate@1.0.3","maintainers":[{"name":"nandal","email":"sandeep@nandal.in"}],"homepage":"https://github.com/nandal/pi-ext/tree/main/tool-awareness-gate","bugs":{"url":"https://github.com/nandal/pi-ext/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"eb99d0e83bf400f8556475c4b489f0eecc9432f2","tarball":"https://registry.npmjs.org/@bytesbrains/pi-tool-awareness-gate/-/pi-tool-awareness-gate-1.0.3.tgz","fileCount":9,"integrity":"sha512-Vm3Pz560Fs6ogdDHdRmjUtG3cmYfsoLwTJZoIYLKnODhYmINjEZqlHb1Oudl+cDnG8/y2TZ6rkyo17StcIedUw==","signatures":[{"sig":"MEUCIQDjXF5W4mcm20B5o3baAfFVSHaraD+82Pf0PKQxqB075QIgRnOIBn/ypmRoFH5qYVPXE3n6sZxczLn625e33jDV8aE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42847},"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":"tool-awareness-gate"},"_npmVersion":"11.3.0","description":"Tool limitation awareness layer for AI agents — intercepts tool results, infers quality signals, injects limitation reminders, and logs structured envelopes for evaluation.","directories":{},"_nodeVersion":"24.2.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-tool-awareness-gate_1.0.3_1778871438872_0.20610867497959573","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@bytesbrains/pi-tool-awareness-gate","version":"1.0.4","description":"Tool limitation awareness layer for AI agents — intercepts tool results, infers quality signals, injects limitation reminders, and logs structured envelopes for evaluation.","keywords":["pi-package","pi-extension","tool-awareness","quality-signals","limitation-detection","agent-protocol","observability"],"author":{"name":"BytesBrains Pte Ltd","url":"https://bytesbrains.com"},"repository":{"type":"git","url":"git+https://github.com/bytesbrains/pi-tool-awareness-gate.git"},"homepage":"https://github.com/bytesbrains/pi-tool-awareness-gate#readme","bugs":{"url":"https://github.com/bytesbrains/pi-tool-awareness-gate/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-tool-awareness-gate@1.0.4","gitHead":"d27586172b308b98f209cd6118308660043431ae","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-PY/UFqmAb2l1Q2oiMhNpBm+qL7uGbhsFNmXyA9ehOt4ZomE8CD/IAF4UzLYrU9YoohyP9ZG3MWoNKNY6W8iIdA==","shasum":"3f8922b5066ed9c9ead403f48bdc1e56dff706c1","tarball":"https://registry.npmjs.org/@bytesbrains/pi-tool-awareness-gate/-/pi-tool-awareness-gate-1.0.4.tgz","fileCount":10,"unpackedSize":44420,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG527R5O5B29WR9NEKr6hy+ZY1/rKKoC0Y9V+l7wKdmQAiBSTwjV9CpIalVB6Qvtg7qrwrFWS8d7D1Gdwee8y3QJ1w=="}]},"_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-tool-awareness-gate_1.0.4_1783472791865_0.36242486519642925"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-15T18:57:18.727Z","modified":"2026-07-08T01:06:32.107Z","1.0.3":"2026-05-15T18:57:19.134Z","1.0.4":"2026-07-08T01:06:32.001Z"},"bugs":{"url":"https://github.com/bytesbrains/pi-tool-awareness-gate/issues"},"author":{"name":"BytesBrains Pte Ltd","url":"https://bytesbrains.com"},"license":"MIT","homepage":"https://github.com/bytesbrains/pi-tool-awareness-gate#readme","keywords":["pi-package","pi-extension","tool-awareness","quality-signals","limitation-detection","agent-protocol","observability"],"repository":{"type":"git","url":"git+https://github.com/bytesbrains/pi-tool-awareness-gate.git"},"description":"Tool limitation awareness layer for AI agents — intercepts tool results, infers quality signals, injects limitation reminders, and logs structured envelopes for evaluation.","maintainers":[{"name":"nandal","email":"sandeep@nandal.in"}],"readme":"# Tool Awareness Gate for Pi\n\n> Intercepts every tool result, infers quality signals, injects limitation reminders into agent context, and logs structured envelopes for evaluation. **Zero code changes required in other gates.**\n\n## Install\n\n```bash\npi install npm:@bytesbrains/pi-tool-awareness-gate\n```\n\nOr add to `.pi/settings.json`:\n\n```json\n{\n  \"packages\": [\"npm:@bytesbrains/pi-tool-awareness-gate\"]\n}\n```\n\n## What It Does\n\nEvery tool your agent calls — bash, read, write, edit, browser, CI, doctor — returns a result. But how reliable is that result? The awareness gate intercepts every `tool_result` event and adds:\n\n| Signal | What It Tells the Agent |\n|---|---|\n| **Status** | `success`, `partial`, `failure`, `timeout`, `unauthorized` |\n| **Confidence** | 0-1 score — how reliable is this result? |\n| **Completeness** | `full`, `partial`, `minimal` — did we get everything? |\n| **Truncation** | Was output cut off? |\n| **Freshness** | How stale is the data? |\n| **Warnings** | Human + agent readable caveats |\n| **Suggestions** | Actionable next steps (\"retry with narrower scope\") |\n\n## How It Works\n\n```\nTool executes → tool_result event fires\n     │\n     ▼\n┌─────────────────────────────┐\n│ 1. Infer quality signals    │  ← heuristic analysis of raw output\n│ 2. Detect limitation flags  │  ← truncated? stale? scoped?\n│ 3. Generate warnings        │  ← \"Output was truncated\"\n│ 4. Format short reminder    │  ← 1-2 line summary\n│ 5. Inject into agent context│  ← prepended to result text\n│ 6. Log rich payload         │  ← .awareness/envelopes.log\n└─────────────────────────────┘\n```\n\n### Short Reminder Example\n\nWhen a tool result has issues, the agent sees:\n\n```\n⚠️ [bash] conf:0% partial truncated\n   • Non-zero exit code: 1 • Output was truncated\n   → Check stderr output for error details before retrying\n\n$ ls /nonexistent\nls: /nonexistent: No such file or directory\n```\n\n### Rich Payload Example\n\nLogged to `.awareness/envelopes.log`:\n\n```json\n{\n  \"timestamp\": \"2026-05-15T10:30:00.000Z\",\n  \"tool\": \"bash\",\n  \"invocation_id\": \"bash-42\",\n  \"status\": \"partial\",\n  \"latency_ms\": 45,\n  \"quality\": {\n    \"confidence\": 0.8,\n    \"completeness\": \"full\",\n    \"freshness\": 0.5,\n    \"accuracy\": 0.8\n  },\n  \"limitations\": { \"truncated\": false },\n  \"warnings\": [],\n  \"suggestions\": []\n}\n```\n\n## Tool-Specific Inference\n\nThe gate has tool-specific heuristics for richer signals:\n\n| Tool | Extra Signals Detected |\n|---|---|\n| `bash` | Exit code, stderr presence, timeout |\n| `read` | Truncation at limit, offset/limit awareness |\n| `write`/`edit` | Bytes written vs expected |\n| `browser_*` | HTTP errors, OCR failures, timeouts |\n| `ci_*` | API errors, Gitea connectivity issues |\n| `doctor_*` | Informational — no warnings |\n\n## Configuration\n\nCreate `.awarenessrc.yml` in your project root (optional — sensible defaults):\n\n```yaml\n# Enable/disable the awareness layer\nenabled: true\n\n# Inject short reminders into agent context\ninjectReminders: true\n\n# Log rich payloads for evaluation\nlogEnvelopes: true\n\n# Where to write envelope logs\nenvelopeLogPath: .awareness/envelopes.log\n\n# Max warnings to include per short reminder (before truncation)\nmaxWarningsInReminder: 3\n\n# Quality thresholds\nthresholds.lowConfidence: 0.5\nthresholds.staleFreshness: 0.3\nthresholds.maxWarningsBeforeCritical: 5\n\n# Tools to skip awareness tracking (comma-separated)\nexcludedTools:\n```\n\n## Architecture\n\n```\ntool-awareness-gate/\n├── package.json\n├── src/\n│   ├── index.ts      ← Hooks pi.on(\"tool_result\"), main orchestration\n│   ├── types.ts      ← ToolResultEnvelope<T>, QualitySignals, LimitationFlags\n│   ├── infer.ts      ← Heuristic inference from raw tool outputs\n│   ├── format.ts     ← Short reminder + rich payload formatters\n│   ├── config.ts     ← .awarenessrc.yml loader\n│   └── helpers.ts    ← Invocation IDs, text extraction, log appending\n└── README.md\n```\n\n## Integration with Other Gates\n\n**No code changes needed.** The awareness gate works at the framework level, intercepting events from all gates automatically.\n\nWhen a gate wants to provide domain-specific quality signals (richer than what inference can detect), it imports the envelope types:\n\n```typescript\nimport type { ToolResultEnvelope } from \"@bytesbrains/pi-tool-awareness-gate/src/types\";\n\n// Gate enriches its own result with domain-specific quality signals\nreturn {\n  content: [...],\n  details: {\n    ...details,\n    _awareness: {\n      quality: { freshness: 0.95 },  // CI just fetched live data\n      limitations: { truncated: false },\n    },\n  },\n};\n```\n\nThe awareness gate will **merge** gate-provided signals with its own inference, preferring the gate's signals when available.\n\n## Benefits\n\n- **More trustworthy agents** — agents know when to doubt results\n- **Better debugging** — structured logs show tool quality over time\n- **Reduced overconfidence** — agents see explicit confidence scores\n- **Progressive adoption** — works automatically, gates enrich when ready\n- **Zero breaking changes** — no modifications to existing tool code\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"}