Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
80 commits
Select commit Hold shift + click to select a range
3b82252
Fix Responses route prefix handling
eavanvalkenburg Nov 11, 2026
e76e87e
Harden Foundry host settings and option boundaries
eavanvalkenburg Nov 11, 2026
3c3b592
Merge commit 'e76e87e6de2aca3b37c0614450fc7f30768d7a0b' into foundry-…
eavanvalkenburg Nov 11, 2026
e0243ce
Add conditional session-backed Foundry approval authority
eavanvalkenburg Nov 11, 2026
439847c
Use explicit Responses hosting settings
eavanvalkenburg Nov 11, 2026
bd9e313
Merge commit 'e0243ce5c27e0337b052eae2fada485f573450ed' into foundry-…
eavanvalkenburg Nov 11, 2026
18784b1
Merge commit '696fbc3b5b719ed5385b85f8d5e69ee045e9305f' into foundry-…
eavanvalkenburg Nov 11, 2026
aa0836b
Python: Foundry hosting structured invocation-time OAuth consent and …
eavanvalkenburg Nov 11, 2026
716f830
Python: Remove legacy _validate_response_server_options after build_r…
eavanvalkenburg Nov 11, 2026
72330c8
Distinguish invalid approval controls from backend errors
eavanvalkenburg Nov 11, 2026
4b47b1e
Merge commit '72330c85cb9c877431f8eebc9e6f211a5bd0ba6a' into foundry-…
eavanvalkenburg Nov 11, 2026
d494a2a
Document Foundry hosting support boundaries and add CAS custom storag…
eavanvalkenburg Nov 11, 2026
ce30d6a
Merge commit '716f8308450abcde744c538878d815afe73700d5' into foundry-…
eavanvalkenburg Nov 11, 2026
b773183
Python: Restore _validate_response_server_options steering guard
eavanvalkenburg Nov 11, 2026
2c54461
Document Foundry Toolbox invocation-time OAuth consent behavior
eavanvalkenburg Nov 11, 2026
7d54db8
Remove legacy Foundry function approval store
eavanvalkenburg Nov 11, 2026
68d6308
Merge commit '7d54db8c15885166f7ecd52a7892213782c12a48' into foundry-…
eavanvalkenburg Nov 11, 2026
1b6a15f
Merge commit 'b773183e0' into foundry-responses-integration
eavanvalkenburg Nov 11, 2026
dcd6763
Clarify store=false OAuth consent failure wording
eavanvalkenburg Nov 11, 2026
0991cf6
Strengthen custom storage sample CAS tests
eavanvalkenburg Nov 11, 2026
8038d42
Clarify local custom store provider isolation
eavanvalkenburg Nov 11, 2026
8a71328
Fix native workflow stateless tool ownership
eavanvalkenburg Nov 11, 2026
a761684
Merge commit '8a713288bfd6d08bda8fb86b8ffd60e072e35745' into foundry-…
eavanvalkenburg Nov 11, 2026
191ee4f
Reject wildcard and list revisions in Foundry session CAS
eavanvalkenburg Nov 11, 2026
9d7d0ab
Merge commit '191ee4f9714d61f19cfb69a8bf4edc88d3fe484a' into foundry-…
eavanvalkenburg Nov 11, 2026
3520a8f
Harden custom Cosmos approval CAS sample
eavanvalkenburg Nov 11, 2026
0556e37
Merge commit '3520a8f006d4c3937e2fdc5b89f81f6a04ac129f' into foundry-…
eavanvalkenburg Nov 11, 2026
5d36417
Clarify workflow tool ownership guidance
eavanvalkenburg Nov 11, 2026
5a2bf84
Validate provider background after hosted agent middleware
eavanvalkenburg Nov 11, 2026
5949039
Merge commit '5a2bf847c6f041f2dc42a18b8c5dcc3038f1c07c' into foundry-…
eavanvalkenburg Nov 11, 2026
dd9c10e
Withdraw unagreed provider-background middleware guard
eavanvalkenburg Nov 11, 2026
02f1f99
Clarify scope of custom Cosmos storage prerequisite
eavanvalkenburg Nov 11, 2026
3cc4905
Restore agreed background guard and test RawAgent middleware
eavanvalkenburg Nov 11, 2026
11dd8cd
Merge native background guard qualification
eavanvalkenburg Nov 11, 2026
dfeebfe
Merge commit '11dd8cd715d616333dfd12a08' into foundry-docs-rc-qualifi…
eavanvalkenburg Nov 11, 2026
2a240d3
Reconcile Foundry hosting background and steering docs
eavanvalkenburg Nov 11, 2026
84d15e8
Fix consent test typing and use atomic session store in Toolbox appro…
eavanvalkenburg Nov 11, 2026
3daab6f
Merge consent and approval test fixes
eavanvalkenburg Nov 11, 2026
1687482
Wire Responses approval and consent lifecycle
eavanvalkenburg Nov 11, 2026
5bc075d
Merge commit '1687482388085f7f55fbb17570a64d5fd8b56f4b' into foundry-…
eavanvalkenburg Nov 11, 2026
0cc33bf
docs: reconcile final Foundry hosting contracts and samples
eavanvalkenburg Nov 11, 2026
4c50dcb
Remove legacy Invocations wire format
eavanvalkenburg Nov 11, 2026
8e2738c
Merge commit '4c50dcb8f867f0ab81f3744ad77306d2a059d9be' into foundry-…
eavanvalkenburg Nov 11, 2026
b8a8f8d
docs: remove legacy Invocations wire format guidance
eavanvalkenburg Nov 11, 2026
e9b0884
Merge commit 'b8a8f8d6033963f4fb8a7b9af617ad84c55bade3' into foundry-…
eavanvalkenburg Nov 11, 2026
3d0afc8
Format Invocations tests
eavanvalkenburg Nov 11, 2026
d7d7594
Merge commit '3d0afc855f1347fe82f04359bceef10bf5864a15' into foundry-…
eavanvalkenburg Nov 11, 2026
55d3875
Remove unused Responses options validator
eavanvalkenburg Nov 11, 2026
067e121
Unify hosting background middleware guards
eavanvalkenburg Nov 11, 2026
d7470ef
Unify invalid approval preflight errors
eavanvalkenburg Nov 11, 2026
29e01d6
Validate approval history once per preflight
eavanvalkenburg Nov 11, 2026
e9ecd8a
Centralize deferred response event buffering
eavanvalkenburg Nov 11, 2026
2975070
Consolidate redundant storage and steering tests
eavanvalkenburg Nov 11, 2026
dbbb27d
Remove repeated hosting guidance
eavanvalkenburg Nov 11, 2026
75369c7
Preserve approval preflight error boundaries
eavanvalkenburg Nov 11, 2026
4d083b0
Preserve typed background guard dispatch
eavanvalkenburg Nov 11, 2026
20277b1
Remove unused workflow approval lookup
eavanvalkenburg Nov 11, 2026
8f54303
Remove approval lookup protocol
eavanvalkenburg Nov 11, 2026
4cb7d15
Clarify factory resource lifecycle limits
eavanvalkenburg Nov 11, 2026
e1845b3
Merge approval lookup removal
eavanvalkenburg Nov 11, 2026
0bf85c9
Python: Remove CAS approval authority; keep session approval request map
eavanvalkenburg Nov 11, 2026
a91b6ea
Merge commit '0bf85c998' into foundry-responses-integration
eavanvalkenburg Nov 11, 2026
8925c74
Python: Update approval translation tests for session request map
eavanvalkenburg Nov 11, 2026
6a8e170
Merge commit '8925c7488' into foundry-responses-integration
eavanvalkenburg Nov 11, 2026
e247c0c
Python: Use Core session approvals and workflow request_info for Foun…
eavanvalkenburg Nov 11, 2026
5806acc
Python: Remove Responses legacy parser compatibility guard
eavanvalkenburg Nov 11, 2026
15adafd
Make caller generation options opt-in
eavanvalkenburg Nov 11, 2026
4fbb4a9
Merge caller generation options opt-in
eavanvalkenburg Nov 11, 2026
bde8bbe
Fix stale Invocations host guard tests
eavanvalkenburg Nov 11, 2026
391e695
Merge Invocations routing guard follow-up
eavanvalkenburg Nov 11, 2026
db4b065
Python: Opt in to caller options in Responses hosting
eavanvalkenburg Nov 11, 2026
7d92c28
Python: Keep Responses removed-setting guard with opt-in options
eavanvalkenburg Nov 11, 2026
df055c7
Revert "Python: Keep Responses removed-setting guard with opt-in opti…
eavanvalkenburg Nov 11, 2026
e357eac
Python: pass Invocations hook background through without middleware g…
eavanvalkenburg Nov 11, 2026
a76223a
Merge commit 'e357eac1354380d679ab288ec461301717553323' into foundry-…
eavanvalkenburg Nov 11, 2026
6949d93
Python: remove stale Invocations setting guards
eavanvalkenburg Nov 11, 2026
46ffffa
Python: preserve application background options without middleware guard
eavanvalkenburg Nov 11, 2026
12dfb38
Merge commit '46ffffafd17b12bbf03193f6d3600106276b8023' into foundry-…
eavanvalkenburg Nov 11, 2026
a38be7b
Python: split Foundry hosting into four concrete hosts
eavanvalkenburg Nov 11, 2026
cb8d8a7
Python: describe current Responses workflow options in sample
eavanvalkenburg Nov 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 73 additions & 27 deletions docs/decisions/0055-python-foundry-hosting-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,29 +37,31 @@ Choose separate agent and native workflow hosts. Share protocol internals, but k
configuration, and state ownership specific to each execution model.

