pi-project-switcher 0.6.0 → 0.8.0

package/README.md

@@ -14,6 +14,8 @@ A [pi coding agent](https://github.com/earendil-works/pi) extension to switch be
   - persists across reloads (session entry)
   - sets the session display name
   - injects the project path into every agent turn's system prompt, so file operations default to the active project
+  - **via the Telegram bridge**: the switch is confirmed in the chat — a short reply with the project, working directory, and session identity, plus buttons (project list, and switch back to the previous project). The confirmation is sent from the new session runtime, so it also works when the switch restores a stored session. No-switch outcomes (already active, cancelled, unknown) are answered in the chat too.
+  - **Telegram transport re-arm**: a session-replacing switch from the Telegram bridge suspends the bridge's polling (pi-telegram stands down on session shutdown and its auto-reconnect declines the handoff because the restored session's cwd differs from the lock's cwd). The switcher therefore re-runs `/telegram-connect` from the new session ~9 s after the switch — but **only** when the session being left provably owned the connected transport: pi-telegram's lock (`~/.pi/agent/tmp/telegram/owners.json`) must name this process with a fresh heartbeat and a cwd matching the old session. Native switches and switches from sessions that didn't own the bot never re-arm. The lock file is only read, never modified.
   - **if the project doesn't exist yet**, offers to create the folder and switch to it (confirmation dialog on dialog-capable surfaces; use `/project <name>!` to skip the dialog — e.g. on headless/RPC surfaces). Unsafe names (path segments, `..`, hidden, absolute) are never created.
 - **Session restore** — a machine-local map (`~/.pi/agent/project-switcher-sessions.json`) remembers the most recent session per project. Switching projects returns you to that project's last session; if none exists (or the file is gone), the switch happens in the current session.
 - **Auto-detection** — if pi starts inside `~/dev/<project>`, that project is active automatically

package/index.ts

@@ -19,6 +19,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -182,6 +183,14 @@ let config: Config | null = null;
  */
 const TELEGRAM_STATUS_RE = /^\[telegram(?:\|[^\]]*)?\]\s*\/project\s*$/;
 
+/**
+ * Same, but for `/project <name>` (a switch). The command bridge strips
+ * the tag and re-dispatches the bare command line, so a Telegram-originated
+ * switch would otherwise be indistinguishable from a native invocation.
+ * Arguments are captured so the flag matches the command the user sent.
+ */
+const TELEGRAM_SWITCH_RE = /^\[telegram(?:\|[^\]]*)?\]\s*\/project\s+(\S.*)$/;
+
 /** How long an armed flag stays valid (ms). Guards against stale flags
  *  from dispatches that never reached the command handler. */
 const TELEGRAM_FLAG_TTL_MS = 30_000;
@@ -189,6 +198,9 @@ const TELEGRAM_FLAG_TTL_MS = 30_000;
 /** Armed-at timestamp of a pending Telegram-originated status request, or null. */
 let telegramStatusFlag: number | null = null;
 
+/** Armed-at timestamp of a pending Telegram-originated switch request, or null. */
+let telegramSwitchFlag: number | null = null;
+
 function armTelegramStatusFlag(): void {
   telegramStatusFlag = Date.now();
 }
@@ -201,8 +213,21 @@ function consumeTelegramStatusFlag(): boolean {
   return Date.now() - armed <= TELEGRAM_FLAG_TTL_MS;
 }
 
