@hienlh/ppm 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.8.2] - 2026-03-23
+
+### Fixed
+- **Heartbeat during SDK connection**: Keep "Connecting... (Xs)" indicator alive until real content arrives — previously stopped by `account_info` event, causing misleading "thinking" state during 3-minute SDK failures
+- **Unknown API error hint**: "API error: unknown" now shows actionable guidance (check connectivity, re-add account, new session)
+
+## [0.8.1] - 2026-03-23
+
+### Fixed
+- **Silent timeout on account decrypt failure**: When all account tokens fail decryption (e.g. different machine key in WSL), now shows actionable error instead of 120s silent timeout
+- **SDK error extraction**: Use `errors: string[]` array per SDK spec instead of non-existent singular `error` field — previously swallowed error details
+- **Assistant message error detection**: Handle `SDKAssistantMessage.error` field for `authentication_failed`, `billing_error`, `rate_limit`, `server_error` per SDK spec
+- **Empty success detection**: Detect SDK returning `success` with 0 turns and no content as silent failure, surface guidance to user
+- **Network error hints**: Add WSL-specific hints for ConnectionRefused, auth failures, and connectivity issues
+
 ## [0.8.0] - 2026-03-23
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

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

@@ -106,7 +106,9 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     if (!event || typeof event !== "object") return null;
     const e = event as Record<string, unknown>;
     if (e.type === "result" && e.subtype === "error_during_execution") {
-      const msg = String(e.error ?? e.error_message ?? e.message ?? "");
+      // SDK uses `errors: string[]` array for error details
+      const errorsArr = Array.isArray(e.errors) ? (e.errors as string[]).join(" ") : "";
+      const msg = errorsArr || String(e.error ?? "");
       if (msg.includes("429") || msg.toLowerCase().includes("rate limit") || msg.toLowerCase().includes("overloaded")) return 429;
       if (msg.includes("401") || msg.toLowerCase().includes("unauthorized") || msg.toLowerCase().includes("invalid api key")) return 401;
     }
