@jx-grxf/patchpilot 1.0.0 → 1.2.0

package/dist/tui/types.d.ts

@@ -23,4 +23,12 @@ export type AdvisorNote = {
     role: SubagentRole;
     message: string;
 };
+export type ToolTelemetry = {
+    total: number;
+    succeeded: number;
+    failed: number;
+    approvals: number;
+    denied: number;
+    byTool: Partial<Record<AgentToolName | "subagent", number>>;
+};
 export declare const maxTranscriptLines = 300;

package/dist/tui/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tui/types.ts"],"names":[],"mappings":"AAiCA,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tui/types.ts"],"names":[],"mappings":"AA0CA,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC"}

package/docs/architecture.md

@@ -0,0 +1,115 @@
+# Architecture
+
+PatchPilot is split into a small agent core and an Ink terminal interface.
+
+## Components
+
+| Component | Responsibility |
+|---|---|
+| `OllamaClient` | Sends chat requests to the selected Ollama HTTP API and reads host model state |
+| `compute` | Classifies the selected Ollama endpoint as local or remote compute |
+| `subagents` | Runs small planner/reviewer advisor calls before the primary agent loop |
+| `AgentRunner` | Maintains the model loop, work-state transitions, session events, and typed tool calls |
+| `WorkspaceTools` | Provides bounded file, search, patch, Git, test, and shell actions |
+| `SessionStore` | Persists append-only JSONL session events and updates the global session index |
+| `App` | Renders the TUI transcript, approval prompts, status, and prompt input |
+| `systemStats` | Samples CPU and memory usage for the live header telemetry |
+
+## Compute Model
+
+PatchPilot separates the client machine from the compute machine:
+
+- The client machine runs the TUI, reads and writes workspace files, runs Git, and executes tests.
+- The compute machine runs Ollama inference.
+- `/connect` changes only the Ollama compute endpoint. It does not move workspace tools to the remote host.
+- Host discovery checks both the local LAN and reachable Tailscale peers, then verifies each candidate against Ollama's `GET /api/version`.
+- A localhost endpoint is classified as local compute. A LAN endpoint such as `http://192.168.1.50:11434` is classified as remote compute.
+
+This keeps the Windows-desktop-GPU plus MacBook-editing workflow simple: expose Ollama on the Windows machine, connect from the Mac, and keep all file operations local to the Mac workspace.
+
+## Subagents
+
+The first subagent layer is advisory and intentionally small:
+
+| Subagent | Purpose | Tool Access |
+|---|---|---|
+| Planner | Suggests likely files, order of work, and verification steps | None |
+| Reviewer | Calls out risk, missing tests, and platform concerns | None |
+
+Both subagents run as separate model calls before the primary agent starts. Their output is injected as advisory context only; the primary agent must still verify with workspace tools before changing code. This follows the useful part of the opencode `primary` vs `subagent` model without granting background agents write or shell permissions.
+
+## Native App Direction
+
+The target native structure is:
+
+| Layer | Direction |
+|---|---|
+| Core CLI | Keep the TypeScript/Node agent as the sidecar because it already owns tools, Ollama, and safety boundaries |
+| Desktop shell | Use Tauri for macOS and Windows instead of maintaining both Electron and Tauri |
+| Connect | Reuse the same Ollama compute endpoint model in CLI and desktop |
+| Security | Bind any local control server to loopback only and keep remote model traffic explicit |
+
+## Agent Protocol
+
+The first version uses a JSON command envelope instead of provider-specific tool calling. That keeps behavior portable across local models, including models that do not reliably emit native tool calls.
+
+Tool request:
+
+```json
+{
+  "action": "tools",
+  "message": "I need to inspect the project files.",
+  "tool_calls": [
+    {
+      "name": "list_files",
+      "arguments": {
+        "path": "."
+      }
+    }
+  ]
+}
+```
+
+PatchPilot exposes a `ToolSpec` registry for each tool. Specs describe risk, side effects, permission class, and transcript category. Tool calls execute sequentially so approval-gated reads, writes, and shell actions cannot overwrite each other's pending approval state.
+
+Longer runs can also call `update_todo` with a compact task snapshot. The runner stores that state separately from the transcript and the TUI renders it in the lower transcript area, with `in_progress` items animated and `completed` items checked.
+
+Final answer:
+
+```json
+{
+  "action": "final",
+  "message": "The repository is a TypeScript TUI agent..."
+}
+```
+
+## Sessions
+
+Each TUI launch creates a session id. Events are appended to `.patchpilot/sessions/<session-id>.jsonl` in the workspace:
+
+- `session.created`
+- `run.started`
+- `model.request`
+- `tool.requested`
+- `approval.requested`
+- `tool.completed`
+- `run.completed`
+- `run.failed`
+
+The workspace `.patchpilot/` folder is ignored by Git. A global index at `~/.patchpilot/session-index.json` keeps recent sessions discoverable for `patchpilot sessions`, `patchpilot resume`, `/sessions`, and `/resume`.
+
+## Release Publishing
+
+Tagged releases use `.github/workflows/release.yml`. The workflow verifies that `package.json` matches the tag, installs with `npm ci`, runs tests, builds, packs the CLI, publishes `@jx-grxf/patchpilot` to npm, and then creates or updates the GitHub Release with the `.tgz` artifact. Publishing uses the `NPM_TOKEN` repository secret when present and can fall back to npm trusted publishing if the package is configured for GitHub Actions OIDC on npm.
+
+## Safety
+
+The workspace root is resolved once at startup. Every file path is resolved against that root and rejected if it escapes the workspace. Writes and shell commands are blocked by default. In the TUI, risky tools request approval with allow-once, allow-session, or deny decisions. `--apply` and `--allow-shell` remain explicit compatibility switches for users who want global write or shell permission.
+
+## Telemetry
+
+PatchPilot reads Ollama's non-streaming chat metadata for prompt tokens, response tokens, total duration, and generation speed. Gemini reads API `usageMetadata`. Codex OAuth runs `codex exec --json` and parses the `turn.completed.usage` event, including `cached_input_tokens`, so the TUI can show real Codex CLI usage instead of only character-based estimates.
+
+Model discovery is cached in the current TUI session. Prompt execution reuses the known model list when the selected model is already present, avoiding repeated Gemini model-list calls and keeping Codex/Ollama discovery off the hot path.
+
+The TUI also keeps session-level accounting: request count, prompt tokens, cached prompt tokens, output tokens, total tokens, and estimated cost where public API token pricing is known. Local Ollama cost is reported as zero; Codex OAuth cost is shown as an API-price estimate because actual ChatGPT-plan quota handling is external to PatchPilot.

