[moonyue-w]

Summary

Align the existing Forward/Managed SDK contracts with the official QCA documentation reviewed on 2026-11-03. This adds typed Forward Session budgets and model overrides, approval evaluation details and Environment startup scripts; it fixes the language-specific gaps documented below. The README also documents startup timing, 64 KB / 5-minute constraints and failure events. No HTTP endpoints or version numbers change.

Forward event types now expose cumulative Credits and Outcome/status details, and shared model configuration exposes speed. Managed Memory version/redacted and Vault credentials are typed; Memory updated operations, list metadata, nested model types and legacy Thread usage are aligned where applicable.

Why

Current types omit fields in the documented API, and the approval result shape can be read incorrectly. This makes the existing endpoints usable through supported typed parameters and response fields.

Verification

Node 22.22.2: build, npm run typecheck, npm test (4,460 passed), npm run docs:check, npm pack --dry-run, changelog and release-tool tests passed. The test suite covers CJS/ESM and subpath consumers. The follow-up commit changes only README documentation; the docs check was repeated successfully.

• Relevant SDK, public type and package checks pass.
• Documentation and Unreleased changelog updated.
• Contract regression tests cover the changed wire fields and omission/null semantics.
• Cross-SDK parity and compatibility reviewed.
• No credentials or live configuration included.
• Account-backed integration and QA package acceptance: pending after merge; no live tests were run for this change.

Impact and migration

Compare evaluated_permission as a string and check optional event-specific fields before reading. Managed nested-model effort is a string; legacy modified remains a deprecated alias.

Budget/model omission and null semantics, cumulative usage consumption, and migration details are in CHANGELOG.md. A pre-1.0 minor release is required for the incompatible type changes.

Contract sources

• https://docs.qoder.com/cloud-agents/api/forward/sessions/data-structure
• https://docs.qoder.com/cloud-agents/api/forward/sessions/update
• https://docs.qoder.com/cloud-agents/api/environments/schemas
• https://docs.qoder.com/cloud-agents/api/memory-stores/schemas