From 9f09a19a093fc40a1c331ea55219d2196ea07e7e Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Fri, 10 Apr 2026 10:05:13 +0700
Subject: [PATCH] Gate Claude SDK stream trace logs behind PASEO_CLAUDE_DEBUG

Per-token trace logs from the query pump fire twice per streaming event
and contribute to memory growth under heavy use. Gate them behind an
opt-in env var so they're available for debugging but silent by default.
---
 packages/server/.env.example                  |  3 ++
 .../server/agent/providers/claude-agent.ts    | 40 +++++++++++--------
 2 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/packages/server/.env.example b/packages/server/.env.example
index f9771f268..960466c82 100644
--- a/packages/server/.env.example
+++ b/packages/server/.env.example
@@ -18,3 +18,6 @@ PASEO_LISTEN=127.0.0.1:6767
 # Debug recordings (dictation + STT input + TTS output)
 # When enabled, recordings are saved under `${cwd}/.debug/recordings/`
 PASEO_DICTATION_DEBUG=1
+
+# Enable verbose Claude SDK stream logging (trace-level per-token logs)
+PASEO_CLAUDE_DEBUG=1
diff --git a/packages/server/src/server/agent/providers/claude-agent.ts b/packages/server/src/server/agent/providers/claude-agent.ts
index 2218a0fc5..aa32dfa22 100644
--- a/packages/server/src/server/agent/providers/claude-agent.ts
+++ b/packages/server/src/server/agent/providers/claude-agent.ts
@@ -1047,6 +1047,8 @@ export function readEventIdentifiers(message: SDKMessage): EventIdentifiers {
   };
 }
 
+const claudeDebug = process.env.PASEO_CLAUDE_DEBUG === "1";
+
 export class ClaudeAgentClient implements AgentClient {
   readonly provider: "claude" = "claude";
   readonly capabilities = CLAUDE_CAPABILITIES;
@@ -2454,15 +2456,17 @@ class ClaudeAgentSession implements AgentSession {
       while (!this.closed && this.query === activeQuery) {
         try {
           for await (const message of activeQuery) {
-            this.logger.trace(
-              {
-                claudeSessionId: this.claudeSessionId,
-                messageType: message.type,
-                messageSubtype: "subtype" in message ? message.subtype : undefined,
-                messageUuid: "uuid" in message ? message.uuid : undefined,
-              },
-              "Claude query pump: raw SDK message",
-            );
+            if (claudeDebug) {
+              this.logger.trace(
+                {
+                  claudeSessionId: this.claudeSessionId,
+                  messageType: message.type,
+                  messageSubtype: "subtype" in message ? message.subtype : undefined,
+                  messageUuid: "uuid" in message ? message.uuid : undefined,
+                },
+                "Claude query pump: raw SDK message",
+              );
+            }
             consecutiveInterruptAbortRecoveries = 0;
             if (await this.handleMissingResumedConversation(message, activeQuery)) {
               return;
@@ -2538,14 +2542,16 @@ class ClaudeAgentSession implements AgentSession {
     const turnId = this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? null;
     const identifiers = readEventIdentifiers(message);
 
-    this.logger.trace(
-      {
-        claudeSessionId: this.claudeSessionId,
-        messageType: message.type,
-        turnId,
-      },
-      "Claude query pump: SDK message",
-    );
+    if (claudeDebug) {
+      this.logger.trace(
+        {
+          claudeSessionId: this.claudeSessionId,
+          messageType: message.type,
+          turnId,
+        },
+        "Claude query pump: SDK message",
+      );
+    }
 
     const messageEvents = this.translateMessageToEvents(message, {
       suppressAssistantText: true,