pi-jar 0.1.0

package/docs/PLAN.md

@@ -0,0 +1,68 @@
+# pi-jar roadmap
+
+## Goal
+
+A polished Pi package where the agent's work is visible at a glance, motion communicates useful state, and the core workflows (planning, goals, roles) are enforced rather than merely suggested.
+
+## Principles
+
+1. **State first.** You should always know what is running, what is waiting on you, and what is done or failed.
+2. **Motion has meaning.** Animate only active work or important events; everything works with motion off.
+3. **Enforce through public APIs.** Tool sets, `tool_call` guards, hidden context, `agent_before_settle` continuations and session entries. Never scrape another extension's private data.
+4. **Responsive by default.** Narrow terminals get compact layouts, never wrapped dashboards.
+5. **Low overhead.** Idle pi-jar does not repaint continuously; timers are unref'd and stop with the session.
+
+## Done
+
+### Foundation and visuals
+
+- [x] Pi package manifest; Pi core packages as `"*"` peer dependencies; tested against the latest Pi
+- [x] dark theme with six accent variants; generated with `npm run themes:build`
+- [x] responsive footer (model, effort, session, cwd, context, RAM, cost, quota, goal, roles, branch)
+- [x] pixel-fire welcome flame with embers, sparks, wind and a deterministic frozen frame for motion-off
+- [x] welcome card with workspace, workflow and role state, plus clickable actions (fullscreen) or keyboard hints (regular)
+- [x] persisted visual settings with Appearance, Footer and Pi tabs
+
+### Composer
+
+- [x] rounded frame that keeps autocomplete below it and overflow counts in the borders
+- [x] auto-expanding input (≈60% of the terminal) and click-to-place cursor in fullscreen
+- [x] Ember mascot with moods for idle, blink, generating, tools, dialogs, sleepy, error, goal completion and poke
+- [x] next-prompt suggestions as dim ghost text, accepted with Tab
+
+### Workflows
+
+- [x] plan mode: read-only gating, plan directory write guard, `jar_plan_submit` validation, reminders, split plan view, approve/compact/refine/stop, continue-with role
+- [x] goal mode: task gate, implementor continuation, advisor audit, evidence-based completion, round budget, pause/resume
+- [x] model roles v2: aliases, effort suffixes, custom roles, project overrides, cycle order, split manager
+- [x] `jar_todo` branch-aware checklist and `/jar tasks`
+- [x] `jar_ask` structured questions
+- [x] `/jar history` read-only timeline
+- [x] publisher-driven teammate roles and quota windows
+- [x] change review (`/diff`): per-file baselines, split diff view, accept/revert
+- [x] background shells (`jar_shell`) with watch patterns that wake the agent
+- [x] parallel subagents (`jar_delegate`) on model roles, shown as live teammates
+- [x] composer image chips and prompt history search
+- [x] recent-session gallery on the welcome card and `/jar resume`
+- [x] `implement` role and automatic, manual-choice-respecting role switches
+- [x] advisor: `jar_advisor`, `/advisor`, loop and failure gates
+- [x] `/usage` and `/context` panel; `/jar commit` with the `commit` role
+
+## Next
+
+- [ ] plan view: inline notes per section fed into **Refine**; section delete with undo
+- [ ] goal mode: optional token or time budget alongside the round budget
+- [ ] roles: per-role fallback chains when a model is unavailable
+- [ ] tasks: optional in-progress state, grouping and priorities
+- [ ] presets (minimal / normal / verbose / focus) for the footer
+- [ ] optional light theme, if it keeps the same identity
+- [ ] terminal checks: iTerm2, Ghostty, WezTerm, VS Code, tmux
+- [ ] changelog and release process
+
+## Non-goals
+
+pi-jar does not:
+
+- become a multi-agent orchestrator or own other extensions' task execution;
+- keep a second source of truth for another extension's state;
+- change Pi's native transcript, keybindings or clipboard as a side effect (Pi settings change only when you toggle them in the Pi tab).

package/docs/SHOWCASE.md

@@ -0,0 +1,22 @@
+# Showcase and media
+
+pi-jar's README visual should demonstrate the real TUI rather than a polished mockup that quietly invents capabilities. The canonical demo asset is:
+
+```text
+docs/assets/pi-jar-demo.gif
+```
+
+## What the demo should show
+
+The primary loop should make the product understandable without narration:
+
+- the animated torch-style `π` and natural flame/ember motion;
+- the hopeful welcome message and live workspace card;
+- visible project, session, plan, goal, task and role state when available;
+- the composer and Ember mascot so the welcome screen feels connected to the working UI.
+
+## Capture guidelines
+
+Keep the source capture in a dark terminal using a pi-jar theme. Crop dead time before the UI appears, avoid showing secrets or unrelated desktop chrome, and prefer a short loop over a full recording. The README version should be optimized for quick loading; the original recording can remain outside the repository.
+
+The visual is supporting evidence, not the documentation itself. Every demonstrated feature should still be explained in the README or the focused docs.

package/docs/WORKFLOWS.md

