fix(api)!: align session credits, identity scope, and pairing

CHANGELOG.md

@@ -5,6 +5,20 @@ existing `0.1.0` release; earlier development prereleases are not listed.
 
 ## [Unreleased]
 
+### Fixed
+
+- Align Managed Session budgets with the official decimal-string `max_credit_cost` contract, shared by Deployment budgets. The limit covers cumulative model and sandbox Credits; reaching it rejects the next user message without interrupting the current turn.
+- Expose Managed and Forward Session `model_credits`, `sandbox_runtime_credits`, and `total_credits`; decode top-level `session.usage` Credits and per-call `model_usage.credits` / compaction `usage.credits`. Session usage may be absent. Legacy response token/list-cost fields remain available.
+- Route Identity ownership through query parameters on existing Forward Environment, Skill/Version, Vault/Credential, and File operations, including multipart uploads and content downloads.
+- Allow existing channel pairing creation with either a code or `channel_pairing_id`, and expose pairing scope details. No additional API endpoints are introduced.
+
+### Migration
+
+- **Breaking budget field change:** Replace `{ type: "limit", max_list_cost: {...} }` with `{ type: "limit", max_credit_cost: "100.00" }`. Amounts are positive decimal strings, not currency objects. Omitting a budget update preserves the limit; explicit null removes it.
+- Consume the three top-level Credits fields from `session.usage` events. Replace cumulative snapshots rather than adding them; compaction Credits are already included in Session totals.
+- Set `identity_id` in resource params; for methods without params, set it in the existing request-options argument. Use this only with a PAT. With a SAT, omit `identity_id`; the server infers ownership from the token and rejects explicit values (including an empty string).
+- Channel pairing requests must provide exactly one of `code` or `channel_pairing_id`; existing code-based calls remain supported.
+
 ## [0.6.0]
 
 ### Added

docs/api/forward/README.md

@@ -251,6 +251,7 @@
 - [EventContentUnionParam](type-aliases/EventContentUnionParam.md)
 - [ForwardClientOptions](type-aliases/ForwardClientOptions.md)
 - [IdentityCreateParams](type-aliases/IdentityCreateParams.md)
+- [IdentityScopeOptions](type-aliases/IdentityScopeOptions.md)
 - [MemoryStoreCreateParams](type-aliases/MemoryStoreCreateParams.md)
 - [MemoryStoreMemoryCreateParams](type-aliases/MemoryStoreMemoryCreateParams.md)
 - [ModelConfig](type-aliases/ModelConfig.md)

docs/api/forward/classes/Environments.md

@@ -56,7 +56,7 @@ Archive an environment retained by historical sessions or tool calls.
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -108,7 +108,7 @@ createEnvironment
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -160,7 +160,7 @@ listEnvironment
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 

docs/api/forward/classes/Files.md

@@ -56,7 +56,7 @@
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -82,7 +82,7 @@ deleteFile
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -108,7 +108,7 @@ downloadFile
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 

docs/api/forward/classes/SkillVersions.md

@@ -90,7 +90,7 @@ createSkillVersion
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -120,7 +120,7 @@ deleteSkillVersion
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -180,7 +180,7 @@ listSkillVersion
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 

docs/api/forward/classes/Skills.md

@@ -88,7 +88,7 @@ createSkill
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 

docs/api/forward/classes/VaultCredentials.md

@@ -90,7 +90,7 @@ createVaultCredential
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -150,7 +150,7 @@ listVaultCredential
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 

docs/api/forward/classes/Vaults.md

@@ -88,7 +88,7 @@ createVault
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 
@@ -140,7 +140,7 @@ listVault
 
 ##### options?
 
