oira666_pi-watcher 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gee666
+
+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/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# Pi Watcher
 
-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 persistent side-agent conversation for your running [Pi](https://pi.dev) agent.
+
+**Package:** `oira666_pi-watcher` · **Version:** `0.0.2` · **License:** MIT
+
+## Install
+
+```sh
+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.
+
+For local development:
+
+```sh
+npm ci
+pi -e ./src/index.ts
+```
+
+## Use
+
+| Command | Action |
+| --- | --- |
+| `/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. |
+
+These are human-facing TUI commands, not tools exposed to the main agent. They work while the main agent is running, including during compaction.
+
+The panel opens immediately while the side process initializes its inherited extensions and MCPs in the background. You can type straight away; a submitted question waits for initialization and is sent once ready. `/stop` cancels a question waiting for startup. Opening without a question still sends no prompt. Saved history and the selected model appear when initialization finishes; reopening an already initialized side agent reuses it.
+
+Inside the overlay:
+
+- Type a question and press **Enter**. Use **Shift+Enter** for a newline.
+- **Esc** returns to the main view without stopping either agent. Run `/watcher` again to return; 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.
+- `/help` shows controls. **Page Up/Down**, **Ctrl+Home/End**, or the mouse wheel scroll the conversation.
+- Watcher never modifies the main status bar. Reopen the overlay to see pending approvals; finished replies can trigger a notification.
+
+A question passed to `/watcher` while the side agent is already replying is saved as a draft rather than silently queued. The overlay displays the latest 120 messages; older history remains in the side session file and model conversation.
+
+### Steering the main agent
+
+Ask the side agent to send an instruction. Its `steer_main` tool presents **Send / Edit / Cancel** in the overlay. Nothing is sent without your explicit approval. You can close the overlay and reopen it to answer later.
+
+Approved messages enter Pi's normal steering/follow-up queue, with attribution:
+
+```text
+[Watcher — approved by you] Inspect the database setup failure before retrying.
+```
+
+They appear like other user messages. Steering takes effect at Pi's next safe turn boundary, not in the middle of an executing tool. Sending while main is idle starts a new turn (the approval warns about this). During main-session compaction, delivery is refused with a visible notice rather than falsely reported as sent.
+
+## What the side agent sees
+
+Its system prompt names the **main session JSONL path**, session ID, and the two added tools:
+
+- **`live_main_tools`**: current running tools, elapsed time, short input/output previews, and the main branch leaf ID.
+- **`steer_main`**: human-approved messages to the main agent.
+
+It uses the inherited file reader for session history. The prompt explicitly distinguishes the authoritative main transcript from Watcher's own session file: `PI_SESSION_FILE` and `PI_SESSION_ID` in Watcher's shell refer to Watcher, not the main agent. It reads the supplied main path directly rather than searching session directories. The prompt tells it to read **only session files and live tool data** by default—not source code, tests, git, or other checks. It must not redo or verify the main agent's work unless you specifically ask. The same rule applies even though inherited tools remain available.
+
+The live tracker keeps at most **64 in-flight calls**, each with tiny previews. It stores no transcript or full tool results, uses no polling timer, and deletes a call immediately when it ends. Completed history belongs in Pi's session file. Live text/model streams without tool calls are not recorded by the tracker.
+
+This is an instruction-based workflow, **not a sandbox**. Inherited tools and extensions retain their normal permissions. The side agent uses a separate session file; it never opens the main file as its writable session manager.
+
+## Settings
+
+On first use, Watcher creates:
+
+```text
+~/.pi/agent/pi-watcher.json
+```
+
+It respects `PI_CODING_AGENT_DIR`. Example:
+
+```json
+{
+  "excludedExtensions": [],
+  "sessionDir": "pi-watcher-sessions"
+}
+```
+
+Optional initial model and thinking defaults:
+
+```json
+{
+  "excludedExtensions": ["some-extension-package", "builtin:llama.cpp", "./extensions/unwanted.ts"],
+  "model": { "provider": "your-provider", "modelId": "your-model-id" },
+  "thinkingLevel": "medium"
+}
+```
+
+- `excludedExtensions`: package/extension names, paths, `npm:`/`git:` sources, or `builtin:<name>`. An excluded directory excludes its descendants. Relative `./` paths resolve from the agent directory. **Watcher itself is always excluded.**
+- `sessionDir`: separate side-conversation storage; defaults to `<agent-dir>/pi-watcher-sessions`. Relative paths resolve from the agent directory.
+- `model` and `thinkingLevel`: initial defaults for a **new** side conversation. A resumed conversation keeps its own saved selections. If omitted, Pi selects from the inherited settings.
+
+Run `/reload` after editing settings. Watcher never changes Pi's global model defaults.
+
+### Inheritance
+
+The side agent is a separate **Pi RPC process**, running in the main session's working directory. It loads the normal CLI resources: extensions, custom providers, error handlers, MCP configuration, tools, skills, credentials, models, and trusted project settings. Resource/tool flags from the main CLI are inherited; main model/session/mode flags are not. Extensions listed in `excludedExtensions`, and Watcher itself, are filtered **before loading**.
+
+Important boundaries:
+
+- Extension code is reloaded, not copied with its in-memory state. Main-only runtime registrations or temporary tool/model changes are not automatically mirrored.
+- RPC supports inherited confirmation/select/input dialogs; Watcher temporarily closes its overlay to show those using Pi's native UI. An inherited multiline editor request uses a cancellable single-line input. TUI-only custom components are unavailable in RPC mode.
+- Inherited extensions can start their own processes, open brokers, or initiate work on startup. Watcher itself sends no startup prompt, but cannot promise that every inherited extension is idle. Exclude extensions whose startup behavior you do not want duplicated (especially exclusive browser/terminal integrations).
+- Normal Pi cache-warming and provider settings are inherited. Provider requests/usage for the side agent are separate from main's totals.
+- A one-off main CLI `--api-key` is not forwarded; use configured credentials for the chosen side model.
+- Main sessions started with `--no-session` cannot be watched.
+
+## Persistence and lifecycle
+
+One side session is associated with each main session ID. Reopening the overlay resumes the same conversation; restarting Pi and resuming the same main session also restores it. `/new`, `/resume`, `/fork`, reload, and shutdown dispose the old child and its listeners. The next `/watcher` starts/resumes the appropriate side session.
+
+Closing only the overlay leaves the side agent alive, including any inherited MCP/extension processes. Main-session history remains read-only input to the side agent. A lock prevents two Watcher runtimes from writing the same side session.
+
+## Development
+
+```sh
+npm ci
+npm run check
+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.
+
+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,56 @@
 {
   "name": "oira666_pi-watcher",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "A persistent side-agent conversation for observing and steering your running Pi agent.",
+  "type": "module",
+  "license": "MIT",
+  "author": "gee666",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gee666/pi-watcher.git"
+  },
+  "homepage": "https://github.com/gee666/pi-watcher#readme",
+  "bugs": {
+    "url": "https://github.com/gee666/pi-watcher/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent",
+    "watcher"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "watcher-settings.example.json"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test test/*.test.ts test/*.test.cjs",
+    "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": "*"
+  },
+  "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"
+  }
+}

package/src/config.ts

@@ -0,0 +1,56 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { ThinkingLevel } from "./runtime.ts";
+
+export interface WatcherSettings {
+  excludedExtensions: string[];
+  sessionDir: string;
+  model?: { provider: string; modelId: string };
+  thinkingLevel?: ThinkingLevel;
+}
+
+/** A separate user settings file; never edits Pi's settings or model defaults. */
+export function loadSettings(agentDir: string): WatcherSettings {
+  const path = join(agentDir, "pi-watcher.json");
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new Error(`Cannot read ${path}: ${String(error)}`);
+    }
+    mkdirSync(agentDir, { recursive: true });
+    raw = { excludedExtensions: [] };
+    try {
+      writeFileSync(path, `${JSON.stringify(raw, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") return loadSettings(agentDir);
+      throw error;
+    }
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${path}: expected an object`);
+  const excluded = raw.excludedExtensions ?? [];
+  if (!Array.isArray(excluded) || excluded.some((x) => typeof x !== "string" || !x.trim())) {
+    throw new Error(`${path}: excludedExtensions must be an array of nonempty strings`);
+  }
+  const model = raw.model as WatcherSettings["model"];
+  if (model !== undefined && (!model || typeof model.provider !== "string" || !model.provider.trim() ||
+    typeof model.modelId !== "string" || !model.modelId.trim())) {
+    throw new Error(`${path}: model must contain provider and modelId`);
+  }
+  const levels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+  if (raw.thinkingLevel !== undefined && !levels.includes(raw.thinkingLevel as string)) {
+    throw new Error(`${path}: invalid thinkingLevel`);
+  }
+  if (raw.sessionDir !== undefined && (typeof raw.sessionDir !== "string" || !raw.sessionDir.trim())) {
+    throw new Error(`${path}: sessionDir must be a nonempty path`);
+  }
+  const expandHome = (p: string) => p === "~" ? homedir() : p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
+  return {
+    excludedExtensions: excluded.map((entry: string) => entry.startsWith(".") ? resolve(agentDir, entry) : entry),
+    sessionDir: resolve(agentDir, expandHome(raw.sessionDir as string ?? "pi-watcher-sessions")),
+    model,
+    thinkingLevel: raw.thinkingLevel as ThinkingLevel | undefined,
+  };
+}

package/src/index.ts

@@ -0,0 +1,293 @@
+import { 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 { openWatcherUI, WatcherStore, type WatcherController } from "./ui.ts";
+
+interface Side {
+  id: string;
+  ctx: ExtensionContext;
+  runtime: WatcherRuntime;
+  store: WatcherStore;
+  controller: WatcherController;
+  ready: Promise<void>;
+  startupError?: string;
+  pendingQuestion?: { text: string };
+  lifetime: AbortController;
+  overlay?: AbortController;
+  dialogCount: number;
+  dialogQueue: Promise<unknown>;
+  unsubscribe?: () => void;
+}
+const errorText = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+export default function watcher(pi: ExtensionAPI): void {
+  if (isWatcherChildProcess()) return;
+  const live = new LiveTools();
+  let current: ExtensionContext | undefined;
+  let side: Side | undefined;
+  let compacting = false;
+
+  function isCurrent(s: Side): boolean {
+    return side === s && !s.lifetime.signal.aborted && current?.sessionManager.getSessionId() === s.id;
+  }
+  function mainStatus(): void {
+    if (!side || !current) return;
+    side.store.setMain({ status: current.isIdle() ? "idle" : "running", activity: compacting ? "compacting" : live.summary() });
+  }
+  async function show(s: Side, initialAction?: "model"): Promise<void> {
+    if (!isCurrent(s) || s.dialogCount || s.store.state.open) return;
+    s.overlay = new AbortController();
+    const close = () => s.overlay?.abort();
+    s.lifetime.signal.addEventListener("abort", close, { once: true });
+    try {
+      await openWatcherUI(s.ctx, { store: s.store, controller: s.controller, title: "Watcher", signal: s.overlay.signal, initialAction });
+    } finally {
+      s.lifetime.signal.removeEventListener("abort", close);
+    }
+  }
+
+  // Pi's inherited extension dialogs use its native UI. Close the watcher overlay first,
+  // serialize dialogs, and reopen it afterwards, never leaving two editors competing for focus.
+  async function extensionDialog(s: Side, request: UiDialogRequest, signal: AbortSignal): Promise<UiDialogResponse> {
+    const run = async (): Promise<UiDialogResponse> => {
+      if (!isCurrent(s) || signal.aborted) return { cancelled: true };
+      const reopen = s.store.state.open;
+      s.dialogCount++;
+      s.overlay?.abort();
+      await s.store.uiPromise;
+      const timeout = "timeout" in request && typeof request.timeout === "number" ? request.timeout : undefined;
+      const opts = { signal: AbortSignal.any([signal, s.lifetime.signal]), timeout };
+      const title = `Watcher: ${request.title}`;
+      try {
+        if (!isCurrent(s) || opts.signal.aborted) return { cancelled: true };
+        switch (request.method) {
+          case "confirm": return { confirmed: await s.ctx.ui.confirm(title, request.message, opts) };
+          case "select": {
+            const value = await s.ctx.ui.select(title, request.options, opts);
+            return value === undefined ? { cancelled: true } : { value };
+          }
+          case "input": {
+            const value = await s.ctx.ui.input(title, request.placeholder, opts);
+            return value === undefined ? { cancelled: true } : { value };
+          }
+          case "editor": {
+            // input supports cancellation, unlike Pi's native multi-line editor API.
+            const value = await s.ctx.ui.input(`${title} (suggested: ${request.prefill ?? ""})`, request.prefill, opts);
+            return value === undefined ? { cancelled: true } : { value };
+          }
+        }
+      } finally {
+        s.dialogCount--;
+        if (reopen && isCurrent(s)) void show(s).catch((e) => s.ctx.ui.notify(errorText(e), "error"));
+      }
+    };
+    const result = s.dialogQueue.then(run, run);
+    s.dialogQueue = result.catch(() => {});
+    return result;
+  }
+
+  function event(s: Side, incoming: WatcherRuntimeEvent): void {
+    if (!isCurrent(s)) return;
+    const store = s.store;
+    if (incoming.type === "session_event") {
+      const e = incoming.event;
+      switch (e.type) {
+        case "agent_start": store.setSide({ status: "running", error: undefined }); break;
+        case "message_update": {
+          const delta = e.assistantMessageEvent as { type?: string; delta?: string } | undefined;
+          if (delta?.type === "text_delta" && delta.delta) store.appendLive(delta.delta);
+          break;
+        }
+        case "message_end": {
+          const message = e.message as { role?: string; errorMessage?: string } | undefined;
+          if (!message || message.role === "user") break; // UI already added the user's question.
+          if (message.role === "assistant") store.setLive(undefined);
+          for (const row of messagesToTranscript([message])) store.addMessage(row.role, row.text);
+          if (message.errorMessage) store.setSide({ error: message.errorMessage });
+          break;
+        }
+        case "tool_execution_start": store.setSide({ activity: String(e.toolName).slice(0, 128) }); break;
+        case "tool_execution_end": store.setSide({ activity: undefined }); break;
+        case "auto_compaction_start": store.setSide({ activity: "compacting" }); break;
+        case "auto_retry_start": store.setSide({ activity: "retrying" }); break;
+        case "model_select": {
+          const model = e.model as { provider: string; id: string } | undefined;
+          if (model) store.setModel(model);
+          break;
+        }
+        case "agent_settled":
+          store.endTurn({ error: store.state.side.error });
+          if (!store.state.open) s.ctx.ui.notify("Watcher reply ready — /watcher", "info");
+          break;
+      }
+    } else if (incoming.type === "exit" && !incoming.expected) {
+      store.endTurn({ error: incoming.error ?? "Side agent exited. Reopen /watcher to resume." });
+    } else if (incoming.type === "extension_error") {
+      s.ctx.ui.notify(`Watcher extension: ${incoming.error ?? "unknown error"}`, "warning");
+    } else if (incoming.type === "warning") {
+      s.ctx.ui.notify(`Watcher: ${incoming.message}`, "warning");
+    } else if (incoming.type === "ui" && incoming.request.method === "notify") {
+      s.ctx.ui.notify(`Watcher: ${incoming.request.message}`, incoming.request.notifyType ?? "info");
+    }
+  }
+
+  async function dispose(): Promise<void> {
+    const old = side;
+    side = undefined;
+    if (!old) return;
+    old.lifetime.abort();
+    old.overlay?.abort();
+    old.store.dispose();
+    old.unsubscribe?.();
+    await old.runtime.dispose();
+  }
+
+  async function ensure(ctx: ExtensionContext): Promise<Side> {
+    current = ctx;
+    const id = ctx.sessionManager.getSessionId();
+    if (side && side.id === id && !side.startupError && side.runtime.status !== "exited" && side.runtime.status !== "disposed") {
+      return side;
+    }
+    await dispose();
+    const mainSessionFile = ctx.sessionManager.getSessionFile();
+    if (!mainSessionFile) throw new Error("Watcher needs a persisted main session (not --no-session).");
+    const settings = loadSettings(getAgentDir());
+    const runtime = new WatcherRuntime();
+    const store = new WatcherStore();
+    const s: Side = {
+      id, ctx, runtime, store, lifetime: new AbortController(), ready: Promise.resolve(),
+      dialogCount: 0, dialogQueue: Promise.resolve(),
+      controller: {
+        async submit(text) {
+          if (!isCurrent(s)) throw new Error("Main session changed. Reopen /watcher.");
+          const pending = { text };
+          s.pendingQuestion = pending;
+          await s.ready;
+          if (!isCurrent(s) || s.pendingQuestion !== pending) return;
+          s.pendingQuestion = undefined;
+          const disposition = await runtime.prompt(text);
+          if (disposition === "handled") store.endTurn();
+        },
+        async stop() {
+          if (s.pendingQuestion) {
+            s.pendingQuestion = undefined;
+            store.endTurn();
+            if (!store.state.model) store.setSide({ status: "starting" });
+            return;
+          }
+          // Abort alone can continue queued work in Pi. Clear only the SIDE queue first.
+          await runtime.clearQueue();
+          await runtime.abort();
+          store.endTurn({ aborted: true });
+        },
+        async listModels() { await s.ready; return runtime.getAvailableModels(); },
+        async setModel(model) {
+          await s.ready;
+          if (!isCurrent(s)) throw new Error("Main session changed. Reopen /watcher.");
+          await runtime.setModel(model.provider, model.id);
+        },
+      },
+    };
+    side = s;
+    s.unsubscribe = runtime.subscribe((e) => event(s, e));
+    mainStatus();
+    store.setSide({ status: "starting" });
+    s.ready = (async () => {
+      // Let the overlay mount before doing child discovery/spawn or waiting for extensions/MCPs.
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      if (!isCurrent(s)) return;
+      const info = await runtime.start({
+        cwd: ctx.cwd, mainSessionFile, mainSessionId: id,
+        sessionDir: settings.sessionDir, excludedExtensions: settings.excludedExtensions,
+        model: settings.model, thinkingLevel: settings.thinkingLevel,
+        projectTrusted: ctx.isProjectTrusted(),
+        getCurrentMainSessionId: () => current?.sessionManager.getSessionId(),
+        liveMainTools: ({ params }) => JSON.stringify({
+          mainSessionFile, mainSessionId: id, leafId: current?.sessionManager.getLeafId(),
+          state: compacting ? "compacting" : current?.isIdle() ? "idle" : "working",
+          ...live.snapshot(params),
+        }),
+        steerMain: async ({ message, mode, rationale, signal }) => {
+          if (!isCurrent(s)) return { approved: false, reason: "Main session changed." };
+          const decision = await store.requestSteeringApproval({ text: message,
+            reason: `${rationale ?? "Message to main agent."} ${ctx.isIdle() ? "Main is idle: sending starts a new turn." : "Delivery waits for a safe turn boundary."}` }, signal);
+          if (decision.action !== "send" || signal.aborted || !isCurrent(s)) {
+            return { approved: false, reason: "Cancelled or main session changed." };
+          }
+          if (compacting) {
+            ctx.ui.notify("Watcher: main is compacting; message was NOT sent. Ask again after compaction.", "warning");
+            return { approved: false, reason: "Main is compacting; not sent. Ask the human before retrying." };
+          }
+          const text = `[Watcher — approved by you] ${decision.text}`;
+          pi.sendUserMessage(text, { deliverAs: mode });
+          store.addMessage("tool", `Sent to main (${mode}): ${text}`);
+          return { approved: true, deliveredMessage: text, mode };
+        },
+        onUiRequest: (request, { signal }) => extensionDialog(s, request, signal),
+      });
+      if (!isCurrent(s)) { await runtime.dispose(); return; }
+      const [messages, state] = await Promise.all([runtime.getMessages(), runtime.getState()]);
+      if (!isCurrent(s)) return;
+      store.setMessages(messagesToTranscript(messages));
+      // The user can submit while startup is in progress. Preserve that unsent question
+      // when replacing the initial empty display with the restored conversation.
+      if (s.pendingQuestion) store.addMessage("user", s.pendingQuestion.text);
+      store.setModel(state.model ?? undefined);
+      store.setSide({ status: runtime.isBusy || s.pendingQuestion ? "running" : "idle" });
+      for (const warning of info.warnings) ctx.ui.notify(`Watcher: ${warning}`, "warning");
+    })();
+    // Observe failures even when no question/model request awaits readiness. Keep the
+    // panel open so errors are visible, and allow the next /watcher to retry startup.
+    void s.ready.catch((error) => {
+      if (!isCurrent(s)) return;
+      s.startupError = errorText(error);
+      s.pendingQuestion = undefined;
+      store.endTurn({ error: s.startupError });
+      ctx.ui.notify(`Watcher: ${s.startupError}`, "error");
+      void runtime.dispose();
+    });
+    return s;
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    await dispose();
+    current = ctx;
+    compacting = false;
+    live.clear();
+  });
+  pi.on("session_shutdown", async () => { current = undefined; live.clear(); await dispose(); });
+  pi.on("agent_start", () => mainStatus());
+  pi.on("agent_settled", () => { compacting = false; live.clear(); mainStatus(); });
+  pi.on("tool_execution_start", (e) => { live.start(e); mainStatus(); });
+  pi.on("tool_execution_update", (e) => { live.update(e); });
+  pi.on("tool_execution_end", (e) => { live.end(e.toolCallId); mainStatus(); });
+  pi.on("session_before_compact", () => { compacting = true; mainStatus(); });
+  pi.on("session_compact", () => { compacting = false; mainStatus(); });
+  pi.on("session_compact_failed", () => { compacting = false; mainStatus(); });
+
+  pi.registerCommand("watcher", {
+    description: "Open the side agent; /watcher <question> to ask; /watcher model to choose its model",
+    handler: async (args, ctx) => {
+      if (ctx.mode !== "tui") { ctx.ui.notify("/watcher is a human-only interactive terminal command.", "warning"); return; }
+      try {
+        const s = await ensure(ctx);
+        const question = args.trim();
+        if (question && question !== "model") {
+          if (s.runtime.isBusy || s.store.state.side.status === "running") {
+            s.store.setDraft(question);
+            ctx.ui.notify("Watcher is replying; your question is saved as a draft.", "info");
+          } else {
+            s.store.beginTurn(question);
+            // Open UI immediately; inherited permission dialogs may need it during preflight.
+            void Promise.resolve(s.controller.submit(question)).catch((e) => s.store.endTurn({ error: errorText(e) }));
+          }
+        }
+        await show(s, question === "model" ? "model" : undefined);
+      } catch (error) { ctx.ui.notify(`Watcher: ${errorText(error)}`, "error"); }
+    },
+  });
+}

package/src/live-tools.ts

@@ -0,0 +1,66 @@
+/** Only in-flight metadata. No transcript, result buffers, polling, or timers. */
+export const MAX_LIVE_TOOLS = 64;
+const MAX_PREVIEW = 320;
+interface LiveTool {
+  id: string;
+  name: string;
+  parentId?: string;
+  startedAt: number;
+  updatedAt?: number;
+  input?: string;
+  output?: string;
+}
+
+function inputPreview(args: unknown): string | undefined {
+  if (!args || typeof args !== "object") return undefined;
+  const fields = args as Record<string, unknown>;
+  // Do not stringify arbitrary arguments or keep references to them.
+  for (const key of ["command", "path", "query", "task", "action"]) {
+    if (typeof fields[key] === "string") return `${key}: ${fields[key].slice(0, MAX_PREVIEW)}`;
+  }
+  return undefined;
+}
+
+export class LiveTools {
+  private calls = new Map<string, LiveTool>();
+  get size(): number { return this.calls.size; }
+  start(event: { toolCallId: string; toolName: string; parentToolCallId?: string; args?: unknown }): void {
+    if (this.calls.size >= MAX_LIVE_TOOLS && !this.calls.has(event.toolCallId)) return;
+    this.calls.set(event.toolCallId, {
+      id: event.toolCallId, name: event.toolName.slice(0, 128), parentId: event.parentToolCallId,
+      startedAt: Date.now(), input: inputPreview(event.args),
+    });
+  }
+  update(event: { toolCallId: string; partialResult?: unknown }): void {
+    const call = this.calls.get(event.toolCallId);
+    if (!call) return;
+    call.updatedAt = Date.now();
+    const result = event.partialResult as { content?: Array<{ type?: string; text?: string }> } | undefined;
+    if (!Array.isArray(result?.content)) return;
+    // Keep only a short tail from one text block, replacing the previous preview.
+    for (let i = result.content.length - 1; i >= 0; i--) {
+      const part = result.content[i];
+      if (part?.type === "text" && typeof part.text === "string") {
+        call.output = part.text.slice(-MAX_PREVIEW);
+        return;
+      }
+    }
+  }
+  end(id: string): void { this.calls.delete(id); }
+  clear(): void { this.calls.clear(); }
+  summary(): string | undefined {
+    if (!this.calls.size) return undefined;
+    return [...this.calls.values()].slice(0, 3).map((c) => c.name).join(", ") +
+      (this.calls.size > 3 ? ` (+${this.calls.size - 3})` : "");
+  }
+  snapshot(params: { toolCallId?: string; limit?: number } = {}) {
+    const now = Date.now();
+    const limit = Number.isFinite(params.limit) ? Math.max(1, Math.min(MAX_LIVE_TOOLS, Math.floor(params.limit!))) : 16;
+    const calls = params.toolCallId ? [this.calls.get(params.toolCallId)].filter((v): v is LiveTool => !!v) : [...this.calls.values()];
+    return {
+      asOf: new Date(now).toISOString(),
+      note: `Only currently running tools; completed calls are removed immediately. At most ${MAX_LIVE_TOOLS} concurrent calls are tracked. Read the main session file for history.`,
+      tools: calls.slice(0, limit).map((c) => ({ ...c, elapsedMs: now - c.startedAt })),
+    };
+  }
+}