Document worker history paging contracts

Author: durable-workflow-ops

docs/polyglot/cli-python-parity.md

@@ -22,6 +22,7 @@ repositories:
 | Query workflow | `tests/fixtures/control-plane/workflow-query-parity.json` |
 | Update workflow | `tests/fixtures/control-plane/workflow-update-parity.json` |
 | Cancel workflow | `tests/fixtures/control-plane/workflow-cancel-parity.json` |
+| Workflow task history page | `tests/fixtures/control-plane/workflow-task-history-parity.json` |
 
 The CLI sends JSON caller payloads directly. The Python SDK wraps the same
 semantic payload in its Avro envelope. Both target the same endpoint and
@@ -195,6 +196,41 @@ Both calls mean `POST /workflows/{workflow_id}/cancel`. Cancellation is
 cooperative: workflow code can observe it and clean up. Use termination only
 for the force-stop operator path.
 
+## Workflow Task History Page
+
+Worker-history paging is a worker-plane operation, not the ordinary
+control-plane run-history listing. Use it when a workflow-task poll response
+contains `next_history_page_token` and the worker needs the next replay page
+for the same leased task.
+
+CLI:
+
+```bash
+dw workflow-task:history workflow-task-231 history-page-2 \
+  --lease-owner=polyglot-worker-231 \
+  --attempt=2 \
+  --json
+```
+
+Python:
+
+```python
+async with client:
+    page = await client.workflow_task_history(
+        task_id="workflow-task-231",
+        next_history_page_token="history-page-2",
+        lease_owner="polyglot-worker-231",
+        workflow_task_attempt=2,
+    )
+```
+
+Both calls mean `POST /worker/workflow-tasks/{task_id}/history` with
+`next_history_page_token`, `lease_owner`, and `workflow_task_attempt` in the
+JSON request body. Both surfaces preserve the canonical server response fields:
+`history_events`, `total_history_events`, and `next_history_page_token`.
+Do not treat the control-plane aliases `events` or `next_page_token` as valid
+worker-history response fields.
+
 ## Parity Checklist
 
 When adding a new CLI or SDK operation, keep the contract language-neutral:

docs/polyglot/cli-reference.md

@@ -196,10 +196,41 @@ worker loops.
 | Command | Purpose | Important options |
 | --- | --- | --- |
 | `dw workflow-task:poll <worker-id>` | Poll one workflow task. | `--task-queue`, `--build-id`, `--poll-request-id`, `--history-page-size`, `--accept-history-encoding`, `--json` |
+| `dw workflow-task:history <task-id> <page-token>` | Fetch the next history page for a leased workflow task. | `--lease-owner`, `--attempt`, `--json` |
 | `dw workflow-task:complete <task-id> <attempt>` | Complete one workflow task with command payloads. | `--lease-owner`, `--complete-result`, `--command`, `--json` |
 | `dw activity:complete <task-id> <attempt-id>` | Complete one leased activity attempt. | `--lease-owner`, input options, `--json` |
 | `dw activity:fail <task-id> <attempt-id>` | Fail one leased activity attempt. | `--lease-owner`, `--message`, `--type`, `--non-retryable`, `--json` |
 
+### Workflow Task History Pages
+
+`workflow-task:history` is the CLI diagnostic wrapper around the worker-plane
+history-page endpoint. Use it only after `workflow-task:poll` returns a leased
+workflow task with `next_history_page_token`; normal workers should let their
+SDK fetch extra history pages.
+
+```bash
+dw workflow-task:history workflow-task-01 history-page-2 \
+  --lease-owner=python-worker-1 \
+  --attempt=2 \
+  --json
+```
+
+JSON output is the server response without field renaming:
+
+```json
+{
+  "history_events": [
+    {"event_id": 2, "event_type": "ActivityScheduled", "payload": {}}
+  ],
+  "total_history_events": 4,
+  "next_history_page_token": "history-page-3"
+}
+```
+
+Automation should read `history_events`, `total_history_events`, and
+`next_history_page_token`. The worker-history endpoint does not use the
+control-plane run-history fields `events` or `next_page_token`.
+
 ## Namespace And Search Attribute Commands
 
 | Command | Purpose | Important options |

docs/polyglot/python.md

@@ -277,6 +277,25 @@ These methods send `X-Durable-Workflow-Protocol-Version` and use `worker_token`
 when one is configured. Prefer the higher-level `Worker` unless you are writing
 an SDK adapter or protocol conformance test.
 
+`workflow_task_history(...)` pages replay history for one already leased
+workflow task. Call it only after `poll_workflow_task(...)` returns
+`next_history_page_token`:
+
+```python
+page = await client.workflow_task_history(
+    task_id="workflow-task-01",
+    next_history_page_token="history-page-2",
+    lease_owner="python-worker-1",
+    workflow_task_attempt=2,
+)
+```
+
+The request body uses `next_history_page_token`, `lease_owner`, and
+`workflow_task_attempt`. The decoded response uses the worker-protocol field
+names `history_events`, `total_history_events`, and
+`next_history_page_token`; it does not use the control-plane run-history names
+`events` or `next_page_token`.
+
 ## Defining Workflows
 
 Workflows are Python classes decorated with `@workflow.defn`. The `run` method is a generator that yields commands to the server.