[agentserver] address feedback: tags internal, single shutdown-grace env var, simpler CHANGELOG, simpler README

Per review feedback:

1. **Single shutdown-grace env var.** Removed
   AGENTSERVER_TASK_MANAGER_SHUTDOWN_GRACE_SECONDS; the framework now
   reads only AGENTSERVER_SHUTDOWN_GRACE_SECONDS.

2. **Tags is internal.** Removed the public 'tags=' keyword from the
   @task decorator and Task.options(...). The framework still uses
   the internal TaskOptions.tags field for source-stamping; developers
   no longer have a way to set arbitrary tags from the public surface.
   - Removed: samples/durable_source (only demonstrated the removed
     tags= public keyword)
   - Removed: tests/durable/test_callable_factories.py (only tested
     the removed tags-callable factory feature)
   - Removed: tests/durable/test_sample_e2e.py::
     test_reserved_tag_cannot_be_overridden
   - Updated: tests/durable/test_decorator.py to remove tags= cases
     and add 'tags' to the retired-args parametrize list
   - Updated: docs/durable-task-guide.md to drop the tags row from the
     @task reference table and the 'tags' mention in the recovery-safe
     options paragraph

3. **CHANGELOG simplified.** Trimmed the 2.0.0b6 entry to two bullets
   (durable-task primitive + httpx removal) — end-developer-facing,
   not a duplicate of the guide. Same treatment for invocations
   1.0.0b5 (one bullet covering the four durable samples).

4. **README simplified.** Replaced the two durable examples (one with
   timeout but no cancellation hook; one storing conversation history
   in ctx.metadata — both anti-patterns per our own guide) with a
   single minimal example showing the @task decorator and .run() call.
   Pointers to the developer guide for streaming/suspend/retry/timeout.

Verified: 433 core tests pass, pylint 10.00/10, mypy 0 new errors.

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

Author: RaviPidaparthi

sdk/agentserver/.gitignore

@@ -3,3 +3,6 @@ specs/
 .specify/
 .github/
 .vscode/
+
+# Demo session state — regenerated each time the demo runs
+.demo-session

sdk/agentserver/azure-ai-agentserver-core/CHANGELOG.md

@@ -4,126 +4,25 @@
 
 ### Features Added
 
