feat(client-js): add cancel() method alias for Run class (#11417)

## Description

Add a new cancel() method as a more concise alias for cancelRun() in the
Run class. This provides better developer ergonomics while maintaining
backward compatibility.

Changes:
- Add cancel() method to Run class with comprehensive JSDoc
documentation
- Mark cancelRun() as deprecated with pointer to cancel()
- Document abort signal behavior with practical examples
- Update client-js SDK documentation with cancel() method
- Update Run.cancel() reference documentation
- Add 'canceled' status to Run Status documentation

The new method includes detailed documentation about:
- How cancellation works (abort signal, status updates)
- How steps can respond to cancellation
- Practical examples of cancellation-aware steps

## Related Issue(s)

slack

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a simplified cancel() action for workflow runs as the preferred
cancellation API; legacy cancelRun() remains deprecated for
compatibility.
* Cancellation now returns a confirmation object (message) and sets run
status to "canceled".

* **Documentation**
* Expanded docs on cancellation behavior, updated return details, and
added guidance and examples for abort-signal-aware step cleanup and
cancellation patterns.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: roaminro

.changeset/twenty-worms-study.md

@@ -0,0 +1,5 @@
+---
+'@mastra/client-js': patch
+---
+
+Add `cancel()` method as an alias for `cancelRun()` in the Run class. The new method provides a more concise API while maintaining backward compatibility. Includes comprehensive documentation about abort signals and how steps can respond to cancellation.

client-sdks/client-js/src/resources/run.ts

@@ -71,13 +71,81 @@ export class Run extends BaseResource {
   /**
    * Cancels a specific workflow run by its ID
    * @returns Promise containing a success message
+   * @deprecated Use `cancel()` instead
    */
   cancelRun(): Promise<{ message: string }> {
     return this.request(`/api/workflows/${this.workflowId}/runs/${this.runId}/cancel`, {
       method: 'POST',
     });
   }
 
+  /**
+   * Cancels a workflow run.
+   *
+   * This method aborts any running steps and updates the workflow status to 'canceled' .
+   * It works for both actively running workflows and suspended/waiting workflows.
+   *
+   * ## How cancellation works
+   *
+   * When called, the workflow will:
+   * 1. **Trigger the abort signal** - Uses the standard Web API AbortSignal to notify running steps
+   * 2. **Prevent subsequent steps** - No further steps will be executed
+   *
+   * ## Abort signal behavior
+   *
+   * Steps that check the `abortSignal` parameter can respond to cancellation:
+   * - Steps can listen to the 'abort' event: `abortSignal.addEventListener('abort', callback)`
+   * - Steps can check if already aborted: `if (abortSignal.aborted) { ... }`
+   * - Useful for canceling timeouts, network requests, or long-running operations
+   *
+   * **Note:** Steps must actively check the abort signal to be canceled mid-execution.
+   * Steps that don't check the signal will run to completion, but subsequent steps won't execute.
+   *
+   * @returns Promise that resolves with `{ message: 'Workflow run canceled' }` when cancellation succeeds
+   * @throws {HTTPException} 400 - If workflow ID or run ID is missing
+   * @throws {HTTPException} 404 - If workflow or workflow run is not found
+   *
+   * @example
+   * ```typescript
+   * const run = await workflow.createRun({ runId: 'run-123' });
+   * await run.cancel();
+   * // Returns: { message: 'Workflow run canceled' }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Example of a step that responds to cancellation
+   * const step = createStep({
+   *   id: 'long-running-step',
+   *   execute: async ({ inputData, abortSignal, abort }) => {
+   *     const timeout = new Promise((resolve) => {
+   *       const timer = setTimeout(() => resolve('done'), 10000);
+   *
+   *       // Clean up if canceled
+   *       abortSignal.addEventListener('abort', () => {
+   *         clearTimeout(timer);
+   *         resolve('canceled');
+   *       });
+   *     });
+   *
+   *     const result = await timeout;
+   *
+   *     // Check if aborted after async operation
+   *     if (abortSignal.aborted) {
+   *       return abort(); // Stop execution
+   *     }
+   *
+   *     return { result };
+   *   }
+   * });
+   * ```
+   */
+  cancel(): Promise<{ message: string }> {
+    return this.request(`/api/workflows/${this.workflowId}/runs/${this.runId}/cancel`, {
+      method: 'POST',
+    });
+  }
+
   /**
    * Starts a workflow run synchronously without waiting for the workflow to complete
    * @param params - Object containing the inputData, initialState and requestContext

docs/src/content/en/reference/client-js/workflows.mdx

@@ -145,6 +145,21 @@ await run.resume({
 });
 ```
 
+### cancel()
+
+Cancel a running workflow:
+
+```typescript
+const run = await workflow.createRun({ runId: existingRunId });
+
+const result = await run.cancel();
+// Returns: { message: 'Workflow run canceled' }
+```
+
+This method stops any running steps and prevents subsequent steps from executing. Steps that check the `abortSignal` parameter can respond to cancellation by cleaning up resources (timeouts, network requests, etc.).
+
+See the [Run.cancel()](/reference/v1/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
+
 ### stream()
 
 Stream workflow execution for real-time updates:

docs/src/content/en/reference/workflows/run-methods/cancel.mdx

@@ -7,12 +7,15 @@ description: Documentation for the `Run.cancel()` method in workflows, which can
 
 The `.cancel()` method cancels a workflow run, stopping execution and cleaning up resources.
 
+This method aborts any running steps and updates the workflow status to 'canceled'. It works for both actively running workflows and suspended/waiting workflows.
+
 ## Usage example
 
 ```typescript
 const run = await workflow.createRun();
 
 await run.cancel();
+// Returns: { message: 'Workflow run canceled' }
 ```
 
 ## Parameters
@@ -34,14 +37,31 @@ await run.cancel();
   content={[
     {
       name: "result",
-      type: "Promise<void>",
+      type: "Promise<{ message: string }>",
       description:
-        "A promise that resolves when the workflow run has been cancelled",
+        "A promise that resolves with { message: 'Workflow run canceled' } when cancellation succeeds",
     },
   ]}
 />
 
-## Extended usage example
+## How cancellation works
+
+When called, the workflow will:
+1. **Trigger the abort signal** - Uses the standard Web API AbortSignal to notify running steps
+2. **Prevent subsequent steps** - No further steps will be executed
+
+## Abort signal behavior
+
+Steps that check the `abortSignal` parameter can respond to cancellation:
+- Steps can listen to the 'abort' event: `abortSignal.addEventListener('abort', callback)`
+- Steps can check if already aborted: `if (abortSignal.aborted) { ... }`
+- Useful for cancelling timeouts, network requests, or long-running operations
+
+**Note:** Steps must actively check the abort signal to be canceled mid-execution. Steps that don't check the signal will run to completion, but subsequent steps won't execute.
+
+## Extended usage examples
+
+### Cancelling a workflow on error
 
 ```typescript
 const run = await workflow.createRun();
@@ -53,6 +73,34 @@ try {
 }
 ```
 
+### Creating a step that responds to cancellation
+
+```typescript
+const step = createStep({
+  id: 'long-running-step',
+  execute: async ({ inputData, abortSignal, abort }) => {
+    const timeout = new Promise((resolve) => {
+      const timer = setTimeout(() => resolve('done'), 10000);
+      
+      // Clean up if canceled
+      abortSignal.addEventListener('abort', () => {
+        clearTimeout(timer);
+        resolve('canceled');
+      });
+    });
+    
+    const result = await timeout;
+    
+    // Check if aborted after async operation
+    if (abortSignal.aborted) {
+      return abort(); // Stop execution
+    }
+    
+    return { result };
+  }
+});
+```
+
 ## Related
 
 - [Workflows overview](/docs/v1/workflows/overview#running-workflows)

docs/src/content/en/reference/workflows/run.mdx

@@ -53,8 +53,8 @@ if (result.status === "suspended") {
     },
     {
       name: "cancel",
-      type: "() => Promise<void>",
-      description: "Cancels the workflow execution",
+      type: "() => Promise<{ message: string }>",
+      description: "Cancels the workflow execution, stopping any running steps and preventing subsequent steps from executing",
       required: true,
     },
     {
@@ -102,6 +102,12 @@ A workflow run's `status` indicates its current execution state. The possible va
       description:
         "Workflow execution is paused waiting for resume, with suspended step information",
     },
+    {
+      name: "canceled",
+      type: "string",
+      description:
+        "Workflow execution was canceled via the cancel() method, stopping any running steps and preventing subsequent steps from executing",
+    },
   ]}
 />