docs(agentserver-skills): correct API guidance that would misguide coding agents

Reviewed all four standalone skills against the actual package surface and fixed
claims that produce broken code:

durable-task-skill:
- Remove the broken 'from ...durable import ... Suspended' (Suspended is an
  internal _Suspended sentinel, not exported -> ImportError).
- Fix local-provider env vars: the LocalFileTaskProvider roots at
  ${AGENTSERVER_DURABLE_ROOT:-~/.durable}/tasks/ and the force-local override is
  AGENTSERVER_TASKS_BACKEND=local (the doc's ~/.durable-tasks/ +
  AGENTSERVER_DURABLE_TASKS_PATH were wrong/legacy).

responses-skill:
- context.durable_metadata / DurableMetadataNamespace does not exist; the real
  handler metadata facade is context.conversation_chain_metadata
  (ConversationChainMetadataNamespace, has .flush()). Fixed surface table +
  decision shortcut.
- Import CreateResponse and ResponseEventStream from the public top-level
  azure.ai.agentserver.responses (not the private models._generated /
  streaming._event_stream modules).

streaming-skill:
- use_file_backed_replay takes storage_dir=, not root= (2 spots).

invocations-skill verified correct (invoke_handler/get_invocation_handler/
cancel_invocation_handler/ws_handler/request.state.session_id all real) — no change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: RaviPidaparthi

sdk/agentserver/skills/durable-task-skill.md

@@ -62,7 +62,7 @@ Use `@task` when **any** of these apply:
 ## Minimal pattern
 
 ```python
-from azure.ai.agentserver.core.durable import task, TaskContext, Suspended
+from azure.ai.agentserver.core.durable import task, TaskContext
 
 @task(name="my_agent", steerable=True)
 async def my_agent(ctx: TaskContext[dict]) -> dict:
@@ -152,9 +152,10 @@ In hosted environments (`FOUNDRY_HOSTING_ENVIRONMENT` set by the platform)
 task-storage API automatically — no opt-in env var required.
 
 In local development (no `FOUNDRY_HOSTING_ENVIRONMENT`) `@task` uses
-`LocalFileTaskProvider` rooted at `~/.durable-tasks/` (override with
-`AGENTSERVER_DURABLE_TASKS_PATH` for tests). No service dependency for
-local iteration.
+`LocalFileTaskProvider` rooted at `${AGENTSERVER_DURABLE_ROOT:-~/.durable}/tasks/`
+(override the root with `AGENTSERVER_DURABLE_ROOT`). No service dependency for
+local iteration. To force the local backend even when hosted-detection would
+otherwise pick the hosted provider, set `AGENTSERVER_TASKS_BACKEND=local`.
 
 ## Packaging — private preview wheels
 
@@ -183,7 +184,7 @@ Consume the checked-in wheels per:
 | LangGraph integration | [`samples/durable_langgraph/`](https://github.com/Azure/azure-sdk-for-python/tree/refs/heads/feature/agentserver-durable-tasks/sdk/agentserver/azure-ai-agentserver-invocations/samples/durable_langgraph) |
 
 Read the developer guide first — it covers `EntryMode`, retry semantics,
-`Suspended`, steering queue backpressure, cancel-cause booleans
+multi-turn suspend/resume, steering queue backpressure, cancel-cause booleans
 (`timeout_exceeded`, `cancel_requested`, `pending_input_count`), shutdown
 via `ctx.exit_for_recovery()`, and the patterns referenced above. The
 samples ground the API in working code.

sdk/agentserver/skills/responses-skill.md

@@ -72,8 +72,8 @@ from azure.ai.agentserver.responses import (
     ResponsesAgentServerHost,
     ResponseContext,
     TextResponse,
+    CreateResponse,
 )
-from azure.ai.agentserver.responses.models._generated import CreateResponse
 
 app = ResponsesAgentServerHost()
 
@@ -102,7 +102,7 @@ streaming partials, structured outputs), use `ResponseEventStream` and
 yield events directly:
 
 ```python
-from azure.ai.agentserver.responses.streaming._event_stream import ResponseEventStream
+from azure.ai.agentserver.responses import ResponseEventStream
 
 @app.response_handler
 async def my_handler(request, context, cancellation_signal):
@@ -163,7 +163,7 @@ When opted in, the handler also sees:
 | `context.is_recovery: bool` | `True` on a crash-recovered re-entry |
 | `context.is_steered_turn: bool` | `True` on the drain re-entry that follows a steering input |
 | `context.pending_input_count: int` | Live count of queued steering inputs |
-| `context.durable_metadata: DurableMetadataNamespace` | `MutableMapping` for handler-managed checkpoint state (small — watermarks, dedup tokens, NOT full conversation history). `await context.durable_metadata.flush()` for at-most-once side-effect fencing before an upstream call with observable side effects |
+| `context.conversation_chain_metadata: ConversationChainMetadataNamespace` | `MutableMapping` for handler-managed checkpoint state (small — watermarks, dedup tokens, NOT full conversation history). `await context.conversation_chain_metadata.flush()` for at-most-once side-effect fencing before an upstream call with observable side effects |
 | `await context.exit_for_recovery()` | Recovery primitive — `return await context.exit_for_recovery()` to leave the response `in_progress` so the next-lifetime recovery scanner picks it up |
 
 ## Hosted vs local
@@ -231,4 +231,4 @@ in working code.
 | OpenAI Chat Completions API endpoint | ❌ | Different protocol — use a different host. |
 | Free-form invocations-protocol agent | ❌ | Use the `agentserver-durable-tasks` + `agentserver-streaming` skills directly. |
 | Server-to-server background job with no HTTP surface | ❌ | Use the `@task` primitive directly. |
-| Persist conversation history in `context.durable_metadata` | ❌ | Wrong — `durable_metadata` is for small watermarks. Use your own DB or framework store (LangGraph SqliteSaver, etc.) for content. |
+| Persist conversation history in `context.conversation_chain_metadata` | ❌ | Wrong — `conversation_chain_metadata` is for small watermarks. Use your own DB or framework store (LangGraph SqliteSaver, etc.) for content. |

sdk/agentserver/skills/streaming-skill.md

@@ -98,7 +98,7 @@ subscriber both call it with the same id and get the **same**
 |---|---|---|---|
 | `use_in_memory_live()` *(default)* | Single subscriber attaches before the producer; lowest memory. | No — late subscribers miss earlier events. | No. |
 | `use_in_memory_replay(cursor_fn=..., ttl_seconds=...)` | Late subscribers / disconnect+reconnect within the same process; cursor-based catch-up. | Yes, up to TTL. | No. |
-| `use_file_backed_replay(root=..., cursor_fn=...)` | `@task` handler that can crash and recover; subscribers need monotonic event continuity across the crash boundary. | Yes, across process restarts for the same stream id + on-disk dir. | Yes. |
+| `use_file_backed_replay(storage_dir=..., cursor_fn=...)` | `@task` handler that can crash and recover; subscribers need monotonic event continuity across the crash boundary. | Yes, across process restarts for the same stream id + on-disk dir. | Yes. |
 
 Call exactly **one** configurator at app startup. Don't switch
 backings mid-process.
@@ -178,7 +178,7 @@ every event in your producer.
 
 The streaming registry is the natural pair for `@task`. The recipe:
 
-1. At app startup, call `streams.use_file_backed_replay(root=...,
+1. At app startup, call `streams.use_file_backed_replay(storage_dir=...,
    cursor_fn=lambda ev: ev["sequence_number"])`.
 2. Producer (inside your `@task` handler) stamps every event with a
    monotonically increasing `sequence_number`. After a crash, the