-**Durable tasks — new primitive.** This release introduces the durable-task
-primitive: a small decorator-driven API that lets a hosted agent run long
-operations as **named tasks** that survive process crashes, OOM kills, and
-container redeployments. Tasks pick up exactly where they were after recovery,
-without the developer writing any explicit checkpoint or replay code.
-
-The full developer learning arc lives in
-[`docs/durable-task-guide.md`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/agentserver/azure-ai-agentserver-core/docs/durable-task-guide.md).
-A short tour:
-
-```python
-from azure.ai.agentserver.core.durable import task
-
-@task(name="long_research")
-async def do_research(ctx, prompt: str) -> dict:
-    # ctx.entry_mode tells you "fresh" | "resumed" | "recovered"
-    if ctx.entry_mode == "recovered":
-        # Pick up from where you were, using ctx.metadata
-        ...
-    await ctx.stream({"phase": "searching"})
-    ...
-    return {"summary": "..."}
-
-# In your handler:
-run = await do_research.run(task_id="task-123", input={"prompt": "..."})
-async for chunk in run:
-    ...
-result = await run.result()
-```
-
-**Concepts shipping in this release**
-
-- `@task(...)` decorator + `Task` returned object with `.run()`, `.start()`,
-  `.options(...)`, `.get_active_run(task_id)`.
-- `TaskContext` — passed to every handler invocation. Exposes `entry_mode`,
-  `input`, `metadata` (with auto-flush at lifecycle boundaries), `cancel`
-  (an `asyncio.Event`), the cause booleans `timeout_exceeded` and
-  `cancel_requested`, the steering signals `pending_input_count` and
-  `is_steered_turn`, the shutdown signal `shutdown`, the retry counter
-  `retry_attempt`, and the recovery counter `recovery_count`. Provides
-  `ctx.suspend(output=...)`, `ctx.stream(chunk)`, and
-  `ctx.exit_for_recovery()` (used during graceful shutdown to leave the
-  stored status `in_progress` so the next process recovers the task).
-- `TaskResult.status` — `Literal["completed", "suspended"]`. Failure paths
-  surface as exceptions (`TaskFailed`, `TaskCancelled`,
-  `TaskConflictError`); the stored status is `"completed"` plus an error
-  payload.
-- `TaskConflictError` — single error type for any "task is busy / not
-  available" state (live elsewhere, recovered elsewhere, evicted under
-  split-brain protection, terminal with queued steerer). Carries
-  `current_status` so callers can branch.
-- `RetryPolicy` — exponential / fixed / linear backoff presets, durable
-  across crash and recovery (failures-only; crash recovery does not
-  consume retry budget).
-- `EntryMode` Literal: `"fresh" | "resumed" | "recovered"`.
-- `Suspended` (sentinel for `.run()` of a suspended task),
-  `TaskStatus` Literal (`"pending" | "in_progress" | "suspended" | "completed"`),
-  `TaskMetadata`, `StreamHandler`, `StreamHandlerFactory`, `QueueStreamHandler`.
-
-**Behavior shipping in this release**
-
-- **Automatic recovery.** Crashed-mid-task records are detected at three
-  layers — startup scan, periodic background scan, and inline reclaim at
-  every scheduling primitive (`.run`, `.start`, `.get_active_run`). The
-  developer sees `ctx.entry_mode == "recovered"` and otherwise the same
-  `TaskContext` surface as on a fresh entry.
-- **Split-brain protection.** A new agent process that takes over a session
-  cancels stranded executions in the previous process cleanly via
-  `HTTP 409 binding_mismatch`. The previous process classifies this as
-  *evicted*, cancels its execution, suppresses its terminal write, and
-  signals its awaiters with `TaskConflictError`. Caller-observable behavior
-  matches the live-elsewhere case.
-- **Steering as plain multi-turn.** `Task.start(...)` on an already-active
-  steerable task queues the new input. The first turn's `ctx.suspend(...)`
-  call resolves the steerer's `.result()` with the *next* turn's outcome,
-  delivering plain pipelined-handler semantics with no separate "superseded"
-  status. The first turn's caller observes the natural outcome of the first
-  turn unchanged.
-- **Per-turn wall-clock timeout.** `@task(timeout=...)` is anchored to a
-  persisted per-turn-start timestamp. A crash mid-turn does NOT reset the
-  budget; the recovered watchdog computes
-  `remaining = max(0, timeout - (now - turn_started_at))`. The watchdog is
-  cooperative-only: it sets `ctx.timeout_exceeded = True` then
-  `ctx.cancel.set()` — handlers that ignore both run until the process ends
-  or `TaskRun.cancel()` is called externally.
-- **Metadata auto-flush at lifecycle boundaries.** `ctx.metadata` is
-  flushed automatically at every terminal-of-turn boundary (suspend,
-  complete, cooperative cancel, exception, suspend-with-queued-steering,
-  return-with-queued-steering, raise-with-queued-steering, shutdown via
-  `exit_for_recovery`). Explicit `ctx.metadata.flush()` remains available
-  as a fence before at-most-once side effects.
-- **Bookkeeping is durable.** Suspended-resume input patches are
-  ETag-protected. Steerable input data is cleared from the stored record at
-  the suspend transition (data minimization). The lease owner string
-  incorporates both `FOUNDRY_AGENT_NAME` and session ID, so two different
-  agents sharing a session ID cannot collide on lease ownership.
-
-**Transport**
-
-- `HostedTaskProvider` is built on `azure.core.AsyncPipelineClient` with
-  the standard policy chain (request-id, headers, user-agent, retry,
-  `AsyncBearerTokenCredentialPolicy`, task-API logging, distributed
-  tracing). `ContentDecodePolicy` is intentionally excluded; body parsing
-  happens at the call site with defensive error handling. The retry policy
-  retries on 5xx / 408 / 429 only — never on 409 regardless of body. The
-  `credential` parameter on `HostedTaskProvider.__init__` is typed
-  `AsyncTokenCredential`.
-- `httpx` is no longer a production dependency.
-
-**Documentation & tests**
-
-- New developer guide at `docs/durable-task-guide.md` is the end-to-end
-  learning arc for the primitive (concepts → reference → patterns →
-  troubleshooting).
-- New doc-review meta-test (`tests/durable/test_dev_guide_review.py`) keeps
-  the guide and the public surface in sync.
-- The durable-task test suite (`tests/durable/`) covers the public surface
-  contract, recovery in all three layers, eviction, steering as
-  multi-turn, the per-turn-wall-clock-durable timeout, and metadata
-  auto-flush invariants.
+- **Durable tasks** — new `@task` decorator and supporting types
+  (`TaskContext`, `TaskResult`, `TaskRun`, `RetryPolicy`,
+  `TaskConflictError`, `TaskFailed`, `TaskCancelled`) for
+  crash-resilient long-running agents. Tasks survive container
+  restarts, OOM kills, and redeployments; the framework re-enters the
+  handler with `ctx.entry_mode == "recovered"` and a populated
+  `ctx.metadata` after a crash. Supports streaming output via
+  `ctx.stream()`, multi-turn suspend/resume via `ctx.suspend()`,
+  cooperative cancel via `ctx.cancel`, per-turn wall-clock timeout via
+  `@task(timeout=...)`, and steering of in-flight tasks via
+  `@task(steerable=True)`. See the
+  [developer guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/agentserver/azure-ai-agentserver-core/docs/durable-task-guide.md)
+  for the full API and patterns reference.
+
+### Other Changes
+
+- The hosted task-store transport is now built on
+  `azure.core.AsyncPipelineClient` instead of `httpx`; `httpx` is no
+  longer a production dependency.
 
 ## 2.0.0b5 (2026-05-25)
 

