Add task management system documentation

Adds comprehensive documentation for the new task management system from PR #683:

- New Tasks API reference documenting @task() decorator, TaskContext methods, and task lifecycle management
- New Durable Tasks guide covering long-running operations backed by Cloudflare Workflows
- Updated sidebar ordering to logically place tasks documentation after state management
- Adjusted navigation order for browse-the-web, HTTP/SSE, RAG, and WebSockets pages

These changes document the new @task() and @task({ durable: true }) decorators that enable tracked background operations with real-time progress updates, cancellation support, and WebSocket broadcasting to connected clients.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: github-actions[bot]

src/content/docs/agents/api-reference/browse-the-web.mdx

@@ -2,7 +2,7 @@
 title: Browse the web
 pcx_content_type: concept
 sidebar:
-  order: 7
+  order: 9
 ---
 
 import {

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

@@ -0,0 +1,210 @@
+---
+title: Durable Tasks
+pcx_content_type: concept
+sidebar:
+  order: 8
+
+---
+
+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+
+Durable tasks are long-running operations backed by [Cloudflare Workflows](/workflows/). They survive agent restarts and can run for hours or days.
+
+## 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> {
+  // Your agent code
+}
+```
+
+</TypeScriptExample>
+
+2. Add the workflow binding to your configuration:
+
+<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";
+
+export class MyAgent extends Agent<Env> {
+  @task({ durable: true })
+  async longAnalysis(input: { repoUrl: string }, ctx: TaskContext) {
+    // Each step is checkpointed - survives restarts
+    const files = await ctx.step("fetch", () => fetchRepoFiles(input.repoUrl));
+
+    // Durable sleep - can wait for hours or days
+    await ctx.sleep("rate-limit", "1h");
+
+    const analysis = await ctx.step("analyze", () => analyzeFiles(files));
+
+    return analysis;
+  }
+}
+```
+
+</TypeScriptExample>
+
+## Durable Context Methods
+
+Durable tasks have additional `TaskContext` methods:
+
+### ctx.step(name, fn)
+
+Execute a checkpointed step. If the workflow restarts, completed steps are skipped and their results are replayed.
+
+<TypeScriptExample>
+
+```ts
+const data = await ctx.step("fetch-data", async () => {
+  return await fetch(url).then((r) => r.json());
+});
+```
+
+</TypeScriptExample>
+
+### ctx.sleep(name, duration)
+
+Pause execution for a duration. The workflow hibernates and resumes automatically.
+
+<TypeScriptExample>
+
+```ts
+await ctx.sleep("wait", "30m");
+await ctx.sleep("daily-check", "24h");
+```
+
+</TypeScriptExample>
+
+Accepts: `"30s"`, `"5m"`, `"1h"`, `"7d"`, or `"30 seconds"`, `"5 minutes"`.
+
+### ctx.waitForEvent(name, options)
+
+Wait for an external event (human approval, webhook).
+
+<TypeScriptExample>
+
+```ts
+const approval = await ctx.waitForEvent("approval", {
+  type: "user-approved",
+  timeout: "24h"
+});
+```
+
+</TypeScriptExample>
+
+:::note
+
+`waitForEvent` is only available in durable tasks.
+
+:::
+
+## Retry Configuration
+
+Configure automatic retries 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 (minutes to days)
+- Multi-step workflows with checkpoints
+- Operations that must survive restarts
+- Tasks requiring durable sleep or external events
+
+## Custom Workflows
+
+For advanced control, extend `AgentWorkflow` instead:
+
+<TypeScriptExample>
+
+```ts
+import { AgentWorkflow, type WorkflowTaskContext } from "agents";
+
+export class CustomWorkflow extends AgentWorkflow<Env, { input: string }> {
+  async run(ctx: WorkflowTaskContext<{ input: string }>) {
+    ctx.emit("started");
+
+    const result = await ctx.step("process", async () => {
+      return processInput(ctx.params.input);
+    });
+
+    ctx.setProgress(100);
+    return result;
+  }
+}
+```
+
+</TypeScriptExample>
+
+Then dispatch it with `this.workflow()`:
+
+<TypeScriptExample>
+
+```ts
+export class MyAgent extends Agent<Env> {
+  @callable()
+  async startCustom(input: { data: string }) {
+    return this.workflow("CUSTOM_WORKFLOW", input);
+  }
+}
+```
+
+</TypeScriptExample>
+
+## Related resources
+
+- [Workflows documentation](/workflows/)
+- [Tasks API reference](/agents/api-reference/tasks/)

src/content/docs/agents/api-reference/http-sse.mdx

@@ -2,7 +2,7 @@
 title: HTTP and Server-Sent Events
 pcx_content_type: concept
 sidebar:
-  order: 8
+  order: 10
 
 ---
 

src/content/docs/agents/api-reference/rag.mdx

@@ -2,7 +2,7 @@
 title: Retrieval Augmented Generation
 pcx_content_type: concept
 sidebar:
-  order: 9
+  order: 11
 
 ---