package/docs/gemini-wrapper.md

@@ -29,6 +29,9 @@ Do not paste these values into issues, logs, chats, or commits. `__Secure-1PSID`
 
 ```sh
 patchpilot --provider gemini-wrapper
+patchpilot --provider gemini-wrapper --model flash
+patchpilot --provider gemini-wrapper --model flash-lite
+patchpilot --provider gemini-wrapper --model pro
 ```
 
 Choose `Gemini-Wrapper` in setup. PatchPilot asks for:
@@ -61,6 +64,26 @@ If a pasted `__Secure-1PSIDTS` expires, PatchPilot retries the bridge request on
 
 The default bridge timeout is 180 seconds. `gemini-3-pro` can take longer through the unofficial WebAPI bridge, so PatchPilot gives Pro models at least 240 seconds. For fast local test loops, use `auto`; PatchPilot omits the model parameter and lets Gemini Web pick its current default.
 
+PatchPilot exposes current Gemini Web shortcuts through live bridge discovery:
+
+| PatchPilot model | Bridge behavior |
+| --- | --- |
+| `auto` | omit model and let Gemini Web choose |
+| `flash-lite` | resolve the live Flash-Lite model from `client.list_models()` and pass its `model_id` |
+| `flash` | prefer a live 3.5 Flash descriptor when the bridge exposes it; otherwise fall back to the current Flash descriptor or `gemini-3-flash` |
+| `pro` | resolve the live Pro descriptor when available; otherwise fall back to `gemini-3-pro` |
+| `thinking` | legacy compatibility alias for `gemini-3-flash-thinking` when available |
+
+Gemini Web now presents Denkaufwand/Thinking-Level controls rather than a recommended standalone `thinking` model. The unofficial `gemini_webapi` bridge does not expose that control as a stable PatchPilot option yet, so `/reasoning` reports the limitation instead of pretending to change Web Denkaufwand.
+
+## File Analysis
+
+Gemini-Wrapper file analysis uses the same `gemini_webapi` file pipeline documented by the upstream project: PatchPilot passes the approved file path as `files=[...]` to `GeminiClient.generate_content`. This is used by `inspect_document` for screenshots and images when the managed Python bridge is active, and as a fallback for PDFs/DOCX files when local text extraction cannot produce useful text.
+
+Supported direct file inputs include PNG, JPEG, WebP, GIF, HEIC/HEIF, PDF, and DOCX. PatchPilot still applies its own safety checks first: external absolute paths require file-analysis approval, sensitive paths are blocked, and browser cookie stores are never auto-scanned.
+
+By default, Gemini-Wrapper is tried first for images. PDFs use `pdftotext` first and DOCX is parsed from `word/document.xml` first; provider file analysis is used only when local document extraction fails or returns no useful text. Text/code files are read directly. Images can use local `tesseract` OCR when the user asks for `mode:"local"`/`mode:"ocr"`.
+
 The Python wrapper stores refreshed Google cookies in a PatchPilot-owned cache:
 
 ```text

package/docs/product-context.md

@@ -0,0 +1,43 @@
+# PatchPilot Product Context
+
+PatchPilot is a local-first, permissioned terminal coding agent. It is designed for repository work where the user wants every risky operation to be visible, reviewable, and easy to approve or deny.
+
+## Core Workflow
+
+1. Inspect the workspace with read-only tools.
+2. Keep a visible todo list for multi-step work.
+3. Propose or apply focused edits in build mode.
+4. Request scoped approvals for writes, package scripts, tests, and shell commands.
+5. Show Git diff, run checks, and leave commits or pull requests under the user's control.
+
+## Safety Model
+
+- `plan` mode is read-only.
+- `build` mode can request approvals for writes and shell actions.
+- `bypass` mode removes per-tool approval prompts only after an explicit trusted-workspace confirmation.
+- Session approvals are scoped to a concrete target such as a path, script body, patch hash, or normalized shell command.
+- Secrets, browser profiles, cookies, and credential files are denied by default.
+
+## TUI Surface
+
+- Header: current provider, model, route, mode, and high-level run state.
+- Sidebar: workspace, permissions, machine stats, session telemetry, and advisors.
+- Transcript: compact run log, tool results, todos, and live status.
+- Composer: bounded multiline prompt editor with visible newest input.
+- Command palette: `/models`, `/sessions`, `/connect`, `/doctor`, `/experimental`, and related commands.
+
+## Provider Matrix
+
+- Ollama: local or remote LAN/Tailscale inference.
+- Gemini: official Google Gemini API key.
+- Gemini-Wrapper: opt-in Gemini Web bridge through pinned `gemini_webapi`; Python bridge supports file analysis, HTTP wrapper mode does not.
+- OpenRouter: broad cloud model routing, including free variants.
+- NVIDIA: OpenAI-compatible NVIDIA NIM endpoints.
+- Codex: ChatGPT login through Codex CLI.
+
+## Useful First Questions
+
+- "What can PatchPilot do in this repo?"
+- "Summarize this project and list the safest next fixes."
+- "Find the test commands and explain the release process."
+- "Review the current diff for risky changes."

package/docs/releases/v1.0.1.md

@@ -0,0 +1,25 @@
+# PatchPilot v1.0.1
+
+## Highlights
+
+- Adds real Gemini-Wrapper file analysis for screenshots, images, PDFs, and DOCX files through the managed `gemini_webapi` Python bridge.
+- Adds `create_pdf` and `create_docx` tools so PatchPilot can generate simple text documents from agent output.
+- Adds a live provider-neutral todo panel in the TUI so longer agent runs show pending, active, and completed work.
+
+## Fixed
+
+- Fixed image inspection only returning metadata. With Gemini-Wrapper enabled, `inspect_document` now sends approved image files to Gemini Web as file inputs and returns visual analysis plus extracted visible text.
+- Fixed escaped multiline file writes. `write_file` and line-range `edit_file` now normalize likely double-escaped code/HTML payloads before writing, preventing `\n` and `\"` from landing as literal one-line source.
+- Fixed scanned/image-based PDF handling by falling back to Gemini-Wrapper file analysis when local `pdftotext` cannot extract text.
+- Fixed false-positive image inspection results. If provider analysis fails and no OCR mode was requested, PatchPilot now reports metadata-only analysis as degraded instead of claiming the image was understood.
+- Fixed approval-gated tools appearing stuck after approval by updating the visible run state immediately and executing tool calls sequentially.
+
+## Improved
+
+- Local document analysis is faster by default: PDFs use `pdftotext` and DOCX files are parsed directly before PatchPilot spends provider time. Images still use provider vision in `auto`, while `mode:"ocr"` keeps local OCR explicit.
+- Gemini-Wrapper docs now explain the upstream `files=[...]` pipeline and the supported file formats.
+- Providers can update visible run tasks through `update_todo`, with the active item animated in the transcript panel.
+
+## Pull Requests
+
+- #21 Improve file-edit reliability and Gemini-Wrapper document analysis.

