magic-agent 1.0.0

package/internal/agent/runcmd.go

@@ -0,0 +1,259 @@
+package agent
+
+// runcmd.go - 进程组感知的 CLI 执行辅助（平台无关部分）。
+//
+// 三家 CLI 都是 node 启动器，内部还会 spawn worker 子进程。
+// exec.CommandContext 超时只杀直接子进程，CLI 的 worker 会变孤儿
+// 继续跑（实测残留多个 node 进程）。这里统一用进程组：
+//
+//	1. configureProcAttr: 让 CLI 及其全部后代进独立进程组（组长 = CLI）；
+//	2. ctx 结束/超时时 killProcessGroup 杀掉整组；
+//	3. cmd.Wait() 自然回收。
+//
+// 平台差异（Setpgid/负 pid kill vs Windows taskkill /T）分别放在
+// runcmd_unix.go 与 runcmd_windows.go。
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+	"time"
+)
+
+// spawnHookKey ctx 里携带「子进程已启动」回调的键（见 WithSpawnHook）。
+type spawnHookKey struct{}
+
+// WithSpawnHook 注册「引擎子进程刚启动」的回调（参数是子进程 pid）。
+//
+// 用途：会话登记表要记住**引擎子进程**的 pid —— 它自成进程组（Setpgid），
+// 与 magic-agent 自己不在同一组，所以调用方杀 magic-agent 的进程组带不走它。
+// 记录到 pid 后，`magic-agent --stop <会话>` 才能精确杀掉这条会话的引擎。
+//
+// 回调在 Start() 之后同步调用，只做写文件这类轻量事（不阻塞读流）。
+func WithSpawnHook(ctx context.Context, fn func(pid int)) context.Context {
+	if fn == nil {
+		return ctx
+	}
+	return context.WithValue(ctx, spawnHookKey{}, fn)
+}
+
+// notifySpawn 通知 ctx 上注册的 spawn 回调（无回调时什么都不做）。
+func notifySpawn(ctx context.Context, pid int) {
+	if ctx == nil || pid <= 0 {
+		return
+	}
+	if fn, ok := ctx.Value(spawnHookKey{}).(func(int)); ok && fn != nil {
+		fn(pid)
+	}
+}
+
+// runCLI 在独立进程组里执行 bin args，返回 (stdout, stderr, err)。
+// 超时/取消时杀掉整个进程组（含 CLI 的全部后代进程）。
+func runCLI(ctx context.Context, bin string, args ...string) (string, string, error) {
+	return runCLIIn(ctx, "", bin, args...)
+}
+
+// runCLIIn 同 runCLI，但可指定工作目录 dir（空 = 继承调用方 cwd）。
+// workspace 的主要落地手段就是它：claude / codebuddy / trae / openclaw 都没有
+// 「工作目录」flag，**进程 cwd 就是它们的原生方式**（相对路径、CLAUDE.md 发现、
+// git 上下文都跟着它走）；codex 另有原生 `-C/--cd`（见 codex.go buildArgs）。
+func runCLIIn(ctx context.Context, dir string, bin string, args ...string) (string, string, error) {
+	return runCLIEnvIn(ctx, dir, nil, bin, args...)
+}
+
+// runCLIEnv 在 runCLI 基础上为子进程追加环境变量（extra 为 K=V 切片，
+// 追加在继承环境之后 —— Go exec 语义：重复 key 取最后一个，故 extra 覆盖继承值）。
+func runCLIEnv(ctx context.Context, extra []string, bin string, args ...string) (string, string, error) {
+	return runCLIEnvIn(ctx, "", extra, bin, args...)
+}
+
+// runCLIEnvIn = runCLIIn + runCLIEnv（工作目录 + 追加环境变量）。
+func runCLIEnvIn(ctx context.Context, dir string, extra []string, bin string, args ...string) (string, string, error) {
+	cmd := exec.Command(bin, args...)
+	if dir != "" {
+		cmd.Dir = dir
+	}
+	configureProcAttr(cmd)
+
+	/* stdout/stderr 用**自建管道 + 自己 drain**，不直挂 bytes.Buffer：
+	   Go 只在目标是 *os.File 时才不做「内部拷贝 goroutine」，而 **cmd.Wait() 会等那些
+	   goroutine 结束** —— 只要子进程还有后代握着管道写端（引擎 CLI 的 node worker 逃出
+	   进程组时就是这样），Wait 就永远不返回：症状是「引擎已经死了，magic-agent 却挂着不退」。
+	   （流式路径 2026-09-18 踩过一次，见 stream.go 的同类注释；这里按同一姿势一并修。） */
+	stdoutR, stdoutW, perr := os.Pipe()
+	if perr != nil {
+		return "", "", perr
+	}
+	stderrR, stderrW, perr := os.Pipe()
+	if perr != nil {
+		stdoutR.Close()
+		stdoutW.Close()
+		return "", "", perr
+	}
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = stdoutW
+	cmd.Stderr = stderrW
+	cmd.Env = envWithDefaults()
+	if len(extra) > 0 {
+		cmd.Env = append(cmd.Env, extra...)
+	}
+
+	if err := cmd.Start(); err != nil {
+		stdoutR.Close()
+		stdoutW.Close()
+		stderrR.Close()
+		stderrW.Close()
+		return "", "", err
+	}
+	notifySpawn(ctx, cmd.Process.Pid) // 会话登记表据此记住引擎子进程 pid
+	stdoutW.Close()
+	stderrW.Close()
+	drained := make(chan struct{}, 2)
+	go func() { defer stdoutR.Close(); _, _ = io.Copy(&stdout, stdoutR); drained <- struct{}{} }()
+	go func() { defer stderrR.Close(); _, _ = io.Copy(&stderr, stderrR); drained <- struct{}{} }()
+
+	// 看门狗：ctx 结束 → 杀整组。
+	waitErr := make(chan error, 1)
+	go func() { waitErr <- cmd.Wait() }()
+
+	select {
+	case err := <-waitErr:
+		waitDrained(drained, 2, 10*time.Second) // 进程已退：等 drain 读完余量（有限等待防后代握管道挂死）
+		return stdout.String(), stderr.String(), err
+	case <-ctx.Done():
+		killProcessGroup(cmd)
+		select {
+		case <-waitErr:
+		case <-time.After(10 * time.Second):
+		}
+		waitDrained(drained, 2, 5*time.Second)
+		return stdout.String(), stderr.String(), fmt.Errorf("process group killed: %w", ctx.Err())
+	}
+}
+
+// waitDrained 等 n 个 drain goroutine 收尾，最多等 d（防后代进程握着写端导致永久挂起）。
+func waitDrained(ch <-chan struct{}, n int, d time.Duration) {
+	deadline := time.After(d)
+	for i := 0; i < n; i++ {
+		select {
+		case <-ch:
+		case <-deadline:
+			return
+		}
+	}
+}
+
+// envWithDefaults 继承当前环境（CLI 依赖 HOME/PATH 等基础变量）。
+func envWithDefaults() []string {
+	return environ()
+}
+
+// newStreamCmd 构造流式 CLI 进程（进程组 + 环境继承，stdout 留给调用方接管）。
+func newStreamCmd(bin string, args []string) *exec.Cmd {
+	return newStreamCmdIn("", bin, args)
+}
+
+// newStreamCmdIn 同 newStreamCmd，可指定工作目录（workspace，见 runCLIIn 注释）。
+func newStreamCmdIn(dir string, bin string, args []string) *exec.Cmd {
+	cmd := exec.Command(bin, args...)
+	if dir != "" {
+		cmd.Dir = dir
+	}
+	configureProcAttr(cmd)
+	cmd.Env = envWithDefaults()
+	return cmd
+}
+
+// streamStderrBuf 流式进程的 stderr 缓冲（保留尾部 32KB 供错误摘要）。
+type streamStderrBuf struct {
+	buf [32 * 1024]byte
+	n   int
+}
+
+func (b *streamStderrBuf) Write(p []byte) (int, error) {
+	if room := len(b.buf) - b.n; room > 0 {
+		if len(p) <= room {
+			copy(b.buf[b.n:], p)
+			b.n += len(p)
+			return len(p), nil
+		}
+		copy(b.buf[b.n:], p[:room])
+		b.n = len(b.buf)
+	}
+	return len(p), nil
+}
+
+// String 尾部内容（去 ANSI）。
+func (b *streamStderrBuf) String() string {
+	return stripANSI(string(b.buf[:b.n]))
+}
+
+// stderrSummary 从 CLI 的 stderr 里提取人可读的失败摘要：
+// 取最后一行非空输出（CLI 报错通常在末尾），去 ANSI 色码，截断。
+func stderrSummary(stderr string) string {
+	lines := strings.Split(strings.TrimSpace(stderr), "\n")
+	for i := len(lines) - 1; i >= 0; i-- {
+		if s := strings.TrimSpace(lines[i]); s != "" {
+			return truncateStr(stripANSI(s), 500)
+		}
+	}
+	return ""
+}
+
+// wrapCliError 统一包装引擎 CLI 的执行失败。
+//
+// 外层文本 "<engine> CLI: <cliCauseError>"（cliCauseError.Error() 自带
+// stderr 摘要），错误链经 %w 保持完整 —— WriteError 由此提取 reason。
+//
+// stderr 为空时（典型：超时被杀）不追加 stderr 摘要，避免拿 err 自身
+// 回填造成重复。
+func wrapCliError(engine, stdout, stderr string, err error) error {
+	summary := stderrSummary(stderr)
+	return fmt.Errorf("%s CLI: %w", engine, &cliCauseError{cause: err, summary: summary})
+}
+
+// cliCauseError CLI 失败的根因载体。
+// Error() 输出格式：
+//
+//	有摘要  "<cause> (stderr: <摘要>)"
+//	无摘要  "<cause>"（超时 / fork 失败类）
+type cliCauseError struct {
+	cause   error
+	summary string
+}
+
+func (e *cliCauseError) Error() string {
+	if e.summary != "" {
+		return fmt.Sprintf("%v (stderr: %s)", e.cause, e.summary)
+	}
+	return e.cause.Error()
+}
+
+func (e *cliCauseError) Cause() error { return e.cause }
+
+// Summary stderr 摘要；空表示无（超时/fork 失败类）。
+func (e *cliCauseError) Summary() string { return e.summary }
+
+// Unwrap 支持 errors.Is/As 沿链下钻。
+func (e *cliCauseError) Unwrap() error { return e.cause }
+
+// stripANSI 去除 ANSI 转义序列（色码），避免错误信息里混入 "\x1b[31m"。
+func stripANSI(s string) string {
+	var b strings.Builder
+	inEsc := false
+	for _, r := range s {
+		switch {
+		case r == 0x1b:
+			inEsc = true
+		case inEsc && (r == 'm' || r == 'K' || r == 'H'):
+			inEsc = false // CSI 序列终结符
+		case !inEsc:
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}

package/internal/agent/runcmd_test.go

@@ -0,0 +1,81 @@
+//go:build !windows
+
+package agent
+
+// runcmd_test.go - 进程组杀灭回归测试（POSIX only：依赖 sh 脚本与进程组信号）。
+//
+// 场景：CLI 脚本 spawn 一个长活后台子进程（模拟 codebuddy 的 node
+// worker），runCLI 超时后整个进程组（含后台子进程）必须被杀干净。
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func TestRunCLIKillsProcessGroupOnTimeout(t *testing.T) {
+	dir := t.TempDir()
+	marker := filepath.Join(dir, "alive")
+	cli := filepath.Join(dir, "slow-cli")
+	// 脚本：启动即 touch marker（消除负载下的启动竞态），后台循环持续
+	// 写 marker（模拟 worker 存活），前台 sleep 30s。
+	script := "#!/bin/sh\ntouch " + marker + "\n(while true; do touch " + marker + "; sleep 0.2; done) &\nsleep 30\n"
+	if err := os.WriteFile(cli, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 800*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	_, _, err := runCLI(ctx, cli)
+	if err == nil {
+		t.Fatal("expected timeout error")
+	}
+	if elapsed := time.Since(start); elapsed > 5*time.Second {
+		t.Errorf("kill took too long: %v", elapsed)
+	}
+
+	// 等一小段时间，检查 marker 不再更新（进程组已死）。
+	stat1, _ := os.Stat(marker)
+	time.Sleep(600 * time.Millisecond)
+	stat2, _ := os.Stat(marker)
+	if stat1 == nil {
+		t.Fatal("marker should exist (worker was alive)")
+	}
+	if stat2 != nil && stat2.ModTime().After(stat1.ModTime()) {
+		t.Errorf("background worker still alive after group kill (mtime advanced: %v -> %v)", stat1.ModTime(), stat2.ModTime())
+	}
+
+	// 残留进程检查：该脚本名下不应有进程。
+	if err := syscall.Kill(0, 0); err != nil {
+		t.Logf("signal self check: %v", err)
+	}
+}
+
+func TestRunCLISuccess(t *testing.T) {
+	dir := t.TempDir()
+	cli := filepath.Join(dir, "ok-cli")
+	if err := os.WriteFile(cli, []byte("#!/bin/sh\necho OUT\necho ERR >&2\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	stdout, stderr, err := runCLI(context.Background(), cli)
+	if err != nil {
+		t.Fatalf("runCLI: %v", err)
+	}
+	if stdout != "OUT\n" {
+		t.Errorf("stdout = %q", stdout)
+	}
+	if stderr != "ERR\n" {
+		t.Errorf("stderr = %q", stderr)
+	}
+}
+
+func TestRunCLIStartFailure(t *testing.T) {
+	_, _, err := runCLI(context.Background(), "/nonexistent/cli-xyz")
+	if err == nil {
+		t.Fatal("expected start error")
+	}
+}

package/internal/agent/runcmd_unix.go

@@ -0,0 +1,56 @@
+//go:build !windows
+
+package agent
+
+// runcmd_unix.go - Unix (darwin/linux) 进程组实现。
+//
+// Setpgid 让子进程自成进程组（pgid = 子进程 pid），超时时用负 pid
+// 向整组发 SIGKILL，CLI 内部 spawn 的 node worker 一并清理。
+
+import (
+	"errors"
+	"os/exec"
+	"syscall"
+)
+
+// configureProcAttr 让子进程进入独立进程组。
+func configureProcAttr(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+}
+
+// killProcessGroup 杀掉整个进程组（负 pid = 进程组）。
+func killProcessGroup(cmd *exec.Cmd) {
+	if cmd.Process == nil {
+		return
+	}
+	_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+}
+
+// killTarget 把 (pid, group) 换算成 syscall.Kill 的目标：
+// 进程组用负 pid（子 CLI 自成一组，pgid = 子 pid），单进程用正 pid。
+func killTarget(pid int, group bool) int {
+	if group {
+		return -pid
+	}
+	return pid
+}
+
+// TerminatePID 按 pid 发 SIGTERM（group=true → 整个进程组）。
+func TerminatePID(pid int, group bool) error {
+	return syscall.Kill(killTarget(pid, group), syscall.SIGTERM)
+}
+
+// KillPID 按 pid 发 SIGKILL（group=true → 整个进程组）。
+func KillPID(pid int, group bool) error {
+	return syscall.Kill(killTarget(pid, group), syscall.SIGKILL)
+}
+
+// PIDAlive 报告 pid 是否还活着（signal 0 只做权限/存在性检查）。
+// EPERM 也算活着（进程在，只是不归我们管）。
+func PIDAlive(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	err := syscall.Kill(pid, 0)
+	return err == nil || errors.Is(err, syscall.EPERM)
+}

package/internal/agent/runcmd_windows.go

@@ -0,0 +1,66 @@
+//go:build windows
+
+package agent
+
+// runcmd_windows.go - Windows 进程树实现。
+//
+// Windows 没有 POSIX 进程组语义，等价做法：
+//   - 启动时置 CREATE_NEW_PROCESS_GROUP 让 CLI 自成一组（隔离 Ctrl-C、
+//     便于整组信号）；
+//   - 超时时用 `taskkill /T /F /PID <pid>` 强制杀掉整棵进程树
+//     （/T 含所有后代），避免 node worker 变孤儿。
+//
+// 注释里刻意不写裸反斜杠，避免转义歧义。
+
+import (
+	"errors"
+	"os/exec"
+	"strconv"
+	"strings"
+	"syscall"
+)
+
+// createNewProcessGroup 对应 Windows CREATE_NEW_PROCESS_GROUP 标志。
+const createNewProcessGroup = 0x00000200
+
+// configureProcAttr 让子进程自成进程组。
+func configureProcAttr(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{CreationFlags: createNewProcessGroup}
+}
+
+// killProcessGroup 用 taskkill 杀掉进程树（/T 后代 + /F 强制）。
+func killProcessGroup(cmd *exec.Cmd) {
+	if cmd.Process == nil {
+		return
+	}
+	pid := strconv.Itoa(cmd.Process.Pid)
+	// 优先整树杀；失败再退回单进程 Kill。
+	if err := exec.Command("taskkill", "/T", "/F", "/PID", pid).Run(); err != nil {
+		_ = cmd.Process.Kill()
+	}
+}
+
+// TerminatePID Windows 无 SIGTERM 语义 → 与 KillPID 同路（taskkill /T /F 杀整棵树）。
+func TerminatePID(pid int, group bool) error {
+	return KillPID(pid, group)
+}
+
+// KillPID 按 pid 杀进程树（group 参数在 Windows 无意义：taskkill /T 总是带后代）。
+func KillPID(pid int, group bool) error {
+	if pid <= 0 {
+		return errors.New("invalid pid")
+	}
+	return exec.Command("taskkill", "/T", "/F", "/PID", strconv.Itoa(pid)).Run()
+}
+
+// PIDAlive 用 tasklist 查该 pid 是否还在。
+func PIDAlive(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	out, err := exec.Command("tasklist", "/FI", "PID eq "+strconv.Itoa(pid), "/NH").Output()
+	if err != nil {
+		return false
+	}
+	return strings.Contains(string(out), strconv.Itoa(pid))
+}

package/internal/agent/runner.go

@@ -0,0 +1,180 @@
+package agent
+
+// runner.go - 超时 + 重试编排。
+//
+// Runner 在 Engine 之上叠加跨引擎一致的调用语义：
+//
+//	- 每次尝试独立超时（context.WithTimeout），超时错误可重试；
+//	- 可重试错误分类：网络类（connection refused / reset / EOF / timeout /
+//	  signal killed）与限流类（429 / rate limit / 503 overloaded）重试，
+//	  其余（参数错、鉴权错、空输出、明确非重试 CLI 错误）快速失败；
+//	- 指数退避：attempt N 失败后等待 backoff * 2^(N-1)，上限 maxBackoff；
+//	  重试等待可被 ctx 取消打断；
+//	- 重试次数语义：retries=2 表示「最多 1 + 2 = 3 次尝试」。
+//
+// 使用：
+//
+//	r := &agent.Runner{Engine: e, Timeout: 3*time.Minute, Retries: 2}
+//	resp, err := r.Run(ctx, agent.Request{...})
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"math/rand"
+	"os"
+	"strings"
+	"time"
+)
+
+// stderr 用于测试替换的 stderr 句柄。
+var stderr io.Writer = os.Stderr
+
+// Runner 单引擎的调用编排器。
+type Runner struct {
+	// Engine 目标引擎（必填）。
+	Engine Engine
+
+	// Timeout 单次尝试超时；0 = 引擎默认。
+	Timeout time.Duration
+
+	// Retries 额外重试次数（总尝试 = 1 + Retries）。
+	Retries int
+
+	// Backoff 首次重试前等待；之后指数翻倍。0 = 2s。
+	Backoff time.Duration
+
+	// MaxBackoff 退避上限。0 = 30s。
+	MaxBackoff time.Duration
+
+	// Verbose 打印重试过程到 stderr。
+	Verbose bool
+}
+
+// defaultTimeout 按引擎取默认超时。
+func (r *Runner) defaultTimeout() time.Duration {
+	switch r.Engine.(type) {
+	case *ClaudeEngine:
+		return DefaultClaudeTimeout
+	case *CodeBuddyEngine:
+		return DefaultCodeBuddyTimeout
+	case *CodeBuddyAIEngine:
+		return DefaultCodeBuddyTimeout // 同族 CLI，超时语义一致
+	case *TraeEngine:
+		return DefaultTraeTimeout
+	case *LLMEngine:
+		return DefaultLLMTimeout
+	case *ArkClawEngine:
+		return DefaultArkClawTimeout
+	case *CodeBuddyGatewayEngine:
+		return DefaultCBGatewayTimeout
+	case *DshEngine:
+		return DefaultDshTimeout
+	}
+	return 5 * time.Minute
+}
+
+// isRetryable 判断错误是否值得重试。
+func isRetryable(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, context.DeadlineExceeded) {
+		return true // 单次尝试超时 → 重新来一遍
+	}
+	msg := strings.ToLower(err.Error())
+	for _, kw := range []string{
+		"429", "rate limit", "rate_limit", "overloaded",
+		"connection refused", "connection reset", "broken pipe",
+		"eof", "timeout", "timed out",
+		"signal: killed", "context deadline exceeded",
+		"temporarily unavailable", "502", "503", "504",
+	} {
+		if strings.Contains(msg, kw) {
+			return true
+		}
+	}
+	return false
+}
+
+// Run 执行带超时与重试的调用。ctx 取消/超时整体打断（不算可重试）。
+func (r *Runner) Run(ctx context.Context, req Request) (Response, error) {
+	if r.Engine == nil {
+		return Response{}, fmt.Errorf("runner: engine is nil")
+	}
+	if req.Engine == "" {
+		req.Engine = r.Engine.Name()
+	}
+
+	timeout := r.Timeout
+	if timeout == 0 {
+		timeout = r.defaultTimeout()
+	}
+	backoff := r.Backoff
+	if backoff == 0 {
+		backoff = 2 * time.Second
+	}
+	maxBackoff := r.MaxBackoff
+	if maxBackoff == 0 {
+		maxBackoff = 30 * time.Second
+	}
+
+	totalAttempts := 1 + r.Retries
+	var lastErr error
+
+	for attempt := 1; attempt <= totalAttempts; attempt++ {
+		// 整体 ctx 已取消 → 直接终止，不再尝试。
+		if err := ctx.Err(); err != nil {
+			if lastErr != nil {
+				return Response{}, fmt.Errorf("aborted after %d attempts: %w (last error: %v)", attempt-1, err, lastErr)
+			}
+			return Response{}, err
+		}
+
+		req.Timeout = timeout
+		attemptCtx, cancel := context.WithTimeout(ctx, timeout)
+		resp, err := r.Engine.Complete(attemptCtx, req)
+		cancel()
+
+		if err == nil {
+			resp.Attempts = attempt
+			if resp.Engine == "" {
+				resp.Engine = req.Engine
+			}
+			return resp, nil
+		}
+		lastErr = err
+
+		if r.Verbose {
+			fmt.Fprintf(stderr, "  ⏳ %s 第 %d/%d 次尝试失败: %v\n", r.Engine.Name(), attempt, totalAttempts, err)
+		}
+
+		if !isRetryable(err) {
+			return Response{}, fmt.Errorf("%w (attempts=%d, non-retryable)", err, attempt)
+		}
+		if attempt == totalAttempts {
+			break
+		}
+
+		// 指数退避 + 少量抖动，等待可被整体 ctx 打断。
+		wait := backoff * time.Duration(1<<uint(attempt-1))
+		if wait > maxBackoff {
+			wait = maxBackoff
+		}
+		jitter := time.Duration(rand.Int63n(int64(wait)/4 + 1))
+		wait += jitter
+		if r.Verbose {
+			fmt.Fprintf(stderr, "  ⏳ %s 将在 %v 后重试...\n", r.Engine.Name(), wait)
+		}
+		timer := time.NewTimer(wait)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return Response{}, fmt.Errorf("aborted during backoff: %w (last error: %v)", ctx.Err(), lastErr)
+		case <-timer.C:
+		}
+	}
+
+	return Response{}, fmt.Errorf("%s: all %d attempts failed: %w", r.Engine.Name(), totalAttempts, lastErr)
+}