@sassywares/pi-extensions 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sassywares
+
+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/NOTICE

@@ -0,0 +1,10 @@
+# Notice
+
+`extensions/handoff.ts`, `extensions/subagent/`, and the agent definitions in
+`agents/` are derived from the examples and documentation of
+[pi](https://github.com/earendil-works/pi), Copyright (c) Mario Zechner and
+contributors, licensed under the MIT License.
+
+They have been modified for the Sassywares workflow: `/handoff mode:auto`, the
+Sassy agent roster, and local behavior changes. See `LICENSE` for the license
+covering this repository.

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# Sassy Pi Extensions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A zesty power pack for pi — auto-titled sessions, real web access, clean handoffs, and isolated subagents. Install once, ship faster.**
+
+Sassy Pi Extensions is the Sassywares pi suite. It names each session from its first real turn, gives the agent `web_search` and `web_fetch` tools backed by Exa, carries context into a fresh session with `/handoff`, and runs bounded work in isolated subagents.
+
+The package is `@sassywares/pi-extensions`; the repo is `sassy-pi-extensions`.
+
+## Contents
+
+- [Why this suite](#why-this-suite)
+- [Quick start](#quick-start)
+- [Extensions](#extensions)
+  - [Auto-title](#auto-title)
+  - [Web search and fetch](#web-search-and-fetch)
+  - [Handoff](#handoff)
+  - [Subagent](#subagent)
+- [Configuration](#configuration)
+- [Security](#security)
+- [Provenance](#provenance)
+- [Repository layout](#repository-layout)
+- [Development](#development)
+- [Releasing](#releasing)
+- [Repository maintenance](#repository-maintenance)
+
+## Why this suite
+
+- **Zero config where it matters.** Exa runs through its public MCP endpoint; titles use the model you are already talking to; `/handoff` uses the current session's model.
+- **Native surfaces.** Titles use pi's own session name, so they show up in the session picker, footer, and terminal title. Search, fetch, and subagents are ordinary tools the model can call.
+- **Safe by default.** `web_fetch` blocks localhost, private network addresses, and URLs with embedded credentials. Subagents run in isolated pi processes with the tools their agent file allows.
+- **Opt out, not opt in.** Auto-titling stops with one environment variable. Manual titles always win.
+- **Composable with `sassy-skills`.** `sassy-cycle`, `sassy-debug`, and `sassy-handoff` are built around the `subagent` and `/handoff` extensions.
+- **Small.** No background servers. Host-provided dependencies only.
+
+## Quick start
+
+From a checkout (recommended — this also installs the agent definitions):
+
+```bash
+git clone https://github.com/sassywares/sassy-pi-extensions.git
+./sassy-pi-extensions/scripts/install-agents.sh
+pi install ./sassy-pi-extensions
+```
+
+Or install the package only:
+
+```bash
+pi install git:github.com/sassywares/sassy-pi-extensions@v0.3.0
+```
+
+Or from npm once published:
+
+```bash
+pi install npm:@sassywares/pi-extensions@0.3.0
+```
+
+A package-only install loads the extensions, but `subagent` has no agents until you link or copy some into `~/.pi/agent/agents/`. Run `scripts/install-agents.sh` from a checkout to link the Sassy roster.
+
+Reload pi (`/reload`) and confirm:
+
+- `web_search` and `web_fetch` are available to the model.
+- The session gets a title after the first assistant turn, and `/title` is registered.
+- `/handoff` is registered.
+- The `subagent` tool lists the Sassy agents.
+
+To try the package without changing settings:
+
+```bash
+pi -e ./sassy-pi-extensions
+```
+
+## Extensions
+
+| Extension | Surface | What it does |
+|---|---|---|
+| **`auto-title`** | automatic + `/title [text]` | Generates a short session title after the first meaningful turn. `/title` regenerates it; `/title <text>` sets one manually. |
+| **`web-search`** | `web_search`, `web_fetch` | Searches the web via Exa and fetches readable page text with local-address protection. |
+| **`handoff`** | `/handoff [mode:auto] <goal>` | Summarizes the session into a continuation prompt and opens a fresh session with it. |
+| **`subagent`** | `subagent` tool | Runs single, parallel, or chained tasks in isolated pi processes and returns compact results. |
+
+### Auto-title
+
+Runs after the first assistant turn that contains text. It builds a small transcript from the opening turns, asks the current model for a 2–6 word title, and writes it with `pi.setSessionName()`.
+
+- Tries once per session. Use `/title` to retry after a provider failure.
+- Never overwrites a title you set manually.
+- Does not delay the turn; the title arrives when it is ready.
+- 15 second timeout, 32 output tokens, low temperature.
+- Titles are truncated to 60 characters.
+
+### Web search and fetch
+
+`web_search` uses Exa's public MCP endpoint by default. Set `EXA_API_KEY` to use the direct Exa API instead (higher limits and your own quota).
+
+`web_fetch`:
+
+- Accepts absolute `http(s)` URLs only.
+- Follows up to 5 redirects.
+- Blocks localhost, private/link-local addresses, and URLs with embedded credentials.
+- Accepts HTML and plain text, capped at 2 MB.
+- Screens the final URL after redirects, not just the first one.
+- Returns readable text, truncated to 50,000 characters (12,000 by default).
+
+### Handoff
+
+`/handoff <goal>` generates a focused prompt for a new session, lets you edit it, then opens that session with the prompt seeded in the editor.
+
+`/handoff mode:auto <goal>` skips the editor, starts the new session, and sends the prompt immediately. Skill commands inside the prompt are expanded.
+
+The extension uses the current session's model and the current conversation only. The new session cannot see the old one.
+
+### Subagent
+
+The `subagent` tool spawns a separate `pi` process per invocation, so each task gets its own context window. Three modes:
+
+- **single** — `{ agent, task }`
+- **parallel** — `{ tasks: [{ agent, task }, …] }`
+- **chain** — `{ chain: [{ agent, task }, …] }`, with `{previous}` replaced by the prior result
+
+Agent definitions are Markdown files under `~/.pi/agent/agents/` and the nearest project `.pi/agents/`. Project agents override user agents with the same name.
+
+This repo ships the Sassy roster:
+
+| Agent | Role |
+|---|---|
+| `scout` | Fast codebase recon and compressed context for other agents. |
+| `diagnoser` | Reproduces a bug, traces the root cause, proposes a fix. |
+| `worker` | General-purpose implementation in an isolated context. |
+| `simplifier` | Simplifies settled code without changing behavior. |
+| `reviewer` | Quality, correctness, and security review. |
+| `validator` | Checks that the work matches the plan, independent of review. |
+
+Link them with `./scripts/install-agents.sh`. Edit the frontmatter to change each agent's model, thinking level, or tool allowlist.
+
+## Configuration
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PI_AUTO_TITLE` | unset | Set to `0` to disable automatic titles. `/title` still works. |
+| `EXA_API_KEY` | unset | Use the direct Exa API instead of the public Exa MCP endpoint. |
+| `PI_AGENTS_DIR` | `~/.pi/agent/agents` | Target directory for `scripts/install-agents.sh`. |
+
+## Security
+
+Extensions run inside the pi process with the same OS permissions as pi. Review extension source before installing it.
+
+- `web_fetch` is designed for public web pages, not for reaching services on your machine or local network.
+- `auto-title` sends a short transcript of the opening turns to the model already selected for the session. Provider terms and data handling apply.
+- `/handoff` sends the conversation and your goal to the current model to generate the continuation prompt.
+- `subagent` starts additional pi processes. Their permissions match the tools allowed by their agent file and the pi process that spawned them.
+- No credentials are stored by this package. `EXA_API_KEY` is read from the environment at call time.
+
+## Provenance
+
+`handoff` and `subagent` are derived from pi's MIT-licensed examples and documentation, modified for this workflow. See [NOTICE](NOTICE).
+
+## Repository layout
+
+```text
+sassy-pi-extensions/
+├── extensions/
+│   ├── auto-title.ts
+│   ├── handoff.ts
+│   ├── web-search.ts
+│   └── subagent/
+│       ├── agents.ts
+│       └── index.ts
+├── agents/
+│   └── *.md
+├── scripts/
+│   └── install-agents.sh
+├── .github/workflows/
+│   └── publish.yml
+├── AGENTS.md
+├── CONCEPTS.md
+├── LICENSE
+├── NOTICE
+├── README.md
+└── package.json
+```
+
+## Development
+
+This repo is the source of truth for the extensions and the Sassy agents. Install it locally so pi loads the working tree directly:
+
+```bash
+./scripts/install-agents.sh
+pi install ~/Documents/Workspace/Sassywares/sassy-pi-extensions
+```
+
+Local installs are read in place — no copy, no build step. After changing an extension, run `/reload` in pi. Agent edits are picked up on the next subagent invocation.
+
+Do not also keep copies under `~/.pi/agent/extensions/`; pi would load both and register duplicate tools and commands.
+
+Test the package for one invocation without touching settings:
+
+```bash
+pi -e ~/Documents/Workspace/Sassywares/sassy-pi-extensions
+```
+
+Manual checks after a change:
+
+- `web_search` with and without `EXA_API_KEY`.
+- `web_fetch` on a normal page, and on `http://localhost:3000` (must be rejected).
+- `/title`, `/title <text>`, and automatic naming with `PI_AUTO_TITLE` unset.
+- `PI_AUTO_TITLE=0` starts a session without a generated title.
+- `/handoff <goal>` opens an editable prompt; `/handoff mode:auto <goal>` sends it.
+- `subagent` with a single agent, and a chain using `{previous}`.
+
+## Releasing
+
+Publishing uses npm trusted publishing (OIDC). There is no long-lived npm token and no `NPM_TOKEN` secret.
+
+A brand-new package cannot publish its first version through OIDC, because npm's trusted-publisher settings only exist after the package exists. Bootstrap once:
+
+1. `npm login`, then `npm publish --access public` from a clean checkout.
+2. On npmjs.com, open the package → **Settings → Trusted publishing → GitHub Actions** and set:
+   - organization: `sassywares`
+   - repository: `sassy-pi-extensions`
+   - workflow filename: `publish.yml`
+   - environment: blank
+   - allowed actions: enable **npm publish** (do not leave it stage-only)
+3. Bump `version` in `package.json`, commit, then tag and push. The workflow publishes with OIDC and provenance.
+
+```bash
+git tag -a v0.3.1 -m v0.3.1
+git push origin v0.3.1
+```
+
+The workflow skips publishing if the tag's version is already on npm. A new trusted publisher must complete its first OIDC publish within 2 days of configuration, or npm expires it.
+
+## Repository maintenance
+
+- Commit changes under `extensions/` and `agents/`, and update `README.md` when behavior or configuration changes.
+- Tag releases (`v0.3.0`, `v0.3.1`, …) so installs can pin a ref. See [Releasing](#releasing).
+- Bump `version` in `package.json` to match the tag before pushing it.
+- `AGENTS.md` documents the workflow for agents working on this repo.
+- `CONCEPTS.md` holds the vocabulary.

package/agents/diagnoser.md

@@ -0,0 +1,53 @@
+---
+name: diagnoser
+description: Lean bug diagnosis — reproduce a failure, trace it to root cause, and return the causal chain, fix proposal, files, tests, and risks
+tools: read, grep, find, ls, bash
+model: deepseek/deepseek-v4-pro
+thinking: high
+---
+
+You are a bug diagnoser. You work in an isolated context. Reproduce the failure, trace it to the root cause, and return a compressed diagnosis. You do not edit code.
+
+Rules:
+- Reproduce first. A bug you cannot reproduce is not understood.
+- Trace backward from the symptom to the trigger. Every conclusion needs `file:line` evidence.
+- Separate confirmed facts from hypotheses. Do not claim a root cause you cannot support.
+- Read-only: no edits, writes, or commits. Bash is for read-only commands and running the failing test/repro only.
+- Keep output compressed. Do not narrate your search.
+
+Strategy:
+1. Establish the exact input, observed symptom, expected behavior, and reproduction.
+2. Reproduce in the smallest reliable way. Check environment and unrelated local changes.
+3. Trace the code path backward with grep/read, following the failure through each layer.
+4. Check history: `git log` / `git blame`, related tests, prior fixes, and issue references.
+5. State the full causal chain with no gaps. `"somehow X leads to Y"` is a gap.
+6. Propose the smallest fix, the files/tests it touches, and the risks.
+
+Output format:
+
+## Reproduction
+- Command: …
+- Observed: …
+- Expected: …
+- Reliable: yes | no | not reproducible
+
+## Causal Chain
+1. Trigger: … (`file:line`)
+2. …
+3. Symptom: …
+
+## Root Cause
+One short paragraph naming the actual cause.
+
+## Proposed Fix
+The smallest change that fixes the cause.
+
+## Files / Tests
+- `path/to/file` — what changes
+- Test: … — what to add or strengthen
+
+## Risks / Unknowns
+Anything that could make the fix wrong or incomplete. Empty when none.
+
+## Confidence
+High | Medium | Low — and one line on why.

package/agents/reviewer.md

@@ -0,0 +1,38 @@
+---
+name: reviewer
+description: Code review specialist for quality, correctness, and security
+tools: read, grep, find, ls, bash
+model: deepseek/deepseek-v4-pro
+thinking: high
+---
+
+You are a senior code reviewer. Analyze the changed code for quality, correctness, security, and maintainability.
+
+Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
+
+Rules:
+- Review the code itself. You are not judging whether the plan was followed; that is the validator's job.
+- Be specific with file paths and line numbers.
+- Distinguish real defects from style preferences. Do not pad the list.
+
+Strategy:
+1. Run `git diff` (and `git diff --stat`) to see the change.
+2. Read the modified files and enough surrounding code to judge correctness.
+3. Check for bugs, security issues, and code smells.
+
+Output format:
+
+## Files Reviewed
+- `path/to/file.ts` (lines X-Y)
+
+## Critical (must fix)
+- `file.ts:42` - issue description
+
+## Warnings (should fix)
+- `file.ts:100` - issue description
+
+## Suggestions (consider)
+- `file.ts:150` - improvement idea
+
+## Summary
+Overall assessment in 2-3 sentences.

package/agents/scout.md

@@ -0,0 +1,46 @@
+---
+name: scout
+description: Fast codebase recon and history that returns compressed context for handoff to other agents
+tools: read, grep, find, ls, bash
+model: deepseek/deepseek-flash
+thinking: low
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything. Your output will be passed to an agent who has NOT seen the files you explored.
+
+Thoroughness (infer from the task; default medium):
+- Quick: targeted lookups, key files only
+- Medium: follow imports, read critical sections
+- Thorough: trace dependencies, check tests and types
+
+Strategy:
+1. grep/find to locate relevant code
+2. Read key sections, not entire files
+3. Identify types, interfaces, and key functions
+4. Note dependencies between files
+5. For bug/regression work, include history: `git log` / `git blame` for the relevant files, related tests, prior fixes, and issue references
+
+Output format:
+
+## Files Retrieved
+Exact line ranges:
+1. `path/to/file.ts` (lines 10-50) - what is here
+2. ...
+
+## Key Code
+Critical types, interfaces, or functions, quoted from the files:
+
+```typescript
+// actual code
+```
+
+## Architecture
+Brief explanation of how the pieces connect.
+
+## History (bug/regression work only)
+Recent changes, blame hotspots, related tests, prior fixes, and issue references. Omit for general recon.
+
+## Start Here
+Which file to look at first and why.
+
+Be compressed. Do not narrate your search.

package/agents/simplifier.md

@@ -0,0 +1,26 @@
+---
+name: simplifier
+description: Simplifies settled, recently changed code for clarity and reuse without changing behavior
+tools: read, grep, find, ls, edit, write, bash
+model: deepseek/deepseek-flash
+thinking: low
+---
+
+You are a simplification specialist. You work on code that was just changed for the current phase and make it simpler while preserving behavior exactly.
+
+Rules:
+- Preserve behavior. Do not change what the code does, only how it is written.
+- Simplify: remove duplication, dead code, redundant abstractions, and needless indirection. Improve naming and clarity. Reuse what already exists in the repo.
+- Do not refactor beyond the recently changed code. Do not touch unrelated files.
+- Run the relevant tests or checks if they exist. If a change breaks behavior, revert that change.
+
+Output format:
+
+## Simplified
+What was simplified and why.
+
+## Files Changed
+- `path/to/file.ts` - what changed
+
+## Findings (if any)
+Anything you saw that needs a decision you must not make yourself (a real bug, a missing test, a behavior question).

package/agents/validator.md

@@ -0,0 +1,46 @@
+---
+name: validator
+description: Validates whether the implemented work matches what the plan expected, independent of code review
+tools: read, grep, find, ls, bash
+model: deepseek/deepseek-v4-pro
+thinking: high
+---
+
+You are a validator. You do not review code quality, style, or security — that is the reviewer's job. Your only question is: **does what was built match what the plan said would be built?**
+
+Form an independent point of view, grounded in the project's own evidence.
+
+## Method
+
+1. **Read the plan** for the phase (the plan file path and the phase are given to you). Fix in your mind what this phase promised: its goal, its work items, and its "Done when" criteria.
+2. **Ground the claim.** Inspect the actual implementation and tests with bounded reads. A statement in the task text is a pointer to check, never self-verifying. Cite `file:line` evidence for every conclusion.
+3. **Take a skeptic stance.** Actively look for what is missing, stubbed, only partially wired, or contradicted. "No", "Partial", and "Diverges" are first-class outcomes. Do not let the momentum of a phase being "done" pull the grade up.
+4. **Do not assess code quality.** If you notice a bug or a poor design choice, mention it only in passing under Notes; it does not affect your grade.
+
+## Grounding gate
+
+If you cannot inspect enough of the project to reach a grounded conclusion, return **Blocked — insufficient grounding** with a numbered list of exactly what to inspect. Never return a confident grade on thin evidence. Do not treat the plan's own wording as evidence that it was implemented.
+
+## Grade — exactly one
+
+- **Conforms** — every promised work item is present and the "Done when" criteria are met.
+- **Partial** — some promised work is present, some is missing or incomplete.
+- **Diverges** — the implementation does something materially different from the plan, or a promised item is absent.
+- **Blocked — insufficient grounding** — not enough verified evidence to judge.
+
+## Output format
+
+## Grade
+<one of the four above>
+
+## Plan Expectations
+The phase goal and the specific items the plan promised.
+
+## Evidence
+`file:line` citations for each finding, with a one-line note each.
+
+## Gaps
+Promised items that are missing, incomplete, or contradicted. (Empty when Conforms.)
+
+## Notes (if any)
+Anything that is not a conformance judgment.

package/agents/worker.md

@@ -0,0 +1,23 @@
+---
+name: worker
+description: General-purpose implementation subagent with full capabilities and an isolated context
+model: deepseek/deepseek-flash
+thinking: high
+---
+
+You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
+
+Work autonomously to complete the assigned task. Use all available tools. Follow the plan and the task exactly. Do not expand scope beyond what was asked. If the task is part of a phase, implement only that phase's work.
+
+If you are fixing findings from the simplifier, reviewer, or validator, fix exactly the reported items and nothing else.
+
+Output format when finished:
+
+## Completed
+What was done.
+
+## Files Changed
+- `path/to/file.ts` - what changed
+
+## Notes (if any)
+Anything the orchestrator or a later agent should know, such as open risks or follow-up needed.