@@ -533,7 +535,19 @@ export class ClaudeAgentSdkProvider implements AIProvider {
 
       // Account-based auth injection (multi-account mode)
       // Fallback to existing env (ANTHROPIC_API_KEY) when no accounts configured.
-      const account = accountSelector.isEnabled() ? accountSelector.next() : null;
+      const accountsEnabled = accountSelector.isEnabled();
+      const account = accountsEnabled ? accountSelector.next() : null;
+      if (accountsEnabled && !account) {
+        // All accounts in DB but none usable
+        const reason = accountSelector.lastFailReason;
+        const hint = reason === "all_decrypt_failed"
+          ? "Account tokens were encrypted with a different machine key. Re-add your accounts in Settings, or copy ~/.ppm/account.key from the original machine."
+          : "All accounts are disabled or in cooldown. Check Settings → Accounts.";
+        console.error(`[sdk] session=${sessionId} account auth failed (${reason}): ${hint}`);
+        yield { type: "error" as const, message: `Authentication failed: ${hint}` };
+        yield { type: "done" as const, sessionId, resultSubtype: "error_auth" };
+        return;
+      }
       if (account) {
         console.log(`[sdk] Using account ${account.id} (${account.email ?? "no-email"})`);
         yield { type: "account_info" as const, accountId: account.id, accountLabel: account.label ?? account.email ?? "Unknown" };
@@ -774,6 +788,21 @@ export class ClaudeAgentSdkProvider implements AIProvider {
 
         // Full assistant message
         if (msg.type === "assistant") {
+          // SDK assistant messages can carry an error field for auth/billing/rate-limit failures
+          const assistantError = (msg as any).error as string | undefined;
+          if (assistantError) {
+            const errorHints: Record<string, string> = {
+              authentication_failed: "API authentication failed. Check your account credentials in Settings → Accounts.",
+              billing_error: "Billing error on this account. Check your subscription status.",
+              rate_limit: "Rate limited by the API. Please wait and try again.",
+              invalid_request: "Invalid request sent to the API.",
+              server_error: "Anthropic API server error. Try again shortly.",
+              unknown: "API connection failed. Possible causes: network unreachable, expired OAuth token, or API outage. Try: 1) Check connectivity (`curl -s https://api.anthropic.com`), 2) Re-add account in Settings, 3) Create a new chat session.",
+            };
+            const hint = errorHints[assistantError] ?? `API error: ${assistantError}`;
+            console.error(`[sdk] session=${sessionId} assistant error: ${assistantError}`);
+            yield { type: "error", message: hint };
+          }
           const content = (msg as any).message?.content;
           if (Array.isArray(content)) {
             for (const block of content) {
@@ -875,9 +904,11 @@ export class ClaudeAgentSdkProvider implements AIProvider {
 
           // Surface non-success subtypes as errors so FE can display them
           if (subtype && subtype !== "success") {
-            // Extract error detail from SDK result — check multiple possible fields
-            const sdkError = result.error ?? result.error_message ?? result.message ?? result.reason ?? "";
-            const sdkDetail = typeof sdkError === "string" ? sdkError : JSON.stringify(sdkError);
+            // SDK error results use `errors: string[]` array (not singular `error`)
+            const errorsArr = Array.isArray(result.errors) ? result.errors : [];
+            const sdkDetail = errorsArr.length > 0
+              ? errorsArr.join("\n")
+              : (typeof result.error === "string" ? result.error : "");
             // Log full result for debugging (truncated at 2000 chars)
             console.error(`[sdk] result error: subtype=${subtype} turns=${result.num_turns ?? 0} detail=${sdkDetail || "(none)"}`);
             console.error(`[sdk] result full dump: ${JSON.stringify(result).slice(0, 2000)}`);
@@ -887,13 +918,35 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               error_during_execution: "Agent encountered an error during execution.",
             };
             const baseMsg = errorMessages[subtype] ?? `Agent stopped: ${subtype}`;
-            const fullMsg = sdkDetail ? `${baseMsg}\n${sdkDetail}` : baseMsg;
+            // Add specific hints for common network/auth errors
+            const detailLower = sdkDetail.toLowerCase();
+            let hint = "";
+            if (detailLower.includes("connectionrefused") || detailLower.includes("connection refused") || detailLower.includes("econnrefused")) {
+              hint = "\n\nHint: Cannot reach Anthropic API. If running in WSL, check DNS/proxy settings (e.g. `curl -s https://api.anthropic.com` from WSL terminal).";
+            } else if (detailLower.includes("unable to connect")) {
+              hint = "\n\nHint: Network connectivity issue. Check your internet connection and firewall/proxy settings.";
+            } else if (detailLower.includes("401") || detailLower.includes("unauthorized") || detailLower.includes("invalid api key")) {
+              hint = "\n\nHint: Authentication failed. Try re-adding your account in Settings → Accounts.";
+            }
+            const fullMsg = sdkDetail ? `${baseMsg}\n${sdkDetail}${hint}` : baseMsg;
             yield {
               type: "error",
               message: fullMsg,
             };
           }
 
+          // Detect empty/suspicious success — SDK returned "success" but no real assistant content
+          if ((!subtype || subtype === "success") && (result.num_turns ?? 0) === 0 && !assistantContent) {
+            // SDK success result has `result: string` containing final text
+            const resultText = typeof result.result === "string" ? result.result : "";
+            console.warn(`[sdk] session=${sessionId} result success but 0 turns, no assistant content, result="${resultText.slice(0, 200)}"`);
+            console.warn(`[sdk] result dump: ${JSON.stringify(result).slice(0, 2000)}`);
+            const hint = resultText
+              ? `Claude returned: "${resultText}"\nThis may indicate a session or connection issue. Try creating a new chat session.`
+              : "Claude returned no response (0 turns). This usually means the API connection failed silently. Check that `claude` CLI works in your terminal, or try creating a new chat session.";
+            yield { type: "error", message: hint };
+          }
+
           // Store subtype and numTurns for the done event
           resultSubtype = subtype;
           resultNumTurns = result.num_turns as number | undefined;
@@ -961,7 +1014,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
             if (retryMsg.type === "result") {
               const r = retryMsg as any;
               if (r.subtype && r.subtype !== "success") {
-                yield { type: "error", message: r.error ?? `Agent stopped: ${r.subtype}` };
+                const retryErrors = Array.isArray(r.errors) ? r.errors.join("\n") : "";
+                yield { type: "error", message: retryErrors || `Agent stopped: ${r.subtype}` };
               }
               resultSubtype = r.subtype;
               resultNumTurns = r.num_turns;

package/src/server/ws/chat.ts

@@ -146,8 +146,12 @@ async function runStreamLoop(sessionId: string, providerId: string, content: str
       const ev = event as any;
       const evType = ev.type ?? "unknown";
 
-      // First event received — stop heartbeat, switch to streaming status
-      if (!firstEventReceived) {
+      // First content event — stop heartbeat, switch to streaming status.
+      // Skip metadata events (account_info, streaming_status) that arrive before
+      // the SDK subprocess actually produces output — keeps heartbeat + "connecting"
+      // indicator alive until real content flows.
+      const isMetadataEvent = evType === "account_info" || evType === "streaming_status";
+      if (!firstEventReceived && !isMetadataEvent) {
         firstEventReceived = true;
         const waitMs = Date.now() - startTime;
         console.log(`[chat] session=${sessionId} first SDK event after ${waitMs}ms: type=${evType}`);

package/src/services/account-selector.service.ts

@@ -36,11 +36,20 @@ class AccountSelectorService {
     setConfigValue(MAX_RETRY_CONFIG_KEY, String(n));
   }
 
+  /** Reason for the last null return from next() */
+  private _lastFailReason: "none" | "no_active" | "all_decrypt_failed" = "none";
+
+  /** Why the last next() call returned null */
+  get lastFailReason(): "none" | "no_active" | "all_decrypt_failed" {
+    return this._lastFailReason;
+  }
+
   /**
    * Pick next available account (skips cooldown/disabled).
    * Returns null if no active accounts available.
    */
   next(): AccountWithTokens | null {
+    this._lastFailReason = "none";
     const now = Math.floor(Date.now() / 1000);
     const allAccounts = accountService.list();
 
@@ -53,7 +62,10 @@ class AccountSelectorService {
     }
 
     const active = accountService.list().filter((a) => a.status === "active");
-    if (active.length === 0) return null;
+    if (active.length === 0) {
+      this._lastFailReason = "no_active";
+      return null;
+    }
 
     let pickedId: string;
     if (this.getStrategy() === "fill-first") {
@@ -66,7 +78,11 @@ class AccountSelectorService {
       this.cursor = (this.cursor + 1) % active.length;
     }
     this._lastPickedId = pickedId;
-    return accountService.getWithTokens(pickedId);
+    const result = accountService.getWithTokens(pickedId);
+    if (!result) {
+      this._lastFailReason = "all_decrypt_failed";
+    }
+    return result;
   }
 
   /** Called when account receives 429 — apply exponential backoff */

package/src/types/chat.ts

@@ -79,7 +79,8 @@ export type ResultSubtype =
   | "success"
   | "error_max_turns"
   | "error_max_budget_usd"
-  | "error_during_execution";
+  | "error_during_execution"
+  | "error_auth";
 
 export type ChatEvent =
   | { type: "text"; content: string; parentToolUseId?: string }