-[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
 
 #### Returns
 

docs/api/forward/interfaces/ChannelPairing.md

@@ -22,6 +22,12 @@ Channel ID。
 
 ***
 
+### created\_at?
+
+> `optional` **created\_at?**: `string`
+
+***
+
 ### id
 
 > **id**: `string`
@@ -46,6 +52,24 @@ Pairing ID，解除配对时使用。
 
 ***
 
+### scope\_display\_name
+
+> **scope\_display\_name**: `string`
+
+***
+
+### scope\_external\_id
+
+> **scope\_external\_id**: `string`
+
+***
+
+### scope\_type
+
+> **scope\_type**: `string`
+
+***
+
 ### status
 
 > **status**: `string`
@@ -67,3 +91,9 @@ Pairing ID，解除配对时使用。
 > **type**: `string`
 
 固定为 `channel_pairing`。
+
+***
+
+### updated\_at?
+
+> `optional` **updated\_at?**: `string`

docs/api/forward/interfaces/ChannelPairingNewParams.md

@@ -14,11 +14,19 @@ Additional fields are preserved verbatim by the SDK.
 
 ## Properties
 
-### code
+### channel\_pairing\_id?
 
-> **code**: `string`
+> `optional` **channel\_pairing\_id?**: `string`
 
-Channel 消息中显示的 6 位配对码。
+Pending pairing ID. Supply exactly one of code or channel_pairing_id.
+
+***
+
+### code?
+
+> `optional` **code?**: `string`
+
+Channel 消息中的配对码；与 channel_pairing_id 二选一。
 
 ***
 

docs/api/forward/interfaces/EnvironmentListParams.md

@@ -30,6 +30,14 @@ Additional fields are preserved verbatim by the SDK.
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### limit?
 
 > `optional` **limit?**: `number` \| `null`

docs/api/forward/interfaces/EnvironmentNewParams.md

@@ -38,6 +38,14 @@ Environment 运行时配置对象；省略时默认使用 `{"type":"cloud"}`。
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### metadata?
 
 > `optional` **metadata?**: `Record`\<`string`, `unknown`\> \| `null`

docs/api/forward/interfaces/EnvironmentUpdateParams.md

@@ -30,6 +30,14 @@ Additional fields are preserved verbatim by the SDK.
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### metadata?
 
 > `optional` **metadata?**: `Record`\<`string`, `unknown`\> \| `null`

docs/api/forward/interfaces/FileListParams.md

@@ -30,6 +30,14 @@ Additional fields are preserved verbatim by the SDK.
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### limit?
 
 > `optional` **limit?**: `number` \| `null`

docs/api/forward/interfaces/FileUploadParams.md

@@ -30,6 +30,14 @@ Additional fields are preserved verbatim by the SDK.
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### metadata?
 
 > `optional` **metadata?**: `Record`\<`string`, `unknown`\> \| `null`

docs/api/forward/interfaces/Session.md

@@ -110,6 +110,6 @@ Template 摘要。
 
 ***
 
-### usage
+### usage?
 
-> **usage**: [`SessionUsage`](SessionUsage.md)
+> `optional` **usage?**: [`SessionUsage`](SessionUsage.md)

docs/api/forward/interfaces/SessionUsage.md

@@ -14,6 +14,18 @@ Additional fields are preserved verbatim by the SDK.
 
 ## Properties
 
+### model\_credits?
+
+> `optional` **model\_credits?**: `number`
+
+***
+
+### sandbox\_runtime\_credits?
+
+> `optional` **sandbox\_runtime\_credits?**: `number`
+
+***
+
 ### total\_credits
 
 > **total\_credits**: `number`

docs/api/forward/interfaces/SkillGetParams.md

@@ -14,6 +14,14 @@ Additional fields are preserved verbatim by the SDK.
 
 ## Properties
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### include\_content?
 
 > `optional` **include\_content?**: `boolean` \| `null`

docs/api/forward/interfaces/SkillListParams.md

@@ -38,6 +38,14 @@ Additional fields are preserved verbatim by the SDK.
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### limit?
 
 > `optional` **limit?**: `number` \| `null`

docs/api/forward/interfaces/SkillNewParams.md

@@ -54,6 +54,14 @@ Forward Resource icon 公开 ID。
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### metadata?
 
 > `optional` **metadata?**: `Record`\<`string`, `unknown`\> \| `null`

docs/api/forward/interfaces/SkillUpdateParams.md

@@ -46,6 +46,14 @@ Additional fields are preserved verbatim by the SDK.
 
 ***
 
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+Select identity ownership with a PAT. Omit when using a SAT.
+
+***
+
 ### metadata?
 
 > `optional` **metadata?**: `Record`\<`string`, `unknown`\> \| `null`