pi-project-switcher 0.6.0 → 0.7.0

package/README.md

@@ -14,6 +14,7 @@ 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.
   - **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,58 @@ 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}`
+  );
+}
+
 
 function getConfig(): Config {
   if (!config) {
@@ -367,8 +444,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 +478,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 +519,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 +553,94 @@ 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}\`` : "";
+      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 (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 +671,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.7.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"}}