@@ -0,0 +1,141 @@
+# Workflows
+
+pi-jar adds four agent workflows on top of Pi. Each is enforced with Pi's public extension API — active tool sets, `tool_call` guards, hidden context messages, the `agent_before_settle` continuation boundary, and session entries — rather than by prompting alone.
+
+## Plan mode
+
+### Lifecycle
+
+```text
+/plan ──▶ read-only tools + plan role ──▶ agent explores
+            │                                  │
+            │                  writes $TMPDIR/pi-jar/plans/<session>/<slug>-plan.md
+            │                                  │
+            │                   jar_plan_submit({ path }) ──▶ validate ──✗──▶ missing sections returned
+            │                                  │ ✓
+            ▼                                  ▼
+   turn ended without submit          plan view (after the run settles)
+   → hidden reminder (≤ 2/prompt)      approve │ compact+approve │ refine │ stop
+                                               ▼
+                         seed jar_todo, restore tools/model, optional role,
+                         send <plan path="…">full text</plan> as the next prompt
+```
+
+### Enforcement
+
+| Mechanism | Detail |
+| --- | --- |
+| Active tools | Current tools ∩ `read, bash, grep, find, ls, jar_ask`, plus `write`, `edit`, `jar_plan_submit`. The previous set is restored exactly on exit. |
+| `tool_call` guard | Unknown tools fail closed. `bash` must pass the read-only allowlist (no redirection, substitution, globbing or mutating git/find flags). `write`/`edit` must target a `.md` file whose real path (after resolving symlinks on the nearest existing ancestor and on the file itself) is inside the session's plan directory. |
+| Hidden context | Each run gets `[PI-JAR PLAN MODE · READ ONLY]` with the plan directory, the template and the rule to end with `jar_plan_submit`. It is filtered out of context once plan mode ends. |
+| Submission | `jar_plan_submit` reads at most 64 KB, strips control sequences, requires one `#` title and `## Context`, `## Approach` (with numbered/bulleted steps or `###` step headings), `## Critical files` and `## Verification`. Success ends the turn (`terminate`). |
+| Reminder | `agent_before_settle` appends a hidden reminder and continues once — at most twice per user prompt — when a completed turn did not submit. Never after an interrupt or error, and never on top of another extension's continuation. |
+
+### Plan view
+
+`openPlanView` renders a full-height overlay using the shared split frame:
+
+- Left: table of contents from ATX headings (fenced code ignored). A single `#` title becomes the header; content before the first heading is an **Overview** entry; `###` entries are indented. Width is `clamp(round(w × 0.26), 18, 32)`; below 64 columns the sidebar collapses into a `‹ n/m heading ›` pager.
+- Right: the selected section and its subsections rendered with Pi's markdown renderer, scrollable independently.
+- Bottom: actions and the **continue with** role chip (cycles through assigned roles in `cycleOrder`).
+- The view handles clicks and wheel only; press/drag/release fall through to Pi so text selection and copy-on-select keep working.
+
+State (`pi-jar.plan` entries, v2: `enabled`, `steps`, `text`, `path`, `title`) follows the session branch; v1 entries still restore.
+
+## Goal mode
+
+### States
+
+```text
+            /goal <text>
+                 │
+                 ▼
+   ┌──────── active ────────┐
+   │   phase: implement      │◀─── auditor added tasks
+   │     │ all tasks done    │
+   │     ▼                   │
+   │   phase: audit ─────────┼──▶ jar_goal complete (evidence) ──▶ complete
+   └──┬──────────────────────┘
+      │ Esc / error / plan mode / jar_goal block / round budget
+      ▼
+    paused ──/goal resume──▶ active
+    /goal clear ──▶ (dropped)
+```
+
+### Rules
+
+- **Round budget:** each automatic continuation is a round (`round n/max`, default 8). A real user message resets it. Reaching the limit pauses the goal.
+- **Task gate:** with no open task, `write`/`edit` are blocked, and so are shell commands that are not on the read-only allowlist during the implement phase. During the audit, edits are blocked but verification commands are allowed.
+- **Roles per round:** implement rounds run on the `implement` role and the audit round on `advisor` (each only if assigned). The previous model and effort are restored when the run settles.
+- **Completion:** `jar_goal complete` requires the audit phase, no open tasks, and non-empty evidence. It ends the turn, records the evidence, and Ember shows `(★ᴗ★)`.
+- **Context hygiene:** only the newest goal context and continuation messages are kept in the prompt.
+
+Goal events (`pi-jar.goal`, v2: `set`, `status`, `round`) are append-only session entries; v1 `set`/`clear` still replay.
+
+## Model roles
+
+Resolution for a role name:
+
+1. Merge global (`<agent dir>/pi-jar-roles.json`) and project (`<cwd>/.pi/pi-jar-roles.json`) roles; project wins per role.
+2. If the spec is `@other[:effort]`, remember the effort (first one wins) and follow `other`; stop after five hops or on a cycle.
+3. A `provider/model[:effort]` spec resolves through Pi's model registry; activation fails with a notice if the model is unknown or unauthenticated.
+4. An unassigned role "follows the current model" (activating it only labels the footer).
+
+`activateTemporary(role)` returns a restore function that puts back the previous model, effort and active role — used by plan mode (`plan`), approved-plan execution (`implement`), goal rounds (`implement` / `advisor`).
+
+Manual choices win: a model or effort you select yourself (model picker, cycling, `/thinking`) while a temporary role is applied cancels that role's restore, so leaving plan mode or finishing a goal round never overrides it. pi-jar's own switches are not counted as manual.
+
+## Advisor
+
+- Context sent: the newest conversation (≈24k characters; tool results truncated to 1.2k each) plus `git status --short --branch` and `git diff --stat HEAD` (≤4k). No tools run on the advisor's side.
+- `jar_advisor` returns the advice as the tool result. `/advisor [focus]` and the failure gate deliver a visible `pi-jar.advisor` message (steered into a running turn, or queued for the next one when idle).
+- Loop gate: the same tool and input three times within the last eight calls blocks that call and returns the advice as the block reason. Failure gate: three failing tool results in a row. Both share a budget of two consultations per user prompt and are reset by your next message.
+- The advisor model comes from the `advisor` role; unassigned, it is the current model with a fresh context.
+
+## Commit
+
+`/jar commit [note]` reads the staged diff (≤60k characters) and the last eight commit subjects, asks the `commit` role (or the current model) for a message in the same style, and opens it in an editor. Saving commits with `git commit -F`; an empty message cancels. With nothing staged it offers `git add -A`. It never pushes.
+
+## Usage and context panel
+
+- Usage totals come from the assistant messages on the active branch plus pi-jar's side calls (advisor, commit) for this session. Limit bars use the quota lookup that feeds the footer.
+- Context parts are estimated at ~4 characters per token (images ≈1.6k tokens) and scaled to the provider-reported total when known. The autocompact buffer is Pi's compaction reserve (`compaction.reserveTokens`), or 0 when compaction is off. Context files and skills are the ones the last prompt used.
+
+## Next-prompt suggestions
+
+- The `jar_suggest` tool is active only while the pi-jar composer and the suggestions setting are on.
+- Its prompt guidelines ask the agent to call it once, last, when a request is finished; the result ends the turn, so it costs no extra model round.
+- If a completed turn did not suggest, a single hidden reminder asks for one (never while plan or goal automation owns the next step, and never after an interrupt).
+- The suggestion is sanitized to one line (≤ 160 characters) and kept in memory only. It is cleared by your next prompt, a new run, typing, or branch navigation.
+
+## Change review
+
+- A `tool_call` hook records a file's content right before the agent's **first** `edit` or `write` to it (project files only, up to 200 files, 1 MB each, text only). Later edits keep that baseline, so the review always shows everything since the agent started on the file.
+- `/diff` (or <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>D</kbd>) compares the baseline with the file on disk using a line diff with 3 lines of context. Files that are back to their baseline drop out.
+- **Accept** forgets the baseline. **Revert** writes the baseline back (or removes a file the agent created) after a second key press to confirm. Errors are reported and the file stays listed.
+- Baselines live in memory for the session; changes made through `bash` or by you are not tracked.
+
+## Background shells
+
+```text
+jar_shell start {command, watch: "ready|error"}  →  s1 running
+      ↓ output (ANSI stripped, last 2000 lines)
+watch matches  or  process exits  →  pi-jar.shell message  →  agent wakes (or it is queued)
+```
+
+- Each shell runs `/bin/sh -c` in its own process group; `kill` sends SIGTERM to the group, then SIGKILL after 3 s. At most 8 run at once; the 20 most recent are kept.
+- A watch fires once per shell. With `notify: false` nothing wakes the agent; it can still read `output`.
+- In goal mode, starting a shell with a non-read-only command counts as a change and needs an open task, like `bash`.
+
+## Subagents
+
+- `jar_delegate` takes 1–4 tasks. Each runs `pi --mode json -p --no-session --model <role model> [--thinking <effort>] [--tools read,grep,find,ls] "<task>"` in the project directory, with `PI_JAR_CHILD=1`.
+- The model comes from the task's role (default `task`), falling back to `default` and then the current model.
+- Progress (tools used, turns, cost) streams into the tool card; each running subagent is published as a teammate for the welcome TEAM row and footer, and cleared when it ends.
+- Subagents time out after 20 minutes and stop when the turn is aborted. The result lists every report with its role, model and outcome. In goal mode, `write: true` needs an open task.
+
+## Sessions and prompt history
+
+- The welcome loads the three most recent sessions for the project (excluding the current one and empty ones) in the background, reading each file (up to 8 MB) for its latest pi-jar goal and plan title.
+- Clicking a recent row stages `/jar resume N` in the composer (switching sessions needs a command); `/jar resume` alone opens the searchable picker.
+- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd> collects every user prompt in the current session file (all branches, newest first) plus the opening prompt of up to 50 recent sessions, deduplicated, and fuzzy-filters as you type.