feat(api): add throwIfAborted helper and completePrompt options regression tests

[easonLiangWorldedtech]

Add the missing throwIfAborted fast-fail guard and the shared abort-detection / abort-error helpers to the abort-signal utilities (#1008 merged the merge helpers but not this guard), plus regression tests for the CompletePromptOptions interface added by #901.

• src/api/providers/utils/abort-signal.ts:
  • new throwIfAborted(signal?) — throws Error with name = "AbortError" when the signal is already aborted
  • new shared isRequestAborted(error, signal?) — true when the caller signal fired, a native AbortError / OpenAI SDK APIUserAbortError was raised, or the message is exactly "Request was aborted."
  • new shared createAbortError(providerName) — fresh AbortError with a provider-specific message ending in "aborted", satisfying the Task.ts abort contract
  • new exported OpenAiRequestOptions type
• src/api/providers/utils/__tests__/abort-signal.spec.ts: 3 throwIfAborted tests (undefined / not aborted / aborted) + 7 new tests for the shared helpers
• src/api/providers/__tests__/complete-prompt-options.spec.ts: new regression spec (4 tests) for the interface surface

Part of the abort-signal series (round 1). Builds on #674, #901, #1008. Addresses #404.

Summary by CodeRabbit

• New Features

  • Added support for detecting already-cancelled requests and returning clear, provider-specific abort errors.
  • Improved recognition of cancellation across different request and error formats.
  • Added support for combining request timeouts with cancellation signals.

• Bug Fixes

  • Improved handling of optional request cancellation signals and consistent cancellation reporting.

• Tests

  • Expanded coverage for cancellation scenarios, timeout options, combined settings, empty configurations, error messages, and error naming.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e06b6201-6fa7-4a3a-ace9-82c638f07e1c

📥 Commits

Reviewing files that changed from the base of the PR and between f3e807a and a0117fb.

📒 Files selected for processing (2)

• src/api/providers/utils/__tests__/abort-signal.spec.ts
• src/api/providers/utils/abort-signal.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The provider API now includes abort-signal guards, detection, and error creation utilities. Tests cover abort behavior, abort error variants, and valid CompletePromptOptions combinations.

Changes

Provider API updates

Layer / File(s)	Summary
Abort-signal utilities src/api/providers/utils/abort-signal.ts	Added throwIfAborted, OpenAiRequestOptions, isRequestAborted, and createAbortError.
Abort-signal behavior coverage src/api/providers/utils/__tests__/abort-signal.spec.ts	Added tests for signal states, native and SDK abort errors, exact abort messages, unrelated errors, and normalized error instances.
Completion option coverage src/api/providers/__tests__/complete-prompt-options.spec.ts	Added tests for abortSignal, timeoutMs, both properties, and an empty options object.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to a0117

This PR adds abort-handling helpers and regression coverage without any identified current-head correctness or production-impact risk; it is merge-ready after normal checks and review.

Suggested reviewers: edelauna

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the implementation and tests, but it omits the required template sections and an explicit linked issue entry.	Use the repository template and add an explicit issue link, test procedure, checklist status, and documentation notes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main helper addition and the related CompletePromptOptions regression tests.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[easonLiangWorldedtech]

Series follow-up flag: adopt RequestConfigBuilder for abort/timeout option construction

This PR currently builds its abort/timeout request options directly with mergeAbortSignalAndTimeout(...) from src/api/providers/utils/abort-signal.ts. That is behaviorally identical to the RequestConfigBuilder path (src/api/providers/config-builder/request-config-builder.ts, introduced in #1008) - the builder wraps the same utility. The series plan is to make the builder the canonical call site for SDK request-option construction (typed TOptions variants per SDK), so this PR is flagged for that update.

Status: series foundation - nothing to migrate here. This PR ships the abort-signal utilities (including throwIfAborted and the timeout guard) that the builder delegates to; provider-side adoption is tracked on the individual provider PRs.

[easonLiangWorldedtech]

Round 1 — final status: all checks green, changed-line coverage verified

Part of the abort-signal series addressing #404 (builds on #674, #901, #1008). Foundation PR — canonical abort-signal utilities + CompletePromptOptions.

Final verified 2026-08-20: all CI checks green on this head (0 pending / 0 failed), CodeRabbit review clean, and zero new bot findings after this commit.

• Final head: e61feb13e (rebased onto main 252c69b52)
• Work in this round: new src/api/providers/utils/abort-signal.ts — mergeAbortSignalAndTimeout(externalSignal?, timeoutMs?), mergeAbortSignals(primary, secondary?), and the throwIfAborted helper (the series-wide API shape: no cleanup()/finally contract; callers own listener removal). All 16 utility tests green.
• Config builder: the statics added to RequestConfigBuilder in feat(api): abort signal support for openai-codex (completePrompt + createMessage) #1290/feat(api): abort signal support for openai-native and openai-compatible (completePrompt + createMessage) #1291 delegate to the utilities introduced here, so the canonical timeout-merge semantics have a single source.
• Changed-line coverage: 5/5 executable changed lines covered (100%). Measured with local vitest --coverage (v8 + lcov — same pipeline as the repo's codecov/patch check) and cross-referenced line-by-line against git diff 252c69b52..HEAD.