Add task management and durable tasks documentation

Syncs documentation for cloudflare/agents PR #683 which adds:
- @task() decorator for tracked background operations
- Task management API (get, list, cancel, delete)
- Durable tasks with Cloudflare Workflows integration
- Real-time task updates via WebSocket

Related to: cloudflare/agents#683

Author: github-actions[bot]

src/content/docs/agents/api-reference/durable-tasks.mdx

@@ -0,0 +1,187 @@
+---
+title: Durable Tasks
+pcx_content_type: concept
+sidebar:
+  order: 7
+
+---
+
+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+
+Durable tasks are long-running operations backed by [Cloudflare Workflows](/workflows/). They survive agent restarts and automatically retry on failure. Use durable tasks when operations need to run for extended periods or require guaranteed completion.
+
+## Setup
+
+1. Export `DurableTaskWorkflow` from your worker:
+
+<TypeScriptExample>
+
+```ts
+// src/index.ts
+import { Agent, routeAgentRequest, DurableTaskWorkflow } from "agents";
+
+export { DurableTaskWorkflow };
+
+export class MyAgent extends Agent<Env> {
+  // ...
+}
+```
+
+</TypeScriptExample>
+
+2. Add the workflow binding to `wrangler.jsonc`:
+
+<WranglerConfig>
+
+```jsonc
+{
+  "workflows": [
+    {
+      "name": "durable-tasks",
+      "binding": "DURABLE_TASKS_WORKFLOW",
+      "class_name": "DurableTaskWorkflow"
+    }
+  ]
+}
+```
+
+</WranglerConfig>
+
+## Usage
+
+Mark a task as durable with `durable: true`:
+
+<TypeScriptExample>
+
+```ts
+import { Agent, task, type TaskContext } from "agents";
+
+class MyAgent extends Agent<Env> {
+  @task({ durable: true })
+  async longAnalysis(input: { repoUrl: string }, ctx: TaskContext) {
+    ctx.emit("started");
+    const files = await fetchRepoFiles(input.repoUrl);
+    ctx.setProgress(50);
+    const analysis = await analyzeFiles(files);
+    return analysis;
+  }
+}
+```
+
+</TypeScriptExample>
+
+Durable tasks provide:
+
+- **Automatic retries** on failure (configurable)
+- **Survives restarts** - the workflow engine manages execution
+- **Real-time updates** via `ctx.emit()` and `ctx.setProgress()`
+
+## Retry Configuration
+
+Configure automatic retry behavior for durable tasks:
+
+<TypeScriptExample>
+
+```ts
+@task({
+  durable: true,
+  retry: {
+    limit: 3,
+    delay: "10s",
+    backoff: "exponential"
+  }
+})
+async unreliableTask(input: Input, ctx: TaskContext) {
+  // Automatically retries on failure
+}
+```
+
+</TypeScriptExample>
+
+## When to Use Durable Tasks
+
+Use `@task()` (simple) for:
+
+- Operations under 30 seconds
+- Tasks that can restart from scratch
+
+Use `@task({ durable: true })` for:
+
+- Long-running operations that need retry guarantees
+- Operations that must survive agent restarts
+
+## Custom Workflows
+
+For multi-step workflows with individual checkpoints, extend `AgentWorkflow`:
+
+<TypeScriptExample>
+
+```ts
+import { AgentWorkflow, type WorkflowTaskContext } from "agents";
+
+export class AnalysisWorkflow extends AgentWorkflow<Env, { repoUrl: string }> {
+  async run(ctx: WorkflowTaskContext<{ repoUrl: string }>) {
+    // Each step is checkpointed - survives restarts
+    const files = await ctx.step("fetch", async () => {
+      ctx.emit("phase", { name: "fetching" });
+      return fetchRepoFiles(ctx.params.repoUrl);
+    });
+
+    // Durable sleep - can wait for hours or days
+    await ctx.sleep("rate-limit", "1h");
+
+    return await ctx.step("analyze", async () => {
+      ctx.setProgress(50);
+      return analyzeFiles(files);
+    });
+  }
+}
+```
+
+</TypeScriptExample>
+
+Add to `wrangler.jsonc`:
+
+<WranglerConfig>
+
+```jsonc
+{
+  "workflows": [
+    {
+      "name": "analysis-workflow",
+      "binding": "ANALYSIS_WORKFLOW",
+      "class_name": "AnalysisWorkflow"
+    }
+  ]
+}
+```
+
+</WranglerConfig>
+
+Dispatch the workflow via `this.workflow()`:
+
+<TypeScriptExample>
+
+```ts
+class MyAgent extends Agent<Env> {
+  @callable()
+  async startAnalysis(input: { repoUrl: string }) {
+    return this.workflow("ANALYSIS_WORKFLOW", input);
+  }
+}
+```
+
+</TypeScriptExample>
+
+### WorkflowTaskContext Methods
+
+Custom workflows have access to:
+
+- `ctx.step(name, fn)` - Checkpointed step, replayed on restart
+- `ctx.sleep(name, duration)` - Durable sleep (for example, `"1h"`, `"7d"`)
+- `ctx.emit(type, data)` - Send events to clients
+- `ctx.setProgress(n)` - Set progress percentage
+
+## Example
+
+Refer to the [task-runner example](https://github.com/cloudflare/agents/tree/main/examples/task-runner) for a complete implementation with both simple and durable tasks.

src/content/docs/agents/api-reference/task-management.mdx

@@ -0,0 +1,162 @@
+---
+title: Task management
+pcx_content_type: concept
+sidebar:
+  order: 6
+
+---
+
+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+
+Tasks are tracked background operations with progress updates, cancellation support, and real-time synchronization to connected clients. Use the `@task()` decorator to mark methods as tracked tasks that provide visibility into long-running operations.
+
+## Quick Start
+
+Use the `@task()` decorator to mark a method as a tracked task:
+
+<TypeScriptExample>
+
+```ts
+import { Agent, task, type TaskContext } from "agents";
+
+class MyAgent extends Agent<Env> {
+  @task({ timeout: "5m" })
+  async processData(input: { url: string }, ctx: TaskContext) {
+    ctx.emit("started", { url: input.url });
+    ctx.setProgress(25);
+
+    const data = await fetch(input.url);
+    ctx.setProgress(75);
+
+    return { processed: true };
+  }
+}
+```
+
+</TypeScriptExample>
+
+The client receives real-time updates automatically via WebSocket.
+
+## TaskContext
+
+Every task method receives a `TaskContext` as the second parameter with:
+
+- `emit(type, data)` - Send custom events to connected clients
+- `setProgress(n)` - Set progress percentage (0-100)
+- `signal` - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for cancellation detection
+
+<TypeScriptExample>
+
+```ts
+@task({ timeout: "2m" })
+async analyze(input: Input, ctx: TaskContext) {
+  ctx.emit("phase", { name: "fetching" });
+
+  if (ctx.signal.aborted) {
+    throw new Error("Cancelled");
+  }
+
+  ctx.setProgress(50);
+  // ...
+}
+```
+
+</TypeScriptExample>
+
+## Managing Tasks
+
+Access tasks via `this.tasks` within your Agent methods:
+
+<TypeScriptExample>
+
+```ts
+// Get a specific task
+const task = this.tasks.get(taskId);
+
+// List all tasks
+const all = this.tasks.list();
+
+// List tasks by status
+const running = this.tasks.list({ status: "running" });
+
+// Cancel a task
+await this.tasks.cancel(taskId, "User requested");
+
+// Delete a completed task
+this.tasks.delete(taskId);
+```
+
+</TypeScriptExample>
+
+## Client Updates
+
+Tasks broadcast updates to all connected WebSocket clients via the `CF_AGENT_TASK_UPDATE` message type:
+
+<TypeScriptExample>
+
+```ts
+// React client
+const agent = useAgent({ agent: "my-agent", name: "default" });
+
+agent.addEventListener("message", (event) => {
+  const data = JSON.parse(event.data);
+  if (data.type === "CF_AGENT_TASK_UPDATE") {
+    const { taskId, task } = data;
+    // Access: task.status, task.progress, task.events, task.result
+  }
+});
+```
+
+</TypeScriptExample>
+
+## Task Options
+
+Configure task behavior with decorator options:
+
+<TypeScriptExample>
+
+```ts
+@task({
+  timeout: "5m",      // Cancel if exceeds duration
+})
+async myTask(input: Input, ctx: TaskContext) {
+  // ...
+}
+```
+
+</TypeScriptExample>
+
+Timeout accepts duration strings (`"30s"`, `"5m"`, `"1h"`) or milliseconds as a number.
+
+## Task Status
+
+Tasks transition through these states:
+
+- `pending` - Created, waiting to run
+- `running` - Currently executing
+- `completed` - Finished successfully
+- `failed` - Threw an error
+- `aborted` - Cancelled or timed out
+
+## Durable Tasks
+
+For long-running operations that need to survive agent restarts, use durable tasks backed by [Cloudflare Workflows](/workflows/):
+
+<TypeScriptExample>
+
+```ts
+@task({ durable: true })
+async longProcess(input: Input, ctx: TaskContext) {
+  // Durable step - survives restarts
+  const data = await ctx.step("fetch", () => fetchData(input));
+
+  // Durable sleep - can sleep for days
+  await ctx.sleep("rate-limit", "1h");
+
+  return await ctx.step("process", () => process(data));
+}
+```
+
+</TypeScriptExample>
+
+Refer to [Durable Tasks](/agents/api-reference/durable-tasks/) for setup and details.