@hienlh/ppm 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.8.3] - 2026-03-23
+
+### Fixed
+- **WSL timeout diagnostics**: Connection timeout error now detects WSL environment and suggests specific DNS/proxy troubleshooting steps
+- **No-credentials warning**: Log warning when no account and no API key in env — helps diagnose why SDK subprocess hangs
+
+## [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

package/package.json

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

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

@@ -553,6 +553,14 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         yield { type: "account_info" as const, accountId: account.id, accountLabel: account.label ?? account.email ?? "Unknown" };
       }
       const queryEnv = this.buildQueryEnv(meta.projectPath, account);
+
+      // Pre-flight: warn if no credentials at all (avoids 2-minute silent timeout)
+      if (!account) {
+        const hasApiKey = !!(queryEnv.ANTHROPIC_API_KEY || queryEnv.CLAUDE_CODE_OAUTH_TOKEN);
+        if (!hasApiKey) {
+          console.warn(`[sdk] session=${sessionId} no account and no API key in env — Claude CLI will use its own auth (if any)`);
+        }
+      }
       console.log(`[sdk] query: session=${sessionId} sdkId=${sdkId} isFirst=${isFirstMessage} fork=${shouldFork} cwd=${effectiveCwd} platform=${process.platform} accountMode=${!!account} permissionMode=${permissionMode} isBypass=${isBypass}`);
 
       // TODO: Remove when TS SDK fixes Windows stdin pipe buffering (see queryDirectCli() JSDoc for tracking issues)
@@ -797,6 +805,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               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}`);

package/src/server/ws/chat.ts

@@ -130,9 +130,14 @@ async function runStreamLoop(sessionId: string, providerId: string, content: str
         clearInterval(heartbeat);
         console.error(`[chat] session=${sessionId} SDK connection timeout after ${elapsed}s`);
         logSessionEvent(sessionId, "ERROR", `SDK connection timeout after ${elapsed}s — subprocess may have failed to start`);
+        const projectPath = entry?.projectPath ?? "";
+        const isWSL = projectPath.startsWith("/home/") || projectPath.startsWith("/mnt/");
+        const wslHint = isWSL
+          ? "\n\nWSL detected — this is likely a network issue. Try from your WSL terminal:\n  curl -s https://api.anthropic.com\nIf that fails, check WSL DNS settings (/etc/resolv.conf) or proxy configuration."
+          : "";
         safeSend(sessionId, {
           type: "error",
-          message: `Claude SDK failed to respond after ${elapsed}s. Check that "claude" CLI works in your terminal, or try: ppm start -f`,
+          message: `Claude SDK failed to respond after ${elapsed}s. The API may be unreachable from this machine.${wslHint}\n\nGeneral troubleshooting:\n• Check internet connectivity\n• Run \`claude\` in your terminal to verify it works\n• Try: ppm start -f`,
         });
         abortController.abort();
         return;
@@ -146,8 +151,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}`);