@hienlh/ppm 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.8.7] - 2026-03-23
+
+### Fixed
+- **Env var diagnostics in timeout/error messages**: When SDK hangs or returns `unknown` error, error message now guides user to check `ANTHROPIC_API_KEY`/`ANTHROPIC_BASE_URL` env vars (stale/invalid keys cause silent hang) with exact debug commands
+- **Shell env logging**: Log when shell environment has `ANTHROPIC_API_KEY`/`ANTHROPIC_BASE_URL` set — helps diagnose SDK hangs in server logs
+
+## [0.8.6] - 2026-03-23
+
+### Fixed
+- **Actionable timeout error**: Timeout error now shows project path, exact `claude -p "hi"` debug command, and steps to check hooks/MCP/settings
+- **SDK lifecycle logging**: All SDK `system` events (hook_started, init, etc.) now logged with full JSON — helps diagnose where SDK hangs
+
 ## [0.8.5] - 2026-03-23
 
 ### Fixed

package/package.json

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

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

@@ -82,6 +82,12 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     account: { id: string; accessToken: string } | null,
   ): Record<string, string | undefined> {
     const base = { ...process.env, ...this.getProjectEnvOverrides(projectPath) };
+    // Log if shell env has Anthropic vars — helps diagnose hanging SDK
+    for (const key of this.SENSITIVE_ENV_KEYS) {
+      if (process.env[key]) {
+        console.log(`[sdk] Shell env has ${key} set (length=${process.env[key]!.length})`);
+      }
+    }
     if (!account) return base;
     const isOAuthToken = account.accessToken.startsWith("sk-ant-oat");
     if (isOAuthToken) {
@@ -688,6 +694,11 @@ export class ClaudeAgentSdkProvider implements AIProvider {
           yield approvalEvents.shift()!;
         }
 
+        // Log all system events for debugging SDK lifecycle
+        if (msg.type === "system") {
+          console.log(`[sdk] session=${sessionId} system: subtype=${(msg as any).subtype ?? "none"} ${JSON.stringify(msg).slice(0, 500)}`);
+        }
+
         // Capture SDK session metadata from init message
         if (msg.type === "system" && (msg as any).subtype === "init") {
           const initMsg = msg as any;
@@ -808,7 +819,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 error in project "${effectiveCwd}". Debug: run \`cd ${effectiveCwd} && claude -p "hi"\` in your terminal. If that also fails, the issue is Claude CLI auth or project config (.claude/ folder). Try: 1) \`claude login\`, 2) Remove .claude/settings.local.json, 3) Create a new chat session.`,
+              unknown: `API error in project "${effectiveCwd}". Debug:\n1. Run: \`cd ${effectiveCwd} && claude -p "hi"\`\n2. Check env: \`echo $ANTHROPIC_API_KEY $ANTHROPIC_BASE_URL\` — stale/invalid keys cause this\n3. Try: \`ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL="" claude -p "hi"\`\n4. Refresh auth: \`claude login\``,
             };
             const hint = errorHints[assistantError] ?? `API error: ${assistantError}`;
             yield { type: "error", message: hint };

package/src/server/ws/chat.ts

@@ -135,9 +135,10 @@ async function runStreamLoop(sessionId: string, providerId: string, content: str
         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."
           : "";
+        const debugCmd = projectPath ? `cd ${projectPath} && claude -p "hi"` : `claude -p "hi"`;
         safeSend(sessionId, {
           type: "error",
-          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`,
+          message: `Claude SDK timed out after ${elapsed}s for project "${projectPath || "(no project)"}".${wslHint}\n\nDebug steps:\n1. Run: \`${debugCmd}\` — if it also hangs, the issue is your Claude CLI environment\n2. Check env vars: \`echo $ANTHROPIC_API_KEY $ANTHROPIC_BASE_URL\` — stale/invalid keys cause silent hang\n3. Try with env cleared: \`ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL="" ${debugCmd}\`\n4. Check hooks/MCP: \`cat ${projectPath}/.claude/settings.local.json\`\n5. Refresh auth: \`claude login\``,
         });
         abortController.abort();
         return;