shariq-pi-extensions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shariq Riaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# Shariq's Pi extensions
+
+Cross-platform extensions and operating skills for the Pi coding agent. Credentials and runtime state stay on each machine and are never bundled with the package.
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:shariq-pi-extensions
+```
+
+Or install the latest source from GitHub:
+
+```bash
+pi install git:https://github.com/shariqriazz/shariq-pi-extensions
+```
+
+Run `/reload` in an existing Pi session after installation; new sessions load the package automatically.
+
+## Included extensions
+
+The package contains:
+
+- Antigravity provider
+- structured user questions
+- managed background terminals
+- copy-all transcript support
+- Factory OAuth and rotating API-key provider
+- Firecrawl search and scraping
+- Git status UI
+- persistent task goals
+- dedicated multi-agent orchestration
+- Pi Memory
+- per-response TPS, TTFT, elapsed-time, and output status
+- Context Usage display
+- small shell and command shortcuts
+- Pi subagents
+- lightweight URL fetching
+
+The package also includes the `ember-warm-dark` TUI theme and declares the `background-terminals`, `orchestration`, and `subagents` skills so Pi loads their operating guidance automatically. Pi reads them from the installed package; duplicating files under `<agent-dir>/skills` is unnecessary and would leave stale copies after removal.
+
+See [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) for commands, tools, configuration, and external dependencies.
+
+## Enable or disable extensions
+
+Open Pi's package configuration UI:
+
+```bash
+pi config
+```
+
+Toggle individual resources, including Pi Memory, save, and run `/reload`. Disabling Pi Memory stops capture and injection without deleting its database under `<agent-dir>/pi-memory/`. Remove the installed package to disable the whole suite:
+
+```bash
+pi remove npm:shariq-pi-extensions
+```
+
+For a Git installation, use `pi remove git:https://github.com/shariqriazz/shariq-pi-extensions`.
+
+## Pi Memory
+
+Pi Memory lives at [`extensions/pi-memory`](extensions/pi-memory) inside the same package as every other extension. Use `pi config` to enable or disable it independently; no second package installation is required. Its runtime database remains under `<agent-dir>/pi-memory/` whether the extension is enabled or disabled.
+
+## Update
+
+```bash
+pi update --extensions --no-approve
+```
+
+An npm installation follows published versions. An unpinned Git installation follows the repository's default branch; a source pinned to a tag or commit remains fixed until its reference is changed explicitly.
+
+## Machine-local configuration
+
+The repository never contains credentials. Configure authentication separately on each machine through Pi login, environment variables, or the service's normal credential store.
+
+Runtime files use Pi's active agent directory rather than a fixed home or checkout path. This keeps the same package usable on macOS and Linux and prevents updates from overwriting state.
+
+## Development
+
+```bash
+mise install --locked
+mise exec --locked -- npm ci
+mise exec --locked -- npm run validate
+mise exec --locked -- npm run pack:inspect
+```
+
+See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for repository workflow and release checks, and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for package boundaries.
+
+## Credits and license
+
+Parts of this suite began with work by [Ben Davis](https://github.com/davis7dotsh) and [Thomas Mustier](https://github.com/tmustier). See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for details.
+
+Released under the [MIT License](LICENSE).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+This package includes substantial local changes to work that began in two public Pi setups.
+
+## Ben Davis
+
+Several early extensions and shared patterns were adapted from [Ben Davis's `davis7dotsh/my-pi-setup`](https://github.com/davis7dotsh/my-pi-setup), including work around user questions, background terminals, transcript copying, Firecrawl tools, Git status, and subagents. The implementations in this package have since been reorganized and extended, but Ben's setup was the starting point for those parts.
+
+## Thomas Mustier
+
+`extensions/context-usage` is derived from `pi-contextimate` in [Thomas Mustier's `tmustier/pine-of-glass`](https://github.com/tmustier/pine-of-glass). That work is distributed under the MIT License. Its original copyright and license text are preserved in [`extensions/context-usage/LICENSE`](extensions/context-usage/LICENSE).

package/docs/ARCHITECTURE.md

@@ -0,0 +1,54 @@
+# Architecture
+
+Last verified: 2026-08-21
+
+## Package boundary
+
+The repository has one Pi package boundary at its root. Every extension, including Pi Memory, is an independently declared resource in `package.json#pi.extensions`. Pi therefore loads only intentional extension factories, and `pi config` can toggle each one without separate installation.
+
+## Source layout
+
+```text
+extensions/<name>/index.ts       suite extension entrypoints
+extensions/<name>/src/           extension-owned implementation
+extensions/shared/               runtime helpers shared across extensions
+skills/                          operating guidance paired with async extensions
+docs/                            package-level maintenance documentation
+scripts/                         repository validation helpers
+```
+
+Extension entrypoints register tools, commands, providers, events, or UI. Shared code stays in `extensions/shared` only when more than one extension owns the behavior. Provider-specific protocol and authentication code remains inside its provider directory. The background-terminal, orchestration, and subagent skills ship beside their extensions so a new machine receives the required lifecycle guidance with the tools.
+
+## Dependency model
+
+Pi-owned packages and `typebox` are optional peer dependencies at runtime. Pi supplies them when it loads the package. Exact versions are development dependencies so local typechecking and tests use a reproducible API surface.
+
+Third-party runtime dependencies are normal package dependencies:
+
+- `@lydell/node-pty` powers managed background terminals;
+- `effect` powers subagent lifecycle and coordination;
+- `ws` powers Factory's Responses WebSocket transport.
+
+The repository uses one root manifest and lockfile for the full extension suite.
+
+## Runtime state
+
+Installed package directories are treated as immutable. Extensions resolve writable state through Pi's APIs:
+
+- Factory key selection, Droid metadata, and throttled per-credential limit cache: `<agent-dir>/factory/`
+- Pi Memory state: `<agent-dir>/pi-memory/`
+- Subagent configuration and catalog: paths derived from `getAgentDir()`
+- Orchestration settings and run ledgers: `<agent-dir>/orchestration/`
+- project configuration: paths derived from Pi's `CONFIG_DIR_NAME`
+
+Credentials remain in Pi auth storage, environment variables, service credential stores, or ignored machine-local files. Package source never contains an API key, OAuth token, database, cache, or session.
+
+## Portability
+
+Runtime paths use `node:path`, `getAgentDir()`, `CONFIG_DIR_NAME`, `os.homedir()`, and platform checks where service credential locations differ. Code must not assume `/Users`, `/home`, Homebrew, a particular shell, or a package installation path. Native PTY support is installed through npm for the active Node platform.
+
+## Loading and updates
+
+Pi manages npm and Git package installations and may replace their contents during updates, so user state must never be written beside extension source.
+
+`pi config` controls every individual package resource, including Pi Memory. Disabling Pi Memory leaves its runtime database intact and prevents its extension factory from loading after reload.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,88 @@
+# Development and cutover
+
+Last verified: 2026-08-21
+
+## Requirements
+
+- mise
+- Pi matching the pinned development dependency version
+- platform build support required by `@lydell/node-pty`
+
+Install the exact Node toolchain and dependencies:
+
+```bash
+mise install --locked
+mise exec --locked -- npm ci
+```
+
+## Validation
+
+Validate the complete suite and inspect the package payload:
+
+```bash
+mise exec --locked -- npm run validate
+mise exec --locked -- npm pack --dry-run
+```
+
+The root validation checks TypeScript, runtime tests, declared extension and skill entrypoints, and forbidden runtime files. Inspect the package file list before committing. It must not contain credentials, `.env`, Factory key configuration, caches, databases, sessions, logs, or `node_modules`.
+
+## Adding an extension
+
+1. Add a self-contained directory under `extensions/` with an `index.ts` entrypoint.
+2. Use relative imports for extension-owned code and `extensions/shared` only for genuinely shared behavior.
+3. Put external runtime modules in root `dependencies`.
+4. Add the exact entrypoint to root `package.json#pi.extensions`.
+5. Add focused runtime tests and update `docs/EXTENSIONS.md`.
+6. Run both validations and inspect the package payload.
+
+Do not add nested package manifests or lockfiles to default-suite extensions. The workspace root owns their dependencies and tooling.
+
+## Runtime configuration
+
+Use `getAgentDir()` for user-level state and `CONFIG_DIR_NAME` for project-level Pi configuration. Use `node:path` and explicit platform branches where third-party credential locations differ. Never infer a writable location from `import.meta.url` or the installed package directory.
+
+Keep secrets out of examples and fixtures. Tests should inject temporary roots, fake environment objects, or local test servers rather than reading real credentials.
+
+## Skills paired with extensions
+
+The root manifest declares `skills/background-terminals` and `skills/subagents`. Pi loads them directly from the managed Git package. Do not copy them into the agent directory from install scripts; that would create duplicates and leave stale files after removal.
+
+When either skill changes, validate its structure and keep its behavior aligned with the corresponding extension tools.
+
+## Pi Memory
+
+Pi Memory is a normal root-package resource at `extensions/pi-memory`. It is declared separately in `package.json#pi.extensions`, so `pi config` can enable or disable it without affecting the other extensions. Its database stays under `<agent-dir>/pi-memory/` and must never be stored in the installed package directory.
+
+## Current-machine cutover
+
+Do not remove a working local extension set before the managed package is available.
+
+1. Push and validate the public GitHub repository.
+2. Run `pi install git:https://github.com/shariqriazz/shariq-pi-extensions`; do not reload yet.
+3. Move old auto-discovered extension directories out of the active Pi extension directory so package and local copies cannot load together.
+4. Move the old paired skill directories out of active discovery; the Git package supplies them.
+5. Keep Pi Memory disabled through the package resource filter when memory should remain inactive; preserve its data under `<agent-dir>/pi-memory/`.
+6. Preserve Factory keys and Droid cache under `<agent-dir>/factory/` with restrictive permissions.
+7. Run `/reload` once.
+8. Verify package provenance through `pi list`, then check representative commands, tools, providers, and both packaged skills.
+
+Rollback is the reverse: remove the Git package from Pi settings, restore the local extension and skill directories, and reload. Never delete credentials or databases during rollback.
+
+## Distribution
+
+GitHub hosts the public source and npm distributes versioned releases. Push validated changes to `main` under the repository's normal Git policy.
+
+```bash
+git push origin main
+gh repo view shariqriazz/shariq-pi-extensions --json visibility,url
+```
+
+Before publishing a new npm version:
+
+1. Update `package.json#version` using semantic versioning.
+2. Run `mise exec --locked -- npm ci` and `mise exec --locked -- npm run validate`.
+3. Inspect `mise exec --locked -- npm run pack:inspect` for secrets, runtime state, and accidental files.
+4. Publish with `npm publish --access public --provenance`, or run the `Publish npm package` workflow with `NPM_TOKEN` configured.
+5. Verify the registry version and install it with `pi install npm:shariq-pi-extensions`.
+
+Use npm for stable versioned installs. Use an unpinned Git source for updates directly from `main`, and a tag or commit when a machine should remain fixed to a known revision.

package/docs/EXTENSIONS.md

@@ -0,0 +1,89 @@
+# Extension catalog
+
+Last verified: 2026-08-20
+
+## Providers
+
+### [Antigravity Provider](../extensions/antigravity-provider/README.md)
+
+Registers the `antigravity` provider and `/login antigravity` flow for supported Google Antigravity models. Use `/antigravity.doctor` to inspect non-secret provider status. Credentials remain in Pi auth storage.
+
+### [Factory provider](../extensions/factory-provider/README.md)
+
+Registers one `factory` provider with Factory account OAuth, direct API keys, or rotating API keys. `/factory` opens one full-width dashboard for provider/authentication state, model metadata, rotation status, and authoritative Factory usage across every credential. Standard and Droid Core windows stay separate, percentages are labeled as used, and keys are never aggregated. Rotation applies a monthly → weekly → 5-hour eligibility waterfall, then selects the least recently used eligible key and retains same-request failover for recognized pre-output errors. Background refreshes are throttled to 15 minutes; `r` force-refreshes from the dashboard.
+
+Rotating keys belong in `<agent-dir>/factory/api-keys.json`. Droid metadata cache belongs in `<agent-dir>/factory/droid.json`. Refresh metadata explicitly after upgrading Droid:
+
+```bash
+FACTORY_DROID_REFRESH=1 pi --list-models factory
+```
+
+The curated catalog intentionally excludes `-fast` variants and the removals documented in `extensions/factory-provider/REFRESH_MODELS.md`.
+
+## Agent workflow
+
+### [Structured questions](../extensions/ask-user/README.md)
+
+`ask_user` presents one blocking multiple-choice decision with an optional custom answer. It is intended for decisions that cannot be resolved safely from available context.
+
+### [Goals](../extensions/goal/README.md)
+
+The goal extension adds persistent, branch-safe objectives, progress evidence, budgets, pause/resume controls, and strict completion/blocker gates. Use `/goal` for the operator UI and the `create_goal`, `get_goal`, `update_goal_progress`, and `update_goal` tools for agent-controlled state.
+
+### [Subagents](../extensions/subagents/README.md)
+
+The subagent extension runs flat Pi child agents with profiles, capability policies, continuation, result delivery, optional worktrees, and a dashboard. Configuration lives in `<agent-dir>/subagents.json`; trusted projects may override it through their Pi config directory. The configured concurrency ceiling is 50.
+
+The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement automatically sends a follow-up that starts the next parent turn; status tools are for explicit inspection, not waiting.
+
+### [Orchestration](../extensions/orchestration/README.md)
+
+The Orchestration extension coordinates explicitly requested large tasks through a dedicated orchestrator plus configurable explorer, frontend, backend, general-worker, and reviewer models. `/orchestration` opens the dashboard and `/orchestration settings` configures global role models. It reuses the canonical Subagents runtime, maintains a 10-worker pool per project, isolates Git writers in task worktrees, resumes the original worker for substantial review fixes, and applies final reviewed changes without committing or pushing.
+
+The model-facing `create_orchestration` tool starts planning only after an explicit orchestration request. `get_orchestration` reports status without advancing work. Interrupted runs recover paused under `<agent-dir>/orchestration/`.
+
+### [Background terminals](../extensions/background-terminals/README.md)
+
+Managed PTYs support servers, watchers, long builds, downloads, and interactive processes. The extension tracks up to eight concurrent terminals, retains bounded output, stores full logs in restrictive temporary directories, and stops process groups during shutdown or reload.
+
+Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal automatically sends a completion or failure follow-up and starts the next parent turn. Reading a terminal no longer suppresses that delivery; agents should inspect only for explicit progress requests or immediate interaction.
+
+## Web access
+
+### [Firecrawl web](../extensions/firecrawl-web/README.md)
+
+`web_search` discovers current web, news, images, GitHub, research, and PDF sources. `web_scrape` renders difficult or JavaScript-heavy pages. Authentication resolves from environment variables, the active Pi agent `.env`, or Firecrawl CLI credentials.
+
+### [Web fetch](../extensions/web-fetch/README.md)
+
+`web_fetch` retrieves a known HTTP or HTTPS URL without spending Firecrawl credits. It supports Markdown, text, and HTML output with bounded time and response size.
+
+## Interface and quality of life
+
+### [Context Usage](../extensions/context-usage/README.md)
+
+Displays the estimated prompt and session contribution to the active context window. The default summary is a compact context-budget card; use `Ctrl+O` or `/context-usage` to cycle to compact and expanded audit views.
+
+### [Performance status](../extensions/performance-status/README.md)
+
+Adds a responsive footer-area status row for each assistant message. Live TPS/output are marked as estimates; final TPS uses conventional decode throughput from first streamed token to message completion. TTFT and total elapsed time separately expose provider latency, prefill, and hidden reasoning; output tokens and active tools remain separate.
+
+### [Git info](../extensions/git-info/README.md)
+
+Adds repository state to Pi's interface. `/lg` opens the local Git view and `/pr` exposes pull-request context when available.
+
+### [Copy all](../extensions/copy-all/README.md)
+
+`/copy-all` copies the current conversation in a readable form while omitting tool protocol noise that does not belong in the transcript.
+
+### [Shell shortcuts](../extensions/shell-shortcuts/README.md)
+
+Adds `/exit` as an alias for Pi's normal quit command. Keep this extension limited to small, low-risk conveniences.
+
+## [Persistent memory](../extensions/pi-memory/README.md)
+
+Pi Memory lives at `extensions/pi-memory` as an individually toggleable resource in the main package. It injects bounded relevant memories, queues asynchronous extraction, and stores durable state in SQLite under `<agent-dir>/pi-memory/`. Enable or disable it through `pi config`; disabling it does not delete its data.
+
+## Per-extension details
+
+Implementation-specific behavior and maintenance notes remain next to each extension in its own README. Package-wide installation, dependencies, state boundaries, and release rules belong in the root documentation.

package/extensions/antigravity-provider/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antigravity extension contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/antigravity-provider/README.md

@@ -0,0 +1,23 @@
+# Antigravity Provider
+
+Local persistent Pi provider for Google Antigravity-compatible models.
+
+- Package module: `extensions/antigravity-provider/`
+- Provider id: `antigravity`
+- Login command: `/login antigravity`
+- Doctor command: `/antigravity.doctor`
+
+The provider includes an IPv4 OAuth token-exchange fallback for Node environments where the default request fails. Its deterministic catalog follows Antigravity CLI 1.1.13 model identifiers and runtime behavior.
+
+Current public model IDs:
+- `antigravity/gemini-3.7-flash`
+- `antigravity/gemini-3.6-flash`
+- `antigravity/gemini-3.5-flash`
+- `antigravity/gemini-3.1-pro`
+- `antigravity/claude-sonnet-4-6`
+- `antigravity/claude-opus-4-6`
+- `antigravity/gpt-oss-120b`
+
+Pi's thinking selector is normalized to Antigravity's runtime IDs: Flash models clamp `off`/`minimal` to `low` and `xhigh`/`max` to `high`; Gemini 3.1 Pro clamps to its `low`/`high` pair; Claude and GPT-OSS use their single fixed-thinking runtime regardless of the selected Pi level.
+
+The provider id intentionally remains `antigravity`; existing `~/.pi/agent/auth.json` credentials continue to work without moving secret values. After updating `agy`, compare `agy models` with `antigravity/models.ts` before changing this deterministic catalog.