package/docs/releases/v1.1.0.md

@@ -0,0 +1,30 @@
+# PatchPilot v1.1.0
+
+## Highlights
+
+- Adds Gemini-Wrapper document analysis for screenshots, images, PDFs, and DOCX files through the managed `gemini_webapi` bridge.
+- Adds approval-aware file generation tools for simple PDF and DOCX output.
+- Adds visible provider-neutral run todos so longer agent tasks expose pending, active, and completed work in the TUI.
+- Imports Gemini browser-cookie onboarding and model discovery improvements into the stable CLI line.
+
+## Fixed
+
+- Fixed escaped multiline file writes by normalizing likely double-escaped payloads before writing or line-range editing files.
+- Fixed image inspection that only returned metadata by routing approved image inputs through Gemini-Wrapper file analysis when available.
+- Fixed scanned PDF analysis by falling back to provider file analysis when local `pdftotext` cannot extract text.
+- Fixed approval-gated tools appearing stuck after approval by updating visible run state immediately and executing tool calls sequentially.
+- Fixed Gemini-Wrapper transport resets by retrying recoverable network failures.
+- Fixed local agent artifacts and game experiments leaking toward GitHub by ignoring them and removing generated `PATCHPILOT.md` from the tracked tree.
+
+## Improved
+
+- Updated runtime and development dependencies, including Ink, Zod, React, tsx, Vitest, Node types, and TypeScript 6.
+- Updated GitHub Actions to `actions/setup-node@v6` and `actions/github-script@v9`.
+- Added release workflow automation that triggers the website refresh after a GitHub release completes.
+- Kept generated local notes and browser-game experiments local-only via `.gitignore`.
+
+## Pull Requests
+
+- #21 Improve file-edit reliability and Gemini-Wrapper document analysis.
+- #19 Trigger website rebuild after releases.
+- #10, #11, #12, #13, #14, #15, #16 Dependency and workflow updates.

