oira666_pi-watcher 0.0.6 → 0.0.8

package/EVERGREEN.md

@@ -0,0 +1,59 @@
+## Summary
+- Watcher is a persistent, independent conversation for observing and steering a running main agent.
+- Opening, toggling, 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`, Alt+W, 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.
+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

@@ -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:
 
@@ -27,6 +29,7 @@ pi -e ./src/index.ts
 | `/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. |
+| `/watcher command` | Copy `pi --session <side session file>` to the clipboard so you can open the watcher conversation in another terminal (works from any directory). |
 
 These are human-facing TUI controls, not tools exposed to the main agent. They work while the main agent is running, including during compaction.
 
@@ -130,11 +133,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.6",
+  "version": "0.0.8",
   "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

@@ -1,10 +1,11 @@
-import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { copyToClipboard, getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadSettings } from "./config.ts";
 import { LiveTools } from "./live-tools.ts";
 import {
   isWatcherChildProcess, messagesToTranscript, WatcherRuntime,
   type UiDialogRequest, type UiDialogResponse, type WatcherRuntimeEvent,
 } from "./runtime.ts";
+import { deriveSideSessionId, findSideSessionFile, formatSideSessionCommand } from "./runtime-args.ts";
 import { openWatcherUI, WatcherStore, type WatcherController } from "./ui.ts";
 
 interface Side {
@@ -283,10 +284,24 @@ export default function watcher(pi: ExtensionAPI): void {
     },
   });
 
+  /** Copy `pi --session <side session file>` (opens it from any directory) and echo it dimmed. */
+  async function copySessionCommand(ctx: ExtensionContext): Promise<void> {
+    try {
+      const id = ctx.sessionManager.getSessionId();
+      const running = side && side.id === id ? side.runtime.info?.sideSessionFile : undefined;
+      const file = running ?? findSideSessionFile(loadSettings(getAgentDir()).sessionDir, deriveSideSessionId(id));
+      if (!file) { ctx.ui.notify("Watcher: no side session yet for this session. Open /watcher first.", "warning"); return; }
+      const command = formatSideSessionCommand(file);
+      await copyToClipboard(command);
+      ctx.ui.notify(`command copied: ${command}`, "info");
+    } catch (error) { ctx.ui.notify(`Watcher: could not copy command: ${errorText(error)}`, "error"); }
+  }
+
   pi.registerCommand("watcher", {
-    description: "Open the side agent; /watcher <question> to ask; /watcher model to choose its model",
+    description: "Open the side agent; /watcher <question> to ask; /watcher model to choose its model; /watcher command to copy a `pi --session` command for another terminal",
     handler: async (args, ctx) => {
       if (ctx.mode !== "tui") { ctx.ui.notify("/watcher is a human-only interactive terminal command.", "warning"); return; }
+      if (args.trim() === "command") { await copySessionCommand(ctx); return; }
       try {
         const s = await ensure(ctx);
         const question = args.trim();

package/src/runtime-args.ts

@@ -3,7 +3,8 @@
  * main-session header verification, pi package discovery.
  */
 
-import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { BRIDGE_TOOL_NAMES } from "./runtime-protocol.ts";
 
@@ -21,6 +22,30 @@ export function deriveSideSessionId(mainSessionId: string): string {
 	return `watcher-${cleaned}`.slice(0, 200).replace(/[^A-Za-z0-9]+$/, "");
 }
 
+/**
+ * One-line shell command that opens the side session in another terminal: `pi --session <file>`.
+ * A file path (not an id) opens that exact session from any directory; pi switches to the
+ * session's cwd. The home directory is shown as `~` when that stays shell-safe, else single-quoted.
+ */
+export function formatSideSessionCommand(sessionFile: string, home = homedir()): string {
+	const safe = /^[A-Za-z0-9_@%+=:,./-]+$/;
+	let path = sessionFile;
+	if (home && path.startsWith(`${home}/`) && safe.test(path.slice(home.length))) path = `~${path.slice(home.length)}`;
+	else if (!safe.test(path)) path = `'${path.replace(/'/g, `'\\''`)}'`;
+	return `pi --session ${path}`;
+}
+
+/** Existing side session file `<timestamp>_<id>.jsonl` in a flat session dir, newest first. */
+export function findSideSessionFile(sessionDir: string, sideSessionId: string): string | undefined {
+	try {
+		const suffix = `_${sideSessionId}.jsonl`;
+		const hit = readdirSync(sessionDir).filter((f) => f.endsWith(suffix)).sort().pop();
+		return hit ? join(sessionDir, hit) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 export function isValidSessionId(id: string): boolean {
 	return /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(id);
 }