Function waitForAgentReady

coderd/x/chatd/chattool/createworkspace.go:619–704

waitForAgentReady waits for the workspace agent to become reachable and for its startup scripts to finish. It returns status fields suitable for merging into a tool response.

(
	ctx context.Context,
	db database.Store,
	agent database.WorkspaceAgent,
	agentConnFn AgentConnFunc,
)

// reachable and for its startup scripts to finish. It returns
// status fields suitable for merging into a tool response.
func waitForAgentReady(
	ctx context.Context,
	db database.Store,
	agent database.WorkspaceAgent,
	agentConnFn AgentConnFunc,
) map[string]any {
	result := map[string]any{}
	agentID := agent.ID

	// Phase 1: retry connecting to the agent.
	if agentConnFn != nil {
		agentCtx, agentCancel := context.WithTimeout(ctx, agentConnectTimeout)
		defer agentCancel()

		ticker := time.NewTicker(agentRetryInterval)
		defer ticker.Stop()

		var lastErr error
		for {
			attemptCtx, attemptCancel := context.WithTimeout(agentCtx, agentAttemptTimeout)
			conn, release, err := agentConnFn(attemptCtx, agentID)
			attemptCancel()
			if err == nil {
				release()
				_ = conn
				break
			}
			lastErr = err

			select {
			case <-agentCtx.Done():
				result["agent_status"] = "not_ready"
				// External agents may need user action on a different
				// host. Surface that guidance instead of the raw dial
				// error after the retry window has elapsed. The retry
				// loop itself is unchanged, so a Connecting external
				// agent still gets the full window to come online.
				if msg := externalAgentReadyError(ctx, db, agent); msg != "" {
					result["agent_error"] = msg
				} else {
					result["agent_error"] = lastErr.Error()
				}
				return result
			case <-ticker.C:
			}
		}
	}

	// Phase 2: poll lifecycle until startup scripts finish.
	scriptCtx, scriptCancel := context.WithTimeout(ctx, startupScriptTimeout)
	defer scriptCancel()

	ticker := time.NewTicker(startupScriptPollInterval)
	defer ticker.Stop()

	var lastState database.WorkspaceAgentLifecycleState
	for {
		row, err := db.GetWorkspaceAgentLifecycleStateByID(scriptCtx, agentID)