oira666_pi-watcher 0.0.7 → 0.0.9

package/EVERGREEN.md

@@ -0,0 +1,61 @@
+## Summary
+- Watcher is a persistent, independent conversation for observing and steering a running main agent.
+- Opening, closing, copying, and picking a model must not prompt or stop either agent.
+- Public touchpoints: extension commands/events/UI, session metadata, tool registration, and Pi RPC.
+- The child wraps exported package-manager implementation methods before extensions load.
+- Main history is read-only input; steering requires human approval and is refused during compaction.
+- Main risks are CLI/resource-loading drift, session identity, lifecycle races, and overlay focus.
+
+## Intent
+Give the human a side conversation without interrupting or duplicating the main agent's work.
+One side session belongs to each main session; reopening and restarting preserve its history/model.
+Observe the supplied main JSONL path and bounded live-tool previews, not source or verification work
+unless explicitly requested. This is a prompt policy, not a sandbox. Never change main model defaults
+or its status bar. Closing the panel leaves the side conversation running.
+
+## Pi integration (public APIs)
+`src/index.ts` registers `/watcher`, session/agent/tool/compaction handlers, and approved
+`sendUserMessage(..., { deliverAs })`. It reads session ID/file/leaf, idle state, and project trust.
+The overlay uses `ctx.ui.custom`, native dialogs, clipboard helpers, themes, and pi-tui components.
+The child registers `live_main_tools`/`steer_main`, adds prompt sections in `before_agent_start`,
+and persists its main-session link using `appendEntry`/session entries.
+RPC supplies prompts, state/history/models, queue clearing, abort, extension dialogs, and settlement.
+The package manifest exposes `src/index.ts`; credentials/settings/resources follow normal Pi loading.
+
+## Internal Pi APIs
+Internal/undocumented coupling is present: `runtime-child.mjs` calls exported CLI `main()` and
+patches `DefaultPackageManager.prototype.resolve` and `resolveExtensionSources`, relying on the
+resolved extension-resource shape (`enabled`, path, source metadata) before imports occur.
+`runtime-args.ts` discovers npm package layouts (`dist/bundle/index.js`, `dist/index.js`, CLI entry).
+There are no direct private Pi module imports or private Pi instance-field accesses in runtime code.
+The `__PI_WATCHER_CHILD__` global and Node IPC protocol belong to Watcher, not Pi.
+Standalone binaries alone cannot supply the importable child runtime.
+
+## Weak points
+Resource/CLI changes can break exclusions, inherited flags, or nested subagent launches.
+Session replacement, reload, startup cancellation, approval, and child exit must release locks/listeners.
+RPC message framing, event names, model persistence, and compaction delivery boundaries matter.
+Inherited extensions can start work/processes; exclusion is essential and permissions remain inherited.
+UI tests simulate terminal components; e2e does not drive an actual interactive PTY or clipboard.
+
+## Tests
+`npm run test:evergreen` runs `npm test` (latest Pi dependencies, TypeScript check, unit/integration),
+then `test/e2e/watcher.test.ts`. No lint script is configured.
+Unit tests cover bounded live state, prompt identity/policy, CLI filtering, JSONL transport, and UI.
+`runtime-integration.test.ts` uses real RPC children and an offline provider to protect prompt-free
+startup, inheritance/exclusions, nested Pi launches, isolated models, resume, approval refusal,
+session guards, locks, shutdown, and recovery. `extension.test.cjs` exercises command → overlay →
+RPC → approval → main delivery, including compaction refusal and shutdown cancellation.
+It also verifies that Watcher registers no keyboard shortcuts and that `/watcher` opens and reopens
+the panel without prompting or losing the side conversation.
+E2E launches `$EVERGREEN_PI_BIN` (or `pi` on PATH) with stdin ignored and uses
+`$EVERGREEN_E2E_MODEL` (required) for real main/side model calls. It verifies reading actual main
+history, live-tool access, unchanged main history, and exact side-history restoration after restart.
+It copies configured auth/models into a temporary agent directory; credentials are never committed.
+The child uses the latest modular npm Pi from devDependencies, even with a standalone global host.
+
+## Relevant changelog topics
+Watch extension loading/package-manager resources, CLI entry/layout/flags, trust and built-in MCP;
+RPC framing/dialogs/settlement; session JSONL/resume/tools and model persistence; steering/compaction;
+TUI key parsing, overlay focus/disposal, and clipboard support. Pi 1.4.0 includes relevant fixes for
+concurrent dialogs and resumed extension-tool activation. Tested against Pi 1.4.0.

