@hienlh/ppm 0.9.0-beta.9 → 0.9.1

package/src/services/supervisor.ts

@@ -35,8 +35,27 @@ const LOG_FILE = resolve(PPM_DIR, "ppm.log");
 let serverChild: Subprocess | null = null;
 let tunnelChild: Subprocess | null = null;
 let tunnelUrl: string | null = null;
+let adoptedTunnelPid: number | null = null; // PID of tunnel kept alive across upgrade
 let shuttingDown = false;
 
+type SupervisorState = "running" | "paused" | "upgrading";
+let supervisorState: SupervisorState = "running";
+
+let resumeResolve: (() => void) | null = null;
+
+function waitForResume(): Promise<void> {
+  return new Promise((resolve) => {
+    resumeResolve = resolve;
+  });
+}
+
+function triggerResume(): void {
+  if (resumeResolve) {
+    resumeResolve();
+    resumeResolve = null;
+  }
+}
+
 let serverRestarts = 0;
 let lastServerCrash = 0;
 let tunnelRestarts = 0;
@@ -129,8 +148,25 @@ export async function spawnServer(
   serverRestarts++;
 
   if (serverRestarts > MAX_RESTARTS) {
-    log("FATAL", `Server exceeded ${MAX_RESTARTS} restarts, giving up`);
-    shutdown();
+    log("WARN", `Server exceeded ${MAX_RESTARTS} restarts, pausing`);
+    notifyStateChange("running", "paused", "max_restarts_exceeded");
+    supervisorState = "paused";
+    updateStatus({
+      state: "paused",
+      pid: null,
+      pausedAt: new Date().toISOString(),
+      pauseReason: "max_restarts",
+      lastCrashError: `exit ${exitCode}`,
+    });
+    // Wait for resume signal — supervisor stays alive
+    await waitForResume();
+    // Resumed — reset and respawn
+    notifyStateChange("paused", "running", "user_resume");
+    supervisorState = "running";
+    serverRestarts = 0;
+    updateStatus({ state: "running", pausedAt: null, pauseReason: null });
+    log("INFO", "Resuming server after pause");
+    if (!shuttingDown) return spawnServer(serverArgs, logFd);
     return;
   }
 
@@ -189,12 +225,7 @@ async function syncUrlToCloud(url: string) {
   } catch {}
 }
 
