@hienlh/ppm 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [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
+- **Diagnostic error messages for project-specific failures**: When SDK returns `assistant error: unknown`, error now includes project path and exact `claude` CLI command to run for diagnosis
+- **Full SDK event dump on error**: Log complete assistant message JSON for debugging (visible in server logs)
+- **Removed broken session retry**: Retry-as-fresh-session didn't help since fresh sessions also fail for the same project — removed to avoid masking the real error
+
 ## [0.8.4] - 2026-03-23
 
 ### Fixed

package/package.json

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

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

@@ -688,6 +688,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;
@@ -799,47 +804,16 @@ export class ClaudeAgentSdkProvider implements AIProvider {
           // 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) {
-            console.error(`[sdk] session=${sessionId} assistant error: ${assistantError} (isFirst=${isFirstMessage})`);
-            // If resuming an existing session and it errors → retry as fresh session
-            if (!isFirstMessage && retryCount < MAX_RETRIES) {
-              retryCount++;
-              console.warn(`[sdk] session=${sessionId} resume failed with assistant error "${assistantError}" — retrying as fresh session`);
-              yield { type: "text" as const, content: `Session resume failed (${assistantError}). Retrying with a fresh session...` };
-              // Re-create query without resume
-              const freshQ = query({
-                prompt: message,
-                options: {
-                  cwd: effectiveCwd,
-                  systemPrompt: systemPromptOpt,
-                  settingSources: ["user", "project"],
-                  env: queryEnv,
-                  settings: { permissions: { allow: [], deny: [] } },
-                  allowedTools,
-                  permissionMode,
-                  allowDangerouslySkipPermissions: isBypass,
-                  ...(permissionHooks && { hooks: permissionHooks }),
-                  ...(providerConfig.model && { model: providerConfig.model }),
-                  ...(providerConfig.effort && { effort: providerConfig.effort }),
-                  maxTurns: providerConfig.max_turns ?? 100,
-                  ...(providerConfig.max_budget_usd && { maxBudgetUsd: providerConfig.max_budget_usd }),
-                  ...(providerConfig.thinking_budget_tokens != null && {
-                    thinkingBudgetTokens: providerConfig.thinking_budget_tokens,
-                  }),
-                  canUseTool,
-                  includePartialMessages: true,
-                } as any,
-              });
-              this.activeQueries.set(sessionId, freshQ);
-              eventSource = freshQ;
-              continue retryLoop;
-            }
+            // Dump full SDK message for debugging
+            console.error(`[sdk] session=${sessionId} cwd=${effectiveCwd} assistant error: ${assistantError} (isFirst=${isFirstMessage} retry=${retryCount})`);
+            console.error(`[sdk] assistant message dump: ${JSON.stringify(msg).slice(0, 2000)}`);
             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.",
+              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.`,
             };
             const hint = errorHints[assistantError] ?? `API error: ${assistantError}`;
             yield { type: "error", message: hint };
@@ -1020,7 +994,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       } // end retryLoop
     } catch (e) {
       const msg = (e as Error).message ?? String(e);
-      console.error(`[sdk] error: ${msg}`);
+      console.error(`[sdk] session=${sessionId} cwd=${meta.projectPath} error: ${msg}`);
       if (msg.includes("abort") || msg.includes("closed")) {
         // User-initiated abort or WS closed — nothing to report
       } else if (!isFirstMessage && msg.includes("exited with code")) {

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 in your terminal: \`${debugCmd}\`\n2. Check for hanging hooks/MCP servers: \`cat ${projectPath}/.claude/settings.local.json\`\n3. Try removing project Claude config: \`mv ${projectPath}/.claude ${projectPath}/.claude.bak\`\n4. If none of the above helps, try: \`claude login\` to refresh auth`,
         });
         abortController.abort();
         return;