package/README.md

@@ -2,7 +2,7 @@
 
 A persistent side-agent conversation for your running [Pi](https://pi.dev) agent.
 
-**Package:** `oira666_pi-watcher` · **Version:** `0.0.6` · **License:** MIT
+**Package:** `oira666_pi-watcher` · **Version:** `0.0.9` · **License:** MIT
 
 ## Install
 
@@ -10,7 +10,9 @@ A persistent side-agent conversation for your running [Pi](https://pi.dev) agent
 pi install npm:oira666_pi-watcher
 ```
 
-Then restart Pi or run `/reload`. Requires Node.js **22.19+** and the modular Pi installation. Tested against **Pi 1.0.4**; the child launcher depends on that version's package-manager loading interfaces. Standalone compiled Pi binaries are not supported.
+Then restart Pi or run `/reload`. Requires Node.js **22.19+** and the modular Pi installation. The child launcher uses Pi's package-manager loading interfaces. Standalone compiled Pi binaries are not supported.
+
+Tested against Pi 1.4.0.
 
 For local development:
 
@@ -23,7 +25,6 @@ pi -e ./src/index.ts
 
 | Command | Action |
 | --- | --- |
-| **Alt+W** | Toggle the Watcher panel without sending a prompt or stopping either agent. |
 | `/watcher` | Create/resume the side agent and show its conversation. **Sends no prompt.** |
 | `/watcher Why is it retrying?` | Open and send exactly that question. |
 | `/watcher model` | Open the side agent's model picker. Does not prompt either agent. |
@@ -36,7 +37,7 @@ The panel opens immediately while the side process initializes its inherited ext
 Inside the overlay:
 
 - Type a question and press **Enter**. Use **Shift+Enter** for a newline.
-- **Alt+W** closes the panel from any Watcher view. Press it again to reopen. **Esc** also returns from chat to the main view without stopping either agent. Conversation, draft, and scroll position are retained.
+- **Esc** closes the conversation view without stopping either agent. In the model picker or an editor, it returns to the previous view. Use `/watcher` to reopen. Conversation, draft, and scroll position are retained.
 - `/model` opens a searchable provider/model picker. Its selection affects **only the side agent** and is persisted in that side conversation. You can change models while the side agent is running, just like in Pi; switching does not abort the current reply.
 - `/stop` cancels only the side agent and clears its queued messages.
 - `/copy` copies to the system clipboard, because terminal mouse selection spans the full terminal width. Messages are numbered in the transcript (`You #n`, `Watcher #n`):
@@ -131,11 +132,17 @@ Closing only the overlay leaves the side agent alive, including any inherited MC
 
 ```sh
 npm ci
-npm run check
-npm test
+mkdir -p tmp
+TMPDIR="$PWD/tmp" npm test
 npm pack --dry-run --ignore-scripts
 ```
 
-Tests use an offline scripted provider; no paid model calls are needed. They exercise the real RPC child, extension inheritance/exclusion, session resume, models, steering, main-extension integration, transport limits, live-tool cleanup, and overlay keyboard/rendering behavior.
+`npm test` installs the direct Pi development dependencies at `@latest` with install scripts disabled, then runs `npm run check` and the tests. Tests target only the latest npm Pi release. Before each release, update the tested version above and the Pi peer dependency baseline after all checks pass. No lint command is configured.
+
+`npm test` uses an offline scripted provider; no paid model calls are needed. These tests exercise the real RPC child, extension inheritance/exclusion, session resume, models, steering, main-extension integration, transport limits, live-tool cleanup, and overlay keyboard/rendering behavior.
+
+For Evergreen, set `EVERGREEN_E2E_MODEL` to a configured `provider/model` and run `npm run test:evergreen`. It runs the suite above plus a real-model e2e test using `EVERGREEN_PI_BIN` (default: `pi` on PATH), with stdin ignored. The e2e host is the global Pi; its Watcher child uses the latest modular npm Pi development dependency. This test makes model calls, requires configured credentials, and checks main-history observation, live-tool access, read-only main history, and side-session restoration. See [EVERGREEN.md](EVERGREEN.md) for compatibility risks and coverage.
+
+These are automated tests, not a manual terminal smoke test. README snippets are not separately executed.
 
 The implementation is in `src/index.ts` (integration), `src/runtime*` (isolated child and RPC/IPC bridge), `src/live-tools.ts`, `src/config.ts`, and `src/ui*` (overlay).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-watcher",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "A persistent side-agent conversation for observing and steering your running Pi agent.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
   "files": [
     "src/",
     "README.md",
+    "EVERGREEN.md",
     "LICENSE",
     "watcher-settings.example.json"
   ],
@@ -35,22 +36,23 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "pretest": "npm install @earendil-works/pi-ai@latest @earendil-works/pi-agent-core@latest @earendil-works/pi-coding-agent@latest @earendil-works/pi-tui@latest --save-dev --ignore-scripts && npm run check",
     "test": "node --test test/*.test.ts test/*.test.cjs",
+    "test:evergreen": "node test/evergreen.mjs",
     "prepack": "npm run check && npm test"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-agent-core": ">=1.4.0",
+    "@earendil-works/pi-ai": ">=1.4.0",
+    "@earendil-works/pi-coding-agent": ">=1.4.0",
+    "@earendil-works/pi-tui": ">=1.4.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.4",
-    "@earendil-works/pi-agent-core": "1.0.4",
-    "@earendil-works/pi-coding-agent": "1.0.4",
-    "@earendil-works/pi-tui": "1.0.4",
-    "@types/node": "^22.19.0",
-    "jiti": "^2.6.1",
-    "typescript": "^5.9.3"
+    "@earendil-works/pi-agent-core": "^1.4.0",
+    "@earendil-works/pi-ai": "^1.4.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
   }
 }

