feat(#20): stream + cancel adapter routes complete the wt surface (slice-2, part 2a)

Completes the adapter's session/turn surface, still additive and non-breaking (no
surface rewired, no hand-rolled path deleted — the cli/web rewire + deletions +
live smoke are part 2b).

- stream_turn: drives the SDK's resilient stream (auto-resume absorbs the old
  reconnect_turn) and yields SDK TurnEvents, re-wrapping the stream's TERMINAL SDK
  errors into ratatoskr's caller-semantic exceptions per DEC-2 (SessionRetired →
  SessionApiFailed; AgentNotAvailable / TurnLaunchUnavailable / MalformedSse* /
  TurnIdFlip → ratatoskr's same-named types; ConnectionDropped → SseConnectionDropped;
  ConnectFailed / terminal ResumeError → SseConnectFailed). The presenter keeps
  catching ratatoskr types (part 2b aligns the except clauses).
- cancel_turn: returns the SDK CancelResult (a 200 cancelled=False is the benign
  late-cancel race, B-CAN-3), mapping the typed cancel races onto ratatoskr's
  CancelTurnNotFound / CancelAlreadyCompleted / CancelFailed.
- SseConnectionDropped.last_seen_sse_id widened to SseId | str | None: the SDK's
  resume cursor is a raw composite-id str (the cutover's target form); the
  hand-rolled path's SseId stays accepted until it is deleted. The one live reader
  (stream_turn_resilient) generalizes cleanly — a str cursor is already the id.

Suite 570 green (555 + 15); wt.py + sse_client.py mypy + ruff clean. Patch.

docs/contracts/worldtree_sdk_cutover.contract.md

@@ -0,0 +1,218 @@
+---
+contract_version: "2.1"
+module: "ratatoskr.wt"
+purpose: "SDK-adapter cutover — replace ratatoskr's hand-rolled httpx consumer wrappers (sessions/sse_client/tier3) with a thin adapter over worldtree-sdk (Python) 1.0.0, deleting the old wrappers; CLI/TUI/web surfaces and caller-semantic exceptions preserved."
+touches:
+  - src/ratatoskr/wt.py
+  - src/ratatoskr/cli.py
+  - src/ratatoskr/tui.py
+  - src/ratatoskr/web/server.py
+scope: "Cut ratatoskr's CONSUMER client layer over from its hand-rolled httpx wrappers (sessions.py / sse_client.py / tier3.py / first_message.py) to consume worldtree-sdk (Python) 1.0.0. Replace the wrappers with a thin ratatoskr-owned adapter over the SDK; delete the old wrappers; keep the CLI / TUI / Starlette web surfaces and ratatoskr's caller-semantic exception surface. The Bifrost PROVIDER planes (memory/affect — where Worldtree dispatches INTO ratatoskr, ADR-0009) are consumer-orthogonal and untouched. Cutover decided by operator ruling 2026-07-18; design locked via vor-cross with worldtree-codex (thread 01KXWCWV3VKNR0HP74D2RCY0DC)."
+depends_on:
+  - "worldtree-sdk (Python) == 1.0.0  # git tag python-v1.0.0; pin to the internal Gitea registry once published (DEC-5)"
+used_by:
+  - "ratatoskr.cli"
+  - "ratatoskr.tui"
+  - "ratatoskr.web"
+language: "python"
+complexity: "high"
+estimated_loc: 400  # net, rough — deletes (old wrappers) offset adds (adapter + call-site edits); sized per slice, not up front
+confidence: 0.8
+assumptions:
+  - "worldtree-sdk 1.0.0 is the GA Python consumer SDK ratatoskr's parity pass shaped; its resource surface (WorldtreeClient.sessions/agents/characters/me/capabilities/models/admin) covers all 21 of ratatoskr's covered routes. Verified against ~/development/worldtree-sdk @ python-v1.0.0."
+  - "Caller-injected transport is a first-class tested path (PY-INV-012): WorldtreeClient(base_url, auth=..., transport=my_httpx_async_client) uses ratatoskr's AsyncClient and NEVER closes it. Ratatoskr keeps base_url / bearer / User-Agent / timeout / web-app lifecycle ownership."
+  - "The SDK REST floor is an undiscriminated ApiError(error_code, message, status, body) (B-ERR-1/B-OPEN-3); hide-existence 404s are NOT distinguished by the SDK (B-ERR-4). Ratatoskr's caller-semantic mapping lives one layer up (DEC-2)."
+---
+
+# worldtree-sdk cutover — consumer-layer adapter contract
+
+Single SDK-adapter contract per operator DEC-1. This is a migration contract: its
+spine is a route-family slice plan, not a dense FN-block spec — each slice's
+adapter FN detail is filled in at that slice's TDD (incremental migration; the
+per-route SDK signatures are already mapped below).
+
+## Locked design (operator-accepted 2026-07-18, post vor-cross)
+
+- **DEC-1 — retire, don't repurpose (two-phase).** Normative authority for the
+  consumer wire transfers to THIS contract immediately (as of this file, #2 sessions
+  and #15 tier3 are superseded — no longer the spec of record); the contract FILES
+  are DELETED at slice-7 teardown, only after the code they specified is gone
+  (avoids both orphaning live code and leaving obsolete norms active mid-migration).
+  `first_message` is NOT retired — it stays a ratatoskr-owned usage contract at the
+  spec level (its preset / best-effort-timeout / swallow policy is local, not
+  SDK-owned). Repurposing the wire contracts would risk a shadow-normative copy of
+  SDK-owned semantics — the exact thing the cutover eliminates.
+- **DEC-2 — thin semantic error adapter.** CLI/web/TUI keep ratatoskr's typed
+  exceptions; the adapter maps the SDK's `ApiError` floor → ratatoskr's
+  caller-semantic types (the SDK stays undiscriminated; hide-existence maps here).
+- **DEC-3 — no shims (house rule).** Delete the old wrapper modules and update all
+  call-sites to the new adapter. No compatibility facade preserving old
+  module/function APIs (pre-1.0 no-backwards-compat rule).
+- **DEC-4 — incremental + live-smoke, no soak.** Migrate one route-family per
+  slice, TDD each slice, and run a targeted LIVE smoke of that family against the
+  personal endpoint before deleting the replaced hand-rolled path. (The SDK's
+  fixture corpus proves the WIRE; the live smoke proves ratatoskr's
+  presenter/adapter/env-wiring survived the dependency inversion.)
+  **Smoke acceptance bar (the minimum that lets an old path be deleted):** drive
+  each route in the family's primary flow END-TO-END through the ratatoskr surface
+  (CLI/web) — not the wrapper directly — against the personal endpoint under the
+  real consumer key, and OBSERVE the expected success (a created session, a streamed
+  turn that renders, a persona write that reads back), not merely a non-crash. A
+  smoke that only asserts "no exception" does NOT clear the bar. **Smoke vs. soak
+  boundary:** a smoke is a single pass of the family's flows at deletion time; a
+  (forbidden) soak is a sustained dual-path parallel-run — do the former, not the
+  latter.
+- **DEC-5 — wait for the registry.** Pin `worldtree-sdk == 1.0.0` from the internal
+  Gitea registry once published (verify the uv install first); use the
+  `python-v1.0.0` git tag only if the registry lags. Contract-drafting is NOT
+  gated (SDK source is inspectable); IMPLEMENTATION pin is.
+- **DEC-6 — minor bump at ship.** The cutover ships as a minor (architecture-cutover
+  milestone; pre-1.0 breaking-internal) — requires explicit operator approval at
+  ship time, not now.
+
+## Adapter design
+
+- **`ratatoskr.wt`** — a thin adapter module owning ONE `WorldtreeClient`, built
+  with ratatoskr's own `httpx.AsyncClient` injected (`transport=`), ratatoskr's
+  `auth`/`admin_auth` providers, and the ratatoskr User-Agent. It exposes
+  ratatoskr-semantic call surfaces the presenters already expect, and translates
+  SDK errors → ratatoskr exceptions (DEC-2).
+- **Transport ownership (INV-CUT-1 [hard]):** the injected `AsyncClient` is
+  ratatoskr-owned; `WorldtreeClient.aclose()` / `async with` exit must NOT close
+  it (SDK `_owns_client=False` on injection). Ratatoskr owns the client lifecycle
+  exactly as today.
+- **Error boundary (INV-CUT-2 [hard]):** ratatoskr's caller-semantic exceptions
+  are raised by the adapter, mapping from the SDK where the SDK already
+  discriminates (`AgentNotAvailable`, `TurnLaunchUnavailable`, `SessionRetired`,
+  `Cancel*`, `Resume*`, `Malformed*`) and from `ApiError(status=..., error_code)`
+  on a KNOWN route otherwise — including the hide-existence 404 →
+  `AuthoredHistoryUnavailable` (labeling a call we made, NOT capability-probing).
+- **Provider boundary (INV-CUT-3 [hard]):** the Bifrost provider planes stay
+  hand-rolled and are never routed through the SDK. The Bifrost-BOUND
+  `sessions.create` (consumer-side, `bifrost=` + consumer-key auth) DOES go through
+  the SDK and stays consumer-layer.
+- **Import boundary (INV-CUT-4 [hard]):** `tests/test_no_worldtree_imports.py`
+  stays; the boundary becomes "no Worldtree SOURCE imports", with `worldtree_sdk`
+  the allowed client dependency.
+
+## Invariants
+
+- **INV-CUT-1 [hard]** — Ratatoskr owns the injected `httpx.AsyncClient` lifecycle;
+  the SDK never closes it (`_owns_client=False` on transport injection).
+- **INV-CUT-2 [hard]** — The adapter raises ratatoskr's caller-semantic exceptions
+  per the explicit **§ Error map** table below — mapping from the SDK's discriminated
+  errors (passthrough) and from `ApiError` by the ROUTE that raised it (the route is
+  the discriminator, never the body). Every `ApiError` is mapped; the default is
+  `SessionApiFailed`. No route invents semantics the table doesn't list.
+- **INV-CUT-3 [hard]** — The Bifrost PROVIDER planes never route through the SDK;
+  the Bifrost-BOUND `sessions.create` does (consumer-side).
+- **INV-CUT-4 [hard]** — The no-Worldtree-SOURCE-import boundary holds
+  (`worldtree_sdk` allowed); `tests/test_no_worldtree_imports.py` enforces it.
+- **INV-CUT-5 [hard]** — Each slice runs a LIVE smoke of its route family before the
+  replaced hand-rolled path is deleted (DEC-4); no old path is removed unproven.
+
+## Route map — ratatoskr wrapper → SDK method (grounded @ python-v1.0.0)
+
+| Ratatoskr wrapper (retiring) | SDK method | SDK return |
+|---|---|---|
+| `create_session` | `sessions.create(...)` | `SessionInfo` |
+| `list_sessions` | `sessions.list(limit, cursor)` | page |
+| `stream_turn` | `sessions.stream_turn(...)` (resilient) / `stream_turn_raw` (single) | `AsyncIterator[Event]` |
+| `reconnect_turn` | folded into `sessions.stream_turn` auto-resume | — |
+| `cancel_turn` | `sessions.cancel_turn(...)` | `CancelResult` |
+| `get_session_messages` | `sessions.messages(id)` | open-world |
+| `get_session_tools` | `sessions.tools(id)` | `SessionTools` |
+| `set_persona_state` | `sessions.set_persona_state(id, PadState)` | None |
+| `write_authored_history` | `sessions.write_history(...)` | authored-turn |
+| `get_persona_state` | `agents.persona_state(agent_id)` | `AgentPersonaState` |
+| `list_agents` | `agents.list()` | `AgentList` |
+| `define_agent` | `agents.define(...)` | `DefinedAgent` |
+| `patch_agent` | `agents.patch(id, changes)` | `PatchedAgent` |
+| `delete_agent` | `agents.delete(id)` | None |
+| `get_me` | `me.get()` | `MeInfo` |
+| `get_capabilities` | `capabilities.get()` | `Capabilities` |
+| `list_character_models` | `models.available_for_characters()` | `ModelsAvailable` |
+| `create_character` | `characters.create(...)` | `CreatedCharacter` |
+| `get_character_state` | `characters.state(id)` | `CharacterState` |
+| `delete_character` | `characters.delete(id)` | `CharacterDeleteResult` |
+| `get_session_bifrost` | `admin.sessions.bifrost(id)` | `BifrostInspection` |
+| `stream_admin_events` | `admin.stream_events(...)` | `AsyncIterator[AdminEvent]` |
+
+Note: SDK returns are typed `shapes.*`; per the parity pass the freeform reads
+(`SessionTools`, `BifrostInspection`, capabilities) are deliberately open-world in
+the Python spine. The adapter PASSES THESE THROUGH unmodified (does not normalize);
+presenters read them as mappings, tolerant of wire drift. If an open-world read is
+malformed the presenter degrades (never crashes) — same posture as the existing
+`_format_whoami` hardening.
+
+## Error map (INV-CUT-2 — the explicit table)
+
+**The ROUTE is the discriminator, not the error body** (labeling a call we made, NOT
+capability-probing — B-ERR-4). A 404 is mapped by which method raised it; the adapter
+NEVER sniffs the body to decide whether something exists. Authored-history is
+currently the ONLY hide-existence route (per Worldtree B-ERR-4); if Worldtree adds
+others, they get their own row here — the default is NOT a general "any 404 → hidden".
+
+| SDK raises (from) | Adapter maps to |
+|---|---|
+| SDK `AgentNotAvailable` / `TurnLaunchUnavailable` / `SessionRetired` (stream-open) | ratatoskr `AgentNotAvailable` / `TurnLaunchUnavailable` / (retired → `SessionApiFailed`) — same names, passthrough |
+| SDK `ConnectionDropped` (mid-stream) | `SseConnectionDropped` |
+| SDK `ResumeError` subclasses (in resilient stream) | resilient `stream_turn` absorbs; terminal → `SseConnectFailed` |
+| SDK `Cancel*` (cancel_turn) | folded into `CancelResult`; late-cancel race (B-CAN-3) returns `cancelled=False`, never raises |
+| `ApiError(404)` on `sessions.create` | `AgentNotFound` |
+| `ApiError(404)` on `sessions.write_history` | `AuthoredHistoryUnavailable` (hide-existence) |
+| `ApiError(422 cursor_invalid)` on `sessions.list` | `InvalidCursor` |
+| `ApiError(502 bifrost_handshake_failed)` on bound `sessions.create` | `BifrostHandshakeFailed` |
+| **`ApiError` (any other status/route) — the default** | `SessionApiFailed(status, error_code, body)` |
+
+The default row is load-bearing: any `ApiError` not matched above surfaces as the
+generic `SessionApiFailed` carrying the raw `status`/`error_code`/`body` — the
+adapter does NOT invent per-route semantics the contract doesn't list, and does NOT
+leave an `ApiError` un-mapped. Each slice adds/confirms its route's rows here before
+the old path is deleted.
+
+## Slice plan (incremental, DEC-4)
+
+Each slice: wire the family through `ratatoskr.wt` → update call-sites → TDD →
+LIVE smoke against the personal endpoint → delete the replaced hand-rolled path →
+re-anchor its coverage-map rows.
+
+1. **Foundation** — `ratatoskr.wt` module + injected `WorldtreeClient` + auth
+   providers + the error-adapter skeleton (the § Error map's default `ApiError` →
+   `SessionApiFailed` rule + the discriminated-error passthrough). No USER-VISIBLE
+   behavior change (imports/construction change; the skeleton is unit-tested but
+   unexercised by any surface until slice 2). Done = `ratatoskr.wt` importable, the
+   client constructs with an injected transport, and the error-map default is unit-
+   covered.
+2. **Sessions/turn** — create/list/messages/tools/cancel + the turn STREAM + the
+   Bifrost-bound create. The turn presenter wires the resilient `sessions.stream_turn`
+   (auto-resume — this ABSORBS the old `reconnect_turn`, which is deleted this slice
+   with its call-sites); `stream_turn_raw` is available for a single-attempt caller
+   but is NOT the presenter default. (Highest-traffic; the SSE presenter is the
+   riskiest wiring.)
+3. **Persona + authored-history** — set_persona_state (PadState) + write_history
+   (hide-existence mapping) + first_message presets (stay ratatoskr-owned OVER the
+   SDK method).
+4. **Agents (Tier-3)** — list/get/define/patch/delete/persona_state. (Folds in the
+   pending `model`→`role` cutover — see [[project-tier3-agents-model-to-role-pending]].)
+5. **Characters + me/capabilities/models** — the remaining consumer reads.
+6. **Admin** — admin.sessions.bifrost + admin.stream_events (admin_auth).
+7. **Teardown** — delete residual hand-rolled modules; drop `httpx-sse` (SDK owns
+   SSE parsing); retire contracts #2/#15; final coverage-map re-anchor; minor bump
+   (DEC-6, operator approval).
+
+## Out of scope
+
+- Bifrost PROVIDER planes (memory/affect) — hand-rolled, ADR-0009, untouched.
+- CLI / TUI / Starlette web surfaces — their EXTERNAL BEHAVIOR is preserved (their
+  call-sites DO change — they're updated to the new adapter per `touches:`; what's
+  invariant is the observable behavior, not the code).
+- The four parked post-v1 SDK ergonomics items (replayed:bool, raw-dict persona
+  escape hatch, list_all iterator, split session types) — coordinated post-v1 lane
+  with wtsdk-dev, not this cutover.
+
+## Coverage-map re-anchor
+
+`docs/coverage-map.md` shifts from "hand-rolled route exists + live-proven" to
+"SDK method wired and exercised by a ratatoskr surface"; excluded-by-design rows
+stay explicit. Re-anchored per slice as each family lands.

docs/coverage-map.md

@@ -23,6 +23,23 @@ anchors against the frozen machine-readable artifacts, NOT the prose markdown:
 | Conversation SSE events | `conversation-api-sse-events.schema.json` (sha `9deeebf4…`) — **11 discriminated event types** | **client** |
 | Bifrost wire (consumer protocol) | wire **v0.6** STABLE/FROZEN (`bifrost==1.0.0`) — memory + affect planes | **provider** (Worldtree dispatches into us) |
 
+> **External ratification — worldtree-sdk v1.0.0 (wtsdk-dev, 2026-07-18, althing
+> thread `01KXVF24WQD2T5ZCS49KKFCCMH`).** The TypeScript v0 consumer SDK wires all
+> **41 ops as typed methods** from the **same OpenAPI 2.3.0** (sha
+> `36148179601453a0` — matches our vendored pin exactly), so it is the independent
+> parity authority for the surface this ledger tracks. Ratatoskr does **not** adopt
+> the SDK — we are the parallel **Python/httpx** reference-consumer of the identical
+> surface (no TS/npm surface exists to pin it into). Cross-check corroboration: the
+> SDK's **W-4** (send `config.role`, response echoes `model` unremapped) matches what
+> ratatoskr shipped in **v0.21.2** for ephemeral-Echo create.
+>
+> **Future consumable — worldtree-sdk Python spine (wtsdk-dev, next milestone).** The
+> TS v1 surface is our parity *checklist*; the forthcoming **Python spine** (same
+> behavioral-spec + fixture corpus, TS decisions kept Python-portable per their
+> surface-design §6) is what ratatoskr would actually *consume* when it lands.
+> wtsdk-dev slots ratatoskr as **THE reference consumer** whose coverage column
+> drives that spine — a future repin candidate, not yet available.
+
 > **Pin drift (finding P-1) — REMEDIATED 2026-06-30.** Ratatoskr formerly
 > vendored only the **prose markdown** (`docs/conversation-api-spec.md`), which
 > is byte-identical to live Worldtree's but frozen at v0.35.16-era content (last
@@ -67,7 +84,7 @@ sub-gap).
 
 | Endpoint | Status | Where consumed | Note |
 |---|---|---|---|