package/docs/releases/v1.2.0.md

@@ -0,0 +1,28 @@
+# PatchPilot v1.2.0
+
+## Highlights
+
+- Makes the fullscreen shell the stable default, with a compact header, command palette, animated run status, artifacts bar, saved-cost counter, cursor-aware composer, and a `/theme` switch back to the legacy layout.
+- Adds context storage and compaction primitives plus `/context` and `/compact` commands so long sessions can preserve useful workspace state without replaying noisy transcripts.
+- Adds composable ultra modes: `ultramaxx`, `ultrafast`, `ultracheap`, `ultrafocus:<path>`, and `ultraloop`, with conflict checks and visible keyword styling.
+- Adds first-run preferences for default mode, reasoning, thinking budget, and subagents, plus a use-at-your-own-risk acceptance step before onboarding continues.
+- Adds Windows hardening for clipboard image paste, path/attachment parsing, Codex CLI launcher resolution, and Gemini-Wrapper bootstrap commands.
+
+## Fixed
+
+- Hardened shell approvals so pipes remain supported, `&&` and `;` are available only through `/experimental shell-metacharacters`, and redirects, expansion, background jobs, OR chains, multiline commands, and glob expansion require explicit approval even in build+bypass.
+- Fixed `/write on` and `/shell on` so they no longer bypass the trusted-workspace confirmation panel.
+- Fixed fake success for unknown `/experimental` flags by validating supported flags before persisting settings.
+- Fixed external-file approval bypass behavior, shell path guards, attachment context handling, and secret/path checks around workspace tools.
+- Fixed Gemini-Wrapper re-auth flows so expired cookies can trigger an approval-style refresh panel and failed prompts can retry after refresh.
+- Fixed provider retry behavior, todo-only/fake final handling, TUI prompt handling, composer cursor behavior, run-status randomization, and overlay layout clipping.
+
+## Improved
+
+- Refreshes README guidance for the default shell, ultra modes, context commands, shell-metacharacter controls, onboarding disclaimer, remote host setup, and the current safety model.
+- Refreshes the npm lockfile with `npm update` and keeps the package verification surface aligned with the current dependency graph.
+- Adds broader Vitest coverage for context storage, compaction, shell guards, command help, layout math, clipboard, attachments, provider retry helpers, ultra modes, and Windows-oriented path behavior.
+
+## Pull Requests
+
+- #23 PatchPilot deep-dive hardening and context system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jx-grxf/patchpilot",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "private": false,
   "description": "Local-first coding agent TUI for visible, permissioned repo changes.",
   "type": "module",
@@ -10,7 +10,9 @@
   "files": [
     "dist",
     ".env.example",
+    "docs/architecture.md",
     "docs/gemini-wrapper.md",
+    "docs/product-context.md",
     "docs/releases",
     "docs/showcase/patchpilot-banner.png",
     "docs/showcase/patchpilot-logo.png",
@@ -60,7 +62,7 @@
     "@types/node": "^24.10.0",
     "@types/react": "^19.2.6",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
+    "typescript": "6.0.3",
     "vitest": "^4.1.5"
   },
   "engines": {