docs: add task management and workflow integration documentation

Syncs documentation from cloudflare/agents PR #683
cloudflare/agents#683

Adds comprehensive documentation for the task system including:
- Tasks: Tracked background operations with progress updates
- Durable Tasks: Long-running operations backed by Cloudflare Workflows

New pages:
- /agents/api-reference/tasks/ - Task decorator, TaskContext API, and client updates
- /agents/api-reference/durable-tasks/ - Durable task setup, workflow context methods, and custom workflows

Author: github-actions[bot]

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

@@ -0,0 +1,209 @@
+---
+title: Durable Tasks
+pcx_content_type: concept
+sidebar:
+  order: 12
+
+---
+
+import { Render, 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> {
+  // ...
+}
+```
+
+</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) {
+    // 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
+class MyAgent extends Agent<Env> {
+  @callable()
+  async startCustom(input: { data: string }) {
+    return this.workflow("CUSTOM_WORKFLOW", input);
+  }
+}
+```
+
+</TypeScriptExample>
+
+## 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/tasks.mdx

@@ -0,0 +1,160 @@
+---
+title: Tasks
+pcx_content_type: concept
+sidebar:
+  order: 11
+
+---
+
+import { Render, TypeScriptExample, WranglerConfig } from "~/components";
+
+Tasks are tracked background operations with progress updates, cancellation support, and real-time synchronization to connected clients.
+
+## 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` with:
+
+- `emit(type, data)` - Send events to connected clients
+- `setProgress(n)` - Set progress percentage (0-100)
+- `signal` - AbortSignal for cancellation
+
+<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`:
+
+<TypeScriptExample>
+
+```ts
+// Get a task
+const task = this.tasks.get(taskId);
+
+// List all tasks
+const all = this.tasks.list();
+
+// List by status
+const running = this.tasks.list({ status: "running" });
+
+// Cancel a task
+await this.tasks.cancel(taskId, "User requested");
+
+// Delete completed task
+this.tasks.delete(taskId);
+```
+
+</TypeScriptExample>
+
+## Client Updates
+
+Tasks broadcast updates to all connected WebSocket clients:
+
+<TypeScriptExample>
+
+```tsx
+// 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;
+    // task.status, task.progress, task.events, task.result
+  }
+});
+```
+
+</TypeScriptExample>
+
+## Options
+
+<TypeScriptExample>
+
+```ts
+@task({
+  timeout: "5m",      // Cancel if exceeds duration
+})
+async myTask(input: Input, ctx: TaskContext) {
+  // ...
+}
+```
+
+</TypeScriptExample>
+
+Timeout accepts: `"30s"`, `"5m"`, `"1h"`, or milliseconds.
+
+## 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 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.