Skip to content

Commit bd05c81

Browse files
moonyue-wmoonyue-w
authored
fix(api)!: align credits, ownership, and pairing contracts (#23)
Match QCA Session budget and usage schemas, route Forward identity ownership through query parameters, and support pairing by record ID. Include wire contract and public type tests, generated references, and migration notes. BREAKING CHANGE: replace max_list_cost currency objects with max_credit_cost decimal strings.
1 parent 597ff04 commit bd05c81

61 files changed

Lines changed: 911 additions & 171 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,20 @@ existing `0.1.0` release; earlier development prereleases are not listed.
55

66
## [Unreleased]
77

8+
### Fixed
9+
10+
- 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.
11+
- 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.
12+
- Route Identity ownership through query parameters on existing Forward Environment, Skill/Version, Vault/Credential, and File operations, including multipart uploads and content downloads.
13+
- Allow existing channel pairing creation with either a code or `channel_pairing_id`, and expose pairing scope details. No additional API endpoints are introduced.
14+
15+
### Migration
16+
17+
- **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.
18+
- 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.
19+
- 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).
20+
- Channel pairing requests must provide exactly one of `code` or `channel_pairing_id`; existing code-based calls remain supported.
21+
822
## [0.6.0]
923

1024
### Added

‎docs/api/forward/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,7 @@
251251
- [EventContentUnionParam](type-aliases/EventContentUnionParam.md)
252252
- [ForwardClientOptions](type-aliases/ForwardClientOptions.md)
253253
- [IdentityCreateParams](type-aliases/IdentityCreateParams.md)
254+
- [IdentityScopeOptions](type-aliases/IdentityScopeOptions.md)
254255
- [MemoryStoreCreateParams](type-aliases/MemoryStoreCreateParams.md)
255256
- [MemoryStoreMemoryCreateParams](type-aliases/MemoryStoreMemoryCreateParams.md)
256257
- [ModelConfig](type-aliases/ModelConfig.md)

‎docs/api/forward/classes/Environments.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Archive an environment retained by historical sessions or tool calls.
5656

5757
##### options?
5858

59-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
59+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
6060

6161
#### Returns
6262

@@ -108,7 +108,7 @@ createEnvironment
108108

109109
##### options?
110110

111-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
111+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
112112

113113
#### Returns
114114

@@ -160,7 +160,7 @@ listEnvironment
160160

161161
##### options?
162162

163-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
163+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
164164

165165
#### Returns
166166

‎docs/api/forward/classes/Files.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656

5757
##### options?
5858

59-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
59+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
6060

6161
#### Returns
6262

@@ -82,7 +82,7 @@ deleteFile
8282

8383
##### options?
8484

85-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
85+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
8686

8787
#### Returns
8888

@@ -108,7 +108,7 @@ downloadFile
108108

109109
##### options?
110110

111-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
111+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
112112

113113
#### Returns
114114

‎docs/api/forward/classes/SkillVersions.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ createSkillVersion
9090

9191
##### options?
9292

93-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
93+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
9494

9595
#### Returns
9696

@@ -120,7 +120,7 @@ deleteSkillVersion
120120

121121
##### options?
122122

123-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
123+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
124124

125125
#### Returns
126126

@@ -180,7 +180,7 @@ listSkillVersion
180180

181181
##### options?
182182

183-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
183+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
184184

185185
#### Returns
186186

‎docs/api/forward/classes/Skills.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ createSkill
8888

8989
##### options?
9090

91-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
91+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
9292

9393
#### Returns
9494

‎docs/api/forward/classes/VaultCredentials.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ createVaultCredential
9090

9191
##### options?
9292

93-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
93+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
9494

9595
#### Returns
9696

@@ -150,7 +150,7 @@ listVaultCredential
150150

151151
##### options?
152152

153-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
153+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
154154

155155
#### Returns
156156

‎docs/api/forward/classes/Vaults.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ createVault
8888

8989
##### options?
9090

91-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
91+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
9292

9393
#### Returns
9494

@@ -140,7 +140,7 @@ listVault
140140

141141
##### options?
142142

143-
[`RequestOptions`](../../index/interfaces/RequestOptions.md)
143+
[`IdentityScopeOptions`](../type-aliases/IdentityScopeOptions.md)
144144

145145
#### Returns
146146

‎docs/api/forward/interfaces/ChannelPairing.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ Channel ID。
2222

2323
***
2424

25+
### created\_at?
26+
27+
> `optional` **created\_at?**: `string`
28+
29+
***
30+
2531
### id
2632

2733
> **id**: `string`
@@ -46,6 +52,24 @@ Pairing ID，解除配对时使用。
4652

4753
***
4854

55+
### scope\_display\_name
56+
57+
> **scope\_display\_name**: `string`
58+
59+
***
60+
61+
### scope\_external\_id
62+
63+
> **scope\_external\_id**: `string`
64+
65+
***
66+
67+
### scope\_type
68+
69+
> **scope\_type**: `string`
70+
71+
***
72+
4973
### status
5074

5175
> **status**: `string`
@@ -67,3 +91,9 @@ Pairing ID，解除配对时使用。
6791
> **type**: `string`
6892
6993
固定为 `channel_pairing`。
94+
95+
***
96+
97+
### updated\_at?
98+
99+
> `optional` **updated\_at?**: `string`

‎docs/api/forward/interfaces/ChannelPairingNewParams.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,19 @@ Additional fields are preserved verbatim by the SDK.
1414

1515
## Properties
1616

17-
### code
17+
### channel\_pairing\_id?
1818

19-
> **code**: `string`
19+
> `optional` **channel\_pairing\_id?**: `string`
2020
21-
Channel 消息中显示的 6 位配对码。
21+
Pending pairing ID. Supply exactly one of code or channel_pairing_id.
22+
23+
***
24+
25+
### code?
26+
27+
> `optional` **code?**: `string`
28+
29+
Channel 消息中的配对码；与 channel_pairing_id 二选一。
2230

2331
***
2432

0 commit comments

Comments
 (0)