moonyue-w · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026
@@ -5,6 +5,30 @@ existing `0.1.0` release; earlier development prereleases are not listed.
 
 ## [Unreleased]
 
+### Added
+
+- Automatically mark direct Forward and Managed Session creation with `__qca_sdk_created`, `__qca_sdk_language`, and the actual `__qca_sdk_version`, preserving caller metadata.
+- Add Forward Dreams (create, list, retrieve, cancel, archive), channel pairing list/retrieve/update, and Managed OAuth start with typed requests and responses.
+- Add Identity automatic memory-store control, mount access and cursor pagination, sparse managed-capability overrides, and full tools-array replacement.
+- Support string Template references and Advisor model entries in Forward Multiagent rosters, Schedule file resources, and optional Run input snapshots.
+- Add typed Managed OSS bucket storage with separate write credentials/read views, and Memory Store ID cursor parameters.
+
+### Fixed
+
+- Align Forward Outcome rubric objects and Managed Agent/Dream model configuration with the official API. Dream model defaults to `auto` when omitted; object configuration supports `effort` and `context_window`.
+
+### Breaking changes
+
+- Session creation rejects conflicting values for the three reserved SDK metadata keys before sending; matching string values remain accepted. Missing or null metadata now contains the markers, which count toward API metadata limits.
+- Forward event `rubric` is a text/content or file/file_id object instead of a string.
+- Managed Agent `effort` is a level string instead of an object; Agent and Dream model configuration no longer declares the unsupported `speed` field.
+- Identity mount lists now return standard pages (and an `AsyncPaginator` for the async client). Existing awaited calls still yield a page; use normal or async iteration to traverse all pages.
+
+### Migration
+
+- Rename business fields that collide with the three `__qca_sdk_` keys and leave space for automatic markers. See “SDK-created Session metadata” in the README.
+- Send `rubric={"type": "text", "content": "..."}` and `model={"id": "ultimate", "effort": "high"}`; remove Managed `speed` arguments. See the README's “Official contract alignment” section.
+
 ## [0.12.0]
 
 ### Added

@@ -41,6 +41,32 @@ Under the hood these run `pydoc-markdown` via `uv` on a pinned Python 3.12:
 uv run --python 3.12 --extra dev --locked pydoc-markdown pydoc-markdown.yml
 ```
 
+## SDK-created Session metadata
+
+Direct Forward and Managed Session creation automatically adds these string-valued
+metadata fields (Python includes both sync and async clients):
+
+| Field | Value |
+| --- | --- |
+| `__qca_sdk_created` | `"true"` |
+| `__qca_sdk_language` | `"python"` |
+| `__qca_sdk_version` | The installed SDK's version |
+
+Reserve the `__qca_sdk_` prefix for SDK provenance. Business metadata is preserved,
+and the caller's metadata object is not mutated. Omitted or null metadata becomes
+an object containing the markers. Passing an existing marker with the exact same
+string value is accepted; a different value or type (including null) fails locally
+before any HTTP request. This also applies after `extra_body` overrides are merged.
+
+Session updates, reads and event operations do not inject or repair these fields.
+Sessions created indirectly through Schedules, Batches or Realtime are outside this
+behavior. These markers describe the creating SDK; they are client-supplied metadata,
+not an authentication or authorization mechanism.
+
+Migration: rename any business fields that already use these three keys before
+upgrading. Automatic markers count toward API metadata limits; the SDK never drops
+business fields to make room. No additional parameters or opt-in are required.
+
 ## Usage
 
 ```python
@@ -868,3 +894,67 @@ Synchronous searches return `SyncPage`; asynchronous searches can be awaited for
 an `AsyncPage` or directly iterated with `async for`. Use `get_next_page()` for
 manual pagination (await it on an async page). `*SearchParams` TypedDicts are
 exported from `qca.forward.types` and `qca.managed.types`.
+
+## Official contract alignment
+
+The next release aligns these public types with the official API documentation
+retrieved on 2026-10-27. It introduces source changes relative to 0.12.0:
+Outcome `rubric` is an object; Managed Agent `effort` is a string; Managed Agent
+and Dream model objects do not accept `speed`. Managed Dream `model` is optional
+and defaults to `auto`. Discover model IDs and supported efforts/context windows
+with List models. These Managed model changes do not remove Forward model features.
+
+```python
+from qca import Forward, Managed
+
+client = Forward(pat="...")
+rubric = {"type": "text", "content": "report exists"}
+model = {"id": "ultimate", "effort": "high"}
+dream = client.dreams.create(inputs=[{
+    "type": "identity_template", "identity_id": "idn_...", "template_id": "tmpl_...",
+}])  # model defaults to auto
+
+for mount in client.identities.memory_stores.list(
+    "tmpl_...", identity_id="idn_...", limit=20,
+):
+    print(mount.memory_store_id)
+```
+
+The async mount list returns an `AsyncPaginator`: use `async for` directly, or
+`await` it to obtain the first `AsyncPage`. Sync lists return `SyncPage`.
+Identity `tools=[]` replaces all tools with no tools; `tools=None` clears that
+override. Pass `managed_tool_config={"schedule": {"enabled": False}, "drive": None}`
+to disable Schedule tools and restore inherited Drive settings. Omitted values
+remain unchanged. Multiagent `agents` accepts Template ID strings and
+`{"type": "advisor", "model": "ultimate"}` objects.
+
+New Forward Dream calls require a PAT or an admin SAT; an Identity SAT is not
+supported. Inputs contain exactly one primary Memory Store or Identity/Template
+source, optionally plus Session sources. Pairing `update` changes an active
+binding; supply at least one nonempty Identity or Template ID. Use pairing
+`create` to complete a pending pairing. Pending records preserve empty
+`identity_id`, `template_id`, and `paired_at` strings.
+
+Identity `auto_memory_store=false` disables automatic default-store creation.
+Independent mounts now accept `access="read_write"`; omit access for a new
+read-only mount, or to preserve an existing mount's permission. Schedule
+`resources` accepts file entries and `[]` clears them; Run retrieval supports
+`include_initial_events=true` to return the saved input snapshot.
+
+Managed cloud Environment `config.storage.buckets` supports up to eight OSS
+mounts. When the resulting configuration has buckets, explicitly include beta
+`oss-bucket-2026-09-23` (`Betas` in Go, `betas` in Python/TS). Send credentials
+only when creating or replacing them; omit `credential` on an existing named
+bucket to keep it. Responses expose a read view without role ARN or AccessKey
+secret. `storage: {buckets: []}` clears mounts.
+
+Managed `OAuth.Start` (Go) / `oauth.start` (Python/TS) returns `authorization_url`,
+`state`, and `callback_origin`; the user completes authorization in a browser.
+Client secrets go in the POST body, never in a URL. This method does not open a
+browser or complete consent automatically.
+
+See the official [Outcome contract](https://docs.qoder.com/cloud-agents/api/forward/sessions/send-events),
+[Identity overrides](https://docs.qoder.com/cloud-agents/api/forward/identities/upsert-config),
+[Dream inputs](https://docs.qoder.com/cloud-agents/api/forward/dreams/create),
+[OSS storage](https://docs.qoder.com/cloud-agents/api/environments/storage-buckets),
+and [OAuth flow](https://docs.qoder.com/cloud-agents/api/vaults/start-oauth).