feat: add checkpointing docs

docs.json

@@ -2572,6 +2572,18 @@
                   "run-cancellation/workflow-cancel-run"
                 ]
               },
+              {
+                "group": "Run Control",
+                "pages": [
+                  "run-control/overview",
+                  "run-control/checkpointing",
+                  "run-control/continue-run",
+                  "run-control/regenerate",
+                  "run-control/fork-run",
+                  "run-control/branch-session",
+                  "run-control/api-reference"
+                ]
+              },
               {
                 "group": "Background Execution",
                 "pages": [

run-control/api-reference.mdx

@@ -0,0 +1,213 @@
+---
+title: API Reference
+description: HTTP endpoints for continuing, forking, branching, and inspecting runs.
+---
+
+All run-control verbs ship as both SDK methods and HTTP endpoints. The HTTP layer is what AgentOS exposes for the FE; the SDK is what you call from your own Python code.
+
+## Endpoint Summary
+
+| Endpoint | Method | What it does |
+|---|---|---|
+| `/agents/{agent_id}/runs/{run_id}/continue` | POST | Resume, regenerate, fork, or follow up on a run |
+| `/agents/{agent_id}/runs/{run_id}/checkpoints` | GET | List checkpoint boundaries for a run |
+| `/agents/{agent_id}/runs/{run_id}/checkpoints/{message_index}` | GET | Snapshot of the run truncated at a boundary |
+| `/agents/{agent_id}/sessions/{session_id}/branch` | POST | Deep-copy a session into a new one |
+
+Team variants exist at `/teams/{team_id}/...` with identical shapes.
+
+## POST `/continue`
+
+Form-encoded body. All fields optional.
+
+| Field | Type | Purpose |
+|---|---|---|
+| `session_id` | string | The session that owns the run (required when the run isn't already loaded server-side) |
+| `requirements` | JSON string | HITL tool results to apply before resuming |
+| `input` | string | New user message to append before the next turn |
+| `continue_from` | string | `"end"`, `"last_user"`, or a numeric message index |
+| `fork` | bool | Clone with a new `run_id` |
+| `regenerate` | bool | Drop the last response and redo (always forks) |
+| `replace_original` | bool | Hide the source from history when regenerating (default `true`) |
+| `additional_instructions` | string | Steering text appended as a user message when regenerating |
+| `stream` | bool | Stream events back as SSE (default `false`) |
+| `background` | bool | Run in a detached task, return immediately (default `false`) |
+
+### Example: HITL resolve
+
+```bash
+curl -X POST "$HOST/agents/{agent_id}/runs/{run_id}/continue" \
+  -F "session_id=sess-xyz" \
+  -F 'requirements=[{"tool_execution":{"tool_call_id":"tc1","result":"approved"}}]'
+```
+
+### Example: Regenerate
+
+```bash
+curl -X POST "$HOST/agents/{agent_id}/runs/{run_id}/continue" \
+  -F "session_id=sess-xyz" \
+  -F "regenerate=true" \
+  -F "additional_instructions=Be more concise"
+```
+
+### Example: Fork at boundary
+
+```bash
+curl -X POST "$HOST/agents/{agent_id}/runs/{run_id}/continue" \
+  -F "session_id=sess-xyz" \
+  -F "continue_from=4" \
+  -F "fork=true" \
+  -F "input=Try a different approach"
+```
+
+### Response
+
+The new `RunOutput` (or the resumed one if same `run_id`). Lineage fields populated when applicable:
+
+| Field | When it's set |
+|---|---|
+| `forked_from_run_id` | Set on any forked run (regenerate, fork, branched session runs) |
+| `forked_from_message_index` | The actual boundary used (may be lower than requested if snapped) |
+| `forked_from_session_id` | Set on runs that came from `branch_session` |
+| `regenerated_from` | Set when `regenerate=True` |
+| `last_checkpoint_at_message_index` | Latest mid-run checkpoint position on `checkpoint="tool-batch"` runs |
+
+## GET `/checkpoints`
+
+List the message boundaries the FE can offer as resume points.
+
+```bash
+curl "$HOST/agents/{agent_id}/runs/{run_id}/checkpoints?session_id=sess-xyz"
+```
+
+### Response
+
+```json
+{
+  "run_id": "run-abc",
+  "session_id": "sess-xyz",
+  "checkpoints": [
+    {
+      "checkpoint_id": "1",
+      "run_id": "run-abc",
+      "session_id": "sess-xyz",
+      "message_index": 5,
+      "continue_from": 5,
+      "status": "RUNNING",
+      "reason": "checkpoint",
+      "created_at": 1781700829,
+      "message_id": "msg-uuid-1",
+      "message_role": "tool",
+      "message_preview": "15.3M",
+      "is_latest": false
+    },
+    {
+      "checkpoint_id": "2",
+      "run_id": "run-abc",
+      "session_id": "sess-xyz",
+      "message_index": 6,
+      "continue_from": 6,
+      "status": "COMPLETED",
+      "reason": "end",
+      "created_at": 1781700835,
+      "message_id": "msg-uuid-2",
+      "message_role": "assistant",
+      "message_preview": "Lagos is largest, then Tokyo...",
+      "is_latest": true
+    }
+  ]
+}
+```
+
+### Fields
+
+| Field | Purpose |
+|---|---|
+| `checkpoint_id` | 1-based display ordinal (Checkpoint 1, 2, 3, ...). Use for UI labels. |
+| `message_index` | Pass back as `continue_from` to resume from this boundary. Pair-safe. |
+| `message_id` | Stable UUID of the message at the boundary. Use for client-side state. |
+| `message_role` | `"user"`, `"assistant"`, or `"tool"`. |
+| `message_preview` | First 120 chars of the boundary message's content. |
+| `reason` | `"checkpoint"` (mid-run barrier) or `"end"` (terminal). |
+| `status` | Run status at the time of the checkpoint. |
+| `is_latest` | `true` for the terminal end-of-transcript entry. |
+
+Every `message_index` returned is pair-safe. Passing it back as `continue_from` will never get snapped.
+
+## GET `/checkpoints/{message_index}`
+
+Return a truncated snapshot of the run at the chosen boundary. The stored run is never mutated.
+
+```bash
+curl "$HOST/agents/{agent_id}/runs/{run_id}/checkpoints/5?session_id=sess-xyz"
+```
+
+### Response
+
+```json
+{
+  "checkpoint": { ... same shape as a timeline entry ... },
+  "snapshot": {
+    "run_id": "run-abc",
+    "messages": [ ... truncated to messages[:5] ... ],
+    "tools": [ ... only tools referenced by surviving messages ... ],
+    "requirements": [ ... only requirements referencing surviving tool_call_ids ... ],
+    "last_checkpoint_at_message_index": 5,
+    ...
+  }
+}
+```
+
+Use to preview "this is what the run will look like if you continue from here" before firing the actual `/continue`.
+
+## POST `/sessions/{session_id}/branch`
+
+Deep-copy every run from the source session into a new session.
+
+```bash
+curl -X POST "$HOST/agents/{agent_id}/sessions/{session_id}/branch" \
+  -F "user_id=user-123"
+```
+
+### Response
+
+```json
+{
+  "session_id": "<new-uuid>",
+  "branched_from": "<source-session-id>"
+}
+```
+
+The caller's `user_id` scopes the source session read. Users cannot branch sessions they don't own.
+
+## Status Codes
+
+| Code | Meaning |
+|---|---|
+| 200 | Run/session successfully advanced/branched/inspected |
+| 400 | Invalid body (e.g. `continue_from` not parseable, `message_index` out of range) |
+| 404 | Run, session, or agent/team not found |
+| 409 | Run state incompatible with the requested action (e.g. continuing a `CANCELLED` run) |
+| 500 | Internal error |
+
+## Team Endpoints
+
+Identical surface at `/teams/{team_id}/...`:
+
+- `POST /teams/{team_id}/runs/{run_id}/continue`
+- `GET /teams/{team_id}/runs/{run_id}/checkpoints`
+- `GET /teams/{team_id}/runs/{run_id}/checkpoints/{message_index}`
+- `POST /teams/{team_id}/sessions/{session_id}/branch`
+
+Same request shape, same response shape. Team runs have `team_id` instead of `agent_id` and a `member_responses` array on the run.
+
+## SDK Equivalents
+
+| HTTP | SDK |
+|---|---|
+| `POST /runs/{run_id}/continue` | `agent.continue_run(run_id=..., ...)` |
+| `POST /sessions/{session_id}/branch` | `agent.branch_session(session_id=...)` |
+| `GET /runs/{run_id}/checkpoints` | Inspect `run_output.messages` directly, or use the HTTP endpoint |
+| `GET /runs/{run_id}/checkpoints/{i}` | (HTTP-only — derive locally if needed) |
+
+All async variants exist (`acontinue_run`, `abranch_session`).

run-control/branch-session.mdx

@@ -0,0 +1,107 @@
+---
+title: Branch a Session
+description: Deep-copy every run from a session into a brand-new session.
+---
+
+`branch_session` clones an entire session — every run, plus session state and metadata — into a new session with a fresh `session_id`. Use it to spin off an independent conversation thread from a known starting state.
+
+## Basic Usage
+
+```python
+new_session_id = agent.branch_session(session_id="sess-original")
+
+# Continue in the new session — independent of the original
+result = agent.run(
+    input="What if we went a different direction?",
+    session_id=new_session_id,
+)
+```
+
+The new session contains deep copies of every run. The original session is untouched.
+
+## Branch vs Fork
+
+| | Branch session | Fork run |
+|---|---|---|
+| Granularity | Whole session | One run |
+| Result | New `session_id`, all runs deep-copied | New `run_id`, sibling in same session |
+| Endpoint | `POST /sessions/{session_id}/branch` | `POST /runs/{run_id}/continue` with `fork=True` |
+| Lineage field on new entity | `branched_from` on the new session | `forked_from_run_id` on the new run |
+
+Use **branch** when you want a whole new conversation thread that starts from the current state of an existing one. Use **fork** when you want to try an alternative path that lives next to the original.
+
+## When to Use
+
+| Scenario | Use |
+|---|---|
+| "Save this conversation, let me try a different approach in a new thread" | Branch |
+| "Rewind to message 3 and explore an alternative" | Fork |
+| "Try the last response again with steering" | Regenerate |
+| "Resume this paused run with tool results" | Continue (HITL) |
+
+## What Gets Copied
+
+- All `RunOutput` rows in the source session
+- `session_data` (including `session_state`)
+- `session_name` and metadata
+
+What does NOT carry over:
+
+- Live runs in flight on the source (only persisted runs are copied)
+- Cross-session memory (memory is keyed by `user_id`, shared across sessions of that user by design)
+
+## User Scoping
+
+`branch_session` reads the source session with the caller's `user_id`. A user cannot branch another user's session. Pass `user_id` explicitly if you're calling outside an authenticated request context:
+
+```python
+new_session_id = agent.branch_session(
+    session_id="sess-original",
+    user_id="user-123",
+)
+```
+
+## Teams
+
+`Team.branch_session` works the same way:
+
+```python
+new_team_session_id = team.branch_session(session_id="team-sess-original")
+```
+
+All team runs and any nested member runs from the source are deep-copied. The new team session is independent.
+
+## HTTP
+
+```bash
+curl -X POST "$HOST/agents/{agent_id}/sessions/{session_id}/branch" \
+  -F "user_id=user-123"
+```
+
+Returns the new `session_id`. See [API Reference](/run-control/api-reference).
+
+## Lineage Tracking
+
+The branched session carries `branched_from = <source session_id>`. Each copied run carries `forked_from_session_id = <source session_id>` so you can render the lineage in a UI.
+
+## Examples
+
+### Agents
+
+| Example | What it shows |
+|---|---|
+| [Branch a session](https://github.com/agno-agi/agno/blob/main/cookbook/02_agents/21_fork_session/01_fork_session.py) | Spins off a new session from an existing one, runs an independent follow-up in each, and verifies the original session is untouched. |
+
+### Teams
+
+| Example | What it shows |
+|---|---|
+| [Branch a team session](https://github.com/agno-agi/agno/blob/main/cookbook/03_teams/26_fork_session/01_fork_session.py) | Team variant. All team runs and nested member runs are deep-copied; the new session is fully independent. |
+
+## Next Steps
+
+| Task | Guide |
+|---|---|
+| Sibling run in the same session | [Fork a Run](/run-control/fork-run) |
+| Redo the last response | [Regenerate](/run-control/regenerate) |
+| Persist sessions across requests | [Persisting Sessions](/sessions/persisting-sessions) |