feat(common): Add PromptResult<T> type for explicit abort handling

- Introduce PromptResult<T> discriminated union (PromptSuccess<T> | PromptAborted)
- Add helper functions: promptSuccess, promptAborted, isAbortError, unwrapPromptResult
- Add ABORT_ERROR_MESSAGE constant for consistent error messages
- Update LLM contract types to return PromptResult

Author: brandonkachen

common/src/types/contracts/llm.ts

@@ -5,6 +5,7 @@ import type { ParamsExcluding } from '../function-params'
 import type { Logger } from './logger'
 import type { Model } from '../../old-constants'
 import type { Message } from '../messages/codebuff-message'
+import type { PromptResult } from '../../util/error'
 import type { generateText, streamText, ToolCallPart } from 'ai'
 import type z from 'zod/v4'
 
@@ -52,7 +53,7 @@ export type PromptAiSdkStreamFn = (
     trackEvent: TrackEventFn
     signal: AbortSignal
   } & ParamsExcluding<typeof streamText, 'model' | 'messages'>,
-) => AsyncGenerator<StreamChunk, string | null>
+) => AsyncGenerator<StreamChunk, PromptResult<string | null>>
 
 export type PromptAiSdkFn = (
   params: {
@@ -78,7 +79,7 @@ export type PromptAiSdkFn = (
     n?: number
     signal: AbortSignal
   } & ParamsExcluding<typeof generateText, 'model' | 'messages'>,
-) => Promise<string>
+) => Promise<PromptResult<string>>
 
 export type PromptAiSdkStructuredInput<T> = {
   apiKey: string
@@ -104,7 +105,7 @@ export type PromptAiSdkStructuredInput<T> = {
   trackEvent: TrackEventFn
   signal: AbortSignal
 }
-export type PromptAiSdkStructuredOutput<T> = Promise<T>
+export type PromptAiSdkStructuredOutput<T> = Promise<PromptResult<T>>
 export type PromptAiSdkStructuredFn = <T>(
   params: PromptAiSdkStructuredInput<T>,
 ) => PromptAiSdkStructuredOutput<T>

common/src/util/error.ts

@@ -12,6 +12,60 @@ export type Failure<E extends ErrorObject = ErrorObject> = {
   error: E
 }
 
+/**
+ * Result type for prompt functions that can be aborted.
+ * Provides rich semantics to distinguish between successful completion and user abort.
+ *
+ * ## When to use `PromptResult<T>` vs `ErrorOr<T>`
+ *
+ * Use `PromptResult<T>` when:
+ * - The operation can be cancelled by the user (via AbortSignal)
+ * - An abort is an expected outcome, not an error
+ * - You need to distinguish between errors (which might trigger fallbacks) and
+ *   user-initiated aborts (which should propagate immediately)
+ *
+ * Use `ErrorOr<T>` when:
+ * - The operation can fail with an error that should be handled
+ * - There's no concept of user-initiated abort
+ * - You want to return error details rather than throw
+ *
+ * ## Abort handling patterns
+ *
+ * 1. **Check and return early** - For graceful handling where abort means "stop, no error":
+ *    ```ts
+ *    const result = await promptAiSdk({ ... })
+ *    if (result.aborted) return // or return null, false, etc.
+ *    doSomething(result.value)
+ *    ```
+ *
+ * 2. **Unwrap and throw** - For propagating aborts as exceptions:
+ *    ```ts
+ *    const value = unwrapPromptResult(await promptAiSdk({ ... }))
+ *    // Throws if aborted, callers should use isAbortError() in catch blocks
+ *    ```
+ *
+ * 3. **Rethrow in catch blocks** - Prevent swallowing abort errors:
+ *    ```ts
+ *    try {
+ *      await someOperation()
+ *    } catch (error) {
+ *      if (isAbortError(error)) throw error // Don't swallow aborts
+ *      // Handle other errors
+ *    }
+ *    ```
+ */
+export type PromptResult<T> = PromptSuccess<T> | PromptAborted
+
+export type PromptSuccess<T> = {
+  aborted: false
+  value: T
+}
+
+export type PromptAborted = {
+  aborted: true
+  reason?: string
+}
+
 export type ErrorObject = {
   name: string
   message: string
@@ -50,6 +104,72 @@ export function failure(error: unknown): Failure<ErrorObject> {
   }
 }
 
+/**
+ * Create a successful prompt result.
+ */
+export function promptSuccess<T>(value: T): PromptSuccess<T> {
+  return {
+    aborted: false,
+    value,
+  }
+}
+
+/**
+ * Create an aborted prompt result.
+ */
+export function promptAborted(reason?: string): PromptAborted {
+  return {
+    aborted: true,
+    ...(reason !== undefined && { reason }),
+  }
+}
+
+/**
+ * Standard error message for aborted requests.
+ * Use this constant when throwing abort errors to ensure consistency.
+ */
+export const ABORT_ERROR_MESSAGE = 'Request aborted'
+
+/**
+ * Check if an error is an abort error.
+ * Use this helper to detect abort errors in catch blocks.
+ *
+ * Detects both:
+ * - Errors with message 'Request aborted' (thrown by our code via ABORT_ERROR_MESSAGE)
+ * - Native AbortError (thrown by fetch/AI SDK when AbortSignal is triggered)
+ */
+export function isAbortError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false
+  }
+  // Check for our custom abort error message
+  if (error.message === ABORT_ERROR_MESSAGE) {
+    return true
+  }
+  // Check for native AbortError (DOMException or Error with name 'AbortError')
+  // This is thrown by fetch, AI SDK, and other web APIs when AbortSignal is triggered
+  if (error.name === 'AbortError') {
+    return true
+  }
+  return false
+}
+
+/**
+ * Unwrap a PromptResult, returning the value if successful or throwing if aborted.
+ *
+ * Use this helper for consistent abort handling when you want aborts to propagate
+ * as exceptions. Callers should use `isAbortError()` in catch blocks to detect
+ * and handle abort errors appropriately (e.g., rethrow instead of logging as errors).
+ *
+ * @throws {Error} When result.aborted is true. The error message is ABORT_ERROR_MESSAGE.
+ */
+export function unwrapPromptResult<T>(result: PromptResult<T>): T {
+  if (result.aborted) {
+    throw new Error(ABORT_ERROR_MESSAGE)
+  }
+  return result.value
+}
+
 // Extended error properties that various libraries add to Error objects
 interface ExtendedErrorProperties {
   status?: number