sdk/agentserver/azure-ai-agentserver-core/README.md

@@ -118,48 +118,23 @@ python my_agent.py
 The `@task` decorator builds crash-resilient agents that survive container restarts, OOM kills, and redeployments. Task state is persisted to a task store, enabling automatic recovery and multi-turn suspend/resume patterns.
 
 ```python
-from datetime import timedelta
-from azure.ai.agentserver.core.durable import task, TaskContext, RetryPolicy
+from azure.ai.agentserver.core.durable import task, TaskContext
 
-@task(
-    timeout=timedelta(minutes=30),
-    retry=RetryPolicy.exponential_backoff(max_attempts=3),
-    tags={"priority": "high"},
-)
+@task
 async def process_document(ctx: TaskContext[dict]) -> dict:
-    ctx.metadata["phase"] = "processing"
-    result = await analyze(ctx.input["document_url"])
-    ctx.metadata["phase"] = "complete"
-    return {"summary": result}
-```
-
-**Start and await a task:**
-
-```python
-result = await process_document.run(task_id="doc-42", input={"document_url": "..."})
+    # ctx.entry_mode is "fresh" | "resumed" | "recovered".
+    # The framework re-invokes the handler from the top after a
+    # crash; ctx.input survives, so the handler picks up.
+    summary = await analyze(ctx.input["document_url"])
+    return {"summary": summary}
+
+result = await process_document.run(
+    task_id="doc-42", input={"document_url": "..."},
+)
 print(result.output)  # {"summary": "..."}
 ```
 
