Merge branch 'feature/agentserver-responses-spec016' into feature/agentserver-durable-agent-demo

Author: RaviPidaparthi

sdk/agentserver/azure-ai-agentserver-responses/tests/e2e/durability_contract/CONTRACT_COVERAGE.md

@@ -193,3 +193,17 @@ closed them, and the remaining genuine recovery gaps were filled.
 | `context.persisted_response` is seeded on recovery | Proven-by-consequence (B4): `test_row_11_path_c.py` resume markers + `test_reset_event_content.py` both FAIL if seeding is broken | recovery seeding |
 | `response.created` idempotency across real crash recovery (single created per durable stream) | `test_streaming_recovery_continuity.py` (B8 — asserts exactly one `response.created` after recovery) + `tests/e2e/test_recovery_idempotent_create.py` (provider layer) | event sequence |
 | Per-cell tests MUST verify the row's contract surface, not terminal status alone | `test_contract_completeness.py::test_per_cell_tests_assert_more_than_just_status` (Spec 032 FR-001 — HARD gate) | meta |
+
+---
+
+## Conformance gap closure — request-carried `agent_reference` (hosted-shaped input)
+
+| Clause | Test | Dimension |
+|---|---|---|
+| Row 1 Path C with a request-carried `agent_reference` (the hosted gateway-injected `AgentReference` model): durable start MUST still create a durable task and recover after SIGKILL — i.e. the model-typed `agent_reference` must not break durable-input serialization and silently degrade to a non-durable `asyncio.create_task` | `test_recovery_with_agent_reference.py::test_row_1_path_c_recovers_with_agent_reference` (stream=F/T) | recovery; durable-input serialization |
+
+This closes the gap that let the hosted `TypeError: Object of type AgentReference
+is not JSON serializable` durable-start failure ship: every other durability
+test sends no `agent_reference` (`{}` sentinel) or a plain string, so none
+exercised the model form through the (provider-agnostic) durable-input
+serialization. Unit-level guard: `tests/unit/test_durable_orchestrator.py::TestSplitRuntimeRefsSerializable`.

sdk/agentserver/azure-ai-agentserver-responses/tests/e2e/durability_contract/test_recovery_with_agent_reference.py

@@ -0,0 +1,97 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+"""Row 1 × Path C with a request-carried ``agent_reference`` (hosted-shaped input).
+
+**Why this test exists (conformance gap closure).**
+
+The hosted gateway injects an ``agent_reference`` onto every request, which the
+library normalizes into an :class:`AgentReference` *model* (a Mapping, but NOT
+``json.dumps``-serializable). That model flows into the durable-task input
+(``_start_durable_background`` -> ``start_durable`` -> ``_split_runtime_refs``).
+If it is persisted un-normalized, the core durable ``create_and_start`` ->
+``_resolve_input_storage`` size check raises
+``TypeError: Object of type AgentReference is not JSON serializable`` and the
+whole durable start **silently falls back to a non-durable ``asyncio.create_task``**
+— so no durable task exists and crash recovery never happens.
+
+Every other durability test sends NO ``agent_reference`` (so
+``_normalize_agent_reference`` returns the ``{}`` sentinel, which is trivially
+serializable) or a plain string — so none of them exercised the model form and
+the bug shipped invisibly. This test mirrors the hosted condition: it puts an
+``agent_reference`` on the request and then crashes (Path C). Because durable
+start is **provider-agnostic**, the bug reproduces locally: if the model leaks
+into the durable input, the durable task is never created, the SIGKILL'd
+non-durable task is lost, and recovery never reaches ``completed`` — failing
+this test. With the fix (normalize model -> dict before persisting) the durable
+task is created and recovery completes.
+
+Contract source: ``durability-contract.md`` § Per-row contracts → Row 1.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+import pytest
+
+from tests.e2e._crash_harness import CrashHarness
+from tests.e2e.durability_contract.conftest import (
+    LONG_GRACE_S,
+    LONG_TIME_SECS,
+    poll_until_terminal,
+    post_and_get_response_id,
+)
+
+# A realistic hosted-shaped agent_reference. The library normalizes this dict
+# into an AgentReference MODEL (not a plain dict) on the way in, reproducing the
+# exact value the hosted gateway injects.
+_AGENT_REFERENCE = {
+    "type": "agent_reference",
+    "name": "durability-conformance-agent",
+    "version": "1",
+}
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stream", [False, True], ids=["stream=False", "stream=True"])
+async def test_row_1_path_c_recovers_with_agent_reference(
+    make_harness: Callable[..., CrashHarness], stream: bool
+) -> None:
+    """A durable bg request carrying an ``agent_reference`` MUST still start a
+    durable task and recover after SIGKILL.
+
+    Regression guard for the hosted ``AgentReference is not JSON serializable``
+    durable-start failure that silently degraded durable background responses to
+    non-durable ``asyncio.create_task`` (no crash recovery).
+    """
+    harness = make_harness(
+        durable_background=True,
+        handler_sleep_ms=int(LONG_TIME_SECS * 1000),
+        shutdown_grace_seconds=LONG_GRACE_S,
+    )
+    await harness.start()
+    try:
+        response_id = await post_and_get_response_id(
+            harness.client,
+            store=True,
+            background=True,
+            stream=stream,
+            extra={"agent_reference": _AGENT_REFERENCE},
+        )
+        # Let the handler begin before the SIGKILL.
+        await asyncio.sleep(0.5)
+
+        await harness.kill()
+        await harness.restart()
+
+        # If agent_reference broke durable start, the SIGKILL'd asyncio fallback
+        # left no durable record -> this never reaches "completed".
+        terminal = await poll_until_terminal(
+            harness.client,
+            response_id,
+            timeout_seconds=30.0,
+        )
+        assert terminal["status"] == "completed", terminal
+    finally:
+        await harness.close()