Files
kandev/apps/backend/internal/agent/runtime/lifecycle/session.go
T
João Salavisa dcfec0d23c refactor(backend): classify errors via sentinels instead of substring matches (#1057)
* refactor(backend): classify errors via sentinels instead of substring matches

Introduce package-local sentinel errors in the github, task repo, agent
lifecycle, and office/skills packages. Producers wrap with fmt.Errorf("%w: ...")
so callers can classify via errors.Is/errors.As instead of brittle
strings.Contains(err.Error(), ...) checks that break on library upgrades.

Sentinels added (or relocated to errors.go):
- github: ErrInvalidToken (new); ErrInvalidPRURL, ErrTaskNotFound, ErrSelfApprove
  moved from service.go.
- task/repository/sqlite: ErrTaskNotFound, ErrOfficeSessionRaceConflict.
- lifecycle: ErrAgentAlreadyRunning, ErrAgentReported.
- office/skills: ErrSkillNotFound, ErrSkillFileNotFound.

Consumers updated to errors.Is/errors.As across orchestrator, task/handlers,
github, and office/skills. AssociateExistingPRByURL switches %v -> %w so the
inner parsePRURL error stays in the chain. process_handlers now uses
errors.Is(err, syscall.ECONNREFUSED) and lifecycle.ErrNoExecutionForSession
plus a small isTimeoutError helper backed by errors.As.

A new taskDeleterAdapter in cmd/kandev/turn_adapters.go translates
taskrepo.ErrTaskNotFound to github.ErrTaskNotFound at the wiring boundary,
avoiding a layering violation between the github and task packages.

The one remaining substring check, in CreateTaskSession, is encapsulated
inside the repo and converts the SQLite UNIQUE-violation message into the
typed ErrOfficeSessionRaceConflict sentinel so callers never see the driver
string.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test(backend): add TestErrorsAreClassifiable for refactored packages

Pin the new sentinel-based contract for each refactored package. Each test
exercises the producer paths and asserts errors.Is reaches the sentinel
through the wrap chain, and (where applicable) confirms untyped lookalike
strings no longer classify.

- github: isTaskNotFound, AssociateExistingPRByURL/ErrInvalidPRURL,
  ConfigureToken/ErrInvalidToken (using a noop secret manager).
- task/repository/sqlite: GetTask, DeleteTask, UpdateTaskState wrap
  ErrTaskNotFound.
- task/handlers: isNotFound + isAgentReportedError follow the typed chain.
- orchestrator: each isXError classifies exact + wrapped sentinels, rejects
  untyped lookalikes.
- office/skills: readUserHomeSkillInventoryFile wraps ErrSkillFileNotFound;
  ErrSkillNotFound survives fmt.Errorf("%w", ...).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test(github): drop network-hitting subtest from errors_test

The "ConfigureToken wraps ErrInvalidToken when validation fails" subtest
constructed a real PATClient and called GetAuthenticatedUser, which makes
a live HTTP request to api.github.com. That's flaky in CI / offline dev
and violates the unit-test boundary (caught in review).

Replace with a sentinel-survives-wrap-pattern check that locks in the
exact %w/%w shape used by ConfigureToken, plus an assertion that the
inner cause stays reachable through errors.Is. The full ConfigureToken
flow stays covered by service_token_test.go and integration tests.

Remove the now-unused noopSecretManager stub type.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(task): restore "timed out" UX for plain-fmt.Errorf timeout producers

The original createPromptErrorMessage rendered the friendly "Request timed
out…" hint via strings.Contains(err.Error(), "timeout"). The refactor
replaced it with errors.Is(context.DeadlineExceeded) + a net.Error
Timeout() helper — strictly typed. But several upstream producers along
the prompt path (service.WaitForSessionReady, agent-stream connect waits
in lifecycle/session.go and manager_interaction.go, agentctl health waits
in agentctl/client.go and launcher.go, the orchestrator's own
waitForSessionReady) return plain fmt.Errorf("timeout …") with no typed
Timeout() method, so the typed check missed them and the user saw the
generic "Failed to send message to agent" instead.

Add a substring fallback inside isTimeoutError as a UX safety net while
keeping the primary typed paths intact. Lock the contract with table
tests covering all three classes (net.Error timeout, plain string,
context.DeadlineExceeded) so any future trim of the fallback breaks
loudly. Migrating each upstream producer to a typed sentinel is tracked
as out-of-scope follow-up.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test(backend): tighten classification tests to exercise typed-sentinel contracts

Addresses bot-review feedback on PR #1057:

- task/handlers/errors_test.go: cover all four not-found sentinels
  (taskrepo.ErrTaskNotFound, service.ErrDocumentNotFound,
  service.ErrTaskPlanNotFound, service.ErrRevisionNotFound) in
  TestErrorsAreClassifiable via a table-driven loop, instead of only
  one. Drop the spurious Deadline() *time.Time method on timeoutNetErr
  — it isn't part of net.Error and the existing `var _ net.Error =
  timeoutNetErr{}` line already pins the interface.

- orchestrator/scheduler/scheduler_test.go: testTaskRepository was
  still returning the local scheduler.ErrTaskNotFound, which doesn't
  satisfy the production processTasks check (now errors.Is on
  taskrepo.ErrTaskNotFound). Mirror the real sqlite repo's wrap so the
  mock and prod paths agree. The local scheduler.ErrTaskNotFound is
  truly dead after that, so drop it from scheduler.go.

- office/skills: the wrap-pattern subtest in errors_test.go was only
  testing fmt.Errorf, not production code. Move the contract assertion
  to service_test.go (external skills_test package) where it drives
  the real GetSkillFromConfig lookup path against an empty in-memory
  repository.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(backend): drop redundant context.DeadlineExceeded check and fix doc grammar

Addresses bot-review feedback on PR #1057:

- task/handlers/message_handlers.go::createPromptErrorMessage: the
  explicit errors.Is(promptErr, context.DeadlineExceeded) is redundant
  with isTimeoutError, which already matches via errors.As against
  Timeout() — context.DeadlineExceeded implements Timeout()==true.
  Inline comment documents the consolidation.

- github/errors.go: fix grammar in the ErrTaskNotFound doc comment
  ("is the sentinel cleanup paths check for to distinguish" →
  "is the sentinel that cleanup paths check to distinguish").

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 13:07:46 +01:00

706 lines
26 KiB
Go

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