-**Multi-turn suspend/resume (e.g., conversational agents):**
-
-```python
-@task()
-async def chat_session(ctx: TaskContext[dict]) -> dict:
-    message = ctx.input["message"]
-    history = ctx.metadata.get("history", [])
-    reply = await generate_reply(message, history)
-    history.append({"role": "user", "content": message})
-    history.append({"role": "assistant", "content": reply})
-    ctx.metadata["history"] = history
-    return await ctx.suspend(output={"reply": reply})
-
-# Each call resumes the same session:
-result = await chat_session.run(task_id="session-1", input={"message": "Hello"})
-print(result.output)          # {"reply": "Hi! How can I help?"}
-print(result.is_suspended)    # True
-```
-
-See the [Developer Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/agentserver/azure-ai-agentserver-core/docs/durable-task-guide.md) for the full API reference.
+See the [Developer Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/agentserver/azure-ai-agentserver-core/docs/durable-task-guide.md) for streaming, multi-turn suspend/resume, retries, timeouts, steering, and the patterns reference.
 
 ## Troubleshooting
 

sdk/agentserver/azure-ai-agentserver-core/azure/ai/agentserver/core/_base.py

@@ -40,22 +40,16 @@
 def _read_task_manager_shutdown_grace() -> float:
     """Return TaskManager shutdown grace in seconds (env-driven, default 25.0).
 
-    Reads ``AGENTSERVER_TASK_MANAGER_SHUTDOWN_GRACE_SECONDS`` if set,
-    falling back to ``AGENTSERVER_SHUTDOWN_GRACE_SECONDS`` (used by the
-    responses layer for in-process draining). Defaults to 25.0 when
-    neither is set, matching the original behaviour. Allows tests
-    (and operators) to keep shutdown fast when no long-running durable
-    handlers need to checkpoint — for example the conformance suite
-    runs with a 1s grace so the in-process shutdown marker fires
-    before the handler completes naturally.
+    Reads ``AGENTSERVER_SHUTDOWN_GRACE_SECONDS``. Defaults to 25.0 when
+    unset. Allows tests (and operators) to keep shutdown fast when no
+    long-running durable handlers need to checkpoint — for example the
+    conformance suite runs with a 1s grace so the in-process shutdown
+    marker fires before the handler completes naturally.
 
     :return: Grace period in seconds (non-negative).
     :rtype: float
     """
-    raw = (
-        os.environ.get("AGENTSERVER_TASK_MANAGER_SHUTDOWN_GRACE_SECONDS")
-        or os.environ.get("AGENTSERVER_SHUTDOWN_GRACE_SECONDS")
-    )
+    raw = os.environ.get("AGENTSERVER_SHUTDOWN_GRACE_SECONDS")
     if raw is None:
         return 25.0
     try:

sdk/agentserver/azure-ai-agentserver-core/azure/ai/agentserver/core/durable/_decorator.py

