diff --git a/docs/decisions/0055-python-foundry-hosting-contracts.md b/docs/decisions/0055-python-foundry-hosting-contracts.md index 30c76e5be7d..2115cd476a4 100644 --- a/docs/decisions/0055-python-foundry-hosting-contracts.md +++ b/docs/decisions/0055-python-foundry-hosting-contracts.md @@ -80,6 +80,12 @@ clients, providers, and mutable tools. A new graph wrapper around shared executo Reject known shared execution resources rather than cloning them. This guard cannot prove that arbitrary application globals are isolated. Keep workflow names and executor IDs stable for checkpoint restoration. +Construct tool objects inside the workflow factory as the default. Module-level `@tool` decoration +constructs one shared wrapper with its own lifetime counters and any captured resources. The current +ownership guard rejects reused function-tool objects without attempting to infer function purity. +A function may be defined elsewhere and wrapped inside the factory, but developers remain responsible +for captured or externally shared state. Fresh wrappers do not clone that state or establish isolation. + Close factory-owned context-managed agents for the request, including failure and cancellation cleanup. Applications own cleanup of other resources they create; caller-owned shared resources must not be closed. State needed across requests belongs in supported stores, not request-owned instance fields. @@ -144,14 +150,24 @@ or other request-option precedence. ### Approvals and consent -Use session-backed authority for regular-agent approvals rather than a separate public approval-store API. -Native workflow pending authority remains checkpoint-owned. Canonical pending state, conditional consumption, -persistence ordering, custom-store capabilities, and failure semantics require a complete design before -replacing existing approval storage. +The native agent owns approval tracking, pending snapshots, policy decisions, binding, consumption, +and execution in its `AgentSession`. Hosting persists the complete session rather than implementing a +second approval store or a Foundry-specific approval dictionary in session state. +Native workflow pending authority remains checkpoint-owned. + +AgentServer's wire IDs differ from native approval IDs. Retain only transport correlation in the +response item's internal metadata; it is not executable authority. The native session must still +contain the matching pending request. Save that session before publishing a resumable approval. +Remove the separate approval-store configuration and exports without silently migrating old pending work. + +This migration preserves Core's existing session-level guarantees. Durable single-consumption across +workers and independently restored old snapshots requires separate native session-store coordination. +Do not implement that guarantee in a hosting-specific approval manager. -Reject incomplete hosted MCP approval sets with HTTP 400 before streaming, response headers, -`response.created`, or protected dispatch, without consuming pending authority. -A complete batch may mix approvals and rejections. +The intended HTTP contract rejects incomplete hosted MCP approval sets before streaming, response headers, +`response.created`, or protected dispatch, without consuming pending authority. A complete batch may mix +approvals and rejections. Exact pre-header HTTP 400 behavior remains blocked on a suitable public SDK +validation hook under #9537; the native approval migration does not claim to implement that requirement. Represent invocation-time OAuth consent as structured consent with incomplete response status. Pair each emitted function call with one terminal result, preserve completed sibling results, and stop diff --git a/docs/specs/004-python-function-calling-loop.md b/docs/specs/004-python-function-calling-loop.md index f755951845d..646b36748a7 100644 --- a/docs/specs/004-python-function-calling-loop.md +++ b/docs/specs/004-python-function-calling-loop.md @@ -641,6 +641,9 @@ that manually replay messages own the equivalent rule: do not resend an approval | Mixed approved/rejected batch | Every call gets one correctly correlated terminal result. | `packages/core/tests/core/test_function_invocation_logic.py::test_rejected_approval` | | Persisted approval replay | Resume executes with the prior call available. | `test_persisted_approval_messages_replay_correctly` | | Hosted approval pass-through | Hosted requests/responses are bound to the recorded provider request and are not processed as local calls. | `test_hosted_tool_approval_response`, `test_hosted_mcp_approval_response_passthrough`, `test_session_approval_binding_reconstructs_hosted_response`, `test_mixed_local_and_hosted_approval_flow` | +| Foundry native approval round trip | HTTP approval and rejection resume the issuing serialized native session in streaming and non-streaming modes; completed decisions cannot execute again. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_native_agent_consumes_serialized_session_approval`, `test_native_approval_batch_waits_for_all_decisions` | +| Foundry native approval publication | Only requests matching native pending state are published, after successful native finalization and session persistence; failures publish no approval item. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_non_streaming_emits_mcp_approval_request_and_persists_native_session`, `test_streaming_emits_mcp_approval_request_and_persists_native_session`, `test_custom_agent_cannot_publish_approval_without_matching_native_state`, `test_failed_native_finalization_does_not_publish_approval`, `test_session_save_failure_does_not_publish_resumable_approval` | +| Foundry deferred approval output | Output order is preserved across finalization; count and serialized-byte limits fail explicitly without publishing the buffered approval, and an overflowing producer is closed in both response modes. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_deferred_approval_preserves_streamed_output_order`, `test_deferred_approval_output_has_count_and_byte_limits`, `test_deferred_approval_output_enforces_default_limits`, `test_deferred_approval_limit_closes_an_unending_stream` | | Agent-tool child approval | A child `ToolApprovalMiddleware` can auto-approve runtime tool requests inside one delegated invocation; unresolved child approvals execute nothing and do not enter the caller's approval state or dispatch a same-named parent tool, including with propagated application state. Mixed batches preserve non-approval user-input requests. Shared parent and child state rejects overlapping `ToolApprovalMiddleware.source_id` values before running the child; parent approval state, including state of middleware passed to a single parent run, is neither visible nor mutable inside the child (a child cannot add standing rules or forge a decision for a pending request), and custom child approval queues do not leak into later delegations. | `packages/core/tests/core/test_agents.py::test_chat_agent_as_tool_auto_approves_child_tool_with_middleware`, `test_chat_agent_as_tool_fails_closed_for_unresolved_child_approval`, `test_chat_agent_as_tool_child_approval_does_not_dispatch_same_named_parent_tool`, `test_chat_agent_as_tool_preserves_non_approval_requests_from_mixed_child_batch`, `test_chat_agent_as_tool_shared_session_requires_distinct_tool_approval_source_ids`, `test_chat_agent_as_tool_isolates_custom_parent_approval_state`, `test_chat_agent_as_tool_isolates_run_level_parent_approval_state`, `test_chat_agent_as_tool_run_level_approval_state_cannot_authorize_pending_request`, `test_chat_agent_as_tool_run_level_approval_ownership_is_per_invocation`, `test_chat_agent_as_tool_approved_delegation_does_not_confuse_framework_approval_state`, `test_chat_agent_as_tool_does_not_restore_custom_approval_queue_on_fresh_delegation` | | Approval-time user input | Every user-input request from one approved execution returns in order with assistant role and no extra model call; the execution consumes one call-budget unit. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_returns_all_user_input_requests_without_another_model_call`, `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_user_input_counts_toward_function_call_budget` | | Mixed terminal result and follow-up input | Completed siblings remain tool-role while only follow-up input requests use assistant-role messages/updates. | `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_separates_terminal_results_from_follow_up_requests`, `packages/openai/tests/openai/test_openai_chat_completion_client.py::test_mixed_approval_resume_roles_serialize_function_result_as_tool`, `packages/core/tests/core/test_harness_tool_approval.py::test_dynamic_policy_approval_partitions_safe_sibling_result_roles` | @@ -684,6 +687,8 @@ that manually replay messages own the equivalent rule: do not resend an approval | Local approval without authoritative session | A local approval response carried by any message role executes nothing when no session recorded its request, whether the request is fabricated, absent, answered with tampered arguments, or repeated as several responses sharing one approval id. Verified for both streaming and non-streaming. | `test_local_approval_response_without_authoritative_session_does_not_execute`, `test_duplicate_approval_id_reclassification_does_not_execute_without_session` | | Filtering precedes batch validation | An unbound local response is removed before stateless mixed-batch completeness is enforced, so it is never counted as an answer and the remaining history is validated on its own merits. | `test_unbound_local_approval_response_is_filtered_before_mixed_batch_validation` | | Session-bound approval round trip | The same response executes once when the issuing session is supplied on the resuming run. | `test_local_approval_response_executes_with_authoritative_session` | +| Foundry wire/session isolation | A wire approval cannot bind to a different native session or to a later request that reuses the native ID with a changed server, tool, or arguments; rejected aliases leave pending authority intact in both response modes. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_wire_correlation_cannot_cross_native_sessions`, `test_stale_wire_approval_cannot_bind_to_reused_native_id` | +| Foundry wire argument serialization | Equivalent JSON argument representations still bind to the native snapshot without coercing booleans to numbers or rounding distinct numeric values. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_wire_approval_accepts_equivalent_argument_serialization`, `test_stale_wire_approval_cannot_bind_to_reused_native_id` | | Hosted approval pass-through | Provider-issued approvals still reach the provider untouched without a session. | `test_hosted_approval_response_passes_through_without_session` | | Settled replay without a session | A completed approval round replays as history: it does not re-execute, does not warn, and does not fail a completed mixed batch. | `test_settled_approval_response_replays_without_session_or_warning`, `test_completed_split_stateless_mixed_batch_is_inert_on_later_turn` | | Binding opt-out | `disable_approval_response_binding` restores the previous unbound pass-through. | `test_disable_approval_response_binding_restores_unbound_behavior` | @@ -758,6 +763,7 @@ that manually replay messages own the equivalent rule: do not resend an approval | Invalidated per-service-call persistence | An invalidated service response, its partial calls, and any nonexistent results are not success-persisted, and invalid content does not advance session continuation state. | `packages/core/tests/core/test_function_invocation_logic.py::test_invalidated_response_is_not_persisted` | | Streaming message injection with per-service-call persistence | A streaming response rebuilt from updates mirrors the inner conversation id exactly, including clearing it, and keeps its internal marker, so the next iteration appends only the latest message rather than replaying the whole turn on top of provider-held history, and never persists a conversation id from an earlier injected service call. | `packages/core/tests/core/test_middleware_with_chat.py::TestChatMiddleware::test_message_injection_middleware_streaming_preserves_inner_continuation_state`, `test_message_injection_middleware_streaming_keeps_service_conversation_id_external`, `test_message_injection_middleware_streaming_clears_conversation_id_when_final_call_has_none`, `test_message_injection_middleware_conversation_id_matches_across_streaming_modes`, `packages/core/tests/core/test_harness_agent.py::test_streaming_harness_tool_call_does_not_duplicate_transcript` | | Service-side approval decision | Stored hosted request is skipped; the current approved or rejected hosted response is sent, while local approval controls are omitted from provider input. | `packages/openai/tests/openai/test_openai_chat_client.py::test_prepare_messages_strips_approval_request_but_keeps_response_under_storage`, `test_prepare_messages_drops_local_approval_controls` | +| Foundry history-owned approval replay | Host-managed stateless input restores the pending hosted request even with capped wire history; agent-managed or service-side history receives no duplicate, while both response modes serialize exactly one current provider decision. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_hosted_approval_replays_only_with_the_owner_of_history`, `test_native_agent_consumes_serialized_session_approval` | | OpenAI approval serialization | Hosted approval id and decision serialize to `mcp_approval_response`; local approvals remain in-process. | `test_prepare_message_for_openai_with_function_approval_response`, `test_prepare_content_for_opentool_approval_response`, `test_function_approval_response_with_mcp_tool_call` | | OpenAI end-to-end hosted approval | Hosted request parses, response sends, and continuation completes. | `test_end_to_end_mcp_approval_flow` | | Stored function call/result | Service-side storage drops server-issued calls but keeps new outputs. | `test_prepare_options_with_conversation_id_strips_server_issued_items`, `test_prepare_messages_for_openai_full_conversation_with_reasoning` | diff --git a/python/PACKAGE_STATUS.md b/python/PACKAGE_STATUS.md index 424b4ef44ec..4e25ff17bd6 100644 --- a/python/PACKAGE_STATUS.md +++ b/python/PACKAGE_STATUS.md @@ -156,7 +156,7 @@ listed below. - `agent-framework-core`: `SessionStore` and `FileSessionStore` from `agent_framework/_sessions.py` - `agent-framework-foundry-hosting`: `FoundryAgentSessionStore` from - `agent_framework_foundry_hosting/_state_store.py` + `agent_framework_foundry_hosting/_shared.py` #### `TO_PROMPT_AGENT` diff --git a/python/packages/core/agent_framework/foundry/__init__.py b/python/packages/core/agent_framework/foundry/__init__.py index a3cd29c0f3e..e34c1441fa8 100644 --- a/python/packages/core/agent_framework/foundry/__init__.py +++ b/python/packages/core/agent_framework/foundry/__init__.py @@ -41,10 +41,7 @@ "CheckpointStoreProvider": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), "FoundryCheckpointStore": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), "ContextScopedStoreProvider": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), - "FoundryFunctionApprovalStore": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), "FoundryRequestScope": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), - "FunctionApprovalStore": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), - "FunctionApprovalStoreProvider": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), "FoundryToolbox": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"), "FoundryLocalChatOptions": ("agent_framework_foundry_local", "agent-framework-foundry-local"), "FoundryLocalClient": ("agent_framework_foundry_local", "agent-framework-foundry-local"), diff --git a/python/packages/core/agent_framework/foundry/__init__.pyi b/python/packages/core/agent_framework/foundry/__init__.pyi index 424b48e0215..1cd4bff5293 100644 --- a/python/packages/core/agent_framework/foundry/__init__.pyi +++ b/python/packages/core/agent_framework/foundry/__init__.pyi @@ -37,11 +37,8 @@ from agent_framework_foundry_hosting import ( ContextScopedStoreProvider, FoundryAgentSessionStore, FoundryCheckpointStore, - FoundryFunctionApprovalStore, FoundryRequestScope, FoundryToolbox, - FunctionApprovalStore, - FunctionApprovalStoreProvider, InvocationsHostServer, ResponsesHostServer, StoreProvider, @@ -85,15 +82,12 @@ __all__ = [ "FoundryEmbeddingOptions", "FoundryEmbeddingSettings", "FoundryEvals", - "FoundryFunctionApprovalStore", "FoundryLocalChatOptions", "FoundryLocalClient", "FoundryLocalSettings", "FoundryMemoryProvider", "FoundryRequestScope", "FoundryToolbox", - "FunctionApprovalStore", - "FunctionApprovalStoreProvider", "GeneratedEvaluatorRef", "InvocationsHostServer", "InvocationsWorkflowHostServer", diff --git a/python/packages/foundry_hosting/README.md b/python/packages/foundry_hosting/README.md index e777022ab02..f5fe6c49b17 100644 --- a/python/packages/foundry_hosting/README.md +++ b/python/packages/foundry_hosting/README.md @@ -51,7 +51,8 @@ returning a new wrapper around shared executors does not isolate execution state Workflow hosts expose checkpoint storage, not agent-session storage or agent history/background policies. Responses workflows retain `prepare_options`; Invocations workflows use the parser's -explicit workflow kwargs instead. Agent approval-store APIs are unchanged. +explicit workflow kwargs instead. Regular-agent approval state belongs to the native +agent and its `AgentSession`; no separate approval-store API is exposed. Agent hosts reject `WorkflowAgent`, whether supplied directly or returned by a factory. `checkpoint_store_provider` is available only on workflow hosts. No stored state is converted between native workflow and agent execution models. @@ -242,6 +243,17 @@ agents, clients, context providers, and mutable tools; hosting rejects known sharing rather than cloning or unwrapping it. Workflow names and executor IDs must remain stable so the exact scoped checkpoint can be restored. +Construct tool objects inside the workflow factory as the default. A module-level +`@tool` decorator constructs one shared `FunctionTool`, including its invocation +counters and configured lifetime limits. The current ownership guard rejects +reusing that object across native workflow requests, even if its function is pure. + +A plain Python function can be defined outside the factory and wrapped with +`tool(function)` inside it to create a fresh tool object for each workflow. +This does not copy state captured by the function, bound objects, wrapped agents, +or connections. Developers must manage that state and its isolation explicitly; +moving only the wrapper construction does not make shared mutable resources safe. + Native workflow state is scoped to the trusted platform user plus Foundry sandbox. Each outer stored `response.id` is bound to its exact MAF checkpoint, graph identity, lineage, pending reply authority, output, and usage. The host @@ -483,7 +495,7 @@ conversation or response ID. | MAF `AgentSession.session_id` / `service_session_id` | Inner agent state and optional downstream service continuation; neither identifies the Foundry sandbox. | | Workflow checkpoint ID | Inner workflow state within a checkpoint context, not a Foundry session ID. | -The default hosted MAF session, checkpoint, and approval stores use a `v2` namespace +The default hosted MAF session and checkpoint stores use a `v2` namespace derived from the hashed platform identity, with `user_isolation=True` and an explicit platform `call_id` on each item operation. Checkpoint context IDs are hashed as well. The same user in two hosted sandboxes cannot read the other's default MAF state. @@ -599,9 +611,34 @@ locally. Stored checkpoints are scoped under `checkpoints`. ### Function approvals -`ResponsesHostServer` persists function approvals durably. By default, it uses the -`FoundryFunctionApprovalStore`, backed by Foundry storage when hosted and file-based -storage locally. Stored approvals are scoped under `function_approvals`. +The native agent tracks pending approvals, validates decisions, and consumes them +in its `AgentSession`. Hosting persists and restores the complete native session +through `agent_session_store_provider`; it does not maintain a second approval store. +An approval reply must continue the issuing session through `previous_response_id` +or a named conversation. The wire approval ID alone does not establish authority. + +Custom agents must establish matching native pending state by the end of a run +that emits an approval request. Hosting rejects unmatched or unrecorded requests +before publishing an approval item; it does not register approvals on an agent's behalf. + +AgentServer requires its own wire-ID format. The adapter stores only native-ID +and session-ID correlation in the response item's internal metadata, which the SDK +removes from client-facing responses. It resolves that metadata through the scoped +response provider, independently of model-history limits, then delegates binding +and consumption to Core. Native workflow authority remains in its exact checkpoint. + +Remove `function_approval_store_provider` and imports of `FunctionApprovalStore`, +`FoundryFunctionApprovalStore`, and `FunctionApprovalStoreProvider` when upgrading. +Old approval-store records are not migrated. Start a fresh conversation rather +than resuming approvals emitted before this migration. + +Approval output waits for native finalization, and the session is saved before +an approval request is published. This preserves Core's existing session-level +guarantees, not durable single-consumption across +concurrent workers or independently restored old snapshots. Stronger session-store +coordination is separate work. Incomplete hosted MCP batches still need the SDK +preflight support tracked by #9537 to return HTTP 400 before streaming starts; +this migration does not claim that behavior. ## Native Invocations workflows @@ -680,9 +717,9 @@ If a connection drops after commit, retrying the same trusted user/sandbox/call replays that response's complete stored snapshot without executing the workflow or replacing its head. A different call ID starts normal turn validation and cannot retrieve that snapshot. -Local callers may pass one built workflow for a one-shot non-pausing run. Any -workflow that can pause for external input must use a request-aware factory so a -fresh graph can restore and consume the durable reply on the next request. +Local callers also use a request-aware factory, including one-shot non-pausing +runs. Each request receives a fresh graph; a continuation restores and consumes +its durable reply from the exact scoped checkpoint. After a newer Invocations head is durably committed, the host reclaims completed ancestor response records and checkpoints oldest-first, retaining only current, pending, active or blocked authority. Cleanup failures are logged and retried by diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py index 08a11a53272..cea3f1dc478 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py @@ -13,17 +13,18 @@ from ._responses_agent import ResponsesHostServer from ._responses_workflow import ResponsesWorkflowHostServer from ._scope import FoundryRequestScope - from ._shared import InvocationRun, ResponsesRequest, WorkflowSource, WorkflowTurn, response_input_messages - from ._state_store import ( + from ._shared import ( AgentSessionStoreProvider, CheckpointStoreProvider, ContextScopedStoreProvider, FoundryAgentSessionStore, FoundryCheckpointStore, - FoundryFunctionApprovalStore, - FunctionApprovalStore, - FunctionApprovalStoreProvider, + InvocationRun, + ResponsesRequest, StoreProvider, + WorkflowSource, + WorkflowTurn, + response_input_messages, ) from ._toolbox import FoundryToolbox @@ -33,23 +34,20 @@ __version__ = "0.0.0" _LAZY_EXPORTS: Final[dict[str, str]] = { - "AgentSessionStoreProvider": "._state_store", - "CheckpointStoreProvider": "._state_store", - "ContextScopedStoreProvider": "._state_store", - "FoundryAgentSessionStore": "._state_store", - "FoundryCheckpointStore": "._state_store", - "FoundryFunctionApprovalStore": "._state_store", + "AgentSessionStoreProvider": "._shared", + "CheckpointStoreProvider": "._shared", + "ContextScopedStoreProvider": "._shared", + "FoundryAgentSessionStore": "._shared", + "FoundryCheckpointStore": "._shared", "FoundryRequestScope": "._scope", "FoundryToolbox": "._toolbox", "InvocationRun": "._shared", - "FunctionApprovalStore": "._state_store", - "FunctionApprovalStoreProvider": "._state_store", "InvocationsHostServer": "._invocations_agent", "InvocationsWorkflowHostServer": "._invocations_workflow", "ResponsesHostServer": "._responses_agent", "ResponsesRequest": "._shared", "ResponsesWorkflowHostServer": "._responses_workflow", - "StoreProvider": "._state_store", + "StoreProvider": "._shared", "WorkflowSource": "._shared", "WorkflowTurn": "._shared", "response_input_messages": "._shared", @@ -61,11 +59,8 @@ "ContextScopedStoreProvider", "FoundryAgentSessionStore", "FoundryCheckpointStore", - "FoundryFunctionApprovalStore", "FoundryRequestScope", "FoundryToolbox", - "FunctionApprovalStore", - "FunctionApprovalStoreProvider", "InvocationRun", "InvocationsHostServer", "InvocationsWorkflowHostServer", diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py index c1430210ca4..b38270e56ab 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py @@ -40,8 +40,10 @@ ) from ._scope import FoundryRequestScope from ._shared import ( + AgentSessionStoreProvider, AgentSource, InvocationRun, + StoreProvider, UnsupportedOptions, is_agent, resolve_agent, @@ -50,7 +52,6 @@ validate_sse_keep_alive_interval, validate_unsupported_options, ) -from ._state_store import AgentSessionStoreProvider, StoreProvider logger = logging.getLogger(__name__) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py index 4a85faa16d1..086082c6bc7 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py @@ -20,7 +20,7 @@ from starlette.types import Receive, Scope, Send from ._scope import FoundryRequestScope -from ._workflow_state import WorkflowBlockedError, WorkflowConflictError +from ._shared import WorkflowBlockedError, WorkflowConflictError InvocationOptionsHook = Callable[[Request, dict[str, Any]], Mapping[str, Any] | Awaitable[Mapping[str, Any]]] diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py index 460467131cc..11819b8b416 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py @@ -42,9 +42,16 @@ invocation_request_scope, ) from ._scope import FoundryRequestScope -from ._shared import WorkflowResolver, WorkflowSource, WorkflowTurn, validate_sse_keep_alive_interval, workflow_agents -from ._state_store import CheckpointStoreProvider, ContextScopedStoreProvider -from ._workflow_state import HostedWorkflowRun +from ._shared import ( + CheckpointStoreProvider, + ContextScopedStoreProvider, + HostedWorkflowRun, + WorkflowResolver, + WorkflowSource, + WorkflowTurn, + validate_sse_keep_alive_interval, + workflow_agents, +) logger = logging.getLogger(__name__) @@ -73,6 +80,9 @@ def __init__( executors, agents, clients, providers, and mutable tools inside the factory. Keep workflow and executor IDs stable for checkpoint restoration. The host enters and closes context-managed agents; applications own other resource cleanup. Known shared execution resources are rejected. + Construct tool objects inside the factory. A module-level `@tool` creates a shared wrapper, + which the ownership guard rejects even for a pure function. A function defined elsewhere can + be wrapped with `tool(function)` inside the factory; applications still own any captured state. Keyword Args: parse_input: Sync or async parser returning typed `WorkflowTurn` input or a complete pending diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py index f408189295d..600d27ee96a 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_agent.py @@ -5,10 +5,12 @@ from __future__ import annotations import asyncio +import inspect import logging from collections.abc import ( AsyncGenerator, AsyncIterable, + Awaitable, Generator, Mapping, Sequence, @@ -34,6 +36,7 @@ SupportsAgentRun, ) from agent_framework._telemetry import mark_feature_used +from agent_framework._tools import _load_pending_approval_requests # pyright: ignore[reportPrivateUsage] from agent_framework.exceptions import AgentFrameworkException from azure.ai.agentserver.core import get_request_context from azure.ai.agentserver.responses import ( @@ -68,6 +71,7 @@ _is_allowed_oauth_consent_link, # pyright: ignore[reportPrivateUsage] _items_to_messages, # pyright: ignore[reportPrivateUsage] _log_response_failure, # pyright: ignore[reportPrivateUsage] + _native_approval_id, # pyright: ignore[reportPrivateUsage] _normalize_allowed_oauth_consent_origins, # pyright: ignore[reportPrivateUsage] _output_items_to_messages, # pyright: ignore[reportPrivateUsage] _OutputItemTracker, # pyright: ignore[reportPrivateUsage] @@ -79,9 +83,11 @@ ) from ._scope import FoundryRequestScope from ._shared import ( + AgentSessionStoreProvider, AgentSource, OptionsHook, ResponsesRequest, + StoreProvider, UnsupportedOptions, _build_response_server_options, # pyright: ignore[reportPrivateUsage] is_agent, @@ -93,17 +99,13 @@ validate_request_options, validate_unsupported_options, ) -from ._state_store import ( - AgentSessionStoreProvider, - FunctionApprovalStore, - FunctionApprovalStoreProvider, - StoreProvider, -) logger = logging.getLogger(__name__) _HOSTED_RESPONSES_HISTORY_SOURCE_ID = "_foundry_responses_history" +_MAX_DEFERRED_APPROVAL_UPDATES = 4096 +_MAX_DEFERRED_APPROVAL_BYTES = 4 * 1024 * 1024 _HistorySource = Literal["host_managed", "agent_managed", "inference_service"] @@ -226,7 +228,6 @@ def __init__( prefix: str = "", response_store: ResponseProviderProtocol | None = None, agent_session_store_provider: StoreProvider[SessionStore] | None = None, - function_approval_store_provider: StoreProvider[FunctionApprovalStore] | None = None, allowed_oauth_consent_origins: Sequence[str] | None = None, history_source: Literal["host_managed", "agent_managed", "inference_service"] = "host_managed", background_source: Literal["host_managed", "inference_service"] = "host_managed", @@ -250,14 +251,15 @@ def __init__( that keep mutable state outside `AgentSession`. `WorkflowAgent` instances and factory results are rejected. Use `ResponsesWorkflowHostServer` with a native workflow factory instead. + Approval-emitting runs must finalize matching native pending session state; + hosting rejects unmatched requests before publishing them. Keyword Args: prefix: The URL prefix for the server. response_store: Optional response store for caller-facing persistence and history. agent_session_store_provider: Optional provider for MAF agent session storage. - If not provided, a default `AgentSessionStoreProvider` will be used. - function_approval_store_provider: Optional provider for function approval storage. - If not provided, a default `FunctionApprovalStoreProvider` will be used. + Stores the complete native session, including pending approvals, before an + approval request is published. If omitted, uses `AgentSessionStoreProvider`. allowed_oauth_consent_origins: Optional exact HTTPS origins allowed for OAuth consent links. When omitted, hosting retains its existing safe-HTTPS validation without restricting the destination origin. When provided, every link must match an entry; an empty sequence rejects @@ -403,11 +405,6 @@ def __init__( self._session_storage_provider = ( AgentSessionStoreProvider() if agent_session_store_provider is None else agent_session_store_provider ) - self._function_approval_storage_provider = ( - FunctionApprovalStoreProvider() - if function_approval_store_provider is None - else function_approval_store_provider - ) # Lazy agent lifecycle: the agent (and any MCP tools it owns) is entered on # the first request rather than at server startup, so that authentication @@ -723,7 +720,7 @@ async def _load_request_messages( self, context: ResponseContext, *, - approval_storage: FunctionApprovalStore | None, + session: AgentSession | Awaitable[AgentSession] | None = None, configuration: _AgentConfiguration | None = None, ) -> list[Message]: """Load the request's input and prior history concurrently, assembled for the run. @@ -745,13 +742,37 @@ async def _load_request_messages( async def _load_input() -> list[Message]: input_items = await context.get_input_items() - return await _items_to_messages(input_items, approval_storage=approval_storage) + resolved_session = await session if inspect.isawaitable(session) else session + wire_ids: list[str] = [] + for input_item in input_items: + if input_item["type"] == "mcp_approval_response": + wire_ids.append(input_item["approval_request_id"]) + elif input_item["type"] == "mcp_approval_request": + wire_ids.append(input_item["id"]) + approval_ids: dict[str, str] = {} + if wire_ids: + # The SDK context has no public exact-item lookup. Use its already selected provider, + # not capped model history or a second approval store, preserving the platform scope. + provider = context._provider # pyright: ignore[reportPrivateUsage] + if provider is None or resolved_session is None: + raise _PublicResponseFailure(ValueError("Approval continuation requires a stored native session.")) + stored_items = await provider.get_items(wire_ids, context=context.platform_context) + for wire_id, item in zip(wire_ids, stored_items, strict=True): + if item is None or item["type"] != "mcp_approval_request" or item["id"] != wire_id: + raise _PublicResponseFailure(ValueError(f"No native pending approval matches {wire_id!r}.")) + approval_ids[wire_id] = _native_approval_id(cast(Mapping[str, Any], item), session=resolved_session) + return await _items_to_messages( + input_items, + session=resolved_session, + approval_ids=approval_ids, + include_hosted_approval_requests=uses_agent_server_history, + ) async def _load_history() -> list[Message]: if not uses_agent_server_history: return [] history = await context.get_history() - return await _output_items_to_messages(history, approval_storage=approval_storage) + return await _output_items_to_messages(history) input_task = asyncio.ensure_future(_load_input()) history_task = asyncio.ensure_future(_load_history()) @@ -853,11 +874,6 @@ async def _handle_inner_agent( ) request_context = get_request_context() - approval_storage = ( - self._function_approval_storage_provider.get_store(config=self.config, platform_context=request_context) - if stored - else None - ) previous_response_id = request.get("previous_response_id") session_load_id = ( context.response_id @@ -875,17 +891,10 @@ async def _handle_inner_agent( else None ) - # Load the caller's input items and prior conversation history concurrently with the - # session load below. These are independent storage round-trips with no data dependency - # between them, so overlapping them removes serial latency from the request critical path. + session_ready: asyncio.Future[AgentSession] = asyncio.get_running_loop().create_future() request_messages_task = asyncio.ensure_future( - self._load_request_messages( - context, - approval_storage=approval_storage, - configuration=configuration, - ) + self._load_request_messages(context, session=session_ready, configuration=configuration) ) - session = ( await session_storage.get(session_load_id) if session_storage is not None and session_load_id is not None @@ -903,6 +912,7 @@ async def _handle_inner_agent( ) ) session = agent.create_session() + session_ready.set_result(session) provider_state = session.state.get(_HOSTED_PROVIDER_STATE_KEY) if context.conversation_id is not None: if context.is_recovery and provider_background: @@ -1055,6 +1065,36 @@ async def _handle_inner_agent( inner_stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]] | None = None updates: _SignalledIterator[AgentResponseUpdate] | None = None + deferred_updates: list[AgentResponseUpdate] = [] + deferred_bytes = 0 + + async def publish_update( + update: AgentResponseUpdate, *, complete_message: bool = False + ) -> AsyncGenerator[ResponseStreamEvent]: + approval_requests = [ + content for content in update.contents if content.type == "function_approval_request" + ] + if approval_requests: + if not stored or session_storage is None: + raise ValueError("Approval and user-input continuation requires store=true.") + pending = _load_pending_approval_requests(session) + for request in approval_requests: + recorded = pending.get(request.id) if request.id is not None else None + if recorded is None or recorded.to_dict() != request.to_dict(): + raise _PublicResponseFailure( + ValueError( + "The agent emitted an approval request without matching native pending state. " + "Use native agent/session approval handling before the run completes." + ) + ) + await _set_agent_session(session_storage, context.response_id, session) + if context.conversation_id is not None: + await _set_agent_session(session_storage, context.conversation_id, session) + async for event in tracker.handle_update( + update, complete_message=complete_message, approval_session_id=session.session_id + ): + yield event + if provider_background: if session_storage is None or not isinstance(agent, RawAgent): raise RuntimeError("Provider background requires a stored MAF agent session.") @@ -1078,9 +1118,7 @@ async def _handle_inner_agent( for update in _agent_response_updates(response, context.response_id): if context.shutdown.is_set() or cancellation_signal.is_set(): break - async for event in tracker.handle_update( - update, approval_storage=approval_storage, complete_message=True - ): + async for event in publish_update(update, complete_message=True): yield event if context.shutdown.is_set() or cancellation_signal.is_set(): continue @@ -1102,8 +1140,29 @@ async def _handle_inner_agent( for content in update.contents ): raise ValueError("Approval and user-input continuation requires store=true.") - async for event in tracker.handle_update(update, approval_storage=approval_storage): - yield event + if deferred_updates or any( + content.type == "function_approval_request" for content in update.contents + ): + # Native providers can record approval authority only after their stream + # finishes. Keep subsequent output ordered behind that approval. + if len(deferred_updates) >= _MAX_DEFERRED_APPROVAL_UPDATES: + raise _PublicResponseFailure( + ValueError("Deferred approval output exceeds the update-count limit.") + ) + update_bytes = len( + update.to_json(ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode( + "utf-8" + ) + ) + if deferred_bytes + update_bytes > _MAX_DEFERRED_APPROVAL_BYTES: + raise _PublicResponseFailure( + ValueError("Deferred approval output exceeds the serialized-size limit.") + ) + deferred_bytes += update_bytes + deferred_updates.append(update) + else: + async for event in publish_update(update): + yield event if inner_stream is not None and isinstance(updates, _SignalledIterator) and not updates.signalled: final = await inner_stream.get_final_response() if final.continuation_token is not None and final.finish_reason is None: @@ -1112,6 +1171,9 @@ async def _handle_inner_agent( "configure background_source='inference_service' with history_source='inference_service' " "to resume it." ) + for update in deferred_updates: + async for event in publish_update(update): + yield event except (asyncio.CancelledError, GeneratorExit): request_interrupted = True raise diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py index 9fe5ce7b3ab..9f60e5cedf8 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_shared.py @@ -22,6 +22,7 @@ ) from contextlib import suppress from dataclasses import asdict, dataclass, is_dataclass +from decimal import Decimal from typing import Any, Generic, Literal, TypeGuard, TypeVar, cast from urllib.parse import urlparse @@ -43,6 +44,10 @@ Annotation as FrameworkAnnotation, ) from agent_framework._mcp import _MCP_TOOL_RESULT_HOST_PAYLOAD_KEY # pyright: ignore[reportPrivateUsage] +from agent_framework._tools import ( + _bind_approval_response_to_pending_request, # pyright: ignore[reportPrivateUsage] + _load_pending_approval_requests, # pyright: ignore[reportPrivateUsage] +) from agent_framework._types import _get_annotation_text_span_regions # pyright: ignore[reportPrivateUsage] from agent_framework.observability import OBSERVABILITY_SETTINGS from azure.ai.agentserver.responses import ( @@ -73,6 +78,7 @@ OutputItem, OutputItemComputerToolCall, OutputItemComputerToolCallOutput, + OutputItemMcpApprovalRequest, OutputItemReasoningItem, OutputMessageContent, ResponseIncompleteReason, @@ -93,14 +99,12 @@ ) from mcp import MCPError -from ._state_store import ( - FunctionApprovalStore, -) - logger = logging.getLogger(__name__) _MODEL_OUTPUT_KIND_KEY = "model_output_kind" _MODEL_OUTPUT_REFUSAL = "refusal" +_NATIVE_APPROVAL_ID_KEY = "agent_framework_approval_id" +_NATIVE_APPROVAL_SESSION_KEY = "agent_framework_approval_session_id" _HOSTED_PROVIDER_STATE_KEY = "_foundry_provider_background" _HOSTED_SOURCE_CONVERSATION_KEY = "_foundry_source_conversation" _HOSTED_SERVICE_CHILD_KEY = "_foundry_service_child" @@ -970,8 +974,8 @@ async def handle_update( self, update: AgentResponseUpdate, *, - approval_storage: FunctionApprovalStore | None = None, complete_message: bool = False, + approval_session_id: str | None = None, ) -> AsyncGenerator[ResponseStreamEvent]: """Process one agent update: note its finish reason, then handle each of its contents. @@ -985,8 +989,8 @@ async def handle_update( async for event in self.handle( content, message_id=update.message_id, - approval_storage=approval_storage, start_new_content_part=complete_message, + approval_session_id=approval_session_id, ): yield event @@ -995,8 +999,8 @@ async def handle( content: Content, message_id: str | None = None, *, - approval_storage: FunctionApprovalStore | None = None, start_new_content_part: bool = False, + approval_session_id: str | None = None, ) -> AsyncGenerator[ResponseStreamEvent]: """Process a content item, yielding its events. @@ -1006,10 +1010,9 @@ async def handle( change in ``message_id`` across otherwise same-typed text content marks a new logical message and forces the previous output item closed, rather than being merged into it. - approval_storage: Used for content types that fall back to one-shot emission - (anything not recognized as a streaming delta type) to save/load approval requests. start_new_content_part: Whether text and refusal content start a new independent content part instead of continuing the current streaming occurrence. + approval_session_id: Native session identity used only to scope stored wire correlation. """ if _is_refusal_text_content(content) and content.text is not None: for event in self._ensure_message_content("refusal", message_id, start_new_part=start_new_content_part): @@ -1250,33 +1253,24 @@ async def handle( elif content.type == "function_approval_request": for event in self._close(): yield event - function_call: Content = content.function_call # type: ignore + function_call = content.function_call + if not content.id or function_call is None or not function_call.name: + raise ValueError("An approval request requires a native request ID and a named function call.") server_label = function_call.server_name or "agent_framework" - request_saved = False - async for event in self._stream.output_item_mcp_approval_request( - server_label, - function_call.name, # type: ignore - _json_safe_to_str(function_call.arguments), - ): - if approval_storage is not None and not request_saved: - # Extract the approval request ID generated by the infrastructure when the - # approval request item is added to the stream, and save it to approval - # storage so it can be retrieved later for round trips. - item = event.get("item") if isinstance(event, Mapping) else getattr(event, "item", None) - approval_request_id = ( - cast(Mapping[str, Any], item).get("id") - if isinstance(item, Mapping) - else getattr(item, "id", None) - ) - if isinstance(approval_request_id, str): - await approval_storage.save_approval_request(approval_request_id, content) - request_saved = True - yield event - if approval_storage is not None and not request_saved: - logger.warning( - "Approval request was not saved to approval storage because the approval request ID " - "could not be extracted from the stream event." - ) + wire_id = IdGenerator.new_mcp_approval_request_item_id(str(self._stream.response["id"])) + item = OutputItemMcpApprovalRequest( + type="mcp_approval_request", + id=wire_id, + server_label=server_label, + name=function_call.name, + arguments=_json_safe_to_str(function_call.arguments), + ) + builder = self._stream.add_output_item(wire_id) + builder.internal_metadata[_NATIVE_APPROVAL_ID_KEY] = content.id + if approval_session_id is not None: + builder.internal_metadata[_NATIVE_APPROVAL_SESSION_KEY] = approval_session_id + yield builder.emit_added(item) + yield builder.emit_done(item) elif content.type == "oauth_consent_request": for event in self._close(): @@ -1573,21 +1567,40 @@ def _persist_pending_container_file_citations(self) -> None: async def _items_to_messages( # pyright: ignore[reportUnusedFunction] - input_items: Sequence[Item], *, approval_storage: FunctionApprovalStore | None = None + input_items: Sequence[Item], + *, + session: AgentSession | None = None, + approval_ids: Mapping[str, str] | None = None, + include_hosted_approval_requests: bool = False, ) -> list[Message]: - """Converts a sequence of input items to a list of Messages, one per item. + """Convert input items and restore native context for current approval decisions. Args: input_items: The input items to convert. - approval_storage: An optional ApprovalStorage instance used to look up - approval requests when converting MCP approval response items. + + Keyword Args: + session: Native session holding the agent's authoritative pending requests. + approval_ids: Transport-only mapping from stored wire IDs to native request IDs. + include_hosted_approval_requests: Replay hosted requests when hosting owns the stateless + model transcript. Agent-managed or service-side history supplies its own context. Returns: - A list of Messages, one per supported input item. + Native request context followed by the supported input messages. """ messages: list[Message] = [] + if any(item["type"] == "mcp_approval_response" for item in input_items): + requests = [ + request + for request in _load_pending_approval_requests(session).values() + if request.function_call is not None + and (include_hosted_approval_requests or not request.function_call.hosted) + ] + if requests: + # Capped wire history may omit calls. Local snapshots let Core restore call/result + # pairs; hosted snapshots belong only in the host-managed stateless transcript. + messages.append(Message(role="assistant", contents=requests)) for item in input_items: - messages.append(await _item_to_message(item, approval_storage=approval_storage)) + messages.append(await _item_to_message(item, session=session, approval_ids=approval_ids)) return messages @@ -1679,18 +1692,19 @@ def _shell_command_output_to_content(output: Mapping[str, Any]) -> Content: ) -async def _item_to_message( +async def _item_to_message( # ruff: ignore[unused-async] -- Keep the shared async conversion contract. item: Item, *, - approval_storage: FunctionApprovalStore | None = None, + session: AgentSession | None = None, + approval_ids: Mapping[str, str] | None = None, _item_type_name: Literal["Item", "OutputItem"] = "Item", ) -> Message: """Converts an Item to a Message. Args: item: The Item to convert. - approval_storage: An optional ApprovalStorage instance used to look up - approval requests when converting MCP approval response items. + session: Native session holding the agent's authoritative pending requests. + approval_ids: Transport-only mapping from stored wire IDs to native request IDs. _item_type_name: The item type name to include in unsupported-type errors. Returns: @@ -1774,31 +1788,38 @@ async def _item_to_message( ) if item["type"] == "mcp_approval_request": - if approval_storage is not None: - try: - function_approval_request_content = await approval_storage.load_approval_request(item["id"]) - except (KeyError, ValueError) as exc: - raise _PublicResponseFailure(exc) from None - else: - raise ValueError("ApprovalStorage is required to load approval request.") + pending = _load_pending_approval_requests(session) + request_id = approval_ids.get(item["id"]) if approval_ids is not None else item["id"] + function_approval_request_content = pending.get(request_id) if request_id is not None else None + if function_approval_request_content is None: + raise _PublicResponseFailure(ValueError(f"No native pending approval matches {item['id']!r}.")) return Message( role="assistant", contents=[function_approval_request_content], ) if item["type"] == "mcp_approval_response": - if approval_storage is not None: - try: - function_approval_request_content = await approval_storage.load_approval_request( - item["approval_request_id"] - ) - except (KeyError, ValueError) as exc: - raise _PublicResponseFailure(exc) from None - else: - raise ValueError("ApprovalStorage is required to load approval request.") + request_id = ( + approval_ids.get(item["approval_request_id"]) if approval_ids is not None else item["approval_request_id"] + ) + response = Content( + "function_approval_response", + id=request_id, + approved=item["approve"] is True, + ) + bound = ( + _bind_approval_response_to_pending_request(response, session, consume=False) + if session is not None and request_id is not None + else None + ) + if bound is None: + raise _PublicResponseFailure( + ValueError(f"No native pending approval matches {item['approval_request_id']!r}.") + ) + response.function_call = bound.function_call return Message( role="user", - contents=[function_approval_request_content.to_function_approval_response(item["approve"])], + contents=[response], ) if item["type"] == "code_interpreter_call": @@ -1985,34 +2006,93 @@ async def _item_to_message( async def _output_items_to_messages( # pyright: ignore[reportUnusedFunction] history: Sequence[OutputItem], - *, - approval_storage: FunctionApprovalStore | None = None, ) -> list[Message]: """Converts a sequence of OutputItem objects to a list of Message objects. + Historical approval controls are not replayed. Native session state owns + pending requests; only current input carries new approval decisions. + Args: history (Sequence[OutputItem]): The sequence of OutputItem objects to convert. - approval_storage (ApprovalStorage | None, optional): The approval storage to use for - resolving MCP approval requests. Defaults to None. Returns: list[Message]: The list of Message objects. """ messages: list[Message] = [] for item in history: - messages.append(await _output_item_to_message(item, approval_storage=approval_storage)) + if item["type"] in ("mcp_approval_request", "mcp_approval_response"): + continue + messages.append(await _output_item_to_message(item)) return messages -async def _output_item_to_message( - item: OutputItem, *, approval_storage: FunctionApprovalStore | None = None -) -> Message: +def _approval_arguments_match(stored: Any, current: Any) -> bool: + """Compare wire arguments without coercing JSON value types or rounding numbers.""" + if not isinstance(stored, str): + return False + current_text = _json_safe_to_str(current) + if stored == current_text: + return True + try: + stored_value = json.loads(stored, parse_float=Decimal) + current_value = json.loads(current_text, parse_float=Decimal) + except json.JSONDecodeError: + return False + + def matches(left: Any, right: Any) -> bool: + if type(left) is not type(right): + return False + if isinstance(left, dict): + left_dict = cast(dict[str, Any], left) + right_dict = cast(dict[str, Any], right) + return left_dict.keys() == right_dict.keys() and all( + matches(value, right_dict[key]) for key, value in left_dict.items() + ) + if isinstance(left, list): + left_list = cast(list[Any], left) + right_list = cast(list[Any], right) + return len(left_list) == len(right_list) and all( + matches(left_item, right_item) for left_item, right_item in zip(left_list, right_list, strict=True) + ) + return bool(left == right) + + return matches(stored_value, current_value) + + +def _native_approval_id( # pyright: ignore[reportUnusedFunction] + item: Mapping[str, Any], *, session: AgentSession | None = None +) -> str: + """Resolve stored wire correlation without allowing it to redirect native authority.""" + raw_metadata = item.get("internal_metadata") + metadata: Mapping[str, Any] = cast(Mapping[str, Any], raw_metadata) if isinstance(raw_metadata, Mapping) else {} + request_id = metadata.get(_NATIVE_APPROVAL_ID_KEY) + if not isinstance(request_id, str) or not request_id: + raise _PublicResponseFailure( + ValueError("The approval uses an unsupported stored format; start a new conversation.") + ) + if session is not None: + if metadata.get(_NATIVE_APPROVAL_SESSION_KEY) != session.session_id: + raise _PublicResponseFailure(ValueError("The approval does not belong to this native session.")) + request = _load_pending_approval_requests(session).get(request_id) + function_call = request.function_call if request is not None else None + if ( + function_call is None + or item.get("server_label") != (function_call.server_name or "agent_framework") + or item.get("name") != function_call.name + or not _approval_arguments_match(item.get("arguments"), function_call.arguments) + ): + raise _PublicResponseFailure( + ValueError("The stored approval does not match the current native pending request.") + ) + return request_id + + +async def _output_item_to_message(item: OutputItem, *, session: AgentSession | None = None) -> Message: """Converts an OutputItem to a Message. Args: item (OutputItem): The OutputItem to convert. - approval_storage (ApprovalStorage | None, optional): The approval storage to use for - resolving MCP approval requests. Defaults to None. + session: Native session holding the agent's authoritative pending requests. Returns: Message: The converted Message. @@ -2046,7 +2126,7 @@ async def _output_item_to_message( return await _item_to_message( cast(Item, item), - approval_storage=approval_storage, + session=session, _item_type_name="OutputItem", ) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py index 8b1805073ff..fdf550fed5d 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py @@ -50,6 +50,7 @@ _agent_response_updates, # pyright: ignore[reportPrivateUsage] _hosted_internal_metadata, # pyright: ignore[reportPrivateUsage] _item_to_message, # pyright: ignore[reportPrivateUsage] + _native_approval_id, # pyright: ignore[reportPrivateUsage] _normalize_allowed_oauth_consent_origins, # pyright: ignore[reportPrivateUsage] _OutputItemTracker, # pyright: ignore[reportPrivateUsage] _request_without_reserved_metadata, # pyright: ignore[reportPrivateUsage] @@ -57,8 +58,12 @@ ) from ._scope import FoundryRequestScope from ._shared import ( + CheckpointStoreProvider, + ContextScopedStoreProvider, + HostedWorkflowRun, OptionsHook, ResponsesRequest, + WorkflowConflictError, WorkflowResolver, WorkflowSource, WorkflowTurn, @@ -70,8 +75,6 @@ validate_workflow_source, workflow_agents, ) -from ._state_store import CheckpointStoreProvider, ContextScopedStoreProvider -from ._workflow_state import HostedWorkflowRun, WorkflowConflictError logger = logging.getLogger(__name__) @@ -225,36 +228,12 @@ async def _load_replies(request: ResponsesRequest, run: HostedWorkflowRun) -> di return dict(validated.responses or {}) -class _CheckpointApprovals: - """Collect wire aliases in the same per-response pair as the pending checkpoint.""" - - def __init__(self, checkpoint: WorkflowCheckpoint | None, aliases: dict[str, str]) -> None: - self.pending = checkpoint.pending_request_info_events if checkpoint is not None else {} - self.aliases = aliases - - async def save_approval_request(self, approval_request_id: str, request: Content) -> None: - matches = [ - request_id - for request_id, event in self.pending.items() - if isinstance(event.data, Content) and event.data.to_dict() == request.to_dict() - ] - if len(matches) != 1 or matches[0] in self.aliases.values(): - raise _WorkflowRequestError("Approval output must match one unique request in the exact pause checkpoint.") - self.aliases[approval_request_id] = matches[0] - - async def load_approval_request(self, approval_request_id: str) -> Content: - request_id = self.aliases.get(approval_request_id) - event = self.pending.get(request_id) if request_id is not None else None - if event is None or not isinstance(event.data, Content): - raise _WorkflowRequestError("The approval is unavailable in this pending checkpoint.") - return event.data - - async def _project( event: WorkflowEvent[Any], stream: ResponseEventStream, tracker: _OutputItemTracker, - approvals: _CheckpointApprovals, + checkpoint: WorkflowCheckpoint | None, + aliases: dict[str, str], ) -> list[ResponseStreamEvent]: updates: list[AgentResponseUpdate] = [] complete_message = False @@ -265,14 +244,14 @@ async def _project( elif isinstance(event.data, Content) and event.data.type in ("function_call", "computer_tool_call"): content = Content.from_dict(event.data.to_dict()) content.call_id = wire_id - approvals.aliases[wire_id] = event.request_id + aliases[wire_id] = event.request_id else: content = Content.from_function_call( wire_id, "request_info", arguments={"request_id": wire_id, "request": _wire_value(event.data)}, ) - approvals.aliases[wire_id] = event.request_id + aliases[wire_id] = event.request_id if isinstance(event.data, Content) and event.data.type == "oauth_consent_request": updates.append(AgentResponseUpdate(contents=[event.data])) updates.append(AgentResponseUpdate(contents=[content])) @@ -317,14 +296,41 @@ async def _project( return events events: list[ResponseStreamEvent] = [] for update in updates: - events.extend([ + projected = [ item async for item in tracker.handle_update( update, - approval_storage=approvals, complete_message=complete_message, ) - ]) + ] + for item_event in projected: + raw_item = item_event.get("item") + if item_event.get("type") != "response.output_item.added" or not isinstance(raw_item, Mapping): + continue + item = cast(Mapping[str, Any], raw_item) + if item.get("type") != "mcp_approval_request": + continue + native_id = _native_approval_id(item) + approval_content = next( + content + for content in update.contents + if content.type == "function_approval_request" and content.id == native_id + ) + pending = checkpoint.pending_request_info_events if checkpoint is not None else {} + matches = [ + request_id + for request_id, request in pending.items() + if isinstance(request.data, Content) + and request.data.type == "function_approval_request" + and request.data.to_dict() == approval_content.to_dict() + ] + wire_id = item.get("id") + if not isinstance(wire_id, str) or len(matches) != 1 or matches[0] in aliases.values(): + raise _WorkflowRequestError( + "Approval output must match one unique request in the exact pause checkpoint." + ) + aliases[wire_id] = matches[0] + events.extend(projected) return events @@ -354,6 +360,9 @@ def __init__( Build fresh workflows, executors, agents, clients, providers, and mutable tools inside the factory. Keep workflow and executor IDs stable for checkpoint restoration. The host closes context-managed agents returned by the factory; applications own other resource cleanup. + Construct tool objects inside the factory. A module-level `@tool` creates a shared wrapper, + which the ownership guard rejects even for a pure function. A function defined elsewhere can + be wrapped with `tool(function)` inside the factory; applications still own any captured state. Keyword Args: parse_input: Sync or async parser of this turn's `ResponsesRequest`. Return a typed @@ -585,10 +594,9 @@ async def flush(checkpoint_id: str | None) -> list[ResponseStreamEvent]: draft.emit_created() draft.emit_in_progress() next_tracker = _OutputItemTracker(draft, self._allowed_origins) - approval_projection = _CheckpointApprovals(checkpoint, next_aliases) events: list[ResponseStreamEvent] = [] for event in buffered: - events.extend(await _project(event, draft, next_tracker, approval_projection)) + events.extend(await _project(event, draft, next_tracker, checkpoint, next_aliases)) events.extend(next_tracker.close()) _hosted_internal_metadata(draft)[_HOSTED_PROVIDER_USAGE_KEY] = next_tracker.usage_details await run.stage(_snapshot(draft), approvals=next_aliases, checkpoint_id=checkpoint_id) diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py index 09b316b995e..b162b9e2a07 100644 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py +++ b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py @@ -1,15 +1,21 @@ # Copyright (c) Microsoft. All rights reserved. -"""Share request contracts, options, and request-owned agent and workflow factories across Foundry hosts.""" +"""Share request contracts, options, factories, and native-state handling across Foundry hosts.""" from __future__ import annotations +import hashlib import inspect +import json +import logging +import secrets import weakref +from abc import ABC, abstractmethod from collections import OrderedDict -from collections.abc import Awaitable, Callable, Iterator, Mapping, Sequence +from collections.abc import AsyncGenerator, Awaitable, Callable, Iterator, Mapping, Sequence from copy import deepcopy -from dataclasses import dataclass, field +from dataclasses import asdict, dataclass, field, replace +from datetime import datetime from types import MappingProxyType from typing import Any, Generic, Literal, Protocol, TypeAlias, TypeGuard, cast @@ -19,20 +25,48 @@ AgentExecutor, AgentMiddleware, AgentResponse, + AgentResponseUpdate, AgentRunInputs, + AgentSession, + ChatResponse, + ChatResponseUpdate, + CheckpointID, + CheckpointStorage, Content, HistoryProvider, InMemoryHistoryProvider, Message, RawAgent, + SessionStore, SupportsAgentRun, Workflow, WorkflowAgent, WorkflowCheckpoint, + WorkflowCheckpointException, + WorkflowEvent, WorkflowExecutor, WorkflowInvocationKwargs, WorkflowRunState, ) +from agent_framework._workflows._agent_executor import ( + _validate_computer_tool_result, # pyright: ignore[reportPrivateUsage] +) +from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value +from agent_framework._workflows._const import ( + RESOLVED_WORKFLOW_RUN_KWARGS_KEY, + ROUTED_WORKFLOW_RUN_KWARGS_KEY, + WORKFLOW_RUN_KWARGS_KEY, +) +from agent_framework._workflows._typing_utils import is_instance_of +from agent_framework._workflows._workflow import ( + _coerce_request_info_response, # pyright: ignore[reportPrivateUsage] +) +from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext +from azure.ai.agentserver.core.storage import ( + FoundryStateStore, + FoundryStorageConflictError, + FoundryStoragePreconditionError, +) from azure.ai.agentserver.responses import ResponseContext, ResponsesServerOptions from azure.ai.agentserver.responses.models import CreateResponse, Item from typing_extensions import TypeVar @@ -291,7 +325,7 @@ async def response_input_messages(request: ResponsesRequest) -> list[Message]: """ from ._responses_shared import _items_to_messages # pyright: ignore[reportPrivateUsage] - return await _items_to_messages(await request.get_input_items(), approval_storage=None) + return await _items_to_messages(await request.get_input_items()) def validate_request_options(options: Mapping[str, Any]) -> None: @@ -756,3 +790,1301 @@ def collect(graph: Workflow) -> None: def _forget(self, key: int, reference: weakref.ReferenceType[Any]) -> None: if self._owned.get(key) is reference: del self._owned[key] + + +StoreT = TypeVar("StoreT") + + +def _encoded_checkpoint_hash(value: Any) -> str: + """Hash the exact JSON-compatible representation acknowledged by storage.""" + payload = json.dumps(value, sort_keys=True, allow_nan=False, separators=(",", ":")).encode("utf-8") + return hashlib.sha256(payload).hexdigest() + + +def _select_latest_checkpoint(checkpoints: list[WorkflowCheckpoint]) -> WorkflowCheckpoint: + """Return the latest checkpoint, resolving timestamp ties through the lineage chain. + + Mirrors the tie-breaker used by the core checkpoint storages. Checkpoints taken at the + same superstep boundary can share a timestamp. Among the checkpoints with the newest + timestamp, one that another of them names as its ``previous_checkpoint_id`` is + superseded, so the result does not depend on the order the store lists keys in. + If several unsuperseded candidates remain, the one with the greatest ``checkpoint_id`` + is returned, so the choice among them is stable too. + """ + newest_timestamp = max(datetime.fromisoformat(cp.timestamp) for cp in checkpoints) + candidates = [cp for cp in checkpoints if datetime.fromisoformat(cp.timestamp) == newest_timestamp] + superseded_ids = {cp.previous_checkpoint_id for cp in candidates} + leaves = [cp for cp in candidates if cp.checkpoint_id not in superseded_ids] + return max(leaves or candidates, key=lambda cp: cp.checkpoint_id) + + +def _store_scope(config: AgentConfig, platform_context: FoundryAgentRequestContext) -> FoundryRequestScope | None: + if not config.is_hosted: + return None + return FoundryRequestScope.from_context(config, platform_context) + + +def _store_name(root: str, scope: FoundryRequestScope | None, context_id: str | None = None) -> str: + if scope is None: + return f"{root}/{context_id}" if context_id is not None else root + name = f"{root}/v2/{scope.storage_key}" + if context_id is not None: + name += f"/{hashlib.sha256(context_id.encode('utf-8')).hexdigest()[:24]}" + return name + + +class StoreProvider(ABC, Generic[StoreT]): + """Provide store for a hosting environment.""" + + @abstractmethod + def get_store(self, *, config: AgentConfig, platform_context: FoundryAgentRequestContext) -> StoreT: + """Get store for a hosting environment. + + Args: + config: The resolved agent server configuration. + platform_context: The request-scoped platform context for the current request. + + Returns: + The store instance for the given hosting environment. + """ + + +class ContextScopedStoreProvider(ABC, Generic[StoreT]): + """Provide a context-scoped store for a hosting environment. + + Use this when state must be queried or managed as a collection belonging to + one context, rather than accessed only by an individual item ID. The context + can be a conversation ID or another identifier that groups related state. + """ + + @abstractmethod + def get_store( + self, + *, + config: AgentConfig, + context_id: str, + platform_context: FoundryAgentRequestContext, + ) -> StoreT: + """Get a context-scoped store for a hosting environment. + + Args: + config: The resolved agent server configuration. + context_id: A string that uniquely identifies the context for which the store is scoped. + platform_context: The request-scoped platform context for the current request. + + Returns: + The store instance for the given hosting environment and context ID. + """ + + +# region Checkpoint persistence + + +class FoundryCheckpointStore: + """Checkpoint store backed by the `FoundryStateStore`.""" + + DEFAULT_ROOT_SCOPE = "checkpoints" + + def __init__( + self, + context_id: str, + platform_context: FoundryAgentRequestContext, + *, + allowed_checkpoint_types: list[str] | None = None, + scope: FoundryRequestScope | None = None, + ) -> None: + """Initialize a Foundry-scoped checkpoint store for the given context ID. + + Args: + context_id: A string that uniquely identifies the context for which the checkpoint store is scoped. + This can be used to isolate checkpoints for different workflow runs. + platform_context: The request-scoped platform context for the current request. + allowed_checkpoint_types: Additional types (beyond the built-in safe set + and framework types) that are permitted during checkpoint + deserialization. Each entry should be a ``"module:qualname"`` + string (e.g., ``"my_app.models:MyState"``). + scope: Trusted request scope for hosted sandbox isolation. + """ + if not context_id: + raise ValueError("context_id must be provided to initialize a FoundryCheckpointStore.") + + self.context_id = context_id + self.platform_context = platform_context + self._allowed_types: frozenset[str] = frozenset(allowed_checkpoint_types or []) + self._scope = scope + + async def _get_store(self) -> FoundryStateStore: + return await FoundryStateStore.get_or_create( + _store_name(self.DEFAULT_ROOT_SCOPE, self._scope, self.context_id), + user_isolation=True, + ) + + async def save(self, checkpoint: WorkflowCheckpoint) -> CheckpointID: + """Save a workflow checkpoint to the store. + + Args: + checkpoint: The workflow checkpoint to save. + + The checkpoint will be serialized to a dictionary and then encoded before being stored. + + Returns: + The ID of the saved checkpoint. + """ + from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value + + encoded_checkpoint = encode_checkpoint_value(checkpoint.to_dict()) + + store = await self._get_store() + async with store: + await store.set_item(checkpoint.checkpoint_id, encoded_checkpoint, call_id=self.platform_context.call_id) + return checkpoint.checkpoint_id + + async def _load_encoded(self, checkpoint_id: CheckpointID) -> Any: + store = await self._get_store() + async with store: + item = await store.get_item(checkpoint_id, call_id=self.platform_context.call_id) + if item is None: + raise WorkflowCheckpointException(f"No checkpoint found with ID {checkpoint_id}") + return item.value + + async def load(self, checkpoint_id: CheckpointID) -> WorkflowCheckpoint: + """Load a workflow checkpoint from the store. + + Args: + checkpoint_id: The ID of the checkpoint to load. + + Returns: + The loaded workflow checkpoint. + + Raises: + WorkflowCheckpointException: If no checkpoint is found with the given ID. + """ + from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value + + encoded = await self._load_encoded(checkpoint_id) + return WorkflowCheckpoint.from_dict(decode_checkpoint_value(encoded, allowed_types=self._allowed_types)) + + async def load_with_hash(self, checkpoint_id: CheckpointID) -> tuple[WorkflowCheckpoint, str]: + """Load a checkpoint and hash its exact persisted encoding. + + Pickle is not a canonical serialization across Python versions or repeated + encodes. Hashing the acknowledged storage value preserves exact tamper + detection without rejecting an unchanged checkpoint after deserialization. + """ + from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value + + encoded = await self._load_encoded(checkpoint_id) + checkpoint = WorkflowCheckpoint.from_dict(decode_checkpoint_value(encoded, allowed_types=self._allowed_types)) + return checkpoint, _encoded_checkpoint_hash(encoded) + + async def list_checkpoints(self, *, workflow_name: str) -> list[WorkflowCheckpoint]: + """List all workflow checkpoints for a given workflow name.""" + from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value + + store = await self._get_store() + checkpoints: list[WorkflowCheckpoint] = [] + after: str | None = None + async with store: + while True: + page = await store.list_keys(after=after, call_id=self.platform_context.call_id) + for item_key in page.keys: + item = await store.get_item(item_key.key, call_id=self.platform_context.call_id) + if item is None: + continue + checkpoint = WorkflowCheckpoint.from_dict( + decode_checkpoint_value(item.value, allowed_types=self._allowed_types) + ) + if checkpoint.workflow_name == workflow_name: + checkpoints.append(checkpoint) + if not page.has_more or page.last_id is None: + break + after = page.last_id + return checkpoints + + async def delete(self, checkpoint_id: CheckpointID) -> bool: + store = await self._get_store() + async with store: + deleted_item = await store.delete_item(checkpoint_id, call_id=self.platform_context.call_id) + return deleted_item.id is not None + + async def get_latest(self, *, workflow_name: str) -> WorkflowCheckpoint | None: + checkpoints = await self.list_checkpoints(workflow_name=workflow_name) + if not checkpoints: + return None + return _select_latest_checkpoint(checkpoints) + + async def list_checkpoint_ids(self, *, workflow_name: str) -> list[CheckpointID]: + checkpoints = await self.list_checkpoints(workflow_name=workflow_name) + return [checkpoint.checkpoint_id for checkpoint in checkpoints] + + +class CheckpointStoreProvider(ContextScopedStoreProvider[CheckpointStorage]): + """Provide workflow checkpoint store scoped to a context. + + A workflow context can contain multiple checkpoints. Scoping establishes the + collection boundary used to list checkpoints, restore the latest checkpoint, + and clean up older checkpoints without affecting another workflow context. + + This defaults to using the `FoundryCheckpointStore` in all environments. + """ + + def __init__(self, *, allowed_checkpoint_types: list[str] | None = None) -> None: + """Initialize the provider. + + Args: + allowed_checkpoint_types: Additional types (beyond the built-in safe set + and framework types) that are permitted during checkpoint + deserialization, forwarded to every store this provider creates. + Each entry should be a ``"module:qualname"`` string + (e.g., ``"my_app.models:MyState"``). + """ + self._allowed_checkpoint_types = allowed_checkpoint_types + + def validate_checkpoint_value(self, value: object) -> None: + """Verify a value can round-trip through this provider's restricted decoder. + + Native hosts use this before claiming a stored typed workflow turn so an + omitted application allowlist fails before executors or tools run. + """ + from agent_framework._workflows._checkpoint_encoding import ( + decode_checkpoint_value, + encode_checkpoint_value, + ) + + decode_checkpoint_value( + encode_checkpoint_value(value), + allowed_types=frozenset(self._allowed_checkpoint_types or ()), + ) + + def get_store( + self, + *, + config: AgentConfig, + context_id: str, + platform_context: FoundryAgentRequestContext, + ) -> CheckpointStorage: + """Get checkpoint store for the requested hosting environment.""" + if not context_id: + raise ValueError("context_id must be provided to get a checkpoint store.") + + return self.get_store_for_scope( + context_id=context_id, + platform_context=platform_context, + scope=_store_scope(config, platform_context), + ) + + def get_store_for_scope( + self, + *, + scope: FoundryRequestScope | None, + context_id: str, + platform_context: FoundryAgentRequestContext, + ) -> CheckpointStorage: + """Create a checkpoint store using a host's already validated scope. + + Native hosts use this after protocol-specific identity resolution. + ``get_store`` retains its strict configuration-based scope validation. + + Args: + scope: Trusted user and sandbox scope resolved by the protocol host. + context_id: Native workflow lineage's checkpoint collection. + platform_context: The current request's storage authorization context. + """ + return FoundryCheckpointStore( + context_id, + platform_context, + allowed_checkpoint_types=self._allowed_checkpoint_types, + scope=scope, + ) + + +# endregion Checkpoint persistence + +# region Agent session persistence + + +class FoundryAgentSessionStore(SessionStore): + """Agent session store backed by the `FoundryStateStore`.""" + + DEFAULT_ROOT_SCOPE = "agent_sessions" + + def __init__( + self, + platform_context: FoundryAgentRequestContext, + *, + store_name: str | None = None, + scope: FoundryRequestScope | None = None, + ) -> None: + """Initialize session storage. + + Args: + platform_context: The request-scoped platform context. + store_name: Logical state-store name. Defaults to `agent_sessions`. + scope: Trusted Foundry request scope for sandbox-specific storage. + """ + if store_name is not None and (not isinstance(store_name, str) or not store_name.strip()): + raise ValueError("store_name must be a non-empty string") + self.platform_context = platform_context + self._store_name = self.DEFAULT_ROOT_SCOPE if store_name is None else store_name + self._scope = scope + self._etags: dict[str, str | None] = {} + + async def _get_store(self) -> FoundryStateStore: + return await FoundryStateStore.get_or_create( + _store_name(self._store_name, self._scope), + user_isolation=True, + ) + + async def get(self, session_id: str) -> AgentSession | None: + store = await self._get_store() + async with store: + item = await store.get_item(session_id, call_id=self.platform_context.call_id) + if item is None: + self._etags[session_id] = None + return None + if not item.etag: + raise RuntimeError("Foundry agent session storage returned a loaded session without an ETag.") + self._etags[session_id] = item.etag + return AgentSession.from_dict(item.value) + + async def set(self, session_id: str, session: AgentSession) -> None: + store = await self._get_store() + async with store: + try: + etag = self._etags.get(session_id) + if etag is not None: + result = await store.set_item( + session_id, session.to_dict(), if_match=etag, call_id=self.platform_context.call_id + ) + elif self._scope is not None or session_id in self._etags: + result = await store.create_item( + session_id, session.to_dict(), call_id=self.platform_context.call_id + ) + else: + result = await store.set_item(session_id, session.to_dict(), call_id=self.platform_context.call_id) + except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: + raise RuntimeError("Another request advanced this agent session; reload before writing.") from exc + if not result.etag: + raise RuntimeError("Foundry agent session storage did not return an ETag after saving.") + self._etags[session_id] = result.etag + + async def delete(self, session_id: str) -> None: + store = await self._get_store() + async with store: + await store.delete_item(session_id, call_id=self.platform_context.call_id) + self._etags.pop(session_id, None) + + +class AgentSessionStoreProvider(StoreProvider[SessionStore]): + """Provide agent session store for the active hosting environment. + + This defaults to using the `FoundryAgentSessionStore` in all environments. + """ + + def __init__(self, *, store_name: str | None = None) -> None: + """Initialize the provider. + + Args: + store_name: Logical state-store name. Defaults to `agent_sessions`. + """ + if store_name is not None and (not isinstance(store_name, str) or not store_name.strip()): + raise ValueError("store_name must be a non-empty string") + self._store_name = store_name + + def _get_scoped_store( + self, platform_context: FoundryAgentRequestContext, scope: FoundryRequestScope | None + ) -> SessionStore: + return FoundryAgentSessionStore( + platform_context, + store_name=self._store_name, + scope=scope, + ) + + def get_store(self, *, config: AgentConfig, platform_context: FoundryAgentRequestContext) -> SessionStore: + """Get agent session store for the requested hosting environment.""" + return self._get_scoped_store(platform_context, _store_scope(config, platform_context)) + + +# endregion Agent session persistence + + +# region Native workflow state + +_CONFLICT = "Another request advanced this workflow. Reload its current response or start a fresh lineage." +_BLOCKED = "This workflow turn was interrupted or failed; start a fresh workflow lineage to avoid replaying effects." +logger = logging.getLogger(__name__) + + +class WorkflowConflictError(RuntimeError): + """A scoped workflow head, graph, or reply authority no longer permits this turn.""" + + +class WorkflowBlockedError(WorkflowConflictError): + """A failed or cancelled turn blocks its lineage to prevent uncertain effect replay.""" + + +def _key(kind: str, identifier: str) -> str: + if not isinstance(identifier, str) or not identifier: + raise ValueError("A non-empty workflow state identifier is required.") + return f"{kind}-{hashlib.sha256(identifier.encode('utf-8')).hexdigest()}" + + +def _json_object(value: Mapping[str, Any]) -> dict[str, Any]: + """Validate snapshots without arbitrary encoders or success-shaped string fallbacks.""" + if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value): + raise TypeError("A workflow output snapshot must be a JSON object.") + return cast(dict[str, Any], json.loads(json.dumps(dict(value), allow_nan=False))) + + +def _checkpoint_hash(checkpoint: WorkflowCheckpoint) -> str: + encoded = encode_checkpoint_value(checkpoint.to_dict()) + return hashlib.sha256(json.dumps(encoded, sort_keys=True, allow_nan=False).encode("utf-8")).hexdigest() + + +@dataclass(frozen=True) +class WorkflowBinding: + """The exact checkpoint for one outer response, not a sandbox or provider session.""" + + response_id: str + checkpoint_id: str | None + lineage_id: str + workflow_name: str + graph_hash: str + scope_key: str + checkpoint_hash: str | None = None + conversation_id: str | None = None + previous_response_id: str | None = None + + @classmethod + def from_value(cls, value: Any, scope: FoundryRequestScope) -> WorkflowBinding: + if not isinstance(value, dict): + raise ValueError("Invalid persisted workflow binding.") + value = cast(dict[str, Any], value) + if set(value) != set(cls.__dataclass_fields__): + raise ValueError("Invalid persisted workflow binding.") + for name in ("response_id", "lineage_id", "workflow_name", "graph_hash", "scope_key"): + if not isinstance(value[name], str) or not value[name]: + raise ValueError("Invalid persisted workflow binding.") + for name in ("checkpoint_id", "checkpoint_hash", "conversation_id", "previous_response_id"): + if value[name] is not None and (not isinstance(value[name], str) or not value[name]): + raise ValueError("Invalid persisted workflow binding.") + if (value["checkpoint_id"] is None) != (value["checkpoint_hash"] is None): + raise ValueError("Invalid persisted workflow checkpoint identity.") + binding = cls(**value) + if binding.scope_key != scope.storage_key: + raise PermissionError("The workflow state is not available in this trusted scope.") + return binding + + +@dataclass(frozen=True) +class WorkflowRecord: + """A per-response checkpoint/output pair retained independently of a later head.""" + + binding: WorkflowBinding + owner: str + status: Literal["active", "completed", "blocked"] + snapshot: dict[str, Any] | None = None + approvals: dict[str, str] | None = None + + @classmethod + def from_value(cls, value: Any, scope: FoundryRequestScope) -> WorkflowRecord: + if not isinstance(value, dict): + raise ValueError("Invalid persisted workflow response pair.") + value = cast(dict[str, Any], value) + if set(value) != set(cls.__dataclass_fields__): + raise ValueError("Invalid persisted workflow response pair.") + binding = WorkflowBinding.from_value(value["binding"], scope) + if ( + not isinstance(value["owner"], str) + or not value["owner"] + or value["status"] + not in ( + "active", + "completed", + "blocked", + ) + ): + raise ValueError("Invalid persisted workflow response pair.") + snapshot = value["snapshot"] + if snapshot is not None: + snapshot = _json_object(snapshot) + raw_approvals = value["approvals"] + approvals: dict[str, str] | None = None + if raw_approvals is not None: + if not isinstance(raw_approvals, dict): + raise ValueError("Invalid persisted workflow reply authority.") + approvals = {} + for wire_id, request_id in cast(dict[object, object], raw_approvals).items(): + if not isinstance(wire_id, str) or not wire_id or not isinstance(request_id, str) or not request_id: + raise ValueError("Invalid persisted workflow reply authority.") + approvals[wire_id] = request_id + if value["status"] == "completed" and (binding.checkpoint_id is None or snapshot is None): + raise ValueError("A completed workflow response requires an exact checkpoint/output pair.") + return cls(binding, value["owner"], value["status"], snapshot, approvals) + + +@dataclass(frozen=True) +class WorkflowHead: + """One CAS authority for a lineage, including its optional named conversation.""" + + lineage_id: str + conversation_id: str | None + binding: WorkflowBinding | None = None + response_id: str | None = None + owner: str | None = None + blocked: bool = False + + @classmethod + def from_value(cls, value: Any, scope: FoundryRequestScope) -> WorkflowHead: + if not isinstance(value, dict): + raise ValueError("Invalid persisted workflow head.") + value = cast(dict[str, Any], value) + if set(value) != set(cls.__dataclass_fields__): + raise ValueError("Invalid persisted workflow head.") + if not isinstance(value["lineage_id"], str) or not value["lineage_id"] or type(value["blocked"]) is not bool: + raise ValueError("Invalid persisted workflow head.") + for name in ("conversation_id", "response_id", "owner"): + if value[name] is not None and (not isinstance(value[name], str) or not value[name]): + raise ValueError("Invalid persisted workflow head.") + if (value["owner"] is None) != (value["response_id"] is None): + raise ValueError("Invalid persisted workflow claim.") + binding = WorkflowBinding.from_value(value["binding"], scope) if value["binding"] is not None else None + if binding is not None and ( + binding.lineage_id != value["lineage_id"] or binding.conversation_id != value["conversation_id"] + ): + raise ValueError("Invalid persisted workflow head binding.") + return cls( + value["lineage_id"], + value["conversation_id"], + binding, + value["response_id"], + value["owner"], + value["blocked"], + ) + + +class FoundryWorkflowBindingStore: + """Persist scoped per-response pairs and fenced linear workflow claims.""" + + def __init__(self, scope: FoundryRequestScope) -> None: + self.scope = scope + + async def _get_store(self) -> FoundryStateStore: + return await FoundryStateStore.get_or_create( + f"workflow_bindings/v2/{self.scope.storage_key}", user_isolation=True + ) + + async def get_response(self, response_id: str) -> tuple[WorkflowRecord | None, str | None]: + store = await self._get_store() + async with store: + item = await store.get_item(_key("response", response_id), call_id=self.scope.call_id) + if item is None: + return None, None + record = WorkflowRecord.from_value(item.value, self.scope) + if record.binding.response_id != response_id or not item.etag: + raise ValueError("Invalid persisted workflow response identity or ETag.") + return record, item.etag + + async def get_head(self, lineage_id: str, conversation_id: str | None) -> tuple[WorkflowHead | None, str | None]: + store = await self._get_store() + key = _key("conversation", conversation_id) if conversation_id is not None else _key("lineage", lineage_id) + async with store: + item = await store.get_item(key, call_id=self.scope.call_id) + if item is None: + return None, None + head = WorkflowHead.from_value(item.value, self.scope) + if ( + head.conversation_id != conversation_id + or (conversation_id is None and head.lineage_id != lineage_id) + or not item.etag + ): + raise ValueError("Invalid persisted workflow head identity or ETag.") + return head, item.etag + + async def save_response(self, record: WorkflowRecord, *, expected_etag: str | None) -> str: + if record.binding.scope_key != self.scope.storage_key: + raise PermissionError("Cannot write workflow state outside its trusted scope.") + return await self._write(_key("response", record.binding.response_id), asdict(record), expected_etag) + + async def save_head(self, head: WorkflowHead, *, expected_etag: str | None) -> str: + if head.binding is not None and head.binding.scope_key != self.scope.storage_key: + raise PermissionError("Cannot write workflow state outside its trusted scope.") + key = ( + _key("conversation", head.conversation_id) + if head.conversation_id is not None + else _key("lineage", head.lineage_id) + ) + return await self._write(key, asdict(head), expected_etag) + + async def delete_response(self, response_id: str, *, expected_etag: str) -> bool: + """Conditionally delete a superseded response record.""" + store = await self._get_store() + async with store: + try: + deleted = await store.delete_item( + _key("response", response_id), + if_match=expected_etag, + call_id=self.scope.call_id, + ) + except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: + raise WorkflowConflictError(_CONFLICT) from exc + return deleted.id is not None + + async def _write(self, key: str, value: dict[str, Any], expected_etag: str | None) -> str: + store = await self._get_store() + async with store: + try: + if expected_etag is None: + result = await store.create_item(key, value, call_id=self.scope.call_id) + else: + result = await store.set_item(key, value, if_match=expected_etag, call_id=self.scope.call_id) + except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: + raise WorkflowConflictError(_CONFLICT) from exc + if not result.etag: + raise RuntimeError("Workflow storage did not acknowledge a conditional write with an ETag.") + return result.etag + + +class _CheckpointWrites: + """Track acknowledged core saves, never selecting an unrelated latest checkpoint.""" + + def __init__(self, storage: CheckpointStorage, run: HostedWorkflowRun) -> None: + self.storage = storage + self.run = run + self.last_checkpoint: WorkflowCheckpoint | None = None + self.acknowledged_ids: set[str] = set() + + async def save(self, checkpoint: WorkflowCheckpoint) -> str: + await self.run.assert_claim() + validate_workflow_provider_state(self.run.workflow, checkpoint) + identifier = await self.storage.save(checkpoint) + if identifier != checkpoint.checkpoint_id: + raise RuntimeError("Workflow checkpoint storage acknowledged a different checkpoint.") + self.last_checkpoint = checkpoint + self.acknowledged_ids.add(identifier) + return identifier + + async def load(self, checkpoint_id: str) -> WorkflowCheckpoint: + checkpoint = await self.storage.load(checkpoint_id) + # Core checkpoint restoration follows run-kwargs setup. Retain fresh request + # kwargs rather than restoring the previous request's private call context. + fresh = self.run.workflow._runner.state.export_state() # pyright: ignore[reportPrivateUsage] + state = dict(checkpoint.state) + for key in (WORKFLOW_RUN_KWARGS_KEY, RESOLVED_WORKFLOW_RUN_KWARGS_KEY, ROUTED_WORKFLOW_RUN_KWARGS_KEY): + state[key] = fresh.get(key, {}) + return replace(checkpoint, state=state) + + async def load_persisted(self, checkpoint_id: str) -> tuple[WorkflowCheckpoint, str]: + """Load a checkpoint with a process-stable integrity hash when supported.""" + load_with_hash = getattr(cast(Any, self.storage), "load_with_hash", None) + if callable(load_with_hash): + loader = cast( + Callable[[str], Awaitable[tuple[WorkflowCheckpoint, str]]], + load_with_hash, + ) + checkpoint, checkpoint_hash = await loader(checkpoint_id) + if not isinstance(checkpoint, WorkflowCheckpoint) or not isinstance(checkpoint_hash, str): + raise TypeError("Checkpoint storage returned an invalid checkpoint integrity pair.") + return checkpoint, checkpoint_hash + checkpoint = await self.storage.load(checkpoint_id) + return checkpoint, _checkpoint_hash(checkpoint) + + async def list_checkpoints(self, *, workflow_name: str) -> list[WorkflowCheckpoint]: + return await self.storage.list_checkpoints(workflow_name=workflow_name) + + async def list_checkpoint_ids(self, *, workflow_name: str) -> list[str]: + return await self.storage.list_checkpoint_ids(workflow_name=workflow_name) + + async def get_latest(self, *, workflow_name: str) -> WorkflowCheckpoint | None: + return await self.storage.get_latest(workflow_name=workflow_name) + + async def delete(self, checkpoint_id: str) -> bool: + return await self.storage.delete(checkpoint_id) + + +class HostedWorkflowRun: + """A native turn with explicit validation, claim, pairing, commit, and abort boundaries. + + Protocol hosts own output encoding and lifecycle signals. Closing ``events`` + never commits a turn. A failed or cancelled claim is blocked rather than + releasing potentially consumed approvals or replaying external side effects. + """ + + def __init__( + self, + workflow: Workflow, + scope: FoundryRequestScope, + *, + stored: bool, + recovery: bool, + fresh_factory: bool, + reclaim_superseded: bool, + ) -> None: + self.workflow = workflow + self.scope = scope + self.stored = stored + self.recovery = recovery + self.fresh_factory = fresh_factory + self.reclaim_superseded = reclaim_superseded + self.store = FoundryWorkflowBindingStore(scope) + self.binding: WorkflowBinding + self._head: WorkflowHead | None = None + self._head_etag: str | None = None + self._record: WorkflowRecord | None = None + self._record_etag: str | None = None + self._storage: _CheckpointWrites | None = None + self._checkpoint: WorkflowCheckpoint | None = None + self._reply_approvals: dict[str, str] = {} + self._turn: WorkflowTurn[Any] | None = None + self._client_kwargs = WorkflowInvocationKwargs() + self._function_kwargs = WorkflowInvocationKwargs() + self._claimed = False + self._finalized = False + self.already_completed = False + + @classmethod + async def prepare( + cls, + workflow: Workflow, + *, + scope: FoundryRequestScope, + response_id: str, + config: AgentConfig, + platform_context: FoundryAgentRequestContext, + checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage], + previous_response_id: str | None = None, + conversation_id: str | None = None, + lineage_id: str | None = None, + stored: bool = True, + recovery: bool = False, + replay_completed: bool = False, + fresh_factory: bool = False, + reclaim_superseded: bool = False, + ) -> HostedWorkflowRun: + """Read exact continuation state without claiming, consuming replies, or executing.""" + if not workflow.name or not workflow.graph_signature_hash: + raise ValueError("Native workflows require a stable, non-empty workflow name and graph identity.") + if previous_response_id is not None and conversation_id is not None: + raise ValueError("A workflow turn cannot combine previous_response_id and conversation.") + if not stored and (recovery or previous_response_id is not None or conversation_id is not None): + raise ValueError("store=false workflow requests cannot continue stored state; start a one-shot turn.") + run = cls( + workflow, + scope, + stored=stored, + recovery=recovery, + fresh_factory=fresh_factory, + reclaim_superseded=reclaim_superseded, + ) + run.binding = WorkflowBinding( + response_id=response_id, + checkpoint_id=None, + lineage_id=lineage_id or response_id, + workflow_name=workflow.name, + graph_hash=workflow.graph_signature_hash, + scope_key=scope.storage_key, + conversation_id=conversation_id, + previous_response_id=previous_response_id, + ) + if not stored: + return run + + own, own_etag = await run.store.get_response(response_id) + if not recovery and replay_completed and own is not None and own.status == "completed": + recovery = True + run.recovery = True + if recovery and own is not None: + run._record, run._record_etag = own, own_etag + run.binding = own.binding + run._reply_approvals = own.approvals or {} + elif own is not None: + raise WorkflowConflictError( + "This workflow response already exists; retrieve it instead of executing it again." + ) + + previous: WorkflowBinding | None = None + if previous_response_id is not None and (not recovery or own is None): + record, _ = await run.store.get_response(previous_response_id) + if record is None or record.status != "completed": + raise ValueError("The previous response has no completed workflow checkpoint in this trusted scope.") + previous = record.binding + if not recovery: + run._reply_approvals = record.approvals or {} + if previous.conversation_id is not None: + raise ValueError("A named workflow conversation cannot be forked through previous_response_id.") + run.binding = replace(run.binding, lineage_id=previous.lineage_id) + + head, etag = await run.store.get_head(run.binding.lineage_id, run.binding.conversation_id) + run._head, run._head_etag = head, etag + if recovery: + if head is None: + raise RuntimeError("The workflow recovery authority is unavailable; start a fresh lineage.") + if own is None: + if head.response_id != response_id or head.owner is None or head.blocked: + raise WorkflowConflictError(_CONFLICT) + run.binding = replace(run.binding, lineage_id=head.lineage_id) + blocked_record = WorkflowRecord(run.binding, head.owner, "blocked") + await run.store.save_response(blocked_record, expected_etag=None) + await run.store.save_head(replace(head, blocked=True), expected_etag=etag) + raise WorkflowBlockedError(_BLOCKED) + if own.status == "blocked": + if head.response_id == response_id and head.owner == own.owner and not head.blocked: + await run.store.save_head(replace(head, blocked=True), expected_etag=etag) + raise WorkflowBlockedError(_BLOCKED) + if own.binding.checkpoint_id is None or own.snapshot is None: + if head.response_id != response_id or head.owner != own.owner or head.blocked: + raise WorkflowConflictError(_CONFLICT) + blocked_record = replace(own, status="blocked") + await run.store.save_response(blocked_record, expected_etag=own_etag) + await run.store.save_head(replace(head, blocked=True), expected_etag=etag) + raise WorkflowBlockedError(_BLOCKED) + if own.status == "completed": + current = head.binding + visited: set[str] = set() + while current is not None and current != own.binding: + if current.response_id in visited or current.previous_response_id is None: + current = None + break + visited.add(current.response_id) + parent, _ = await run.store.get_response(current.previous_response_id) + current = parent.binding if parent is not None and parent.status == "completed" else None + if current is not None: + run.already_completed = True + elif head.response_id != response_id or head.blocked: + raise WorkflowConflictError(_CONFLICT) + else: + run._finalized = True + elif head.response_id != response_id or head.owner != own.owner or head.blocked: + raise WorkflowConflictError(_CONFLICT) + previous = run.binding + elif head is not None: + if head.blocked: + raise WorkflowBlockedError(_BLOCKED) + if head.response_id is not None: + active_record, _ = await run.store.get_response(head.response_id) + if active_record is None and head.owner is not None: + interrupted_binding = WorkflowBinding( + response_id=head.response_id, + checkpoint_id=None, + lineage_id=head.lineage_id, + workflow_name=workflow.name, + graph_hash=workflow.graph_signature_hash, + scope_key=scope.storage_key, + conversation_id=head.conversation_id, + previous_response_id=head.binding.response_id if head.binding is not None else None, + ) + await run.store.save_response( + WorkflowRecord(interrupted_binding, head.owner, "blocked"), + expected_etag=None, + ) + await run.store.save_head(replace(head, blocked=True), expected_etag=etag) + raise WorkflowBlockedError(_BLOCKED) + raise WorkflowConflictError( + "This workflow has an in-flight turn. Wait for it or start a fresh lineage." + ) + if previous is not None and head.binding != previous: + raise WorkflowConflictError("This workflow continuation is stale or forked; use its current response.") + previous = head.binding + if previous is not None: + record, _ = await run.store.get_response(previous.response_id) + if record is None or record.status != "completed" or record.binding != previous: + raise ValueError("The workflow head has no exact completed response binding.") + run._reply_approvals = record.approvals or {} + run.binding = replace( + run.binding, + lineage_id=head.lineage_id, + previous_response_id=previous.response_id if previous is not None else None, + ) + elif previous is not None: + raise ValueError("The workflow lineage authority is unavailable in this trusted scope.") + + context_id = _key("native", f"{scope.storage_key}:{run.binding.lineage_id}") + storage = ( + checkpoint_store_provider.get_store_for_scope( + scope=scope, context_id=context_id, platform_context=platform_context + ) + if isinstance(checkpoint_store_provider, CheckpointStoreProvider) + else checkpoint_store_provider.get_store( + config=config, context_id=context_id, platform_context=platform_context + ) + ) + run._storage = _CheckpointWrites(storage, run) + if previous is not None: + if previous.workflow_name != workflow.name or previous.graph_hash != workflow.graph_signature_hash: + raise WorkflowConflictError( + "The stored workflow graph is incompatible. Rebuild its original graph or start a fresh lineage." + ) + if previous.checkpoint_id is None: + raise ValueError("The workflow response has no acknowledged checkpoint.") + checkpoint, checkpoint_hash = await run._storage.load_persisted(previous.checkpoint_id) + if ( + checkpoint.checkpoint_id != previous.checkpoint_id + or checkpoint.workflow_name != workflow.name + or checkpoint.graph_signature_hash != workflow.graph_signature_hash + or checkpoint_hash != previous.checkpoint_hash + ): + raise ValueError("The exact workflow checkpoint does not match its response binding.") + run._checkpoint = checkpoint + validate_workflow_provider_state(workflow, checkpoint) + return run + + @property + def snapshot(self) -> dict[str, Any] | None: + """The exact same-response recovery snapshot, independent of the current lineage head.""" + return self._record.snapshot if self._record is not None else None + + @property + def approvals(self) -> Mapping[str, str]: + """Caller-facing approval aliases bound to the loaded response's exact checkpoint.""" + return self._reply_approvals + + @property + def has_completed_output(self) -> bool: + """Whether recovery can deliver already finalized output without rerunning executors.""" + return self._record is not None and self._record.status == "completed" + + @property + def pending_requests(self) -> Mapping[str, WorkflowEvent[Any]]: + """Pending request authority from the exact acknowledged checkpoint.""" + checkpoint = self.current_checkpoint + return checkpoint.pending_request_info_events if checkpoint is not None else {} + + @property + def current_checkpoint(self) -> WorkflowCheckpoint | None: + """The last acknowledged checkpoint from this run, or its exact restoration checkpoint.""" + if self._storage is not None and self._storage.last_checkpoint is not None: + return self._storage.last_checkpoint + return self._checkpoint + + @property + def checkpoint_id(self) -> str | None: + """The exact acknowledged checkpoint ID, never a latest-checkpoint query.""" + checkpoint = self.current_checkpoint + return checkpoint.checkpoint_id if checkpoint is not None else None + + def recovery_turn(self) -> WorkflowTurn[Any]: + """Restore application kwargs without re-parsing already consumed approval input. + + The checkpoint, rather than a new start input or replayed reply, is the + recovery action. Host-injected identity and storage controls are replaced + by ``prepare_workflow_kwargs`` for the current trusted request. + """ + if not self.recovery or self._checkpoint is None: + raise RuntimeError("A recovery turn requires an exact restored checkpoint.") + resolved = self._checkpoint.state.get(RESOLVED_WORKFLOW_RUN_KWARGS_KEY, {}) + if not isinstance(resolved, Mapping): + raise ValueError("Invalid persisted workflow invocation kwargs.") + resolved = cast(Mapping[str, Any], resolved) + + def invocation_kwargs(name: str) -> WorkflowInvocationKwargs: + values = resolved.get(name, {}) + if not isinstance(values, Mapping): + raise ValueError("Invalid persisted workflow invocation kwargs.") + values = cast(Mapping[str, Any], values) + global_kwargs = dict(values.get("global_kwargs", {})) + executor_kwargs = {key: dict(value) for key, value in values.get("executor_kwargs", {}).items()} + if name == "client_kwargs": + for kwargs in (global_kwargs, *executor_kwargs.values()): + kwargs.pop("additional_function_arguments", None) + if "options" in kwargs: + kwargs["options"] = dict(kwargs["options"]) + kwargs["options"].pop("store", None) + return WorkflowInvocationKwargs(global_kwargs, executor_kwargs) + + return WorkflowTurn( + input=self._checkpoint, + client_kwargs=invocation_kwargs("client_kwargs"), + function_invocation_kwargs=invocation_kwargs("function_invocation_kwargs"), + ) + + def validate_turn(self, turn: WorkflowTurn[Any]) -> WorkflowTurn[Any]: + """Validate all input/replies and existing workflow kwargs before claiming authority.""" + if not isinstance(turn, WorkflowTurn): + raise TypeError("The workflow parser must return WorkflowTurn.") + self._client_kwargs, self._function_kwargs = prepare_workflow_kwargs( + self.workflow, + turn, + self.scope, + stored=self.stored, + fresh_factory=self.fresh_factory, + ) + if self.recovery: + self._turn = turn + return turn + pending = self.pending_requests + if turn.responses is not None: + if not self.stored or self._checkpoint is None: + raise ValueError("Workflow replies require a pending stored checkpoint.") + if set(turn.responses) != set(pending) or not pending: + raise ValueError("Workflow replies must answer exactly the complete pending request batch.") + replies: dict[str, Any] = {} + reply_ids: set[tuple[str, str]] = set() + for request_id, reply in turn.responses.items(): + event = pending[request_id] + try: + reply = _coerce_request_info_response(reply, event.response_type, request_id) + except (TypeError, ValueError) as exc: + raise ValueError("A workflow reply does not match its pending request type.") from exc + if isinstance(event.data, Content): + request = event.data + if isinstance(reply, Content): + identifier = reply.id if reply.type == "function_approval_response" else reply.call_id + if identifier is not None: + key = (reply.type, identifier) + if key in reply_ids: + raise ValueError("Duplicate workflow reply authority is not allowed.") + reply_ids.add(key) + if request.type == "function_approval_request" and ( + not isinstance(reply, Content) + or reply.type != "function_approval_response" + or reply.id != request.id + or type(reply.approved) is not bool + or reply.function_call is None + or request.function_call is None + or reply.function_call.to_dict() != request.function_call.to_dict() + ): + raise ValueError("The approval decision does not match its exact pending function call.") + if request.type == "function_call" and ( + not isinstance(reply, Content) + or reply.type != "function_result" + or reply.call_id != request.call_id + ): + raise ValueError("The function result does not match its pending call.") + if request.type == "computer_tool_call": + if not isinstance(reply, Content): + raise ValueError("A computer reply must be typed Content.") + _validate_computer_tool_result(request, reply) + replies[request_id] = reply + turn = replace(turn, responses=replies) + else: + if pending: + raise ValueError("This workflow is awaiting replies; do not replace them with new input.") + if self._checkpoint is not None and any(self._checkpoint.messages.values()): + raise ValueError("The workflow is still in flight; new input cannot replace its checkpoint.") + if not any(is_instance_of(turn.input, input_type) for input_type in self.workflow.input_types): + raise ValueError("The workflow parser's input does not match the start executor's type.") + self._turn = turn + return turn + + async def claim(self) -> None: + """Fence the exact validated turn before any executor or response handler runs.""" + if self._turn is None: + raise RuntimeError("Validate the workflow turn before claiming it.") + if self._claimed or self.already_completed: + return + if not self.stored: + self._claimed = True + return + owner = secrets.token_hex(16) + head = replace( + self._head or WorkflowHead(self.binding.lineage_id, self.binding.conversation_id), + response_id=self.binding.response_id, + owner=owner, + ) + self._head_etag = await self.store.save_head(head, expected_etag=self._head_etag) + self._head = head + self._claimed = True + record = ( + replace(self._record, owner=owner) + if self.recovery and self._record is not None + else WorkflowRecord(self.binding, owner, "active") + ) + self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) + self._record = record + await self._reclaim_completed_ancestors() + + async def assert_claim(self) -> None: + if not self._claimed: + raise RuntimeError("The workflow turn has not been claimed.") + if not self.stored: + return + head, etag = await self.store.get_head(self.binding.lineage_id, self.binding.conversation_id) + if head != self._head or etag != self._head_etag or head is None or head.blocked: + raise WorkflowConflictError(_CONFLICT) + + async def events( + self, + turn: WorkflowTurn[Any], + *, + client_kwargs: WorkflowInvocationKwargs | Mapping[str, Any] | None = None, + function_invocation_kwargs: WorkflowInvocationKwargs | Mapping[str, Any] | None = None, + ) -> AsyncGenerator[WorkflowEvent[Any]]: + """Execute core events, with explicit caller-owned commit and cancellation boundaries.""" + if self.already_completed or self.has_completed_output: + return + await self.assert_claim() + if self._turn is None: + raise RuntimeError("The workflow turn has not been validated.") + turn = self._turn + if self._checkpoint is not None and not self.recovery: + await self.workflow._runner.restore_checkpoint(self._checkpoint) # pyright: ignore[reportPrivateUsage] + stream = self.workflow.run( + None if self.recovery else turn.input, + responses=None if self.recovery else turn.responses, + checkpoint_id=self._checkpoint.checkpoint_id if self.recovery and self._checkpoint is not None else None, + checkpoint_storage=self._storage, + stream=True, + client_kwargs=client_kwargs if client_kwargs is not None else self._client_kwargs, + function_invocation_kwargs=( + function_invocation_kwargs if function_invocation_kwargs is not None else self._function_kwargs + ), + ) + try: + async for event in stream: + data = event.data + if ( + isinstance(data, (AgentResponse, AgentResponseUpdate, ChatResponse, ChatResponseUpdate)) + and data.continuation_token is not None + ): + raise RuntimeError("Native workflows cannot checkpoint unfinished provider background output.") + if event.type == "superstep_completed": + validate_workflow_provider_state(self.workflow) + if event.type == "request_info" and not self.stored: + raise ValueError("Approval and user-input continuation requires store=true.") + yield event + result = await stream.get_final_response() + if result.get_final_state() not in (WorkflowRunState.IDLE, WorkflowRunState.IDLE_WITH_PENDING_REQUESTS): + raise RuntimeError("The workflow did not finalize successfully.") + validate_workflow_provider_state(self.workflow) + self._finalized = True + finally: + await stream.close() + + async def stage( + self, + snapshot: Mapping[str, Any], + *, + approvals: Mapping[str, str] | None = None, + checkpoint_id: str | None = None, + ) -> None: + """CAS-pair output with an acknowledged core checkpoint before publishing its events.""" + if not self.stored: + return + snapshot_value = _json_object(snapshot) + checkpoint, checkpoint_hash = await self._get_checkpoint_with_hash(checkpoint_id or self.checkpoint_id) + if checkpoint is None: + raise RuntimeError("Output cannot be paired before a core checkpoint is acknowledged.") + if approvals is not None and any( + request_id not in checkpoint.pending_request_info_events for request_id in approvals.values() + ): + raise ValueError("Approval authority must belong to this exact pending checkpoint.") + await self.assert_claim() + if self._record is None: + raise RuntimeError("The workflow response pair has not been claimed.") + binding = replace(self.binding, checkpoint_id=checkpoint.checkpoint_id, checkpoint_hash=checkpoint_hash) + pending_approvals = { + wire_id: request_id + for wire_id, request_id in (approvals if approvals is not None else self._record.approvals or {}).items() + if request_id in checkpoint.pending_request_info_events + } + record = replace( + self._record, + binding=binding, + snapshot=snapshot_value, + approvals=pending_approvals, + ) + self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) + self.binding, self._record = binding, record + await self.assert_claim() + + async def get_checkpoint(self, checkpoint_id: str | None) -> WorkflowCheckpoint | None: + """Read a checkpoint acknowledged in this run, including a producer-stamped stream boundary.""" + checkpoint, _ = await self._get_checkpoint_with_hash(checkpoint_id) + return checkpoint + + async def _get_checkpoint_with_hash( + self, checkpoint_id: str | None + ) -> tuple[WorkflowCheckpoint | None, str | None]: + if checkpoint_id is None: + return None, None + if self._storage is None or ( + checkpoint_id not in self._storage.acknowledged_ids + and (self._checkpoint is None or checkpoint_id != self._checkpoint.checkpoint_id) + ): + raise ValueError("Output pairing requires a checkpoint acknowledged by this exact workflow turn.") + checkpoint, checkpoint_hash = await self._storage.load_persisted(checkpoint_id) + if ( + checkpoint.checkpoint_id != checkpoint_id + or checkpoint.workflow_name != self.workflow.name + or checkpoint.graph_signature_hash != self.workflow.graph_signature_hash + ): + raise ValueError("The acknowledged workflow checkpoint identity changed.") + validate_workflow_provider_state(self.workflow, checkpoint) + return checkpoint, checkpoint_hash + + async def commit(self, snapshot: Mapping[str, Any] | None = None) -> None: + """Commit only fully finalized, encoded output, before protocol success or done.""" + if self.already_completed: + return + if not self._finalized: + raise RuntimeError("A workflow cannot commit before successful core finalization.") + if not self.stored: + return + if snapshot is not None: + await self.stage(snapshot) + await self.assert_claim() + if self._record is None or self._record.snapshot is None or self.binding.checkpoint_id != self.checkpoint_id: + raise RuntimeError("The final workflow output has not been paired with its exact checkpoint.") + record = replace(self._record, status="completed") + self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) + self._record = record + head = WorkflowHead(self.binding.lineage_id, self.binding.conversation_id, self.binding) + self._head_etag = await self.store.save_head(head, expected_etag=self._head_etag) + self._head = head + self._claimed = False + + async def _reclaim_completed_ancestors(self) -> None: + """Best-effort reclaim after the new head is durably committed. + + Cleanup is oldest-first. If a deletion fails, newer records retain the + chain needed for a later successful commit to retry cleanup. + """ + if not self.reclaim_superseded or self._storage is None: + return + response_id = self.binding.previous_response_id + records: list[tuple[WorkflowRecord, str]] = [] + visited: set[str] = set() + try: + current_checkpoint_id = self.binding.checkpoint_id + checkpoint_ids = await self._storage.storage.list_checkpoint_ids(workflow_name=self.binding.workflow_name) + for checkpoint_id in checkpoint_ids: + if current_checkpoint_id is None or checkpoint_id != current_checkpoint_id: + await self._storage.storage.delete(checkpoint_id) + while response_id is not None: + if response_id in visited: + raise ValueError("Invalid cycle in superseded workflow response lineage.") + visited.add(response_id) + record, etag = await self.store.get_response(response_id) + if record is None or etag is None: + break + if ( + record.status != "completed" + or record.binding.scope_key != self.scope.storage_key + or record.binding.lineage_id != self.binding.lineage_id + or record.binding.conversation_id != self.binding.conversation_id + ): + break + records.append((record, etag)) + response_id = record.binding.previous_response_id + for record, etag in reversed(records): + await self.store.delete_response(record.binding.response_id, expected_etag=etag) + except Exception: + logger.exception("Failed to reclaim superseded native workflow state; a later commit can retry cleanup") + + async def abort(self) -> None: + """Block interrupted/failed authority instead of permitting unsafe reply or effect replay.""" + if not self.stored or not self._claimed or self.already_completed: + return + await self.assert_claim() + if self._record is not None: + record = replace(self._record, status="blocked") + self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) + self._record = record + if self._head is not None: + head = replace(self._head, blocked=True) + self._head_etag = await self.store.save_head(head, expected_etag=self._head_etag) + self._head = head + self._claimed = False + + +# endregion Native workflow state diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py deleted file mode 100644 index 539287adc74..00000000000 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_state_store.py +++ /dev/null @@ -1,514 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - - -import hashlib -import json -from abc import ABC, abstractmethod -from datetime import datetime -from typing import Any, Generic, Protocol, TypeVar - -from agent_framework import ( - AgentSession, - CheckpointID, - CheckpointStorage, - Content, - SessionStore, - WorkflowCheckpoint, - WorkflowCheckpointException, -) -from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext -from azure.ai.agentserver.core.storage import ( - FoundryStateStore, - FoundryStorageConflictError, - FoundryStoragePreconditionError, -) - -from ._scope import FoundryRequestScope - -StoreT = TypeVar("StoreT") - - -def _encoded_checkpoint_hash(value: Any) -> str: - """Hash the exact JSON-compatible representation acknowledged by storage.""" - payload = json.dumps(value, sort_keys=True, allow_nan=False, separators=(",", ":")).encode("utf-8") - return hashlib.sha256(payload).hexdigest() - - -def _select_latest_checkpoint(checkpoints: list[WorkflowCheckpoint]) -> WorkflowCheckpoint: - """Return the latest checkpoint, resolving timestamp ties through the lineage chain. - - Mirrors the tie-breaker used by the core checkpoint storages. Checkpoints taken at the - same superstep boundary can share a timestamp. Among the checkpoints with the newest - timestamp, one that another of them names as its ``previous_checkpoint_id`` is - superseded, so the result does not depend on the order the store lists keys in. - If several unsuperseded candidates remain, the one with the greatest ``checkpoint_id`` - is returned, so the choice among them is stable too. - """ - newest_timestamp = max(datetime.fromisoformat(cp.timestamp) for cp in checkpoints) - candidates = [cp for cp in checkpoints if datetime.fromisoformat(cp.timestamp) == newest_timestamp] - superseded_ids = {cp.previous_checkpoint_id for cp in candidates} - leaves = [cp for cp in candidates if cp.checkpoint_id not in superseded_ids] - return max(leaves or candidates, key=lambda cp: cp.checkpoint_id) - - -def _store_scope(config: AgentConfig, platform_context: FoundryAgentRequestContext) -> FoundryRequestScope | None: - if not config.is_hosted: - return None - return FoundryRequestScope.from_context(config, platform_context) - - -def _store_name(root: str, scope: FoundryRequestScope | None, context_id: str | None = None) -> str: - if scope is None: - return f"{root}/{context_id}" if context_id is not None else root - name = f"{root}/v2/{scope.storage_key}" - if context_id is not None: - name += f"/{hashlib.sha256(context_id.encode('utf-8')).hexdigest()[:24]}" - return name - - -class StoreProvider(ABC, Generic[StoreT]): - """Provide store for a hosting environment.""" - - @abstractmethod - def get_store(self, *, config: AgentConfig, platform_context: FoundryAgentRequestContext) -> StoreT: - """Get store for a hosting environment. - - Args: - config: The resolved agent server configuration. - platform_context: The request-scoped platform context for the current request. - - Returns: - The store instance for the given hosting environment. - """ - - -class ContextScopedStoreProvider(ABC, Generic[StoreT]): - """Provide a context-scoped store for a hosting environment. - - Use this when state must be queried or managed as a collection belonging to - one context, rather than accessed only by an individual item ID. The context - can be a conversation ID or another identifier that groups related state. - """ - - @abstractmethod - def get_store( - self, - *, - config: AgentConfig, - context_id: str, - platform_context: FoundryAgentRequestContext, - ) -> StoreT: - """Get a context-scoped store for a hosting environment. - - Args: - config: The resolved agent server configuration. - context_id: A string that uniquely identifies the context for which the store is scoped. - platform_context: The request-scoped platform context for the current request. - - Returns: - The store instance for the given hosting environment and context ID. - """ - - -# region Checkpoint persistence - - -class FoundryCheckpointStore: - """Checkpoint store backed by the `FoundryStateStore`.""" - - DEFAULT_ROOT_SCOPE = "checkpoints" - - def __init__( - self, - context_id: str, - platform_context: FoundryAgentRequestContext, - *, - allowed_checkpoint_types: list[str] | None = None, - scope: FoundryRequestScope | None = None, - ) -> None: - """Initialize a Foundry-scoped checkpoint store for the given context ID. - - Args: - context_id: A string that uniquely identifies the context for which the checkpoint store is scoped. - This can be used to isolate checkpoints for different workflow runs. - platform_context: The request-scoped platform context for the current request. - allowed_checkpoint_types: Additional types (beyond the built-in safe set - and framework types) that are permitted during checkpoint - deserialization. Each entry should be a ``"module:qualname"`` - string (e.g., ``"my_app.models:MyState"``). - scope: Trusted request scope for hosted sandbox isolation. - """ - if not context_id: - raise ValueError("context_id must be provided to initialize a FoundryCheckpointStore.") - - self.context_id = context_id - self.platform_context = platform_context - self._allowed_types: frozenset[str] = frozenset(allowed_checkpoint_types or []) - self._scope = scope - - async def _get_store(self) -> FoundryStateStore: - return await FoundryStateStore.get_or_create( - _store_name(self.DEFAULT_ROOT_SCOPE, self._scope, self.context_id), - user_isolation=True, - ) - - async def save(self, checkpoint: WorkflowCheckpoint) -> CheckpointID: - """Save a workflow checkpoint to the store. - - Args: - checkpoint: The workflow checkpoint to save. - - The checkpoint will be serialized to a dictionary and then encoded before being stored. - - Returns: - The ID of the saved checkpoint. - """ - from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value - - encoded_checkpoint = encode_checkpoint_value(checkpoint.to_dict()) - - store = await self._get_store() - async with store: - await store.set_item(checkpoint.checkpoint_id, encoded_checkpoint, call_id=self.platform_context.call_id) - return checkpoint.checkpoint_id - - async def _load_encoded(self, checkpoint_id: CheckpointID) -> Any: - store = await self._get_store() - async with store: - item = await store.get_item(checkpoint_id, call_id=self.platform_context.call_id) - if item is None: - raise WorkflowCheckpointException(f"No checkpoint found with ID {checkpoint_id}") - return item.value - - async def load(self, checkpoint_id: CheckpointID) -> WorkflowCheckpoint: - """Load a workflow checkpoint from the store. - - Args: - checkpoint_id: The ID of the checkpoint to load. - - Returns: - The loaded workflow checkpoint. - - Raises: - WorkflowCheckpointException: If no checkpoint is found with the given ID. - """ - from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value - - encoded = await self._load_encoded(checkpoint_id) - return WorkflowCheckpoint.from_dict(decode_checkpoint_value(encoded, allowed_types=self._allowed_types)) - - async def load_with_hash(self, checkpoint_id: CheckpointID) -> tuple[WorkflowCheckpoint, str]: - """Load a checkpoint and hash its exact persisted encoding. - - Pickle is not a canonical serialization across Python versions or repeated - encodes. Hashing the acknowledged storage value preserves exact tamper - detection without rejecting an unchanged checkpoint after deserialization. - """ - from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value - - encoded = await self._load_encoded(checkpoint_id) - checkpoint = WorkflowCheckpoint.from_dict(decode_checkpoint_value(encoded, allowed_types=self._allowed_types)) - return checkpoint, _encoded_checkpoint_hash(encoded) - - async def list_checkpoints(self, *, workflow_name: str) -> list[WorkflowCheckpoint]: - """List all workflow checkpoints for a given workflow name.""" - from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value - - store = await self._get_store() - checkpoints: list[WorkflowCheckpoint] = [] - after: str | None = None - async with store: - while True: - page = await store.list_keys(after=after, call_id=self.platform_context.call_id) - for item_key in page.keys: - item = await store.get_item(item_key.key, call_id=self.platform_context.call_id) - if item is None: - continue - checkpoint = WorkflowCheckpoint.from_dict( - decode_checkpoint_value(item.value, allowed_types=self._allowed_types) - ) - if checkpoint.workflow_name == workflow_name: - checkpoints.append(checkpoint) - if not page.has_more or page.last_id is None: - break - after = page.last_id - return checkpoints - - async def delete(self, checkpoint_id: CheckpointID) -> bool: - store = await self._get_store() - async with store: - deleted_item = await store.delete_item(checkpoint_id, call_id=self.platform_context.call_id) - return deleted_item.id is not None - - async def get_latest(self, *, workflow_name: str) -> WorkflowCheckpoint | None: - checkpoints = await self.list_checkpoints(workflow_name=workflow_name) - if not checkpoints: - return None - return _select_latest_checkpoint(checkpoints) - - async def list_checkpoint_ids(self, *, workflow_name: str) -> list[CheckpointID]: - checkpoints = await self.list_checkpoints(workflow_name=workflow_name) - return [checkpoint.checkpoint_id for checkpoint in checkpoints] - - -class CheckpointStoreProvider(ContextScopedStoreProvider[CheckpointStorage]): - """Provide workflow checkpoint store scoped to a context. - - A workflow context can contain multiple checkpoints. Scoping establishes the - collection boundary used to list checkpoints, restore the latest checkpoint, - and clean up older checkpoints without affecting another workflow context. - - This defaults to using the `FoundryCheckpointStore` in all environments. - """ - - def __init__(self, *, allowed_checkpoint_types: list[str] | None = None) -> None: - """Initialize the provider. - - Args: - allowed_checkpoint_types: Additional types (beyond the built-in safe set - and framework types) that are permitted during checkpoint - deserialization, forwarded to every store this provider creates. - Each entry should be a ``"module:qualname"`` string - (e.g., ``"my_app.models:MyState"``). - """ - self._allowed_checkpoint_types = allowed_checkpoint_types - - def validate_checkpoint_value(self, value: object) -> None: - """Verify a value can round-trip through this provider's restricted decoder. - - Native hosts use this before claiming a stored typed workflow turn so an - omitted application allowlist fails before executors or tools run. - """ - from agent_framework._workflows._checkpoint_encoding import ( - decode_checkpoint_value, - encode_checkpoint_value, - ) - - decode_checkpoint_value( - encode_checkpoint_value(value), - allowed_types=frozenset(self._allowed_checkpoint_types or ()), - ) - - def get_store( - self, - *, - config: AgentConfig, - context_id: str, - platform_context: FoundryAgentRequestContext, - ) -> CheckpointStorage: - """Get checkpoint store for the requested hosting environment.""" - if not context_id: - raise ValueError("context_id must be provided to get a checkpoint store.") - - return self.get_store_for_scope( - context_id=context_id, - platform_context=platform_context, - scope=_store_scope(config, platform_context), - ) - - def get_store_for_scope( - self, - *, - scope: FoundryRequestScope | None, - context_id: str, - platform_context: FoundryAgentRequestContext, - ) -> CheckpointStorage: - """Create a checkpoint store using a host's already validated scope. - - Native hosts use this after protocol-specific identity resolution. - ``get_store`` retains its strict configuration-based scope validation. - - Args: - scope: Trusted user and sandbox scope resolved by the protocol host. - context_id: Native workflow lineage's checkpoint collection. - platform_context: The current request's storage authorization context. - """ - return FoundryCheckpointStore( - context_id, - platform_context, - allowed_checkpoint_types=self._allowed_checkpoint_types, - scope=scope, - ) - - -# endregion Checkpoint persistence - -# region Function approval persistence - - -class FunctionApprovalStore(Protocol): - """Store for saving function approval requests.""" - - async def save_approval_request(self, approval_request_id: str, request: Content) -> None: - """Save a function approval request under the given ID.""" - ... - - async def load_approval_request(self, approval_request_id: str) -> Content: - """Load a function approval request by its ID.""" - ... - - -class FoundryFunctionApprovalStore: - """Function approval store backed by the `FoundryStateStore`.""" - - DEFAULT_ROOT_SCOPE = "function_approvals" - - def __init__( - self, - platform_context: FoundryAgentRequestContext, - *, - scope: FoundryRequestScope | None = None, - ) -> None: - self.platform_context = platform_context - self._scope = scope - - async def _get_store(self) -> FoundryStateStore: - return await FoundryStateStore.get_or_create( - _store_name(self.DEFAULT_ROOT_SCOPE, self._scope), - user_isolation=True, - ) - - async def save_approval_request(self, approval_request_id: str, request: Content) -> None: - store = await self._get_store() - async with store: - try: - await store.create_item(approval_request_id, request.to_dict(), call_id=self.platform_context.call_id) - except FoundryStorageConflictError as ex: - raise ValueError(f"Approval request with ID '{approval_request_id}' already exists.") from ex - - async def load_approval_request(self, approval_request_id: str) -> Content: - store = await self._get_store() - async with store: - item = await store.get_item(approval_request_id, call_id=self.platform_context.call_id) - if item is None: - raise KeyError(f"Approval request with ID '{approval_request_id}' does not exist.") - return Content.from_dict(item.value) - - -class FunctionApprovalStoreProvider(StoreProvider[FunctionApprovalStore]): - """Provide function approval store for the active hosting environment. - - This defaults to using the `FoundryFunctionApprovalStore` in all environments. - """ - - def get_store( - self, - *, - config: AgentConfig, - platform_context: FoundryAgentRequestContext, - ) -> FunctionApprovalStore: - """Get function approval store for the requested hosting environment.""" - return FoundryFunctionApprovalStore( - platform_context, - scope=_store_scope(config, platform_context), - ) - - -# endregion Function approval persistence - -# region Agent session persistence - - -class FoundryAgentSessionStore(SessionStore): - """Agent session store backed by the `FoundryStateStore`.""" - - DEFAULT_ROOT_SCOPE = "agent_sessions" - - def __init__( - self, - platform_context: FoundryAgentRequestContext, - *, - store_name: str | None = None, - scope: FoundryRequestScope | None = None, - ) -> None: - """Initialize session storage. - - Args: - platform_context: The request-scoped platform context. - store_name: Logical state-store name. Defaults to `agent_sessions`. - scope: Trusted Foundry request scope for sandbox-specific storage. - """ - if store_name is not None and (not isinstance(store_name, str) or not store_name.strip()): - raise ValueError("store_name must be a non-empty string") - self.platform_context = platform_context - self._store_name = self.DEFAULT_ROOT_SCOPE if store_name is None else store_name - self._scope = scope - self._etags: dict[str, str | None] = {} - - async def _get_store(self) -> FoundryStateStore: - return await FoundryStateStore.get_or_create( - _store_name(self._store_name, self._scope), - user_isolation=True, - ) - - async def get(self, session_id: str) -> AgentSession | None: - store = await self._get_store() - async with store: - item = await store.get_item(session_id, call_id=self.platform_context.call_id) - if item is None: - self._etags[session_id] = None - return None - if not item.etag: - raise RuntimeError("Foundry agent session storage returned a loaded session without an ETag.") - self._etags[session_id] = item.etag - return AgentSession.from_dict(item.value) - - async def set(self, session_id: str, session: AgentSession) -> None: - store = await self._get_store() - async with store: - try: - etag = self._etags.get(session_id) - if etag is not None: - result = await store.set_item( - session_id, session.to_dict(), if_match=etag, call_id=self.platform_context.call_id - ) - elif self._scope is not None or session_id in self._etags: - result = await store.create_item( - session_id, session.to_dict(), call_id=self.platform_context.call_id - ) - else: - result = await store.set_item(session_id, session.to_dict(), call_id=self.platform_context.call_id) - except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: - raise RuntimeError("Another request advanced this agent session; reload before writing.") from exc - if not result.etag: - raise RuntimeError("Foundry agent session storage did not return an ETag after saving.") - self._etags[session_id] = result.etag - - async def delete(self, session_id: str) -> None: - store = await self._get_store() - async with store: - await store.delete_item(session_id, call_id=self.platform_context.call_id) - self._etags.pop(session_id, None) - - -class AgentSessionStoreProvider(StoreProvider[SessionStore]): - """Provide agent session store for the active hosting environment. - - This defaults to using the `FoundryAgentSessionStore` in all environments. - """ - - def __init__(self, *, store_name: str | None = None) -> None: - """Initialize the provider. - - Args: - store_name: Logical state-store name. Defaults to `agent_sessions`. - """ - if store_name is not None and (not isinstance(store_name, str) or not store_name.strip()): - raise ValueError("store_name must be a non-empty string") - self._store_name = store_name - - def _get_scoped_store( - self, platform_context: FoundryAgentRequestContext, scope: FoundryRequestScope | None - ) -> SessionStore: - return FoundryAgentSessionStore( - platform_context, - store_name=self._store_name, - scope=scope, - ) - - def get_store(self, *, config: AgentConfig, platform_context: FoundryAgentRequestContext) -> SessionStore: - """Get agent session store for the requested hosting environment.""" - return self._get_scoped_store(platform_context, _store_scope(config, platform_context)) - - -# endregion Agent session persistence diff --git a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py b/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py deleted file mode 100644 index ae822942767..00000000000 --- a/python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py +++ /dev/null @@ -1,926 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Exact native workflow pairs and linear reply authority within a trusted sandbox.""" - -from __future__ import annotations - -import hashlib -import json -import logging -import secrets -from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping -from dataclasses import asdict, dataclass, replace -from typing import Any, Literal, cast - -from agent_framework import ( - AgentResponse, - AgentResponseUpdate, - ChatResponse, - ChatResponseUpdate, - CheckpointStorage, - Content, - Workflow, - WorkflowCheckpoint, - WorkflowEvent, - WorkflowInvocationKwargs, - WorkflowRunState, -) -from agent_framework._workflows._agent_executor import ( - _validate_computer_tool_result, # pyright: ignore[reportPrivateUsage] -) -from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value -from agent_framework._workflows._const import ( - RESOLVED_WORKFLOW_RUN_KWARGS_KEY, - ROUTED_WORKFLOW_RUN_KWARGS_KEY, - WORKFLOW_RUN_KWARGS_KEY, -) -from agent_framework._workflows._typing_utils import is_instance_of -from agent_framework._workflows._workflow import ( - _coerce_request_info_response, # pyright: ignore[reportPrivateUsage] -) -from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext -from azure.ai.agentserver.core.storage import ( - FoundryStateStore, - FoundryStorageConflictError, - FoundryStoragePreconditionError, -) - -from ._scope import FoundryRequestScope -from ._shared import WorkflowTurn, prepare_workflow_kwargs, validate_workflow_provider_state -from ._state_store import CheckpointStoreProvider, ContextScopedStoreProvider - -_CONFLICT = "Another request advanced this workflow. Reload its current response or start a fresh lineage." -_BLOCKED = "This workflow turn was interrupted or failed; start a fresh workflow lineage to avoid replaying effects." -logger = logging.getLogger(__name__) - - -class WorkflowConflictError(RuntimeError): - """A scoped workflow head, graph, or reply authority no longer permits this turn.""" - - -class WorkflowBlockedError(WorkflowConflictError): - """A failed or cancelled turn blocks its lineage to prevent uncertain effect replay.""" - - -def _key(kind: str, identifier: str) -> str: - if not isinstance(identifier, str) or not identifier: - raise ValueError("A non-empty workflow state identifier is required.") - return f"{kind}-{hashlib.sha256(identifier.encode('utf-8')).hexdigest()}" - - -def _json_object(value: Mapping[str, Any]) -> dict[str, Any]: - """Validate snapshots without arbitrary encoders or success-shaped string fallbacks.""" - if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value): - raise TypeError("A workflow output snapshot must be a JSON object.") - return cast(dict[str, Any], json.loads(json.dumps(dict(value), allow_nan=False))) - - -def _checkpoint_hash(checkpoint: WorkflowCheckpoint) -> str: - encoded = encode_checkpoint_value(checkpoint.to_dict()) - return hashlib.sha256(json.dumps(encoded, sort_keys=True, allow_nan=False).encode("utf-8")).hexdigest() - - -@dataclass(frozen=True) -class WorkflowBinding: - """The exact checkpoint for one outer response, not a sandbox or provider session.""" - - response_id: str - checkpoint_id: str | None - lineage_id: str - workflow_name: str - graph_hash: str - scope_key: str - checkpoint_hash: str | None = None - conversation_id: str | None = None - previous_response_id: str | None = None - - @classmethod - def from_value(cls, value: Any, scope: FoundryRequestScope) -> WorkflowBinding: - if not isinstance(value, dict): - raise ValueError("Invalid persisted workflow binding.") - value = cast(dict[str, Any], value) - if set(value) != set(cls.__dataclass_fields__): - raise ValueError("Invalid persisted workflow binding.") - for name in ("response_id", "lineage_id", "workflow_name", "graph_hash", "scope_key"): - if not isinstance(value[name], str) or not value[name]: - raise ValueError("Invalid persisted workflow binding.") - for name in ("checkpoint_id", "checkpoint_hash", "conversation_id", "previous_response_id"): - if value[name] is not None and (not isinstance(value[name], str) or not value[name]): - raise ValueError("Invalid persisted workflow binding.") - if (value["checkpoint_id"] is None) != (value["checkpoint_hash"] is None): - raise ValueError("Invalid persisted workflow checkpoint identity.") - binding = cls(**value) - if binding.scope_key != scope.storage_key: - raise PermissionError("The workflow state is not available in this trusted scope.") - return binding - - -@dataclass(frozen=True) -class WorkflowRecord: - """A per-response checkpoint/output pair retained independently of a later head.""" - - binding: WorkflowBinding - owner: str - status: Literal["active", "completed", "blocked"] - snapshot: dict[str, Any] | None = None - approvals: dict[str, str] | None = None - - @classmethod - def from_value(cls, value: Any, scope: FoundryRequestScope) -> WorkflowRecord: - if not isinstance(value, dict): - raise ValueError("Invalid persisted workflow response pair.") - value = cast(dict[str, Any], value) - if set(value) != set(cls.__dataclass_fields__): - raise ValueError("Invalid persisted workflow response pair.") - binding = WorkflowBinding.from_value(value["binding"], scope) - if ( - not isinstance(value["owner"], str) - or not value["owner"] - or value["status"] - not in ( - "active", - "completed", - "blocked", - ) - ): - raise ValueError("Invalid persisted workflow response pair.") - snapshot = value["snapshot"] - if snapshot is not None: - snapshot = _json_object(snapshot) - raw_approvals = value["approvals"] - approvals: dict[str, str] | None = None - if raw_approvals is not None: - if not isinstance(raw_approvals, dict): - raise ValueError("Invalid persisted workflow reply authority.") - approvals = {} - for wire_id, request_id in cast(dict[object, object], raw_approvals).items(): - if not isinstance(wire_id, str) or not wire_id or not isinstance(request_id, str) or not request_id: - raise ValueError("Invalid persisted workflow reply authority.") - approvals[wire_id] = request_id - if value["status"] == "completed" and (binding.checkpoint_id is None or snapshot is None): - raise ValueError("A completed workflow response requires an exact checkpoint/output pair.") - return cls(binding, value["owner"], value["status"], snapshot, approvals) - - -@dataclass(frozen=True) -class WorkflowHead: - """One CAS authority for a lineage, including its optional named conversation.""" - - lineage_id: str - conversation_id: str | None - binding: WorkflowBinding | None = None - response_id: str | None = None - owner: str | None = None - blocked: bool = False - - @classmethod - def from_value(cls, value: Any, scope: FoundryRequestScope) -> WorkflowHead: - if not isinstance(value, dict): - raise ValueError("Invalid persisted workflow head.") - value = cast(dict[str, Any], value) - if set(value) != set(cls.__dataclass_fields__): - raise ValueError("Invalid persisted workflow head.") - if not isinstance(value["lineage_id"], str) or not value["lineage_id"] or type(value["blocked"]) is not bool: - raise ValueError("Invalid persisted workflow head.") - for name in ("conversation_id", "response_id", "owner"): - if value[name] is not None and (not isinstance(value[name], str) or not value[name]): - raise ValueError("Invalid persisted workflow head.") - if (value["owner"] is None) != (value["response_id"] is None): - raise ValueError("Invalid persisted workflow claim.") - binding = WorkflowBinding.from_value(value["binding"], scope) if value["binding"] is not None else None - if binding is not None and ( - binding.lineage_id != value["lineage_id"] or binding.conversation_id != value["conversation_id"] - ): - raise ValueError("Invalid persisted workflow head binding.") - return cls( - value["lineage_id"], - value["conversation_id"], - binding, - value["response_id"], - value["owner"], - value["blocked"], - ) - - -class FoundryWorkflowBindingStore: - """Persist scoped per-response pairs and fenced linear workflow claims.""" - - def __init__(self, scope: FoundryRequestScope) -> None: - self.scope = scope - - async def _get_store(self) -> FoundryStateStore: - return await FoundryStateStore.get_or_create( - f"workflow_bindings/v2/{self.scope.storage_key}", user_isolation=True - ) - - async def get_response(self, response_id: str) -> tuple[WorkflowRecord | None, str | None]: - store = await self._get_store() - async with store: - item = await store.get_item(_key("response", response_id), call_id=self.scope.call_id) - if item is None: - return None, None - record = WorkflowRecord.from_value(item.value, self.scope) - if record.binding.response_id != response_id or not item.etag: - raise ValueError("Invalid persisted workflow response identity or ETag.") - return record, item.etag - - async def get_head(self, lineage_id: str, conversation_id: str | None) -> tuple[WorkflowHead | None, str | None]: - store = await self._get_store() - key = _key("conversation", conversation_id) if conversation_id is not None else _key("lineage", lineage_id) - async with store: - item = await store.get_item(key, call_id=self.scope.call_id) - if item is None: - return None, None - head = WorkflowHead.from_value(item.value, self.scope) - if ( - head.conversation_id != conversation_id - or (conversation_id is None and head.lineage_id != lineage_id) - or not item.etag - ): - raise ValueError("Invalid persisted workflow head identity or ETag.") - return head, item.etag - - async def save_response(self, record: WorkflowRecord, *, expected_etag: str | None) -> str: - if record.binding.scope_key != self.scope.storage_key: - raise PermissionError("Cannot write workflow state outside its trusted scope.") - return await self._write(_key("response", record.binding.response_id), asdict(record), expected_etag) - - async def save_head(self, head: WorkflowHead, *, expected_etag: str | None) -> str: - if head.binding is not None and head.binding.scope_key != self.scope.storage_key: - raise PermissionError("Cannot write workflow state outside its trusted scope.") - key = ( - _key("conversation", head.conversation_id) - if head.conversation_id is not None - else _key("lineage", head.lineage_id) - ) - return await self._write(key, asdict(head), expected_etag) - - async def delete_response(self, response_id: str, *, expected_etag: str) -> bool: - """Conditionally delete a superseded response record.""" - store = await self._get_store() - async with store: - try: - deleted = await store.delete_item( - _key("response", response_id), - if_match=expected_etag, - call_id=self.scope.call_id, - ) - except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: - raise WorkflowConflictError(_CONFLICT) from exc - return deleted.id is not None - - async def _write(self, key: str, value: dict[str, Any], expected_etag: str | None) -> str: - store = await self._get_store() - async with store: - try: - if expected_etag is None: - result = await store.create_item(key, value, call_id=self.scope.call_id) - else: - result = await store.set_item(key, value, if_match=expected_etag, call_id=self.scope.call_id) - except (FoundryStorageConflictError, FoundryStoragePreconditionError) as exc: - raise WorkflowConflictError(_CONFLICT) from exc - if not result.etag: - raise RuntimeError("Workflow storage did not acknowledge a conditional write with an ETag.") - return result.etag - - -class _CheckpointWrites: - """Track acknowledged core saves, never selecting an unrelated latest checkpoint.""" - - def __init__(self, storage: CheckpointStorage, run: HostedWorkflowRun) -> None: - self.storage = storage - self.run = run - self.last_checkpoint: WorkflowCheckpoint | None = None - self.acknowledged_ids: set[str] = set() - - async def save(self, checkpoint: WorkflowCheckpoint) -> str: - await self.run.assert_claim() - validate_workflow_provider_state(self.run.workflow, checkpoint) - identifier = await self.storage.save(checkpoint) - if identifier != checkpoint.checkpoint_id: - raise RuntimeError("Workflow checkpoint storage acknowledged a different checkpoint.") - self.last_checkpoint = checkpoint - self.acknowledged_ids.add(identifier) - return identifier - - async def load(self, checkpoint_id: str) -> WorkflowCheckpoint: - checkpoint = await self.storage.load(checkpoint_id) - # Core checkpoint restoration follows run-kwargs setup. Retain fresh request - # kwargs rather than restoring the previous request's private call context. - fresh = self.run.workflow._runner.state.export_state() # pyright: ignore[reportPrivateUsage] - state = dict(checkpoint.state) - for key in (WORKFLOW_RUN_KWARGS_KEY, RESOLVED_WORKFLOW_RUN_KWARGS_KEY, ROUTED_WORKFLOW_RUN_KWARGS_KEY): - state[key] = fresh.get(key, {}) - return replace(checkpoint, state=state) - - async def load_persisted(self, checkpoint_id: str) -> tuple[WorkflowCheckpoint, str]: - """Load a checkpoint with a process-stable integrity hash when supported.""" - load_with_hash = getattr(cast(Any, self.storage), "load_with_hash", None) - if callable(load_with_hash): - loader = cast( - Callable[[str], Awaitable[tuple[WorkflowCheckpoint, str]]], - load_with_hash, - ) - checkpoint, checkpoint_hash = await loader(checkpoint_id) - if not isinstance(checkpoint, WorkflowCheckpoint) or not isinstance(checkpoint_hash, str): - raise TypeError("Checkpoint storage returned an invalid checkpoint integrity pair.") - return checkpoint, checkpoint_hash - checkpoint = await self.storage.load(checkpoint_id) - return checkpoint, _checkpoint_hash(checkpoint) - - async def list_checkpoints(self, *, workflow_name: str) -> list[WorkflowCheckpoint]: - return await self.storage.list_checkpoints(workflow_name=workflow_name) - - async def list_checkpoint_ids(self, *, workflow_name: str) -> list[str]: - return await self.storage.list_checkpoint_ids(workflow_name=workflow_name) - - async def get_latest(self, *, workflow_name: str) -> WorkflowCheckpoint | None: - return await self.storage.get_latest(workflow_name=workflow_name) - - async def delete(self, checkpoint_id: str) -> bool: - return await self.storage.delete(checkpoint_id) - - -class HostedWorkflowRun: - """A native turn with explicit validation, claim, pairing, commit, and abort boundaries. - - Protocol hosts own output encoding and lifecycle signals. Closing ``events`` - never commits a turn. A failed or cancelled claim is blocked rather than - releasing potentially consumed approvals or replaying external side effects. - """ - - def __init__( - self, - workflow: Workflow, - scope: FoundryRequestScope, - *, - stored: bool, - recovery: bool, - fresh_factory: bool, - reclaim_superseded: bool, - ) -> None: - self.workflow = workflow - self.scope = scope - self.stored = stored - self.recovery = recovery - self.fresh_factory = fresh_factory - self.reclaim_superseded = reclaim_superseded - self.store = FoundryWorkflowBindingStore(scope) - self.binding: WorkflowBinding - self._head: WorkflowHead | None = None - self._head_etag: str | None = None - self._record: WorkflowRecord | None = None - self._record_etag: str | None = None - self._storage: _CheckpointWrites | None = None - self._checkpoint: WorkflowCheckpoint | None = None - self._reply_approvals: dict[str, str] = {} - self._turn: WorkflowTurn[Any] | None = None - self._client_kwargs = WorkflowInvocationKwargs() - self._function_kwargs = WorkflowInvocationKwargs() - self._claimed = False - self._finalized = False - self.already_completed = False - - @classmethod - async def prepare( - cls, - workflow: Workflow, - *, - scope: FoundryRequestScope, - response_id: str, - config: AgentConfig, - platform_context: FoundryAgentRequestContext, - checkpoint_store_provider: ContextScopedStoreProvider[CheckpointStorage], - previous_response_id: str | None = None, - conversation_id: str | None = None, - lineage_id: str | None = None, - stored: bool = True, - recovery: bool = False, - replay_completed: bool = False, - fresh_factory: bool = False, - reclaim_superseded: bool = False, - ) -> HostedWorkflowRun: - """Read exact continuation state without claiming, consuming replies, or executing.""" - if not workflow.name or not workflow.graph_signature_hash: - raise ValueError("Native workflows require a stable, non-empty workflow name and graph identity.") - if previous_response_id is not None and conversation_id is not None: - raise ValueError("A workflow turn cannot combine previous_response_id and conversation.") - if not stored and (recovery or previous_response_id is not None or conversation_id is not None): - raise ValueError("store=false workflow requests cannot continue stored state; start a one-shot turn.") - run = cls( - workflow, - scope, - stored=stored, - recovery=recovery, - fresh_factory=fresh_factory, - reclaim_superseded=reclaim_superseded, - ) - run.binding = WorkflowBinding( - response_id=response_id, - checkpoint_id=None, - lineage_id=lineage_id or response_id, - workflow_name=workflow.name, - graph_hash=workflow.graph_signature_hash, - scope_key=scope.storage_key, - conversation_id=conversation_id, - previous_response_id=previous_response_id, - ) - if not stored: - return run - - own, own_etag = await run.store.get_response(response_id) - if not recovery and replay_completed and own is not None and own.status == "completed": - recovery = True - run.recovery = True - if recovery and own is not None: - run._record, run._record_etag = own, own_etag - run.binding = own.binding - run._reply_approvals = own.approvals or {} - elif own is not None: - raise WorkflowConflictError( - "This workflow response already exists; retrieve it instead of executing it again." - ) - - previous: WorkflowBinding | None = None - if previous_response_id is not None and (not recovery or own is None): - record, _ = await run.store.get_response(previous_response_id) - if record is None or record.status != "completed": - raise ValueError("The previous response has no completed workflow checkpoint in this trusted scope.") - previous = record.binding - if not recovery: - run._reply_approvals = record.approvals or {} - if previous.conversation_id is not None: - raise ValueError("A named workflow conversation cannot be forked through previous_response_id.") - run.binding = replace(run.binding, lineage_id=previous.lineage_id) - - head, etag = await run.store.get_head(run.binding.lineage_id, run.binding.conversation_id) - run._head, run._head_etag = head, etag - if recovery: - if head is None: - raise RuntimeError("The workflow recovery authority is unavailable; start a fresh lineage.") - if own is None: - if head.response_id != response_id or head.owner is None or head.blocked: - raise WorkflowConflictError(_CONFLICT) - run.binding = replace(run.binding, lineage_id=head.lineage_id) - blocked_record = WorkflowRecord(run.binding, head.owner, "blocked") - await run.store.save_response(blocked_record, expected_etag=None) - await run.store.save_head(replace(head, blocked=True), expected_etag=etag) - raise WorkflowBlockedError(_BLOCKED) - if own.status == "blocked": - if head.response_id == response_id and head.owner == own.owner and not head.blocked: - await run.store.save_head(replace(head, blocked=True), expected_etag=etag) - raise WorkflowBlockedError(_BLOCKED) - if own.binding.checkpoint_id is None or own.snapshot is None: - if head.response_id != response_id or head.owner != own.owner or head.blocked: - raise WorkflowConflictError(_CONFLICT) - blocked_record = replace(own, status="blocked") - await run.store.save_response(blocked_record, expected_etag=own_etag) - await run.store.save_head(replace(head, blocked=True), expected_etag=etag) - raise WorkflowBlockedError(_BLOCKED) - if own.status == "completed": - current = head.binding - visited: set[str] = set() - while current is not None and current != own.binding: - if current.response_id in visited or current.previous_response_id is None: - current = None - break - visited.add(current.response_id) - parent, _ = await run.store.get_response(current.previous_response_id) - current = parent.binding if parent is not None and parent.status == "completed" else None - if current is not None: - run.already_completed = True - elif head.response_id != response_id or head.blocked: - raise WorkflowConflictError(_CONFLICT) - else: - run._finalized = True - elif head.response_id != response_id or head.owner != own.owner or head.blocked: - raise WorkflowConflictError(_CONFLICT) - previous = run.binding - elif head is not None: - if head.blocked: - raise WorkflowBlockedError(_BLOCKED) - if head.response_id is not None: - active_record, _ = await run.store.get_response(head.response_id) - if active_record is None and head.owner is not None: - interrupted_binding = WorkflowBinding( - response_id=head.response_id, - checkpoint_id=None, - lineage_id=head.lineage_id, - workflow_name=workflow.name, - graph_hash=workflow.graph_signature_hash, - scope_key=scope.storage_key, - conversation_id=head.conversation_id, - previous_response_id=head.binding.response_id if head.binding is not None else None, - ) - await run.store.save_response( - WorkflowRecord(interrupted_binding, head.owner, "blocked"), - expected_etag=None, - ) - await run.store.save_head(replace(head, blocked=True), expected_etag=etag) - raise WorkflowBlockedError(_BLOCKED) - raise WorkflowConflictError( - "This workflow has an in-flight turn. Wait for it or start a fresh lineage." - ) - if previous is not None and head.binding != previous: - raise WorkflowConflictError("This workflow continuation is stale or forked; use its current response.") - previous = head.binding - if previous is not None: - record, _ = await run.store.get_response(previous.response_id) - if record is None or record.status != "completed" or record.binding != previous: - raise ValueError("The workflow head has no exact completed response binding.") - run._reply_approvals = record.approvals or {} - run.binding = replace( - run.binding, - lineage_id=head.lineage_id, - previous_response_id=previous.response_id if previous is not None else None, - ) - elif previous is not None: - raise ValueError("The workflow lineage authority is unavailable in this trusted scope.") - - context_id = _key("native", f"{scope.storage_key}:{run.binding.lineage_id}") - storage = ( - checkpoint_store_provider.get_store_for_scope( - scope=scope, context_id=context_id, platform_context=platform_context - ) - if isinstance(checkpoint_store_provider, CheckpointStoreProvider) - else checkpoint_store_provider.get_store( - config=config, context_id=context_id, platform_context=platform_context - ) - ) - run._storage = _CheckpointWrites(storage, run) - if previous is not None: - if previous.workflow_name != workflow.name or previous.graph_hash != workflow.graph_signature_hash: - raise WorkflowConflictError( - "The stored workflow graph is incompatible. Rebuild its original graph or start a fresh lineage." - ) - if previous.checkpoint_id is None: - raise ValueError("The workflow response has no acknowledged checkpoint.") - checkpoint, checkpoint_hash = await run._storage.load_persisted(previous.checkpoint_id) - if ( - checkpoint.checkpoint_id != previous.checkpoint_id - or checkpoint.workflow_name != workflow.name - or checkpoint.graph_signature_hash != workflow.graph_signature_hash - or checkpoint_hash != previous.checkpoint_hash - ): - raise ValueError("The exact workflow checkpoint does not match its response binding.") - run._checkpoint = checkpoint - validate_workflow_provider_state(workflow, checkpoint) - return run - - @property - def snapshot(self) -> dict[str, Any] | None: - """The exact same-response recovery snapshot, independent of the current lineage head.""" - return self._record.snapshot if self._record is not None else None - - @property - def approvals(self) -> Mapping[str, str]: - """Caller-facing approval aliases bound to the loaded response's exact checkpoint.""" - return self._reply_approvals - - @property - def has_completed_output(self) -> bool: - """Whether recovery can deliver already finalized output without rerunning executors.""" - return self._record is not None and self._record.status == "completed" - - @property - def pending_requests(self) -> Mapping[str, WorkflowEvent[Any]]: - """Pending request authority from the exact acknowledged checkpoint.""" - checkpoint = self.current_checkpoint - return checkpoint.pending_request_info_events if checkpoint is not None else {} - - @property - def current_checkpoint(self) -> WorkflowCheckpoint | None: - """The last acknowledged checkpoint from this run, or its exact restoration checkpoint.""" - if self._storage is not None and self._storage.last_checkpoint is not None: - return self._storage.last_checkpoint - return self._checkpoint - - @property - def checkpoint_id(self) -> str | None: - """The exact acknowledged checkpoint ID, never a latest-checkpoint query.""" - checkpoint = self.current_checkpoint - return checkpoint.checkpoint_id if checkpoint is not None else None - - def recovery_turn(self) -> WorkflowTurn[Any]: - """Restore application kwargs without re-parsing already consumed approval input. - - The checkpoint, rather than a new start input or replayed reply, is the - recovery action. Host-injected identity and storage controls are replaced - by ``prepare_workflow_kwargs`` for the current trusted request. - """ - if not self.recovery or self._checkpoint is None: - raise RuntimeError("A recovery turn requires an exact restored checkpoint.") - resolved = self._checkpoint.state.get(RESOLVED_WORKFLOW_RUN_KWARGS_KEY, {}) - if not isinstance(resolved, Mapping): - raise ValueError("Invalid persisted workflow invocation kwargs.") - resolved = cast(Mapping[str, Any], resolved) - - def invocation_kwargs(name: str) -> WorkflowInvocationKwargs: - values = resolved.get(name, {}) - if not isinstance(values, Mapping): - raise ValueError("Invalid persisted workflow invocation kwargs.") - values = cast(Mapping[str, Any], values) - global_kwargs = dict(values.get("global_kwargs", {})) - executor_kwargs = {key: dict(value) for key, value in values.get("executor_kwargs", {}).items()} - if name == "client_kwargs": - for kwargs in (global_kwargs, *executor_kwargs.values()): - kwargs.pop("additional_function_arguments", None) - if "options" in kwargs: - kwargs["options"] = dict(kwargs["options"]) - kwargs["options"].pop("store", None) - return WorkflowInvocationKwargs(global_kwargs, executor_kwargs) - - return WorkflowTurn( - input=self._checkpoint, - client_kwargs=invocation_kwargs("client_kwargs"), - function_invocation_kwargs=invocation_kwargs("function_invocation_kwargs"), - ) - - def validate_turn(self, turn: WorkflowTurn[Any]) -> WorkflowTurn[Any]: - """Validate all input/replies and existing workflow kwargs before claiming authority.""" - if not isinstance(turn, WorkflowTurn): - raise TypeError("The workflow parser must return WorkflowTurn.") - self._client_kwargs, self._function_kwargs = prepare_workflow_kwargs( - self.workflow, - turn, - self.scope, - stored=self.stored, - fresh_factory=self.fresh_factory, - ) - if self.recovery: - self._turn = turn - return turn - pending = self.pending_requests - if turn.responses is not None: - if not self.stored or self._checkpoint is None: - raise ValueError("Workflow replies require a pending stored checkpoint.") - if set(turn.responses) != set(pending) or not pending: - raise ValueError("Workflow replies must answer exactly the complete pending request batch.") - replies: dict[str, Any] = {} - reply_ids: set[tuple[str, str]] = set() - for request_id, reply in turn.responses.items(): - event = pending[request_id] - try: - reply = _coerce_request_info_response(reply, event.response_type, request_id) - except (TypeError, ValueError) as exc: - raise ValueError("A workflow reply does not match its pending request type.") from exc - if isinstance(event.data, Content): - request = event.data - if isinstance(reply, Content): - identifier = reply.id if reply.type == "function_approval_response" else reply.call_id - if identifier is not None: - key = (reply.type, identifier) - if key in reply_ids: - raise ValueError("Duplicate workflow reply authority is not allowed.") - reply_ids.add(key) - if request.type == "function_approval_request" and ( - not isinstance(reply, Content) - or reply.type != "function_approval_response" - or reply.id != request.id - or type(reply.approved) is not bool - or reply.function_call is None - or request.function_call is None - or reply.function_call.to_dict() != request.function_call.to_dict() - ): - raise ValueError("The approval decision does not match its exact pending function call.") - if request.type == "function_call" and ( - not isinstance(reply, Content) - or reply.type != "function_result" - or reply.call_id != request.call_id - ): - raise ValueError("The function result does not match its pending call.") - if request.type == "computer_tool_call": - if not isinstance(reply, Content): - raise ValueError("A computer reply must be typed Content.") - _validate_computer_tool_result(request, reply) - replies[request_id] = reply - turn = replace(turn, responses=replies) - else: - if pending: - raise ValueError("This workflow is awaiting replies; do not replace them with new input.") - if self._checkpoint is not None and any(self._checkpoint.messages.values()): - raise ValueError("The workflow is still in flight; new input cannot replace its checkpoint.") - if not any(is_instance_of(turn.input, input_type) for input_type in self.workflow.input_types): - raise ValueError("The workflow parser's input does not match the start executor's type.") - self._turn = turn - return turn - - async def claim(self) -> None: - """Fence the exact validated turn before any executor or response handler runs.""" - if self._turn is None: - raise RuntimeError("Validate the workflow turn before claiming it.") - if self._claimed or self.already_completed: - return - if not self.stored: - self._claimed = True - return - owner = secrets.token_hex(16) - head = replace( - self._head or WorkflowHead(self.binding.lineage_id, self.binding.conversation_id), - response_id=self.binding.response_id, - owner=owner, - ) - self._head_etag = await self.store.save_head(head, expected_etag=self._head_etag) - self._head = head - self._claimed = True - record = ( - replace(self._record, owner=owner) - if self.recovery and self._record is not None - else WorkflowRecord(self.binding, owner, "active") - ) - self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) - self._record = record - await self._reclaim_completed_ancestors() - - async def assert_claim(self) -> None: - if not self._claimed: - raise RuntimeError("The workflow turn has not been claimed.") - if not self.stored: - return - head, etag = await self.store.get_head(self.binding.lineage_id, self.binding.conversation_id) - if head != self._head or etag != self._head_etag or head is None or head.blocked: - raise WorkflowConflictError(_CONFLICT) - - async def events( - self, - turn: WorkflowTurn[Any], - *, - client_kwargs: WorkflowInvocationKwargs | Mapping[str, Any] | None = None, - function_invocation_kwargs: WorkflowInvocationKwargs | Mapping[str, Any] | None = None, - ) -> AsyncGenerator[WorkflowEvent[Any]]: - """Execute core events, with explicit caller-owned commit and cancellation boundaries.""" - if self.already_completed or self.has_completed_output: - return - await self.assert_claim() - if self._turn is None: - raise RuntimeError("The workflow turn has not been validated.") - turn = self._turn - if self._checkpoint is not None and not self.recovery: - await self.workflow._runner.restore_checkpoint(self._checkpoint) # pyright: ignore[reportPrivateUsage] - stream = self.workflow.run( - None if self.recovery else turn.input, - responses=None if self.recovery else turn.responses, - checkpoint_id=self._checkpoint.checkpoint_id if self.recovery and self._checkpoint is not None else None, - checkpoint_storage=self._storage, - stream=True, - client_kwargs=client_kwargs if client_kwargs is not None else self._client_kwargs, - function_invocation_kwargs=( - function_invocation_kwargs if function_invocation_kwargs is not None else self._function_kwargs - ), - ) - try: - async for event in stream: - data = event.data - if ( - isinstance(data, (AgentResponse, AgentResponseUpdate, ChatResponse, ChatResponseUpdate)) - and data.continuation_token is not None - ): - raise RuntimeError("Native workflows cannot checkpoint unfinished provider background output.") - if event.type == "superstep_completed": - validate_workflow_provider_state(self.workflow) - if event.type == "request_info" and not self.stored: - raise ValueError("Approval and user-input continuation requires store=true.") - yield event - result = await stream.get_final_response() - if result.get_final_state() not in (WorkflowRunState.IDLE, WorkflowRunState.IDLE_WITH_PENDING_REQUESTS): - raise RuntimeError("The workflow did not finalize successfully.") - validate_workflow_provider_state(self.workflow) - self._finalized = True - finally: - await stream.close() - - async def stage( - self, - snapshot: Mapping[str, Any], - *, - approvals: Mapping[str, str] | None = None, - checkpoint_id: str | None = None, - ) -> None: - """CAS-pair output with an acknowledged core checkpoint before publishing its events.""" - if not self.stored: - return - snapshot_value = _json_object(snapshot) - checkpoint, checkpoint_hash = await self._get_checkpoint_with_hash(checkpoint_id or self.checkpoint_id) - if checkpoint is None: - raise RuntimeError("Output cannot be paired before a core checkpoint is acknowledged.") - if approvals is not None and any( - request_id not in checkpoint.pending_request_info_events for request_id in approvals.values() - ): - raise ValueError("Approval authority must belong to this exact pending checkpoint.") - await self.assert_claim() - if self._record is None: - raise RuntimeError("The workflow response pair has not been claimed.") - binding = replace(self.binding, checkpoint_id=checkpoint.checkpoint_id, checkpoint_hash=checkpoint_hash) - pending_approvals = { - wire_id: request_id - for wire_id, request_id in (approvals if approvals is not None else self._record.approvals or {}).items() - if request_id in checkpoint.pending_request_info_events - } - record = replace( - self._record, - binding=binding, - snapshot=snapshot_value, - approvals=pending_approvals, - ) - self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) - self.binding, self._record = binding, record - await self.assert_claim() - - async def get_checkpoint(self, checkpoint_id: str | None) -> WorkflowCheckpoint | None: - """Read a checkpoint acknowledged in this run, including a producer-stamped stream boundary.""" - checkpoint, _ = await self._get_checkpoint_with_hash(checkpoint_id) - return checkpoint - - async def _get_checkpoint_with_hash( - self, checkpoint_id: str | None - ) -> tuple[WorkflowCheckpoint | None, str | None]: - if checkpoint_id is None: - return None, None - if self._storage is None or ( - checkpoint_id not in self._storage.acknowledged_ids - and (self._checkpoint is None or checkpoint_id != self._checkpoint.checkpoint_id) - ): - raise ValueError("Output pairing requires a checkpoint acknowledged by this exact workflow turn.") - checkpoint, checkpoint_hash = await self._storage.load_persisted(checkpoint_id) - if ( - checkpoint.checkpoint_id != checkpoint_id - or checkpoint.workflow_name != self.workflow.name - or checkpoint.graph_signature_hash != self.workflow.graph_signature_hash - ): - raise ValueError("The acknowledged workflow checkpoint identity changed.") - validate_workflow_provider_state(self.workflow, checkpoint) - return checkpoint, checkpoint_hash - - async def commit(self, snapshot: Mapping[str, Any] | None = None) -> None: - """Commit only fully finalized, encoded output, before protocol success or done.""" - if self.already_completed: - return - if not self._finalized: - raise RuntimeError("A workflow cannot commit before successful core finalization.") - if not self.stored: - return - if snapshot is not None: - await self.stage(snapshot) - await self.assert_claim() - if self._record is None or self._record.snapshot is None or self.binding.checkpoint_id != self.checkpoint_id: - raise RuntimeError("The final workflow output has not been paired with its exact checkpoint.") - record = replace(self._record, status="completed") - self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) - self._record = record - head = WorkflowHead(self.binding.lineage_id, self.binding.conversation_id, self.binding) - self._head_etag = await self.store.save_head(head, expected_etag=self._head_etag) - self._head = head - self._claimed = False - - async def _reclaim_completed_ancestors(self) -> None: - """Best-effort reclaim after the new head is durably committed. - - Cleanup is oldest-first. If a deletion fails, newer records retain the - chain needed for a later successful commit to retry cleanup. - """ - if not self.reclaim_superseded or self._storage is None: - return - response_id = self.binding.previous_response_id - records: list[tuple[WorkflowRecord, str]] = [] - visited: set[str] = set() - try: - current_checkpoint_id = self.binding.checkpoint_id - checkpoint_ids = await self._storage.storage.list_checkpoint_ids(workflow_name=self.binding.workflow_name) - for checkpoint_id in checkpoint_ids: - if current_checkpoint_id is None or checkpoint_id != current_checkpoint_id: - await self._storage.storage.delete(checkpoint_id) - while response_id is not None: - if response_id in visited: - raise ValueError("Invalid cycle in superseded workflow response lineage.") - visited.add(response_id) - record, etag = await self.store.get_response(response_id) - if record is None or etag is None: - break - if ( - record.status != "completed" - or record.binding.scope_key != self.scope.storage_key - or record.binding.lineage_id != self.binding.lineage_id - or record.binding.conversation_id != self.binding.conversation_id - ): - break - records.append((record, etag)) - response_id = record.binding.previous_response_id - for record, etag in reversed(records): - await self.store.delete_response(record.binding.response_id, expected_etag=etag) - except Exception: - logger.exception("Failed to reclaim superseded native workflow state; a later commit can retry cleanup") - - async def abort(self) -> None: - """Block interrupted/failed authority instead of permitting unsafe reply or effect replay.""" - if not self.stored or not self._claimed or self.already_completed: - return - await self.assert_claim() - if self._record is not None: - record = replace(self._record, status="blocked") - self._record_etag = await self.store.save_response(record, expected_etag=self._record_etag) - self._record = record - if self._head is not None: - head = replace(self._head, blocked=True) - self._head_etag = await self.store.save_head(head, expected_etag=self._head_etag) - self._head = head - self._claimed = False diff --git a/python/packages/foundry_hosting/tests/conftest.py b/python/packages/foundry_hosting/tests/conftest.py index 3348c068c6f..daa8cb51255 100644 --- a/python/packages/foundry_hosting/tests/conftest.py +++ b/python/packages/foundry_hosting/tests/conftest.py @@ -4,7 +4,9 @@ from __future__ import annotations -from collections.abc import Iterator +import asyncio +import json +from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping, Sequence from functools import partial from pathlib import Path from tempfile import TemporaryDirectory @@ -13,6 +15,11 @@ import pytest if TYPE_CHECKING: + from unittest.mock import MagicMock + + from agent_framework import Agent, AgentResponseUpdate, AgentSession, Content, Message + from agent_framework.openai import OpenAIChatClient + from agent_framework_foundry_hosting import ( InvocationsHostServer, InvocationsWorkflowHostServer, @@ -21,6 +28,218 @@ ) +@pytest.fixture +def approval_session() -> Callable[[Content], AgentSession]: + from agent_framework import AgentSession + from agent_framework._tools import _store_pending_approval_requests + + def create(request: Content) -> AgentSession: + session = AgentSession() + _store_pending_approval_requests(session, [request]) + return session + + return create + + +@pytest.fixture +def deferred_approval_agent( + approval_session: Callable[[Content], AgentSession], +) -> Callable[ + [Sequence[AgentResponseUpdate], bool], + tuple[MagicMock, list[AgentResponseUpdate], asyncio.Event], +]: + from unittest.mock import MagicMock + + from agent_framework import AgentResponse, AgentResponseUpdate, Content, ResponseStream, SupportsAgentRun + + def create( + tail: Sequence[AgentResponseUpdate], repeat: bool + ) -> tuple[MagicMock, list[AgentResponseUpdate], asyncio.Event]: + approval = Content.from_function_approval_request( + "deferred-approval", + Content.from_function_call("deferred-call", "delete_file", arguments={}, hosted=True), + ) + updates = [AgentResponseUpdate(role="assistant", contents=[approval]), *tail] + closed = asyncio.Event() + agent = MagicMock(spec=SupportsAgentRun) + agent.id = "deferred-approval-agent" + agent.name = "Deferred approval agent" + agent.description = "Produce approval output with observable stream cleanup." + agent.context_providers = [] + agent.create_session.side_effect = lambda **kwargs: approval_session(approval) + + async def generate() -> AsyncIterator[AgentResponseUpdate]: + try: + for update in updates: + yield update + if repeat: + empty = AgentResponseUpdate(role="assistant") + while True: + yield empty + finally: + closed.set() + + def run(*args: Any, **kwargs: Any) -> ResponseStream[AgentResponseUpdate, AgentResponse]: + return ResponseStream(generate(), finalizer=AgentResponse.from_updates) + + agent.run.side_effect = run + return agent, updates, closed + + return create + + +@pytest.fixture +def native_approval_agent(request: pytest.FixtureRequest) -> tuple[Agent, list[str], list[list[Message]]]: + from agent_framework import ( + Agent, + BaseChatClient, + ChatOptions, + ChatResponse, + ChatResponseUpdate, + Content, + FunctionInvocationLayer, + ResponseStream, + tool, + ) + + executions: list[str] = [] + calls: list[list[Message]] = [] + paths: tuple[str, ...] = getattr(request, "param", ("/safe",)) + + @tool(approval_mode="always_require") + def delete_file(path: str) -> str: + """Record a protected operation without accessing the filesystem.""" + executions.append(path) + return "deleted" + + class ApprovalClient(FunctionInvocationLayer[ChatOptions], BaseChatClient[ChatOptions]): + def _inner_get_response( + self, *, messages: Sequence[Message], stream: bool, options: Mapping[str, Any], **kwargs: Any + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + calls.append(list(messages)) + contents = ( + [ + Content.from_function_call( + f"provider-call-{index}" if index else "provider-call", + "delete_file", + arguments={"path": path}, + id=f"native-call-{index}" if index else "native-call", + ) + for index, path in enumerate(paths) + ] + if len(calls) == 1 + else [Content.from_text("done")] + ) + + async def updates() -> AsyncIterator[ChatResponseUpdate]: + yield ChatResponseUpdate(role="assistant", contents=contents) + + return ResponseStream(updates(), finalizer=ChatResponse.from_updates) + + return Agent[ChatOptions](client=ApprovalClient(), tools=[delete_file]), executions, calls + + +@pytest.fixture +async def hosted_approval_client( + request: pytest.FixtureRequest, +) -> AsyncIterator[tuple[OpenAIChatClient, list[dict[str, Any]]]]: + from importlib import import_module + + from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions + from openai import AsyncOpenAI, DefaultAsyncHttpxClient + + calls: list[dict[str, Any]] = [] + fail_after_approval = getattr(request, "param", None) == "failure_after_approval" + # OpenAI supports both httpx and httpx2; match the SDK-selected transport. + sdk_httpx = import_module(DefaultAsyncHttpxClient.__mro__[1].__module__.partition(".")[0]) + + def respond(request: Any) -> Any: + assert request.method == "POST" + assert request.url.path == "/v1/responses" + payload = json.loads(request.content) + calls.append(payload) + stored = payload.get("store", True) + response: dict[str, Any] = { + "id": f"resp_hosted_{len(calls)}", + "object": "response", + "created_at": 1_700_000_000, + "model": "test-model", + "status": "in_progress", + "output": [], + "error": None, + "incomplete_details": None, + "instructions": None, + "metadata": {}, + "parallel_tool_calls": False, + "temperature": 1.0, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "usage": None, + "store": stored, + "background": False, + "conversation": {"id": "conv_hosted"} if stored else None, + } + output: list[dict[str, Any]] = ( + [ + { + "type": "mcp_approval_request", + "id": "provider-approval", + "arguments": '{"path": "/safe"}', + "name": "delete_file", + "server_label": "hosted-tools", + } + ] + if len(calls) == 1 + else [ + { + "type": "message", + "id": f"msg_hosted_{len(calls)}", + "role": "assistant", + "status": "completed", + "content": [{"type": "output_text", "text": "done", "annotations": [], "logprobs": []}], + } + ] + ) + events: list[dict[str, Any]] = [ + {"type": "response.created", "response": response}, + { + "type": "response.output_item.added", + "output_index": 0, + "item": {**output[0], "content": []} if output[0]["type"] == "message" else output[0], + }, + ] + if output[0]["type"] == "message": + events.append({ + "type": "response.output_text.delta", + "item_id": output[0]["id"], + "output_index": 0, + "content_index": 0, + "delta": "done", + "logprobs": [], + }) + if fail_after_approval and len(calls) == 1: + events.append({"type": "error", "code": "server_error", "message": "provider failed", "param": None}) + else: + events.append({"type": "response.output_item.done", "output_index": 0, "item": output[0]}) + events.append({ + "type": "response.completed", + "response": {**response, "status": "completed", "output": output}, + }) + for index, event in enumerate(events): + event["sequence_number"] = index + body = "".join(f"event: {event['type']}\ndata: {json.dumps(event)}\n\n" for event in events) + return sdk_httpx.Response(200, headers={"content-type": "text/event-stream"}, text=body + "data: [DONE]\n\n") + + async with AsyncOpenAI( + api_key="test-key", + base_url="https://provider.test/v1", + max_retries=0, + http_client=DefaultAsyncHttpxClient(transport=sdk_httpx.MockTransport(respond)), + ) as api_client: + yield OpenAIChatClient[OpenAIChatOptions](model="test-model", async_client=api_client), calls + + @pytest.fixture(autouse=True) def disable_agentserver_external_telemetry(monkeypatch: pytest.MonkeyPatch) -> None: """Keep package regressions offline, including SDK resource detection and exporters.""" diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py index 8924d81a33c..eac2b87438e 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_host_options.py @@ -14,6 +14,18 @@ from azure.ai.agentserver.responses import ResponsesServerOptions +@pytest.mark.parametrize("host_type", ["ResponsesHostServer"], indirect=True) +def test_removed_approval_store_keyword_fails_before_sdk_construction( + host_type: type[Any], host_constructor: partial[Any] +) -> None: + with ( + patch.object(host_type.__bases__[0], "__init__") as initialize, + pytest.raises(TypeError, match="function_approval_store_provider"), + ): + host_constructor(function_approval_store_provider=None) + initialize.assert_not_called() + + @pytest.mark.parametrize( "settings", [ diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py index ca2f762f647..04fb312829e 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py @@ -61,8 +61,7 @@ WorkflowTurn, ) from agent_framework_foundry_hosting._invocations_shared import _workflow_output, _WorkflowOutputError -from agent_framework_foundry_hosting._state_store import FoundryCheckpointStore -from agent_framework_foundry_hosting._workflow_state import FoundryWorkflowBindingStore, WorkflowHead +from agent_framework_foundry_hosting._shared import FoundryCheckpointStore, FoundryWorkflowBindingStore, WorkflowHead @dataclass(frozen=True) diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py index 4f9f218aa45..a00942579a5 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py @@ -47,7 +47,7 @@ ResponsesWorkflowHostServer, WorkflowTurn, ) -from agent_framework_foundry_hosting._workflow_state import FoundryWorkflowBindingStore, HostedWorkflowRun +from agent_framework_foundry_hosting._shared import FoundryWorkflowBindingStore, HostedWorkflowRun class _Ticket(BaseModel): @@ -457,8 +457,8 @@ async def test_approval_wire_ids_bind_only_to_exact_pending_checkpoint() -> None async def test_store_false_has_no_durable_native_state_and_cannot_pause() -> None: with ( - patch("agent_framework_foundry_hosting._workflow_state.FoundryStateStore.get_or_create") as bindings, - patch("agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create") as checkpoints, + patch("agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create") as bindings, + patch("agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create") as checkpoints, ): response = await _post(_server(), '{"text":"one"}', store=False) assert response["status"] == "completed", response diff --git a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py index 0a9896bb218..fa80156dc5a 100644 --- a/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py +++ b/python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py @@ -35,13 +35,14 @@ from azure.ai.agentserver.core.storage import FoundryStorageConflictError, FoundryStoragePreconditionError from agent_framework_foundry_hosting import CheckpointStoreProvider, FoundryRequestScope, WorkflowTurn -from agent_framework_foundry_hosting._shared import WorkflowResolver, prepare_workflow_kwargs -from agent_framework_foundry_hosting._workflow_state import ( +from agent_framework_foundry_hosting._shared import ( FoundryWorkflowBindingStore, HostedWorkflowRun, WorkflowBlockedError, WorkflowConflictError, WorkflowHead, + WorkflowResolver, + prepare_workflow_kwargs, ) @@ -451,7 +452,7 @@ async def test_completed_response_replay_is_explicit_and_does_not_advance_the_he async def test_default_store_integrity_hashes_the_persisted_encoding_without_repickling() -> None: first = await _prepare("one", workflow=_workflow(_Approval())) with patch( - "agent_framework_foundry_hosting._workflow_state._checkpoint_hash", + "agent_framework_foundry_hosting._shared._checkpoint_hash", side_effect=AssertionError("default storage must not re-pickle checkpoints for integrity"), ): await _finish(first, WorkflowTurn(input="/safe")) @@ -571,13 +572,13 @@ async def test_both_sdk_cas_errors_are_visible_and_private(error: type[Exception async def test_store_false_writes_nothing_and_rejects_resumption() -> None: - with patch("agent_framework_foundry_hosting._workflow_state.FoundryStateStore.get_or_create") as get_store: + with patch("agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create") as get_store: run = await _prepare("one", stored=False) assert await _finish(run, WorkflowTurn(input=3)) == [3] get_store.assert_not_called() with pytest.raises(ValueError, match="one-shot"): await _prepare("two", stored=False, previous_response_id="one") - with patch("agent_framework_foundry_hosting._workflow_state.FoundryStateStore.get_or_create") as get_store: + with patch("agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create") as get_store: run = await _prepare("pause", workflow=_workflow(_Review()), stored=False) turn = run.validate_turn(WorkflowTurn(input="review")) await run.claim() diff --git a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py index 44f6ac80b9e..a028763bb99 100644 --- a/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py +++ b/python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py @@ -28,10 +28,8 @@ def test_package_import_is_lazy() -> None: assert "agent_framework_foundry_hosting._responses_shared" not in sys.modules assert "agent_framework_foundry_hosting._responses_workflow" not in sys.modules assert "agent_framework_foundry_hosting._scope" not in sys.modules - assert "agent_framework_foundry_hosting._state_store" not in sys.modules assert "agent_framework_foundry_hosting._toolbox" not in sys.modules assert "agent_framework_foundry_hosting._shared" not in sys.modules - assert "agent_framework_foundry_hosting._workflow_state" not in sys.modules """ ) subprocess.run([sys.executable, "-I", "-c", code], check=True) @@ -62,12 +60,18 @@ def test_protocol_hosts_import_independently_in_either_order(protocol: str, work subprocess.run([sys.executable, "-I", "-c", code], check=True) -def test_native_workflow_exports_match_runtime_and_typing_namespace() -> None: +def test_native_workflow_and_storage_exports_match_runtime_and_typing_namespace() -> None: import agent_framework.foundry as foundry import agent_framework_foundry_hosting as hosting for name in ( + "AgentSessionStoreProvider", + "CheckpointStoreProvider", + "ContextScopedStoreProvider", + "FoundryAgentSessionStore", + "FoundryCheckpointStore", + "StoreProvider", "WorkflowTurn", "WorkflowSource", "ResponsesRequest", diff --git a/python/packages/foundry_hosting/tests/test_invocations.py b/python/packages/foundry_hosting/tests/test_invocations.py index 25781a54c83..e1660ece85d 100644 --- a/python/packages/foundry_hosting/tests/test_invocations.py +++ b/python/packages/foundry_hosting/tests/test_invocations.py @@ -61,7 +61,7 @@ from agent_framework_foundry_hosting import InvocationRun, InvocationsHostServer, StoreProvider from agent_framework_foundry_hosting._invocations_shared import invocation_partition_key -from agent_framework_foundry_hosting._state_store import FoundryAgentSessionStore +from agent_framework_foundry_hosting._shared import FoundryAgentSessionStore pytestmark = pytest.mark.filterwarnings("ignore:.*SessionStore is experimental.*") @@ -367,7 +367,7 @@ def update_session(session: AgentSession) -> None: identities = [("sandbox-a", "user-1"), ("sandbox-b", "user-1"), ("sandbox-a", "user-2")] with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=capture_store_name, ): for round_number in (1, 2): diff --git a/python/packages/foundry_hosting/tests/test_request.py b/python/packages/foundry_hosting/tests/test_request.py index 4a783d30556..c7c26826b02 100644 --- a/python/packages/foundry_hosting/tests/test_request.py +++ b/python/packages/foundry_hosting/tests/test_request.py @@ -119,7 +119,7 @@ async def test_explicit_message_migration_helper_converts_only_current_turn() -> result = await response_input_messages(request) assert result is converted - converter.assert_awaited_once_with(items, approval_storage=None) + converter.assert_awaited_once_with(items) async def test_hook_rejects_reserved_fields_and_non_mapping_result() -> None: diff --git a/python/packages/foundry_hosting/tests/test_responses.py b/python/packages/foundry_hosting/tests/test_responses.py index d3e8216a48c..80c465c9db9 100644 --- a/python/packages/foundry_hosting/tests/test_responses.py +++ b/python/packages/foundry_hosting/tests/test_responses.py @@ -103,13 +103,13 @@ _output_item_to_message, # pyright: ignore[reportPrivateUsage] _output_items_to_messages, # pyright: ignore[reportPrivateUsage] _OutputItemTracker, # pyright: ignore[reportPrivateUsage] + _PublicResponseFailure, # pyright: ignore[reportPrivateUsage] _stringify_mcp_output, # pyright: ignore[reportPrivateUsage] consent_url_from_error, ) -from agent_framework_foundry_hosting._state_store import ( +from agent_framework_foundry_hosting._shared import ( AgentSessionStoreProvider, FoundryAgentSessionStore, - FunctionApprovalStoreProvider, ) _OPENAI_HTTPX = cast(Any, import_module(DefaultAsyncHttpxClient.__mro__[1].__module__.partition(".")[0])) @@ -131,12 +131,6 @@ def _isolate_agentserver_state_root(tmp_path_factory: pytest.TempPathFactory) -> os.environ["AGENTSERVER_STATE_ROOT"] = previous_root -def _function_approval_store(request: Content) -> MagicMock: - storage = MagicMock() - storage.load_approval_request = AsyncMock(return_value=request) - return storage - - def _make_function_approval_request_content( *, request_id: str = "apr_test", @@ -1622,10 +1616,6 @@ def test_init_uses_default_store_providers(self) -> None: server._session_storage_provider, # pyright: ignore[reportPrivateUsage] AgentSessionStoreProvider, ) - assert isinstance( - server._function_approval_storage_provider, # pyright: ignore[reportPrivateUsage] - FunctionApprovalStoreProvider, - ) def test_init_rejects_history_provider_with_load_messages(self) -> None: @@ -2214,8 +2204,6 @@ async def test_store_false_neither_saves_session_nor_stores_inner_response(self, agent = Agent(client=client, default_options=OpenAIChatOptions(store=True)) store = SessionStore() server = _make_server(agent, session_store=store, history_source=mode) - approvals = MagicMock(spec=FunctionApprovalStoreProvider) - server._function_approval_storage_provider = approvals # pyright: ignore[reportPrivateUsage] response = await _post_json(server, {"input": "one shot", "store": False, "model": "test-model"}) @@ -2226,7 +2214,6 @@ async def test_store_false_neither_saves_session_nor_stores_inner_response(self, assert agent.default_options["store"] is True provider = cast(MagicMock, server._session_storage_provider) # pyright: ignore[reportPrivateUsage] provider.get_store.assert_not_called() - approvals.get_store.assert_not_called() async def test_store_false_rejects_external_history_and_custom_agent(self) -> None: history = _PerServiceCallHistoryProvider() @@ -6256,11 +6243,11 @@ async def test_mcp_call_with_output_reconstructs_mcp_result_content(self) -> Non assert msg.contents[1].type == "mcp_server_tool_result" assert msg.contents[1].output == "found 10 cats" - async def test_mcp_approval_request(self) -> None: + async def test_mcp_approval_request(self, approval_session: Callable[[Content], AgentSession]) -> None: from azure.ai.agentserver.responses.models import OutputItemMcpApprovalRequest saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = OutputItemMcpApprovalRequest({ "type": "mcp_approval_request", @@ -6269,15 +6256,15 @@ async def test_mcp_approval_request(self) -> None: "name": "dangerous_tool", "arguments": "{}", }) - msg = await _output_item_to_message(item, approval_storage=storage) + msg = await _output_item_to_message(item, session=session) assert msg.role == "assistant" assert msg.contents[0].type == "function_approval_request" - async def test_mcp_approval_response(self) -> None: + async def test_mcp_approval_response(self, approval_session: Callable[[Content], AgentSession]) -> None: from azure.ai.agentserver.responses.models import OutputItemMcpApprovalResponseResource saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = OutputItemMcpApprovalResponseResource({ "type": "mcp_approval_response", @@ -6285,7 +6272,7 @@ async def test_mcp_approval_response(self) -> None: "approval_request_id": "apr-1", "approve": True, }) - msg = await _output_item_to_message(item, approval_storage=storage) + msg = await _output_item_to_message(item, session=session) assert msg.role == "user" assert msg.contents[0].type == "function_approval_response" assert msg.contents[0].approved is True @@ -6888,11 +6875,11 @@ async def test_mcp_call_with_output_reconstructs_mcp_result_content(self) -> Non assert msg.contents[1].type == "mcp_server_tool_result" assert msg.contents[1].output == "found 10 cats" - async def test_mcp_approval_request(self) -> None: + async def test_mcp_approval_request(self, approval_session: Callable[[Content], AgentSession]) -> None: from azure.ai.agentserver.responses.models import ItemMcpApprovalRequest saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = ItemMcpApprovalRequest({ "type": "mcp_approval_request", @@ -6901,23 +6888,23 @@ async def test_mcp_approval_request(self) -> None: "name": "dangerous_tool", "arguments": "{}", }) - msg = await _item_to_message(item, approval_storage=storage) + msg = await _item_to_message(item, session=session) assert msg is not None assert msg.role == "assistant" assert msg.contents[0].type == "function_approval_request" - async def test_mcp_approval_response(self) -> None: + async def test_mcp_approval_response(self, approval_session: Callable[[Content], AgentSession]) -> None: from azure.ai.agentserver.responses.models import MCPApprovalResponse saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = MCPApprovalResponse({ "type": "mcp_approval_response", "approval_request_id": "apr-1", "approve": True, }) - msg = await _item_to_message(item, approval_storage=storage) + msg = await _item_to_message(item, session=session) assert msg is not None assert msg.role == "user" assert msg.contents[0].type == "function_approval_response" @@ -8243,11 +8230,13 @@ async def test_multi_turn_function_call_then_text_and_image(self) -> None: class TestFunctionApprovalConversion: """Tests for the approval-aware paths in `_item_to_message` / `_output_item_to_message`.""" - async def test_output_item_mcp_approval_request_loads_from_storage(self) -> None: + async def test_output_item_mcp_approval_request_uses_native_session( + self, approval_session: Callable[[Content], AgentSession] + ) -> None: from azure.ai.agentserver.responses.models import OutputItemMcpApprovalRequest saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = OutputItemMcpApprovalRequest({ "type": "mcp_approval_request", @@ -8256,17 +8245,17 @@ async def test_output_item_mcp_approval_request_loads_from_storage(self) -> None "name": "dangerous_tool", "arguments": "{}", }) - msg = await _output_item_to_message(item, approval_storage=storage) + msg = await _output_item_to_message(item, session=session) assert msg.role == "assistant" c = msg.contents[0] assert c.type == "function_approval_request" assert c.id == "apr-1" - # The full saved Content (incl. function_call) is restored. + # Wire-supplied names and arguments cannot replace the native pending request. function_call = c.function_call assert function_call is not None assert function_call.name == "delete_file" - async def test_output_item_mcp_approval_request_without_storage_raises(self) -> None: + async def test_output_item_mcp_approval_request_without_session_raises(self) -> None: from azure.ai.agentserver.responses.models import OutputItemMcpApprovalRequest item = OutputItemMcpApprovalRequest({ @@ -8276,14 +8265,16 @@ async def test_output_item_mcp_approval_request_without_storage_raises(self) -> "name": "dangerous_tool", "arguments": "{}", }) - with pytest.raises(ValueError, match="ApprovalStorage is required"): + with pytest.raises(_PublicResponseFailure, match="No native pending approval"): await _output_item_to_message(item) - async def test_output_item_mcp_approval_response_resolves_to_approval_response(self) -> None: + async def test_output_item_mcp_approval_response_resolves_to_approval_response( + self, approval_session: Callable[[Content], AgentSession] + ) -> None: from azure.ai.agentserver.responses.models import OutputItemMcpApprovalResponseResource saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = OutputItemMcpApprovalResponseResource({ "type": "mcp_approval_response", @@ -8291,7 +8282,7 @@ async def test_output_item_mcp_approval_response_resolves_to_approval_response(s "approval_request_id": "apr-1", "approve": True, }) - msg = await _output_item_to_message(item, approval_storage=storage) + msg = await _output_item_to_message(item, session=session) assert msg.role == "user" c = msg.contents[0] assert c.type == "function_approval_response" @@ -8301,7 +8292,7 @@ async def test_output_item_mcp_approval_response_resolves_to_approval_response(s assert function_call is not None assert function_call.name == "delete_file" - async def test_output_item_mcp_approval_response_without_storage_raises(self) -> None: + async def test_output_item_mcp_approval_response_without_session_raises(self) -> None: from azure.ai.agentserver.responses.models import OutputItemMcpApprovalResponseResource item = OutputItemMcpApprovalResponseResource({ @@ -8310,14 +8301,16 @@ async def test_output_item_mcp_approval_response_without_storage_raises(self) -> "approval_request_id": "apr-1", "approve": False, }) - with pytest.raises(ValueError, match="ApprovalStorage is required"): + with pytest.raises(_PublicResponseFailure, match="No native pending approval"): await _output_item_to_message(item) - async def test_input_item_mcp_approval_request_loads_from_storage(self) -> None: + async def test_input_item_mcp_approval_request_uses_native_session( + self, approval_session: Callable[[Content], AgentSession] + ) -> None: from azure.ai.agentserver.responses.models import ItemMcpApprovalRequest saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = ItemMcpApprovalRequest({ "type": "mcp_approval_request", @@ -8326,28 +8319,52 @@ async def test_input_item_mcp_approval_request_loads_from_storage(self) -> None: "name": "dangerous_tool", "arguments": "{}", }) - msg = await _item_to_message(item, approval_storage=storage) + msg = await _item_to_message(item, session=session) assert msg.role == "assistant" assert msg.contents[0].type == "function_approval_request" assert msg.contents[0].id == "apr-1" - async def test_input_item_mcp_approval_response_resolves_to_approval_response(self) -> None: + async def test_input_item_mcp_approval_response_resolves_to_approval_response( + self, approval_session: Callable[[Content], AgentSession] + ) -> None: from azure.ai.agentserver.responses.models import MCPApprovalResponse saved = _make_function_approval_request_content(request_id="apr-1") - storage = _function_approval_store(saved) + session = approval_session(saved) item = MCPApprovalResponse({ "type": "mcp_approval_response", "approval_request_id": "apr-1", "approve": False, }) - msg = await _item_to_message(item, approval_storage=storage) + msg = await _item_to_message(item, session=session) assert msg.role == "user" c = msg.contents[0] assert c.type == "function_approval_response" assert c.approved is False + @pytest.mark.parametrize("request_id, hosted", [("replacement-generation", False), ("provider-approval-id", True)]) + async def test_approval_translation_preserves_native_request_identity( + self, request_id: str, hosted: bool, approval_session: Callable[[Content], AgentSession] + ) -> None: + from agent_framework._tools import _load_pending_approval_requests + from azure.ai.agentserver.responses.models import MCPApprovalResponse + + call = Content.from_function_call( + "provider-call", "delete_file", id="native-call", arguments={"path": "/safe"}, hosted=hosted + ) + pending = Content.from_function_approval_request( + request_id, + call, + additional_properties={"_replacement_approval_request": True} if not hosted else None, + ) + session = approval_session(pending) + item = MCPApprovalResponse(type="mcp_approval_response", approval_request_id=request_id, approve=True) + converted = await _item_to_message(item, session=session) + assert converted.contents[0].id == request_id + assert converted.contents[0].function_call == call + assert set(_load_pending_approval_requests(session)) == {request_id} + @pytest.mark.xdist_group("session_isolation") class TestFunctionApprovalRoundTrip: @@ -8355,16 +8372,26 @@ class TestFunctionApprovalRoundTrip: Turn 1: the agent emits a `function_approval_request` content; the server emits an `mcp_approval_request` output item and persists - the original Content under the emitted id in approval storage. + the native session before publishing it. Turn 2: the caller sends an `mcp_approval_response` input item back; - the server resolves it (via approval storage) into a - `function_approval_response` content delivered to the agent. + the server translates its wire ID and delegates binding to Core, + without consuming the native pending request. """ - async def test_non_streaming_emits_mcp_approval_request_and_persists_to_storage(self) -> None: + @pytest.mark.parametrize("raw_agent", [False, True]) + async def test_non_streaming_emits_mcp_approval_request_and_persists_native_session( + self, raw_agent: bool, approval_session: Callable[[Content], AgentSession] + ) -> None: request_content = _make_function_approval_request_content() - agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[request_content])])) - server = _make_server(agent) + agent = _make_agent( + response=AgentResponse(messages=[Message(role="assistant", contents=[request_content])]), + raw_agent=raw_agent, + ) + agent.create_session.side_effect = lambda: approval_session(request_content) + store = SessionStore() + server = _make_server( + agent, session_store=store, history_source="host_managed" if raw_agent else "agent_managed" + ) resp = await _post(server, stream=False) @@ -8377,16 +8404,17 @@ async def test_non_streaming_emits_mcp_approval_request_and_persists_to_storage( assert approval_items[0]["name"] == "delete_file" assert approval_items[0]["server_label"] == "my_server" - # Storage must contain a saved entry under the emitted request id. - loaded = await server._function_approval_storage_provider.get_store( # pyright: ignore[reportPrivateUsage] - config=server.config, platform_context=get_request_context() - ).load_approval_request(approval_request_id) - assert loaded.type == "function_approval_request" - assert loaded.function_call is not None - assert loaded.function_call.name == "delete_file" + assert approval_request_id != request_content.id + assert "internal_metadata" not in approval_items[0] + loaded = await store.get(body["id"]) + assert loaded is not None + assert loaded.to_dict()["state"] == approval_session(request_content).to_dict()["state"] @pytest.mark.parametrize("with_preamble", [False, True]) - async def test_streaming_emits_mcp_approval_request_and_persists_to_storage(self, with_preamble: bool) -> None: + @pytest.mark.parametrize("raw_agent", [False, True]) + async def test_streaming_emits_mcp_approval_request_and_persists_native_session( + self, with_preamble: bool, raw_agent: bool, approval_session: Callable[[Content], AgentSession] + ) -> None: request_content = _make_function_approval_request_content(request_id="apr_streaming") updates: list[AgentResponseUpdate] = [] preambles = ("Checking the refund policy.", "The refund requires approval.") @@ -8412,8 +8440,12 @@ async def test_streaming_emits_mcp_approval_request_and_persists_to_storage(self ) ) updates.append(AgentResponseUpdate(contents=[request_content], role="assistant")) - agent = _make_agent(stream_updates=updates) - server = _make_server(agent) + agent = _make_agent(stream_updates=updates, raw_agent=raw_agent) + agent.create_session.side_effect = lambda: approval_session(request_content) + store = SessionStore() + server = _make_server( + agent, session_store=store, history_source="host_managed" if raw_agent else "agent_managed" + ) resp = await _post(server, stream=True) @@ -8438,12 +8470,14 @@ async def test_streaming_emits_mcp_approval_request_and_persists_to_storage(self break assert approval_request_id is not None - loaded = await server._function_approval_storage_provider.get_store( # pyright: ignore[reportPrivateUsage] - config=server.config, platform_context=get_request_context() - ).load_approval_request(approval_request_id) - assert loaded.type == "function_approval_request" + response_id = events[0]["data"]["response"]["id"] + loaded = await store.get(response_id) + assert loaded is not None + assert loaded.to_dict()["state"] == approval_session(request_content).to_dict()["state"] - async def test_round_trip_approval_response_reaches_agent(self) -> None: + async def test_round_trip_approval_response_reaches_agent( + self, approval_session: Callable[[Content], AgentSession] + ) -> None: """Two-turn: turn 1 emits an approval request; turn 2 sends an approval response and the agent receives a `function_approval_response`.""" request_content = _make_function_approval_request_content() @@ -8454,7 +8488,8 @@ async def test_round_trip_approval_response_reaches_agent(self) -> None: AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]), ] ) - server = _make_server(agent) + agent.create_session.side_effect = lambda: approval_session(request_content) + server = _make_server(agent, session_store=SessionStore()) first = await _post(server, stream=False) assert first.status_code == 200 @@ -8466,6 +8501,7 @@ async def test_round_trip_approval_response_reaches_agent(self) -> None: # Send back an approval response that references the saved request id. second_payload: dict[str, Any] = { "model": "test-model", + "previous_response_id": first_body["id"], "input": [ { "type": "mcp_approval_response", @@ -8489,7 +8525,9 @@ async def test_round_trip_approval_response_reaches_agent(self) -> None: assert approval_responses[0].approved is True assert approval_responses[0].function_call.name == "delete_file" - async def test_round_trip_approval_response_rejected(self) -> None: + async def test_round_trip_approval_response_rejected( + self, approval_session: Callable[[Content], AgentSession] + ) -> None: """Same as above but the user rejects the approval; the agent must receive `approved=False`.""" request_content = _make_function_approval_request_content() @@ -8500,7 +8538,8 @@ async def test_round_trip_approval_response_rejected(self) -> None: AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])]), ] ) - server = _make_server(agent) + agent.create_session.side_effect = lambda: approval_session(request_content) + server = _make_server(agent, session_store=SessionStore()) first = await _post(server, stream=False) approval_request_id = next( @@ -8511,6 +8550,7 @@ async def test_round_trip_approval_response_rejected(self) -> None: server, { "model": "test-model", + "previous_response_id": first.json()["id"], "input": [ { "type": "mcp_approval_response", @@ -8553,7 +8593,7 @@ async def test_approval_response_referencing_unknown_id_fails(self) -> None: "stream": False, }, ) - # The handler converts the underlying KeyError into a terminal + # The handler converts the failed native binding into a terminal # ``response.failed`` event, so non-streaming callers see HTTP 200 # with status="failed" and a meaningful error message rather than # a generic 5xx response. @@ -8563,6 +8603,579 @@ async def test_approval_response_referencing_unknown_id_fails(self) -> None: error: dict[str, Any] = body.get("error") or {} assert "apr_unknown" in (error.get("message") or "") + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("approved", [False, True]) + @pytest.mark.parametrize( + "history_source, downstream_store", + [("host_managed", False), ("inference_service", True), ("agent_managed", True), ("agent_managed", False)], + ) + async def test_hosted_approval_replays_only_with_the_owner_of_history( + self, + stream: bool, + approved: bool, + history_source: str, + downstream_store: bool, + hosted_approval_client: tuple[OpenAIChatClient, list[dict[str, Any]]], + ) -> None: + client, calls = hosted_approval_client + agent = Agent[OpenAIChatOptions]( + client=client, + default_options=OpenAIChatOptions(store=downstream_store), + context_providers=[InMemoryHistoryProvider()] if history_source == "agent_managed" else [], + ) + server = _make_server( + agent, + session_store=SessionStore(), + history_source=history_source, + **({"max_history_items": 1} if history_source == "host_managed" else {}), + ) + first = await _post(server, stream=stream) + first_body = _parse_sse_events(first.text)[-1]["data"]["response"] if stream else first.json() + assert first_body["status"] == "completed", first_body + wire_id = next(item["id"] for item in first_body["output"] if item["type"] == "mcp_approval_request") + + second = await _post_json( + server, + { + "input": [{"type": "mcp_approval_response", "approval_request_id": wire_id, "approve": approved}], + "previous_response_id": first_body["id"], + "stream": stream, + }, + ) + body = _parse_sse_events(second.text)[-1]["data"]["response"] if stream else second.json() + assert body["status"] == "completed", body + assert len(calls) == 2 + controls = [ + item for item in calls[-1]["input"] if item.get("type") in ("mcp_approval_request", "mcp_approval_response") + ] + expected = ( + [] + if downstream_store + else [ + { + "type": "mcp_approval_request", + "id": "provider-approval", + "arguments": '{"path": "/safe"}', + "name": "delete_file", + "server_label": "hosted-tools", + } + ] + ) + assert controls == [ + *expected, + {"type": "mcp_approval_response", "approval_request_id": "provider-approval", "approve": approved}, + ] + assert calls[-1].get("store", True) is downstream_store + assert calls[-1].get("conversation") == ("conv_hosted" if downstream_store else None) + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("history_source", ["host_managed", "agent_managed"]) + @pytest.mark.parametrize( + "arguments, changes", + [ + pytest.param("{}", {"name": "another_tool"}, id="tool"), + pytest.param("{}", {"server_name": "another_server"}, id="server"), + pytest.param('{"path": "/safe"}', {"arguments": '{"path": "/other"}'}, id="arguments"), + pytest.param('{"value": true}', {"arguments": '{"value": 1}'}, id="boolean-to-integer"), + pytest.param('{"value": 1}', {"arguments": '{"value": true}'}, id="integer-to-boolean"), + pytest.param( + '{"value": 1.00000000000000000001}', + {"arguments": '{"value": 1.00000000000000000002}'}, + id="precise-number", + ), + pytest.param("opaque", {"arguments": "different"}, id="opaque-arguments"), + ], + ) + async def test_stale_wire_approval_cannot_bind_to_reused_native_id( + self, + stream: bool, + history_source: str, + arguments: str, + changes: dict[str, str], + approval_session: Callable[[Content], AgentSession], + ) -> None: + from agent_framework._tools import ( + _bind_approval_response_to_pending_request, + _load_pending_approval_requests, + _store_pending_approval_requests, + ) + + request = _make_function_approval_request_content(arguments=arguments) + agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[request])])) + agent.create_session.side_effect = lambda: approval_session(request) + store = SessionStore() + server = _make_server(agent, session_store=store, history_source=history_source) + first_response = await _post(server, stream=stream) + first = _parse_sse_events(first_response.text)[-1]["data"]["response"] if stream else first_response.json() + assert first["status"] == "completed", first + wire_id = next(item["id"] for item in first["output"] if item["type"] == "mcp_approval_request") + session = await store.get(first["id"]) + assert session is not None + consumed = _bind_approval_response_to_pending_request( + Content("function_approval_response", id=request.id, approved=True), session, consume=True + ) + assert consumed is not None and not _load_pending_approval_requests(session) + replacement = Content.from_dict(request.to_dict()) + assert replacement.function_call is not None + replacement.function_call.id = "new-hosted-occurrence" + replacement.function_call.additional_properties.pop("server_label", None) + for field, value in changes.items(): + setattr(replacement.function_call, field, value) + _store_pending_approval_requests(session, [replacement]) + await store.set(first["id"], session) + + response = await _post_json( + server, + { + "input": [{"type": "mcp_approval_response", "approval_request_id": wire_id, "approve": True}], + "previous_response_id": first["id"], + "stream": stream, + }, + ) + body = _parse_sse_events(response.text)[-1]["data"]["response"] if stream else response.json() + assert body["status"] == "failed", body + assert "does not match the current native pending request" in body["error"]["message"] + assert agent.run.call_count == 1 + saved = await store.get(body["id"]) + assert saved is not None and request.id is not None + assert _load_pending_approval_requests(saved)[request.id].to_dict() == replacement.to_dict() + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize( + "arguments, restored_arguments", + [ + ('{"a": 1, "b": [true, null]}', {"b": [True, None], "a": 1}), + ('{"value": 1.0, "name": "\\u4e2d"}', '{"name": "\u4e2d", "value": 1e0}'), + ("opaque", "opaque"), + ], + ) + async def test_wire_approval_accepts_equivalent_argument_serialization( + self, + stream: bool, + arguments: str, + restored_arguments: Any, + approval_session: Callable[[Content], AgentSession], + ) -> None: + from agent_framework._tools import _load_pending_approval_requests, _store_pending_approval_requests + + request = _make_function_approval_request_content(arguments=arguments) + agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[request])])) + agent.create_session.side_effect = lambda: approval_session(request) + store = SessionStore() + server = _make_server(agent, session_store=store) + first = (await _post(server)).json() + wire_id = next(item["id"] for item in first["output"] if item["type"] == "mcp_approval_request") + session = await store.get(first["id"]) + assert session is not None and request.id is not None + restored = _load_pending_approval_requests(session)[request.id] + assert restored.function_call is not None + restored.function_call.arguments = restored_arguments + _store_pending_approval_requests(session, [restored]) + await store.set(first["id"], session) + agent.run.side_effect = _make_agent( + response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("done")])]) + ).run.side_effect + + response = await _post_json( + server, + { + "input": [{"type": "mcp_approval_response", "approval_request_id": wire_id, "approve": True}], + "previous_response_id": first["id"], + "stream": stream, + }, + ) + body = _parse_sse_events(response.text)[-1]["data"]["response"] if stream else response.json() + assert body["status"] == "completed", body + assert agent.run.call_count == 2 + decisions = [ + content + for message in agent.run.call_args.kwargs["messages"] + for content in message.contents + if content.type == "function_approval_response" + ] + assert len(decisions) == 1 and decisions[0].function_call is not None + assert decisions[0].function_call.arguments == restored_arguments + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("limit", ["count", "bytes"]) + @pytest.mark.parametrize("overflow", [False, True], ids=["exact-limit", "over-limit"]) + async def test_deferred_approval_output_has_count_and_byte_limits( + self, + stream: bool, + limit: str, + overflow: bool, + deferred_approval_agent: Callable[ + [Sequence[AgentResponseUpdate], bool], + tuple[MagicMock, list[AgentResponseUpdate], asyncio.Event], + ], + monkeypatch: pytest.MonkeyPatch, + ) -> None: + agent, updates, closed = deferred_approval_agent( + [AgentResponseUpdate(role="assistant", contents=[Content.from_text("\u4e2d" * 32)])], False + ) + total_bytes = sum( + len(update.to_json(ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")) + for update in updates + ) + monkeypatch.setattr( + "agent_framework_foundry_hosting._responses_agent._MAX_DEFERRED_APPROVAL_UPDATES", + len(updates) - int(overflow and limit == "count"), + raising=False, + ) + monkeypatch.setattr( + "agent_framework_foundry_hosting._responses_agent._MAX_DEFERRED_APPROVAL_BYTES", + total_bytes - int(overflow and limit == "bytes"), + raising=False, + ) + response = await _post( + _make_server(agent, session_store=SessionStore(), history_source="agent_managed"), stream=stream + ) + events = _parse_sse_events(response.text) if stream else [] + body = events[-1]["data"]["response"] if stream else response.json() + assert body["status"] == ("failed" if overflow else "completed"), body + assert closed.is_set() + approvals = [item for item in body["output"] if item["type"] == "mcp_approval_request"] + if overflow: + assert "Deferred approval output exceeds" in body["error"]["message"] + assert approvals == [] + assert not any(event["data"].get("item", {}).get("type") == "mcp_approval_request" for event in events) + else: + assert len(approvals) == 1 + assert body["output"][-1]["content"][0]["text"] == "\u4e2d" * 32 + + @pytest.mark.parametrize("limit", ["count", "bytes"]) + @pytest.mark.parametrize("overflow", [False, True], ids=["exact-limit", "over-limit"]) + async def test_deferred_approval_output_enforces_default_limits( + self, + limit: str, + overflow: bool, + deferred_approval_agent: Callable[ + [Sequence[AgentResponseUpdate], bool], + tuple[MagicMock, list[AgentResponseUpdate], asyncio.Event], + ], + ) -> None: + if limit == "count": + agent, _, closed = deferred_approval_agent( + [AgentResponseUpdate(role="assistant")] * (4095 + int(overflow)), False + ) + else: + text = Content.from_text("") + agent, updates, closed = deferred_approval_agent( + [AgentResponseUpdate(role="assistant", contents=[text])], False + ) + overhead = sum( + len(update.to_json(ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")) + for update in updates + ) + text.text = "x" * (4 * 1024 * 1024 - overhead + int(overflow)) + response = await _post( + _make_server(agent, session_store=SessionStore(), history_source="agent_managed"), stream=False + ) + body = response.json() + assert body["status"] == ("failed" if overflow else "completed"), body["status"] + assert closed.is_set() + if overflow: + assert "Deferred approval output exceeds" in body["error"]["message"] + assert not any(item["type"] == "mcp_approval_request" for item in body["output"]) + else: + assert any(item["type"] == "mcp_approval_request" for item in body["output"]) + + @pytest.mark.parametrize("stream", [False, True]) + async def test_deferred_approval_limit_closes_an_unending_stream( + self, + stream: bool, + deferred_approval_agent: Callable[ + [Sequence[AgentResponseUpdate], bool], + tuple[MagicMock, list[AgentResponseUpdate], asyncio.Event], + ], + monkeypatch: pytest.MonkeyPatch, + ) -> None: + agent, _, closed = deferred_approval_agent([], True) + monkeypatch.setattr( + "agent_framework_foundry_hosting._responses_agent._MAX_DEFERRED_APPROVAL_UPDATES", 2, raising=False + ) + response = await asyncio.wait_for( + _post(_make_server(agent, session_store=SessionStore(), history_source="agent_managed"), stream=stream), + timeout=5, + ) + events = _parse_sse_events(response.text) if stream else [] + body = events[-1]["data"]["response"] if stream else response.json() + assert body["status"] == "failed", body + assert "update-count limit" in body["error"]["message"] + assert closed.is_set() + assert not any(item["type"] == "mcp_approval_request" for item in body["output"]) + assert not any(event["data"].get("item", {}).get("type") == "mcp_approval_request" for event in events) + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("pending_state", ["missing", "mismatched"]) + async def test_custom_agent_cannot_publish_approval_without_matching_native_state( + self, + stream: bool, + pending_state: str, + approval_session: Callable[[Content], AgentSession], + ) -> None: + from agent_framework._tools import _load_pending_approval_requests + + request = _make_function_approval_request_content() + agent = _make_agent( + response=AgentResponse(messages=[Message(role="assistant", contents=[request])]), raw_agent=False + ) + if pending_state == "mismatched": + recorded = Content.from_dict(request.to_dict()) + assert recorded.function_call is not None + recorded.function_call.arguments = '{"path": "/different"}' + agent.create_session.side_effect = lambda: approval_session(recorded) + store = SessionStore() + server = _make_server(agent, session_store=store, history_source="agent_managed") + response = await _post(server, stream=stream) + events = _parse_sse_events(response.text) if stream else [] + body = events[-1]["data"]["response"] if stream else response.json() + assert body["status"] == "failed", body + assert "matching native pending" in body["error"]["message"] + assert not any(item["type"] == "mcp_approval_request" for item in body["output"]) + assert not any(event["data"].get("item", {}).get("type") == "mcp_approval_request" for event in events) + session = await store.get(body["id"]) + assert session is not None + pending = _load_pending_approval_requests(session) + assert len(pending) == (1 if pending_state == "mismatched" else 0) + if pending_state == "mismatched": + assert request.id is not None + pending_call = pending[request.id].function_call + assert pending_call is not None and pending_call.arguments == '{"path": "/different"}' + + @pytest.mark.parametrize("hosted_approval_client", ["failure_after_approval"], indirect=True) + @pytest.mark.parametrize("stream", [False, True]) + async def test_failed_native_finalization_does_not_publish_approval( + self, stream: bool, hosted_approval_client: tuple[OpenAIChatClient, list[dict[str, Any]]] + ) -> None: + from agent_framework._tools import _load_pending_approval_requests + + client, calls = hosted_approval_client + store = SessionStore() + server = _make_server(Agent(client=client), session_store=store) + response = await _post(server, stream=stream) + events = _parse_sse_events(response.text) if stream else [] + body = events[-1]["data"]["response"] if stream else response.json() + assert body["status"] == "failed", body + assert len(calls) == 1 + assert not any(item["type"] == "mcp_approval_request" for item in body["output"]) + assert not any(event["data"].get("item", {}).get("type") == "mcp_approval_request" for event in events) + session = await store.get(body["id"]) + assert session is not None and not _load_pending_approval_requests(session) + + async def test_deferred_approval_preserves_streamed_output_order( + self, approval_session: Callable[[Content], AgentSession] + ) -> None: + request = _make_function_approval_request_content() + agent = _make_agent( + stream_updates=[ + AgentResponseUpdate(role="assistant", contents=[Content.from_text("before")]), + AgentResponseUpdate(role="assistant", contents=[request]), + AgentResponseUpdate(role="assistant", contents=[Content.from_text("after")]), + ] + ) + agent.create_session.side_effect = lambda: approval_session(request) + response = await _post(_make_server(agent, session_store=SessionStore()), stream=True) + events = _parse_sse_events(response.text) + assert events[-1]["data"]["response"]["status"] == "completed" + ordered_output: list[str] = [] + for event in events: + if event["event"] == "response.output_text.done": + ordered_output.append(event["data"]["text"]) + elif ( + event["event"] == "response.output_item.added" + and event["data"]["item"]["type"] == "mcp_approval_request" + ): + ordered_output.append("approval") + assert ordered_output == ["before", "approval", "after"] + + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("approved", [False, True]) + @pytest.mark.parametrize( + "history_source, history_limit", + [("host_managed", None), ("host_managed", 1), ("agent_managed", None)], + ) + async def test_native_agent_consumes_serialized_session_approval( + self, + stream: bool, + approved: bool, + history_source: str, + history_limit: int | None, + native_approval_agent: tuple[Agent, list[str], list[list[Message]]], + ) -> None: + from agent_framework._tools import _load_pending_approval_requests + + agent, executions, calls = native_approval_agent + store = SessionStore() + settings = {"max_history_items": history_limit} if history_source == "host_managed" else {} + server = _make_server(agent, session_store=store, history_source=history_source, **settings) + first = await _post(server, stream=stream) + first_body = _parse_sse_events(first.text)[-1]["data"]["response"] if stream else first.json() + assert first_body["status"] == "completed", first_body + wire_id = next(item["id"] for item in first_body["output"] if item["type"] == "mcp_approval_request") + session = await store.get(first_body["id"]) + assert session is not None + assert set(_load_pending_approval_requests(session)) == {"native-call"} + assert executions == [] + await store.set(first_body["id"], AgentSession.from_dict(json.loads(json.dumps(session.to_dict())))) + + decision = {"type": "mcp_approval_response", "approval_request_id": wire_id, "approve": approved} + second = await _post_json( + server, + {"input": [decision], "previous_response_id": first_body["id"], "stream": stream}, + ) + second_body = _parse_sse_events(second.text)[-1]["data"]["response"] if stream else second.json() + assert second_body["status"] == "completed", second_body + assert executions == (["/safe"] if approved else []) + assert len(calls) == 2 + assert any( + content.type == "function_result" and content.call_id == "provider-call" + for message in calls[-1] + for content in message.contents + ) + resumed_calls = [ + content for message in calls[-1] for content in message.contents if content.type == "function_call" + ] + resumed_results = [ + content for message in calls[-1] for content in message.contents if content.type == "function_result" + ] + assert len(resumed_calls) == len(resumed_results) == 1 + assert resumed_calls[0].call_id == resumed_results[0].call_id == "provider-call" + assert not any( + content.type in ("function_approval_request", "function_approval_response") + for message in calls[-1] + for content in message.contents + ) + saved = await store.get(second_body["id"]) + assert saved is not None and not _load_pending_approval_requests(saved) + + third = await _post_json(server, {"input": "continue", "previous_response_id": second_body["id"]}) + assert third.json()["status"] == "completed", third.json() + assert executions == (["/safe"] if approved else []) + assert len(calls) == 3 + assert not any( + content.type in ("function_approval_request", "function_approval_response") + for message in calls[-1] + for content in message.contents + ) + + replay = await _post_json( + server, {"input": [decision], "previous_response_id": second_body["id"], "stream": False} + ) + assert replay.json()["status"] == "failed" + assert executions == (["/safe"] if approved else []) + assert len(calls) == 3 + + @pytest.mark.parametrize("stream", [False, True]) + async def test_wire_correlation_cannot_cross_native_sessions( + self, stream: bool, approval_session: Callable[[Content], AgentSession] + ) -> None: + from agent_framework._tools import _load_pending_approval_requests + + request = _make_function_approval_request_content() + agent = _make_agent(response=AgentResponse(messages=[Message(role="assistant", contents=[request])])) + agent.create_session.side_effect = lambda: approval_session(request) + store = SessionStore() + server = _make_server(agent, session_store=store) + first = (await _post(server)).json() + other = (await _post(server)).json() + wire_id = next(item["id"] for item in first["output"] if item["type"] == "mcp_approval_request") + response = await _post_json( + server, + { + "input": [{"type": "mcp_approval_response", "approval_request_id": wire_id, "approve": True}], + "previous_response_id": other["id"], + "stream": stream, + }, + ) + body = _parse_sse_events(response.text)[-1]["data"]["response"] if stream else response.json() + assert body["status"] == "failed" + assert "does not belong" in body["error"]["message"] + assert agent.run.call_count == 2 + session = await store.get(other["id"]) + assert session is not None + assert set(_load_pending_approval_requests(session)) == {request.id} + + @pytest.mark.parametrize("native_approval_agent", [("/safe", "/other")], indirect=True) + @pytest.mark.parametrize("stream", [False, True]) + @pytest.mark.parametrize("first_approved", [False, True]) + async def test_native_approval_batch_waits_for_all_decisions( + self, + stream: bool, + first_approved: bool, + native_approval_agent: tuple[Agent, list[str], list[list[Message]]], + ) -> None: + agent, executions, calls = native_approval_agent + server = _make_server(agent, session_store=SessionStore(), max_history_items=1) + first = await _post(server, stream=stream) + first_body = _parse_sse_events(first.text)[-1]["data"]["response"] if stream else first.json() + wire_ids = { + json.loads(item["arguments"])["path"]: item["id"] + for item in first_body["output"] + if item["type"] == "mcp_approval_request" + } + partial = await _post_json( + server, + { + "input": [ + { + "type": "mcp_approval_response", + "approval_request_id": wire_ids["/safe"], + "approve": first_approved, + } + ], + "previous_response_id": first_body["id"], + "stream": stream, + }, + ) + partial_body = _parse_sse_events(partial.text)[-1]["data"]["response"] if stream else partial.json() + assert partial_body["status"] == "completed", partial_body + assert executions == [] + assert len(calls) == 1 + + final = await _post_json( + server, + { + "input": [ + { + "type": "mcp_approval_response", + "approval_request_id": wire_ids["/other"], + "approve": not first_approved, + } + ], + "previous_response_id": partial_body["id"], + "stream": stream, + }, + ) + final_body = _parse_sse_events(final.text)[-1]["data"]["response"] if stream else final.json() + assert final_body["status"] == "completed", final_body + assert executions == (["/safe"] if first_approved else ["/other"]) + assert len(calls) == 2 + model_calls = [ + content.call_id for message in calls[-1] for content in message.contents if content.type == "function_call" + ] + model_results = [ + content.call_id + for message in calls[-1] + for content in message.contents + if content.type == "function_result" + ] + assert model_calls == model_results == ["provider-call", "provider-call-1"] + + @pytest.mark.parametrize("stream", [False, True]) + async def test_session_save_failure_does_not_publish_resumable_approval( + self, stream: bool, native_approval_agent: tuple[Agent, list[str], list[list[Message]]] + ) -> None: + agent, executions, _ = native_approval_agent + store = SessionStore() + server = _make_server(agent, session_store=store) + with patch.object(store, "set", side_effect=RuntimeError("storage unavailable")): + response = await _post(server, stream=stream) + body = _parse_sse_events(response.text)[-1]["data"]["response"] if stream else response.json() + assert body["status"] == "failed", body + assert not any(item["type"] == "mcp_approval_request" for item in body["output"]) + assert executions == [] + # endregion @@ -9650,8 +10263,14 @@ class TestParallelRequestReads: @staticmethod def _identity_converters(monkeypatch: pytest.MonkeyPatch) -> None: - async def _passthrough(items: Any, *, approval_storage: Any = None) -> list[Any]: - del approval_storage + async def _passthrough( + items: Any, + *, + session: Any = None, + approval_ids: Any = None, + include_hosted_approval_requests: bool = False, + ) -> list[Any]: + del session, approval_ids, include_hosted_approval_requests return list(items) monkeypatch.setattr("agent_framework_foundry_hosting._responses_agent._items_to_messages", _passthrough) @@ -9662,19 +10281,19 @@ async def test_reads_overlap_and_preserve_order(self, monkeypatch: pytest.Monkey server = _make_server(_make_agent()) server._uses_agent_server_history = True # pyright: ignore[reportPrivateUsage] - history_msg = Message(role="assistant", contents=[Content.from_text("H")]) - input_msg = Message(role="user", contents=[Content.from_text("I")]) + history_msg = cast(OutputItem, {"type": "output_message", "role": "assistant", "content": []}) + input_msg = cast(Item, {"type": "message", "role": "user", "content": "I"}) input_started = asyncio.Event() history_started = asyncio.Event() release = asyncio.Event() - async def get_input_items() -> list[Message]: + async def get_input_items() -> list[Item]: input_started.set() await release.wait() return [input_msg] - async def get_history() -> list[Message]: + async def get_history() -> list[OutputItem]: history_started.set() await release.wait() return [history_msg] @@ -9683,7 +10302,7 @@ async def get_history() -> list[Message]: context.get_input_items = get_input_items context.get_history = get_history - task = asyncio.ensure_future(server._load_request_messages(context, approval_storage=None)) # pyright: ignore[reportPrivateUsage] + task = asyncio.ensure_future(server._load_request_messages(context)) # pyright: ignore[reportPrivateUsage] try: # Both reads must be in-flight before either is allowed to finish — proves they overlap. await asyncio.wait_for(input_started.wait(), timeout=1) @@ -9701,16 +10320,16 @@ async def test_history_read_skipped_without_agent_server_history(self, monkeypat server = _make_server(_make_agent()) server._uses_agent_server_history = False # pyright: ignore[reportPrivateUsage] - input_msg = Message(role="user", contents=[Content.from_text("I")]) + input_msg = cast(Item, {"type": "message", "role": "user", "content": "I"}) - async def get_input_items() -> list[Message]: + async def get_input_items() -> list[Item]: return [input_msg] context = MagicMock(spec=ResponseContext) context.get_input_items = get_input_items context.get_history = AsyncMock() - messages = await server._load_request_messages(context, approval_storage=None) # pyright: ignore[reportPrivateUsage] + messages = await server._load_request_messages(context) # pyright: ignore[reportPrivateUsage] assert messages == [input_msg] context.get_history.assert_not_awaited() @@ -9739,7 +10358,7 @@ async def get_history() -> list[Message]: with pytest.raises(RuntimeError, match="input read boom"): await asyncio.wait_for( - server._load_request_messages(context, approval_storage=None), # pyright: ignore[reportPrivateUsage] + server._load_request_messages(context), # pyright: ignore[reportPrivateUsage] timeout=2, ) diff --git a/python/packages/foundry_hosting/tests/test_state_store.py b/python/packages/foundry_hosting/tests/test_state_store.py index 5c622ca1e75..e80411ca77f 100644 --- a/python/packages/foundry_hosting/tests/test_state_store.py +++ b/python/packages/foundry_hosting/tests/test_state_store.py @@ -6,19 +6,17 @@ from unittest.mock import AsyncMock, MagicMock, patch import pytest -from agent_framework import AgentSession, Content, WorkflowCheckpoint, WorkflowCheckpointException +from agent_framework import AgentSession, WorkflowCheckpoint, WorkflowCheckpointException from agent_framework._workflows._checkpoint_encoding import encode_checkpoint_value from azure.ai.agentserver.core import AgentConfig, FoundryAgentRequestContext -from azure.ai.agentserver.core.storage import FoundryStateStore, FoundryStorageConflictError +from azure.ai.agentserver.core.storage import FoundryStateStore from agent_framework_foundry_hosting import ContextScopedStoreProvider, StoreProvider -from agent_framework_foundry_hosting._state_store import ( +from agent_framework_foundry_hosting._shared import ( AgentSessionStoreProvider, CheckpointStoreProvider, FoundryAgentSessionStore, FoundryCheckpointStore, - FoundryFunctionApprovalStore, - FunctionApprovalStoreProvider, ) @@ -82,7 +80,6 @@ def _platform_context( def test_storage_providers_use_public_abstraction() -> None: assert issubclass(CheckpointStoreProvider, ContextScopedStoreProvider) assert not issubclass(CheckpointStoreProvider, StoreProvider) - assert issubclass(FunctionApprovalStoreProvider, StoreProvider) assert issubclass(AgentSessionStoreProvider, StoreProvider) @@ -91,7 +88,7 @@ async def test_save_uses_context_scoped_store() -> None: checkpoint = _checkpoint("checkpoint-1") with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ) as get_or_create: result = await FoundryCheckpointStore("context-1", _platform_context()).save(checkpoint) @@ -107,7 +104,7 @@ async def test_load_returns_checkpoint() -> None: store.get_item = AsyncMock(return_value=SimpleNamespace(value=checkpoint.to_dict())) with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ): result = await FoundryCheckpointStore("context-1", _platform_context()).load("checkpoint-1") @@ -130,7 +127,7 @@ async def test_load_restricts_checkpoint_deserialization() -> None: with ( patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ), pytest.raises(WorkflowCheckpointException), @@ -147,7 +144,7 @@ async def test_load_accepts_a_declared_checkpoint_type() -> None: store.get_item = AsyncMock(return_value=SimpleNamespace(value=value)) with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ): result = await FoundryCheckpointStore( @@ -171,7 +168,7 @@ async def test_list_checkpoints_restricts_checkpoint_deserialization() -> None: with ( patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ), pytest.raises(WorkflowCheckpointException), @@ -201,7 +198,7 @@ async def test_provider_forwards_allowed_checkpoint_types() -> None: ) with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ): result = await storage.load("checkpoint-1") @@ -225,7 +222,7 @@ async def test_provider_restricts_by_default() -> None: with ( patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ), pytest.raises(WorkflowCheckpointException), @@ -239,7 +236,7 @@ async def test_load_raises_for_missing_checkpoint() -> None: with ( patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ), pytest.raises(WorkflowCheckpointException, match="No checkpoint found with ID missing"), @@ -268,7 +265,7 @@ async def test_list_checkpoints_paginates_and_filters_by_workflow() -> None: ) with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ): result = await FoundryCheckpointStore("context-1", _platform_context()).list_checkpoints( @@ -287,7 +284,7 @@ async def test_delete_reports_whether_checkpoint_existed(deleted_id: str | None, store.delete_item = AsyncMock(return_value=SimpleNamespace(id=deleted_id)) with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ): result = await FoundryCheckpointStore("context-1", _platform_context()).delete("checkpoint-1") @@ -387,102 +384,13 @@ def test_checkpoint_stores_require_context_id(create_store: Callable[[], Any]) - create_store() -def _approval_request(approval_request_id: str) -> Content: - function_call = Content.from_function_call( - "call-1", - "delete_file", - arguments='{"path": "/foo"}', - additional_properties={"server_label": "my_server"}, - ) - return Content.from_function_approval_request(approval_request_id, function_call) - - -async def test_save_and_load_function_approval_request() -> None: - store = _store() - request = _approval_request("approval-1") - store.get_item = AsyncMock(return_value=SimpleNamespace(value=request.to_dict())) - - with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ) as get_or_create: - storage = FoundryFunctionApprovalStore(_platform_context()) - await storage.save_approval_request("approval-1", request) - loaded = await storage.load_approval_request("approval-1") - - assert get_or_create.await_count == 2 - get_or_create.assert_awaited_with("function_approvals", user_isolation=True) - store.create_item.assert_awaited_once_with("approval-1", request.to_dict(), call_id="call-1") - store.get_item.assert_awaited_once_with("approval-1", call_id="call-1") - assert loaded == request - function_call = loaded.function_call - assert function_call is not None - assert function_call.name == "delete_file" - assert function_call.additional_properties["server_label"] == "my_server" - - -async def test_save_duplicate_function_approval_request_raises() -> None: - store = _store() - store.create_item = AsyncMock(side_effect=FoundryStorageConflictError("already exists")) - - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ), - pytest.raises(ValueError, match="Approval request with ID 'approval-1' already exists"), - ): - await FoundryFunctionApprovalStore(_platform_context()).save_approval_request( - "approval-1", _approval_request("approval-1") - ) - - -async def test_load_missing_function_approval_request_raises() -> None: - store = _store() - store.get_item = AsyncMock(return_value=None) - - with ( - patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", - new=AsyncMock(return_value=store), - ), - pytest.raises(KeyError, match="Approval request with ID 'missing' does not exist"), - ): - await FoundryFunctionApprovalStore(_platform_context()).load_approval_request("missing") - - -@pytest.mark.parametrize("is_hosted", [True, False]) -def test_function_approval_storage_provider_uses_foundry_store(is_hosted: bool) -> None: - provider = FunctionApprovalStoreProvider() - config = _config(is_hosted=is_hosted) - platform_context = _platform_context() - - storage = provider.get_store(config=config, platform_context=platform_context) - - assert type(storage) is FoundryFunctionApprovalStore - assert storage.platform_context is platform_context - - -def test_function_approval_storage_provider_creates_request_scoped_storage() -> None: - with patch("agent_framework_foundry_hosting._state_store.FoundryFunctionApprovalStore") as storage_type: - provider = FunctionApprovalStoreProvider() - config = _config(is_hosted=False) - first_context = _platform_context("call-1") - second_context = _platform_context("call-2") - provider.get_store(config=config, platform_context=first_context) - provider.get_store(config=config, platform_context=second_context) - - assert storage_type.call_args_list[0].args == (first_context,) - assert storage_type.call_args_list[1].args == (second_context,) - - async def test_set_agent_session_uses_scoped_store() -> None: store = _store() session = AgentSession(session_id="agent-session-1") session.state["turn_count"] = 2 with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ) as get_or_create: await FoundryAgentSessionStore(_platform_context()).set("storage-session-1", session) @@ -494,7 +402,7 @@ async def test_set_agent_session_uses_scoped_store() -> None: async def test_agent_session_provider_selects_a_separate_logical_store() -> None: store = _store() with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ) as get_or_create: provider = AgentSessionStoreProvider(store_name="invocation_sessions") @@ -551,7 +459,7 @@ async def test_get_agent_session_returns_deserialized_session() -> None: store.get_item = AsyncMock(return_value=SimpleNamespace(value=session.to_dict(), etag="etag-1")) with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ) as get_or_create: result = await FoundryAgentSessionStore(_platform_context()).get("storage-session-1") @@ -568,7 +476,7 @@ async def test_get_missing_agent_session_returns_none() -> None: store.get_item = AsyncMock(return_value=None) with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ): result = await FoundryAgentSessionStore(_platform_context()).get("missing") @@ -580,7 +488,7 @@ async def test_delete_agent_session_is_idempotent() -> None: store = _store() with patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ): await FoundryAgentSessionStore(_platform_context()).delete("storage-session-1") @@ -619,7 +527,7 @@ def test_agent_session_storage_provider_uses_foundry_store(is_hosted: bool) -> N def test_agent_session_storage_provider_creates_request_scoped_storage() -> None: - with patch("agent_framework_foundry_hosting._state_store.FoundryAgentSessionStore") as storage_type: + with patch("agent_framework_foundry_hosting._shared.FoundryAgentSessionStore") as storage_type: provider = AgentSessionStoreProvider() config = _config(is_hosted=False) first_context = _platform_context("call-1") @@ -631,7 +539,7 @@ def test_agent_session_storage_provider_creates_request_scoped_storage() -> None assert storage_type.call_args_list[1].args == (second_context,) -@pytest.mark.parametrize("provider", ["agent", "checkpoint", "approval"]) +@pytest.mark.parametrize("provider", ["agent", "checkpoint"]) @pytest.mark.parametrize( ("platform_session_id", "request_session_id", "user_id", "call_id"), [ @@ -649,10 +557,8 @@ def test_hosted_store_providers_reject_missing_platform_identity( with pytest.raises(RuntimeError, match="FOUNDRY_AGENT_SESSION_ID|does not match|user ID and call ID"): if provider == "agent": AgentSessionStoreProvider().get_store(config=config, platform_context=context) - elif provider == "checkpoint": - CheckpointStoreProvider().get_store(config=config, context_id="workflow", platform_context=context) else: - FunctionApprovalStoreProvider().get_store(config=config, platform_context=context) + CheckpointStoreProvider().get_store(config=config, context_id="workflow", platform_context=context) async def test_hosted_store_names_partition_sandbox_and_forward_call_id() -> None: @@ -669,7 +575,7 @@ async def get_store(name: str, *, user_isolation: bool) -> MagicMock: _platform_context(call_id="call-2", session_id="other-sandbox"), ] - with patch("agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", new=get_store): + with patch("agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=get_store): for context in contexts: config = _config(is_hosted=True, session_id=context.session_id) sessions = AgentSessionStoreProvider().get_store(config=config, platform_context=context) @@ -678,10 +584,8 @@ async def get_store(name: str, *, user_isolation: bool) -> MagicMock: config=config, context_id="../../conversation", platform_context=context ) await checkpoints.save(_checkpoint("checkpoint-1")) - approvals = FunctionApprovalStoreProvider().get_store(config=config, platform_context=context) - await approvals.save_approval_request("approval-1", _approval_request("approval-1")) - assert len(names) == len(set(names)) == 6 + assert len(names) == len(set(names)) == 4 assert all(name.split("/")[1] == "v2" and len(name) <= 128 for name in names) assert all("user-1" not in name and "sandbox" not in name and "conversation" not in name for name in names) assert {call.kwargs["call_id"] for call in store.create_item.await_args_list} == {"call-1", "call-2"} @@ -704,38 +608,29 @@ async def test_hosted_scope_does_not_read_existing_unscoped_agent_session() -> N assert await legacy.get_item("response-1", call_id=context.call_id) is not None -async def test_hosted_scope_does_not_read_existing_unscoped_checkpoint_or_approval() -> None: +async def test_hosted_scope_does_not_read_existing_unscoped_checkpoint() -> None: context = _platform_context() legacy_checkpoint = await FoundryStateStore.get_or_create("checkpoints/conversation-1", user_isolation=True) - legacy_approval = await FoundryStateStore.get_or_create("function_approvals", user_isolation=True) async with legacy_checkpoint: await legacy_checkpoint.create_item( "checkpoint-1", encode_checkpoint_value(_checkpoint("checkpoint-1").to_dict()), call_id=context.call_id ) - async with legacy_approval: - await legacy_approval.create_item( - "approval-1", _approval_request("approval-1").to_dict(), call_id=context.call_id - ) config = _config(is_hosted=True) checkpoints = CheckpointStoreProvider().get_store( config=config, context_id="conversation-1", platform_context=context ) - approvals = FunctionApprovalStoreProvider().get_store(config=config, platform_context=context) with pytest.raises(WorkflowCheckpointException, match="No checkpoint found"): await checkpoints.load("checkpoint-1") - with pytest.raises(KeyError, match="does not exist"): - await approvals.load_approval_request("approval-1") -async def test_hosted_session_checkpoint_and_approval_data_stay_in_one_sandbox() -> None: +async def test_hosted_session_and_checkpoint_data_stay_in_one_sandbox() -> None: config = _config(is_hosted=True) first_context = _platform_context(session_id="sandbox-1") second_context = _platform_context(session_id="sandbox-2") second_config = _config(is_hosted=True, session_id="sandbox-2") sessions = AgentSessionStoreProvider() checkpoints = CheckpointStoreProvider() - approvals = FunctionApprovalStoreProvider() first_session_store = sessions.get_store(config=config, platform_context=first_context) await first_session_store.set("response-1", AgentSession()) @@ -759,15 +654,6 @@ async def test_hosted_session_checkpoint_and_approval_data_stay_in_one_sandbox() with pytest.raises(WorkflowCheckpointException, match="No checkpoint found"): await second_checkpoint_store.load("checkpoint-1") - first_approval_store = approvals.get_store(config=config, platform_context=first_context) - await first_approval_store.save_approval_request("approval-1", _approval_request("approval-1")) - continued_approval_store = approvals.get_store(config=config, platform_context=continued_context) - assert await continued_approval_store.load_approval_request("approval-1") == _approval_request("approval-1") - second_approval_store = approvals.get_store(config=second_config, platform_context=second_context) - with pytest.raises(KeyError, match="does not exist"): - await second_approval_store.load_approval_request("approval-1") - assert await first_approval_store.load_approval_request("approval-1") == _approval_request("approval-1") - async def test_hosted_session_rejects_a_stale_etag_without_overwriting_the_winner() -> None: config = _config(is_hosted=True) @@ -833,7 +719,7 @@ async def test_loaded_session_without_an_etag_fails_closed() -> None: ) with ( patch( - "agent_framework_foundry_hosting._state_store.FoundryStateStore.get_or_create", + "agent_framework_foundry_hosting._shared.FoundryStateStore.get_or_create", new=AsyncMock(return_value=store), ), pytest.raises(RuntimeError, match="without an ETag"), diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md index 3e88df652e0..1a812e7f6a4 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md @@ -1,8 +1,9 @@ # Custom session storage (Responses protocol) This sample implements custom **MAF agent-session persistence**, including user -and sandbox isolation and optimistic concurrency. The outer Responses store and -function-approval store remain host-managed. This is not a workflow example. +and sandbox isolation and optimistic concurrency. Native approval state is part +of the same `AgentSession` snapshot. The outer Responses store remains +host-managed; there is no separate function-approval store. This is not a workflow example. ## Identity and storage keys