feat(agent-runtime): Improve abort handling with PromptResult pattern and AbortError class

- Add custom AbortError class for robust abort detection (vs brittle string matching)
- Refactor processFileBlock and handleLargeFile to return PromptResult<T> instead of throwing
- Update write-file.ts handler to check result.aborted and throw AbortError at boundary
- Fix E2E mocks to return promptSuccess() instead of raw strings
- Add comprehensive tests for abort propagation in processFileBlock and loopAgentSteps
- Add tests verifying AbortError results in cancelled status, regular errors in failed status

All 407 agent-runtime tests pass. Manual CLI testing confirmed:
- Ctrl+C shows [response interrupted] and no file corruption
- Follow-up prompts work correctly after abort
- Message history preserved

Author: brandonkachen

common/src/util/__tests__/error-abort.test.ts

@@ -62,24 +62,32 @@ describe('AbortError class', () => {
 })
 
 describe('isAbortError edge cases', () => {
-  describe('exact message matching', () => {
+  describe('message matching with startsWith', () => {
     it('returns true for exact ABORT_ERROR_MESSAGE', () => {
       const error = new Error(ABORT_ERROR_MESSAGE)
       expect(isAbortError(error)).toBe(true)
     })
 
-    it('returns false for message containing ABORT_ERROR_MESSAGE as substring', () => {
-      const error = new Error(`Error: ${ABORT_ERROR_MESSAGE} by system`)
+    it('returns true for message with suffix after ABORT_ERROR_MESSAGE (like AbortError with reason)', () => {
+      // This is the format AbortError uses: 'Request aborted: reason'
+      const error = new Error(`${ABORT_ERROR_MESSAGE}: timeout`)
+      expect(isAbortError(error)).toBe(true)
+    })
+
+    it('returns false for message with non-colon suffix after ABORT_ERROR_MESSAGE', () => {
+      // Only 'Request aborted' or 'Request aborted: <reason>' should match
+      // Other patterns like 'Request aborted by user' should NOT match
+      const error = new Error(`${ABORT_ERROR_MESSAGE} due to user action`)
       expect(isAbortError(error)).toBe(false)
     })
 
-    it('returns false for message with prefix before ABORT_ERROR_MESSAGE', () => {
-      const error = new Error(`Something failed: ${ABORT_ERROR_MESSAGE}`)
+    it('returns false for message containing ABORT_ERROR_MESSAGE as substring (not prefix)', () => {
+      const error = new Error(`Error: ${ABORT_ERROR_MESSAGE} by system`)
       expect(isAbortError(error)).toBe(false)
     })
 
-    it('returns false for message with suffix after ABORT_ERROR_MESSAGE', () => {
-      const error = new Error(`${ABORT_ERROR_MESSAGE} due to timeout`)
+    it('returns false for message with prefix before ABORT_ERROR_MESSAGE', () => {
+      const error = new Error(`Something failed: ${ABORT_ERROR_MESSAGE}`)
       expect(isAbortError(error)).toBe(false)
     })
   })

common/src/util/error.ts

@@ -130,20 +130,37 @@ export function promptAborted(reason?: string): PromptAborted {
  */
 export const ABORT_ERROR_MESSAGE = 'Request aborted'
 
+/**
+ * Custom error class for abort errors.
+ * Use this class instead of generic Error for abort errors to ensure
+ * robust detection via isAbortError() (checks error.name === 'AbortError').
+ */
+export class AbortError extends Error {
+  constructor(reason?: string) {
+    super(reason ? `${ABORT_ERROR_MESSAGE}: ${reason}` : ABORT_ERROR_MESSAGE)
+    this.name = 'AbortError'
+  }
+}
+
 /**
  * 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)
+ * - Errors with message starting with 'Request aborted' (thrown by our code via AbortError)
  * - 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) {
+  // Check for our custom abort error message:
+  // - Exact match: 'Request aborted'
+  // - With reason: 'Request aborted: <reason>' (from AbortError class)
+  if (
+    error.message === ABORT_ERROR_MESSAGE ||
+    error.message.startsWith(`${ABORT_ERROR_MESSAGE}: `)
+  ) {
     return true
   }
   // Check for native AbortError (DOMException or Error with name 'AbortError')
@@ -161,11 +178,11 @@ export function isAbortError(error: unknown): boolean {
  * 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.
+ * @throws {AbortError} When result.aborted is true.
  */
 export function unwrapPromptResult<T>(result: PromptResult<T>): T {
   if (result.aborted) {
-    throw new Error(ABORT_ERROR_MESSAGE)
+    throw new AbortError(result.reason)
   }
   return result.value
 }

packages/agent-runtime/src/__tests__/loop-agent-steps.test.ts

@@ -6,7 +6,7 @@ import {
 } from '@codebuff/common/testing/mock-modules'
 import { setupDbSpies } from '@codebuff/common/testing/mocks/database'
 import { getInitialSessionState } from '@codebuff/common/types/session-state'
-import { promptSuccess } from '@codebuff/common/util/error'
+import { AbortError, promptSuccess } from '@codebuff/common/util/error'
 import { assistantMessage, userMessage } from '@codebuff/common/util/messages'
 import db from '@codebuff/internal/db'
 import {
@@ -807,4 +807,128 @@ describe('loopAgentSteps - runAgentStep vs runProgrammaticStep behavior', () =>
     // Should have output set
     expect(result.agentState.output).toEqual({ result: 'done' })
   })
+
+  describe('abort handling', () => {
+    it('should handle AbortError and finish with cancelled status', async () => {
+      // Test that when an AbortError is thrown (e.g., from a tool handler),
+      // loopAgentSteps catches it, finishes with 'cancelled' status, and returns
+      // an error output indicating the run was cancelled.
+
+      const llmOnlyTemplate = {
+        ...mockTemplate,
+        handleSteps: undefined,
+      }
+
+      const localAgentTemplates = {
+        'test-agent': llmOnlyTemplate,
+      }
+
+      // Track finishAgentRun calls
+      let finishAgentRunStatus: string | undefined
+      const mockFinishAgentRun = mock(async (params: { status: string }) => {
+        finishAgentRunStatus = params.status
+      })
+
+      // Mock promptAiSdkStream to throw an AbortError (simulating user cancellation mid-stream)
+      loopAgentStepsBaseParams.promptAiSdkStream = async function* () {
+        // Yield some content first
+        yield { type: 'text' as const, text: 'Starting work...\n' }
+        // Then throw AbortError to simulate user cancellation
+        throw new AbortError('User pressed Ctrl+C')
+      }
+
+      const result = await loopAgentSteps({
+        ...loopAgentStepsBaseParams,
+        agentType: 'test-agent',
+        localAgentTemplates,
+        finishAgentRun: mockFinishAgentRun,
+      })
+
+      // Verify the output indicates cancellation
+      expect(result.output.type).toBe('error')
+      if (result.output.type === 'error') {
+        expect(result.output.message).toBe('Run cancelled by user')
+      }
+
+      // Verify finishAgentRun was called with 'cancelled' status
+      expect(mockFinishAgentRun).toHaveBeenCalled()
+      expect(finishAgentRunStatus).toBe('cancelled')
+    })
+
+    it('should distinguish AbortError from other errors', async () => {
+      // Test that non-abort errors are NOT treated as cancellations
+
+      const llmOnlyTemplate = {
+        ...mockTemplate,
+        handleSteps: undefined,
+      }
+
+      const localAgentTemplates = {
+        'test-agent': llmOnlyTemplate,
+      }
+
+      // Track finishAgentRun calls
+      let finishAgentRunStatus: string | undefined
+      const mockFinishAgentRun = mock(async (params: { status: string }) => {
+        finishAgentRunStatus = params.status
+      })
+
+      // Mock promptAiSdkStream to throw a regular error (not AbortError)
+      loopAgentStepsBaseParams.promptAiSdkStream = async function* () {
+        yield { type: 'text' as const, text: 'Starting...\n' }
+        throw new Error('Network connection failed')
+      }
+
+      const result = await loopAgentSteps({
+        ...loopAgentStepsBaseParams,
+        agentType: 'test-agent',
+        localAgentTemplates,
+        finishAgentRun: mockFinishAgentRun,
+      })
+
+      // Verify the output indicates an error (not cancellation)
+      expect(result.output.type).toBe('error')
+      if (result.output.type === 'error') {
+        expect(result.output.message).toContain('Network connection failed')
+        expect(result.output.message).not.toBe('Run cancelled by user')
+      }
+
+      // Verify finishAgentRun was called with 'failed' status (not 'cancelled')
+      expect(mockFinishAgentRun).toHaveBeenCalled()
+      expect(finishAgentRunStatus).toBe('failed')
+    })
+
+    it('should handle signal.aborted before loop starts', async () => {
+      // Test that if signal is already aborted when loopAgentSteps is called,
+      // it returns immediately with a cancelled message
+
+      const abortController = new AbortController()
+      abortController.abort() // Abort immediately
+
+      const llmOnlyTemplate = {
+        ...mockTemplate,
+        handleSteps: undefined,
+      }
+
+      const localAgentTemplates = {
+        'test-agent': llmOnlyTemplate,
+      }
+
+      const result = await loopAgentSteps({
+        ...loopAgentStepsBaseParams,
+        agentType: 'test-agent',
+        localAgentTemplates,
+        signal: abortController.signal,
+      })
+
+      // Verify the output indicates cancellation
+      expect(result.output.type).toBe('error')
+      if (result.output.type === 'error') {
+        expect(result.output.message).toBe('Run cancelled by user')
+      }
+
+      // LLM should not have been called since we aborted before starting
+      expect(llmCallCount).toBe(0)
+    })
+  })
 })

packages/agent-runtime/src/__tests__/main-prompt.test.ts

@@ -1,6 +1,7 @@
 import * as analytics from '@codebuff/common/analytics'
 import { TEST_USER_ID } from '@codebuff/common/old-constants'
 import { createTestAgentRuntimeParams } from '@codebuff/common/testing/fixtures/agent-runtime'
+import { promptSuccess } from '@codebuff/common/util/error'
 import {
   AgentTemplateTypes,
   getInitialSessionState,
@@ -105,13 +106,13 @@ describe('mainPrompt', () => {
     // Mock processFileBlock
     spyOn(processFileBlockModule, 'processFileBlock').mockImplementation(
       async (params) => {
-        return {
+        return promptSuccess({
           tool: 'write_file' as const,
           path: params.path,
           content: params.newContent,
           patch: undefined,
           messages: [],
-        }
+        })
       },
     )