+function armTelegramSwitchFlag(): void {
+  telegramSwitchFlag = Date.now();
+}
+
+/** Consume the switch flag: returns true (and clears it) when armed and not expired. */
+function consumeTelegramSwitchFlag(): boolean {
+  if (telegramSwitchFlag === null) return false;
+  const armed = telegramSwitchFlag;
+  telegramSwitchFlag = null;
+  return Date.now() - armed <= TELEGRAM_FLAG_TTL_MS;
+}
+
 function clearTelegramStatusFlag(): void {
   telegramStatusFlag = null;
+  telegramSwitchFlag = null;
 }
 
 /**
@@ -258,6 +283,155 @@ function buildTelegramStatusPrompt(projects: string[]): string {
   );
 }
 
+/**
+ * Build the follow-up prompt for a Telegram-originated project switch. The
+ * turn's reply is delivered to the Telegram chat as the visible confirmation
+ * that the switch succeeded (the local UI notification never reaches the
+ * phone). Facts are passed by the extension; the reply shape is prescribed
+ * so the model cannot invent outcomes. `sendFn` is passed in so both switch
+ * paths reuse this: the restore path must send from the fresh withSession
+ * context (never the stale pre-switch pi), the fallback path from the
+ * current runtime.
+ */
+function buildTelegramSwitchConfirmationPrompt(opts: {
+  project: string;
+  path: string;
+  branchStr: string;
+  sessionLine: string;
+  previous: string | null;
+}): string {
+  const { project, path, branchStr, sessionLine, previous } = opts;
+
+  const confirmLine = `✅ Switched to **${project}**${previous ? ` (was: ${previous})` : ""}`;
+  const infoLines = [confirmLine, `📁 ${path}${branchStr ? ` (${branchStr})` : ""}`, sessionLine].join("\n");
+
+  const cells: string[] = ["{📋 Projects|/project}"];
+  if (previous && !isUnsafeButtonName(previous) && previous !== project) {
+    cells.push(`{↩️ Back to ${previous}|/project ${previous}}`);
+  }
+  const buttonBlock =
+    cells.length > 0
+      ? "\n\n```telegram_button\n" + cells.join("\n") + "\n```"
+      : "";
+
+  return (
+    `[project-switcher] The user ran /project ${project} via Telegram and expects a confirmation that the switch succeeded.\n` +
+    `Authoritative switch facts (do not re-derive, do not run any command, do not switch projects yourself):\n` +
+    `${infoLines}\n\n` +
+    `Reply in the chat with exactly the lines above, followed by the button block below, copied verbatim. ` +
+    `Add nothing else.${buttonBlock}`
+  );
+}
+
+/**
+ * Short follow-up for Telegram-originated switch outcomes that changed
+ * nothing (already-active or cancelled): guarantees the chat still gets a
+ * visible reply instead of silence.
+ */
+function buildTelegramNoChangePrompt(text: string): string {
+  return (
+    `[project-switcher] The user ran /project via Telegram.\n` +
+    `Reply in the chat with exactly this line and nothing else: ${text}`
+  );
+}
+
+// ── Telegram transport ownership probe & re-arm ──────────────────────────────
+
+/**
+ * Path of pi-telegram's transport ownership lock. The switcher only ever
+ * READS this file (pi-telegram's own connect handler performs the actual
+ * acquisition); mutating it by hand is explicitly forbidden by the
+ * bridge's diagnosis guidance.
+ */
+function telegramOwnersPath(): string {
+  return join(HOME, ".pi", "agent", "tmp", "telegram", "owners.json");
+}
+
+/**
+ * Freshness bound for the ownership probe. Deliberately LOOSER than
+ * pi-telegram's 8s staleness window: a passing probe means the owner
+ * runtime was definitely alive at switch time (a false positive here only
+ * leads to a connect attempt that pi-telegram itself re-validates).
+ */
+const TELEGRAM_OWNERSHIP_FRESH_MS = 10_000;
+
+/**
+ * Delay before re-dispatching /telegram-connect after a session-replacing
+ * switch. Must exceed pi-telegram's lock staleness window (8s): the
+ * suspended old runtime stops refreshing the heartbeat at session
+ * shutdown, and a *stale* lock is the only one the connect handler's
+ * non-forced acquire can replace across a cwd mismatch.
+ */
+const TELEGRAM_REARM_DELAY_MS = 9_000;
+
+/**
+ * Read-only probe: is the session we are about to leave the live owner of
+ * the connected Telegram transport? True iff pi-telegram's lock file has
+ * an entry for the current process whose heartbeat is fresh and whose cwd
+ * matches the old session's cwd (or is absent). This is the guard that
+ * prevents stealing the bot from a different pi instance or re-arming in
+ * a session that never used Telegram.
+ */
+function probeTelegramTransportOwnership(oldCwd: string): boolean {
+  try {
+    const raw = JSON.parse(readFileSync(telegramOwnersPath(), "utf8"));
+    if (!raw || typeof raw !== "object") return false;
+    // Any profile entry counts (the default profile uses the key "default").
+    for (const entry of Object.values(raw) as any[]) {
+      if (
+        entry &&
+        typeof entry === "object" &&
+        entry.pid === process.pid &&
+        typeof entry.heartbeatMs === "number" &&
+        Date.now() - entry.heartbeatMs <= TELEGRAM_OWNERSHIP_FRESH_MS &&
+        (entry.cwd === undefined || entry.cwd === oldCwd)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    // Missing or malformed lock file: transport not owned here.
+    return false;
+  }
+}
+
+/**
+ * Pending re-arm timer (single slot): scheduling a new re-arm supersedes
+ * a not-yet-fired previous one. The callback only touches the withSession
+ * context it was scheduled with, so it can never act on a stale runtime.
+ */
+let pendingRearmTimer: ReturnType<typeof setTimeout> | null = null;
+
+function scheduleTelegramRearm(newCtx: any, source: string): void {
+  if (pendingRearmTimer) {
+    clearTimeout(pendingRearmTimer);
+    pendingRearmTimer = null;
+  }
+  const timer = setTimeout(async () => {
+    pendingRearmTimer = null;
+    try {
+      // Command re-dispatch from the FRESH runtime: executes pi-telegram's
+      // connect handler (no agent turn) and re-acquires the now-stale lock,
+      // restarting polling in the new session.
+      await newCtx.sendUserMessage("/telegram-connect", {
+        expandPromptTemplates: true,
+      });
+    } catch (err: any) {
+      try {
+        newCtx.ui.notify(
+          `Telegram re-arm after ${source} switch failed: ${err?.message ?? err}`,
+          "warning"
+        );
+      } catch {
+        // Even the fresh context can be gone (e.g. another switch followed):
+        // never let an error escape into an uncaught timer callback.
+      }
+    }
+  }, TELEGRAM_REARM_DELAY_MS);
+  timer.unref?.();
+  pendingRearmTimer = timer;
+}
 
 function getConfig(): Config {
   if (!config) {
@@ -367,8 +541,11 @@ export default function (pi: ExtensionAPI) {
   pi.on("input", async (event) => {
     if (event.source !== "extension") return;
     const firstLine = event.text.split("\n", 1)[0];
-    if (TELEGRAM_STATUS_RE.test(firstLine.trim())) {
+    const trimmed = firstLine.trim();
+    if (TELEGRAM_STATUS_RE.test(trimmed)) {
       armTelegramStatusFlag();
+    } else if (TELEGRAM_SWITCH_RE.test(trimmed)) {
+      armTelegramSwitchFlag();
     }
     // Never transform or handle: the command bridge owns the re-dispatch.
   });
@@ -398,6 +575,7 @@ export default function (pi: ExtensionAPI) {
   // "!") only applies to the typed path; dialog users confirm interactively.
   const switchToProject = async (rawName: string, ctx: any, createOptIn: boolean): Promise<void> => {
     const name = rawName;
+    const isTelegramOrigin = consumeTelegramSwitchFlag();
 
     if (!isValidProject(name)) {
       // Offer to create the folder and switch to it (never silently)
@@ -438,12 +616,25 @@ export default function (pi: ExtensionAPI) {
           `Unknown project: "${name}".\nAvailable: ${available || "(none)"}`,
           "warning"
         );
+        if (isTelegramOrigin) {
+          await ctx.waitForIdle();
+          pi.sendUserMessage(
+            buildTelegramNoChangePrompt(`⚠️ Unknown project: ${name} — no switch performed.`),
+            { deliverAs: "followUp" }
+          );
+        }
         return;
       }
     }
 
     if (name === activeProject) {
       ctx.ui.notify(`Already on project: ${name}`, "info");
+      if (isTelegramOrigin) {
+        await ctx.waitForIdle();
+        pi.sendUserMessage(buildTelegramNoChangePrompt(`ℹ️ Already on project: **${name}**`), {
+          deliverAs: "followUp",
+        });
+      }
       return;
     }
 
@@ -459,32 +650,110 @@ export default function (pi: ExtensionAPI) {
     const targetSession = getMappedSessionFile(name);
 
     if (targetSession) {
-      // Persist the switch in the OLD session before replacing it
-      pi.appendEntry(ENTRY_TYPE, { project: name, switchedAt: new Date().toISOString() });
+      // Pre-write the switch state INTO THE TARGET session file so the
+      // fresh runtime's session_start restores the right project. Writing
+      // it to the current (old) session instead would leave the target
+      // session's own (stale) project entry authoritative.
+      // SessionManager.open() advances the target file's leaf to this entry.
+      // The same entry must also exist in the old session so a later switch
+      // BACK to the previous project still restores it (the old session is
+      // remembered under the previous project below).
+      try {
+        SessionManager.open(targetSession).appendCustomEntry(ENTRY_TYPE, {
+          project: name,
+          switchedAt: new Date().toISOString(),
+        });
+      } catch (err: any) {
+        ctx.ui.notify(
+          `Could not persist switch state to target session: ${err?.message ?? err}`,
+          "warning"
+        );
+      }
 
-      const result = await ctx.switchSession(targetSession);
+      // Persist the switch in the OLD session too (for switching back later).
+      // Still valid: the old runtime has not been invalidated yet.
+      try {
+        pi.appendEntry(ENTRY_TYPE, { project: name, switchedAt: new Date().toISOString() });
+      } catch {
+        // Non-fatal: the target-session entry above is the authoritative one.
+      }
+
+      // Everything after ctx.switchSession() must run in withSession: the
+      // captured `pi` and command `ctx` are stale once the session is
+      // replaced, and using them throws (previously crashed the command
+      // with "stale ctx" errors and killed the whole flow).
+      const branch = getGitBranch(projectPath(name));
+      const branchStr = branch ? ` on branch \`${branch}\`` : "";
+      // Ownership probe BEFORE the switch (the old session's cwd is only
+      // available here): when the session we are leaving is the live owner
+      // of the connected Telegram transport, the new runtime must re-arm
+      // it after the switch (pi-telegram suspends polling on session
+      // shutdown and its auto-start declines the handoff across a cwd
+      // mismatch). The probe failing means we are NOT the owner (another
+      // pi instance, or Telegram was never connected here): re-arm nothing.
+      const ownedTelegramTransport =
+        isTelegramOrigin && probeTelegramTransportOwnership(ctx.cwd);
+      const result = await ctx.switchSession(targetSession, {
+        withSession: async (newCtx: any) => {
+          // Safety net in case the restored session has no project entry:
+          // session_start has already run for the new runtime; if it
+          // restored a different project from a stale entry, the pre-written
+          // entry above is the LAST project-switcher-state entry in the file
+          // and therefore authoritative — set the in-memory state explicitly.
+          activeProject = name;
+          newCtx.ui.notify(
+            `Switched to ${name} — session restored: ${basename(targetSession)}\n` +
+            `Workdir: ${projectPath(name)}${branchStr ? ` ${branchStr}` : ""}`,
+            "info"
+          );
+          if (isTelegramOrigin) {
+            // Confirmation turn from the FRESH runtime: the reply reaches
+            // the Telegram chat (the local notify above never does). Only
+            // the new context is touched — the pre-switch pi/ctx are stale.
+            // The turn also settles pi-telegram's dispatch queue.
+            await newCtx.waitForIdle();
+            await newCtx.sendUserMessage(
+              buildTelegramSwitchConfirmationPrompt({
+                project: name,
+                path: projectPath(name),
+                branchStr,
+                sessionLine: `🗂 Session restored: ${basename(targetSession)}`,
+                previous,
+              }),
+              { deliverAs: "followUp" }
+            );
+          }
+          if (ownedTelegramTransport) {
+            // Re-arm the Telegram transport from the fresh runtime. Only the
+            // withSession context is touched; the delay lets the old lock
+            // go stale (see TELEGRAM_REARM_DELAY_MS) so the connect
+            // handler's acquire can replace it across the cwd mismatch.
+            scheduleTelegramRearm(newCtx, name);
+          }
+        },
+      });
       if (result.cancelled) {
-        // User cancelled; roll back in-memory state
+        // User cancelled; roll back in-memory state. The pre-written target
+        // entry is harmless: it only records that a switch to `name` was
+        // attempted; an explicit later status/switch overrides it.
         activeProject = previous;
         ctx.ui.notify(`Switch cancelled. Staying on ${previous ?? "no project"}.`, "info");
+        if (isTelegramOrigin) {
+          await ctx.waitForIdle();
+          pi.sendUserMessage(
+            buildTelegramNoChangePrompt(
+              `⚠️ Switch to ${name} cancelled — staying on ${previous ?? "no project"}.`
+            ),
+            { deliverAs: "followUp" }
+          );
+        }
         return;
       }
 
-      // switchSession fires a new session_start, which restores state from
-      // the target session's entries (or auto-detects). Set it explicitly as
-      // a safety net in case the session has no project entry yet.
-      activeProject = name;
-      pi.setSessionName(name);
+      // Remember the mapping AFTER a successful switch (withSession has
+      // already run). rememberSessionFile only touches the JSON map on
+      // disk, so calling it here is safe.
       rememberSessionFile(name, targetSession);
-
-      const path = projectPath(name);
-      const branch = getGitBranch(path);
-      const branchStr = branch ? ` on branch \`${branch}\`` : "";
-      ctx.ui.notify(
-        `Switched to ${name} — session restored: ${basename(targetSession)}\n` +
-        `Workdir: ${path}${branchStr ? ` ${branchStr}` : ""}`,
-        "info"
-      );
       return;
     }
 
@@ -515,12 +784,22 @@ export default function (pi: ExtensionAPI) {
       "info"
     );
 
-    // Announce to the agent so it operates in the new context
+    // Announce to the agent so it operates in the new context — or, for a
+    // Telegram-originated switch, send the chat-visible confirmation turn
+    // (it doubles as the agent context announcement).
     await ctx.waitForIdle();
     pi.sendUserMessage(
-      `[Project switched to **${name}**]\n` +
-        `Working directory: \`${path}\`${branchStr}\n` +
-        `Please keep all file operations within this project from now on.`,
+      isTelegramOrigin
+        ? buildTelegramSwitchConfirmationPrompt({
+            project: name,
+            path,
+            branchStr,
+            sessionLine: `🗂 First session in this project (${sessionLine})`,
+            previous,
+          })
+        : `[Project switched to **${name}**]\n` +
+          `Working directory: \`${path}\`${branchStr}\n` +
+          `Please keep all file operations within this project from now on.`,
       { deliverAs: "followUp" }
     );
   };

package/package.json

@@ -1 +1 @@
-{"name": "pi-project-switcher", "version": "0.6.0", "description": "pi coding agent extension: switch between projects under a configurable base directory via /project", "main": "index.ts", "type": "module", "scripts": {"test": "vitest run", "test:watch": "vitest", "typecheck": "tsc --noEmit"}, "keywords": ["pi", "pi-package", "pi-extension", "project", "switcher", "project-switching"], "author": "stefclawd", "license": "MIT", "repository": {"type": "git", "url": "git+https://github.com/stefclawd/pi-project-switcher.git"}, "bugs": {"url": "https://github.com/stefclawd/pi-project-switcher/issues"}, "homepage": "https://github.com/stefclawd/pi-project-switcher#readme", "files": ["index.ts", "README.md", "LICENSE"], "engines": {"node": ">=22.19.0"}, "pi": {"extensions": ["./index.ts"]}, "devDependencies": {"@earendil-works/pi-coding-agent": "^0.85.1", "@types/node": "^24.0.0", "typescript": "^5.7.0", "vitest": "^3.0.0"}}
+{"name": "pi-project-switcher", "version": "0.8.0", "description": "pi coding agent extension: switch between projects under a configurable base directory via /project", "main": "index.ts", "type": "module", "scripts": {"test": "vitest run", "test:watch": "vitest", "typecheck": "tsc --noEmit"}, "keywords": ["pi", "pi-package", "pi-extension", "project", "switcher", "project-switching"], "author": "stefclawd", "license": "MIT", "repository": {"type": "git", "url": "git+https://github.com/stefclawd/pi-project-switcher.git"}, "bugs": {"url": "https://github.com/stefclawd/pi-project-switcher/issues"}, "homepage": "https://github.com/stefclawd/pi-project-switcher#readme", "files": ["index.ts", "README.md", "LICENSE"], "engines": {"node": ">=22.19.0"}, "pi": {"extensions": ["./index.ts"]}, "devDependencies": {"@earendil-works/pi-coding-agent": "^0.85.1", "@types/node": "^24.0.0", "typescript": "^5.7.0", "vitest": "^3.0.0"}}