// Package orchestrator provides the main orchestrator service that ties all components together. package orchestrator import ( "context" "errors" "fmt" "os" "strings" "time" "go.uber.org/zap" "github.com/kandev/kandev/internal/agent/runtime/agentctl" "github.com/kandev/kandev/internal/agent/runtime/lifecycle" "github.com/kandev/kandev/internal/agent/runtime/routingerr" "github.com/kandev/kandev/internal/orchestrator/dto" "github.com/kandev/kandev/internal/orchestrator/executor" "github.com/kandev/kandev/internal/orchestrator/queue" "github.com/kandev/kandev/internal/sysprompt" "github.com/kandev/kandev/internal/task/models" wfmodels "github.com/kandev/kandev/internal/workflow/models" v1 "github.com/kandev/kandev/pkg/api/v1" ) // PromptResult contains the result of a prompt operation type PromptResult struct { StopReason string // The reason the agent stopped (e.g., "end_turn") AgentMessage string // The agent's accumulated response message } // resumeReasonErrorRecovery is the resume reason returned when a session is in // error-recovery state (WAITING_FOR_INPUT with a non-empty ErrorMessage). const resumeReasonErrorRecovery = "error_recovery" // resumeReasonFailedSessionResumable is the resume reason returned when a // FAILED session is auto-resumed because its runtime is Resumable. Distinct // from "agent_not_running" so log filtering can isolate FAILED auto-resumes. const resumeReasonFailedSessionResumable = "failed_session_resumable" var ErrAgentPromptInProgress = errors.New("agent is currently processing a prompt") var ErrSessionResetInProgress = errors.New("session reset in progress") // ErrSessionNotPromptable is returned when a session cannot accept a prompt // because of its lifecycle state (STARTING, CREATED, FAILED, CANCELLED). // Distinct from ErrAgentPromptInProgress, which is RUNNING-only — confusing // the two misleads the UI and any caller doing errors.Is checks. var ErrSessionNotPromptable = errors.New("session not promptable") func isAgentPromptInProgressError(err error) bool { return err != nil && errors.Is(err, ErrAgentPromptInProgress) } // isSessionBusyError reports whether the session is in a state where a queued // or auto-started prompt should be retried later rather than dropped. Covers // both "the agent is mid-turn" (ErrAgentPromptInProgress, RUNNING) and "the // session isn't yet ready to accept input" (ErrSessionNotPromptable — // STARTING, CREATED, FAILED, CANCELLED). The pre-PR code path collapsed both // into ErrAgentPromptInProgress; this helper preserves the requeue behaviour // after the error split so queued messages targeting a session that is // briefly STARTING/CREATED don't get silently dropped (see TODO about the // missing dead-letter queue in executeQueuedMessage). func isSessionBusyError(err error) bool { if err == nil { return false } return errors.Is(err, ErrAgentPromptInProgress) || errors.Is(err, ErrSessionNotPromptable) } func isSessionResetInProgressError(err error) bool { return err != nil && errors.Is(err, ErrSessionResetInProgress) } // isTransientPromptError reports whether a prompt error is worth retrying via // the queue. ErrExecutionNotFound is intentionally NOT included here: // callers that can recover (autoStartStepPrompt → fallbackFreshLaunchOnMissingExecution) // detect it explicitly via errors.Is and route differently; callers that // can't (executeQueuedMessage) should not infinite-requeue on it. Treating // "execution not found" as transient blanket-applies a retry that loops // forever when the execution is genuinely gone. func isTransientPromptError(err error) bool { if err == nil { return false } msg := strings.ToLower(err.Error()) return strings.Contains(msg, "agent stream disconnected") || strings.Contains(msg, "use of closed network connection") } func isAgentAlreadyRunningError(err error) bool { return err != nil && errors.Is(err, lifecycle.ErrAgentAlreadyRunning) } func validateSessionWorktrees(session *models.TaskSession) error { for _, wt := range session.Worktrees { if wt.WorktreePath == "" { continue } if _, err := os.Stat(wt.WorktreePath); err != nil { return fmt.Errorf("worktree path not found: %w", err) } } return nil } // EnqueueTask manually adds a task to the queue func (s *Service) EnqueueTask(ctx context.Context, task *v1.Task) error { s.logger.Debug("manually enqueueing task", zap.String("task_id", task.ID), zap.String("title", task.Title)) return s.scheduler.EnqueueTask(task) } // PrepareTaskSession creates a session entry without launching the agent. // This allows the WS handler to return the session ID immediately while workspace setup // continues in the background. Use StartCreatedSession to continue with agent launch. // When launchWorkspace is true, workspace infrastructure (agentctl) is launched asynchronously; // the frontend receives preparation progress via executor.prepare.progress WS events. func (s *Service) PrepareTaskSession(ctx context.Context, taskID string, agentProfileID string, executorID string, executorProfileID string, workflowStepID string, launchWorkspace bool) (string, error) { s.logger.Debug("preparing task session", zap.String("task_id", taskID), zap.String("agent_profile_id", agentProfileID), zap.String("executor_id", executorID), zap.String("executor_profile_id", executorProfileID), zap.String("workflow_step_id", workflowStepID), zap.Bool("launch_workspace", launchWorkspace)) // Fetch the task to get workspace info task, err := s.scheduler.GetTask(ctx, taskID) if err != nil { s.logger.Error("failed to fetch task for session preparation", zap.String("task_id", taskID), zap.Error(err)) return "", err } // Resolve agent/executor profile from task metadata if not explicitly provided if agentProfileID == "" { if v, ok := task.Metadata["agent_profile_id"].(string); ok && v != "" { agentProfileID = v } } if executorProfileID == "" { if v, ok := task.Metadata["executor_profile_id"].(string); ok && v != "" { executorProfileID = v } } // Inherit agent/executor profile from parent task's primary session when not // explicitly provided. This covers subtasks created with start_agent=false that // are later opened manually from the UI. We check each field independently so // that a caller providing only some fields still gets the rest filled in. if (agentProfileID == "" || executorProfileID == "" || executorID == "") && task.ParentID != "" { agentProfileID, executorProfileID, executorID = s.inheritFromParentSession( ctx, task.ParentID, agentProfileID, executorProfileID, executorID, ) // Fall back to workspace defaults for agent profile (subtasks only — // regular tasks resolve defaults downstream in the executor layer). if agentProfileID == "" { workspace, err := s.repo.GetWorkspace(ctx, task.WorkspaceID) if err == nil && workspace != nil && workspace.DefaultAgentProfileID != nil && *workspace.DefaultAgentProfileID != "" { agentProfileID = *workspace.DefaultAgentProfileID } } if executorID == "" && executorProfileID == "" { executorID = models.ExecutorIDWorktree } } // Fall back to the task's current workflow step when the caller didn't provide one. // This ensures sessions created via the kanban card (which doesn't send workflow_step_id) // inherit the task's step and participate in workflow events. if workflowStepID == "" { dbTask, err := s.repo.GetTask(ctx, taskID) if err != nil { s.logger.Warn("failed to fetch task for workflow step fallback", zap.String("task_id", taskID), zap.Error(err)) } else if dbTask.WorkflowStepID != "" { workflowStepID = dbTask.WorkflowStepID } } // Create session entry in database. Office tasks route through // EnsureSessionForAgent so runs + advanced-mode reuse one row. // prepareSessionForStart also propagates any inherited workspace // environment (inherit_parent / shared_group) onto the new session. sessionID, err := s.prepareSessionForStart(ctx, task, agentProfileID, executorID, executorProfileID, workflowStepID) if err != nil { s.logger.Error("failed to prepare session", zap.String("task_id", taskID), zap.Error(err)) return "", err } // Notify the frontend that a new CREATED session exists. The start path // transitions through updateTaskSessionState which broadcasts; the prepare // path writes the row directly, so without this the per-task session list // stays empty until a manual reload. s.publishSessionCreatedEvent(ctx, taskID, sessionID, workflowStepID) if launchWorkspace { // Launch workspace infrastructure (agentctl) in the background so the WS response // returns the session ID immediately. The frontend navigates to the session page // and shows preparation progress via executor.prepare.progress WS events. go func() { bgCtx := context.Background() prepExec, launchErr := s.executor.LaunchPreparedSession(bgCtx, task, sessionID, executor.LaunchOptions{AgentProfileID: agentProfileID, ExecutorID: executorID, WorkflowStepID: workflowStepID}) if launchErr != nil { s.logger.Warn("failed to launch workspace for prepared session (file browsing may be unavailable)", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(launchErr)) return } if prepExec != nil { s.ensureSessionPRWatch(bgCtx, taskID, prepExec.SessionID, prepExec.WorktreeBranch) } }() } s.logger.Info("task session prepared", zap.String("task_id", taskID), zap.String("session_id", sessionID)) return sessionID, nil } // StartCreatedSession starts agent execution for a task using a session that is in CREATED state. // This is used when a session was prepared (via PrepareSession) but the agent was not launched, // and the user now wants to start the agent with a prompt (e.g., from the plan panel or chat). // When skipMessageRecord is true, only the session state is updated (the caller already stored the user message). // When planMode is true, plan mode instructions are injected into the prompt and session metadata is set. // autoStart marks the launch as having been triggered by an automated path // (only consumed when skipMessageRecord is false — callers that store their // own message control its metadata directly). // //nolint:cyclop,funlen // existing complexity inherited from main's session-lifecycle handling; signature touched here only to thread autoStart func (s *Service) StartCreatedSession(ctx context.Context, taskID, sessionID, agentProfileID, prompt string, skipMessageRecord, planMode, autoStart bool, attachments []v1.MessageAttachment) (*executor.TaskExecution, error) { s.logger.Debug("starting created session", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("agent_profile_id", agentProfileID)) // Load and verify session session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return nil, fmt.Errorf("failed to get session: %w", err) } if session.TaskID != taskID { return nil, fmt.Errorf("session does not belong to task") } // Accept CREATED (normal) or WAITING_FOR_INPUT (after on_turn_start step transition). // When the user sends the first message to a prepared session, on_turn_start may fire // and move the step, which sets the session to WAITING_FOR_INPUT before we get here. if session.State != models.TaskSessionStateCreated && session.State != models.TaskSessionStateWaitingForInput { return nil, fmt.Errorf("session is not in CREATED or WAITING_FOR_INPUT state (current: %s)", session.State) } // Use agent profile from request, fall back to session's stored value effectiveProfileID := agentProfileID if effectiveProfileID == "" { effectiveProfileID = session.AgentProfileID } if effectiveProfileID == "" { return nil, fmt.Errorf("agent_profile_id is required") } // Override with workflow step's agent profile if one is configured. effectiveProfileID = s.resolveEffectiveAgentProfile(ctx, taskID, "", effectiveProfileID) // If the workflow step overrode the profile, update the session record in DB // so the frontend tab displays the correct agent (it reads session.agent_profile_id). if effectiveProfileID != session.AgentProfileID { s.logger.Info("updating session agent profile for workflow step override", zap.String("session_id", sessionID), zap.String("old_profile", session.AgentProfileID), zap.String("new_profile", effectiveProfileID)) session.AgentProfileID = effectiveProfileID // Tag as workflow-spawned so a later transition to a plain step can // correctly revert to the task default. Without this, the in-place // profile mutation here is invisible to maybySwitchSessionForProfile, // which would treat the session as user-chosen and leave it on the // override forever. s.tagSessionAsWorkflowSwitched(ctx, sessionID) // Re-resolve the agent profile snapshot so the tab shows the correct agent logo/name. // Set a minimal snapshot first so stale data is never persisted if resolution fails. session.AgentProfileSnapshot = map[string]interface{}{"id": effectiveProfileID} if profileInfo, err := s.agentManager.ResolveAgentProfile(ctx, effectiveProfileID); err != nil { s.logger.Warn("failed to resolve agent profile snapshot for workflow step override", zap.String("session_id", sessionID), zap.String("profile_id", effectiveProfileID), zap.Error(err)) } else if profileInfo != nil { session.AgentProfileSnapshot = map[string]interface{}{ "id": profileInfo.ProfileID, "name": profileInfo.ProfileName, "agent_id": profileInfo.AgentID, "agent_name": profileInfo.AgentName, "model": profileInfo.Model, } } if err := s.repo.UpdateTaskSession(ctx, session); err != nil { s.logger.Warn("failed to update session agent profile", zap.String("session_id", sessionID), zap.Error(err)) } } // Transition task state: CREATED → SCHEDULING → (IN_PROGRESS via executor) if err := s.taskRepo.UpdateTaskState(ctx, taskID, v1.TaskStateScheduling); err != nil { s.logger.Warn("failed to update task state to SCHEDULING", zap.String("task_id", taskID), zap.Error(err)) } task, err := s.scheduler.GetTask(ctx, taskID) if err != nil { return nil, err } effectivePrompt := prompt if effectivePrompt == "" { effectivePrompt = task.Description } // NOTE: on_turn_start is intentionally NOT processed here. // - User-initiated path: dispatchPromptAsync (message_handlers.go) already // calls ProcessOnTurnStart before invoking StartCreatedSession via // forwardMessageAsPrompt, so on_turn_start has already fired. // - Workflow auto-start path: autoStartStepPrompt calls us because the // workflow just transitioned us into this step (via on_turn_complete or // on_enter). Firing on_turn_start again here cascades the workflow back // out before the step's auto-start prompt can be delivered to its agent. // // However, for the user-initiated path, on_turn_start may have switched the // session profile already, in which case the session ID we were called with // is now COMPLETED and we need to redirect to the new active session. session, err = s.repo.GetTaskSession(ctx, sessionID) if err != nil { return nil, fmt.Errorf("failed to reload session: %w", err) } if session.State == models.TaskSessionStateCompleted { activeSession, activeErr := s.repo.GetActiveTaskSessionByTaskID(ctx, taskID) if activeErr != nil || activeSession == nil { return nil, fmt.Errorf("session was switched but no active session found: %w", activeErr) } session = activeSession sessionID = activeSession.ID effectiveProfileID = activeSession.AgentProfileID } // Apply workflow step prompt wrapping and plan mode injection. // Called unconditionally so workflow-step prompt composition (prefix/suffix) // applies even when plan mode is not requested. // Re-read the task after on_turn_start may have changed the workflow step. // Ephemeral tasks skip workflow step processing since they have no workflow. dbTask, err := s.repo.GetTask(ctx, taskID) if err != nil { return nil, fmt.Errorf("failed to reload task after on_turn_start: %w", err) } effectivePrompt, planModeActive := s.applyWorkflowAndPlanMode(ctx, effectivePrompt, taskID, sessionID, dbTask.WorkflowStepID, planMode, task.IsEphemeral) // Inject config context for config-mode sessions (dedicated settings chat) if cm, ok := session.Metadata["config_mode"].(bool); ok && cm { effectivePrompt = sysprompt.InjectConfigContext(sessionID, effectivePrompt) } // Wrap the first prompt with the Kandev MCP system block. See the // matching block in startTask for the rationale (DB stores wrapped form; // Message.ToAPI strips for display). Idempotent — upstream call sites that // record the user message themselves (wsAddMessage on CREATED sessions) // wrap first, and the HasKandevContext guard prevents a second wrap here. // Passthrough profiles skip the wrap: the prompt is typed straight into the // agent CLI's TTY and the user sees it verbatim — they don't want a wall of // MCP-tool boilerplate prepended to "hello". if (effectivePrompt != "" || len(attachments) > 0) && !sysprompt.HasKandevContext(effectivePrompt) && !session.IsPassthrough { effectivePrompt = sysprompt.InjectKandevContext(taskID, sessionID, effectivePrompt) } executorID := session.ExecutorID // Cache the raw prompt so a transient-provider-error (529) retry can // re-drive this first turn — initial launches bypass PromptTask. s.rememberTurnPrompt(sessionID, prompt, "", planMode, attachments) execution, err := s.executor.LaunchPreparedSession(ctx, task, sessionID, executor.LaunchOptions{AgentProfileID: effectiveProfileID, ExecutorID: executorID, Prompt: effectivePrompt, StartAgent: true, Attachments: attachments}) if err != nil { return nil, err } // Record the initial user message and set plan mode metadata after launch. // Note: we do NOT set session state here — the executor sets it to STARTING, // and event handlers (handleAgentReady) transition it to WAITING_FOR_INPUT. s.postLaunchCreated(ctx, taskID, sessionID, effectivePrompt, skipMessageRecord, planModeActive, autoStart, attachments) // Ensure a PR watch exists so the poller can detect PRs created by the agent. // PrepareTaskSession may have already created one, but if that goroutine failed // or hadn't completed, this guarantees coverage. go s.ensureSessionPRWatch(context.Background(), taskID, execution.SessionID, execution.WorktreeBranch) return execution, nil } // postLaunchCreated handles post-launch bookkeeping for a created session: // records the initial user message (unless skipped) and sets plan mode metadata. // It does NOT modify session state — the executor sets STARTING, and event handlers // (handleAgentReady) handle the transition to WAITING_FOR_INPUT. // autoStart marks the message as having been created by an automated trigger // (preserved through to recordInitialMessage's auto_start metadata tag); the // flag is only consumed when skipMessage is false (callers that store their // own message control its metadata directly). func (s *Service) postLaunchCreated(ctx context.Context, taskID, sessionID, prompt string, skipMessage, planModeActive, autoStart bool, attachments []v1.MessageAttachment) { if !skipMessage { s.recordInitialMessage(ctx, taskID, sessionID, prompt, planModeActive, autoStart, attachments) } if planModeActive { sess, err := s.repo.GetTaskSession(ctx, sessionID) if err == nil { s.setSessionPlanMode(ctx, sess, true) } } } // StartTask manually starts agent execution for a task. // If workflowStepID is provided and workflowStepGetter is set, the prompt will be built // using the step's prompt_prefix + base prompt + prompt_suffix, and plan mode will be // applied if the step has plan_mode enabled. // If planMode is true and the workflow step doesn't already apply plan mode, // default plan mode instructions are injected into the prompt. // autoStart marks the launch as having been triggered by an automated path // (PR/issue/Jira/Linear watch, workflow auto-start) rather than direct user // input — the seed prompt is tagged so the github cleanup loop can tell // "agent ran on its own" from "user actually engaged". func (s *Service) StartTask(ctx context.Context, taskID string, agentProfileID string, executorID string, executorProfileID string, priority string, prompt string, workflowStepID string, planMode, autoStart bool, attachments []v1.MessageAttachment) (*executor.TaskExecution, error) { return s.startTask(ctx, taskID, agentProfileID, executorID, executorProfileID, priority, prompt, workflowStepID, planMode, autoStart, attachments, nil, nil) } // StartTaskWithEnv starts a task and carries launch-scoped environment variables // through to the agent runtime. Existing StartTask callers keep the old behavior. func (s *Service) StartTaskWithEnv(ctx context.Context, taskID string, agentProfileID string, executorID string, executorProfileID string, priority string, prompt string, workflowStepID string, planMode, autoStart bool, attachments []v1.MessageAttachment, env map[string]string) (*executor.TaskExecution, error) { return s.startTask(ctx, taskID, agentProfileID, executorID, executorProfileID, priority, prompt, workflowStepID, planMode, autoStart, attachments, env, nil) } // StartTaskWithRoute launches a task with a fully resolved provider // override resolved by the office routing dispatcher. Workspace, executor // selection, instruction files, system prompt, and ACP session settings // are inherited from the base AgentProfile referenced by agentProfileID; // only the provider-scoped fields (agent_id, model, mode, flags, env, // permissions) are overridden via route. // // launch carries the Office-built launch context (prompt, env, workflow // step, attachments, plan-mode flag) so routed launches behave // identically to the legacy launch path for everything except provider // selection. Without launch, routed runs would fall back to // task.Description and drop role framing / AGENTS.md / wake context. // // Env merging: launch.Env carries the office-built env vars (token, // KANDEV_*); route.Env carries provider-scoped overrides. The route // env wins on key collisions because per-provider env is the more // specific authority. // // Office-routed launches use autoStart=false: the user kicked off the // task; the office layer only chose the provider. func (s *Service) StartTaskWithRoute( ctx context.Context, taskID, agentProfileID string, launch executor.LaunchContext, route executor.RouteOverride, ) error { merged := mergeRouteEnv(launch.Env, route.Env) _, err := s.startTask(ctx, taskID, agentProfileID, launch.ExecutorID, launch.ExecutorProfileID, launch.Priority, launch.Prompt, launch.WorkflowStepID, launch.PlanMode, false, launch.Attachments, merged, &route) return err } // mergeRouteEnv combines the office-built launch env with the // per-provider route env. Route entries win on key collisions. func mergeRouteEnv(launchEnv, routeEnv map[string]string) map[string]string { if len(launchEnv) == 0 && len(routeEnv) == 0 { return nil } // The size hint is unused intentionally: CodeQL flags // `len(a)+len(b)` as a potential overflow for the make() capacity // argument. Map literals re-grow themselves; the hint was an // optimization, not a correctness requirement. out := make(map[string]string) for k, v := range launchEnv { out[k] = v } for k, v := range routeEnv { out[k] = v } return out } //nolint:cyclop,funlen // launch path threads many orthogonal concerns (workflow-step / agent-profile / office-task / config-mode / route / system-prompt wrapping); splitting it would require shared mutable state across helpers func (s *Service) startTask(ctx context.Context, taskID string, agentProfileID string, executorID string, executorProfileID string, priority string, prompt string, workflowStepID string, planMode, autoStart bool, attachments []v1.MessageAttachment, env map[string]string, route *executor.RouteOverride) (*executor.TaskExecution, error) { s.logger.Debug("manually starting task", zap.String("task_id", taskID), zap.String("agent_profile_id", agentProfileID), zap.String("executor_id", executorID), zap.String("priority", priority), zap.Int("prompt_length", len(prompt)), zap.String("workflow_step_id", workflowStepID), zap.Bool("plan_mode", planMode), zap.Bool("auto_start", autoStart), zap.Int("attachments", len(attachments))) // Office tasks do NOT transition through SCHEDULING / IN_PROGRESS on // every run. Their lifecycle status (todo / in_review / done / // blocked / cancelled) reflects the *user-meaningful workflow*, not // the orchestrator's runtime cycle. Runs schedule the *agent*, // not the task — the agent's runtime state is shown via the topbar // Working spinner + inline session timeline entry. Suppressing the // transition here avoids gratuitous flicker (REVIEW → SCHEDULING → // IN_PROGRESS → REVIEW for a single comment-reply cycle) and matches // the user's mental model. if s.isOfficeTask(ctx, taskID) { s.logger.Debug("skipping SCHEDULING transition for office task", zap.String("task_id", taskID)) } else if err := s.taskRepo.UpdateTaskState(ctx, taskID, v1.TaskStateScheduling); err != nil { s.logger.Warn("failed to update task state to SCHEDULING", zap.String("task_id", taskID), zap.Error(err)) } s.moveTaskToWorkflowStep(ctx, taskID, workflowStepID) // Resolve the workflow step's agent profile override. // The frontend may pass the workspace default profile, but the step may // require a different agent (e.g., Codex on "In Progress", Auggie on "Review"). callerProfileID := agentProfileID agentProfileID = s.resolveEffectiveAgentProfile(ctx, taskID, workflowStepID, agentProfileID) overrideApplied := agentProfileID != callerProfileID // Fetch the task from the repository to get complete task info task, err := s.scheduler.GetTask(ctx, taskID) if err != nil { s.logger.Error("failed to fetch task for manual start", zap.String("task_id", taskID), zap.Error(err)) return nil, err } // Override priority if provided in the request if priority != "" { task.Priority = priority } // Use provided prompt, fall back to task description effectivePrompt := prompt if effectivePrompt == "" { effectivePrompt = task.Description } // Prepare session first so we have the sessionID for config context injection. // For office tasks, replace the per-launch PrepareSession with the per-(task, // agent) EnsureSessionForAgent so runs reuse one row across turns. sessionID, err := s.prepareSessionForStart(ctx, task, agentProfileID, executorID, executorProfileID, workflowStepID) if err != nil { return nil, err } // When the workflow step overrode the caller's profile, tag the session // so maybySwitchSessionForProfile knows it can revert to the task default // on a later plain-step transition. Without this tag, the session looks // indistinguishable from a user-chosen one and stays on the override. if overrideApplied { s.tagSessionAsWorkflowSwitched(ctx, sessionID) } effectivePrompt, planModeActive := s.applyWorkflowAndPlanMode(ctx, effectivePrompt, task.ID, sessionID, workflowStepID, planMode, task.IsEphemeral) // Inject config context for config-mode sessions (dedicated settings chat) configMode := false if cm, ok := task.Metadata["config_mode"].(bool); ok && cm { configMode = true effectivePrompt = sysprompt.InjectConfigContext(sessionID, effectivePrompt) } // Wrap the first prompt with the Kandev MCP system block (task/session IDs + // tool list). Done at the orchestrator layer so recordInitialMessage persists // the wrapped form to task_session_messages; Message.ToAPI strips the // block for the UI bubble and exposes it via raw_content. // Only the first launch carries this wrap — follow-up prompts and resumes // rely on the agent CLI's conversation history retaining it. // Idempotent: upstream call sites (wsAddMessage on CREATED sessions, // recordAutoStartMessage) wrap before recording the user message so the DB // row carries the block; the HasKandevContext guard makes this orchestrator // pass a no-op in those cases instead of double-wrapping. // Passthrough sessions skip the wrap: the prompt is typed straight into the // agent CLI's TTY and the user sees it verbatim — they don't want a wall of // MCP-tool boilerplate prepended to "hello". Use the session snapshot, not a // live profile lookup, so a mid-run profile edit cannot change wrap behavior. skipKandevMCPWrap := false if launchSession, sessErr := s.repo.GetTaskSession(ctx, sessionID); sessErr == nil { skipKandevMCPWrap = launchSession.IsPassthrough } if (effectivePrompt != "" || len(attachments) > 0) && !sysprompt.HasKandevContext(effectivePrompt) && !skipKandevMCPWrap { effectivePrompt = sysprompt.InjectKandevContext(task.ID, sessionID, effectivePrompt) } // Office tasks restrict the MCP toolset: kanban tools (move/update/list // task, etc.) are excluded because office agents call those via the // kandev CLI ($KANDEV_CLI). See docs/specs/office-agent-cli/spec.md. mcpMode := "" if s.isOfficeTask(ctx, taskID) { mcpMode = executor.McpModeOffice } // Cache the raw prompt so a transient-provider-error (529) retry can // re-drive this first turn — initial launches bypass PromptTask. s.rememberTurnPrompt(sessionID, prompt, "", planMode, attachments) execution, err := s.executor.LaunchPreparedSession(ctx, task, sessionID, executor.LaunchOptions{ AgentProfileID: agentProfileID, ExecutorID: executorID, Prompt: effectivePrompt, WorkflowStepID: workflowStepID, StartAgent: true, McpMode: mcpMode, Attachments: attachments, Env: env, RouteOverride: route, }) if err != nil { return nil, err } s.postLaunchStart(ctx, taskID, execution, effectivePrompt, planModeActive || configMode, planModeActive, autoStart, attachments) // Note: Task stays in SCHEDULING state until the agent is fully initialized. // The executor will transition to IN_PROGRESS after StartAgentProcess() succeeds. return execution, nil } // isOfficeTask returns true when the task has an assignee agent profile, which // identifies it as an office-managed task (as opposed to a kanban / quick-chat task). func (s *Service) isOfficeTask(ctx context.Context, taskID string) bool { dbTask, err := s.repo.GetTask(ctx, taskID) return err == nil && dbTask != nil && dbTask.AssigneeAgentProfileID != "" } // prepareSessionForStart creates the session for a launch and propagates any // inherited workspace environment onto it. // // The propagation (inherit_parent / shared_group) lives here rather than only // in PrepareTaskSession so every launch entry point inherits consistently — // including the direct start path (startTask), which MCP-created subtasks reach // via auto-start. Without this, an inherit_parent subtask launched through // startTask would provision a fresh worktree instead of reusing the parent's. // propagateInheritedEnvironment is a no-op for tasks without a workspace policy. func (s *Service) prepareSessionForStart( ctx context.Context, task *v1.Task, agentProfileID, executorID, executorProfileID, workflowStepID string, ) (string, error) { sessionID, err := s.createStartSession(ctx, task, agentProfileID, executorID, executorProfileID, workflowStepID) if err != nil { return "", err } s.propagateInheritedEnvironment(ctx, task, sessionID) return sessionID, nil } // createStartSession picks the right session-creation path for the task: // office tasks with an assignee use the per-(task, agent) EnsureSessionForAgent // (so runs reuse one row across turns); kanban / quick-chat fall through to // the per-launch PrepareSession used since day one. func (s *Service) createStartSession( ctx context.Context, task *v1.Task, agentProfileID, executorID, executorProfileID, workflowStepID string, ) (string, error) { dbTask, err := s.repo.GetTask(ctx, task.ID) if err == nil && dbTask != nil && dbTask.AssigneeAgentProfileID != "" { session, ensureErr := s.executor.EnsureSessionForAgent( ctx, task, dbTask.AssigneeAgentProfileID, agentProfileID, executorID, executorProfileID, ) if ensureErr != nil { return "", ensureErr } // The office/assignee path bypasses StartCreatedSession's override // mutation: the session is created directly with the assignee // profile (which falls back to the step's agent_profile_id via the // runner projection). If that profile differs from the caller's, // the assignment was workflow-driven — tag so a later transition // to a plain step knows it can revert to the task default. if agentProfileID != "" && session.AgentProfileID != "" && session.AgentProfileID != agentProfileID { s.tagSessionAsWorkflowSwitched(ctx, session.ID) } return session.ID, nil } return s.executor.PrepareSession(ctx, task, agentProfileID, executorID, executorProfileID, workflowStepID) } // moveTaskToWorkflowStep moves a task to the target workflow step if provided and different from current. func (s *Service) moveTaskToWorkflowStep(ctx context.Context, taskID, workflowStepID string) { if workflowStepID == "" { return } dbTask, err := s.repo.GetTask(ctx, taskID) if err != nil || dbTask.WorkflowStepID == workflowStepID { return } dbTask.WorkflowStepID = workflowStepID dbTask.UpdatedAt = time.Now().UTC() if err := s.repo.UpdateTask(ctx, dbTask); err != nil { s.logger.Warn("failed to move task to workflow step", zap.String("task_id", taskID), zap.String("workflow_step_id", workflowStepID), zap.Error(err)) return } s.publishTaskUpdated(ctx, dbTask) } // resolveEffectiveAgentProfile checks whether the task's workflow step overrides // the agent profile. If the step (or workflow default) specifies a different // profile, that profile is returned instead of the caller-provided one. // This ensures the initial task start uses the step's agent — not just the // workspace default the frontend sends. func (s *Service) resolveEffectiveAgentProfile(ctx context.Context, taskID, workflowStepID, callerProfileID string) string { if s.workflowStepGetter == nil { s.logger.Debug("resolveEffectiveAgentProfile: no workflowStepGetter, using caller profile", zap.String("task_id", taskID), zap.String("caller_profile", callerProfileID)) return callerProfileID } // Determine the effective step ID: explicit param > task's current step. effectiveStepID := workflowStepID if effectiveStepID == "" { dbTask, err := s.repo.GetTask(ctx, taskID) if err != nil { s.logger.Debug("resolveEffectiveAgentProfile: failed to load task from DB", zap.String("task_id", taskID), zap.Error(err)) return callerProfileID } s.logger.Debug("resolveEffectiveAgentProfile: loaded task from DB", zap.String("task_id", taskID), zap.String("db_workflow_step_id", dbTask.WorkflowStepID)) if dbTask.WorkflowStepID == "" { s.logger.Debug("resolveEffectiveAgentProfile: task has no workflow step, using caller profile", zap.String("task_id", taskID)) return callerProfileID } effectiveStepID = dbTask.WorkflowStepID } step, err := s.workflowStepGetter.GetStep(ctx, effectiveStepID) if err != nil || step == nil { s.logger.Debug("resolveEffectiveAgentProfile: failed to load step", zap.String("task_id", taskID), zap.String("step_id", effectiveStepID), zap.Error(err)) return callerProfileID } s.logger.Debug("resolveEffectiveAgentProfile: loaded step", zap.String("task_id", taskID), zap.String("step_id", effectiveStepID), zap.String("step_name", step.Name), zap.String("step_agent_profile_id", step.AgentProfileID), zap.String("step_workflow_id", step.WorkflowID)) stepProfile := s.resolveStepAgentProfile(ctx, step) s.logger.Debug("resolveEffectiveAgentProfile: resolved step profile", zap.String("task_id", taskID), zap.String("step_profile", stepProfile), zap.String("caller_profile", callerProfileID)) if stepProfile == "" || stepProfile == callerProfileID { return callerProfileID } s.logger.Info("overriding agent profile with workflow step profile", zap.String("task_id", taskID), zap.String("step_id", effectiveStepID), zap.String("step_name", step.Name), zap.String("caller_profile", callerProfileID), zap.String("step_profile", stepProfile)) return stepProfile } // postLaunchStart records the initial message and sets plan mode after a successful launch. func (s *Service) postLaunchStart(ctx context.Context, taskID string, execution *executor.TaskExecution, prompt string, recordPlanMode, setPlanMode, autoStart bool, attachments []v1.MessageAttachment) { if execution.SessionID != "" { s.recordInitialMessage(ctx, taskID, execution.SessionID, prompt, recordPlanMode, autoStart, attachments) if setPlanMode { session, err := s.repo.GetTaskSession(ctx, execution.SessionID) if err == nil { s.setSessionPlanMode(ctx, session, true) } } // Persist prepare_result using SetSessionMetadataKey (json_set) which // atomically sets ONE key without touching others. This avoids the // read-modify-write race where UpdateSessionMetadata clobbers plan_mode. if execution.PrepareResult != nil && execution.PrepareResult.Success { pr := lifecycle.SerializePrepareResult(execution.PrepareResult) if err := s.repo.SetSessionMetadataKey(ctx, execution.SessionID, "prepare_result", pr); err != nil { s.logger.Warn("failed to persist prepare_result", zap.String("session_id", execution.SessionID), zap.Error(err)) } } } go s.ensureSessionPRWatch(context.Background(), taskID, execution.SessionID, execution.WorktreeBranch) } // applyWorkflowAndPlanMode applies workflow step configuration and plan mode injection to a prompt. // Returns the effective prompt and whether plan mode is active (from either the step or the caller). // For ephemeral tasks (quick chat), workflow step processing is skipped since they have no workflow. func (s *Service) applyWorkflowAndPlanMode(ctx context.Context, prompt string, taskID string, sessionID string, workflowStepID string, planMode bool, isEphemeral bool) (string, bool) { effectivePrompt := prompt stepHasPlanMode := false // Skip workflow step prompt injection for ephemeral tasks - they don't have workflows if !isEphemeral && workflowStepID != "" && s.workflowStepGetter != nil { step, err := s.workflowStepGetter.GetStep(ctx, workflowStepID) if err != nil { s.logger.Warn("failed to get workflow step for prompt building", zap.String("workflow_step_id", workflowStepID), zap.Error(err)) } else { stepHasPlanMode = step.HasOnEnterAction(wfmodels.OnEnterEnablePlanMode) effectivePrompt = s.buildWorkflowPrompt(effectivePrompt, step, taskID, sessionID) } } if planMode && !stepHasPlanMode { var parts []string parts = append(parts, sysprompt.Wrap(sysprompt.DefaultPlanPrefix())) parts = append(parts, effectivePrompt) effectivePrompt = strings.Join(parts, "\n\n") } return effectivePrompt, planMode || stepHasPlanMode } // backfillInitialUserMessageIfMissing records the task's description as the // first user message when the session has no messages at all. This covers the // edge case where the initial launch failed before recordInitialMessage was // called (postLaunchStart only runs after a successful LaunchAgent), leaving // the chat empty even though the task carries the prompt the user originally // typed. // // The check requires *zero* messages, not just zero user messages: if any // agent output already exists from a partial prior run, the backfilled // message would land at the bottom of the chat (CreateMessage stamps // CreatedAt=now), which is worse than leaving the chat alone. func (s *Service) backfillInitialUserMessageIfMissing(ctx context.Context, taskID, sessionID, prompt string) { if prompt == "" || s.messageCreator == nil { return } msgs, err := s.repo.ListMessages(ctx, sessionID) if err != nil { s.logger.Warn("backfill initial message: list messages failed", zap.String("session_id", sessionID), zap.Error(err)) return } if len(msgs) > 0 { return } s.recordInitialMessage(ctx, taskID, sessionID, prompt, false, false, nil) } // recordInitialMessage creates the initial user message and updates session state after launch. // autoStart marks the message as having been created by an automated trigger // (workflow auto-start, PR/issue watch, Jira/Linear integration) so cleanup // logic can distinguish "agent ran on its own" from "user actually engaged". func (s *Service) recordInitialMessage(ctx context.Context, taskID, sessionID, prompt string, planModeActive, autoStart bool, attachments []v1.MessageAttachment) { if s.messageCreator != nil && (prompt != "" || len(attachments) > 0) { meta := NewUserMessageMeta().WithPlanMode(planModeActive).WithAutoStart(autoStart).WithAttachments(attachments) if err := s.messageCreator.CreateUserMessage(ctx, taskID, prompt, sessionID, s.getActiveTurnID(sessionID), meta.ToMap()); err != nil { s.logger.Error("failed to create initial user message", zap.String("task_id", taskID), zap.Error(err)) } } } // buildWorkflowPrompt constructs the effective prompt using workflow step configuration. // If step.Prompt contains {{task_prompt}}, it is replaced with the base prompt. // Otherwise, step.Prompt fully replaces the base prompt. // If the step has enable_plan_mode in on_enter events, plan mode prefix is also prepended. // Only true internal instructions are wrapped in tags so they can be stripped from the visible chat. func (s *Service) buildWorkflowPrompt(basePrompt string, step *wfmodels.WorkflowStep, taskID string, sessionID string) string { _ = sessionID var parts []string // Build the prompt from step.Prompt template and base prompt if step.Prompt != "" { interpolatedPrompt := sysprompt.InterpolatePlaceholders(step.Prompt, taskID) if strings.Contains(interpolatedPrompt, "{{task_prompt}}") { // Replace placeholder with base prompt combined := strings.Replace(interpolatedPrompt, "{{task_prompt}}", basePrompt, 1) parts = append(parts, combined) } else { // A step prompt without {{task_prompt}} is treated as the full visible prompt. parts = append(parts, interpolatedPrompt) } } else { // No step prompt, just use base prompt parts = append(parts, basePrompt) } return strings.Join(parts, "\n\n") } // ResumeTaskSession restarts a specific task session using its stored worktree. func (s *Service) ResumeTaskSession(ctx context.Context, taskID, sessionID string) (*executor.TaskExecution, error) { s.logger.Debug("resuming task session", zap.String("task_id", taskID), zap.String("session_id", sessionID)) session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return nil, err } if session.TaskID != taskID { return nil, fmt.Errorf("task session does not belong to task") } running, err := s.repo.GetExecutorRunningBySessionID(ctx, sessionID) if (err != nil || running == nil) && session.State != models.TaskSessionStateCancelled && session.State != models.TaskSessionStateFailed { // Executor record is required for non-terminal sessions. For cancelled/failed sessions // the record may already have been cleaned up before the user clicked Resume — allow it. return nil, fmt.Errorf("session is not resumable: no executor record") } if err := validateSessionWorktrees(session); err != nil { return nil, err } // Completed sessions cannot be restarted — they require a new session. // Failed and cancelled sessions keep the resume token so the relaunched // agent continues the previous conversation (via ACP session/load for // native-resume agents, or --resume on CLI). Users who want a fresh start // after a failure can invoke RecoverSession with action="fresh_start". if session.State == models.TaskSessionStateCompleted { return nil, fmt.Errorf("session is completed and cannot be resumed; create a new session instead") } // Bury any open turns from the previous run before relaunching. Without // this, startTurnForSession adopts the orphan on the next prompt and the // UI's running timer counts from the orphan's started_at — which can be // hours or days ago. Zero-duration completion keeps analytics honest about // the dead window. A failure here shouldn't block the resume; the next // completeTurnForSession sweep will mop up. // // Drop the activeTurns cache entry first, mirroring completeTurnForSession. // Otherwise a stale entry would let getActiveTurnID return the now-abandoned // turn ID without re-reading the DB, tagging new messages to a closed turn. if s.turnService != nil { s.activeTurns.Delete(sessionID) if err := s.turnService.AbandonOpenTurns(ctx, sessionID); err != nil { s.logger.Warn("failed to abandon orphan turns on resume; continuing", zap.String("session_id", sessionID), zap.Error(err)) } } // Use context.WithoutCancel to prevent WebSocket request timeout from canceling the resume. // Session resume can take time and shouldn't be tied to the WS request lifecycle. resumeCtx := context.WithoutCancel(ctx) execution, err := s.executor.ResumeSession(resumeCtx, session, true) if err != nil { // If the execution is already running (duplicate resume request), return it as success. if errors.Is(err, executor.ErrExecutionAlreadyRunning) { if existing, ok := s.executor.GetExecutionBySession(sessionID); ok && existing != nil { existing.SessionState = v1.TaskSessionState(session.State) return existing, nil } } // Task was archived while the resume was in flight — return the error // without mutating task/session state (archive already handled cleanup). // Check both the sentinel (early rejection) and re-read the task to catch // the race where archive completed after the executor's archived check. if errors.Is(err, executor.ErrTaskArchived) { return nil, err } if task, taskErr := s.repo.GetTask(resumeCtx, taskID); taskErr == nil && task != nil && task.ArchivedAt != nil { return nil, executor.ErrTaskArchived } // Use resumeCtx (WithoutCancel) for the failure-recording writes too — // if the caller's ctx was already cancelled (e.g. WS client navigated // away), the SessionStateFailed and TaskStateFailed updates would // themselves fail with "context canceled" and leave the task stuck // looking "running" forever. s.updateTaskSessionState(resumeCtx, taskID, sessionID, models.TaskSessionStateFailed, err.Error(), false, session) if stateErr := s.taskRepo.UpdateTaskState(resumeCtx, taskID, v1.TaskStateFailed); stateErr != nil { s.logger.Warn("failed to update task state to FAILED after resume error", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(stateErr)) } return nil, err } // Preserve persisted task/session state; resume should not mutate state/columns. execution.SessionState = v1.TaskSessionState(session.State) // Backfill the initial user message when a prior failed launch never got // to recordInitialMessage. Without this, the resume can succeed and the // agent starts replying, but the chat shows agent output with no user // prompt above it. // // We use task.Description (the raw user input) rather than the // workflow-effective prompt produced by applyWorkflowAndPlanMode. The // effective prompt may carry a plan-mode prefix or be templated through a // workflow step, but reconstructing the exact prompt the original launch // sent to the agent is brittle (workflow state may have advanced since). // Surfacing the raw description is intentionally conservative: it shows // what the user actually typed, which is what they expect to see in chat. if task, taskErr := s.repo.GetTask(resumeCtx, taskID); taskErr != nil { s.logger.Warn("resume: failed to load task for initial message backfill", zap.String("task_id", taskID), zap.Error(taskErr)) } else if task != nil { s.backfillInitialUserMessageIfMissing(resumeCtx, taskID, sessionID, task.Description) } s.logger.Debug("task session resumed and ready for input", zap.String("task_id", taskID), zap.String("session_id", sessionID)) go s.ensureSessionPRWatch(context.Background(), taskID, execution.SessionID, execution.WorktreeBranch) return execution, nil } // StartSessionForWorkflowStep starts an existing session with a workflow step's prompt configuration. // If the session is not running, it will be resumed first. Then a prompt is sent using the // step's prompt_prefix, prompt_suffix, and plan_mode settings combined with the task description. func (s *Service) StartSessionForWorkflowStep(ctx context.Context, taskID, sessionID, workflowStepID string) error { s.logger.Debug("starting session for workflow step", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("workflow_step_id", workflowStepID)) if workflowStepID == "" { return fmt.Errorf("workflow_step_id is required") } if s.workflowStepGetter == nil { return fmt.Errorf("workflow step getter not configured") } step, err := s.workflowStepGetter.GetStep(ctx, workflowStepID) if err != nil { return fmt.Errorf("failed to get workflow step: %w", err) } session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return fmt.Errorf("failed to get session: %w", err) } if session.TaskID != taskID { return fmt.Errorf("session does not belong to task") } dbTask, err := s.repo.GetTask(ctx, taskID) if err != nil { return fmt.Errorf("failed to get task: %w", err) } if session.ReviewStatus == models.ReviewStatusPending { return fmt.Errorf("session is pending approval - use Approve button to proceed or send a message to request changes") } s.advanceTaskWorkflowStep(ctx, dbTask, workflowStepID, session) effectivePrompt := s.buildWorkflowPrompt(dbTask.Description, step, taskID, sessionID) if err := s.ensureSessionRunning(ctx, sessionID, session); err != nil { return err } stepPlanMode := step.HasOnEnterAction(wfmodels.OnEnterEnablePlanMode) _, err = s.PromptTask(ctx, taskID, sessionID, effectivePrompt, "", stepPlanMode, nil, false) if err != nil { return fmt.Errorf("failed to prompt session: %w", err) } s.logger.Info("session started for workflow step", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("workflow_step_id", workflowStepID), zap.String("step_name", step.Name), zap.Bool("plan_mode", stepPlanMode)) return nil } // advanceTaskWorkflowStep updates the task's workflow step and clears session review status if the step changed. func (s *Service) advanceTaskWorkflowStep(ctx context.Context, task *models.Task, workflowStepID string, session *models.TaskSession) { if task.WorkflowStepID == workflowStepID { return } task.WorkflowStepID = workflowStepID task.UpdatedAt = time.Now().UTC() if err := s.repo.UpdateTask(ctx, task); err != nil { s.logger.Warn("failed to update task workflow step", zap.String("task_id", task.ID), zap.String("workflow_step_id", workflowStepID), zap.Error(err)) } if session.ReviewStatus != models.ReviewStatusNone { if err := s.repo.UpdateSessionReviewStatus(ctx, session.ID, ""); err != nil { s.logger.Warn("failed to clear session review status", zap.String("session_id", session.ID), zap.Error(err)) } } } // ensureSessionRunning resumes the session if the agent is not actually running. // After lazy recovery, a session may be in WAITING_FOR_INPUT with no agent process; // this function detects that case and triggers a resume. func (s *Service) ensureSessionRunning(ctx context.Context, sessionID string, session *models.TaskSession) error { // Check if agent is genuinely running (in-memory execution store, not just DB state) if exec, ok := s.executor.GetExecutionBySession(sessionID); ok && exec != nil { return nil } s.logger.Debug("agent not running for session, attempting resume", zap.String("session_id", sessionID), zap.String("session_state", string(session.State))) // If the session is in CREATED state with an existing workspace (executors_running // row exists), the workspace was prepared but the agent was never started. Use // LaunchPreparedSession which routes to startAgentOnExistingWorkspace to reuse // the workspace rather than ResumeSession which tries a full LaunchAgent and // conflicts with the existing execution. if session.State == models.TaskSessionStateCreated { hasRunning, _ := s.repo.HasExecutorRunningRow(ctx, sessionID) if hasRunning { return s.startAgentOnPreparedWorkspace(ctx, sessionID, session) } } running, err := s.repo.GetExecutorRunningBySessionID(ctx, sessionID) if err != nil || running == nil { return fmt.Errorf("session is not resumable: no executor record (state: %s)", session.State) } if err := validateSessionWorktrees(session); err != nil { return err } // Use context.WithoutCancel to prevent WebSocket request timeout from canceling the resume. // The lifecycle layer publishes events.AgentBootReady (handled by handleAgentBootReady) // when the agent's ACP session initializes — that's what unblocks waitForSessionReady, // no flag-tracking needed. resumeCtx := context.WithoutCancel(ctx) if _, err = s.executor.ResumeSession(resumeCtx, session, true); err != nil { if errors.Is(err, executor.ErrExecutionAlreadyRunning) { return nil // Agent is already running, nothing to do } s.updateTaskSessionState(ctx, session.TaskID, sessionID, models.TaskSessionStateFailed, err.Error(), false, session) if stateErr := s.taskRepo.UpdateTaskState(ctx, session.TaskID, v1.TaskStateFailed); stateErr != nil { s.logger.Warn("failed to update task state to FAILED after session ensure resume error", zap.String("task_id", session.TaskID), zap.String("session_id", sessionID), zap.Error(stateErr)) } return fmt.Errorf("failed to resume session: %w", err) } // ResumeSession launches the agent asynchronously. Wait for it to finish // initializing before returning, so the caller can send a prompt immediately. if err := s.waitForSessionReady(ctx, sessionID); err != nil { return fmt.Errorf("session not ready after resume: %w", err) } s.logger.Debug("session resumed and ready for prompt") return nil } // startAgentOnPreparedWorkspace starts the agent subprocess on a session whose workspace // was prepared (agentctl running) but whose agent process was never started. This avoids // the "session already has an agent running" error from ResumeSession which tries a full // LaunchAgent and conflicts with the existing execution in the lifecycle manager's store. func (s *Service) startAgentOnPreparedWorkspace(ctx context.Context, sessionID string, session *models.TaskSession) error { s.logger.Debug("session has prepared workspace but no agent, starting agent on existing workspace", zap.String("session_id", sessionID)) // Boot ready is published as events.AgentBootReady by the lifecycle layer // and routed to handleAgentBootReady, which flips the session to // WAITING_FOR_INPUT — that's what waitForSessionReady polls for. No flag // tracking required here. launchCtx := context.WithoutCancel(ctx) task, err := s.scheduler.GetTask(launchCtx, session.TaskID) if err != nil { return fmt.Errorf("failed to get task for prepared session: %w", err) } if _, err = s.executor.LaunchPreparedSession(launchCtx, task, sessionID, executor.LaunchOptions{ AgentProfileID: session.AgentProfileID, ExecutorID: session.ExecutorID, StartAgent: true, }); err != nil { return fmt.Errorf("failed to start agent on prepared workspace: %w", err) } if err := s.waitForSessionReady(ctx, sessionID); err != nil { return fmt.Errorf("session not ready after starting agent: %w", err) } s.logger.Debug("agent started on prepared workspace and ready for prompt") return nil } // waitForSessionReady polls the session state until the agent is ready for prompts. func (s *Service) waitForSessionReady(ctx context.Context, sessionID string) error { const ( pollInterval = 500 * time.Millisecond maxWait = 90 * time.Second ) deadline := time.Now().Add(maxWait) for { if time.Now().After(deadline) { return fmt.Errorf("timeout waiting for agent to become ready") } select { case <-ctx.Done(): return ctx.Err() case <-time.After(pollInterval): } sess, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return fmt.Errorf("failed to check session state: %w", err) } switch sess.State { case models.TaskSessionStateWaitingForInput: return nil case models.TaskSessionStateFailed: errMsg := sess.ErrorMessage if errMsg == "" { errMsg = "session failed during startup" } return fmt.Errorf("session failed: %s", errMsg) case models.TaskSessionStateCancelled, models.TaskSessionStateCompleted: return fmt.Errorf("session in unexpected state: %s", sess.State) } } } // GetTaskSessionStatus returns the status of a task session including whether it's resumable func (s *Service) GetTaskSessionStatus(ctx context.Context, taskID, sessionID string) (dto.TaskSessionStatusResponse, error) { s.logger.Debug("checking task session status", zap.String("task_id", taskID), zap.String("session_id", sessionID)) resp := dto.TaskSessionStatusResponse{ SessionID: sessionID, TaskID: taskID, } // 1. Load session from database session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { resp.Error = "session not found" return resp, nil } if session.TaskID != taskID { resp.Error = "session does not belong to task" return resp, nil } resp.State = string(session.State) resp.UpdatedAt = session.UpdatedAt.UTC().Format(time.RFC3339Nano) resp.AgentProfileID = session.AgentProfileID s.populateExecutorStatusInfo(ctx, session, &resp) running, runErr := s.repo.GetExecutorRunningBySessionID(ctx, sessionID) resumeToken := "" if runErr == nil && running != nil { resumeToken = running.ResumeToken resp.ACPSessionID = running.ResumeToken resp.Runtime = running.Runtime if running.Resumable { resp.IsResumable = true } s.applyRemoteRuntimeStatus(ctx, sessionID, &resp) } if shouldHealStuckStartingSession(session, running) { s.logger.Info("healing stale STARTING session state from ready runtime status", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("agent_execution_id", running.AgentExecutionID)) s.setSessionWaitingForInput(ctx, taskID, sessionID) refreshedSession, refreshErr := s.repo.GetTaskSession(ctx, sessionID) if refreshErr == nil && refreshedSession != nil { session = refreshedSession resp.State = string(session.State) if !session.UpdatedAt.IsZero() { resp.UpdatedAt = session.UpdatedAt.UTC().Format(time.RFC3339Nano) } } } // Extract worktree info populateWorktreeInfo(session, &resp) s.populateEnvironmentWorkspaceInfo(ctx, session, &resp) // 2. Check if this session's agent is running if exec, ok := s.executor.GetExecutionBySession(sessionID); ok && exec != nil { resp.IsAgentRunning = true resp.NeedsResume = false return resp, nil } // 3. Session can be resumed if it has a resume token if resumeToken != "" { // Auto-resume FAILED sessions when the runtime is resumable: PR #670 made // terminal-state resume safe (cleanup + retry), so recover transparently // before surfacing the error. Frontend falls back to restore_workspace if // the resume itself fails. if session.State == models.TaskSessionStateFailed && running != nil && running.Resumable { out := s.validateResumeEligibility(session, resp) if out.NeedsResume { out.ResumeReason = resumeReasonFailedSessionResumable } return out, nil } // Don't auto-resume other terminal sessions (CANCELLED stays stopped, COMPLETED is done). if !isActiveSessionState(session.State) { resp.IsAgentRunning = false resp.IsResumable = false resp.NeedsResume = false resp.NeedsWorkspaceRestore = canRestoreWorkspace(&resp) return resp, nil } return s.validateResumeEligibility(session, resp), nil } // 4. No resume token — check if session can be started fresh. return evaluateFreshStartResume(session, running, runErr, resp), nil } // evaluateFreshStartResume checks whether a session without a resume token can be // started fresh. Sessions in error-recovery state (non-empty ErrorMessage) are marked // resumable but not auto-resumed, so the user sees the error and can choose via action buttons. func evaluateFreshStartResume(session *models.TaskSession, running *models.ExecutorRunning, runErr error, resp dto.TaskSessionStatusResponse) dto.TaskSessionStatusResponse { if runErr == nil && running != nil && isActiveSessionState(session.State) { if isErrorRecoveryState(session) { resp.IsAgentRunning = false resp.IsResumable = true resp.NeedsResume = false resp.ResumeReason = resumeReasonErrorRecovery return resp } resp.IsAgentRunning = false resp.IsResumable = true resp.NeedsResume = true resp.ResumeReason = "agent_not_running_fresh_start" return resp } resp.IsAgentRunning = false resp.IsResumable = false resp.NeedsResume = false resp.NeedsWorkspaceRestore = canRestoreWorkspace(&resp) return resp } func (s *Service) populateExecutorStatusInfo(ctx context.Context, session *models.TaskSession, resp *dto.TaskSessionStatusResponse) { if session == nil || resp == nil { return } resp.ExecutorID = session.ExecutorID if session.ExecutorID == "" { return } execModel, err := s.repo.GetExecutor(ctx, session.ExecutorID) if err != nil || execModel == nil { return } resp.ExecutorType = string(execModel.Type) resp.ExecutorName = execModel.Name resp.IsRemoteExecutor = models.IsRemoteExecutorType(execModel.Type) } func (s *Service) applyRemoteRuntimeStatus(ctx context.Context, sessionID string, resp *dto.TaskSessionStatusResponse) { if s.agentManager == nil || resp == nil || !resp.IsRemoteExecutor { return } status, err := s.agentManager.GetRemoteRuntimeStatusBySession(ctx, sessionID) if err != nil || status == nil { return } if status.RuntimeName != "" { resp.Runtime = status.RuntimeName } resp.RemoteState = status.State resp.RemoteName = status.RemoteName if status.ErrorMessage != "" { resp.RemoteStatusErr = status.ErrorMessage } if status.CreatedAt != nil && !status.CreatedAt.IsZero() { resp.RemoteCreatedAt = status.CreatedAt.UTC().Format(time.RFC3339) } if !status.LastCheckedAt.IsZero() { resp.RemoteCheckedAt = status.LastCheckedAt.UTC().Format(time.RFC3339) } } // populateWorktreeInfo copies worktree path and branch into the response if present. func canRestoreWorkspace(resp *dto.TaskSessionStatusResponse) bool { return resp != nil && resp.WorktreePath != nil && *resp.WorktreePath != "" } func populateWorktreeInfo(session *models.TaskSession, resp *dto.TaskSessionStatusResponse) { if len(session.Worktrees) == 0 { return } wt := session.Worktrees[0] if wt.WorktreePath != "" { resp.WorktreePath = &wt.WorktreePath } if wt.WorktreeBranch != "" { resp.WorktreeBranch = &wt.WorktreeBranch } } func (s *Service) populateEnvironmentWorkspaceInfo(ctx context.Context, session *models.TaskSession, resp *dto.TaskSessionStatusResponse) { if hasWorktreeStatus(resp) { return } env, err := s.repo.GetTaskEnvironmentByTaskID(ctx, session.TaskID) if err != nil || env == nil { return } if session.TaskEnvironmentID != "" && env.ID != session.TaskEnvironmentID { return } if resp.WorktreePath == nil && env.WorktreePath != "" { resp.WorktreePath = &env.WorktreePath } if resp.WorktreeBranch == nil && env.WorktreeBranch != "" { resp.WorktreeBranch = &env.WorktreeBranch } } func hasWorktreeStatus(resp *dto.TaskSessionStatusResponse) bool { return resp != nil && resp.WorktreePath != nil && *resp.WorktreePath != "" && resp.WorktreeBranch != nil && *resp.WorktreeBranch != "" } // isActiveSessionState returns true for session states where lazy resume makes sense. func isActiveSessionState(state models.TaskSessionState) bool { switch state { case models.TaskSessionStateWaitingForInput, models.TaskSessionStateStarting, models.TaskSessionStateRunning: return true } return false } // isErrorRecoveryState returns true when a session is in WAITING_FOR_INPUT with // a non-empty ErrorMessage, indicating it was set by handleRecoverableFailure. func isErrorRecoveryState(session *models.TaskSession) bool { return session != nil && session.State == models.TaskSessionStateWaitingForInput && session.ErrorMessage != "" } func shouldHealStuckStartingSession(session *models.TaskSession, running *models.ExecutorRunning) bool { if session == nil || running == nil { return false } if session.State != models.TaskSessionStateStarting { return false } if running.Status != "ready" { return false } // Pre-refactor this also checked session.AgentExecutionID vs running.AgentExecutionID // to skip healing on a divergent row. With the executors_running table now the // single source of truth, that comparison is structurally always equal — drop it. return true } // validateResumeEligibility performs final checks before marking a session as resumable. func (s *Service) validateResumeEligibility(session *models.TaskSession, resp dto.TaskSessionStatusResponse) dto.TaskSessionStatusResponse { if session.AgentProfileID == "" { resp.Error = "session missing agent profile" resp.IsResumable = false return resp } // Check if worktree exists (if one was used) if len(session.Worktrees) > 0 && session.Worktrees[0].WorktreePath != "" { if _, err := os.Stat(session.Worktrees[0].WorktreePath); err != nil { resp.Error = "worktree not found" resp.IsResumable = false return resp } } // Don't auto-resume sessions in error-recovery state. if isErrorRecoveryState(session) { resp.IsAgentRunning = false resp.IsResumable = true resp.NeedsResume = false resp.ResumeReason = resumeReasonErrorRecovery return resp } resp.IsAgentRunning = false resp.NeedsResume = true resp.ResumeReason = "agent_not_running" return resp } // StopTask stops agent execution for a task (stops all active sessions for the task) func (s *Service) StopTask(ctx context.Context, taskID string, reason string, force bool) error { s.logger.Info("stopping task execution", zap.String("task_id", taskID), zap.String("reason", reason), zap.Bool("force", force)) // Stop all agents for this task if err := s.executor.StopByTaskID(ctx, taskID, reason, force); err != nil { return err } // Move task to REVIEW state for user review if err := s.taskRepo.UpdateTaskState(ctx, taskID, v1.TaskStateReview); err != nil { s.logger.Error("failed to update task state to REVIEW after stop", zap.String("task_id", taskID), zap.Error(err)) // Don't return error - the stop was successful } else { s.logger.Info("task moved to REVIEW state after stop", zap.String("task_id", taskID)) } return nil } // CancelTaskExecution stops active sessions for a task without mutating task state. // It is used by office tree controls where pause/cancel state transitions are // handled by the office service itself. func (s *Service) CancelTaskExecution(ctx context.Context, taskID string, reason string, force bool) error { s.logger.Info("cancelling task execution", zap.String("task_id", taskID), zap.String("reason", reason), zap.Bool("force", force)) return s.executor.StopByTaskID(ctx, taskID, reason, force) } // StopSession stops agent execution for a specific session func (s *Service) StopSession(ctx context.Context, sessionID string, reason string, force bool) error { s.logger.Info("stopping session execution", zap.String("session_id", sessionID), zap.String("reason", reason), zap.Bool("force", force)) return s.executor.Stop(ctx, sessionID, reason, force) } // DeleteSession deletes a session that is not currently running. func (s *Service) DeleteSession(ctx context.Context, sessionID string) error { session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return fmt.Errorf("session not found: %w", err) } // Prevent deleting active sessions switch session.State { case models.TaskSessionStateRunning, models.TaskSessionStateStarting: return fmt.Errorf("cannot delete session in %s state — stop it first", session.State) } taskID := session.TaskID wasPrimary := session.IsPrimary s.logger.Info("deleting session", zap.String("session_id", sessionID), zap.String("task_id", taskID), zap.String("state", string(session.State)), zap.Bool("was_primary", wasPrimary)) if err := s.repo.DeleteTaskSession(ctx, sessionID); err != nil { return fmt.Errorf("failed to delete session: %w", err) } // Drop the in-memory git snapshot throttle entry — the session will // never receive another git event, so its cache slot is dead weight. if s.gitSnapshotCache != nil { s.gitSnapshotCache.forget(sessionID) } // Same reasoning for the push-detection tracker. Multi-repo sessions // accumulate one entry per repo; pushTrackerForget walks them all. s.pushTrackerForget(sessionID) // Auto-promote another session if we deleted the primary if wasPrimary { s.promoteNextPrimaryAfterRemoval(ctx, taskID, sessionID) } return nil } // promoteNextPrimaryAfterRemoval picks the best remaining session as primary // after a session is deleted. Prefers RUNNING > active > any remaining. func (s *Service) promoteNextPrimaryAfterRemoval(ctx context.Context, taskID, deletedSessionID string) { sessions, err := s.repo.ListTaskSessions(ctx, taskID) if err != nil || len(sessions) == 0 { return } var candidate string for _, sess := range sessions { if sess.ID == deletedSessionID { continue } if sess.State == models.TaskSessionStateRunning { candidate = sess.ID break } if candidate == "" { candidate = sess.ID } else if isActiveSessionState(sess.State) { // Prefer active over terminal candidate = sess.ID } } if candidate != "" { if err := s.SetPrimarySession(ctx, candidate); err != nil { s.logger.Warn("failed to auto-promote primary after delete", zap.String("task_id", taskID), zap.String("candidate", candidate), zap.Error(err)) } } } // SetPrimarySession marks a session as the primary session for its task // and broadcasts a task.updated event so the frontend reflects the change. func (s *Service) SetPrimarySession(ctx context.Context, sessionID string) error { if err := s.repo.SetSessionPrimary(ctx, sessionID); err != nil { return fmt.Errorf("failed to set session as primary: %w", err) } // Broadcast task.updated so frontend updates the primary star indicator. // The task service's publisher loads primary-session info from the DB, // which already reflects the SetSessionPrimary write above. session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { s.logger.Warn("failed to fetch session after setting primary", zap.Error(err)) return nil } task, err := s.repo.GetTask(ctx, session.TaskID) if err != nil { s.logger.Warn("failed to fetch task after setting primary", zap.Error(err)) return nil } s.publishTaskUpdated(ctx, task) return nil } // StopExecution stops agent execution for a specific execution ID. func (s *Service) StopExecution(ctx context.Context, executionID string, reason string, force bool) error { s.logger.Info("stopping execution", zap.String("execution_id", executionID), zap.String("reason", reason), zap.Bool("force", force)) return s.executor.StopExecution(ctx, executionID, reason, force) } // CaptureArchiveSnapshot captures git state (commits, cumulative diff) for a session before archiving. // This preserves the final git state for historical purposes. func (s *Service) CaptureArchiveSnapshot(ctx context.Context, sessionID string) error { s.logger.Info("capturing archive snapshot", zap.String("session_id", sessionID)) baseCommit, baseBranch, err := s.resolveArchiveBaseCommitAndBranch(ctx, sessionID) if err != nil { return err } // Skip only if we have neither baseCommit nor baseBranch for merge-base calculation if baseCommit == "" && baseBranch == "" { s.logger.Debug("no base_commit or base_branch available, skipping archive snapshot capture", zap.String("session_id", sessionID)) return nil } // Capture commits - baseBranch can be used for merge-base even if baseCommit is empty if !s.captureArchiveCommits(ctx, sessionID, baseCommit, baseBranch) { // Agent not running, skip diff capture as well return nil } // Diff capture requires baseCommit if baseCommit == "" { s.logger.Debug("no base_commit available, skipping archive diff capture", zap.String("session_id", sessionID)) return nil } s.captureArchiveDiff(ctx, sessionID, baseCommit) return nil } // resolveArchiveBaseCommitAndBranch retrieves the base commit and branch for archive snapshot capture. // It first checks the session's stored values, falling back to git status if empty. func (s *Service) resolveArchiveBaseCommitAndBranch(ctx context.Context, sessionID string) (string, string, error) { session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return "", "", fmt.Errorf("failed to get session: %w", err) } baseCommit := session.BaseCommitSHA baseBranch := session.BaseBranch if baseCommit != "" { return baseCommit, baseBranch, nil } // Fallback: try to get base commit from git status for legacy sessions status, err := s.agentManager.GetGitStatus(ctx, sessionID) if err != nil { s.logger.Debug("failed to get git status for base commit fallback", zap.String("session_id", sessionID), zap.Error(err)) return "", baseBranch, nil } if status != nil && status.BaseCommit != "" { s.logger.Debug("using git status base commit as fallback for archive", zap.String("session_id", sessionID), zap.String("base_commit", status.BaseCommit)) return status.BaseCommit, baseBranch, nil } return "", baseBranch, nil } // captureArchiveCommits fetches and saves commits from baseCommit to HEAD. // If targetBranch is provided, uses dynamic merge-base for accurate filtering. // Returns false if the agent is not running (caller should skip remaining capture). func (s *Service) captureArchiveCommits(ctx context.Context, sessionID, baseCommit, targetBranch string) bool { logResult, err := s.agentManager.GetGitLog(ctx, sessionID, baseCommit, 0, targetBranch) // 0 = no limit if err != nil { s.logger.Warn("failed to capture git log for archive", zap.String("session_id", sessionID), zap.Error(err)) return true // Continue with diff capture even if log fails } if logResult == nil { s.logger.Debug("agent not running, skipping archive snapshot capture", zap.String("session_id", sessionID)) return false } if logResult.Success && len(logResult.Commits) > 0 { s.saveArchiveCommits(ctx, sessionID, logResult.Commits) } return true } // captureGitStatusSnapshot fetches the current (cached) git status from agentctl // and saves it as a DB snapshot. Called when a session's execution completes so // the status is available when clients subscribe later. func (s *Service) captureGitStatusSnapshot(ctx context.Context, sessionID string) { _, _ = s.saveGitStatusSnapshot(ctx, sessionID, false) } // captureGitStatusSnapshotWithRetry attempts a fresh capture with up to 3 // retries at 1-second intervals if the first attempt returns stale 0/0 data // (caused by git lock contention between concurrent worktrees). Returns // immediately without retrying when no execution exists for the session // (returns nil,nil) or the agent genuinely has no file changes. func (s *Service) captureGitStatusSnapshotWithRetry(ctx context.Context, sessionID string) { for attempt := 0; attempt < 3; attempt++ { if attempt > 0 { time.Sleep(time.Second) } wrote, noExec := s.saveGitStatusSnapshot(ctx, sessionID, true) if noExec { return // No execution exists — retrying won't help } if wrote { return // Successfully wrote a snapshot (may be 0/0 for no-change turns, that's fine) } // saveGitStatusSnapshot returned false without noExec — means fresh // returned 0/0 and was skipped due to possible lock contention. Retry. } } // saveGitStatusSnapshot is the shared implementation for snapshot capture. // When fresh is true, it bypasses the workspace tracker's poll cache. // Returns (wrote, noExecution): wrote=true if a snapshot was persisted, // noExecution=true if the session has no active execution (nil status). func (s *Service) saveGitStatusSnapshot(ctx context.Context, sessionID string, fresh bool) (wrote, noExecution bool) { var status *client.GitStatusResult var err error if fresh { status, err = s.agentManager.GetGitStatusFresh(ctx, sessionID) } else { status, err = s.agentManager.GetGitStatus(ctx, sessionID) } if err != nil { s.logger.Debug("failed to capture git status snapshot", zap.String("session_id", sessionID), zap.Error(err)) return false, false } if status == nil { return false, true // No execution — caller should not retry } if !status.Success { return false, false } // When a fresh query returns zero additions AND zero deletions, the result // may be stale due to git lock contention between concurrent worktrees // (merge-base computation fails transiently). Don't overwrite a potentially // better live_monitor snapshot that already has the correct non-zero values. if fresh && status.BranchAdditions == 0 && status.BranchDeletions == 0 { return false, false } metadata := map[string]interface{}{ "timestamp": status.Timestamp, "modified": status.Modified, "added": status.Added, "deleted": status.Deleted, "untracked": status.Untracked, "renamed": status.Renamed, "branch_additions": status.BranchAdditions, "branch_deletions": status.BranchDeletions, } if err := s.repo.CreateGitSnapshot(ctx, &models.GitSnapshot{ SessionID: sessionID, SnapshotType: models.SnapshotTypeStatusUpdate, Branch: status.Branch, RemoteBranch: status.RemoteBranch, HeadCommit: status.HeadCommit, BaseCommit: status.BaseCommit, Ahead: status.Ahead, Behind: status.Behind, Files: status.Files, TriggeredBy: "agent_completed", Metadata: metadata, }); err != nil { s.logger.Warn("failed to save git status snapshot", zap.String("session_id", sessionID), zap.Error(err)) return false, false } // Remove stale live_monitor snapshots so the authoritative agent_completed // snapshot is always returned by GetLatestGitSnapshot. Without this, a // live_monitor poll that raced with agent completion could persist a // snapshot with a later timestamp but stale data. if err := s.repo.DeleteLiveMonitorSnapshots(ctx, sessionID); err != nil { s.logger.Debug("failed to clean up live monitor snapshots", zap.String("session_id", sessionID), zap.Error(err)) } s.logger.Debug("saved git status snapshot", zap.String("session_id", sessionID), zap.String("branch", status.Branch), zap.Bool("fresh", fresh)) return true, false } // captureArchiveDiff fetches and saves the cumulative diff from baseCommit to the working tree // (including uncommitted/unstaged changes). func (s *Service) captureArchiveDiff(ctx context.Context, sessionID, baseCommit string) { diffResult, err := s.agentManager.GetCumulativeDiff(ctx, sessionID, baseCommit) if err != nil { s.logger.Warn("failed to capture cumulative diff for archive", zap.String("session_id", sessionID), zap.Error(err)) return } if diffResult == nil || !diffResult.Success { return } if err := s.repo.CreateGitSnapshot(ctx, &models.GitSnapshot{ SessionID: sessionID, SnapshotType: models.SnapshotTypeArchive, HeadCommit: diffResult.HeadCommit, BaseCommit: diffResult.BaseCommit, Files: diffResult.Files, }); err != nil { s.logger.Warn("failed to save archive snapshot", zap.String("session_id", sessionID), zap.Error(err)) return } s.logger.Debug("saved archive snapshot", zap.String("session_id", sessionID), zap.String("head_commit", diffResult.HeadCommit), zap.Int("total_commits", diffResult.TotalCommits)) } // parseCommitTime parses a commit timestamp from git log output. // Returns UTC time to ensure consistent timestamps across environments. func parseCommitTime(s string) time.Time { t, err := time.Parse(time.RFC3339, s) if err != nil { return time.Now().UTC() } return t.UTC() } // saveArchiveCommits persists commits to the database for archive purposes. func (s *Service) saveArchiveCommits(ctx context.Context, sessionID string, commits []*client.GitCommitInfo) { for _, commit := range commits { if err := s.repo.CreateSessionCommit(ctx, &models.SessionCommit{ SessionID: sessionID, CommitSHA: commit.CommitSHA, ParentSHA: commit.ParentSHA, AuthorName: commit.AuthorName, AuthorEmail: commit.AuthorEmail, CommitMessage: commit.CommitMessage, CommittedAt: parseCommitTime(commit.CommittedAt), FilesChanged: commit.FilesChanged, Insertions: commit.Insertions, Deletions: commit.Deletions, }); err != nil { s.logger.Warn("failed to save commit for archive", zap.String("session_id", sessionID), zap.String("commit_sha", commit.CommitSHA), zap.Error(err)) } } s.logger.Debug("saved archive commits", zap.String("session_id", sessionID), zap.Int("count", len(commits))) } // PromptTask sends a follow-up prompt to a running agent for a task session. // If planMode is true, a plan mode prefix is prepended to the prompt. // Attachments (images) are passed through to the agent if provided. func (s *Service) PromptTask(ctx context.Context, taskID, sessionID string, prompt string, model string, planMode bool, attachments []v1.MessageAttachment, dispatchOnly bool) (*PromptResult, error) { s.logger.Debug("PromptTask called", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Int("prompt_length", len(prompt)), zap.String("requested_model", model), zap.Bool("plan_mode", planMode), zap.Int("attachments_count", len(attachments)), zap.Bool("dispatch_only", dispatchOnly)) if sessionID == "" { return nil, fmt.Errorf("session_id is required") } if s.isSessionResetInProgress(sessionID) { return nil, ErrSessionResetInProgress } // Only allow prompts when the session is ready for input. // Reject when the agent is still starting, already processing, or in a terminal state. session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return nil, fmt.Errorf("failed to get session: %w", err) } if err := s.checkSessionPromptable(taskID, sessionID, session.State); err != nil { return nil, err } // Inject config context for config-mode sessions (dedicated settings chat, not plan mode) effectivePrompt := prompt if cm, ok := session.Metadata["config_mode"].(bool); ok && cm { effectivePrompt = sysprompt.InjectConfigContext(sessionID, prompt) } // Inject plan mode prefix for follow-up messages in plan mode sessions. if planMode { effectivePrompt = sysprompt.InjectPlanMode(effectivePrompt) } // Ensure the agent process is actually running. After a lazy backend restart, // the session may be in WAITING_FOR_INPUT but no agent process exists yet. if err := s.ensureSessionRunning(ctx, sessionID, session); err != nil { return nil, fmt.Errorf("failed to ensure session is running: %w", err) } // Reload session after ensureSessionRunning. If a resume happened, ResumeSession // updated the session's AgentExecutionID via persistResumeState — but only on the // pointer it received. If anything along the way swapped the pointer or the // caller's struct is otherwise stale (e.g. a concurrent write), executor.Prompt // would call PromptAgent with the OLD execution ID and get ErrExecutionNotFound. // Re-reading from the DB after ensureSessionRunning guarantees we use the // freshly-persisted AgentExecutionID. if reloaded, err := s.repo.GetTaskSession(ctx, sessionID); err == nil && reloaded != nil { session = reloaded // Re-apply transforms in case metadata changed during ensureSessionRunning. effectivePrompt = prompt if cm, ok := session.Metadata["config_mode"].(bool); ok && cm { effectivePrompt = sysprompt.InjectConfigContext(sessionID, prompt) } if planMode { effectivePrompt = sysprompt.InjectPlanMode(effectivePrompt) } } // Check if model switching is requested if result, switched, err := s.trySwitchModel(ctx, taskID, sessionID, model, effectivePrompt, session); switched || err != nil { return result, err } previousSessionState := session.State // Cache the raw prompt so a transient-provider-error (529) retry can // re-drive this turn after backoff without the caller's context. Stores // the pre-injection prompt; PromptTask re-applies config/plan transforms. s.rememberTurnPrompt(sessionID, prompt, model, planMode, attachments) s.setSessionRunning(ctx, taskID, sessionID, session) s.startTurnForSession(ctx, sessionID) // Use context.WithoutCancel to prevent WebSocket request timeout from canceling the prompt. // Prompts can take a long time (minutes) while the WS request may timeout in 15 seconds. // We still want to log and respond, but the prompt should continue regardless. promptCtx := context.WithoutCancel(ctx) result, err := s.executor.Prompt(promptCtx, taskID, sessionID, effectivePrompt, attachments, dispatchOnly, session) if err != nil { return nil, s.handlePromptError(ctx, taskID, sessionID, previousSessionState, err) } return &PromptResult{ StopReason: result.StopReason, AgentMessage: result.AgentMessage, }, nil } // checkSessionPromptable returns nil when the session's state accepts a new // prompt. RUNNING is rejected with ErrAgentPromptInProgress; any other // non-acceptable state (STARTING / CREATED / FAILED / CANCELLED) is rejected // with ErrSessionNotPromptable so callers can distinguish "wait for the // current turn" from "this session is not in a state where it can take a // prompt". IDLE is acceptable: office sessions intentionally park in IDLE // between turns (agent torn down, ACP session preserved) and the next prompt // resumes them — see ensureSessionRunning. func (s *Service) checkSessionPromptable(taskID, sessionID string, state models.TaskSessionState) error { switch state { case models.TaskSessionStateWaitingForInput, models.TaskSessionStateCompleted, models.TaskSessionStateIdle: return nil case models.TaskSessionStateRunning: s.logger.Warn("rejected prompt while agent is already running", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("session_state", string(state))) return fmt.Errorf("%w, please wait for completion", ErrAgentPromptInProgress) default: s.logger.Warn("rejected prompt: session not ready for input", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("session_state", string(state))) return fmt.Errorf("%w: session is in %s state", ErrSessionNotPromptable, state) } } // handlePromptError reverts session state, logs the failure, transitions the // task to REVIEW for non-transient errors, and completes the in-flight turn. // Returns the (possibly remapped) error for the caller to surface. func (s *Service) handlePromptError(ctx context.Context, taskID, sessionID string, previousSessionState models.TaskSessionState, err error) error { if isTransientPromptError(err) && s.isSessionResetInProgress(sessionID) { s.logger.Warn("prompt deferred while session reset is in progress; retry expected", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(err)) err = ErrSessionResetInProgress } else { s.logger.Error("prompt failed", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(err)) } // Revert session state so it doesn't stay stuck in RUNNING. Route through the // wrapper so WS subscribers are notified — the UI relies on the // session.state_changed broadcast to flip the composer/pause button out of // "Agent is running". The wrapper's terminal-state guard is also correct here: // if a concurrent agent-failure handler moved the session to FAILED we don't // want to overwrite that with previousSessionState. Do NOT pass the preloaded // `session` — the wrapper must re-read the row to see any such concurrent // terminal transition; the stale pre-RUNNING snapshot would defeat the guard. // allowWakeFromWaiting=false — this is a revert away from RUNNING, never a // wake transition; the flag only matters when going WAITING_FOR_INPUT → RUNNING. s.updateTaskSessionState(ctx, taskID, sessionID, previousSessionState, "", false) // ErrCancelEscalated means the user cancelled and the lifecycle manager had to // force-unblock a hung agent. Service.CancelAgent owns the cancel reconcile // (session → WAITING_FOR_INPUT, task → REVIEW, cancel message, complete // turn); skip the REVIEW write here so we don't race that path with a // duplicate update. // A transient provider error (529 Overloaded) is owned by the async // retry-with-backoff path (handleTransientFailure), which keeps the task // in progress while it retries — so don't flap it to REVIEW here. if !isTransientPromptError(err) && !errors.Is(err, lifecycle.ErrCancelEscalated) && !routingerr.IsTransientProviderError(err.Error()) { _ = s.taskRepo.UpdateTaskState(ctx, taskID, v1.TaskStateReview) } s.completeTurnForSession(ctx, sessionID) return err } // trySwitchModel handles model switching for a prompt. Returns (result, true, nil) if a switch was // performed, (nil, false, err) on error, or (nil, false, nil) if no switch was needed. func (s *Service) trySwitchModel(ctx context.Context, taskID, sessionID, model, effectivePrompt string, session *models.TaskSession) (*PromptResult, bool, error) { if model == "" { return nil, false, nil } var currentModel string if session.AgentProfileSnapshot != nil { if m, ok := session.AgentProfileSnapshot["model"].(string); ok { currentModel = m } } if currentModel == model { return nil, false, nil } s.logger.Info("switching model", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("from", currentModel), zap.String("to", model)) switchCtx := context.WithoutCancel(ctx) switchResult, err := s.executor.SwitchModel(switchCtx, taskID, sessionID, model, effectivePrompt) if err != nil { return nil, true, fmt.Errorf("model switch failed: %w", err) } if switchResult.StopReason == "model_switched_in_place" { // Agent is still running with the new model — let PromptTask send the prompt normally. // Invalidate the message creator's model cache so the next message picks up the new model. if s.messageCreator != nil { s.messageCreator.InvalidateModelCache(sessionID) } return nil, false, nil } s.startTurnForSession(ctx, sessionID) s.setSessionRunning(ctx, taskID, sessionID, session) return &PromptResult{ StopReason: switchResult.StopReason, AgentMessage: switchResult.AgentMessage, }, true, nil } // RespondToPermission sends a response to a permission request for a session func (s *Service) RespondToPermission(ctx context.Context, sessionID, pendingID, optionID string, cancelled, rejected bool) error { s.logger.Debug("responding to permission request", zap.String("session_id", sessionID), zap.String("pending_id", pendingID), zap.String("option_id", optionID), zap.Bool("cancelled", cancelled), zap.Bool("rejected", rejected)) // Respond to the permission via agentctl if err := s.executor.RespondToPermission(ctx, sessionID, pendingID, optionID, cancelled); err != nil { // Permission likely expired — update message so frontend reflects this if s.messageCreator != nil { if updateErr := s.messageCreator.UpdatePermissionMessage(ctx, sessionID, pendingID, models.PermissionStatusExpired); updateErr != nil { s.logger.Warn("failed to mark expired permission message", zap.String("session_id", sessionID), zap.String("pending_id", pendingID), zap.Error(updateErr)) } } return err } // Determine status based on response. cancelled=true means the user dismissed // the dialog; rejected=true means the user explicitly clicked Deny with a // reject option. Both map to "rejected" message status. status := models.PermissionStatusApproved if cancelled || rejected { status = models.PermissionStatusRejected } // Update the permission message with the new status if s.messageCreator != nil { if err := s.messageCreator.UpdatePermissionMessage(ctx, sessionID, pendingID, status); err != nil { s.logger.Warn("failed to update permission message status", zap.String("session_id", sessionID), zap.String("pending_id", pendingID), zap.String("status", string(status)), zap.Error(err)) // Don't fail the whole operation if message update fails } } if !cancelled { session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { s.logger.Warn("failed to load task session after permission response", zap.String("session_id", sessionID), zap.Error(err)) return nil } s.setSessionRunning(ctx, session.TaskID, sessionID, session) } return nil } // DrainQueuedMessage dispatches one queued message for a session that is ready // for input. It is intentionally one-at-a-time: each successful prompt will // complete its own turn and then drain the next entry through handleAgentReady. func (s *Service) DrainQueuedMessage(ctx context.Context, sessionID string) (bool, error) { if sessionID == "" { return false, fmt.Errorf("session_id is required") } session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return false, fmt.Errorf("failed to get session: %w", err) } if err := s.checkSessionPromptable(session.TaskID, sessionID, session.State); err != nil { return false, err } return s.drainQueuedMessageForPromptableSession(ctx, sessionID), nil } func (s *Service) isCancelInFlight(sessionID string) bool { _, ok := s.cancelInFlight.Load(sessionID) return ok } // CancelAgent interrupts the current agent turn without terminating the process, // allowing the user to send a new prompt. // // Idempotent w.r.t. missing executions: if the agent manager reports no live execution // for the session (ErrNoExecutionForSession), the method still reconciles the session's // DB state (transitions to WAITING_FOR_INPUT, records the cancel message, completes the // turn) so the user can unstick a session whose agent subprocess crashed. Other errors // still fail the cancel. func (s *Service) CancelAgent(ctx context.Context, sessionID string) error { s.logger.Debug("cancelling agent turn", zap.String("session_id", sessionID)) // Deduplicate concurrent retries. The UI's cancel button has no in-flight // disable, so impatient users click it multiple times while the agent is // still tearing down the turn (e.g. unwinding a Claude Monitor tool can take // several seconds). Without this guard each click produces a duplicate // "Turn cancelled by user" message and races on turn cleanup — the second // call's getActiveTurnID lazily starts a phantom turn after the first call // already closed the real one. if _, busy := s.cancelInFlight.LoadOrStore(sessionID, struct{}{}); busy { s.logger.Debug("cancel already in flight; skipping duplicate", zap.String("session_id", sessionID)) return nil } defer s.cancelInFlight.Delete(sessionID) // Fetch session for state updates and message creation session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { s.logger.Warn("failed to get session for cancel", zap.String("session_id", sessionID), zap.Error(err)) } // Capture the active turn before cancelling so the cancel message attaches // to the turn the user was actually cancelling. If we waited until after // agentManager.CancelAgent, the agent's complete event could have already // closed the turn, and getActiveTurnID would lazily create a phantom turn // just to host the cancel message. cancelTurnID := s.getActiveTurnID(sessionID) // The agent manager routes the cancel to the right signal: ACP cancel for // regular sessions, Ctrl-C via PTY stdin for passthrough sessions. Service // stays protocol-agnostic; the seam is in lifecycle.Manager.CancelAgentBySessionID. if err := s.agentManager.CancelAgent(ctx, sessionID); err != nil { switch { case errors.Is(err, lifecycle.ErrNoExecutionForSession): // The session was live but there is no execution to cancel — the agent process // crashed, exited, or never re-registered after a backend restart. Log at error // level so operators notice the stuck state; we still reconcile DB state below // so the UI unsticks. s.logger.Error("agent process appears to have crashed: no live execution for session on cancel", zap.String("session_id", sessionID), zap.Error(err)) case errors.Is(err, lifecycle.ErrCancelEscalated): // The agent accepted the ACP cancel but never published a completion event. // The lifecycle manager already unblocked the in-flight prompt and marked the // execution ready; reconcile DB state below so the UI unsticks. s.logger.Warn("agent did not acknowledge cancel; reconciling session state", zap.String("session_id", sessionID), zap.Error(err)) default: return fmt.Errorf("cancel agent: %w", err) } } // Transition session to WAITING_FOR_INPUT so the user can send a new // prompt, and reconcile the task row to REVIEW so the sidebar shows the // green check rather than the yellow "needs input" question icon — a // cancelled turn is treated as finished work the user may want to review. if session != nil { s.updateTaskSessionState(ctx, session.TaskID, sessionID, models.TaskSessionStateWaitingForInput, "", true, session) s.writeTaskReviewStateOnCancel(ctx, session.TaskID) } // Record cancellation in the message history if s.messageCreator != nil && session != nil { metadata := map[string]interface{}{ "cancelled": true, "variant": "warning", } if err := s.messageCreator.CreateSessionMessage( ctx, session.TaskID, "Turn cancelled by user", sessionID, string(v1.MessageTypeStatus), cancelTurnID, metadata, false, ); err != nil { s.logger.Warn("failed to create cancel message", zap.String("session_id", sessionID), zap.Error(err)) } } // Complete the turn since the agent was cancelled. Idempotent w.r.t. a // concurrent agent.complete event having already closed the turn. s.completeTurnForSession(ctx, sessionID) s.logger.Debug("agent turn cancelled", zap.String("session_id", sessionID)) return nil } // CompleteTask explicitly completes a task and stops all its agents func (s *Service) CompleteTask(ctx context.Context, taskID string) error { s.logger.Info("completing task", zap.String("task_id", taskID)) // Stop all agents for this task (which will trigger AgentCompleted events and update session states) if err := s.executor.StopByTaskID(ctx, taskID, "task completed by user", false); err != nil { // If agents are already stopped, just update the task state directly s.logger.Warn("failed to stop agents, updating task state directly", zap.String("task_id", taskID), zap.Error(err)) } // Update task state to COMPLETED if err := s.taskRepo.UpdateTaskState(ctx, taskID, v1.TaskStateCompleted); err != nil { return fmt.Errorf("failed to update task state: %w", err) } s.logger.Info("task marked as COMPLETED", zap.String("task_id", taskID)) return nil } // ResetAgentContext resets the agent's conversation context for a session, // clearing conversation history while preserving the workspace environment. func (s *Service) ResetAgentContext(ctx context.Context, sessionID string) error { session, err := s.repo.GetTaskSession(ctx, sessionID) if err != nil { return fmt.Errorf("session not found: %w", err) } if session.State != models.TaskSessionStateWaitingForInput { return fmt.Errorf("agent must be idle to reset context, current state: %s", session.State) } if hasRunning, hasErr := s.repo.HasExecutorRunningRow(ctx, sessionID); hasErr != nil || !hasRunning { return fmt.Errorf("no active agent execution for session %s", sessionID) } // Set STARTING so frontend disables input and shows restarting state s.updateTaskSessionState(ctx, session.TaskID, sessionID, models.TaskSessionStateStarting, "", false, session) if ok := s.resetAgentContext(ctx, session.TaskID, session, "user_request"); !ok { // Restore WAITING_FOR_INPUT on failure s.setSessionWaitingForInput(ctx, session.TaskID, sessionID) return fmt.Errorf("failed to reset agent context for session %s", sessionID) } // Restore WAITING_FOR_INPUT — handleAgentReady ignores events during reset s.setSessionWaitingForInput(ctx, session.TaskID, sessionID) if s.messageCreator != nil { if err := s.messageCreator.CreateSessionMessage( ctx, session.TaskID, "Context reset — new conversation started", sessionID, string(v1.MessageTypeStatus), s.getActiveTurnID(sessionID), nil, false, ); err != nil { s.logger.Warn("failed to create context reset message", zap.String("session_id", sessionID), zap.Error(err)) } } return nil } // GetQueuedTasks returns tasks in the queue func (s *Service) GetQueuedTasks() []*queue.QueuedTask { return s.queue.List() }