fix: align session and resource contracts with QCA docs

Author: moonyue-w

CHANGELOG.md

@@ -5,6 +5,23 @@ existing `0.1.0` release; earlier development prereleases are not listed.
 
 ## [Unreleased]
 
+### Added
+
+- Add typed Forward Session budgets across create/update responses and events, including omission, explicit null clearing and decimal-string limits.
+- Add Forward Session `config.model` overrides and model `speed` configuration, plus optional approval evaluation details, Outcome/status event fields and cumulative top-level Credits on `session.usage`.
+- Add `startup_script` to Forward/Managed Environment models and Managed cloud/self-hosted parameters. It runs on sandbox start/resume; the external worker controls self-hosted execution.
+- Add Managed Memory `version`, version `redacted`, and Vault creation-response `credentials` fields. Vault creation still does not accept credentials in its request.
+
+### Fixed
+
+- Declare Managed Memory list-item metadata/version fields so strict response parsing provides typed access instead of unknown attributes.
+
+### Migration
+
+- Forward `sessions.create()` and `sessions.update()` accept `budget=` directly. Omit it to keep the default/current limit, or pass `None` to clear it.
+- Omit `config.model` on create to inherit; `{"model": None}` restores inheritance on update. Optional approval details are under `event.evaluation.evaluated_permission`; the top-level approval result remains a string, with legacy object parsing retained for compatibility.
+- Managed Thread `usage` is deprecated because current responses omit it; read Session Credits instead. Treat `session.usage` as cumulative snapshots rather than adding successive events.
+
 ### Changed
 
 - Remove resource-specific sections and inventories from the README to keep it focused on SDK setup and shared client behavior.

docs/api/reference.md