-function startCloudHeartbeat(url: string) {
-  if (heartbeatTimer) clearInterval(heartbeatTimer);
-  heartbeatTimer = setInterval(() => {
-    if (tunnelUrl) syncUrlToCloud(tunnelUrl);
-  }, 5 * 60 * 1000);
-}
+// HTTP heartbeat removed — WS is the sole heartbeat mechanism (Phase 4)
 
 export async function spawnTunnel(port: number): Promise<void> {
   let bin: string;
@@ -230,9 +261,8 @@ export async function spawnTunnel(port: number): Promise<void> {
   updateStatus({ shareUrl: tunnelUrl, tunnelPid: tunnelChild.pid });
   log("INFO", `Tunnel ready: ${tunnelUrl} (PID: ${tunnelChild.pid})`);
 
-  // Sync new URL to cloud immediately + start periodic heartbeat
+  // One-time sync of tunnel URL to cloud (WS handles periodic heartbeat)
   await syncUrlToCloud(tunnelUrl);
-  startCloudHeartbeat(tunnelUrl);
 
   const exitCode = await tunnelChild.exited;
   tunnelChild = null;
@@ -282,26 +312,46 @@ function startServerHealthCheck(port: number) {
 
 function startTunnelProbe(port: number) {
   tunnelProbeTimer = setInterval(async () => {
-    if (shuttingDown || !tunnelUrl || !tunnelChild) {
-      tunnelFailCount = 0;
-      return;
+    if (shuttingDown || !tunnelUrl) { tunnelFailCount = 0; return; }
+    if (!tunnelChild && !adoptedTunnelPid) { tunnelFailCount = 0; return; }
+
+    // Check if adopted tunnel process is still alive
+    if (adoptedTunnelPid && !tunnelChild) {
+      try { process.kill(adoptedTunnelPid, 0); } catch {
+        log("WARN", "Adopted tunnel process died, respawning");
+        adoptedTunnelPid = null;
+        tunnelUrl = null;
+        updateStatus({ shareUrl: null, tunnelPid: null });
+        tunnelFailCount = 0;
+        spawnTunnel(port);
+        return;
+      }
     }
+
     try {
       const res = await fetch(`${tunnelUrl}/api/health`, {
         signal: AbortSignal.timeout(10_000),
       });
       if (res.ok) {
         tunnelFailCount = 0;
-        tunnelRestarts = 0; // reset on success
+        tunnelRestarts = 0;
         return;
       }
     } catch {}
     tunnelFailCount++;
-    if (tunnelFailCount >= TUNNEL_PROBE_FAIL_THRESHOLD && tunnelChild) {
+    if (tunnelFailCount >= TUNNEL_PROBE_FAIL_THRESHOLD) {
       log("WARN", `Tunnel URL dead (${tunnelFailCount} failures), regenerating`);
-      try { tunnelChild.kill(); } catch {}
+      if (tunnelChild) {
+        try { tunnelChild.kill(); } catch {}
+        // spawnTunnel loop handles respawn via exited promise
+      } else if (adoptedTunnelPid) {
+        try { process.kill(adoptedTunnelPid, "SIGTERM"); } catch {}
+        adoptedTunnelPid = null;
+        tunnelUrl = null;
+        updateStatus({ shareUrl: null, tunnelPid: null });
+        spawnTunnel(port);
+      }
       tunnelFailCount = 0;
-      // spawnTunnel loop handles respawn via exited promise
     }
   }, TUNNEL_PROBE_INTERVAL_MS);
 }
@@ -322,6 +372,39 @@ async function checkAvailableVersion() {
   }
 }
 
+/** Try to adopt an existing tunnel process from status.json (survives upgrade) */
+function adoptTunnel(): boolean {
+  try {
+    const status = readStatus();
+    const pid = status.tunnelPid as number;
+    const url = status.shareUrl as string;
+    if (!pid || !url) {
+      log("DEBUG", `adoptTunnel: missing tunnelPid(${pid}) or shareUrl(${url}) in status`);
+      return false;
+    }
+    process.kill(pid, 0); // throws if process is dead
+    adoptedTunnelPid = pid;
+    tunnelUrl = url;
+    log("INFO", `Adopted existing tunnel (PID: ${pid}, URL: ${url})`);
+    return true;
+  } catch (e) {
+    log("WARN", `adoptTunnel: tunnel PID ${(readStatus().tunnelPid)} unreachable: ${e}`);
+    return false;
+  }
+}
+
+/** Kill stale tunnel PID from status.json (cleanup after failed adoption) */
+function killStaleTunnel() {
+  try {
+    const status = readStatus();
+    const pid = status.tunnelPid as number;
+    if (!pid) return;
+    try { process.kill(pid, "SIGTERM"); } catch {}
+    log("INFO", `Killed stale tunnel (PID: ${pid})`);
+  } catch {}
+  updateStatus({ tunnelPid: null, shareUrl: null });
+}
+
 /** Spawn new supervisor from updated code, wait for it to be healthy, then exit */
 async function selfReplace(): Promise<{ success: boolean; error?: string }> {
   log("INFO", "Starting self-replace for upgrade");
@@ -330,11 +413,13 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
   try {
     // Prevent spawnServer crash-restart loop from respawning killed children
     shuttingDown = true;
+    notifyStateChange(supervisorState, "upgrading", "self_replace");
+    supervisorState = "upgrading";
+    updateStatus({ state: "upgrading" });
 
-    // Kill server + tunnel children FIRST to free the port for the new supervisor
-    log("INFO", "Stopping server and tunnel before spawning new supervisor");
+    // Kill server child to free the port; keep tunnel alive for domain continuity
+    log("INFO", "Stopping server before spawning new supervisor (tunnel kept alive)");
     if (serverChild) { try { serverChild.kill(); } catch {} serverChild = null; }
-    if (tunnelChild) { try { tunnelChild.kill(); } catch {} tunnelChild = null; }
     // Clear health timers so we don't try to respawn killed children
     if (healthTimer) { clearInterval(healthTimer); healthTimer = null; }
     if (tunnelProbeTimer) { clearInterval(tunnelProbeTimer); tunnelProbeTimer = null; }
@@ -372,20 +457,159 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     log("ERROR", "Self-replace timeout: new supervisor did not start");
     try { child.kill(); } catch {}
     shuttingDown = false;
+    notifyStateChange("upgrading", "running", "upgrade_failed");
+    supervisorState = "running";
+    updateStatus({ state: "running" });
     return { success: false, error: "New supervisor failed to start within 30s" };
   } catch (e) {
     log("ERROR", `Self-replace error: ${e}`);
     shuttingDown = false;
+    notifyStateChange("upgrading", "running", "upgrade_failed");
+    supervisorState = "running";
+    updateStatus({ state: "running" });
     return { success: false, error: (e as Error).message };
   }
 }
 
+// ─── Cloud WS integration ─────────────────────────────────────────────
+
+/** Notify Cloud of supervisor state change via WS */
+async function notifyStateChange(from: string, to: string, reason: string) {
+  try {
+    const { send, isConnected } = await import("./cloud-ws.service.ts");
+    if (isConnected()) {
+      send({
+        type: "state_change",
+        from,
+        to,
+        reason,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  } catch {}
+}
+
+/** Connect supervisor to Cloud via WebSocket (if device is linked) */
+async function connectCloud(opts: { port: number }, serverArgs: string[], logFd: number) {
+  try {
+    const { getCloudDevice } = await import("./cloud.service.ts");
+    const device = getCloudDevice();
+    if (!device) return; // not linked to cloud
+
+    const { connect, onCommand } = await import("./cloud-ws.service.ts");
+    const { VERSION } = await import("../version.ts");
+    const startTime = Date.now();
+
+    connect({
+      cloudUrl: device.cloud_url,
+      deviceId: device.device_id,
+      secretKey: device.secret_key,
+      heartbeatFn: () => {
+        const status = readStatus();
+        // Re-read device file each heartbeat to pick up name changes
+        const currentDevice = getCloudDevice();
+        return {
+          type: "heartbeat" as const,
+          tunnelUrl,
+          state: supervisorState,
+          // Use server-reported version (source of truth) with supervisor fallback
+          appVersion: (status.serverVersion as string) || VERSION,
+          availableVersion: (status.availableVersion as string) || null,
+          serverPid: serverChild?.pid ?? null,
+          uptime: Math.floor((Date.now() - startTime) / 1000),
+          deviceName: currentDevice?.name ?? device.name,
+          timestamp: new Date().toISOString(),
+        };
+      },
+    });
+
+    // Handle commands from Cloud
+    onCommand(async (cmd) => {
+      const { send } = await import("./cloud-ws.service.ts");
+      const sendResult = (success: boolean, error?: string, data?: Record<string, unknown>) => {
+        send({
+          type: "command_result",
+          id: cmd.id,
+          success,
+          error,
+          data,
+          timestamp: new Date().toISOString(),
+        });
+      };
+
+      log("INFO", `Cloud command received: ${cmd.action}`);
+
+      // Send immediate ack so Cloud can update UI before processing
+      send({
+        type: "command_ack",
+        id: cmd.id,
+        timestamp: new Date().toISOString(),
+      });
+
+      switch (cmd.action) {
+        case "restart":
+          if (serverChild) {
+            serverRestartRequested = true;
+            try { serverChild.kill(); } catch {}
+            sendResult(true);
+          } else if (supervisorState === "paused") {
+            triggerResume();
+            sendResult(true);
+          } else {
+            sendResult(false, "No server child to restart");
+          }
+          break;
+
+        case "resume":
+          if (supervisorState === "paused") {
+            triggerResume();
+            sendResult(true);
+          } else {
+            sendResult(false, "Not in paused state");
+          }
+          break;
+
+        case "stop":
+          sendResult(true);
+          // Delay exit to allow WS buffer to flush
+          setTimeout(() => {
+            shutdown();
+            process.exit(0);
+          }, 500);
+          break;
+
+        case "status":
+          sendResult(true, undefined, {
+            state: supervisorState,
+            serverPid: serverChild?.pid ?? null,
+            tunnelUrl,
+            serverRestarts,
+          });
+          break;
+
+        default:
+          sendResult(false, `Unknown action: ${cmd.action}`);
+      }
+    });
+  } catch (e) {
+    log("WARN", `Cloud WS setup failed: ${e}`);
+  }
+}
+
 // ─── Shutdown ──────────────────────────────────────────────────────────
 export function shutdown() {
   if (shuttingDown) return;
   shuttingDown = true;
   log("INFO", "Supervisor shutting down");
 
+  // Unblock if paused
+  triggerResume();
+
+  // Disconnect Cloud WS
+  import("./cloud-ws.service.ts")
+    .then(({ disconnect }) => disconnect())
+    .catch(() => {});
+
   if (healthTimer) clearInterval(healthTimer);
   if (tunnelProbeTimer) clearInterval(tunnelProbeTimer);
   if (heartbeatTimer) clearInterval(heartbeatTimer);
@@ -394,6 +618,7 @@ export function shutdown() {
 
   if (serverChild) { try { serverChild.kill(); } catch {} }
   if (tunnelChild) { try { tunnelChild.kill(); } catch {} }
+  if (adoptedTunnelPid) { try { process.kill(adoptedTunnelPid, "SIGTERM"); } catch {} }
 }
 
 // ─── Main entry ────────────────────────────────────────────────────────
@@ -414,7 +639,10 @@ export async function runSupervisor(opts: {
 
   // Write supervisor PID + clear stale availableVersion from previous run
   writeFileSync(PID_FILE, String(process.pid));
-  updateStatus({ supervisorPid: process.pid, port: opts.port, host: opts.host, availableVersion: null });
+  updateStatus({
+    supervisorPid: process.pid, port: opts.port, host: opts.host, availableVersion: null,
+    state: "running", pausedAt: null, pauseReason: null, lastCrashError: null,
+  });
 
   // Build __serve__ args
   const serverArgs = [
@@ -428,8 +656,13 @@ export async function runSupervisor(opts: {
   process.on("SIGTERM", () => { shutdown(); process.exit(0); });
   process.on("SIGINT", () => { shutdown(); process.exit(0); });
 
-  // SIGUSR2 = graceful server restart (tunnel stays alive)
+  // SIGUSR2 = graceful server restart (tunnel stays alive) or resume from paused
   process.on("SIGUSR2", () => {
+    if (supervisorState === "paused") {
+      log("INFO", "SIGUSR2 received while paused, resuming server");
+      triggerResume();
+      return;
+    }
     log("INFO", "SIGUSR2 received, restarting server only");
     if (serverChild) {
       serverRestartRequested = true; // flag so spawnServer skips backoff
@@ -443,9 +676,9 @@ export async function runSupervisor(opts: {
     const result = await selfReplace();
     if (!result.success) {
       log("ERROR", `Self-replace failed: ${result.error}, restarting children`);
-      // Respawn server (and tunnel if configured) since selfReplace killed them
       spawnServer(serverArgs, logFd);
-      if (opts.share) spawnTunnel(opts.port);
+      // Tunnel was kept alive during selfReplace; only respawn if dead
+      if (opts.share && !tunnelChild && !tunnelUrl) spawnTunnel(opts.port);
     }
   });
 
@@ -458,16 +691,29 @@ export async function runSupervisor(opts: {
     upgradeCheckTimer = setInterval(checkAvailableVersion, UPGRADE_CHECK_INTERVAL_MS);
   }, UPGRADE_SKIP_INITIAL_MS);
 
+  // Connect to Cloud via WebSocket (if device is linked)
+  connectCloud(opts, serverArgs, logFd);
+
   // Spawn server + tunnel in parallel
   const promises: Promise<void>[] = [spawnServer(serverArgs, logFd)];
 
   if (opts.share) {
     startTunnelProbe(opts.port);
-    promises.push(spawnTunnel(opts.port));
+    // Try adopting tunnel kept alive from previous upgrade; spawn new if dead
+    if (!adoptTunnel()) {
+      killStaleTunnel(); // kill orphaned tunnel before spawning new one
+      promises.push(spawnTunnel(opts.port));
+    }
   }
 
   await Promise.all(promises);
 
+  // If upgrading, selfReplace handles process.exit — wait for it
+  if (supervisorState === "upgrading") {
+    log("INFO", "Server loop exited during upgrade, waiting for selfReplace to finish");
+    await new Promise(() => {}); // selfReplace will call process.exit()
+  }
+
   // If we get here, both loops exited (shutdown or max restarts)
   log("INFO", "Supervisor exiting");
   process.exit(shuttingDown ? 0 : 1);

package/src/types/api.ts

@@ -44,4 +44,5 @@ export type ChatWsServerMessage =
   | { type: "session_state"; sessionId: string; phase: SessionPhase; pendingApproval: { requestId: string; tool: string; input: unknown } | null; sessionTitle: string | null }
   | { type: "turn_events"; events: unknown[] }
   | { type: "title_updated"; title: string }
+  | { type: "compact_status"; status: "compacting" | "done" }
   | { type: "ping" };

package/src/types/chat.ts

@@ -29,6 +29,8 @@ export interface AIProvider {
   listSessionsByDir?(dir: string): Promise<SessionInfo[]>;
   ensureProjectPath?(sessionId: string, path: string): void;
   setForkSource?(sessionId: string, sourceSessionId: string): void;
+  forkAtMessage?(sessionId: string, messageId: string, opts?: { title?: string; dir?: string }): Promise<{ sessionId: string }>;
+  markAsResumed?(sessionId: string): void;
   isAvailable?(): Promise<boolean>;
   listModels?(): Promise<ModelOption[]>;
 }
@@ -61,6 +63,7 @@ export interface SessionInfo {
   projectName?: string;
   createdAt: string;
   updatedAt?: string;
+  pinned?: boolean;
 }
 
 export interface LimitBucket {
@@ -111,6 +114,7 @@ export type ChatEvent =
   | { type: "done"; sessionId: string; resultSubtype?: ResultSubtype; numTurns?: number; contextWindowPct?: number }
   | { type: "session_migrated"; oldSessionId: string; newSessionId: string }
   | { type: "account_info"; accountId: string; accountLabel: string }
+  | { type: "account_retry"; reason: string; accountId?: string; accountLabel?: string }
   | { type: "system"; subtype: string };
 
 export type ToolApprovalHandler = (

package/src/types/extension-messages.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared message types for the Extension WebSocket bridge.
+ * Server ↔ Client communication for extension UI updates.
+ */
+import type { ExtensionContributes } from "./extension.ts";
+
+// --- UI types (shared with extension-store) ---
+
+export interface StatusBarItemMsg {
+  id: string;
+  text: string;
+  tooltip?: string;
+  command?: string;
+  alignment: "left" | "right";
+  priority: number;
+  extensionId?: string;
+}
+
+export interface TreeItemMsg {
+  id: string;
+  label: string;
+  description?: string;
+  tooltip?: string;
+  icon?: string;
+  collapsibleState: "none" | "collapsed" | "expanded";
+  command?: string;
+  children?: TreeItemMsg[];
+  contextValue?: string;
+}
+
+export interface QuickPickItemMsg {
+  label: string;
+  description?: string;
+  detail?: string;
+  picked?: boolean;
+}
+
+// --- Server → Client messages ---
+
+export type ExtServerMsg =
+  | { type: "tree:update"; viewId: string; items: TreeItemMsg[]; parentId?: string }
+  | { type: "tree:refresh"; viewId: string }
+  | { type: "statusbar:update"; item: StatusBarItemMsg }
+  | { type: "statusbar:remove"; itemId: string }
+  | { type: "notification"; id: string; level: "info" | "warn" | "error"; message: string; actions?: string[] }
+  | { type: "quickpick:show"; requestId: string; items: QuickPickItemMsg[]; options?: { placeholder?: string; canPickMany?: boolean } }
+  | { type: "inputbox:show"; requestId: string; options: { prompt?: string; value?: string; placeholder?: string; password?: boolean } }
+  | { type: "webview:create"; panelId: string; extensionId: string; viewType: string; title: string }
+  | { type: "webview:html"; panelId: string; html: string }
+  | { type: "webview:dispose"; panelId: string }
+  | { type: "webview:postMessage"; panelId: string; message: unknown }
+  | { type: "contributions:update"; contributions: ExtensionContributes };
+
+// --- Client → Server messages ---
+
+export type ExtClientMsg =
+  | { type: "ready" }
+  | { type: "command:execute"; command: string; args?: unknown[] }
+  | { type: "tree:expand"; viewId: string; itemId: string }
+  | { type: "tree:click"; viewId: string; itemId: string; command?: string }
+  | { type: "webview:message"; panelId: string; message: unknown }
+  | { type: "quickpick:resolve"; requestId: string; selected: QuickPickItemMsg[] | null }
+  | { type: "inputbox:resolve"; requestId: string; value: string | null }
+  | { type: "notification:action"; id: string; action: string | null };

package/src/types/extension.ts

@@ -0,0 +1,131 @@
+/** Extension manifest — parsed from package.json of an installed extension */
+export interface ExtensionManifest {
+  id: string; // npm package name, e.g. @ppm/ext-database
+  version: string;
+  main: string; // JS entry point relative to extension root
+  displayName?: string;
+  description?: string;
+  icon?: string;
+  engines?: { ppm?: string };
+  activationEvents?: string[];
+  contributes?: ExtensionContributes;
+  ppm?: {
+    displayName?: string;
+    icon?: string;
+    webviewDir?: string;
+  };
+  permissions?: string[];
+}
+
+/** VSCode-compatible contributes section */
+export interface ExtensionContributes {
+  commands?: ContributedCommand[];
+  views?: Record<string, ContributedView[]>;
+  configuration?: { properties?: Record<string, ConfigProperty> };
+  menus?: Record<string, ContributedMenu[]>;
+}
+
+export interface ContributedCommand {
+  command: string;
+  title: string;
+  icon?: string;
+  category?: string;
+}
+
+export interface ContributedView {
+  id: string;
+  name: string;
+  type?: "tree" | "webview";
+  icon?: string;
+}
+
+export interface ConfigProperty {
+  type?: string;
+  default?: unknown;
+  description?: string;
+  enum?: unknown[];
+}
+
+export interface ContributedMenu {
+  command: string;
+  when?: string;
+  group?: string;
+}
+
+/** Runtime extension info returned by API */
+export interface ExtensionInfo {
+  id: string;
+  version: string;
+  displayName: string;
+  description: string;
+  icon: string;
+  enabled: boolean;
+  activated: boolean;
+  manifest: ExtensionManifest;
+}
+
+/** DB row for extensions table */
+export interface ExtensionRow {
+  id: string;
+  version: string;
+  display_name: string | null;
+  description: string | null;
+  icon: string | null;
+  enabled: number; // 0 | 1
+  manifest: string; // JSON
+  installed_at: string;
+  updated_at: string;
+}
+
+/** DB row for extension_storage table */
+export interface ExtensionStorageRow {
+  ext_id: string;
+  scope: string;
+  key: string;
+  value: string | null; // JSON
+}
+
+/** Extension activation context passed to ext.activate() */
+export interface ExtensionContext {
+  extensionId: string;
+  extensionPath: string;
+  globalState: StateStore;
+  workspaceState: StateStore;
+  subscriptions: Disposable[];
+}
+
+export interface StateStore {
+  get<T = unknown>(key: string, defaultValue?: T): T | undefined;
+  update(key: string, value: unknown): Promise<void>;
+  keys(): readonly string[];
+}
+
+export interface Disposable {
+  dispose(): void;
+}
+
+/** RPC message types between main process and extension host worker */
+export type RpcMessage =
+  | RpcRequest
+  | RpcResponse
+  | RpcEvent;
+
+export interface RpcRequest {
+  type: "request";
+  id: number;
+  method: string;
+  params: unknown[];
+}
+
+export interface RpcResponse {
+  type: "response";
+  id: number;
+  result?: unknown;
+  error?: string;
+}
+
+export interface RpcEvent {
+  type: "event";
+  event: string;
+  data: unknown;
+}