@northflare/runner 0.0.12 → 0.0.13

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

@@ -1,1425 +0,0 @@
-/**
- * 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";
-import type { Conversation as ClaudeConversation } from "@botanicastudios/claude-code-sdk-ts";
-// 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 { isRunnerDebugEnabled } from "../utils/debug";
-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 (isRunnerDebugEnabled()) {
-      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 (isRunnerDebugEnabled()) {
-      envVars["DEBUG"] = "1";
-    }
-
-    // Simplified system prompt handling
-    const appendSystemPrompt = [
-      context.globalInstructions,
-      context.workspaceInstructions,
-    ]
-      .filter(Boolean)
-      .join("\n\n");
-
-    // Debug log the appendSystemPrompt being sent to Claude SDK
-    console.log(
-      `[ClaudeManager] Building appendSystemPrompt for conversation ${context.conversationId}:`,
-      {
-        hasGlobalInstructions: !!context.globalInstructions,
-        globalInstructionsLength: context.globalInstructions?.length ?? 0,
-        hasWorkspaceInstructions: !!context.workspaceInstructions,
-        workspaceInstructionsLength: context.workspaceInstructions?.length ?? 0,
-        appendSystemPromptLength: appendSystemPrompt.length,
-        appendSystemPromptPreview: appendSystemPrompt.slice(0, 150),
-      }
-    );
-
-    // 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) {
-      mcpServers = expandEnv(config.mcpServers, { TOOL_TOKEN: toolToken });
-      console.log(
-        "[ClaudeManager] MCP servers configuration:",
-        JSON.stringify(mcpServers, null, 2)
-      );
-    }
-
-    // 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
-          ? {
-              systemPrompt: {
-                type: "preset" as const,
-                preset: "claude_code" as const,
-                append: appendSystemPrompt,
-              },
-            }
-          : {}),
-        ...(disallowedTools.length ? { disallowedTools } : {}),
-        ...(mcpServers ? { mcpServers } : {}),
-        ...(isRunnerDebugEnabled()
-          ? {
-              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
-        if (isClaudeConversation(context.conversation)) {
-          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 && isClaudeConversation(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);
-      }
-    } else {
-      console.warn(
-        "[ClaudeManager] Resume requested but conversation instance missing or incompatible"
-      );
-    }
-
-    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,
-    _agentSessionIdOverride?: string
-  ): 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 || !isClaudeConversation(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 (isRunnerDebugEnabled()) {
-        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;
-      let metadata: any = null;
-
-      // Extract parent_tool_use_id if present (for all message types)
-      const msgAsAny = message as any;
-      if (msgAsAny.parent_tool_use_id) {
-        metadata = {
-          parent_tool_use_id: msgAsAny.parent_tool_use_id,
-        };
-      }
-
-      // 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: {
-          messageType = "thinking";
-          subtype = undefined;
-          const thinkingMsg = message as any;
-          structuredContent = [
-            {
-              type: "thinking",
-              thinking: thinkingMsg.content || "",
-              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(),
-              };
-
-              // Check if this is a subagent prompt (Task tool input being sent to subagent)
-              // These have parent_tool_use_id but are NOT tool_result messages
-              if (userMsg.parent_tool_use_id) {
-                console.log(
-                  "[ClaudeManager] Detected subagent prompt message (parent_tool_use_id present, no tool_result)",
-                  {
-                    parent_tool_use_id: userMsg.parent_tool_use_id,
-                  }
-                );
-                messageType = "assistant"; // Change from "user" to "assistant"
-                subtype = "subagent_prompt";
-                // metadata already set above with parent_tool_use_id
-              }
-            }
-
-            // 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: any = {
-          conversationId: context.conversationId,
-          conversationObjectType: context.conversationObjectType,
-          conversationObjectId: context.conversationObjectId,
-          agentSessionId: context.agentSessionId,
-          type: messageType,
-          subtype,
-          content: Array.isArray(structuredContent)
-            ? structuredContent
-            : [structuredContent],
-          messageId,
-          isError,
-        };
-
-        // Add metadata if present
-        if (metadata) {
-          payload.metadata = metadata;
-        }
-
-        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);
-        }
-      })();
-    },
-  };
-}
-function isClaudeConversation(
-  conversation: ConversationContext["conversation"]
-): conversation is ClaudeConversation {
-  return (
-    !!conversation &&
-    typeof (conversation as ClaudeConversation).send === "function" &&
-    typeof (conversation as ClaudeConversation).end === "function"
-  );
-}