{"_id":"@aerok/pi-toolkit","_rev":"2-1582266cee4710403538d83975f02a72","name":"@aerok/pi-toolkit","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aerok/pi-toolkit","version":"0.1.0","keywords":["pi-package","pi-extension","pi-coding-agent","toolkit","bark","notifications","encryption","ios","image-paste"],"author":{"name":"wayne1943x"},"license":"MIT","_id":"@aerok/pi-toolkit@0.1.0","maintainers":[{"name":"aerok","email":"rphoho@gmail.com"}],"homepage":"https://github.com/wayne1943x/pi-toolkit#readme","bugs":{"url":"https://github.com/wayne1943x/pi-toolkit/issues"},"pi":{"extensions":["./extensions/bark/index.ts","./extensions/image-placeholders/index.ts"]},"dist":{"shasum":"77930752a6e6f47c723bf478a016f45742d0cb8c","tarball":"https://registry.npmjs.org/@aerok/pi-toolkit/-/pi-toolkit-0.1.0.tgz","fileCount":18,"integrity":"sha512-AQzIQr5c8OEmaka0oRHZ4u5aEcu2hjoMdmZCpGZx+KHBGd4Bc1UuQS+OdK3vHjiuhh2l8v8Rxg+GGBxDit37lA==","signatures":[{"sig":"MEUCIQDW6GhWujRGwGGPOf+7tjtvtGcaD3aYaMCPZCiK4TsZQQIgUULBCSwERMWsMah2wytEvschYzdVe8lL5+3zpGaPzek=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":85957},"type":"module","engines":{"node":">=22.19.0"},"gitHead":"3918f66f93e0f968cf2544dd6c2604c9ae3c9f6a","scripts":{"test":"tsx --test tests/**/*.test.ts","check":"npm run typecheck && npm test","typecheck":"tsc --noEmit"},"_npmUser":{"name":"aerok","email":"rphoho@gmail.com"},"repository":{"url":"git+https://github.com/wayne1943x/pi-toolkit.git","type":"git"},"_npmVersion":"11.12.1","description":"Encrypted Bark notifications and image paste placeholders for Pi","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","typebox":"^1.1.38","typescript":"^6.0.0","@types/node":"^25.0.0","@earendil-works/pi-ai":"^0.84.0","@earendil-works/pi-tui":"^0.84.0","@earendil-works/pi-coding-agent":"^0.84.0"},"peerDependencies":{"typebox":"^1.1.38","@earendil-works/pi-ai":"^0.84.0","@earendil-works/pi-tui":"^0.84.0","@earendil-works/pi-coding-agent":"^0.84.0"},"_npmOperationalInternal":{"tmp":"tmp/pi-toolkit_0.1.0_1788331500461_0.146741682480644","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aerok/pi-toolkit","version":"0.1.1","description":"Encrypted Bark notifications and image paste placeholders for Pi","type":"module","license":"MIT","author":{"name":"wayne1943x"},"repository":{"type":"git","url":"git+https://github.com/wayne1943x/pi-toolkit.git"},"homepage":"https://github.com/wayne1943x/pi-toolkit#readme","bugs":{"url":"https://github.com/wayne1943x/pi-toolkit/issues"},"keywords":["pi-package","pi-extension","pi-coding-agent","toolkit","bark","notifications","encryption","ios","image-paste"],"scripts":{"test":"tsx --test tests/**/*.test.ts","typecheck":"tsc --noEmit","check":"npm run typecheck && npm test"},"pi":{"extensions":["./extensions/bark/index.ts","./extensions/image-placeholders/index.ts"]},"engines":{"node":">=22.19.0"},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","typebox":"*"},"devDependencies":{"@earendil-works/pi-ai":"^0.84.0","@earendil-works/pi-coding-agent":"^0.84.0","@earendil-works/pi-tui":"^0.84.0","@types/node":"^25.0.0","tsx":"^4.21.0","typebox":"^1.1.38","typescript":"^6.0.0"},"gitHead":"94b529d42bbc79f308282eabbb530558326c3575","_id":"@aerok/pi-toolkit@0.1.1","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-fSgEiDKKHxUqdeJS8/nyijLzNJHOILnDznCJKBUZUJpS/5gUxbDnpFqqsDwuhzLqw52k9VguVVGd+X20yIFVvQ==","shasum":"e1369ccdff4202ce590ae4e66a65085a604ceed2","tarball":"https://registry.npmjs.org/@aerok/pi-toolkit/-/pi-toolkit-0.1.1.tgz","fileCount":18,"unpackedSize":89563,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDTC33oLE334pPqa7EAw3xyJR9pC+pWd/fAsROyZYnr4wIgPn8UN9cCXr8VOH6p52MP/53765q2jO24zpPneayE8HI="}]},"_npmUser":{"name":"aerok","email":"rphoho@gmail.com"},"directories":{},"maintainers":[{"name":"aerok","email":"rphoho@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-toolkit_0.1.1_1788332731836_0.21998401115642086"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T06:45:00.244Z","modified":"2026-09-02T07:05:32.115Z","0.1.0":"2026-09-02T06:45:00.587Z","0.1.1":"2026-09-02T07:05:31.969Z"},"bugs":{"url":"https://github.com/wayne1943x/pi-toolkit/issues"},"author":{"name":"wayne1943x"},"license":"MIT","homepage":"https://github.com/wayne1943x/pi-toolkit#readme","keywords":["pi-package","pi-extension","pi-coding-agent","toolkit","bark","notifications","encryption","ios","image-paste"],"repository":{"type":"git","url":"git+https://github.com/wayne1943x/pi-toolkit.git"},"description":"Encrypted Bark notifications and image paste placeholders for Pi","maintainers":[{"name":"aerok","email":"rphoho@gmail.com"}],"readme":"# pi-toolkit\n\nA focused extension pack for [Pi](https://github.com/earendil-works/pi) that adds encrypted Bark notifications and compact image-paste placeholders.\n\n## Features\n\n### Bark notifications\n\n- End-to-end encrypted delivery by default\n- Automatic notification when a Pi task fully settles\n- One-shot 30-second ringing for important tasks\n- LLM-generated completion recaps with a local fallback\n- Global credentials with project-level, non-secret preferences\n- Official `api.day.app` and self-hosted Bark Server support\n- Manual `toolkit_notify` tool for agent-initiated notifications\n- Defense-in-depth secret redaction\n\n### Image paste placeholders\n\n- Replaces clipboard image paths with readable `[Image N]` markers\n- Sends the original images to vision-capable models\n- Restores image associations from session history\n- Cleans up unused temporary clipboard files\n- Wraps existing custom editors instead of replacing them\n\npi-toolkit is independent of UniPi. It does not depend on `@pi-unipi/*`, register `/unipi:*` commands, or use `~/.unipi`.\n\n## Requirements\n\n- Node.js 22.19 or later\n- `@earendil-works/pi-coding-agent` 0.84 or later\n\n## Installation\n\n### npm\n\n```bash\npi install npm:@aerok/pi-toolkit\n```\n\n### GitHub\n\n```bash\npi install git:github.com/wayne1943x/pi-toolkit\n```\n\n### Local checkout\n\n```bash\ngit clone https://github.com/wayne1943x/pi-toolkit.git\ncd pi-toolkit\nnpm install\npi install .\n```\n\nRestart Pi after installation, or run `/reload` in the current session.\n\n## Quick start\n\n1. Run:\n\n   ```text\n   /toolkit:bark-setup\n   ```\n\n2. Paste the test URL shown in the Bark app. The setup wizard extracts the device key.\n3. Configure Bark app encryption with the values generated by the wizard:\n\n   | Bark setting | Value |\n   |---|---|\n   | Algorithm | `AES128` |\n   | Mode | `CBC` |\n   | Padding | `pkcs7` |\n   | Key | Generated 16-character value; press `K` to copy |\n   | IV | Generated 16-character value; press `I` to copy |\n\n4. Send the encrypted test notification.\n5. Confirm activation only if the device displays the readable test sentence. Do not confirm if Bark displays `Decryption Failed`.\n\nThe wizard does not save or activate new encryption credentials until this device-side check succeeds.\n\n## Bark commands\n\n| Command | Description |\n|---|---|\n| `/toolkit:bark-setup` | Configure the Bark server, device key, delivery defaults, and encryption |\n| `/toolkit:bark-test` | Send a test using the active encryption mode |\n| `/toolkit:bark-toggle` | Quickly enable, disable, toggle, or inspect Bark notifications |\n| `/toolkit:bark-encryption-rotate` | Generate and verify a new encryption Key and IV |\n| `/toolkit:bark-urgent` | Toggle continuous ringing for the next completed task only |\n| `/toolkit:bark-notify-settings` | Configure notification events, encryption mode, and recap behavior |\n| `/toolkit:bark-recap-model` | Select the model used to generate completion recaps |\n\nAll Bark commands use the `toolkit:bark-*` namespace so other pi-toolkit extensions can add their own command groups later.\n\n## Quick enable and disable\n\nToggle global Bark notifications with no arguments:\n\n```text\n/toolkit:bark-toggle\n```\n\nUse an explicit action when the desired result must be unambiguous:\n\n```text\n/toolkit:bark-toggle on\n/toolkit:bark-toggle off\n/toolkit:bark-toggle status\n```\n\nAdd `--project` to target the current project's non-secret enabled override:\n\n```text\n/toolkit:bark-toggle --project\n/toolkit:bark-toggle --project on\n/toolkit:bark-toggle --project off\n/toolkit:bark-toggle --project status\n```\n\nEnabling is refused until the inherited Bark server, device key, and encryption credentials are valid. Disabling clears any armed urgent notification. Status reports global, project, and effective values without changing configuration.\n\n## Default completion notification\n\nWhen `agent_settled` fires, pi-toolkit sends:\n\n| Field | Default |\n|---|---|\n| Title | `Pi · <session name>`, or `Pi Toolkit — Task Complete` when unnamed |\n| Body | One-sentence LLM recap, with a local fallback |\n| Group | `Pi` |\n| Sound | `anticipate` |\n| Level | `active` |\n| Encryption | Enabled after encrypted setup is completed |\n\n`agent_settled` runs after Pi has finished retries, continuations, and compaction, making it the most reliable standalone task-completion event.\n\n## Important tasks\n\nBefore submitting an important task, run:\n\n```text\n/toolkit:bark-urgent\n```\n\nThe footer displays:\n\n```text\n☎ next task: 30s ring\n```\n\nThe next `agent_settled` notification includes Bark `call=1`, which repeats the selected ringtone for approximately 30 seconds. The state is then cleared, even if delivery fails, so an unrelated later task cannot ring unexpectedly.\n\nRun the command again before task completion to cancel it. Urgent state is session-only and does not register or override Pi's `/fast` command.\n\n## Encrypted delivery\n\npi-toolkit implements Bark's documented encryption format:\n\n- AES-128\n- CBC mode\n- PKCS#7 padding\n- 16-byte Key\n- 16-byte fixed IV\n- Base64-encoded ciphertext\n\nThe title, body, group, sound, icon, level, and call fields are included in the encrypted JSON payload. Delivery fields required by Bark are also sent outside the ciphertext when necessary for routing and processing.\n\nBark Server and Apple Push Notification service can observe delivery metadata such as the device key, ciphertext, interruption level, and whether continuous ringing was requested. They cannot read the encrypted title or body.\n\nUse the following command to rotate both the Key and IV:\n\n```text\n/toolkit:bark-encryption-rotate\n```\n\nThe old configuration remains active until the new encrypted test is readable on the device and explicitly confirmed.\n\n### Plaintext mode\n\nEncrypted delivery can be disabled globally from:\n\n```text\n/toolkit:bark-notify-settings\n```\n\nDisabling encryption requires a second confirmation because Bark Server and Apple Push Notification service will be able to read notification content. Projects cannot override encryption mode or downgrade themselves to plaintext.\n\n## Automatic events\n\n| Event | Default | Description |\n|---|---:|---|\n| `agent_settled` | On | The task is fully complete |\n| `agent_end` | Off | Every low-level agent response; may be noisy |\n| `session_shutdown` | Off | The Pi session is closing |\n| `ask_user_prompt` | Off | An ask-user extension is waiting for input |\n| `permission_request` | Off | A permission extension is waiting for approval |\n\nConfigure these events with `/toolkit:bark-notify-settings`.\n\n## LLM recap\n\nCompletion notifications use Pi's provider-neutral model adapter to summarize the final assistant response into one sentence.\n\n- Enabled by default\n- Uses the current session model by default\n- A fixed model can be selected with `/toolkit:bark-recap-model`\n- Input is limited to 2,000 characters\n- Output is limited to 100 tokens\n- Requests time out after 10 seconds\n- Model, authentication, network, and empty-output failures fall back to a local sanitized summary\n\nSensitive values are redacted before text reaches the recap model. Model output is sanitized again before encryption and at the Bark transport boundary.\n\n## Agent notification tool\n\nAgents can send an explicit Bark notification through the same global configuration:\n\n```text\ntoolkit_notify({\n  title: \"Build Complete\",\n  message: \"All checks passed.\",\n  priority: \"normal\"\n})\n```\n\nPriority mapping:\n\n| Toolkit priority | Bark level |\n|---|---|\n| `low` | `passive` |\n| `normal` | `active` |\n| `high` | `timeSensitive` |\n\n`high` deliberately does not map to `critical`, avoiding an unexpected bypass of silent or focus modes.\n\n## Configuration\n\n### Global configuration\n\n```text\n~/.pi/agent/pi-toolkit/bark.json\n```\n\nThis file contains the Bark server URL, device key, encryption Key and IV, defaults, and global event settings. It is written atomically with file mode `0600`; its parent directory uses mode `0700`.\n\n### Project configuration\n\n```text\n<project>/.pi/pi-toolkit/bark.json\n```\n\nProject configuration may override non-secret preferences such as enabled state, group, sound, icon, level, events, and recap settings. It cannot contain or override the server URL, device key, encryption mode, encryption Key, or IV.\n\n## Image paste placeholders\n\nPaste an image into the Pi TUI using Pi's standard shortcut:\n\n- macOS and Linux: `Ctrl+V`\n- Windows and WSL: `Alt+V`\n\nInstead of showing a long temporary path, the editor displays:\n\n```text\n[Image 1]\n[Image 2]\n```\n\nThe marker remains in the prompt so it can be referenced naturally, while the corresponding image is submitted as image content.\n\nAdditional behavior:\n\n- Numbering restarts from `[Image 1]` after each successful submission.\n- PNG, JPEG, WebP, and GIF are supported.\n- Session restore and input history reconnect markers to their original images.\n- Removing an unsubmitted marker cleans up its temporary file.\n- Submission is blocked and editor text is restored if the active model does not support image input.\n- Existing custom editor components remain composable.\n\nDo not install a second copy at `~/.pi/agent/extensions/image-placeholders`; duplicate installations would wrap the editor twice.\n\n## Security model\n\n- Notification text is sanitized before recap, before encryption, and at the Bark transport boundary.\n- Redaction covers common passwords, API keys, tokens, authorization headers, private keys, Bark URLs, cloud-token formats, the configured Bark device key, and the configured encryption Key and IV.\n- Matching values are replaced with `[REDACTED]`.\n- Encryption credentials are displayed only in an interactive setup overlay and are not added to the Pi conversation.\n- Copying a Key or IV places a secret on the system clipboard; overwrite it after configuring the Bark app.\n- The Bark device key must still be sent to the configured Bark Server as a routing credential.\n- Redaction is defense in depth, not a guarantee that arbitrary unlabeled secrets can always be recognized. Avoid including credentials in prompts and final responses.\n- Pi extensions execute local code with the user's permissions. Review packages before installation.\n\n## Development\n\n```bash\nnpm install\nnpm run check\nnpm pack --dry-run\n```\n\nThe test suite covers configuration migration, encrypted payload compatibility, secret redaction, setup confirmation, one-shot urgent notifications, Bark API behavior, and image placeholder lifecycle handling.\n\n## License\n\nMIT. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).\n","readmeFilename":"README.md"}