Method handleStreamError

pkg/runtime/loop_steps.go:143–190

handleStreamError classifies the error returned by tryModelWithFallback and either drives auto-compaction recovery (allowed at most r.maxOverflowCompactions consecutive times) or surfaces a fatal error. Context cancellation is treated as a graceful stop. *overflowCompactions is incremented on retry

(
	ctx context.Context,
	sess *session.Session,
	a *agent.Agent,
	err error,
	contextLimit int64,
	overflowCompactions *int,
	streamSpan trace.Span,
	events EventSink,
)

// verify both the "compaction succeeded → retry" and "compaction
// exhausted → fatal" outcomes without instantiating models.
func (r *LocalRuntime) handleStreamError(
	ctx context.Context,
	sess *session.Session,
	a *agent.Agent,
	err error,
	contextLimit int64,
	overflowCompactions *int,
	streamSpan trace.Span,
	events EventSink,
) streamErrorOutcome {
	// Treat context cancellation as a graceful stop.
	if errors.Is(err, context.Canceled) {
		slog.DebugContext(ctx, "Model stream canceled by context", "agent", a.Name(), "session_id", sess.ID)
		return streamErrorFatal
	}

	// Auto-recovery: if the error is a context overflow and session
	// compaction is enabled, compact the conversation and retry the
	// request instead of surfacing raw errors. We allow at most
	// r.maxOverflowCompactions consecutive attempts to avoid an infinite
	// loop when compaction cannot reduce the context enough.
	if _, ok := errors.AsType[*modelerrors.ContextOverflowError](err); ok && r.sessionCompaction && *overflowCompactions < r.maxOverflowCompactions {
		*overflowCompactions++
		slog.WarnContext(ctx, "Context window overflow detected, attempting auto-compaction",
			"agent", a.Name(),
			"session_id", sess.ID,
			"input_tokens", sess.InputTokens,
			"output_tokens", sess.OutputTokens,
			"context_limit", contextLimit,
			"attempt", *overflowCompactions,
		)
		events.Emit(Warning(
			"The conversation has exceeded the model's context window. Automatically compacting the conversation history...",
			a.Name(),
		))
		r.compactWithReason(ctx, sess, "", compactionReasonOverflow, events)
		return streamErrorRetry
	}

	streamSpan.RecordError(err)
	streamSpan.SetStatus(codes.Error, "error handling stream")
	slog.ErrorContext(ctx, "All models failed", "agent", a.Name(), "error", err)
	r.telemetry.RecordError(ctx, err.Error())
	errMsg := modelerrors.FormatError(err)
	events.Emit(ErrorWithCodeForSession(sess.ID, classifyErrorCode(err), errMsg))
	r.notifyError(ctx, a, sess.ID, errMsg)
	return streamErrorFatal
}

// classifyErrorCode maps a model error to an ErrorCode constant for
// structured error events. The classification mirrors [modelerrors]