package lifecycle import ( "context" "errors" "fmt" "strings" "time" "github.com/coder/acp-go-sdk" "go.uber.org/zap" "github.com/kandev/kandev/internal/agent/agents" agentctl "github.com/kandev/kandev/internal/agent/runtime/agentctl" "github.com/kandev/kandev/internal/agentctl/tracing" agentctltypes "github.com/kandev/kandev/internal/agentctl/types" "github.com/kandev/kandev/internal/common/appctx" "github.com/kandev/kandev/internal/common/logger" v1 "github.com/kandev/kandev/pkg/api/v1" "go.opentelemetry.io/otel/trace" ) // SessionManager handles ACP session initialization and management type SessionManager struct { logger *logger.Logger eventPublisher *EventPublisher streamManager *StreamManager executionStore *ExecutionStore historyManager *SessionHistoryManager stopCh <-chan struct{} // For graceful shutdown coordination } // NewSessionManager creates a new SessionManager func NewSessionManager(log *logger.Logger, stopCh <-chan struct{}) *SessionManager { return &SessionManager{ logger: log, stopCh: stopCh, } } // SetDependencies sets the optional dependencies for full session orchestration. // These are set after construction to avoid circular dependencies. func (sm *SessionManager) SetDependencies(ep *EventPublisher, strm *StreamManager, store *ExecutionStore, history *SessionHistoryManager) { sm.eventPublisher = ep sm.streamManager = strm sm.executionStore = store sm.historyManager = history } // InitializeResult contains the result of session initialization type InitializeResult struct { AgentName string AgentVersion string SessionID string } // InitializeSession initializes an ACP session with the agent. // It handles the initialize handshake and session creation/loading based on config. // // Session behavior: // - If agentConfig.Runtime().SessionConfig.NativeSessionResume is true AND existingSessionID is provided: use session/load // - If NativeSessionResume is false (CLI handles resume): always use session/new // - Otherwise: use session/new func (sm *SessionManager) InitializeSession( ctx context.Context, client *agentctl.Client, agentConfig agents.Agent, existingSessionID string, workspacePath string, mcpServers []agentctltypes.McpServer, ) (*InitializeResult, error) { rt := agentConfig.Runtime() sm.logger.Info("initializing ACP session", zap.String("agent_type", agentConfig.ID()), zap.String("workspace_path", workspacePath), zap.Bool("native_session_resume", rt.SessionConfig.NativeSessionResume), zap.String("existing_session_id", existingSessionID)) // Step 1: Send initialize request sm.logger.Info("sending ACP initialize request", zap.String("agent_type", agentConfig.ID())) agentInfo, err := client.Initialize(ctx, "kandev", "1.0.0") if err != nil { sm.logger.Error("ACP initialize failed", zap.String("agent_type", agentConfig.ID()), zap.Error(err)) return nil, fmt.Errorf("initialize failed: %w", err) } result := &InitializeResult{ AgentName: "unknown", AgentVersion: "unknown", } if agentInfo != nil { result.AgentName = agentInfo.Name result.AgentVersion = agentInfo.Version } sm.logger.Info("ACP initialize response received", zap.String("agent_type", agentConfig.ID()), zap.String("agent_name", result.AgentName), zap.String("agent_version", result.AgentVersion)) // Step 2: Create or resume ACP session based on configuration sessionID, err := sm.createOrLoadSession(ctx, client, agentConfig, existingSessionID, workspacePath, mcpServers) if err != nil { return nil, err } result.SessionID = sessionID return result, nil } // createOrLoadSession creates a new session or loads an existing one based on agent config. func (sm *SessionManager) createOrLoadSession( ctx context.Context, client *agentctl.Client, agentConfig agents.Agent, existingSessionID string, workspacePath string, mcpServers []agentctltypes.McpServer, ) (string, error) { rt := agentConfig.Runtime() sm.logger.Debug("createOrLoadSession decision", zap.String("agent_type", agentConfig.ID()), zap.Bool("native_session_resume", rt.SessionConfig.NativeSessionResume), zap.String("existing_session_id", existingSessionID), zap.Bool("will_attempt_load", rt.SessionConfig.NativeSessionResume && existingSessionID != "")) if rt.SessionConfig.NativeSessionResume && existingSessionID != "" { sessionID, err := sm.loadSession(ctx, client, agentConfig, existingSessionID, mcpServers) if err == nil { return sessionID, nil } // session/load can fail for reasons that don't justify aborting the // session: agent doesn't support the method (capability mismatch / // method not found), the upstream agent CLI no longer recognises the // stored token (expired / version drift / agent-side GC), etc. In all // those cases we want to start a fresh ACP session — the kandev-side // row identity is still preserved, only the agent CLI's conversation // memory is reset. The caller (executor) overwrites the stored token // when the new session ID flows back through the events pipeline. sm.logger.Warn("session/load failed, falling back to session/new", zap.String("agent_type", agentConfig.ID()), zap.String("existing_session_id", existingSessionID), zap.String("reason", err.Error()), zap.Bool("method_not_found", isMethodNotFoundErr(err)), zap.Bool("capability_mismatch", strings.Contains(err.Error(), "LoadSession capability is false")), zap.Bool("session_unknown", isSessionUnknownErr(err))) return sm.createNewSession(ctx, client, agentConfig, workspacePath, mcpServers) } return sm.createNewSession(ctx, client, agentConfig, workspacePath, mcpServers) } // shouldInjectResumeContext determines if we should inject resume context for this session. // Returns true if: // 1. The agent explicitly opts in via SessionConfig.HistoryContextInjection // 2. There's existing history for this session func (sm *SessionManager) shouldInjectResumeContext(agentConfig agents.Agent, taskSessionID string) bool { if sm.historyManager == nil { return false } rt := agentConfig.Runtime() // Only inject if the agent explicitly opts in to history-based context injection if !rt.SessionConfig.HistoryContextInjection { return false } // Check if we have history for this session return sm.historyManager.HasHistory(taskSessionID) } // getResumeContextPrompt generates a prompt with resume context if available. // If there's no history or context injection is disabled, returns the original prompt. func (sm *SessionManager) getResumeContextPrompt(agentConfig agents.Agent, taskSessionID, originalPrompt string) string { if !sm.shouldInjectResumeContext(agentConfig, taskSessionID) { return originalPrompt } resumePrompt, err := sm.historyManager.GenerateResumeContext(taskSessionID, originalPrompt) if err != nil { sm.logger.Warn("failed to generate resume context, using original prompt", zap.String("session_id", taskSessionID), zap.Error(err)) return originalPrompt } return resumePrompt } // loadSession loads an existing session via ACP session/load func (sm *SessionManager) loadSession( ctx context.Context, client *agentctl.Client, agentConfig agents.Agent, sessionID string, mcpServers []agentctltypes.McpServer, ) (string, error) { sm.logger.Info("sending ACP session/load request", zap.String("agent_type", agentConfig.ID()), zap.String("session_id", sessionID)) if err := client.LoadSession(ctx, sessionID, mcpServers); err != nil { sm.logger.Error("ACP session/load failed", zap.String("agent_type", agentConfig.ID()), zap.String("session_id", sessionID), zap.Error(err)) return "", fmt.Errorf("session/load failed: %w", err) } sm.logger.Info("ACP session loaded successfully", zap.String("agent_type", agentConfig.ID()), zap.String("session_id", sessionID)) return sessionID, nil } // createNewSession creates a new session via ACP session/new func (sm *SessionManager) createNewSession( ctx context.Context, client *agentctl.Client, agentConfig agents.Agent, workspacePath string, mcpServers []agentctltypes.McpServer, ) (string, error) { sm.logger.Info("sending ACP session/new request", zap.String("agent_type", agentConfig.ID()), zap.String("workspace_path", workspacePath)) sessionID, err := client.NewSession(ctx, workspacePath, mcpServers) if err != nil { sm.logger.Error("ACP session/new failed", zap.String("agent_type", agentConfig.ID()), zap.String("workspace_path", workspacePath), zap.Error(err)) return "", fmt.Errorf("session/new failed: %w", err) } sm.logger.Info("ACP session created successfully", zap.String("agent_type", agentConfig.ID()), zap.String("session_id", sessionID)) return sessionID, nil } // InitializeAndPrompt performs full ACP session initialization and sends the initial prompt. // This offices: // 1. Session initialization (initialize + session/new or session/load) // 2. Publishing ACP session created event // 3. Connecting WebSocket streams // 4. Sending the initial task prompt (if provided) // 5. Marking the execution as ready // // Returns the session ID on success. func (sm *SessionManager) InitializeAndPrompt( ctx context.Context, execution *AgentExecution, agentConfig agents.Agent, taskDescription string, attachments []MessageAttachment, mcpServers []agentctltypes.McpServer, markReady func(executionID string) error, profileModel string, profileMode string, ) error { // Create session-level trace span to group all operations under one trace _, sessionSpan := tracing.TraceSessionStart( context.Background(), execution.TaskID, execution.SessionID, execution.ID, ) execution.SetSessionSpan(sessionSpan) ctx = trace.ContextWithSpan(ctx, sessionSpan) if execution.agentctl != nil { execution.agentctl.SetTraceContext(execution.SessionTraceContext()) } // Create short-lived init span so the init phase is visible in trace backends // (the parent session span won't be exported until the session ends) ctx, initSpan := tracing.TraceSessionInit(ctx, execution.TaskID, execution.SessionID, execution.ID) defer initSpan.End() rt := agentConfig.Runtime() sm.logger.Info("initializing ACP session", zap.String("execution_id", execution.ID), zap.String("agentctl_url", execution.agentctl.BaseURL()), zap.String("agent_type", agentConfig.ID()), zap.String("existing_acp_session_id", execution.ACPSessionID), zap.Bool("native_session_resume", rt.SessionConfig.NativeSessionResume)) // Connect WebSocket streams FIRST — agent operations now go over the stream if sm.streamManager != nil { updatesReady := make(chan struct{}) sm.streamManager.ConnectAll(execution, updatesReady) // Wait for the updates stream to connect — required for agent operations select { case <-updatesReady: sm.logger.Debug("updates stream ready") case <-time.After(10 * time.Second): return fmt.Errorf("timeout waiting for agent stream to connect") } } // Use InitializeSession for configuration-driven session initialization result, err := sm.InitializeSession( ctx, execution.agentctl, agentConfig, execution.ACPSessionID, execution.WorkspacePath, mcpServers, ) if err != nil { sm.logger.Error("session initialization failed", zap.String("execution_id", execution.ID), zap.Error(err)) return err } sm.logger.Info("ACP session initialized", zap.String("execution_id", execution.ID), zap.String("agent_name", result.AgentName), zap.String("agent_version", result.AgentVersion), zap.String("session_id", result.SessionID)) execution.ACPSessionID = result.SessionID execution.sessionInitialized = true // Apply profile model via ACP session/set_model (best-effort). // ACP is the only surface for model selection now; no --model CLI flag. if profileModel != "" && execution.agentctl != nil { if err := execution.agentctl.SetModel(ctx, profileModel); err != nil { sm.logger.Warn("failed to set profile model via ACP", zap.String("execution_id", execution.ID), zap.String("model", profileModel), zap.Error(err)) } else { sm.logger.Info("set profile model on ACP session", zap.String("execution_id", execution.ID), zap.String("model", profileModel)) } } // Apply profile mode via ACP session/set_mode (best-effort). if profileMode != "" && execution.agentctl != nil { if err := execution.agentctl.SetMode(ctx, result.SessionID, profileMode); err != nil { sm.logger.Warn("failed to set profile mode via ACP", zap.String("execution_id", execution.ID), zap.String("mode", profileMode), zap.Error(err)) } else { sm.logger.Info("set profile mode on ACP session", zap.String("execution_id", execution.ID), zap.String("mode", profileMode)) } } // Publish session created event if sm.eventPublisher != nil { sm.eventPublisher.PublishACPSessionCreated(execution, result.SessionID) } // Send the task prompt if provided, or mark the execution as ready. sm.dispatchInitialPrompt(ctx, execution, agentConfig, taskDescription, attachments, markReady) return nil } // convertAttachments converts lifecycle.MessageAttachment to v1.MessageAttachment for ACP. func convertAttachments(attachments []MessageAttachment) []v1.MessageAttachment { if len(attachments) == 0 { return nil } result := make([]v1.MessageAttachment, 0, len(attachments)) for _, att := range attachments { result = append(result, v1.MessageAttachment{ Type: att.Type, Data: att.Data, MimeType: att.MimeType, Name: att.Name, }) } return result } // dispatchInitialPrompt sends the initial task prompt or marks the execution as ready. // For sessions with a task description, sends the prompt asynchronously. // For resumed sessions (fork_session pattern), defers context injection to the first user message. // For all other cases, marks the execution ready immediately. func (sm *SessionManager) dispatchInitialPrompt(ctx context.Context, execution *AgentExecution, agentConfig agents.Agent, taskDescription string, attachments []MessageAttachment, markReady func(executionID string) error) { switch { case taskDescription != "" || len(attachments) > 0: // The orchestrator wrapped the prompt with the Kandev system block // before handing it to the runtime; do not re-wrap here. effectivePrompt := sm.getResumeContextPrompt(agentConfig, execution.SessionID, taskDescription) if effectivePrompt != taskDescription { sm.logger.Info("injecting resume context into initial prompt", zap.String("execution_id", execution.ID), zap.String("session_id", execution.SessionID), zap.Int("original_length", len(taskDescription)), zap.Int("effective_length", len(effectivePrompt))) } acpAttachments := convertAttachments(attachments) go func() { promptCtx, cancel := appctx.Detached(ctx, sm.stopCh, 0) defer cancel() _, err := sm.SendPrompt(promptCtx, execution, effectivePrompt, false, acpAttachments, false) if err != nil { sm.logger.Error("initial prompt failed", zap.String("execution_id", execution.ID), zap.Error(err)) } }() case sm.shouldInjectResumeContext(agentConfig, execution.SessionID): execution.needsResumeContext = true sm.logger.Info("session has history for context injection, will inject on first user prompt", zap.String("execution_id", execution.ID), zap.String("session_id", execution.SessionID)) if err := markReady(execution.ID); err != nil { sm.logger.Error("failed to mark execution as ready", zap.String("execution_id", execution.ID), zap.Error(err)) } default: sm.logger.Debug("no task description and no resume context needed, marking as ready", zap.String("execution_id", execution.ID)) if err := markReady(execution.ID); err != nil { sm.logger.Error("failed to mark execution as ready", zap.String("execution_id", execution.ID), zap.Error(err)) } } } // buildEffectivePrompt applies resume context injection if needed, returning the effective prompt to send. // The Kandev MCP system block is intentionally NOT re-injected here — it is // only attached to the very first prompt of a task at the orchestrator layer. // On resume, the agent CLI's restored conversation already contains it. func (sm *SessionManager) buildEffectivePrompt(execution *AgentExecution, prompt string) string { if !execution.needsResumeContext || execution.resumeContextInjected { return prompt } effectivePrompt := prompt if sm.historyManager != nil { resumePrompt, err := sm.historyManager.GenerateResumeContext(execution.SessionID, prompt) switch { case err != nil: sm.logger.Warn("failed to generate resume context for follow-up prompt", zap.String("execution_id", execution.ID), zap.Error(err)) case resumePrompt != prompt: effectivePrompt = resumePrompt sm.logger.Info("injecting resume context into follow-up prompt", zap.String("execution_id", execution.ID), zap.String("session_id", execution.SessionID), zap.Int("original_length", len(prompt)), zap.Int("effective_length", len(effectivePrompt))) sm.logger.Info("resume context prompt content", zap.String("execution_id", execution.ID), zap.String("resume_prompt", effectivePrompt)) } } execution.resumeContextInjected = true return effectivePrompt } // waitForPromptDone waits for the prompt to complete, checking for stalls periodically. func (sm *SessionManager) waitForPromptDone(ctx context.Context, execution *AgentExecution) (*PromptResult, error) { stallTicker := time.NewTicker(30 * time.Second) defer stallTicker.Stop() for { select { case signal := <-execution.promptDoneCh: if signal.IsError { sm.logger.Error("prompt completed with error", zap.String("execution_id", execution.ID), zap.String("error", signal.Error)) // Wrap the cancel-escalation sentinel so PromptTask can identify it and // skip the REVIEW task-state transition — the user is cancelling, not // hitting a real agent failure. if strings.HasPrefix(signal.Error, "cancel escalated") { return nil, fmt.Errorf("%w: %s: %w", ErrAgentReported, signal.Error, ErrCancelEscalated) } return nil, fmt.Errorf("%w: %s", ErrAgentReported, signal.Error) } // Peek at buffer for return value execution.messageMu.Lock() agentMessage := execution.messageBuffer.String() execution.messageMu.Unlock() sm.logger.Info("prompt completed", zap.String("execution_id", execution.ID), zap.String("stop_reason", signal.StopReason), zap.Int("message_length", len(agentMessage))) // Note: markReady is NOT called here — handleAgentEvent(complete) already handles it. return &PromptResult{ StopReason: signal.StopReason, AgentMessage: agentMessage, }, nil case <-ctx.Done(): return nil, ctx.Err() case <-stallTicker.C: execution.lastActivityAtMu.Lock() elapsed := time.Since(execution.lastActivityAt) lastActivity := execution.lastActivityAt execution.lastActivityAtMu.Unlock() if elapsed > 5*time.Minute { sm.logger.Warn("agent stall detected: no events received", zap.String("execution_id", execution.ID), zap.Duration("elapsed_since_last_event", elapsed), zap.Time("last_activity", lastActivity)) } } } } // SendPrompt sends a prompt to an agent execution and waits for completion. // For initial prompts, pass validateStatus=false. For follow-up prompts, pass validateStatus=true. // When dispatchOnly is true, returns once agentctl.Prompt has accepted the prompt // instead of blocking on the agent's complete event — used by the MCP message_task // path so the tool call doesn't hang for the duration of the target's turn. // Attachments (images) are passed to the agent if provided. // Returns the prompt result containing the stop reason and agent message. // Note: MarkReady is handled by handleAgentEvent(complete), not by this method. func (sm *SessionManager) SendPrompt( ctx context.Context, execution *AgentExecution, prompt string, validateStatus bool, attachments []v1.MessageAttachment, dispatchOnly bool, ) (*PromptResult, error) { if execution.agentctl == nil { return nil, fmt.Errorf("execution %q has no agentctl client", execution.ID) } // Drain any stale signal left in the channel by a prior dispatch-only prompt // whose completion arrived after SendPrompt returned. Without this, the next // waitForPromptDone would consume the stale signal and report an immediate // (wrong) completion for the new prompt. select { case <-execution.promptDoneCh: default: } // Signal when this prompt completes so CancelAgent can wait for it. // In dispatch-only mode there is no in-flight wait to coordinate with, so the // barrier is unused — skip it to avoid closing the channel before the agent's // async processing actually finishes. if !dispatchOnly { defer beginPromptBarrier(execution)() } // Inject session trace context so prompt spans become children of the session span if sessionSpan := trace.SpanFromContext(execution.SessionTraceContext()); sessionSpan.SpanContext().IsValid() { ctx = trace.ContextWithSpan(ctx, sessionSpan) } // For follow-up prompts, validate status and update to RUNNING if validateStatus { if execution.Status != v1.AgentStatusRunning && execution.Status != v1.AgentStatusReady { return nil, fmt.Errorf("execution %q is not ready for prompts (status: %s)", execution.ID, execution.Status) } if sm.executionStore != nil { sm.executionStore.UpdateStatus(execution.ID, v1.AgentStatusRunning) } } // Clear buffers and streaming state before starting prompt // This ensures each prompt starts fresh and doesn't append to previous message execution.messageMu.Lock() execution.messageBuffer.Reset() execution.thinkingBuffer.Reset() execution.currentMessageID = "" // Clear streaming message ID for new turn execution.currentThinkingID = "" // Clear streaming thinking ID for new turn execution.messageMu.Unlock() // Apply resume context injection if needed (first prompt after resume) effectivePrompt := sm.buildEffectivePrompt(execution, prompt) sm.logger.Info("sending prompt to agent", zap.String("execution_id", execution.ID), zap.Int("prompt_length", len(effectivePrompt)), zap.Int("attachments_count", len(attachments))) // Store user prompt to session history for context injection (store original, not with injected context) if sm.historyManager != nil && execution.historyEnabled && execution.SessionID != "" { if err := sm.historyManager.AppendUserMessage(execution.SessionID, prompt); err != nil { sm.logger.Warn("failed to store user message to history", zap.Error(err)) } } // Initialize activity timestamp for stall detection execution.lastActivityAtMu.Lock() execution.lastActivityAt = time.Now() execution.lastActivityAtMu.Unlock() // Fire the prompt (returns immediately now — completion comes via WebSocket complete event) if err := execution.agentctl.Prompt(ctx, effectivePrompt, attachments); err != nil { if isAgentStreamNotConnectedErr(err) && sm.streamManager != nil { sm.logger.Warn("agent stream not connected, reconnecting and retrying prompt once", zap.String("execution_id", execution.ID)) retryErr := sm.retryPromptAfterReconnect(ctx, execution, effectivePrompt, attachments) if retryErr == nil { if dispatchOnly { return &PromptResult{StopReason: PromptStopReasonDispatched}, nil } return sm.waitForPromptDone(ctx, execution) } sm.logger.Warn("prompt retry after stream reconnect failed", zap.String("execution_id", execution.ID), zap.Error(retryErr)) } sm.logger.Error("failed to trigger prompt", zap.String("execution_id", execution.ID), zap.Error(err)) return nil, fmt.Errorf("failed to trigger prompt: %w", err) } if dispatchOnly { return &PromptResult{StopReason: PromptStopReasonDispatched}, nil } // Wait for completion signal from handleAgentEvent(complete) or stream disconnect. return sm.waitForPromptDone(ctx, execution) } // beginPromptBarrier sets up a completion signal on the execution so CancelAgent // can wait for the in-flight SendPrompt to finish before the caller retries. // Returns a cleanup function that must be deferred: defer beginPromptBarrier(exec)() func beginPromptBarrier(execution *AgentExecution) func() { ch := make(chan struct{}) execution.promptFinishedMu.Lock() execution.promptFinished = ch execution.promptFinishedMu.Unlock() return func() { close(ch) } } func (sm *SessionManager) retryPromptAfterReconnect( ctx context.Context, execution *AgentExecution, prompt string, attachments []v1.MessageAttachment, ) error { ready := make(chan struct{}) sm.streamManager.connectUpdatesStreamAsync(execution, ready) select { case <-ready: case <-ctx.Done(): return ctx.Err() case <-time.After(5 * time.Second): return fmt.Errorf("timed out waiting for updates stream reconnect") } return execution.agentctl.Prompt(ctx, prompt, attachments) } // jsonRPCMethodNotFound is the JSON-RPC 2.0 error code for "Method not found". const jsonRPCMethodNotFound = -32601 // jsonRPCResourceNotFound is the ACP-specific error code that agents return when // asked to load a session ID they don't know about (e.g. claude-agent-acp after // its in-memory session map was cleared by a restart). const jsonRPCResourceNotFound = -32002 // isMethodNotFoundErr checks if an error wraps a JSON-RPC "Method not found" error. func isMethodNotFoundErr(err error) bool { var reqErr *acp.RequestError if errors.As(err, &reqErr) { return reqErr.Code == jsonRPCMethodNotFound } return false } // isSessionUnknownErr reports whether an error from session/load means the // agent doesn't know about the requested session ID — typically because the // agent process restarted and lost its in-memory session map. The caller // should fall back to creating a fresh session rather than aborting the launch. func isSessionUnknownErr(err error) bool { if err == nil { return false } var reqErr *acp.RequestError if errors.As(err, &reqErr) && reqErr.Code == jsonRPCResourceNotFound { return true } // Some agents return the error in the wrapped message string instead of a // structured RequestError. Match the canonical phrase as a safety net. return strings.Contains(err.Error(), "Resource not found") } func isAgentStreamNotConnectedErr(err error) bool { if err == nil { return false } return strings.Contains(err.Error(), "agent stream not connected") }