-| `POST /sessions` | ✅ | `sessions.py:307` → `cli.py:482`,`tui.py:1508`,`web/server.py:155` | + `end_user_id`, `bifrost` binding; 404→AgentNotFound, 502→BifrostHandshakeFailed |
+| `POST /sessions` | ✅ | `sessions.py` `create_session` → `cli.py`,`tui.py`,`web/server.py` | + `end_user_id`, `bifrost` binding; 404→AgentNotFound, 502→BifrostHandshakeFailed. **v0.21.2 (#19): ephemeral-template (Echo) create** — `config` passthrough (`--system-prompt`), `role` not `model` (W-4), `kind`/`config` captured; 422 ephemeral_requires_config now reachable-and-handled. Depth enhancement to an already-covered route — count unchanged |
 | `POST /sessions/{id}/messages` (turn stream, SSE) | ✅ | `sse_client.py:484` `stream_turn` → cli/tui/web | the primary surface; 409→AgentNotAvailable, 503→TurnLaunchUnavailable (b2 #331) |
 | `POST /sessions/{id}/history` (authored-history-write, #347) | ✅ | `sessions.py:583` `write_authored_history` → `cli.py:758` `--seed-first-message` | v1: author=assistant, effects=none, per-session idempotency; 404→AuthoredHistoryUnavailable (hide-existence: feature-absent, never probe); 409/422 mapped. **LIVE-PROVEN 2026-07-06** on personal :8081 (grant applied via a rule-based Heimdall allow, worldtree-dev): create mimir session → seed → **201** (seq=0, phase=seeded, turn_id=1798) → GET /messages reads it back as a plain role=assistant turn (model-invisible provenance confirmed). Hide-404 for ungranted is unit+probe covered |
 | `GET /sessions/{id}/messages` (history) | ✅ | `sessions.py:635` `get_session_messages` → `cli.py:758` `--seed-first-message` read-back | un-deferred as the #347 seed read-back — confirms model-invisible provenance (a seed reads back as a normal `role=assistant` turn) |
@@ -78,7 +95,7 @@ sub-gap).
 | `PATCH /agents/{id}` | ✅ | `tier3.py:219` → `_run_patch` | Tier-3 mutate (system_prompt/model) |
 | `DELETE /agents/{id}` | ✅ | `tier3.py:242` → `_run_delete` | Tier-3 hard-delete |
 | `GET /me` | ✅ | `sessions.py:411` `get_me` → `cli.py` `--whoami` | identity/whoami probe; 401→SessionApiFailed |
-| `GET /capabilities` | ✅ | `sessions.py:428` `get_capabilities` → `cli.py` `--whoami` | Echo ephemeral-template discovery |
+| `GET /capabilities` | ✅ | `sessions.py` `get_capabilities` → `cli.py` `--whoami` | Echo ephemeral-template discovery. **v0.21.2: `--whoami` renderer reads `allowed_roles`/`default_role`** (was the dead `allowed_models`/`default_model`) + tolerates malformed caps; matches conversation-api-spec **v1.1** (`b4a278c`) |
 | `GET /sessions/{id}/tools` | ✅ | `sessions.py:411` `get_session_tools` → `tui.py` `_hydrate_session_tools` | owner-scoped tool inventory in the TUI Tools pane (#183) |
 | `GET /admin/sessions/{id}/bifrost` | ✅ | `sessions.py:428` `get_session_bifrost` → `tui.py` `_hydrate_bifrost_state` | admin-scoped BifrostState pane (#176); admin key (`RATATOSKR_ADMIN_API_KEY`); live-auth-proven |
 | `GET /admin/events` (SSE) | ✅ | `sse_client.py` `stream_admin_events` → `tui.py` `_stream_admin_events` | admin lifecycle SSE stream (#11), session-filtered AdminEvents pane; admin key; live-auth-proven |

persistent-memory.md

@@ -46,6 +46,33 @@ upstream API key stays server-side (INV-003).
 
 _As of 2026-07-18 (evening):_
 
+**🔨 ACTIVE MIGRATION — worldtree-sdk cutover (issue #20), starting slice-1.** Operator ruled ADOPT
+(2026-07-18): ratatoskr cuts its CONSUMER client layer over to consume **worldtree-sdk (Python) 1.0.0** —
+retire the hand-rolled httpx wrappers (`sessions`/`sse_client`/`tier3`) behind a thin `ratatoskr.wt`
+adapter over the SDK. Both TS + Python SDK 1.0.0 are GA (**Python live + pip-installable on the gitea
+PyPI** — DEC-5 gate cleared). Ratatoskr's own **parity pass shaped the Python spine** (open-world reads,
+caller-injected transport, per-wire role/model). Design locked (6 DECs, vor-cross'd with worldtree-codex,
+heid-panel-reviewed → error-map table added); contract `docs/contracts/worldtree_sdk_cutover.contract.md`
+(committed `e45640c`). **SLICE-1 IN PROGRESS:** ✅ dep integrated + DEC-5 verified + committed (`29c4fda`) — `worldtree-sdk==1.0.0`
+installs from the gitea registry (reuses bifrost's index auth, NO new token; core dep + `[tool.uv.sources]`),
+`WorldtreeClient` constructs with an injected transport (`_owns_client=False`, INV-CUT-1 confirmed live),
+suite 534 green. **NEXT = the adapter** `src/ratatoskr/wt.py` (TDD): `build_client(base_url, *, api_key,
+admin_key, transport)` → `WorldtreeClient(auth=, admin_auth=, transport=)` (DESIGN CARE: SDK does per-request
+auth via the providers; our injected `httpx.AsyncClient` carries base_url/UA/timeout, NOT the Authorization
+header — read the SDK `client.py` @ `~/development/worldtree-sdk` for the split, INV-CUT-1) + `translate_error`
+DEFAULT (SDK `ApiError`→`SessionApiFailed`, discriminated `WorldtreeError` subclasses passthrough; route-specific
+rows come in later slices). Unit-test; NO surface wiring (slice-2). Then slices 2-7 (route-family + deletions,
+live-smoke per slice). Scope: consumer layer ONLY;
+Bifrost provider planes untouched. Multi-session grind. Full design → auto-memory
+`project_worldtree_sdk_cutover`. This SUPERSEDES the #371 "repin rides the later Python milestone" framing
+below (that milestone shipped; we're adopting, not just repinning).
+
+**⏸️ DEFERRED — tier3 agents `model`→`role` (scope B), on worldtree-dev's deploy flag.** WT renames the
+agents-RESPONSE selector `model`→`role` (spec 1.2, commit `387c67b`, NOT yet deployed). `_parse_tier3_agent_info`
+reads `body["model"]` → KeyErrors post-deploy. Operator chose scope B (full tier3 `model`→`role` incl.
+contract #15 + CLI `--model`→`--role`). Implement ON the deploy flag, not before (breaks the current demo);
+folds into cutover slice-4. Auto-memory `project_tier3_agents_model_to_role_pending`.
+
 **✅ RESOLVED — the "app product" workstreams leave Rata entirely (operator 2026-07-18).**
 **No arbo fork, no SillyTavern-on-Rata** — a NEW repo (template-dev standing up) takes over BOTH
 app-product ideas. Rata does NOT fork into anything and is NOT the base for any chat / image-gen app.
@@ -88,10 +115,13 @@ Full record → `persistent-memory.d/2026-07-18-368-silo-test-passed.md`. Siblin
 (2) R39 Phase-2 **matched-quartets rebuild** (confirmatory, "whenever"); (3) bifrost **snapshot-cursor
 adoption** (ruled normative, not blocking → `persistent-memory.d/2026-07-16-bifrost-cursor-conformance.md`).
 
-**Substrate / environment:** branch `main` at **v0.21.1**, **PUSHED to origin 2026-07-18** (incl.
-tier3 b127-role adaptation `860e0d5`, #368 memory snapshots + silo work, the contract-drift fix
-`4bd9abd`, and this snapshot); origin `git@gitea.phasefinal.com:vh/ratatoskr.git`. bifrost
-**`==1.1.4`** / wire v0.7; WT openapi vendored 2.3.0; **suite 644 green**. Personal WT on **b127**
+**Substrate / environment:** branch `main` at **v0.21.2**. **origin at `b1fbadd`** (pushed 2026-07-18:
+canonical syncs `5d06a27`/`80c8d58`, ephemeral-Echo `c7016f2` #19, coverage-map→SDK-surface `b1fbadd`).
+**UNPUSHED local commits** (cutover work — operator hasn't pushed): cutover contract `e45640c` #20, the
+`memory:` snapshot, dep-integration `29c4fda` (worldtree-sdk==1.0.0), + this snapshot — **push is the
+operator's call**. origin `git@gitea.phasefinal.com:vh/ratatoskr.git`. **NEW core dep: `worldtree-sdk==1.0.0`**
+(gitea PyPI, `[tool.uv.sources]`). bifrost **`==1.1.4`** / wire v0.7; WT openapi vendored 2.3.0,
+**conversation-api-spec re-synced to v1.1** (`b4a278c`); **suite 534 green**. Personal WT on **b127**
 (`http://10.250.50.152:8081`; #368 silo + #364 promotion-hygiene live both instances). The combined
 **:8392** provider (memory+affect) + **:8765** web are THE surfaces, dev-box BACKGROUND SHELLS —
 restart via `scratchpad/relaunch_by_pid.py <pid>` (pid via `ss -ltnp | grep <port>`). `env.sh` sets
@@ -238,6 +268,9 @@ decision. Captures rationale that won't be obvious from code alone.
 - `[2026-07-18]` **issue #1 contract drift fixed (`4bd9abd`) — SSE event vocab re-canonicalized: added `awaiting_llm_first_token` (#201) + `affect_update` (#204) to the Event union + TESTS (both were parsed by `_envelope_for_type` and tested in `test_sse_client.py`, but never in #1's contract; surfaced by the #371 parity pass). Contract-only, no bump.**
 
 - `[2026-07-18]` **Both app products (arbo image-gen + SillyTavern chat) leave Rata to a NEW repo (template-dev standing up); Rata does NOT fork and is NOT the app base.** Reverts Rata to its core — Worldtree debug-observability surface + Bifrost reference impl + Conversation-API SDK seed/future-consumer. Supersedes the 2026-07-17 'fork Rata for arbo' NEXT-MAJOR plan.
+- `[2026-07-18]` **ephemeral-template (Echo) create SHIPPED (`v0.21.2`, `c7016f2`, #19)** — `config` passthrough + `--system-prompt` + `SessionInfo.kind/config` + `--whoami` roles fix. Diagnosed from the ignored `session_api_failed` startup line; role/model drift resolved w/ worldtree-dev (spec re-synced v1.1). TDD + heid contract-review + bug-hunt.
+- `[2026-07-18]` **Rata = THE reference consumer of the worldtree-sdk Python spine** — parity pass (12 grounded findings) shaped its contract BEFORE build (open-world reads, caller-injected transport, per-wire role/model — adopted); coverage-map re-anchored to the SDK's 41-op ratified surface (`b1fbadd`); 4 ergonomics items parked post-v1 with wtsdk-dev.
+- `[2026-07-18]` **worldtree-sdk cutover DECIDED — adopt the Python SDK for the consumer client layer** (operator, overriding "stay hand-rolled"). Issue #20; contract `docs/contracts/worldtree_sdk_cutover.contract.md` (`e45640c`, vor-cross'd + heid-reviewed); auto-memory `project_worldtree_sdk_cutover`. Consumer layer only, Bifrost provider untouched; slice-1 foundation next. See in-flight.
 
 _65 older entries (2026-05-* debug-TUI/web era + the 2026-06-14 → 06-18 Bifrost-provider build / #17+#18 / #295-296 era) archived to archival-memory.md._
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ratatoskr"
-version = "0.21.2"
+version = "0.21.5"
 description = "Worldtree Conversation API debug console (web + headless CLI) — multi-pane observability"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -16,7 +16,8 @@ keywords = ["worldtree", "debug", "sse", "web", "observability"]
 # See docs/design-brief.md §3 (httpx-sse).
 dependencies = [
     "httpx>=0.27",
-    "httpx-sse>=0.4",
+    "httpx-sse>=0.4",       # #20 slice-7 teardown drops this once the SDK owns SSE parsing
+    "worldtree-sdk==1.0.0", # #20 cutover: the consumer client layer (gitea PyPI); slices retire the hand-rolled wrappers behind ratatoskr.wt
 ]
 
 [project.optional-dependencies]
@@ -70,6 +71,7 @@ url = "https://gitea.phasefinal.com/api/packages/vh/pypi/simple/"
 
 [tool.uv.sources]
 bifrost = { index = "gitea" }
+worldtree-sdk = { index = "gitea" }
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/ratatoskr"]

src/ratatoskr/sse_client.py

@@ -286,9 +286,15 @@ def _eager_failure_fields(body: bytes, status: int) -> tuple[str, str]:
 
 
 class SseConnectionDropped(Exception):
-    """Raised when the HTTP/SSE connection dropped mid-stream."""
+    """Raised when the HTTP/SSE connection dropped mid-stream.
 
-    def __init__(self, *, last_seen_sse_id: SseId | None) -> None:
+    `last_seen_sse_id` is the resume cursor of the last frame seen. The
+    hand-rolled path carries a parsed `SseId`; the worldtree-sdk cutover carries
+    the SDK's raw composite-id `str` (the cutover's target form) — both accepted
+    during the migration.
+    """
+
+    def __init__(self, *, last_seen_sse_id: SseId | str | None) -> None:
         super().__init__(f"SSE connection dropped; last_seen_sse_id={last_seen_sse_id}")
         self.last_seen_sse_id = last_seen_sse_id
 
@@ -611,7 +617,8 @@ async def stream_turn_resilient(
                 client,
                 session_id,
                 content,
-                last_event_id=f"{seen.turn_id}:{seen.seq}",
+                # A str cursor is already the composite id; an SseId is formatted.
+                last_event_id=seen if isinstance(seen, str) else f"{seen.turn_id}:{seen.seq}",
             )
 
 

src/ratatoskr/wt.py

@@ -0,0 +1,321 @@
+"""worldtree-sdk adapter — ratatoskr's single chokepoint onto the Conversation-API SDK.
+
+Slice-1 foundation of the SDK cutover (issue #20;
+`docs/contracts/worldtree_sdk_cutover.contract.md`). A thin adapter that owns ONE
+`WorldtreeClient`, built over ratatoskr's own injected `httpx.AsyncClient`
+transport, and translates the SDK's error floor into ratatoskr's caller-semantic
+exceptions. Two hard invariants anchor it:
+
+  * **INV-CUT-1** — ratatoskr owns the injected transport's lifecycle; the SDK is
+    given it as `transport=` (so `_owns_client=False`) and MUST NOT close it.
+  * **INV-CUT-2** — the adapter raises ratatoskr's caller-semantic exceptions; the
+    ROUTE is the discriminator (never the error body).
+
+This slice ships only the construction chokepoint (`build_client`) and the error
+adapter's DEFAULT rule (`translate_error`: `ApiError` → `SessionApiFailed`, every
+discriminated `WorldtreeError` subclass passing through unchanged). Route-specific
+error rows (`AgentNotFound`, `InvalidCursor`, `AuthoredHistoryUnavailable`, ...)
+and the CLI / web / TUI surface wiring land in later slices.
+
+Transient-migration note (DEC-4, incremental cutover): a same-named
+`SessionApiFailed` still lives in the retiring `ratatoskr.sessions` wrapper and
+serves the old hand-rolled path until slice-2 deletes it. No surface wires the
+adapter in this slice, so the two never meet at runtime; slice-2 reconciles them
+(deletes the `sessions.py` copy, points presenters at this one, which additionally
+carries the SDK's parsed `error_code`).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Mapping
+from typing import Any
+
+import httpx
+import worldtree_sdk as wtsdk
+from worldtree_sdk import ApiError, AuthProvider, CancelResult, WorldtreeClient
+
+# Transitional (slice-2): the caller-semantic exceptions + the BifrostBinding input
+# type still live in the retiring `sessions` / `sse_client` modules; they relocate
+# into this adapter as their call-sites are rewired in later slice-2 commits. wt →
+# sessions / sse_client is one-way (neither imports wt), so there is no cycle.
+from .sessions import (
+    AgentNotFound,
+    BifrostBinding,
+    BifrostConsumerKeyMissing,
+    BifrostHandshakeFailed,
+    InvalidCursor,
+)
+from .sse_client import (
+    AgentNotAvailable,
+    CancelAlreadyCompleted,
+    CancelFailed,
+    CancelTurnNotFound,
+    MalformedSseData,
+    MalformedSseId,
+    SseConnectFailed,
+    SseConnectionDropped,
+    TurnIdFlip,
+    TurnLaunchUnavailable,
+)
+
+
+class SessionApiFailed(Exception):
+    """The adapter's DEFAULT caller-semantic error (INV-CUT-2 default row): any SDK
+    `ApiError` not mapped to a more specific ratatoskr exception surfaces here,
+    carrying the SDK's cleanly-parsed `status` / `error_code` / `body` verbatim.
+    The `body` is already UTF-8-byte-bounded and bearer-scrubbed by the SDK."""
+
+    def __init__(self, *, status: int, error_code: str, body: str | None = None) -> None:
+        super().__init__(
+            f"worldtree API failed: status={status}, error_code={error_code!r}"
+        )
+        self.status = status
+        self.error_code = error_code
+        self.body = body
+
+
+def build_client(
+    base_url: str,
+    *,
+    api_key: AuthProvider,
+    admin_key: AuthProvider | None = None,
+    transport: httpx.AsyncClient,
+) -> WorldtreeClient:
+    """Construct the adapter's `WorldtreeClient` over a ratatoskr-owned transport.
+
+    `transport` is REQUIRED and ratatoskr-owned: injecting it sets the SDK's
+    `_owns_client=False`, so `WorldtreeClient.aclose()` never closes it — ratatoskr
+    owns the lifecycle exactly as today (INV-CUT-1). ratatoskr's `api_key` /
+    `admin_key` map to the SDK's per-request `auth` / `admin_auth` providers; the
+    injected transport carries ratatoskr's User-Agent / timeout (wired by the
+    caller in slice-2), NOT the Authorization header — the SDK adds auth per
+    request.
+    """
+    return WorldtreeClient(
+        base_url,
+        auth=api_key,
+        admin_auth=admin_key,
+        transport=transport,
+    )
+
+
+def translate_error(exc: BaseException) -> BaseException:
+    """Map an SDK exception to ratatoskr's caller-semantic exception (INV-CUT-2).
+
+    Foundation scope — the § Error map DEFAULT plus discriminated passthrough:
+      * SDK `ApiError` (the undiscriminated REST floor) → `SessionApiFailed`
+        carrying `status` / `error_code` / `body`.
+      * Every other exception — the SDK's discriminated `WorldtreeError` subclasses
+        (`AgentNotAvailable`, `SessionRetired`, `ResumeError`, `Cancel*`, ...) and
+        any non-SDK error — passes through by IDENTITY, unchanged.
+
+    Route-specific rows (a 404 on `sessions.create` → `AgentNotFound`, a 404 on
+    `sessions.write_history` → `AuthoredHistoryUnavailable`, ...) are the ROUTE's
+    to add at its call-site in later slices, never inferred from the body here.
+    """
+    if isinstance(exc, ApiError):
+        return SessionApiFailed(
+            status=exc.status, error_code=exc.error_code, body=exc.body
+        )
+    return exc
+
+
+# ── slice-2: sessions/turn adapter routes ────────────────────────────────────
+# Ratatoskr-semantic call surfaces over `WorldtreeClient.sessions.*`. Each builds
+# the request from ratatoskr's domain params, delegates the HTTP to the SDK, and
+# maps the SDK's `ApiError` floor by ROUTE (INV-CUT-2) — route-specific rows first,
+# `translate_error`'s `SessionApiFailed` default otherwise. Open-world reads are
+# returned verbatim (the parity-pass posture: presenters read them as mappings,
+# tolerant of wire drift). The turn STREAM + cancel land alongside the presenter
+# rewire in the next slice-2 commit.
+
+
+def _bifrost_error_from_body(body: str | None) -> str | None:
+    """Pull the spec-level `bifrost_error` from a bound-create 502 body string.
+
+    Tolerates both the FastAPI-nested `{"detail": {"bifrost_error": …}}` shape (the
+    real wire form) and a flat top-level `bifrost_error` — the same both-shape
+    unwrap the hand-rolled path used, adapted to the SDK's already-parsed str body.
+    """
+    if not body:
+        return None
+    try:
+        err = json.loads(body)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(err, dict):
+        return None
+    bifrost_error = err.get("bifrost_error")
+    if bifrost_error is None and isinstance(err.get("detail"), dict):
+        bifrost_error = err["detail"].get("bifrost_error")
+    return bifrost_error
+
+
+async def create_session(
+    client: WorldtreeClient,
+    agent_id: str,
+    *,
+    end_user_id: str | None = None,
+    bifrost: BifrostBinding | None = None,
+    consumer_key: str | None = None,
+    config: Mapping[str, Any] | None = None,
+) -> Mapping[str, Any]:
+    """Create a session (POST /sessions), returning the open-world create result.
+
+    Body-building mirrors the hand-rolled path: `{agent_id}` plus `end_user_id` /
+    `config` / `bifrost` when set. A bound create authenticates with `consumer_key`
+    via the SDK's per-request auth (never a header, never the canary fallback —
+    INV-001); the key is required pre-HTTP. Error map (INV-CUT-2): 404 →
+    `AgentNotFound`; a bound 502 → `BifrostHandshakeFailed`; otherwise the
+    `SessionApiFailed` default.
+    """
+    assert agent_id and isinstance(agent_id, str)
+    assert end_user_id is None or (isinstance(end_user_id, str) and end_user_id)
+    assert config is None or isinstance(config, Mapping)
+    # Ephemeral config + Bifrost binding are mutually exclusive (server 422s).
+    assert not (config is not None and bifrost is not None)
+    # INV-001: a bound create REQUIRES a non-empty consumer key — enforced pre-HTTP
+    # so it never falls back to the canary bearer.
+    if bifrost is not None and not (isinstance(consumer_key, str) and consumer_key):
+        raise BifrostConsumerKeyMissing()
+
+    body: dict[str, Any] = {"agent_id": agent_id}
+    if end_user_id is not None:
+        body["end_user_id"] = end_user_id
+    if config is not None:
+        body["config"] = dict(config)
+    if bifrost is not None:
+        body["bifrost"] = {"endpoint_url": bifrost.endpoint_url, "scope": bifrost.scope}
+
+    try:
+        return await client.sessions.create(body, consumer_key=consumer_key)
+    except ApiError as exc:
+        if exc.status == 404:
+            raise AgentNotFound(agent_id=agent_id) from exc
+        if bifrost is not None and exc.status == 502:
+            raise BifrostHandshakeFailed(
+                bifrost_error=_bifrost_error_from_body(exc.body),
+                body=(exc.body or "").encode(),
+            ) from exc
+        raise translate_error(exc) from exc
+
+
+async def list_sessions(
+    client: WorldtreeClient,
+    *,
+    include_archived: bool = False,
+    limit: int = 50,
+    cursor: str | None = None,
+) -> Mapping[str, Any]:
+    """List sessions (GET /sessions), returning the open-world page verbatim. A 422
+    `cursor_invalid` → `InvalidCursor`; otherwise the `SessionApiFailed` default."""
+    assert 1 <= limit <= 200
+    assert cursor is None or (isinstance(cursor, str) and cursor)
+    try:
+        return await client.sessions.list(
+            limit=limit, cursor=cursor, include_archived=include_archived or None
+        )
+    except ApiError as exc:
+        if exc.status == 422 and exc.error_code == "cursor_invalid":
+            raise InvalidCursor(raw=cursor) from exc
+        raise translate_error(exc) from exc
+
+
+async def get_session_messages(
+    client: WorldtreeClient, session_id: str
+) -> Mapping[str, Any]:
+    """The session's message history (GET /sessions/{id}/messages), verbatim. Any
+    error → the `SessionApiFailed` default (owner-scoped; 404 hide-existence stays
+    generic here — messages is not a hide-existence-mapped route)."""
+    assert session_id and isinstance(session_id, str)
+    try:
+        return await client.sessions.messages(session_id)
+    except ApiError as exc:
+        raise translate_error(exc) from exc
+
+
+async def get_session_tools(
+    client: WorldtreeClient, session_id: str
+) -> Mapping[str, Any]:
+    """The owner-scoped tool inventory (GET /sessions/{id}/tools), verbatim. Any
+    error → the `SessionApiFailed` default."""
+    assert session_id and isinstance(session_id, str)
+    try:
+        return await client.sessions.tools(session_id)
+    except ApiError as exc:
+        raise translate_error(exc) from exc
+
+
+async def stream_turn(
+    client: WorldtreeClient, session_id: str, content: str
+) -> AsyncIterator[wtsdk.TurnEvent]:
+    """Drive the resilient turn stream (auto-resume; absorbs the old `reconnect_turn`)
+    and yield the SDK's `TurnEvent`s, re-wrapping the stream's TERMINAL SDK errors
+    into ratatoskr's caller-semantic exceptions (INV-CUT-2 / DEC-2 — the presenter
+    keeps catching ratatoskr's types).
+
+    The SDK's `stream_turn` retries only the transport-drop class internally; a
+    resume failure / protocol violation / connect failure surfaces unchanged
+    (B-RES-6), and a drop that exhausts the reconnect budget surfaces as
+    `ConnectionDropped`. The eager launch failures (`AgentNotAvailable` 409,
+    `TurnLaunchUnavailable` 503) and `SessionRetired` 410 are subclasses of the
+    SDK's `ConnectFailed`, so they are caught before the generic `ConnectFailed`.
+    """
+    try:
+        async for event in client.sessions.stream_turn(session_id, content):
+            yield event
+    except wtsdk.SessionRetired as exc:
+        # Fresh-mode 410 → the session is gone server-side; a generic API failure.
+        raise SessionApiFailed(
+            status=exc.status, error_code=exc.error_code, body=exc.message
+        ) from exc
+    except wtsdk.AgentNotAvailable as exc:
+        raise AgentNotAvailable(
+            body=(exc.message or "").encode(),
+            error_code=exc.error_code,
+            message=exc.message or "",
+        ) from exc
+    except wtsdk.TurnLaunchUnavailable as exc:
+        raise TurnLaunchUnavailable(
+            body=(exc.message or "").encode(),
+            error_code=exc.error_code,
+            message=exc.message or "",
+        ) from exc
+    except wtsdk.ConnectFailed as exc:
+        raise SseConnectFailed(status=exc.status, body=(exc.message or "").encode()) from exc
+    except wtsdk.ResumeError as exc:
+        # A terminal resume failure (the resilient stream absorbs the retryable ones).
+        raise SseConnectFailed(status=exc.status, body=(exc.message or "").encode()) from exc
+    except wtsdk.ConnectionDropped as exc:
+        raise SseConnectionDropped(last_seen_sse_id=exc.last_seen_sse_id) from exc
+    except wtsdk.MalformedSseId as exc:
+        raise MalformedSseId(raw=exc.raw) from exc
+    except wtsdk.MalformedSseData as exc:
+        raise MalformedSseData(raw=exc.raw) from exc
+    except wtsdk.TurnIdFlip as exc:
+        raise TurnIdFlip(established=exc.established, got=exc.got) from exc
+
+
+async def cancel_turn(
+    client: WorldtreeClient, session_id: str, turn_id: int, *, persist_partial: bool = False
+) -> CancelResult:
+    """Cancel a running turn (POST /sessions/{id}/turns/{turn_id}/cancel). Returns the
+    SDK `CancelResult` (a 200 with `cancelled=False` is the benign late-cancel race,
+    not an error). The typed cancel races map onto ratatoskr's same-named exceptions
+    (DEC-2): 404 `turn_not_found` → `CancelTurnNotFound`, 409 `turn_finished` →
+    `CancelAlreadyCompleted`, any other cancel failure → `CancelFailed`."""
+    assert session_id and isinstance(session_id, str)
+    assert isinstance(turn_id, int) and turn_id > 0
+    try:
+        return await client.sessions.cancel_turn(
+            session_id, turn_id, persist_partial=persist_partial
+        )
+    except wtsdk.CancelTurnNotFound as exc:
+        raise CancelTurnNotFound(turn_id=turn_id) from exc
+    except wtsdk.CancelAlreadyCompleted as exc:
+        raise CancelAlreadyCompleted(turn_id=turn_id) from exc
+    except wtsdk.CancelError as exc:
+        raise CancelFailed(
+            status=0, body=(getattr(exc, "message", "") or str(exc)).encode()
+        ) from exc

tests/test_wt.py

@@ -0,0 +1,412 @@
+"""Unit tests for the worldtree-sdk adapter (`ratatoskr.wt`) — slice-1 foundation.
+
+Covers the two foundation surfaces (issue #20 cutover contract, slice 1):
+  * `build_client` — construction wiring + injected-transport ownership (INV-CUT-1:
+    the SDK must never close ratatoskr's transport).
+  * `translate_error` — the § Error map DEFAULT (`ApiError` → `SessionApiFailed`)
+    plus discriminated-`WorldtreeError` passthrough (INV-CUT-2).
+
+No ratatoskr surface (CLI / web / TUI) is exercised here — that wiring lands in
+slice 2. These tests hit no network (WorldtreeClient does no I/O at construction).
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import httpx
+import pytest
+import worldtree_sdk as wtsdk
+from worldtree_sdk import ApiError, CancelResult, WorldtreeClient
+
+from ratatoskr.sessions import (
+    AgentNotFound,
+    BifrostBinding,
+    BifrostConsumerKeyMissing,
+    BifrostHandshakeFailed,
+    InvalidCursor,
+)
+from ratatoskr.sse_client import (
+    AgentNotAvailable,
+    CancelAlreadyCompleted,
+    CancelFailed,
+    CancelTurnNotFound,
+    MalformedSseData,
+    MalformedSseId,
+    SseConnectFailed,
+    SseConnectionDropped,
+    TurnIdFlip,
+    TurnLaunchUnavailable,
+)
+from ratatoskr.wt import (
+    SessionApiFailed,
+    build_client,
+    cancel_turn,
+    create_session,
+    get_session_messages,
+    get_session_tools,
+    list_sessions,
+    stream_turn,
+    translate_error,
+)
+
+
+class _FakeSessions:
+    """A stand-in for `WorldtreeClient.sessions` — records the last call and
+    returns a canned result or raises a canned error. Lets the adapter's
+    body-building + error-mapping be unit-tested without any SDK HTTP."""
+
+    def __init__(
+        self,
+        *,
+        result: Any = None,
+        error: BaseException | None = None,
+        events: list[Any] | None = None,
+        stream_error: BaseException | None = None,
+    ) -> None:
+        self._result = result
+        self._error = error
+        self._events = events or []
+        self._stream_error = stream_error
+        self.calls: list[tuple[str, tuple[Any, ...], dict[str, Any]]] = []
+
+    async def _dispatch(self, name: str, *args: Any, **kwargs: Any) -> Any:
+        self.calls.append((name, args, kwargs))
+        if self._error is not None:
+            raise self._error
+        return self._result
+
+    async def create(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("create", *args, **kwargs)
+
+    async def list(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("list", *args, **kwargs)
+
+    async def messages(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("messages", *args, **kwargs)
+
+    async def tools(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("tools", *args, **kwargs)
+
+    def stream_turn(self, *args: Any, **kwargs: Any) -> Any:
+        self.calls.append(("stream_turn", args, kwargs))
+        return self._astream()
+
+    async def _astream(self) -> Any:
+        for event in self._events:
+            yield event
+        if self._stream_error is not None:
+            raise self._stream_error
+
+    async def cancel_turn(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._dispatch("cancel_turn", *args, **kwargs)
+
+
+class _FakeClient:
+    def __init__(self, sessions: _FakeSessions) -> None:
+        self.sessions = sessions
+
+
+def _wt(sessions: _FakeSessions) -> WorldtreeClient:
+    """Cast the structural fake to the nominal client type the adapter is typed
+    against — the route functions only touch `client.sessions.*`, which the fake
+    provides. (No network; construction does no I/O.)"""
+    return cast(WorldtreeClient, _FakeClient(sessions))
+
+
+class TestBuildClient:
+    async def test_constructs_worldtree_client(self) -> None:
+        transport = httpx.AsyncClient()
+        try:
+            client = build_client(
+                "https://wt.example:8081", api_key="ck-test", transport=transport
+            )
+            assert isinstance(client, WorldtreeClient)
+            assert client.base_url == "https://wt.example:8081"
+        finally:
+            await transport.aclose()
+
+    async def test_injected_transport_is_ratatoskr_owned(self) -> None:
+        # INV-CUT-1 [hard]: aclose() on the SDK client must NOT close ratatoskr's
+        # transport — ratatoskr owns the lifecycle exactly as it does today.
+        transport = httpx.AsyncClient()
+        client = build_client("https://wt.example", api_key="ck", transport=transport)
+        await client.aclose()
+        assert client.closed is True
+        assert transport.is_closed is False
+        await transport.aclose()
+
+    async def test_admin_key_optional(self) -> None:
+        transport = httpx.AsyncClient()
+        try:
+            # Absent admin_key → admin_auth=None; still constructs.
+            without_admin = build_client(
+                "https://wt.example", api_key="ck", transport=transport
+            )
+            assert isinstance(without_admin, WorldtreeClient)
+            # Present admin_key → constructs (admin surface available in later slices).
+            with_admin = build_client(
+                "https://wt.example", api_key="ck", admin_key="ak", transport=transport
+            )
+            assert isinstance(with_admin, WorldtreeClient)
+        finally:
+            await transport.aclose()
+
+
+class TestTranslateError:
+    def test_apierror_maps_to_session_api_failed_default(self) -> None:
+        exc = ApiError("some_code", "boom", status=500, body="raw-body")
+        mapped = translate_error(exc)
+        assert isinstance(mapped, SessionApiFailed)
+        assert mapped.status == 500
+        assert mapped.error_code == "some_code"
+        assert mapped.body == "raw-body"
+
+    def test_apierror_with_no_body_maps_cleanly(self) -> None:
+        exc = ApiError("nope", "no body", status=404)
+        mapped = translate_error(exc)
+        assert isinstance(mapped, SessionApiFailed)
+        assert mapped.status == 404
+        assert mapped.error_code == "nope"
+        assert mapped.body is None
+
+    def test_discriminated_subclass_passes_through_unchanged(self) -> None:
+        # Discriminated WorldtreeError subclasses are already the right semantic
+        # type at the REST layer — translate_error passes them through by identity
+        # (the stream routes re-wrap them; that is stream_turn's job, not this one).
+        exc = wtsdk.AgentNotAvailable("agent_not_available", "gone", status=409)
+        assert translate_error(exc) is exc
+
+    def test_non_worldtree_error_passes_through_unchanged(self) -> None:
+        exc = ValueError("unrelated")
+        assert translate_error(exc) is exc
+
+
+class TestCreateSession:
+    async def test_happy_returns_sdk_dict_and_builds_body(self) -> None:
+        info = {"session_id": "s-1", "agent_id": "mimir", "created_at": "t", "last_active": "t"}
+        fake = _FakeSessions(result=info)
+        client = _wt(fake)
+        out = await create_session(client, "mimir", end_user_id="u-9")
+        assert out is info  # open-world passthrough — no re-shaping
+        name, args, kwargs = fake.calls[-1]
+        assert name == "create"
+        assert args[0] == {"agent_id": "mimir", "end_user_id": "u-9"}
+        assert kwargs["consumer_key"] is None
+
+    async def test_config_passthrough(self) -> None:
+        fake = _FakeSessions(result={"session_id": "s"})
+        await create_session(
+            _wt(fake), "echo", config={"system_prompt": "be terse"}
+        )
+        assert fake.calls[-1][1][0] == {
+            "agent_id": "echo",
+            "config": {"system_prompt": "be terse"},
+        }
+
+    async def test_bifrost_bound_body_and_consumer_key(self) -> None:
+        fake = _FakeSessions(result={"session_id": "s"})
+        binding = BifrostBinding(endpoint_url="http://h:8391", scope=None)
+        await create_session(
+            _wt(fake), "sindra", bifrost=binding, consumer_key="ck-real"
+        )
+        _name, args, kwargs = fake.calls[-1]
+        assert args[0] == {
+            "agent_id": "sindra",
+            "bifrost": {"endpoint_url": "http://h:8391", "scope": None},
+        }
+        # INV-CUT: the consumer key rides the SDK's per-request auth, NOT a header.
+        assert kwargs["consumer_key"] == "ck-real"
+
+    async def test_bifrost_without_consumer_key_rejected_pre_http(self) -> None:
+        fake = _FakeSessions(result={"session_id": "s"})
+        binding = BifrostBinding(endpoint_url="http://h:8391", scope=None)
+        with pytest.raises(BifrostConsumerKeyMissing):
+            await create_session(_wt(fake), "sindra", bifrost=binding)
+        assert fake.calls == []  # never reached the SDK
+
+    async def test_404_maps_to_agent_not_found(self) -> None:
+        fake = _FakeSessions(error=ApiError("agent_not_found", "no", status=404))
+        with pytest.raises(AgentNotFound) as ei:
+            await create_session(_wt(fake), "ghost")
+        assert ei.value.agent_id == "ghost"
+
+    async def test_bound_502_maps_to_bifrost_handshake_failed(self) -> None:
+        body = '{"detail": {"bifrost_error": "bifrost.auth_rejected"}}'
+        fake = _FakeSessions(
+            error=ApiError("bifrost_handshake_failed", "boom", status=502, body=body)
+        )
+        binding = BifrostBinding(endpoint_url="http://h:8391", scope=None)
+        with pytest.raises(BifrostHandshakeFailed) as ei:
+            await create_session(
+                _wt(fake), "sindra", bifrost=binding, consumer_key="ck"
+            )
+        assert ei.value.bifrost_error == "bifrost.auth_rejected"
+
+    async def test_unbound_502_stays_session_api_failed(self) -> None:
+        fake = _FakeSessions(error=ApiError("upstream", "boom", status=502, body="x"))
+        with pytest.raises(SessionApiFailed) as ei:
+            await create_session(_wt(fake), "mimir")
+        assert ei.value.status == 502
+
+    async def test_default_error_maps_to_session_api_failed(self) -> None:
+        fake = _FakeSessions(error=ApiError("weird", "boom", status=418, body="teapot"))
+        with pytest.raises(SessionApiFailed) as ei:
+            await create_session(_wt(fake), "mimir")
+        assert ei.value.status == 418
+        assert ei.value.error_code == "weird"
+
+
+class TestListSessions:
+    async def test_passes_params_and_returns_dict(self) -> None:
+        page: dict[str, Any] = {"items": [], "next_cursor": None}
+        fake = _FakeSessions(result=page)
+        out = await list_sessions(_wt(fake), limit=10, cursor="c1", include_archived=True)
+        assert out is page
+        kwargs = fake.calls[-1][2]
+        assert kwargs["limit"] == 10
+        assert kwargs["cursor"] == "c1"
+        assert kwargs["include_archived"] is True
+
+    async def test_422_cursor_invalid_maps_to_invalid_cursor(self) -> None:
+        fake = _FakeSessions(error=ApiError("cursor_invalid", "bad", status=422))
+        with pytest.raises(InvalidCursor) as ei:
+            await list_sessions(_wt(fake), cursor="bogus")
+        assert ei.value.raw == "bogus"
+
+    async def test_other_422_stays_session_api_failed(self) -> None:
+        fake = _FakeSessions(error=ApiError("validation_failed", "x", status=422))
+        with pytest.raises(SessionApiFailed):
+            await list_sessions(_wt(fake))
+
+
+class TestReadPassthroughs:
+    async def test_messages_returns_dict(self) -> None:
+        data = {"session_id": "s", "items": []}
+        fake = _FakeSessions(result=data)
+        assert await get_session_messages(_wt(fake), "s") is data
+        assert fake.calls[-1][0] == "messages"
+
+    async def test_tools_returns_dict(self) -> None:
+        data = {"agent_id": "mimir", "builtin_tools": []}
+        fake = _FakeSessions(result=data)
+        assert await get_session_tools(_wt(fake), "s") is data
+        assert fake.calls[-1][0] == "tools"
+
+    async def test_messages_error_maps_to_session_api_failed(self) -> None:
+        fake = _FakeSessions(error=ApiError("auth_revoked", "no", status=401))
+        with pytest.raises(SessionApiFailed) as ei:
+            await get_session_messages(_wt(fake), "s")
+        assert ei.value.status == 401
+
+
+async def _drain(aiter: Any) -> list[Any]:
+    out: list[Any] = []
+    async for ev in aiter:
+        out.append(ev)
+    return out
+
+
+class TestStreamTurn:
+    async def test_yields_events_verbatim(self) -> None:
+        e1, e2 = object(), object()
+        fake = _FakeSessions(events=[e1, e2])
+        got = await _drain(stream_turn(_wt(fake), "s-1", "hello"))
+        assert got == [e1, e2]
+        assert fake.calls[-1] == ("stream_turn", ("s-1", "hello"), {})
+
+    async def test_session_retired_maps_to_session_api_failed(self) -> None:
+        fake = _FakeSessions(
+            stream_error=wtsdk.SessionRetired("session_retired", "gone", status=410)
+        )
+        with pytest.raises(SessionApiFailed) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert ei.value.status == 410
+        assert ei.value.error_code == "session_retired"
+
+    async def test_agent_not_available_rewraps_to_ratatoskr(self) -> None:
+        fake = _FakeSessions(
+            stream_error=wtsdk.AgentNotAvailable("agent_not_available", "no agent", status=409)
+        )
+        with pytest.raises(AgentNotAvailable) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert ei.value.error_code == "agent_not_available"
+        assert ei.value.status == 409
+
+    async def test_turn_launch_unavailable_rewraps_to_ratatoskr(self) -> None:
+        fake = _FakeSessions(
+            stream_error=wtsdk.TurnLaunchUnavailable("not_ready", "busy", status=503)
+        )
+        with pytest.raises(TurnLaunchUnavailable) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert ei.value.retryable is True
+
+    async def test_generic_connect_failed_maps_to_sse_connect_failed(self) -> None:
+        fake = _FakeSessions(stream_error=wtsdk.ConnectFailed("connect_failed", "boom", status=500))
+        with pytest.raises(SseConnectFailed) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert ei.value.status == 500
+
+    async def test_connection_dropped_maps_and_carries_cursor(self) -> None:
+        fake = _FakeSessions(stream_error=wtsdk.ConnectionDropped("12:3"))
+        with pytest.raises(SseConnectionDropped) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert ei.value.last_seen_sse_id == "12:3"
+
+    async def test_resume_error_maps_to_sse_connect_failed(self) -> None:
+        fake = _FakeSessions(stream_error=wtsdk.ResumeError("resume_failed", "boom", status=412))
+        with pytest.raises(SseConnectFailed) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert ei.value.status == 412
+
+    async def test_malformed_sse_id_passes_through_as_ratatoskr(self) -> None:
+        fake = _FakeSessions(stream_error=wtsdk.MalformedSseId("bad-id"))
+        with pytest.raises(MalformedSseId) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert ei.value.raw == "bad-id"
+
+    async def test_malformed_sse_data_passes_through_as_ratatoskr(self) -> None:
+        fake = _FakeSessions(stream_error=wtsdk.MalformedSseData("not json"))
+        with pytest.raises(MalformedSseData):
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+
+    async def test_turn_id_flip_carries_established_and_got(self) -> None:
+        fake = _FakeSessions(stream_error=wtsdk.TurnIdFlip(5, 7))
+        with pytest.raises(TurnIdFlip) as ei:
+            await _drain(stream_turn(_wt(fake), "s", "hi"))
+        assert (ei.value.established, ei.value.got) == (5, 7)
+
+
+class TestCancelTurn:
+    async def test_happy_returns_cancel_result(self) -> None:
+        res = CancelResult(turn_id=42, cancelled=True, reason=None, partial_message_id=None)
+        fake = _FakeSessions(result=res)
+        out = await cancel_turn(_wt(fake), "s-1", 42, persist_partial=True)
+        assert out is res
+        assert fake.calls[-1] == ("cancel_turn", ("s-1", 42), {"persist_partial": True})
+
+    async def test_late_cancel_race_is_a_result_not_an_error(self) -> None:
+        # B-CAN-3: a 200 with cancelled=False is the benign late-cancel no-op.
+        res = CancelResult(turn_id=42, cancelled=False, reason=None, partial_message_id=None)
+        out = await cancel_turn(_wt(_FakeSessions(result=res)), "s", 42)
+        assert out.cancelled is False
+
+    async def test_turn_not_found_maps_to_ratatoskr(self) -> None:
+        fake = _FakeSessions(
+            error=wtsdk.CancelTurnNotFound(42, error_code="turn_not_found", message="gone")
+        )
+        with pytest.raises(CancelTurnNotFound) as ei:
+            await cancel_turn(_wt(fake), "s", 42)
+        assert ei.value.turn_id == 42
+
+    async def test_turn_finished_maps_to_ratatoskr(self) -> None:
+        fake = _FakeSessions(
+            error=wtsdk.CancelAlreadyCompleted(42, error_code="turn_finished", message="done")
+        )
+        with pytest.raises(CancelAlreadyCompleted):
+            await cancel_turn(_wt(fake), "s", 42)
+
+    async def test_other_cancel_failure_maps_to_cancel_failed(self) -> None:
+        fake = _FakeSessions(error=wtsdk.CancelFailed(42, error_code="boom", message="failed"))
+        with pytest.raises(CancelFailed):
+            await cancel_turn(_wt(fake), "s", 42)

uv.lock

@@ -472,11 +472,12 @@ wheels = [
 
 [[package]]
 name = "ratatoskr"
-version = "0.21.2"
+version = "0.21.5"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
     { name = "httpx-sse" },
+    { name = "worldtree-sdk" },
 ]
 
 [package.optional-dependencies]
@@ -519,6 +520,7 @@ requires-dist = [
     { name = "sqlite-vec", marker = "extra == 'provider'", specifier = ">=0.1.6" },
     { name = "starlette", marker = "extra == 'web'", specifier = ">=0.40" },
     { name = "uvicorn", extras = ["standard"], marker = "extra == 'web'", specifier = ">=0.30" },
+    { name = "worldtree-sdk", specifier = "==1.0.0", index = "https://gitea.phasefinal.com/api/packages/vh/pypi/simple/" },
 ]
 provides-extras = ["web", "provider", "dev"]
 
@@ -903,3 +905,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9f/3e/28135a24e384493fa804216b79a6a6759a38cc4ff59118787b9fb693df93/websockets-16.0-cp314-cp314t-win_amd64.whl", hash = "sha256:b14dc141ed6d2dde437cddb216004bcac6a1df0935d79656387bd41632ba0bbd", size = 178531 },
     { url = "https://files.pythonhosted.org/packages/6f/28/258ebab549c2bf3e64d2b0217b973467394a9cea8c42f70418ca2c5d0d2e/websockets-16.0-py3-none-any.whl", hash = "sha256:1637db62fad1dc833276dded54215f2c7fa46912301a24bd94d45d46a011ceec", size = 171598 },
 ]
+
+[[package]]
+name = "worldtree-sdk"
+version = "1.0.0"
+source = { registry = "https://gitea.phasefinal.com/api/packages/vh/pypi/simple/" }
+dependencies = [
+    { name = "httpx" },
+]
+sdist = { url = "https://gitea.phasefinal.com/api/packages/vh/pypi/files/worldtree-sdk/1.0.0/worldtree_sdk-1.0.0.tar.gz", hash = "sha256:0b87001fd90b304befe5e76d21a41dd093057a9d59f86a25189fab80defcd043" }
+wheels = [
+    { url = "https://gitea.phasefinal.com/api/packages/vh/pypi/files/worldtree-sdk/1.0.0/worldtree_sdk-1.0.0-py3-none-any.whl", hash = "sha256:ec9cb03ecdb4662bf1280a64316ee4545bb1330db42e3135f34f56e62c07f6c5" },
+]