@hienlh/ppm 0.18.13 → 0.18.15

package/src/cli/commands/backup-cmd.ts

@@ -0,0 +1,119 @@
+import { Command } from "commander";
+
+/**
+ * `ppm backup` / `ppm restore` — manual control over config-database
+ * snapshots. Snapshots also happen automatically (hourly, at start-up, and
+ * before any schema migration); these commands exist for the two moments
+ * automation cannot cover: taking one deliberately before a risky change, and
+ * getting back on your feet after something ate the database.
+ *
+ * Kept out of `db-cmd.ts` on purpose — that command group manages *external*
+ * database connections, so `ppm db backup` would read as backing one of those
+ * up rather than PPM's own store.
+ */
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+function mb(bytes: number): string {
+  return `${(bytes / 1_048_576).toFixed(1)} MB`;
+}
+
+function ago(date: Date, now = new Date()): string {
+  const mins = Math.round((now.getTime() - date.getTime()) / 60_000);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.round(mins / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+export function registerBackupCommands(program: Command): void {
+  program
+    .command("backup")
+    .description("Snapshot the PPM config database now")
+    .option("--json", "Output as JSON")
+    .action(async (options: { json?: boolean }) => {
+      try {
+        const { backupDb } = await import("../../services/db-backup/db-backup.service.ts");
+        const result = await backupDb("manual");
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        console.log(`${C.green}Snapshot written${C.reset} ${result.path}`);
+        console.log(`  ${mb(result.bytes)} in ${result.ms}ms, integrity verified`);
+        if (result.pruned.length) {
+          console.log(`  ${C.dim}pruned ${result.pruned.length} older snapshot(s) per retention policy${C.reset}`);
+        }
+      } catch (e: any) {
+        console.error(`${C.red}Backup failed:${C.reset} ${e?.message ?? e}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("restore")
+    .description("Restore the PPM config database from a snapshot")
+    .argument("[backup]", "Snapshot filename or path (default: the newest one)")
+    .option("--list", "List available snapshots and exit")
+    .option("--force", "Restore even while PPM is running (stop it first when you can)")
+    .option("--json", "Output as JSON")
+    .action(async (backupArg: string | undefined, options: { list?: boolean; force?: boolean; json?: boolean }) => {
+      try {
+        const { listBackups, activeDbStem } = await import("../../services/db-backup/db-backup.service.ts");
+        const { getBackupsDir } = await import("../../services/db-backup/db-backup-paths.ts");
+        const { restoreDb, resolveBackupArg } = await import("../../services/db-backup/db-backup-restore.ts");
+        const { getDbPath } = await import("../../services/db.service.ts");
+
+        const stem = await activeDbStem();
+        const entries = listBackups(stem);
+
+        if (options.list) {
+          if (options.json) {
+            console.log(JSON.stringify(entries, null, 2));
+            return;
+          }
+          if (entries.length === 0) {
+            console.log(`${C.yellow}No snapshots in ${getBackupsDir()}${C.reset}`);
+            return;
+          }
+          console.log(`${C.bold}Snapshots in ${getBackupsDir()}${C.reset}`);
+          for (const e of entries) {
+            console.log(`  ${C.cyan}${e.name}${C.reset}  ${mb(e.bytes)}  ${C.dim}${e.reason}, ${ago(e.date)}${C.reset}`);
+          }
+          return;
+        }
+
+        const target = backupArg
+          ? resolveBackupArg(backupArg, getBackupsDir())
+          : entries[0]?.path;
+        if (!target) {
+          console.error(`${C.red}No snapshot to restore${C.reset} — nothing in ${getBackupsDir()}`);
+          process.exit(1);
+          return;
+        }
+
+        const result = restoreDb(target, { dbPath: getDbPath(), force: options.force });
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        console.log(`${C.green}Restored${C.reset} ${result.dbPath} (${mb(result.bytes)})`);
+        console.log(`  from ${result.restoredFrom}`);
+        if (result.archivedTo) {
+          console.log(`  ${C.dim}previous database kept at ${result.archivedTo}${C.reset}`);
+        }
+        console.log(`  ${C.dim}start PPM with: ppm start${C.reset}`);
+      } catch (e: any) {
+        console.error(`${C.red}Restore failed:${C.reset} ${e?.message ?? e}`);
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -154,6 +154,9 @@ export async function buildProgram(): Promise<Command> {
   const { registerDbCommands } = await import("./cli/commands/db-cmd.ts");
   registerDbCommands(program);
 
+  const { registerBackupCommands } = await import("./cli/commands/backup-cmd.ts");
+  registerBackupCommands(program);
+
   const { registerBotCommands } = await import("./cli/commands/bot-cmd.ts");
   registerBotCommands(program);
 

package/src/providers/claude-agent-sdk.ts

@@ -20,7 +20,8 @@ import { configService } from "../services/config.service.ts";
 import { mcpConfigService } from "../services/mcp-config.service.ts";
 import { listInheritedClaudeMcpServers } from "../services/claude-code-mcp.service.ts";
 import { updateFromSdkEvent } from "../services/claude-usage.service.ts";
-import { getSessionProjectPath, setSessionMetadata, getSessionTitles, insertTurnUsage } from "../services/db.service.ts";
+import { getSessionProjectPath, setSessionMetadata, getSessionTitles, insertTurnUsage, getSessionAccount } from "../services/db.service.ts";
+import { SUBSCRIPTION_PROMPT_CACHE_TTL_MS, API_KEY_PROMPT_CACHE_TTL_MS } from "../services/subprocess-retention.ts";
 import { buildTurnUsage, formatTurnUsageLog } from "../shared/turn-usage.ts";
 import { accountSelector } from "../services/account-selector.service.ts";
 import { accountService, type AccountWithTokens } from "../services/account.service.ts";
@@ -761,6 +762,33 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     return this.streamingSessions.has(sessionId);
   }
 
+  /**
+   * How long this session's prompt cache is worth holding a subprocess for.
+   *
+   * The hour only applies to a Claude subscription; an API key — settings `api_key`, a shell
+   * key, or anything behind a custom `base_url` — gets five minutes. Mirrors
+   * `buildQueryEnv`'s precedence, since that is what actually decides how the subprocess
+   * authenticates: settings api_key first, then the session's account, then the shell.
+   */
+  promptCacheTtlMs(sessionId: string): number {
+    const cfg = this.getProviderConfig();
+    // A custom endpoint is not Anthropic's subscription API whatever the credential is.
+    const shellBaseUrl = process.env.ANTHROPIC_BASE_URL ?? "";
+    if (cfg.base_url || (shellBaseUrl && !shellBaseUrl.includes("/proxy"))) {
+      return API_KEY_PROMPT_CACHE_TTL_MS;
+    }
+    if (cfg.api_key?.trim()) return API_KEY_PROMPT_CACHE_TTL_MS;
+
+    const accountId = getSessionAccount(sessionId);
+    const token = accountId ? accountService.getWithTokens(accountId)?.accessToken : undefined;
+    if (token) return token.startsWith("sk-ant-oat") ? SUBSCRIPTION_PROMPT_CACHE_TTL_MS : API_KEY_PROMPT_CACHE_TTL_MS;
+
+    // No account recorded yet: the shell's own credentials decide, and an OAuth token there
+    // is still a subscription. Nothing at all means the CLI's own auth, which we cannot
+    // classify — take the short window rather than hold memory on a guess.
+    return process.env.CLAUDE_CODE_OAUTH_TOKEN ? SUBSCRIPTION_PROMPT_CACHE_TTL_MS : API_KEY_PROMPT_CACHE_TTL_MS;
+  }
+
   async *sendMessage(
     _sessionId: string,
     message: string,

package/src/server/index.ts

@@ -30,6 +30,8 @@ import { chatWebSocket } from "./ws/chat.ts";
 import { extensionWebSocket } from "./ws/extensions.ts";
 import { globalWebSocket } from "./ws/global.ts";
 import { groupChatWebSocket } from "./ws/group-chat.ts";
+import { remoteDesktopWebSocket } from "./ws/remote-desktop.ts";
+import { isRemoteDesktopEnabled } from "../services/remote-desktop/remote-desktop-flag.ts";
 import { ok, err } from "../types/api.ts";
 
 /** Tee console.log/error to ~/.ppm/ppm.log while preserving terminal output */
@@ -175,6 +177,10 @@ app.route("/api/system", resourceRoutes);
 import { hostInfoRoutes } from "./routes/host-info.ts";
 app.route("/api/system", hostInfoRoutes);
 
+// Remote desktop (video capture + input) — feature-flagged off by default, see remote-desktop-flag.ts
+import { remoteDesktopRoutes } from "./routes/remote-desktop.ts";
+app.route("/api/remote-desktop", remoteDesktopRoutes);
+
 // Finishes an OAuth loopback login started from another device
 import { loopbackRoutes } from "./routes/oauth-loopback.ts";
 app.route("/api/loopback", loopbackRoutes);
@@ -860,6 +866,20 @@ if (process.argv.includes("__serve__")) {
         return new Response("WebSocket upgrade failed", { status: 400 });
       }
 
+      if (url.pathname === "/ws/remote-desktop") {
+        // Explicit branch so this socket can never fall through to the terminal (shell)
+        // handler's default case. Feature flag + `auth.enabled` are re-checked here
+        // independently of `isWsUpgradeAuthorized` above, which returns true unconditionally
+        // when PPM auth is disabled — a live keyboard/mouse channel must not inherit that.
+        if (!isRemoteDesktopEnabled()) return new Response("Not Found", { status: 404 });
+        if (!configService.get("auth").enabled) {
+          return new Response("Forbidden: remote desktop requires PPM authentication to be enabled", { status: 403 });
+        }
+        const upgraded = server.upgrade(req, { data: { type: "remote-desktop" } });
+        if (upgraded) return undefined;
+        return new Response("WebSocket upgrade failed", { status: 400 });
+      }
+
       if (url.pathname.startsWith("/ws/project/")) {
         const parts = url.pathname.split("/");
         const projectName = decodeURIComponent(parts[3] ?? "");
@@ -901,25 +921,32 @@ if (process.argv.includes("__serve__")) {
       sendPong: true,
       perMessageDeflate: false,
       open(ws: any) {
-        if (ws.data?.type === "chat") chatWebSocket.open(ws);
-        else if (ws.data?.type === "group") groupChatWebSocket.open(ws);
-        else if (ws.data?.type === "extensions") extensionWebSocket.open(ws);
-        else if (ws.data?.type === "global") globalWebSocket.open(ws);
-        else terminalWebSocket.open(ws);
+        const t = ws.data?.type;
+        if (t === "chat") chatWebSocket.open(ws);
+        else if (t === "group") groupChatWebSocket.open(ws);
+        else if (t === "extensions") extensionWebSocket.open(ws);
+        else if (t === "global") globalWebSocket.open(ws);
+        else if (t === "remote-desktop") remoteDesktopWebSocket.open(ws);
+        else if (t === "terminal") terminalWebSocket.open(ws);
+        else ws.close(1008, "unknown socket type");
       },
       message(ws: any, msg: any) {
-        if (ws.data?.type === "chat") chatWebSocket.message(ws, msg);
-        else if (ws.data?.type === "group") groupChatWebSocket.message(ws, msg);
-        else if (ws.data?.type === "extensions") extensionWebSocket.message(ws, msg);
-        else if (ws.data?.type === "global") globalWebSocket.message(ws, msg);
-        else terminalWebSocket.message(ws, msg);
+        const t = ws.data?.type;
+        if (t === "chat") chatWebSocket.message(ws, msg);
+        else if (t === "group") groupChatWebSocket.message(ws, msg);
+        else if (t === "extensions") extensionWebSocket.message(ws, msg);
+        else if (t === "global") globalWebSocket.message(ws, msg);
+        else if (t === "remote-desktop") remoteDesktopWebSocket.message(ws, msg);
+        else if (t === "terminal") terminalWebSocket.message(ws, msg);
       },
       close(ws: any) {
-        if (ws.data?.type === "chat") chatWebSocket.close(ws);
-        else if (ws.data?.type === "group") groupChatWebSocket.close(ws);
-        else if (ws.data?.type === "extensions") extensionWebSocket.close(ws);
-        else if (ws.data?.type === "global") globalWebSocket.close(ws);
-        else terminalWebSocket.close(ws);
+        const t = ws.data?.type;
+        if (t === "chat") chatWebSocket.close(ws);
+        else if (t === "group") groupChatWebSocket.close(ws);
+        else if (t === "extensions") extensionWebSocket.close(ws);
+        else if (t === "global") globalWebSocket.close(ws);
+        else if (t === "remote-desktop") remoteDesktopWebSocket.close(ws);
+        else if (t === "terminal") terminalWebSocket.close(ws);
       },
     } as Parameters<typeof Bun.serve>[0] extends { websocket?: infer W } ? W : never,
   });

package/src/server/routes/accounts.ts

@@ -376,8 +376,36 @@ accountsRoutes.patch("/:id", async (c) => {
   const body = await c.req.json<{ status?: string }>();
   try {
     if (body.status === "disabled") accountService.setDisabled(id);
-    else if (body.status === "active") accountService.setEnabled(id);
-    else return c.json(err("status must be active or disabled"), 400);
+    else if (body.status === "active") {
+      const wasParked = accountService.list().find((a) => a.id === id)?.status === "disabled";
+      // Enabling is where this machine claims the token, so prove it *before* the account
+      // becomes selectable rather than after. postRefreshGrant is three 15s attempts with
+      // 2s and 6s backoff between them — 53s worst case — so enabling first would leave the
+      // account active with an unproven token for most of a minute, long enough for
+      // accountSelector.next() or the proxy to pick it, and the re-park would land only
+      // after that turn had already failed. Refreshing while still
+      // parked needs no rollback at all: on failure setEnabled() simply never runs.
+      //
+      // Only for an account that has a refresh token: a temporary one has nothing to prove,
+      // and setEnabled()'s own guard says something more useful than a refresh error would.
+      if (wasParked && accountService.hasRefreshToken(id)) {
+        const proof = await accountService.ensureFreshTokenChecked(id);
+        if (!proof.account) {
+          // Worth splitting: invalid_grant means the token is gone and only a fresh sign-in
+          // brings it back, while a network drop or a 429 is worth trying again in a minute.
+          // Telling someone to re-authenticate because their wifi blinked is a bad trade.
+          return c.json(
+            err(
+              proof.rejected
+                ? "This account's login was rejected — it stays disabled. Sign in again to give it a live token, then enable it."
+                : "Could not reach Anthropic to check this account — it stays disabled. Try again in a moment.",
+            ),
+            400,
+          );
+        }
+      }
+      accountService.setEnabled(id);
+    } else return c.json(err("status must be active or disabled"), 400);
   } catch (e) {
     return c.json(err((e as Error).message), 400);
   }

package/src/server/routes/chat.ts

@@ -802,7 +802,7 @@ chatRoutes.post("/sessions/:id/images/strip", async (c) => {
     const mode: StripMode = (body as { mode?: unknown }).mode === "all" ? "all" : "oversized";
     const includeAttachments = (body as { includeAttachments?: unknown }).includeAttachments === true;
 
-    const { listRunningSessions } = await import("../ws/chat.ts");
+    const { listRunningSessions, dropSubprocessForTranscriptRewrite } = await import("../ws/chat.ts");
     if (listRunningSessions().some((s) => s.sessionId === sessionId)) {
       return c.json(err("Session is running — wait for the turn to finish"), 409);
     }
@@ -810,6 +810,13 @@ chatRoutes.post("/sessions/:id/images/strip", async (c) => {
     const found = locateTranscript(sessionId);
     if ("error" in found) return c.json(err(found.error), found.status);
 
+    // A subprocess that is merely idle is not "running", but it still holds the conversation
+    // in memory — including the image being stripped. Leaving it alive means the next turn
+    // re-sends the oversized attachment from memory and fails exactly as before, which is the
+    // failure this endpoint exists to clear. Drop it so the turn is rebuilt from the file we
+    // are about to rewrite.
+    dropSubprocessForTranscriptRewrite(sessionId);
+
     const result = await stripTranscriptImagesFile(found.path, mode, { includeAttachments });
     return c.json(ok({
       removed: result.removed,

package/src/server/routes/named-tunnel.ts

@@ -28,9 +28,12 @@ function assertMutationAllowed(c: Context): Response | null {
   }
   const origin = c.req.header("origin");
   if (origin) {
+    // Compare hostname only, not host:port: a 2-process dev setup (Vite proxy rewrites
+    // Host without X-Forwarded-Host) always differs by port, so a full-host compare rejects
+    // every dev request. Origin is browser-set, so a real cross-site attacker still can't forge it.
     let originHost: string | null = null;
-    try { originHost = new URL(origin).host; } catch { originHost = null; }
-    const requestHost = new URL(c.req.url).host;
+    try { originHost = new URL(origin).hostname; } catch { originHost = null; }
+    const requestHost = new URL(c.req.url).hostname;
     if (!originHost || originHost !== requestHost) {
       return c.json(err("cross-origin request rejected"), 403);
     }

package/src/server/routes/remote-desktop.ts

@@ -0,0 +1,64 @@
+/**
+ * `GET /api/remote-desktop/capabilities` (read-only, always answerable) and
+ * `POST /api/remote-desktop/session` (mints the single-use WS nonce). Guard style mirrors
+ * `named-tunnel.ts`: `authMiddleware` already passes every request through when PPM auth is
+ * disabled, so a feature that hands out host control must enforce `auth.enabled` itself, plus
+ * a same-origin check so a foreign page can't drive it via ambient browser credentials.
+ */
+import { Hono, type Context } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { configService } from "../../services/config.service.ts";
+import { getFfmpegCapabilities } from "../../services/media-transcode/ffmpeg-capabilities.ts";
+import { isRemoteDesktopEnabled } from "../../services/remote-desktop/remote-desktop-flag.ts";
+import { mintRemoteDesktopNonce } from "../../services/remote-desktop/remote-desktop-nonce.ts";
+import { isInputAvailable } from "../../services/remote-desktop/remote-desktop-input.ts";
+
+export const remoteDesktopRoutes = new Hono();
+
+function assertSessionAllowed(c: Context): Response | null {
+  if (!isRemoteDesktopEnabled()) {
+    return c.json(err("remote desktop is disabled (set REMOTE_DESKTOP_ENABLED=1)"), 404);
+  }
+  if (!configService.get("auth").enabled) {
+    return c.json(err("remote desktop requires PPM authentication to be enabled"), 403);
+  }
+  const origin = c.req.header("origin");
+  if (origin) {
+    // Compare *hostname* only, not host:port. `named-tunnel.ts`'s copy of this check compares
+    // the full `host` (hostname:port), which only ever matches when the browser's page and the
+    // API it's calling share one origin verbatim — true for the compiled/production build (one
+    // server, one port) but NOT for the standard two-process dev topology (`bun dev:web` on
+    // 5173 proxying to `bun dev:server` on 8081, or this feature's own alt-port test setup):
+    // Vite's dev proxy rewrites the `Host` header to the proxy target's port without adding
+    // `X-Forwarded-Host`, so the backend always sees a different port than the browser's real
+    // `Origin` — the full-host check would reject every dev-mode session request. A real
+    // cross-origin attacker (e.g. evil.com) cannot spoof `Origin` to say `localhost` in the
+    // first place — the browser sets it from the page's actual origin — so relaxing port
+    // equality does not weaken the protection this check exists for.
+    let originHost: string | null = null;
+    try { originHost = new URL(origin).hostname; } catch { originHost = null; }
+    let requestHost: string | null = null;
+    try { requestHost = new URL(c.req.url).hostname; } catch { requestHost = null; }
+    if (!originHost || !requestHost || originHost !== requestHost) {
+      return c.json(err("cross-origin request rejected"), 403);
+    }
+  }
+  return null;
+}
+
+remoteDesktopRoutes.get("/capabilities", async (c) => {
+  if (!isRemoteDesktopEnabled()) return c.json(err("remote desktop is disabled"), 404);
+  const caps = await getFfmpegCapabilities();
+  return c.json(ok({
+    ffmpegAvailable: !!caps.ffmpeg,
+    videoAvailable: process.platform === "win32" && !!caps.ffmpeg,
+    inputAvailable: isInputAvailable(),
+    authRequired: configService.get("auth").enabled,
+  }));
+});
+
+remoteDesktopRoutes.post("/session", (c) => {
+  const rejected = assertSessionAllowed(c);
+  if (rejected) return rejected;
+  return c.json(ok({ nonce: mintRemoteDesktopNonce(), wsPath: "/ws/remote-desktop" }));
+});

package/src/server/routes/settings.ts

@@ -114,6 +114,7 @@ const UI_PREF_VALIDATORS: Record<string, (v: unknown) => boolean> = {
   wordWrap: (v) => typeof v === "boolean",
   tabWrap: (v) => typeof v === "boolean",
   sidebarCollapsed: (v) => typeof v === "boolean",
+  remoteDesktopStatsVisible: (v) => typeof v === "boolean",
   sidebarWidth: (v) => typeof v === "number" && v >= 200 && v <= 600,
   gitStatusViewMode: (v) => v === "flat" || v === "tree",
   editorTabStyle: (v) => v === "default" || v === "boxed" || v === "pill",