Function beginStep

coderd/x/chatd/chatdebug/recorder.go:208–288

beginStep validates preconditions, creates a debug step, and returns a handle plus an enriched context carrying StepContext and attemptSink. Returns (nil, original ctx) when debug recording should be skipped.

(
	ctx context.Context,
	svc *Service,
	opts RecorderOptions,
	op Operation,
	normalizedReq any,
)

// handle plus an enriched context carrying StepContext and attemptSink.
// Returns (nil, original ctx) when debug recording should be skipped.
func beginStep(
	ctx context.Context,
	svc *Service,
	opts RecorderOptions,
	op Operation,
	normalizedReq any,
) (*stepHandle, context.Context) {
	if svc == nil {
		return nil, ctx
	}

	rc, ok := RunFromContext(ctx)
	if !ok || rc.RunID == uuid.Nil {
		return nil, ctx
	}

	chatID := opts.ChatID
	if chatID == uuid.Nil {
		chatID = rc.ChatID
	}
	if !svc.IsEnabled(ctx, chatID, opts.OwnerID) {
		return nil, ctx
	}

	holder, reuseStep := reuseHolderFromContext(ctx)
	if reuseStep {
		holder.mu.Lock()
		defer holder.mu.Unlock()
		// Only reuse the cached handle if it belongs to the same run.
		// A different RunContext means a new logical run, so we must
		// create a fresh step to avoid cross-run attribution.
		if holder.handle != nil && holder.handle.stepCtx.RunID == rc.RunID {
			enriched := ContextWithStep(ctx, holder.handle.stepCtx)
			enriched = withAttemptSink(enriched, holder.handle.sink)
			return holder.handle, enriched
		}
	}

	stepNum := nextStepNumber(rc.RunID)
	step, err := svc.CreateStep(ctx, CreateStepParams{
		RunID:               rc.RunID,
		ChatID:              chatID,
		StepNumber:          stepNum,
		Operation:           op,
		Status:              StatusInProgress,
		HistoryTipMessageID: rc.HistoryTipMessageID,
		NormalizedRequest:   normalizedReq,
	})
	if err != nil {
		svc.log.Warn(ctx, "failed to create chat debug step",
			slog.Error(err),
			slog.F("chat_id", chatID),
			slog.F("run_id", rc.RunID),
			slog.F("operation", op),
		)
		return nil, ctx
	}