@@ -8500,6 +8500,7 @@ def create(
         *,
         identity_id: str,
         template_id: str,
+        budget: Union[BudgetLimitParam, None, NotGiven] = NOT_GIVEN,
         title: Union[str, None, NotGiven] = NOT_GIVEN,
         metadata: Union[Dict[str, Any], None, NotGiven] = NOT_GIVEN,
         config: Union[SessionCreateParamsConfigParam, None,
@@ -8545,6 +8546,7 @@ GET /sessions/{session_id}.
 def update(
         session_id: str,
         *,
+        budget: Union[BudgetLimitParam, None, NotGiven] = NOT_GIVEN,
         title: Union[str, None, NotGiven] = NOT_GIVEN,
         metadata: Union[Dict[str, Any], None, NotGiven] = NOT_GIVEN,
         config: Union[SessionUpdateParamsConfigParam, None,
@@ -8688,6 +8690,7 @@ async def create(
         *,
         identity_id: str,
         template_id: str,
+        budget: Union[BudgetLimitParam, None, NotGiven] = NOT_GIVEN,
         title: Union[str, None, NotGiven] = NOT_GIVEN,
         metadata: Union[Dict[str, Any], None, NotGiven] = NOT_GIVEN,
         config: Union[SessionCreateParamsConfigParam, None,
@@ -8733,6 +8736,7 @@ GET /sessions/{session_id}.
 async def update(
         session_id: str,
         *,
+        budget: Union[BudgetLimitParam, None, NotGiven] = NOT_GIVEN,
         title: Union[str, None, NotGiven] = NOT_GIVEN,
         metadata: Union[Dict[str, Any], None, NotGiven] = NOT_GIVEN,
         config: Union[SessionUpdateParamsConfigParam, None,
@@ -11575,6 +11579,50 @@ class BatchUsage(BaseModel)
 
 #### total\_credits
 
+<a id="qca.forward.types.budget_limit"></a>
+
+# qca.forward.types.budget\_limit
+
+<a id="qca.forward.types.budget_limit.BudgetLimit"></a>
+
+## BudgetLimit
+
+```python
+class BudgetLimit(BaseModel)
+```
+
+[[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/budget_limit.py)
+
+<a id="qca.forward.types.budget_limit.BudgetLimit.max_credit_cost"></a>
+
+#### max\_credit\_cost
+
+<a id="qca.forward.types.budget_limit.BudgetLimit.type"></a>
+
+#### type
+
+<a id="qca.forward.types.budget_limit_param"></a>
+
+# qca.forward.types.budget\_limit\_param
+
+<a id="qca.forward.types.budget_limit_param.BudgetLimitParam"></a>
+
+## BudgetLimitParam
+
+```python
+class BudgetLimitParam(TypedDict)
+```
+
+[[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/budget_limit_param.py)
+
+<a id="qca.forward.types.budget_limit_param.BudgetLimitParam.max_credit_cost"></a>
+
+#### max\_credit\_cost
+
+<a id="qca.forward.types.budget_limit_param.BudgetLimitParam.type"></a>
+
+#### type
+
 <a id="qca.forward.types.channel"></a>
 
 # qca.forward.types.channel
@@ -13496,6 +13544,10 @@ class EnvironmentConfig(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/environment_config.py)
 
+<a id="qca.forward.types.environment_config.EnvironmentConfig.startup_script"></a>
+
+#### startup\_script
+
 <a id="qca.forward.types.environment_config.EnvironmentConfig.setup_script"></a>
 
 #### setup\_script
@@ -15444,6 +15496,10 @@ class ModelConfig(BaseModel)
 
 #### effort
 
+<a id="qca.forward.types.model_config.ModelConfig.speed"></a>
+
+#### speed
+
 <a id="qca.forward.types.model_config.ModelConfig.context_window"></a>
 
 #### context\_window
@@ -15470,6 +15526,10 @@ class ModelConfigParam(TypedDict)
 
 #### effort
 
+<a id="qca.forward.types.model_config_param.ModelConfigParam.speed"></a>
+
+#### speed
+
 <a id="qca.forward.types.model_config_param.ModelConfigParam.context_window"></a>
 
 #### context\_window
@@ -17360,6 +17420,10 @@ class Session(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/session.py)
 
+<a id="qca.forward.types.session.Session.budget"></a>
+
+#### budget
+
 <a id="qca.forward.types.session.Session.outcome_evaluations"></a>
 
 #### outcome\_evaluations
@@ -17474,6 +17538,10 @@ class SessionConfig(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/session_config.py)
 
+<a id="qca.forward.types.session_config.SessionConfig.model"></a>
+
+#### model
+
 <a id="qca.forward.types.session_config.SessionConfig.environment_variables"></a>
 
 #### environment\_variables
@@ -17492,6 +17560,10 @@ class SessionCreateParams(TypedDict)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/session_create_params.py)
 
+<a id="qca.forward.types.session_create_params.SessionCreateParams.budget"></a>
+
+#### budget
+
 <a id="qca.forward.types.session_create_params.SessionCreateParams.identity_id"></a>
 
 #### identity\_id
@@ -17534,6 +17606,10 @@ class SessionCreateParamsConfigParam(TypedDict)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/session_create_params_config_param.py)
 
+<a id="qca.forward.types.session_create_params_config_param.SessionCreateParamsConfigParam.model"></a>
+
+#### model
+
 <a id="qca.forward.types.session_create_params_config_param.SessionCreateParamsConfigParam.environment_variables"></a>
 
 #### environment\_variables
@@ -17552,6 +17628,42 @@ class SessionEvent(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/session_event.py)
 
+<a id="qca.forward.types.session_event.SessionEvent.evaluation"></a>
+
+#### evaluation
+
+<a id="qca.forward.types.session_event.SessionEvent.budget"></a>
+
+#### budget
+
+<a id="qca.forward.types.session_event.SessionEvent.reason"></a>
+
+#### reason
+
+<a id="qca.forward.types.session_event.SessionEvent.iteration"></a>
+
+#### iteration
+
+<a id="qca.forward.types.session_event.SessionEvent.explanation"></a>
+
+#### explanation
+
+<a id="qca.forward.types.session_event.SessionEvent.outcome_evaluation_start_id"></a>
+
+#### outcome\_evaluation\_start\_id
+
+<a id="qca.forward.types.session_event.SessionEvent.model_credits"></a>
+
+#### model\_credits
+
+<a id="qca.forward.types.session_event.SessionEvent.sandbox_runtime_credits"></a>
+
+#### sandbox\_runtime\_credits
+
+<a id="qca.forward.types.session_event.SessionEvent.total_credits"></a>
+
+#### total\_credits
+
 <a id="qca.forward.types.session_event.SessionEvent.id"></a>
 
 #### id
@@ -18398,6 +18510,10 @@ class SessionUpdateParams(TypedDict)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/session_update_params.py)
 
+<a id="qca.forward.types.session_update_params.SessionUpdateParams.budget"></a>
+
+#### budget
+
 <a id="qca.forward.types.session_update_params.SessionUpdateParams.title"></a>
 
 #### title
@@ -18428,6 +18544,10 @@ class SessionUpdateParamsConfigParam(TypedDict)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/session_update_params_config_param.py)
 
+<a id="qca.forward.types.session_update_params_config_param.SessionUpdateParamsConfigParam.model"></a>
+
+#### model
+
 <a id="qca.forward.types.session_update_params_config_param.SessionUpdateParamsConfigParam.environment_variables"></a>
 
 #### environment\_variables
@@ -19420,6 +19540,50 @@ class Tool(BaseModel)
 
 #### input\_schema
 
+<a id="qca.forward.types.tool_approval_evaluation"></a>
+
+# qca.forward.types.tool\_approval\_evaluation
+
+<a id="qca.forward.types.tool_approval_evaluation.ToolApprovalDecision"></a>
+
+## ToolApprovalDecision
+
+```python
+class ToolApprovalDecision(BaseModel)
+```
+
+[[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/tool_approval_evaluation.py)
+
+Automatic decision; reason_code may be indeterminate or high_risk.
+
+<a id="qca.forward.types.tool_approval_evaluation.ToolApprovalDecision.type"></a>
+
+#### type
+
+<a id="qca.forward.types.tool_approval_evaluation.ToolApprovalDecision.reason_code"></a>
+
+#### reason\_code
+
+<a id="qca.forward.types.tool_approval_evaluation.ToolApprovalEvaluation"></a>
+
+## ToolApprovalEvaluation
+
+```python
+class ToolApprovalEvaluation(BaseModel)
+```
+
+[[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/types/tool_approval_evaluation.py)
+
+Policy source (always_allow, always_ask, auto) and optional automatic decision.
+
+<a id="qca.forward.types.tool_approval_evaluation.ToolApprovalEvaluation.type"></a>
+
+#### type
+
+<a id="qca.forward.types.tool_approval_evaluation.ToolApprovalEvaluation.evaluated_permission"></a>
+
+#### evaluated\_permission
+
 <a id="qca.forward.types.tool_config"></a>
 
 # qca.forward.types.tool\_config
@@ -28217,6 +28381,10 @@ class CloudConfigParams(TypedDict)
 
 #### storage
 
+<a id="qca.managed.types.cloud_config_params.CloudConfigParams.startup_script"></a>
+
+#### startup\_script
+
 <a id="qca.managed.types.cloud_config_params.CloudConfigParams.setup_script"></a>
 
 #### setup\_script
@@ -30301,6 +30469,10 @@ class EnvironmentConfigUnion(BaseModel)
 
 #### storage
 
+<a id="qca.managed.types.environment_config_union.EnvironmentConfigUnion.startup_script"></a>
+
+#### startup\_script
+
 <a id="qca.managed.types.environment_config_union.EnvironmentConfigUnion.setup_script"></a>
 
 #### setup\_script
@@ -31939,6 +32111,10 @@ class Memory(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/managed/types/memory.py)
 
+<a id="qca.managed.types.memory.Memory.version"></a>
+
+#### version
+
 <a id="qca.managed.types.memory.Memory.metadata"></a>
 
 #### metadata
@@ -31997,6 +32173,14 @@ class MemoryListItemUnion(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/managed/types/memory_list_item_union.py)
 
+<a id="qca.managed.types.memory_list_item_union.MemoryListItemUnion.metadata"></a>
+
+#### metadata
+
+<a id="qca.managed.types.memory_list_item_union.MemoryListItemUnion.version"></a>
+
+#### version
+
 <a id="qca.managed.types.memory_list_item_union.MemoryListItemUnion.id"></a>
 
 #### id
@@ -32665,6 +32849,10 @@ class MemoryVersion(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/managed/types/memory_version.py)
 
+<a id="qca.managed.types.memory_version.MemoryVersion.redacted"></a>
+
+#### redacted
+
 <a id="qca.managed.types.memory_version.MemoryVersion.id"></a>
 
 #### id
@@ -33707,6 +33895,10 @@ class SelfHostedConfigParams(TypedDict)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/managed/types/self_hosted_config_params.py)
 
+<a id="qca.managed.types.self_hosted_config_params.SelfHostedConfigParams.startup_script"></a>
+
+#### startup\_script
+
 <a id="qca.managed.types.self_hosted_config_params.SelfHostedConfigParams.setup_script"></a>
 
 #### setup\_script
@@ -36195,6 +36387,8 @@ class SessionThreadUsage(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/managed/types/session_thread_usage.py)
 
+Deprecated legacy Token/list-cost usage; current Thread responses omit it.
+
 <a id="qca.managed.types.session_thread_usage.SessionThreadUsage.active_seconds"></a>
 
 #### active\_seconds
@@ -37967,6 +38161,10 @@ class Vault(BaseModel)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/managed/types/vault.py)
 
+<a id="qca.managed.types.vault.Vault.credentials"></a>
+
+#### credentials
+
 <a id="qca.managed.types.vault.Vault.id"></a>
 
 #### id