The decisions below define the intended hosting contracts, not the implementation status of each feature.
See the [Foundry Hosting README](../../python/packages/foundry_hosting/README.md) for the current usage contract.

### Host boundaries

Use `ResponsesHostServer` and `InvocationsHostServer` for agents, and
`ResponsesWorkflowHostServer` and `InvocationsWorkflowHostServer` for native workflows.
Agent hosts reject `WorkflowAgent`; workflow hosts require a factory returning a native `Workflow`.
Do not silently unwrap agents, migrate their state, or retain a combined-host compatibility shim.
Do not silently unwrap agents or migrate their state.

Workflow hosts expose checkpoint storage rather than agent-session storage or agent history settings.
The Responses workflow host owns native execution directly. Share the Invocations engine between its
public hosts rather than duplicating it. Group each protocol into agent, workflow, and shared modules,
with cross-protocol request contracts and factory resolution in a central shared module.
Each of the four hosts owns its own construction, execution, and validation. Do not route agent and workflow
execution through a shared host with mode switches; that couples their validation rules. Group each protocol into
agent and workflow modules. Shared modules hold only protocol-neutral utilities, such as request contracts,
factory resolution, and SSE framing.

Keep all hosts in one package. Responses is the initial stable-surface target; Invocations and Toolbox
remain experimental. Separate classes do not require separate distribution packages.

