@northflare/runner 0.0.1

package/src/components/claude-sdk-manager.ts

@@ -0,0 +1,1354 @@
+/**
+ * ClaudeManager - Manages Claude conversations using SDK-native patterns
+ *
+ * This component handles stateful conversation lifecycle management, maintaining
+ * persistent conversation instances indexed by taskId. Uses the SDK's native
+ * capabilities including the builder pattern, native session management, and
+ * built-in streaming instead of custom wrappers.
+ *
+ * Key improvements:
+ * - Uses claude() builder pattern for simplified configuration
+ * - Native session management with withSessionId()
+ * - Direct AsyncGenerator streaming without custom wrappers
+ * - SDK's onProcessComplete() for proper cleanup
+ * - Simplified error handling while maintaining compatibility
+ */
+
+import { query as sdkQuery } from "@anthropic-ai/claude-agent-sdk";
+// Keep SDKMessage loosely typed to avoid tight coupling to SDK typings
+type SDKMessage = any;
+import { IRunnerApp } from "../types/runner-interface";
+import { EnhancedRepositoryManager } from "./enhanced-repository-manager";
+import { ConversationContext, ConversationConfig, Message } from "../types";
+import { statusLineManager } from "../utils/status-line";
+import { console } from "../utils/console";
+import { expandEnv } from "../utils/expand-env";
+import * as jwt from "jsonwebtoken";
+
+export class ClaudeManager {
+  private runner: IRunnerApp;
+  private repositoryManager: EnhancedRepositoryManager;
+
+  constructor(
+    runner: IRunnerApp,
+    repositoryManager: EnhancedRepositoryManager
+  ) {
+    this.runner = runner;
+    this.repositoryManager = repositoryManager;
+
+    // Log debug mode status
+    if (process.env["DEBUG"] === "true") {
+      console.log(
+        "[ClaudeManager] DEBUG MODE ENABLED - Claude SDK will log verbose output"
+      );
+    }
+
+    // Note: MCP host configuration is passed from orchestrator
+    // Runner does not define its own MCP tools
+    this.setupInternalMcpServer();
+  }
+
+  private setupInternalMcpServer(): void {
+    // Runner does not define its own MCP tools
+    // All MCP tool configuration is passed from orchestrator in conversation config
+  }
+
+  async startConversation(
+    conversationObjectType: "Task" | "TaskPlan",
+    conversationObjectId: string,
+    config: ConversationConfig,
+    initialMessages: Message[],
+    conversationData?: {
+      id: string;
+      objectType: string;
+      objectId: string;
+      model: string;
+      globalInstructions: string;
+      workspaceInstructions: string;
+      permissionsMode: string;
+      agentSessionId: string;
+    }
+  ): Promise<ConversationContext> {
+    // Returns conversation context
+    // Greenfield: conversationData.id is required as the authoritative DB conversation ID
+    if (!conversationData?.id) {
+      throw new Error(
+        "startConversation requires conversationData with a valid conversation.id"
+      );
+    }
+    // Use sessionId from config if resuming, or agentSessionId from conversationData if available
+    const agentSessionId =
+      config.sessionId || conversationData.agentSessionId || "";
+    const conversationId = conversationData.id;
+
+    const context: ConversationContext = {
+      conversationId,
+      agentSessionId, // Will be updated by onSessionId callback for new conversations
+      conversationObjectType,
+      conversationObjectId,
+      taskId:
+        conversationObjectType === "Task" ? conversationObjectId : undefined,
+      workspaceId: config.workspaceId,
+      status: "starting",
+      config,
+      startedAt: new Date(),
+      lastActivityAt: new Date(),
+      // Add conversation details if provided
+      model: conversationData?.model || "sonnet",
+      globalInstructions: conversationData?.globalInstructions || "",
+      workspaceInstructions: conversationData?.workspaceInstructions || "",
+      permissionsMode: conversationData?.permissionsMode || "all",
+    };
+
+    // Store with conversation.id as the key
+    this.runner.activeConversations_.set(conversationId, context);
+    console.log(`[ClaudeManager] Stored conversation context:`, {
+      conversationId,
+      agentSessionId: context.agentSessionId,
+      conversationObjectType: context.conversationObjectType,
+      conversationObjectId: context.conversationObjectId,
+      mapSize: this.runner.activeConversations_.size,
+      allKeys: Array.from(this.runner.activeConversations_.keys()),
+    });
+
+    const workspaceId = config.workspaceId;
+
+    // Checkout repository if specified
+    let workspacePath: string;
+
+    // Check if this is a local workspace by looking for runnerRepoPath in config
+    if (config.runnerRepoPath) {
+      // Local workspace - use the provided path directly
+      workspacePath = config.runnerRepoPath;
+      console.log(`Using local workspace path: ${workspacePath}`);
+
+      // For task conversations in local workspaces, create a local task handle
+      if (conversationObjectType === "Task") {
+        const taskHandle = await this.repositoryManager.createLocalTaskHandle(
+          conversationObjectId,
+          workspacePath
+        );
+        // Store task handle information in context for later use
+        (context as any).taskHandle = taskHandle;
+      }
+    } else if (
+      conversationObjectType === "Task" &&
+      config.repository &&
+      workspaceId
+    ) {
+      // Use task-specific worktree for task conversations
+      console.log(
+        `[ClaudeManager] Creating task worktree with repository config:`,
+        {
+          conversationObjectId,
+          workspaceId,
+          repository: config.repository,
+          hasUrl: !!config.repository.url,
+          url: config.repository.url,
+          branch: config.repository.branch,
+          type: config.repository.type,
+        }
+      );
+
+      // Check if repository.url is missing
+      if (!config.repository.url) {
+        throw new Error(
+          `Repository URL is missing in config for task ${conversationObjectId}. Repository config: ${JSON.stringify(
+            config.repository
+          )}`
+        );
+      }
+
+      const taskHandle = await this.repositoryManager.createTaskWorktree(
+        conversationObjectId,
+        workspaceId,
+        config.repository.url,
+        config.repository.branch,
+        config.githubToken
+      );
+      workspacePath = taskHandle.worktreePath;
+
+      // Store task handle information in context for later use
+      (context as any).taskHandle = taskHandle;
+    } else if (config.repository && workspaceId) {
+      // Check if it's a local repository
+      if (config.repository.type === "local" && config.repository.localPath) {
+        // Use the local path directly
+        workspacePath = config.repository.localPath;
+        console.log(`Using local repository path: ${workspacePath}`);
+      } else {
+        // Fall back to workspace-based checkout for non-task conversations
+        workspacePath = await this.repositoryManager.checkoutRepository(
+          workspaceId,
+          config.repository.url,
+          config.repository.branch,
+          config.githubToken
+        );
+      }
+    } else if (workspaceId) {
+      workspacePath = await this.repositoryManager.getWorkspacePath(
+        workspaceId
+      );
+    } else {
+      // Default workspace path when no workspaceId is provided
+      workspacePath = process.cwd();
+    }
+
+    // Fetch GitHub tokens from orchestrator API if we have a workspaceId
+    const githubToken = workspaceId
+      ? await this.fetchGithubTokens(workspaceId)
+      : undefined;
+
+    // Generate TOOL_TOKEN for MCP tools authentication
+    let toolToken: string | undefined;
+    if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
+      const runnerToken = process.env["NORTHFLARE_RUNNER_TOKEN"];
+      const runnerUid = this.runner.getRunnerUid();
+
+      if (runnerToken && runnerUid && context.conversationId) {
+        // Sign JWT with runner's token
+        toolToken = jwt.sign(
+          {
+            conversationId: context.conversationId,
+            runnerUid: runnerUid,
+          },
+          runnerToken,
+          {
+            expiresIn: "60m", // 60 minutes expiry
+          }
+        );
+        console.log(
+          "[ClaudeManager] Generated TOOL_TOKEN for MCP authentication"
+        );
+      } else {
+        console.warn(
+          "[ClaudeManager] Unable to generate TOOL_TOKEN - missing required data"
+        );
+      }
+    }
+
+    // Simplified SDK configuration - using native query API with streamlined options
+    // const cliPath = require.resolve("@anthropic-ai/claude-code/cli.js");
+
+    // Debug logging for executable paths
+    //console.log("[ClaudeManager] SDK executable paths:", {
+    //  cliPath,
+    //  cwd: workspacePath,
+    //});
+
+    // Simplified environment configuration
+    const envVars: Record<string, string> = {
+      ...(Object.fromEntries(
+        Object.entries(process.env).filter(([_, value]) => value !== undefined)
+      ) as Record<string, string>), // Preserve parent environment, filter out undefined values
+    };
+
+    if (config.anthropicApiKey) {
+      envVars["ANTHROPIC_API_KEY"] = config.anthropicApiKey;
+    }
+
+    if (config.accessToken) {
+      envVars["CLAUDE_CODE_OAUTH_TOKEN"] = config.accessToken;
+    }
+
+    if (githubToken) {
+      envVars["GITHUB_TOKEN"] = githubToken;
+    }
+
+    if (process.env["DEBUG"] === "true") {
+      envVars["DEBUG"] = "1";
+    }
+
+    // Simplified system prompt handling
+    const appendSystemPrompt = [
+      context.globalInstructions,
+      context.workspaceInstructions,
+    ]
+      .filter(Boolean)
+      .join("\n\n");
+
+    // Simplified tool restrictions for read-only mode
+    const disallowedTools: string[] =
+      context.permissionsMode === "read"
+        ? [
+            "Write",
+            "Edit",
+            "MultiEdit",
+            "Bash",
+            "KillBash",
+            "NotebookEdit",
+            "ExitPlanMode",
+          ]
+        : [];
+
+    if (disallowedTools.length) {
+      console.log("[ClaudeManager] Applied read-only mode tool restrictions");
+    }
+
+    // Simplified MCP server configuration
+    let mcpServers: Record<string, any> | undefined;
+    if (config.mcpServers) {
+      console.log(
+        "[ClaudeManager] MCP servers configuration:",
+        JSON.stringify(config.mcpServers, null, 2)
+      );
+      mcpServers = expandEnv(config.mcpServers, { TOOL_TOKEN: toolToken });
+    }
+
+    // Create input stream for user messages (simplified message queueing)
+    const input = createUserMessageStream();
+
+    // Launch SDK with simplified configuration
+    const sdk = sdkQuery({
+      prompt: input.iterable,
+      options: {
+        //pathToClaudeCodeExecutable: cliPath,
+        cwd: workspacePath,
+        env: envVars,
+        model: context.model,
+        permissionMode: "bypassPermissions", // Runner handles permissions
+        resume:
+          config.sessionId || conversationData?.agentSessionId || undefined,
+        ...(appendSystemPrompt ? { appendSystemPrompt } : {}),
+        ...(disallowedTools.length ? { disallowedTools } : {}),
+        ...(mcpServers ? { mcpServers } : {}),
+        ...(process.env["DEBUG"] === "true"
+          ? {
+              stderr: (data: string) => {
+                try {
+                  console.log(`[Claude SDK] ${data}`);
+                } catch {}
+              },
+            }
+          : {}),
+      },
+    });
+
+    // Simplified conversation wrapper - reduced complexity while maintaining interface
+    const conversation = createConversationWrapper(
+      sdk,
+      input,
+      async (hadError: boolean, error?: any) => {
+        await this._finalizeConversation(context, hadError, error);
+      }
+    );
+
+    // Store conversation instance in context for reuse
+    context.conversation = conversation as any;
+
+    // Observe session id from first messages that include it
+    conversation.onSessionId(async (agentSessionId: string) => {
+      if (!agentSessionId) return;
+      const oldSessionId = context.agentSessionId;
+      if (oldSessionId !== agentSessionId) {
+        context.agentSessionId = agentSessionId;
+        context.status = "active";
+        await this.runner.notify("agentSessionId.changed", {
+          conversationId: context.conversationId,
+          conversationObjectType,
+          conversationObjectId,
+          oldAgentSessionId: oldSessionId,
+          newAgentSessionId: agentSessionId,
+        });
+      }
+    });
+
+    // Set up streaming message handler
+    const messageHandler = async (
+      message: SDKMessage,
+      sessionId: string | null
+    ) => {
+      await this.handleStreamedMessage(context, message, sessionId);
+
+      // Heuristic: detect terminal system events and finalize
+      try {
+        if (message?.type === "system") {
+          const m: any = message;
+          const subtype = m.subtype || m?.message?.subtype || m?.event;
+          const exitSignals = [
+            "exit",
+            "exiting",
+            "session_end",
+            "conversation_end",
+            "process_exit",
+            "done",
+            "completed",
+          ];
+          if (subtype && exitSignals.includes(String(subtype))) {
+            await this._finalizeConversation(context, false);
+          }
+        } else if (message?.type === "result") {
+          // Treat 'result' as an end-of-conversation signal for the SDK
+          try {
+            await this._finalizeConversation(context, false);
+            console.log(
+              "[ClaudeManager] Finalized conversation due to SDK 'result' message",
+              {
+                conversationId: context.conversationId,
+                agentSessionId: context.agentSessionId,
+              }
+            );
+          } catch (e) {
+            console.warn(
+              "[ClaudeManager] Error finalizing on 'result' message:",
+              e
+            );
+          }
+        }
+      } catch (e) {
+        console.warn("[ClaudeManager] finalize-on-system heuristic error:", e);
+      }
+    };
+
+    conversation.stream(messageHandler);
+
+    // Note: Error handling is done via process completion handler
+    // The Claude SDK doesn't have an onError method on conversations
+
+    // Send initial messages
+    try {
+      for (const message of initialMessages) {
+        const initialText = this.normalizeToText(message.content);
+        conversation.send({
+          type: "text",
+          text: initialText,
+        });
+      }
+
+      console.log(
+        `Started conversation for ${conversationObjectType} ${conversationObjectId} in workspace ${workspacePath}`
+      );
+
+      // Return the conversation context directly
+      return context;
+    } catch (error) {
+      // Handle startup errors
+      await this._handleConversationError(context, error as Error);
+      throw error;
+    }
+  }
+
+  async stopConversation(
+    agentSessionId: string,
+    context: ConversationContext,
+    isRunnerShutdown: boolean = false,
+    reason?: string
+  ): Promise<void> {
+    if (context && context.conversation) {
+      context.status = "stopping";
+
+      try {
+        // Proactively send end notification to avoid missing it on abnormal exits
+        // Use provided reason, or fall back to 'runner_shutdown' if isRunnerShutdown is true
+        const finalReason =
+          reason || (isRunnerShutdown ? "runner_shutdown" : undefined);
+        await this._finalizeConversation(
+          context,
+          false,
+          undefined,
+          finalReason
+        ).catch(() => {});
+        // Mark conversation as stopped BEFORE ending to prevent race conditions
+        context.status = "stopped";
+
+        // Properly end the conversation using the SDK
+        await context.conversation.end();
+      } catch (error) {
+        console.error(`Error ending conversation ${agentSessionId}:`, error);
+      }
+
+      // Clean up conversation reference
+      delete context.conversation;
+    }
+
+    console.log(
+      `Stopped conversation ${agentSessionId} for ${context.conversationObjectType} ${context.conversationObjectId}`
+    );
+  }
+
+  async resumeConversation(
+    conversationObjectType: "Task" | "TaskPlan",
+    conversationObjectId: string,
+    agentSessionId: string,
+    config: ConversationConfig,
+    conversationData?: any,
+    resumeMessage?: string
+  ): Promise<string> {
+    console.log(`[ClaudeManager] Resuming conversation ${agentSessionId}`);
+
+    // Resume is handled by starting a new conversation with the existing session ID
+    const context = await this.startConversation(
+      conversationObjectType,
+      conversationObjectId,
+      { ...config, sessionId: agentSessionId },
+      [], // Don't send initial messages
+      conversationData
+    );
+
+    // After starting the conversation with the sessionId, we need to send a message
+    // to actually trigger the Claude process to continue
+    if (context.conversation) {
+      try {
+        // Use the provided resume message or default to system instruction
+        const messageToSend =
+          resumeMessage ||
+          "<system-instructions>Please continue</system-instructions>";
+        console.log(
+          `[ClaudeManager] Sending resume message to conversation ${agentSessionId}`
+        );
+        context.conversation.send({
+          type: "text",
+          text: messageToSend,
+        });
+      } catch (error) {
+        console.error(`[ClaudeManager] Error sending resume message:`, error);
+      }
+    }
+
+    return context.agentSessionId;
+  }
+
+  private async _finalizeConversation(
+    context: ConversationContext,
+    hadError: boolean,
+    error?: any,
+    reason?: string
+  ): Promise<void> {
+    // Ensure idempotency
+    if ((context as any)._finalized) return;
+    (context as any)._finalized = true;
+
+    try {
+      await this.runner.notify("conversation.end", {
+        conversationId: context.conversationId,
+        conversationObjectType: context.conversationObjectType,
+        conversationObjectId: context.conversationObjectId,
+        agentSessionId: context.agentSessionId,
+        isError: hadError,
+        errorMessage: error?.message,
+        reason: reason,
+      });
+    } catch (e) {
+      console.error("[ClaudeManager] Failed to notify conversation.end:", e);
+    }
+
+    // Clean up conversation from active conversations
+    try {
+      console.log(`[ClaudeManager] Removing conversation from active map:`, {
+        conversationId: context.conversationId,
+        agentSessionId: context.agentSessionId,
+        mapSizeBefore: this.runner.activeConversations_.size,
+      });
+      this.runner.activeConversations_.delete(context.conversationId);
+      statusLineManager.updateActiveCount(
+        this.runner.activeConversations_.size
+      );
+    } catch {}
+  }
+
+  async sendUserMessage(
+    conversationId: string,
+    content: any,
+    config?: ConversationConfig,
+    conversationObjectType?: "Task" | "TaskPlan",
+    conversationObjectId?: string,
+    conversation?: any
+  ): Promise<void> {
+    console.log(`[ClaudeManager] sendUserMessage called with:`, {
+      conversationId,
+      conversationObjectType,
+      conversationObjectId,
+      hasConfig: !!config,
+      hasConversation: !!conversation,
+      activeConversations: this.runner.activeConversations_.size,
+    });
+
+    // Find by conversationId only
+    let context = this.runner.getConversationContext(conversationId);
+    console.log(`[ClaudeManager] Lookup by conversationId result:`, {
+      found: !!context,
+      conversationId: context?.conversationId,
+      agentSessionId: context?.agentSessionId,
+    });
+
+    if (!context && conversation) {
+      // Use provided conversation details
+      try {
+        const conversationDetails = conversation;
+        console.log(
+          `[ClaudeManager] Using provided config from RunnerMessage:`,
+          {
+            hasConfig: !!config,
+            hasRepository: !!config?.repository,
+            repositoryType: config?.repository?.type,
+            repositoryPath: config?.repository?.localPath,
+            hasTokens: !!(config?.accessToken || config?.githubToken),
+            hasMcpServers: !!config?.mcpServers,
+          }
+        );
+
+        // Use the config that was already prepared by TaskOrchestrator and sent in the RunnerMessage
+        const startConfig: ConversationConfig = {
+          anthropicApiKey:
+            config?.anthropicApiKey || process.env["ANTHROPIC_API_KEY"] || "",
+          systemPrompt: config?.systemPrompt,
+          workspaceId: conversationDetails.workspaceId,
+          ...config, // Use the full config provided in the RunnerMessage
+          ...(conversationDetails.agentSessionId
+            ? { sessionId: conversationDetails.agentSessionId }
+            : {}),
+        };
+
+        // Start the SDK conversation (no initial messages); this attaches to existing session when provided
+        await this.startConversation(
+          conversationDetails.objectType,
+          conversationDetails.objectId,
+          startConfig,
+          [],
+          conversationDetails
+        );
+
+        // Refresh context after start/resume
+        context = this.runner.getConversationContext(conversationId);
+      } catch (error) {
+        console.error(`Failed to fetch conversation ${conversationId}:`, error);
+      }
+    }
+
+    if (!context) {
+      throw new Error(
+        `No active or fetchable conversation found for ${conversationId}`
+      );
+    }
+
+    try {
+      // Send immediately when a conversation instance exists; no need to wait for "active"
+      if (!context.conversation) {
+        throw new Error(
+          `No conversation instance found for conversation ${context.conversationId}`
+        );
+      }
+
+      // Guard: Don't send messages if conversation is stopped or stopping
+      const conversationStatus = context.status as string;
+      if (
+        conversationStatus === "stopped" ||
+        conversationStatus === "stopping"
+      ) {
+        console.warn(
+          `Attempted to send message to stopped/stopping conversation ${context.conversationId}`,
+          {
+            status: context.status,
+            conversationObjectType: context.conversationObjectType,
+            conversationObjectId: context.conversationObjectId,
+          }
+        );
+        return;
+      }
+
+      // Native message injection - SDK handles queueing and delivery
+      const normalizedText = this.normalizeToText(content);
+
+      if (process.env["DEBUG"] === "true") {
+        console.log("[ClaudeManager] Normalized follow-up content", {
+          originalType: typeof content,
+          isArray: Array.isArray(content) || undefined,
+          normalizedPreview:
+            typeof normalizedText === "string"
+              ? normalizedText.slice(0, 160)
+              : String(normalizedText).slice(0, 160),
+        });
+      }
+
+      context.conversation.send({
+        type: "text",
+        text: normalizedText,
+      });
+
+      // Update last activity timestamp
+      context.lastActivityAt = new Date();
+
+      console.log(
+        `Sent user message to conversation ${context.conversationId} (agentSessionId: ${context.agentSessionId}, status: ${context.status})`
+      );
+    } catch (error) {
+      // Handle errors properly
+      await this._handleConversationError(context, error as Error);
+      throw error; // Re-throw to maintain the same behavior
+    }
+  }
+
+  private async fetchGithubTokens(
+    workspaceId: string
+  ): Promise<string | undefined> {
+    try {
+      const response = await fetch(
+        `${this.runner.config_.orchestratorUrl}/api/runner/tokens?workspaceId=${workspaceId}`,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${process.env["NORTHFLARE_RUNNER_TOKEN"]}`,
+          },
+        }
+      );
+
+      if (!response.ok) {
+        console.error(`Failed to fetch GitHub tokens: ${response.status}`);
+        return undefined;
+      }
+
+      const data = (await response.json()) as { githubToken?: string };
+      return data.githubToken;
+    } catch (error) {
+      console.error("Error fetching GitHub tokens:", error);
+      return undefined;
+    }
+  }
+
+  private async _handleConversationError(
+    context: ConversationContext,
+    error: Error
+  ): Promise<void> {
+    const errorType = this.classifyError(error);
+
+    // Notify orchestrator
+    await this.runner.notify("error.report", {
+      conversationId: context.conversationId,
+      conversationObjectType: context.conversationObjectType,
+      conversationObjectId: context.conversationObjectId,
+      agentSessionId: context.agentSessionId,
+      errorType,
+      message: error.message,
+      details: {
+        stack: error.stack,
+        timestamp: new Date(),
+      },
+    });
+
+    // Conversation continues on error - no automatic cleanup
+    console.error(
+      `Conversation error for ${context.conversationObjectType} ${context.conversationObjectId}:`,
+      error
+    );
+  }
+
+  private classifyError(error: Error): string {
+    if (error.message.includes("process exited")) {
+      return "process_exit";
+    } else if (error.message.includes("model")) {
+      return "model_error";
+    } else if (error.message.includes("tool")) {
+      return "tool_error";
+    } else if (error.message.includes("permission")) {
+      return "permission_error";
+    } else if (error.message.includes("timeout")) {
+      return "timeout_error";
+    }
+    return "unknown_error";
+  }
+
+  /**
+   * Normalize arbitrary content shapes into a plain string for the CLI
+   */
+  private normalizeToText(value: any): string {
+    if (typeof value === "string") return value;
+    if (value == null) return "";
+
+    if (typeof value === "object") {
+      // Common simple shapes
+      if (typeof (value as any).text === "string") return (value as any).text;
+      if (
+        typeof (value as any).text === "object" &&
+        (value as any).text &&
+        typeof (value as any).text.text === "string"
+      )
+        return (value as any).text.text;
+      if (typeof (value as any).content === "string")
+        return (value as any).content;
+
+      // Array of blocks: [{ type: 'text', text: '...' }, ...]
+      if (Array.isArray(value)) {
+        const texts = value
+          .map((b) =>
+            b && b.type === "text" && typeof b.text === "string" ? b.text : null
+          )
+          .filter((t): t is string => !!t);
+        if (texts.length) return texts.join(" ");
+      }
+
+      // Nested message shapes
+      if (
+        typeof (value as any).message === "object" &&
+        (value as any).message &&
+        typeof (value as any).message.text === "string"
+      ) {
+        return (value as any).message.text;
+      }
+    }
+
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  private async handleStreamedMessage(
+    context: ConversationContext,
+    message: SDKMessage,
+    sessionId: string | null
+  ): Promise<void> {
+    /*
+     * SDK tool call payload reference (observed shapes)
+     *
+     * 1) Assistant tool call (tool_use)
+     * {
+     *   "type": "assistant",
+     *   "message": {
+     *     "role": "assistant",
+     *     "content": [
+     *       { "type": "text", "text": "…optional text…" },
+     *       { "type": "tool_use", "id": "toolu_01Nbv…", "name": "TodoWrite", "input": { ... } }
+     *     ]
+     *   },
+     *   "session_id": "…"
+     * }
+     *
+     * 2) Tool result (often emitted as type 'user')
+     * {
+     *   "type": "user",
+     *   "message": {
+     *     "role": "user",
+     *     "content": [
+     *       {
+     *         "tool_use_id": "toolu_01E9R475…",
+     *         "type": "tool_result",
+     *         "content": "Todos have been modified successfully. …"
+     *       }
+     *     ]
+     *   },
+     *   "parent_tool_use_id": null,
+     *   "session_id": "…",
+     *   "uuid": "…"
+     * }
+     *
+     * Normalization (runner → server message.agent):
+     * - assistant tool_use → type: 'assistant', content: [{ toolCalls: [{ id, name, arguments }] }, …]
+     * - tool_result (any shape) → type: 'tool_result', subtype: 'tool_result', content:
+     *   [ { type: 'tool_result', subtype: 'tool_result', tool_use_id, content } ]
+     */
+    // Guard: Don't process messages if conversation is stopped or stopping
+    const status = context.status as string;
+    if (status === "stopped" || status === "stopping") {
+      console.log(
+        `Ignoring message for stopped/stopping conversation ${context.conversationId}`,
+        {
+          status: context.status,
+          messageType: message.type,
+        }
+      );
+      return;
+    }
+
+    try {
+      // High-level receipt log
+      console.log(
+        `Received streamed message for ${context.conversationObjectType} ${context.conversationObjectId}`,
+        {
+          type: message?.type,
+        }
+      );
+
+      // Raw SDK message diagnostics
+      try {
+        // Log the full raw SDK message safely (handles circular refs)
+        const safeStringify = (obj: any) => {
+          const seen = new WeakSet();
+          return JSON.stringify(
+            obj,
+            (key, value) => {
+              if (typeof value === "function") return undefined;
+              if (typeof value === "bigint") return String(value);
+              if (typeof value === "object" && value !== null) {
+                if (seen.has(value)) return "[Circular]";
+                seen.add(value);
+              }
+              return value;
+            },
+            2
+          );
+        };
+
+        console.log(
+          "[ClaudeManager] RAW SDK message FULL:",
+          safeStringify(message)
+        );
+
+        const summary = {
+          keys: Object.keys(message || {}),
+          hasMessage: !!(message as any)?.message,
+          contentType: typeof (message as any)?.content,
+          messageContentType: typeof (message as any)?.message?.content,
+          sessionId:
+            (message as any)?.session_id || (message as any)?.sessionId || null,
+        };
+        console.log("[ClaudeManager] RAW SDK message summary:", summary);
+        if ((message as any)?.content !== undefined) {
+          console.log(
+            "[ClaudeManager] RAW SDK content:",
+            (message as any).content
+          );
+        }
+        if ((message as any)?.message?.content !== undefined) {
+          console.log(
+            "[ClaudeManager] RAW SDK nested content:",
+            (message as any).message.content
+          );
+        }
+      } catch (e) {
+        console.warn("[ClaudeManager] Failed to log raw SDK message:", e);
+      }
+
+      // Build structured content based on message type
+      let messageType: string = message.type;
+      let subtype: string | undefined;
+      let structuredContent: any = {};
+      let isError = false;
+      let skipSend = false;
+
+      // Extract content based on message type
+      switch (message.type) {
+        case "assistant": {
+          const assistantMsg = message as any;
+          const blocks =
+            assistantMsg?.message?.content || assistantMsg?.content || [];
+          const textContent = Array.isArray(blocks)
+            ? blocks
+                .filter(
+                  (b: any) =>
+                    b && b.type === "text" && typeof b.text === "string"
+                )
+                .map((b: any) => b.text)
+                .join("")
+            : "";
+          const toolCalls = Array.isArray(blocks)
+            ? blocks
+                .filter((b: any) => b && b.type === "tool_use")
+                .map((b: any) => ({
+                  id: b.id,
+                  name: b.name,
+                  arguments: b.input,
+                }))
+            : undefined;
+
+          structuredContent = {
+            ...(textContent ? { text: textContent } : {}),
+            ...(toolCalls && toolCalls.length ? { toolCalls } : {}),
+            timestamp: new Date().toISOString(),
+          };
+          break;
+        }
+
+        case "thinking" as any: {
+          // Map thinking to assistant with subtype
+          messageType = "assistant";
+          subtype = "thinking";
+          const thinkingMsg = message as any;
+          structuredContent = {
+            text: thinkingMsg.content || "",
+            timestamp: new Date().toISOString(),
+          };
+          break;
+        }
+
+        case "tool_use" as any: {
+          // Tool call request - map to assistant
+          messageType = "assistant";
+          subtype = "tool_use";
+          const toolUseMsg = message as any;
+          structuredContent = {
+            toolCalls: [
+              {
+                id: toolUseMsg.id,
+                name: toolUseMsg.name,
+                arguments: toolUseMsg.input,
+              },
+            ],
+            timestamp: new Date().toISOString(),
+          };
+          break;
+        }
+
+        case "tool_result" as any: {
+          // Tool execution result - normalize to v1-style tool_result blocks
+          // so the server persists as messageType: tool_call_result with correct content
+          messageType = "tool_result";
+          subtype = "tool_result";
+          const toolResultMsg = message as any;
+          structuredContent = [
+            {
+              type: "tool_result",
+              subtype: "tool_result",
+              tool_use_id: toolResultMsg.tool_use_id,
+              content: toolResultMsg.content, // Keep content as native (array or string)
+              timestamp: new Date().toISOString(),
+            },
+          ];
+          break;
+        }
+
+        case "result": {
+          const resultMsg = message as any;
+          structuredContent = {
+            text: resultMsg.content || resultMsg.result || "",
+            timestamp: new Date().toISOString(),
+          };
+          break;
+        }
+
+        case "user": {
+          const userMsg = message as any;
+          // Prefer nested message.content if present (SDK shape), fallback to top-level content
+          const blocks =
+            (userMsg && userMsg.message && userMsg.message.content) ||
+            userMsg?.content ||
+            [];
+
+          if (Array.isArray(blocks)) {
+            const hasToolResult = blocks.some(
+              (b: any) => b && typeof b === "object" && b.type === "tool_result"
+            );
+
+            if (hasToolResult) {
+              // Normalize tool_result blocks to v1-style
+              messageType = "tool_result";
+              subtype = "tool_result";
+              structuredContent = blocks
+                .filter((b: any) => b && b.type === "tool_result")
+                .map((b: any) => ({
+                  type: "tool_result",
+                  subtype: "tool_result",
+                  tool_use_id: b.tool_use_id || b.toolUseId || b.id,
+                  content: b.content, // Keep content as native (array or string)
+                }));
+            } else {
+              // Treat as plain text content by joining text blocks
+              const textContent = blocks
+                .filter(
+                  (b: any) =>
+                    b && b.type === "text" && typeof b.text === "string"
+                )
+                .map((b: any) => b.text)
+                .join("");
+              structuredContent = {
+                text: textContent,
+                timestamp: new Date().toISOString(),
+              };
+            }
+
+            // If content array only contains empty objects, skip sending
+            if (
+              Array.isArray(structuredContent) &&
+              structuredContent.length > 0 &&
+              structuredContent.every(
+                (it: any) =>
+                  !it || typeof it !== "object" || Object.keys(it).length === 0
+              )
+            ) {
+              console.log(
+                "[ClaudeManager] Skipping empty 'user' message with only empty objects from SDK"
+              );
+              skipSend = true;
+            }
+          } else if (typeof userMsg?.content === "string") {
+            // Attempt to parse JSON arrays (common for tool_result payloads)
+            const text = userMsg.content;
+            try {
+              const parsed = JSON.parse(text);
+              if (Array.isArray(parsed)) {
+                const hasToolResult = parsed.some(
+                  (item: any) =>
+                    item &&
+                    typeof item === "object" &&
+                    item.type === "tool_result"
+                );
+                if (hasToolResult) {
+                  messageType = "tool_result";
+                  subtype = "tool_result";
+                  structuredContent = parsed;
+                } else {
+                  structuredContent = {
+                    text,
+                    timestamp: new Date().toISOString(),
+                  };
+                }
+              } else {
+                structuredContent = {
+                  text,
+                  timestamp: new Date().toISOString(),
+                };
+              }
+            } catch {
+              // Not JSON - treat as plain text
+              structuredContent = { text, timestamp: new Date().toISOString() };
+            }
+          } else {
+            // Other object content - preserve as is
+            structuredContent = userMsg?.content || {};
+          }
+          break;
+        }
+
+        case "system": {
+          const systemMsg = message as any;
+          const subtype = systemMsg.subtype || "system";
+          const model = systemMsg.model || systemMsg?.message?.model;
+          const permissionMode =
+            systemMsg.permissionMode || systemMsg?.message?.permissionMode;
+          const summary = [
+            subtype && `[${subtype}]`,
+            model && `model=${model}`,
+            permissionMode && `perm=${permissionMode}`,
+          ]
+            .filter(Boolean)
+            .join(" ");
+          structuredContent = {
+            text: summary || "",
+            timestamp: new Date().toISOString(),
+          };
+          break;
+        }
+
+        case "error" as any: {
+          const errorMsg = message as any;
+          messageType = "system";
+          subtype = "error";
+          isError = true;
+          structuredContent = {
+            text: errorMsg.message || errorMsg.error || "Unknown error",
+            errorType: errorMsg.error_type || "unknown",
+            errorDetails: {
+              stack: errorMsg.stack,
+              code: errorMsg.code,
+              context: errorMsg,
+            },
+            timestamp: new Date().toISOString(),
+          };
+          break;
+        }
+
+        default: {
+          // Unknown message type - log and send as assistant
+          const unknownMsg = message as any;
+          console.warn(`Unknown message type: ${unknownMsg.type}`, message);
+          messageType = "assistant";
+          structuredContent = {
+            text: JSON.stringify(message),
+            timestamp: new Date().toISOString(),
+          };
+        }
+      }
+
+      // Generate a unique message ID
+      const messageId = `${context.agentSessionId}-${Date.now()}-${Math.random()
+        .toString(36)
+        .substr(2, 9)}`;
+
+      // Send agent message to orchestrator with structured content
+      // Skip if conversation is stopping/stopped to avoid race conditions
+      const currentStatus = context.status as string;
+      if (currentStatus !== "stopped" && currentStatus !== "stopping") {
+        if (skipSend) {
+          console.log(
+            "[ClaudeManager] Not sending message.agent due to skipSend=true"
+          );
+          return;
+        }
+
+        const payload = {
+          conversationId: context.conversationId,
+          conversationObjectType: context.conversationObjectType,
+          conversationObjectId: context.conversationObjectId,
+          agentSessionId: context.agentSessionId,
+          type: messageType,
+          subtype,
+          content: Array.isArray(structuredContent)
+            ? structuredContent
+            : [structuredContent],
+          messageId,
+          isError,
+        };
+
+        try {
+          console.log("[ClaudeManager] Sending message.agent payload:", {
+            type: payload.type,
+            subtype: payload.subtype,
+            contentPreview: Array.isArray(payload.content)
+              ? payload.content.slice(0, 1)
+              : payload.content,
+          });
+        } catch {}
+
+        await this.runner.notify("message.agent", payload as any);
+      }
+
+      // Tool calls are now handled directly by Claude through the MCP server
+      // We just log that we saw them but don't intercept or process them
+      if (
+        structuredContent.toolCalls &&
+        structuredContent.toolCalls.length > 0
+      ) {
+        console.log(
+          `Claude is making ${structuredContent.toolCalls.length} tool call(s) via MCP`,
+          {
+            conversationObjectId: context.conversationObjectId,
+            toolNames: structuredContent.toolCalls.map((tc: any) => tc.name),
+          }
+        );
+      }
+    } catch (error) {
+      // Check if this is a transport error due to stopped conversation
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      const isTransportError =
+        errorMessage.includes("Cannot read properties of undefined") ||
+        errorMessage.includes("stdout") ||
+        errorMessage.includes("transport");
+
+      const statusCheck = context.status as string;
+      if (
+        isTransportError &&
+        (statusCheck === "stopped" || statusCheck === "stopping")
+      ) {
+        // This is expected when conversation is stopped - just log it
+        console.log(
+          `Transport error for stopped/stopping conversation ${context.conversationId} (expected):`,
+          errorMessage
+        );
+        return;
+      }
+
+      console.error(
+        `Error handling streamed message for ${context.conversationObjectType} ${context.conversationObjectId}:`,
+        error
+      );
+      await this._handleConversationError(context, error as Error);
+    }
+  }
+}
+
+// Simplified helper functions for SDK integration
+
+type UserMessageStream = {
+  iterable: AsyncIterable<any>;
+  enqueue: (msg: any) => void;
+  close: () => void;
+};
+
+function createUserMessageStream(): UserMessageStream {
+  const queue: any[] = [];
+  let resolver: (() => void) | null = null;
+  let done = false;
+
+  async function* iterator() {
+    while (true) {
+      if (queue.length > 0) {
+        const value = queue.shift();
+        yield value;
+        continue;
+      }
+      if (done) return;
+      await new Promise<void>((resolve) => (resolver = resolve));
+      resolver = null;
+    }
+  }
+
+  return {
+    iterable: iterator(),
+    enqueue: (msg: any) => {
+      if (done) return;
+      queue.push(msg);
+      if (resolver) {
+        const r = resolver;
+        resolver = null;
+        r();
+      }
+    },
+    close: () => {
+      done = true;
+      if (resolver) {
+        const r = resolver;
+        resolver = null;
+        r();
+      }
+    },
+  };
+}
+
+function createConversationWrapper(
+  sdk: any,
+  input: UserMessageStream,
+  onComplete?: (hadError: boolean, error?: any) => Promise<void> | void
+) {
+  let onSessionIdCb: ((id: string) => void) | null = null;
+  let observedSessionId: string | null = null;
+  let startedReader = false;
+
+  function toSdkUserMessage(text: string) {
+    return {
+      type: "user",
+      session_id: observedSessionId || "",
+      parent_tool_use_id: null,
+      message: {
+        role: "user",
+        content: text,
+      },
+    };
+  }
+
+  return {
+    send(payload: { type: string; text: string }) {
+      const text = payload?.text ?? "";
+      input.enqueue(toSdkUserMessage(text));
+    },
+    async end() {
+      try {
+        input.close();
+      } finally {
+        // Simplified process cleanup
+        try {
+          if (sdk?.abortController) {
+            sdk.abortController.abort();
+          }
+        } catch {}
+      }
+    },
+    onSessionId(cb: (id: string) => void) {
+      onSessionIdCb = cb;
+    },
+    stream(
+      handler: (message: SDKMessage, sessionId: string | null) => Promise<void>
+    ) {
+      if (startedReader) return;
+      startedReader = true;
+      (async () => {
+        try {
+          for await (const msg of sdk) {
+            // Simplified session ID extraction
+            const sid = (msg && (msg.session_id || msg.sessionId)) || null;
+            if (sid && sid !== observedSessionId) {
+              observedSessionId = sid;
+              if (onSessionIdCb) onSessionIdCb(sid);
+            }
+            await handler(msg, sid);
+          }
+          // Normal completion
+          if (onComplete) await onComplete(false);
+        } catch (e) {
+          // Error completion
+          if (onComplete) await onComplete(true, e);
+        }
+      })();
+    },
+  };
+}