package/src/index.ts

@@ -270,20 +270,6 @@ export default function watcher(pi: ExtensionAPI): void {
   pi.on("session_compact", () => { compacting = false; mainStatus(); });
   pi.on("session_compact_failed", () => { compacting = false; mainStatus(); });
 
-  pi.registerShortcut("alt+w", {
-    description: "Toggle the Watcher panel",
-    handler: async (ctx) => {
-      if (ctx.mode !== "tui" || !ctx.hasUI) return;
-      try {
-        if (side && isCurrent(side) && side.store.state.open) {
-          side.overlay?.abort();
-          return;
-        }
-        await show(await ensure(ctx));
-      } catch (error) { ctx.ui.notify(`Watcher: ${errorText(error)}`, "error"); }
-    },
-  });
-
   /** Copy `pi --session <side session file>` (opens it from any directory) and echo it dimmed. */
   async function copySessionCommand(ctx: ExtensionContext): Promise<void> {
     try {

package/src/ui.ts

@@ -313,11 +313,6 @@ export class WatcherOverlay implements Component, Focusable {
 
 	handleInput(data: string): void {
 		if (this.closed) return;
-		// Focused overlays own input, so the main editor's shortcut cannot close us.
-		if (matchesKey(data, "alt+w")) {
-			this.close("closed");
-			return;
-		}
 		if (this.notice) {
 			this.notice = undefined;
 			this.requestRender();
@@ -397,7 +392,7 @@ export class WatcherOverlay implements Component, Focusable {
 		if (command === "model") this.openPicker(args.trim());
 		else if (command === "stop") this.doStop();
 		else if (command === "copy") this.doCopy(args);
-		else this.setNotice(`Enter send · Shift+Enter newline · PgUp/PgDn scroll · /model [filter] · /stop · ${COPY_USAGE} · Alt+W / Esc close (main agent untouched)`);
+		else this.setNotice(`Enter send · Shift+Enter newline · PgUp/PgDn scroll · /model [filter] · /stop · ${COPY_USAGE} · Esc close (main agent untouched)`);
 	}
 
 	/** Allow local commands while an approval owns the normal input controls. */
@@ -745,7 +740,6 @@ export class WatcherOverlay implements Component, Focusable {
 		else if (inner >= 76) txt = "Enter send · ⇧Enter newline · PgUp/PgDn scroll · /model · /copy · /stop · Esc close";
 		else if (inner >= 50) txt = "Enter send · PgUp/PgDn · /model · /copy · /stop · Esc";
 		else txt = "Enter send · Esc close";
-		txt = `Alt+W close · ${txt}`;
 		return th.fg("dim", ` ${txt}`);
 	}