@@ -1126,7 +1126,6 @@ def options(
         self,
         *,
         title: str | Callable[[Any, str], str] | None = None,
-        tags: dict[str, str] | Callable[[Any, str], dict[str, str]] | None = None,
         timeout: timedelta | None = None,
         ephemeral: bool | None = None,
         retry: RetryPolicy | None = None,
@@ -1138,8 +1137,6 @@ def options(
 
         :keyword title: Title override.
         :paramtype title: str | Callable[[Any, str], str] | None
-        :keyword tags: Tag overrides.
-        :paramtype tags: dict[str, str] | Callable[[Any, str], dict[str, str]] | None
         :keyword timeout: Execution timeout override.
         :paramtype timeout: timedelta | None
         :keyword ephemeral: Whether to delete task on terminal exit.
@@ -1151,27 +1148,10 @@ def options(
         :return: A new Task with overridden options.
         :rtype: Task[Input, Output]
         """
-        # For tags: if both old and new are dicts, merge them.
-        # Mixing callable and dict is not supported — use one or the other.
-        resolved_tags: dict[str, str] | Callable[[Any, str], dict[str, str]] | None
-        if tags is not None:
-            if callable(tags) != callable(self._opts.tags) and self._opts.tags:
-                raise TypeError(
-                    "Cannot mix callable and dict tags in options(). "
-                    "Pass a callable to replace a callable, or a dict to merge with a dict."
-                )
-            if callable(tags):
-                resolved_tags = tags
-            else:
-                existing = self._opts.tags if isinstance(self._opts.tags, dict) else {}
-                resolved_tags = _strip_reserved_tags({**existing, **(tags or {})})
-        else:
-            resolved_tags = self._opts.tags
-
         new_opts = TaskOptions(
             name=self._opts.name,
             title=title if title is not None else self._opts.title,
-            tags=resolved_tags,
+            tags=self._opts.tags,
             timeout=timeout if timeout is not None else self._opts.timeout,
             ephemeral=(ephemeral if ephemeral is not None else self._opts.ephemeral),
             retry=retry if retry is not None else self._opts.retry,
@@ -1197,7 +1177,6 @@ def task(
     *,
     name: str | None = ...,
     title: str | Callable[[Any, str], str] | None = ...,
-    tags: dict[str, str] | Callable[[Any, str], dict[str, str]] | None = ...,
     timeout: timedelta | None = ...,
     ephemeral: bool = ...,
     retry: RetryPolicy | None = ...,
@@ -1214,7 +1193,6 @@ def task(
     *,
     name: str | None = None,
     title: str | Callable[[Any, str], str] | None = None,
-    tags: dict[str, str] | Callable[[Any, str], dict[str, str]] | None = None,
     timeout: timedelta | None = None,
     ephemeral: bool = True,
     retry: RetryPolicy | None = None,
@@ -1239,8 +1217,6 @@ async def my_task(ctx: TaskContext[MyInput]) -> MyOutput: ...
         existing in-flight tasks are still recovered correctly because the
         framework matches on this name, not the Python function name.
     :keyword title: Human-readable title (string or callable).
-    :keyword tags: Default tags (static dict or callable factory receiving
-        ``(input, task_id)``).
     :keyword timeout: Per-turn, wall-clock, durable, cooperative-only
         execution budget. When the budget elapses for the current turn,
         ``ctx.timeout_exceeded`` is set then ``ctx.cancel`` is set; the
@@ -1275,15 +1251,10 @@ def _wrap(
 
         input_type, output_type = _extract_generic_args(func)
 
-        # Preserve callable tags as-is (stripped at resolve time); strip static dicts now
-        resolved_tags = (
-            tags if callable(tags) else _strip_reserved_tags(dict(tags) if tags else {})
-        )
-
         opts = TaskOptions(
             name=name or func.__qualname__,
             title=title,
-            tags=resolved_tags,
+            tags={},
             timeout=timeout,
             ephemeral=ephemeral,
             retry=retry,

sdk/agentserver/azure-ai-agentserver-core/docs/durable-task-guide.md

@@ -659,7 +659,6 @@ changing it strands existing tasks.
 |--------------------------|-------------------------------------------|---------|-------------|
 | `name`                   | `str`                                     | `fn.__qualname__` | Stable identity for recovery routing. Always set this explicitly for production tasks. |
 | `title`                  | `str \| Callable[[T, str], str] \| None`  | `None`  | Human-readable title (template or callable). |
-| `tags`                   | `dict[str, str] \| Callable[[T, str], dict[str, str]] \| None` | `None` | Default tags (static dict or callable factory). |
 | `timeout`                | `timedelta \| None`                       | `None`  | Execution timeout. When elapsed, `ctx.cancel` is set cooperatively. |
 | `ephemeral`              | `bool`                                    | `True`  | Delete the persisted record on terminal exit. |
 | `retry`                  | `RetryPolicy \| None`                     | `None`  | Retry policy for handler-raised exceptions. Recovery-safe (applied on every entry, including post-crash). |
@@ -695,7 +694,7 @@ you can stream from or `await handle.result()` on. Both accept the
 same `input_id` / `if_last_input_id` sequential-input preconditions
 (see §4).
 
-Everything else that characterises a task — `title`, `tags`, `retry`,
+Everything else that characterises a task — `title`, `retry`,
 `stream_handler_factory`, `steerable`, `ephemeral`,
 `timeout` — is configured once on the `@task(...)` decorator (or via
 `Task.options(...)` for a derived `Task`). There is no per-call