### Request adaptation and construction

Use `parse_input` for custom input adaptation across both protocols. Agent parsers return `InvocationRun`;
workflow parsers return `WorkflowTurn` containing either typed start input or complete pending replies.
Parsing does not replace the host's checkpoint and pending-authority validation.
workflow parsers return `WorkflowTurn` containing either typed start input or pending replies. Workflow hosts
always require a parser; there is no default input conversion.
Parsing does not replace the host's checkpoint binding or the workflow runtime's reply validation.
Use `ResponsesRequest` for the Responses wrapper, including factory and option-hook inputs.
Do not retain aliases for the former parser keywords or request-type name.

Agent hosts accept an instance or a sync/async factory implementing a named-request callable protocol.
Factories must declare a required `request` parameter and are called as `factory(request=request)`.
Expand All @@ -73,19 +75,31 @@ before `prepare_options`. Invocations agent factories receive the Starlette `Req
and option preparation. Preserve these protocol-specific timings rather than forcing identical signatures
or inventing a shared options-precedence policy.

By default, agent hosts forward only the caller's messages. Do not forward caller generation settings; the
agent's own `default_options` apply unchanged, together with host-owned storage/background controls. An
optional `prepare_options` callable on agent hosts is the opt-in customization path; forward only its returned,
validated mapping. This does not prevent application code from inspecting the original request. Responses
agent factories see translated options before the hook. Workflow hosts have no option hook: the parser forwards
model options explicitly through `WorkflowTurn` client kwargs.

Native workflow factories are request-aware and must allocate fresh workflows, executors, agents,
clients, providers, and mutable tools. A new graph wrapper around shared executors is not isolation.
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.

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.
Unwind successfully entered factory-agent contexts when a request finishes, fails, or is cancelled.
`Agent` also unwinds client and MCP contexts already entered if a later context fails to enter.
Allocations before agent entry and partial allocations from a failed client `__aenter__` may not be
cleaned up; calling `agent.close()` before entry does not dispose an unentered client.
Applications own cleanup of other resources they create. An entered caller-supplied context-managed
client can be closed on agent exit; ownership depends on its context contract, and the host cannot
reliably identify shared clients on first use. State needed across requests belongs in supported stores,
not request-owned instance fields.

### Persistence and history ownership

Regular agents continue through agent-session storage. Native workflows continue through their exact
scoped checkpoints, including pending-reply authority. Neither execution model converts the other's state.
scoped checkpoints, including pending `request_info` requests. Neither execution model converts the other's state.
Native workflow agents use checkpoint-owned history, not private inference-service continuation.

Keep three storage decisions distinct:
Expand All @@ -96,20 +110,34 @@ Keep three storage decisions distinct:

Use `history_source="host_managed"` by default, with `"agent_managed"` and `"inference_service"`
as explicit alternatives. `agent_managed` permits developer-owned history providers or downstream
service storage; it is not restricted to `HistoryProvider`. Remove the constructor `store=` alias,
including acceptance of `None`, without changing the wire flag or downstream storage controls.
service storage; it is not restricted to `HistoryProvider`. The constructor selects the backend only through
`response_store`; this does not change the wire flag or downstream storage controls.

### Background execution and recovery

Treat outer background execution, inner inference-service background execution, and recovery permission
as separate controls. Use `background_source="host_managed"` by default. Retain `"inference_service"`
for supported regular agents with inference-service history and outer-background passthrough.
Reject hidden provider background under an outer foreground request.
Validate hosting-visible agent and factory defaults against the selected background mode.

Outer workflow background must not enable background on constituent agents. Native inner provider
background is unsupported. Do not introduce a per-agent workflow-host background switch.
Recovery permission neither selects an execution mode nor guarantees exactly-once external side effects.

For regular Responses and Invocations agents, allow an application options hook to select `background`;
the application owns that choice. Ordinary Responses agent runs preserve hook-selected values. When the host
explicitly selects provider background, retain `background=True` for submission and polling even if the hook
returns `False`. Hook-selected background alone does not enable host-managed polling or recovery. Invocations
does not inject an outer background value.

Do not inject background-specific enforcement middleware or add a Core interception hook. Application agent/chat
middleware owns its changes to background options. Keep validation of caller envelope fields, hook results
other than the agent hook's background choice, and developer defaults before execution. Reject nested caller
`extra_body.background` before the Responses hook. Native workflow option hooks cannot select inner provider
background; make native `WorkflowTurn` reject client-level and run-level middleware. The existing native agent
options middleware still validates transport controls, storage, and unfinished provider responses to preserve
checkpoint ownership; it is not the removed background-specific guard.

### Supported host settings

Expose supported first-class settings and construct SDK options internally, without another framework
Expand All @@ -134,28 +162,45 @@ 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.

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.
Use the framework's built-in approval handling and do not add a host approval authority.
Regular agents keep pending approval requests in the same `AgentSession` that the host loads and saves through
the configured session store. Core binds each approval response to a recorded pending request, rebuilds the call
from that request, and consumes it. The host stores only a translation map from the SDK-generated wire item ID to
the original request in that session's state. This map does not authorize execution. Native workflows use
`request_info` and their exact checkpoint; the host translates wire IDs to request IDs in its checkpoint binding.
There is no separate public approval-store API, no conditional-write capability for custom session stores, and no
import of approvals recorded outside session state.

Do not preflight approval replies before the response starts. The host drops a reply with an unknown wire ID
with a warning, and the framework does not execute a reply that matches no pending request. A turn whose input
contains only dropped replies fails. Partial batches follow the framework: an agent holds the batch until every
request has a reply, and a workflow runs the answered requests. Responses hosts emit requests that are still
pending again under new wire IDs; Invocations workflows keep their request IDs. A batch may mix approvals and rejections. A workflow reply that the runtime rejects before its first superstep releases the
lineage head unchanged; a failure after a superstep starts blocks that lineage. Concurrent replies, forks, and
retries have the same guarantees as any agent run with a shared session or any workflow checkpoint resume.
No path provides exactly-once external side effects.

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
later protected calls. Require `store=true` so continuation can retain the required state;
do not support ephemeral consent under `store=false`.
Buffer consent and approval output until the session snapshots are saved. Invocation-time consent with
inference-service history is unsupported and fails explicitly; connection-time consent remains separate.
A consent failure after execution starts is a failed response, not a pre-header HTTP 400.

### Caller options

Preserve protocol-specific option ordering. Responses translates generation fields before factory resolution
and its hook; Invocations parses and applies its hook before factory resolution. Deep-copy per-run hook input
and replacement mappings without changing developer defaults. Protect hosting and execution controls after
the hook, and reject those controls inside nested transport options. The host split does not authorize
removing existing hooks or applying workflow-only assumptions to regular agents.

### Unresolved boundaries

Do not infer a single-target restriction or a multi-target router without a documented Foundry platform
contract. Request `model` is not implicitly an agent selector.

Broader option precedence and validation details require separate design. The host split does not
authorize removing existing hooks or applying workflow-only assumptions to regular agents.

Keep current dependency requirements and the steering guard until published-wheel compatibility and
concurrent queue-overflow behavior are verified. An upstream merge alone is not release evidence.
These decisions do not redesign Core, concurrency, checkpoints, retries, or external exactly-once execution.
Expand All @@ -165,13 +210,14 @@ These decisions do not redesign Core, concurrency, checkpoints, retries, or exte
- Public signatures identify execution models and their state owners.
- Shared internals avoid duplicate engines without obscuring public contracts.
- Request-aware factories support identity-dependent resources but require deliberate isolation and cleanup.
- The API migration breaks combined-host construction, wrapper hosting, unnamed or zero-argument agent factories, old parser/request names, source literals, and the storage-backend alias.
- Agent and workflow hosts have separate constructors and validation; wrapper hosting and unnamed or zero-argument agent factories are not supported.
- Settings, authority, and consent changes require their own implementation and correctness validation; recording a decision does not establish that it has shipped.

## Validation

Cover public imports and signatures, invalid construction before SDK side effects, sync/async factory
invocation, failure/cancellation cleanup, and rejection of shared workflow resources.
invocation, cleanup of successfully entered contexts on failure/cancellation, and rejection of shared
workflow resources.
Exercise streaming and non-streaming execution, session/checkpoint continuation, pending replies,
and model-free process crash/recovery. Validate maintained samples against public exports.
Offline checks do not establish live Foundry deployment compatibility.
Loading
Loading