ai.pouchy.companion 0.1.0-preview.10

package/CHANGELOG.md

@@ -0,0 +1,346 @@
+# Changelog
+
+All notable changes to the Pouchy Companion Unity/C# SDK are documented here.
+This project adheres to [Semantic Versioning](https://semver.org).
+
+> Parity note — **CORRECTED in 0.1.0-preview.6 (audit round 490)**. This note
+> used to read: "the JS SDK 0.35.0 per-request header deadline
+> (`requestTimeoutMs`) needs no port here — every request already runs under
+> `CompanionClientOptions.Timeout`". That stated the wrong conclusion as
+> settled. Running under *a* deadline was never the question; the point of the
+> JS work is that the flat default is RAISED on the routes whose server handler
+> declares `maxDuration: 300`, and this client's flat 90s was BELOW that ceiling
+> on three of them. Ported in 0.1.0-preview.6 as
+> `CompanionClientOptions.LongWorkTimeout`. Recorded here rather than rewritten
+> away, because a parity ledger that quietly edits its own wrong entries is not
+> auditable.
+
+> Parity ledger — JS surfaces not yet ported (recorded audit round 26, so the
+> gap is a decision, not drift): `handles`/`contextKinds` hello options (the
+> game track's core play-along declaration — the natural NEXT port here),
+> representative mode (`visitor` + `pairVisitor`), `GetAvatar` (a Unity host
+> rendering the companion is a primary consumer), and binary `IngestFile`
+> (`IngestKnowledgeAsync` text is covered). All are single REST calls — port
+> on demand.
+>
+> Added audit round 32: JS `setToken` (swap the bearer token on a live client
+> after ~1h session-token expiry) is also unported — `_token` is readonly
+> here, so a Unity host currently reconnects with a fresh client instead (the
+> session survives: a fresh token for the same user resumes the same session).
+> Python gained `set_token()` this round; port here on demand.
+>
+> Added audit round 361: `EndSessionAsync()` cannot carry the VOICE `transcript`
+> (nor `callGen`) — it posts an empty object. Voice audio is provider-direct, so
+> that field is the only path from anything said aloud into long-term memory. A
+> Unity host is a PRIMARY consumer here (a game that runs its own voice call and
+> uses this client for the session plane loses the entire call at hangup — the
+> server answers `skipped: 'no_content'`). The Dart SDK closed this in
+> `pouchy_companion` 0.1.1; port here on demand — one optional argument, and the
+> wire field has always existed.
+
+## 0.1.0-preview.10 — 2026-08-21
+
+- **The RAW client's documented reconnect loop no longer hot-loops against a
+  gateway that accepts and instantly closes.** preview.9 clamped this shape in
+  `EventStreamPump` — and the README's raw-client idiom one paragraph earlier
+  ("call `StreamEventsAsync` again"; the Go/Python caller-owned-loop contract)
+  stayed un-clamped, exactly the carrier class #523 closed for Python/Go/Dart.
+  `StreamEventsAsync` now sleeps an escalating 1→2→4→8s before opening a
+  window whenever the previous window ended cleanly, delivered **zero
+  envelopes**, and lived under 2s from headers-received — a shape a healthy
+  origin cannot produce (every real window opens with `hello.ack` and closes
+  at ~45s). Any delivered envelope clears the ladder at delivery; an errored
+  window leaves it alone (errors still throw immediately, and backing off on
+  errors is already the caller's documented job). The bound is 2s
+  post-headers — the JS client's stamp — which preview.9's pump could not
+  use from outside the client; the pump keeps its coarser 5s
+  handshake-inclusive guard, and when both fire the delays add (bounded).
+
+## 0.1.0-preview.9 — 2026-08-21
+
+- **`EventStreamPump` no longer hot-loops against a gateway that accepts and
+  instantly closes.** preview.8's policy — "clean window close → reconnect
+  immediately" — was written for the server's designed ~45s cadence, but it
+  also fired on a clean close a gateway produced in milliseconds
+  (auth-as-close, an LB idle policy, a misconfigured proxy). Every reconnect
+  got the same instant close, so the pump reconnected in a zero-delay hot
+  loop: unbounded requests against the gateway and a pinned core on the
+  device. This is the exact shape the JS client's WS leg has guarded since
+  its 0.35.0 short-lived-connection clamp; the pump claimed to mirror that
+  clamp and ported only the error half. Now a clean close that delivered
+  **zero events** in under 5s climbs the existing 1→30s ladder (silently —
+  a clean close is not an error, so `onError` stays quiet). A window that
+  delivered an event, however short, and a zero-event window that ran the
+  designed cadence both keep the immediate reconnect, so idle-but-healthy
+  subscriptions pay nothing. The bound is 5s where the JS clamp is 2s
+  because this measurement includes the handshake (the client exposes no
+  headers-received instant); both sit far below the 45s cadence.
+
+## 0.1.0-preview.8 — 2026-08-21
+
+- **`PouchyCompanionBehaviour` is now an always-on subscription —
+  previously it went silent after exactly one stream window (~45s).**
+  The raw `StreamEventsAsync` consumes ONE window and returns when the
+  server closes it, which it does cleanly every ~45s by design (the
+  go/python idiom: the caller owns the loop). The behaviour called it
+  once, so a Unity host received events for 45 seconds and then silently
+  nothing, forever — the same user-visible shape as the Go cursor defect
+  (#492), reached through a missing loop instead of a poisoned cursor,
+  in the one component whose whole point is that a designer wires it in
+  the Inspector and never writes the loop themselves.
+- **New: `EventStreamPump.RunAsync(client, onEvent, onError, ct)`** —
+  the engine-agnostic reconnect loop the behaviour now rides, public so
+  a pure .NET host gets the same always-on subscription without owning
+  the policy. Clean window close → immediate reconnect (the cursor has
+  advanced; nothing is lost or replayed) and the backoff ladder resets;
+  errors surface via `onError` and retry after
+  `max(ladder, min(RetryAfter, 60s))` with a 1,2,4,8,16,30s ladder — the
+  server can only ever slow the loop down, and a window that delivered
+  events resets the ladder (a working-then-dying link is a fresh
+  incident, not an escalation). `not_connected` stops the pump: the
+  session was ended on purpose and a retry can never mint it back.
+  Cancellation returns quietly, teardown noise included; `RunAsync`
+  never throws, which is what makes it safe to fire-and-forget from a
+  component lifecycle method. Handshake failures in the behaviour remain
+  fatal (a bad/expired token cannot be retried into working).
+- Proven in the package's own runner: 6 new `dotnet test` cases
+  (reconnect-and-resume-from-cursor, RetryAfter-honouring backoff, the
+  60s cap, ladder reset, `not_connected` stop, ladder shape), and four
+  hand-run mutations each fail exactly the intended case — removing the
+  loop (the defect itself), `min` for `max` on RetryAfter, dropping the
+  delivered-reset, dropping the `not_connected` stop. The repo-side
+  cross-SDK gate pins the pump policy and pins that the behaviour rides
+  the pump rather than the bare one-shot call.
+
+## 0.1.0-preview.7 — 2026-08-21
+
+- **The event stream bounds byte-SILENCE —
+  `CompanionClientOptions.StreamStallTimeout` (default 60s).** A half-open
+  TCP drop (a NAT/LB idle-kill eats the FIN; no close ever arrives) left
+  `StreamEventsAsync` blocked forever on a socket that would never speak
+  again, with every later event silently lost — reproduced against the
+  pre-change client (one event delivered, then unbounded silence). The
+  server pings every 1.5s and closes each stream window at 45s, so a
+  HEALTHY connection is never byte-silent for a minute; 60s clears both
+  numbers, the same default and reasoning as the Go SDK's
+  `DefaultStreamStallTimeout`, Dart's `kStreamStallTimeout` and Python's
+  `read=60.0`. Armed per READ, not per stream — a healthy subscription is
+  never cut, and the host's own `onEvent` latency never counts as
+  silence. On a stall the call throws `CompanionError` (`Status` 0, code
+  `aborted`) whose message says what to do: call `StreamEventsAsync`
+  again, it resumes from `Cursor`. Zero/negative
+  (`Timeout.InfiniteTimeSpan`) disables the bound — the pre-preview.7
+  behaviour. Closes the C# half of CR-600 (the last SDK outside this
+  contract).
+- **`CompanionError.RetryAfter` now has a DOMAIN: finite and
+  non-negative, on both carriers.** The header parse was
+  `Math.Max(0.0, secs)` over a `double.TryParse` that accepts `"NaN"`
+  and `"Infinity"` — and `Math.Max` PROPAGATES NaN by specification, so
+  a broken upstream's header reached the caller as NaN/Infinity, where
+  the README's own handler
+  (`Task.Delay(TimeSpan.FromSeconds(e.RetryAfter ?? 1))`) throws inside
+  the caller's catch block; a negative header clamped to 0, an instant
+  retry into the same 429. The body's `retryAfterSec` had NO domain at
+  all — and non-finite is reachable there from a fully COMPLIANT
+  producer, because the JSON overflow literal (`1e400`) is legal JSON
+  and Json.NET decodes it to `double.PositiveInfinity` (measured,
+  Newtonsoft 13.0.3). Both carriers now route through one `Sleepable`
+  predicate (the C# spelling of Go's `sleepableSeconds` / Dart's
+  `_sleepableSeconds` / Python's `_sleepable_seconds`): an out-of-domain
+  body value falls THROUGH to the header instead of suppressing it, an
+  out-of-domain header becomes `null`, and an HTTP-date already in the
+  past still clamps to 0 (that is clock skew from a compliant origin,
+  not corruption). Closes the C# halves of CR-613 and CR-615.
+- **The package gains a behavioural test suite**
+  (`dotnet test packages/unity-sdk/ci/tests/Tests.csproj` — net8, xunit,
+  no Unity editor needed): 28 cases driving the pure .NET client through
+  an injected `HttpClient` stub. Both fixes were reproduced there FIRST
+  (12 of 23 Retry-After cases fail against the preview.6 sources; the
+  stall hang reproduced at >6s), and four hand-run mutations each fail
+  exactly the intended case. The repo-side cross-SDK gates
+  (`retry-after.drift.test.ts`, `stream-cursor.drift.test.ts`) now pin
+  these tests by name; both of their C#-shaped `unbound`/exception books
+  are EMPTY for the first time.
+
+## 0.1.0-preview.6 — 2026-08-18
+
+- **Route-aware deadlines — `CompanionClientOptions.LongWorkTimeout`
+  (default 310s).** The client ran every request under one flat 90s
+  `Timeout`, armed as a single `CancellationTokenSource` under
+  `HttpCompletionOption.ResponseContentRead`, so it bounded the WHOLE
+  exchange. Three companion routes declare `maxDuration: 300` and are
+  reached by this client: `POST …/input` on the buffered (non-streaming)
+  leg, `POST …/tool-result` (the handler awaits the full billed
+  continuation inline), and `POST /api/companion/knowledge` (fetch +
+  chunk + embed all happen before the headers). The drive budget alone
+  is 240s, so 90s was exceeded by ordinary long turns rather than by
+  pathology — a succeeding, BILLED operation surfaced as
+  `request_timeout`, and the natural retry then raced the still-running
+  first request. `IsLongWork(method, path)` now selects
+  `LongWorkTimeout` for exactly those three; everything else keeps the
+  90s `Timeout`, including `POST …/confirm`, whose response is honestly
+  bounded at ~47s (35s tool box + 12s phrasing hop) and already fits.
+  **Additive and non-breaking**: `Timeout` keeps its name, type and
+  default, and lowering it for fast failure on ordinary reads no longer
+  re-introduces the cut on the three long routes. Same number and same
+  reasoning as the Go SDK's `LongWorkTimeout` and the JS SDK's
+  `BUFFERED_TURN_TIMEOUT_MS`.
+- **The streaming POST's deadline is disarmed once an SSE body is
+  confirmed**, so the options doc's claim about it holds by construction
+  rather than by whichever `HttpClientHandler` is underneath. Measured
+  on .NET 8 / `SocketsHttpHandler`: the fired token did NOT cut the body
+  (the read never receives it), so this was not an observed break there
+  — but Unity ships Mono's handler, which is a different implementation,
+  and the buffered fallback branch on the same code path deliberately
+  keeps its deadline because it reads a whole `maxDuration: 300` body.
+- **A `request_timeout` now names the deadline that actually fired**
+  rather than always quoting `Timeout` — a long-work timeout blamed on
+  the ordinary knob sends the integrator to the wrong setting.
+- Cross-SDK gate: `packages/unity-sdk` moves from `unbound` to `bound`
+  in `sdk-deadlines.drift.test.ts` and gains a block that binds this
+  client's predicate to the server's own `maxDuration` declarations in
+  both directions, so a new long route cannot land without a decision
+  here. Compiled and sentinel-checked before publishing
+  (`dotnet build packages/unity-sdk/ci/Compile.csproj`).
+
+- **`quota_exhausted` joined the wire vocabulary** (`Protocol.cs` —
+  `ErrorCodes.QuotaExhausted`, 402, NOT retryable; contrast `RateLimited`).
+  Arrived via the drift-gated regeneration when the JS SDK shipped it in
+  0.45.0 (2026-08-06); recorded here so the next preview release names it
+  instead of shipping it silently.
+- **The C# is compiled now — CR-169 closed.** The package went to npm having
+  never been read by a compiler; the wire vocabulary was drift-tested, the code
+  itself was not. It compiles clean: every `Runtime/*.cs` including
+  `PouchyCompanionBehaviour`, under Unity 2021.3's own profile (.NET Standard
+  2.1, C# 9, `UNITY_2021_1_OR_NEWER`) against the UnityEngine 2021.3.33
+  reference assemblies — **0 errors, 0 warnings**, with the .NET analyzers on.
+  The run is committed as `ci/Compile.csproj` and wired to
+  `.github/workflows/unity-sdk.yml`, so it is a gate rather than a one-time
+  result, and it needs no Unity install or licence on the runner.
+  Paired with a sentinel build that must FAIL: a green compile of code behind
+  `#if UNITY_2021_1_OR_NEWER` means nothing if the define or the engine
+  references stopped resolving, and the sentinel is what tells those apart.
+  **Still not proven, and stated plainly rather than implied away:** runtime
+  behaviour inside a real editor or player. No source or API change — this
+  release is the corrected status on the README, the package description and
+  the public `/sdk` reference, which all still said the compile pass was
+  pending.
+
+## 0.1.0-preview.5 — 2026-07-26
+
+- **`SummaryKey` / `SummaryVars` on `ConfirmRequestPayload` and `PendingConfirm`**
+  (JS SDK 0.43.0 parity). The confirmation sentence now also travels as data — an
+  i18n key plus its placeholder values — so a Unity host that knows the player's
+  language can render the approval in it. `Summary` is unchanged and still always
+  present; both new fields are null for a tool with no keyed summary and on
+  confirmations recorded before this release, so fall back to `Summary`.
+
+## 0.1.0-preview.4 — 2026-07-17
+
+### Added
+
+- **Paused-turn recovery fields (read-only), mirroring JS SDK 0.37.0:**
+  `HelloAckPayload.PendingToolCalls` (new `PendingToolCall` model —
+  `Id`, `Name`, `Args`, `TurnId?`, `PausedAt?`) lists the outstanding tool
+  calls of a turn paused before the handshake (non-empty only when the
+  session was resumed mid-pause), and `ToolCallPayload.Replayed` marks the
+  re-delivery of such a pause-orphaned call. A restarted host can complete
+  the paused turn by posting each result via `SendToolResultAsync` (server
+  apply is idempotent per call id) instead of abandoning it via
+  `EndSessionAsync`.
+
+> Parity note (preview.4): the JS SDK's `replayPendingToolCalls` AUTO-replay
+> is deliberately not ported — same decision as the Python SDK 0.1.6: this
+> client has no tool-call handler registry to replay into (integrators
+> consume the event stream themselves), so recovery stays the caller's
+> explicit `PendingToolCalls` → perform → `SendToolResultAsync` walk.
+> Recorded so the cross-SDK parity ledger stays auditable.
+
+## 0.1.0-preview.3 — 2026-07-17
+
+### Added
+
+- `SendTextResult.Duplicate` — the server has flagged replayed turnIds with
+  `duplicate: true` all along, but the client dropped the field on both send
+  paths, so a caller could not tell a replay from a fresh billed turn. Now
+  populated on the plain POST and the streaming `done` frame (null for a fresh
+  turn). The `SendTextAsync` doc also no longer claims a plain duplicate
+  "returns the recorded reply" — the recorded TEXT only rides back on the
+  streaming path.
+- `CompanionError(message, status, code, retryAfter, innerException)` overload,
+  used by the transport wrapping below to preserve the original exception.
+
+### Fixed
+
+- **Transport failures now throw `CompanionError`** (the README's "every failed
+  call throws CompanionError" was false for them): `HttpRequestException` and
+  the per-request deadline's `TaskCanceledException` escaped raw from
+  `RequestJsonAsync`, `SendTextStreamingAsync`, and `StreamEventsAsync`. They
+  are wrapped with `Status=0` and `Code="request_timeout"` (deadline elapsed) /
+  `"aborted"` (other transport failures, incl. a dropped body stream) — the JS
+  SDK's synthesized-code vocabulary — with the cause as `InnerException`.
+  Caller-token cancellation on the event stream is deliberately NOT wrapped
+  (it stays an `OperationCanceledException`, the behaviour's teardown signal).
+- **No more spurious `OnError` on teardown**: `PouchyCompanionBehaviour.OnDestroy`
+  cancels the CTS and disposes the response, which surfaced the resulting
+  `ObjectDisposedException`/`IOException` as an `OnError` on every normal
+  exit. `RunStreamAsync` now swallows any exception once cancellation was
+  requested.
+- `RequireSession` tags its error `Code="not_connected"` (the JS SDK's code for
+  the same misuse) instead of null, so switch-on-`Code` handling covers it.
+- `RetryAfter` also parses the RFC 9110 HTTP-date form of the `Retry-After`
+  header (delta from now, clamped at 0); only numeric seconds parsed before.
+- `CompanionClientOptions.Timeout` doc no longer overpromises: it reliably
+  bounds time-to-response-headers on the streaming input POST, not whole-body
+  reads.
+- README: escaped the `|` in the `SendWorldStateAsync(event \| events)` table
+  row (it split the GFM table cell); documented the transport-error codes.
+- UPM manifest: added the `license` field and shipped the SDK LICENSE file
+  (the companion-sdk license text, UPM-adapted).
+
+> Parity note (preview.3): `request_timeout` / `aborted` / `not_connected`
+> mirror the JS SDK's SDK_SYNTHESIZED_ERROR_CODES and Python 0.1.5 — one
+> cross-SDK error vocabulary. As in Python, `aborted` here covers any
+> non-timeout transport failure (there is no AbortSignal equivalent).
+
+## 0.1.0-preview.2 — 2026-07-15
+
+### Fixed
+
+- `IngestKnowledgeAsync` sent `{ "source": ... }`, but the server reads `name`
+  (title), `kind`, and `locale` and ignored `source` — so every ingested
+  document was titled "an uploaded file". The signature is now
+  `IngestKnowledgeAsync(text, name, kind, locale)` matching the server contract
+  and the JS/Python SDKs.
+
+## 0.1.0-preview.1 — 2026-07-14
+
+Initial preview release — the C# counterpart of the Python and JS companion
+SDKs, targeting Unity 2021.3+ (netstandard2.1) and plain .NET.
+
+### Added
+
+- `CompanionClient` (pure .NET, no UnityEngine dependency): `ConnectAsync`,
+  `SendTextAsync` (plain + streaming await-reply with `onDelta`),
+  `StreamEventsAsync` (SSE with typed payloads + auto-advancing cursor),
+  `PendingConfirmsAsync`, `ConfirmActionAsync`, `SendToolResultAsync`,
+  `SendWorldStateAsync` (single + batch), `HistoryAsync`, `RecallAsync`,
+  `RememberAsync`, `IngestKnowledgeAsync`, `GetWalletAsync`,
+  `SetModalitiesAsync`, `PingAsync`, `EndSessionAsync`.
+- `PouchyCompanionBehaviour` — optional Unity MonoBehaviour that owns a client,
+  streams events on a background Task, and marshals `OnMessage` / `OnTyping` /
+  `OnConfirmRequest` / `OnToolCall` / `OnError` onto the main thread.
+- Typed models (`Runtime/Models.cs`) for every payload in the wire protocol,
+  with `[JsonExtensionData]` forward-compat and an `OutboundPayloadTypes` map.
+- `CompanionError` with `Status` / `Code` / `RetryAfter`.
+- `Runtime/Protocol.cs` — the message-type and error-code vocabulary, generated
+  from the TypeScript source of truth.
+- UPM manifest (`ai.pouchy.companion`), Newtonsoft.Json dependency, asmdef.
+
+### Notes
+
+- **Wire protocol is drift-guarded** against `src/lib/companion-sdk/protocol.ts`
+  (Protocol.cs byte-equality + Models.cs field-name pins in CI).
+- **Compile verification pending** — this preview was authored without a local
+  .NET toolchain; the first Unity/CI compile pass will follow. Report issues.
+- Voice/WebRTC calls are intentionally out of scope (REST/SSE only).

package/LICENSE

@@ -0,0 +1,42 @@
+Pouchy Companion SDK License
+Copyright (c) 2026 Pouchy.ai. All Rights Reserved.
+
+This license governs use of the "ai.pouchy.companion" software package (the
+"SDK") as distributed for the Unity Package Manager. The SDK is proprietary
+software owned by Pouchy.ai. By installing, copying, or using the SDK you agree
+to these terms.
+
+1. GRANT. Subject to these terms, Pouchy.ai grants you a worldwide,
+   non-exclusive, non-transferable, royalty-free, revocable license to install
+   and use the SDK, as distributed, solely to build and operate applications
+   that integrate with Pouchy.ai's official services and APIs.
+
+2. RESTRICTIONS. Except to the extent a restriction below is prohibited by
+   applicable law, you may not:
+   (a) modify, adapt, or create derivative works of the SDK's source for
+       redistribution;
+   (b) redistribute, sublicense, sell, rent, or lease the SDK as a standalone
+       product, or republish it under a different name;
+   (c) reverse engineer, decompile, or disassemble the SDK except to the extent
+       necessary for interoperability and expressly permitted by law;
+   (d) use the SDK to build or operate a service that competes with Pouchy.ai's
+       services, or to access Pouchy.ai's services in violation of their terms;
+   (e) remove or alter any copyright, trademark, or other proprietary notices.
+
+3. RESERVATION OF RIGHTS. All rights not expressly granted are reserved by
+   Pouchy.ai. No rights are granted in Pouchy.ai's source repositories,
+   trademarks, or services beyond what is needed to use the SDK as described.
+
+4. TERMINATION. This license terminates automatically if you breach it. On
+   termination you must stop using and delete all copies of the SDK.
+
+5. NO WARRANTY. THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY. IN NO EVENT SHALL POUCHY.AI BE LIABLE FOR ANY CLAIM,
+   DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SDK OR THE USE OR
+   OTHER DEALINGS IN THE SDK.
+
+For any other use, or for written permission, contact legal@pouchy.ai.

package/README.md

@@ -0,0 +1,269 @@
+# Pouchy Companion — Unity / C# SDK
+
+A thin, typed C# client for the [Pouchy](https://pouchy.ai) companion REST/SSE
+plane — the same wire contract the JS (`@pouchy_ai/companion-sdk`) and Python
+(`pouchy-companion`) SDKs speak, aimed at **Unity games and .NET integrators**.
+
+> **⚠️ 0.1.0-preview** — the **wire protocol** is drift-tested against the
+> TypeScript source of truth (`Runtime/Protocol.cs` is generated; `Models.cs`
+> field names are pinned in CI), so the vocabulary cannot silently diverge.
+> The **C# compiles clean** — every `Runtime/*.cs`, `PouchyCompanionBehaviour`
+> included, under Unity 2021.3's own profile (.NET Standard 2.1, C# 9) against
+> the UnityEngine 2021.3 reference assemblies: 0 errors, 0 warnings — and the
+> pure .NET client is **behaviour-tested** (`dotnet test`, no editor needed:
+> error/backoff contract, event-stream stall handling). What is **still
+> unproven is runtime behaviour inside a real editor or player**. Please
+> report anything you hit to <support@pouchy.ai>.
+
+- `System.Net.Http.HttpClient` + async/await + **Newtonsoft.Json** — the pure
+  `CompanionClient` has **no UnityEngine dependency**, so it unit-tests outside
+  the editor. `PouchyCompanionBehaviour` is the optional Unity glue.
+- Typed models for every envelope/payload; unknown/newer server fields are
+  preserved (`[JsonExtensionData]`) instead of failing to parse.
+- Voice/WebRTC and browser-only surfaces are **deliberately out of scope**
+  (REST/SSE only) — they need a native WebRTC plugin. Use the JS SDK for embeds.
+
+## Install
+
+The package is published on npm and installs through a **UPM scoped registry**
+(Unity's Package Manager speaks the npm protocol natively). Add both blocks to
+your project's `Packages/manifest.json`:
+
+```json
+{
+  "scopedRegistries": [
+    {
+      "name": "Pouchy",
+      "url": "https://registry.npmjs.org",
+      "scopes": ["ai.pouchy"]
+    }
+  ],
+  "dependencies": {
+    "ai.pouchy.companion": "0.1.0-preview.10"
+  }
+}
+```
+
+Unity resolves it on the next editor focus; after that the package shows up in
+**Window → Package Manager → My Registries** with the normal version/upgrade UI.
+
+This package depends on **Newtonsoft.Json** via
+`com.unity.nuget.newtonsoft-json` (declared in `package.json`). If your project
+doesn't already resolve it, install *Newtonsoft Json* from the Package Manager
+(or add `"com.unity.nuget.newtonsoft-json": "3.2.1"` to your manifest).
+
+**Player settings:** the client uses `System.Net.Http`, so set **Project
+Settings → Player → Api Compatibility Level = .NET Standard 2.1** (Unity's
+default). On IL2CPP builds keep managed stripping at Low, or add a `link.xml`
+preserving `Pouchy.Companion` and `Newtonsoft.Json`, so the reflection-based
+JSON binding survives the AOT strip. (These are the two most likely
+first-compile/runtime snags — see the preview note above.)
+
+## Quickstart
+
+Mint a session token from **your backend** — one per end user. Never ship a
+secret key (`pchy_sk_…`) in a client build; the token is the client credential.
+
+```bash
+curl -X POST https://pouchy.ai/v1/sessions \
+  -H "Authorization: Bearer pchy_sk_…" \
+  -H "Content-Type: application/json" \
+  -d '{ "agent": "<agentId>", "external_user_id": "player_42" }'
+```
+
+### Plain .NET (`CompanionClient`)
+
+```csharp
+using Pouchy.Companion;
+
+using var client = new CompanionClient("https://pouchy.ai", sessionToken);
+var ack = await client.ConnectAsync();
+Console.WriteLine("scopes: " + string.Join(",", ack.GrantedScopes ?? new string[0]));
+
+// Request/response in one call — streams server-side, returns the reply.
+var reply = await client.SendTextAsync("what about the boss on floor 3?", awaitReply: true);
+Console.WriteLine(reply.Text);
+
+// Streaming deltas:
+await client.SendTextAsync("tell me a story", awaitReply: true,
+    onDelta: (chunk, reset) => Console.Write(chunk));
+```
+
+The event stream (proactive messages, confirms, tool calls) resumes from the
+session cursor and gives each envelope a typed `TypedPayload` (every outbound
+event has a class — e.g. `DataActivityPayload` for `companion.data_activity`,
+the metadata-only Data-plane activity frame; needs the `data.activity` scope):
+
+```csharp
+var cts = new CancellationTokenSource();
+await client.StreamEventsAsync(async env =>
+{
+    switch (env.TypedPayload)
+    {
+        case MessagePayload m:
+            Debug.Log("companion: " + m.Text);
+            break;
+        case ConfirmRequestPayload c:
+            // Platform session tokens may resolve confirms directly — your end
+            // user IS this instance's human. Show your own UI, then:
+            var res = await client.ConfirmActionAsync(c.ConfirmId, approve: true);
+            Debug.Log("outcome: " + res.Outcome);
+            break;
+        case ToolCallPayload t:
+            await client.SendToolResultAsync(t.Id, ok: true, result: new { answer = 42 });
+            break;
+    }
+}, cts.Token);
+```
+
+The server closes each stream window after ~45s (a clean end — call
+`StreamEventsAsync` again; it resumes from `client.Cursor`, so nothing is lost
+or repeated). That loop is storm-safe by construction: a clean instantly-closed
+**empty** window (a gateway accepting and immediately closing — never the
+designed cadence, which always delivers at least `hello.ack`) makes the next
+open back off 1→8s (anti-storm, preview.10); any delivered envelope resets the
+ladder, and errors still throw immediately. Byte-**silence** is bounded too (`StreamStallTimeout`, default
+60s): on a half-open TCP drop — a NAT idle-kill eats the FIN and no close ever
+arrives — the call throws a `CompanionError` (`Status` 0) naming the stall
+instead of blocking forever, and the same reconnect resumes. The bound is armed
+per read, so a healthy subscription is never cut, however long it lives. Set
+`StreamStallTimeout = Timeout.InfiniteTimeSpan` to disable it (then only your
+CancellationToken can unblock a dead read).
+
+Don't want to own that loop? **`EventStreamPump.RunAsync(client, onEvent,
+onError, ct)`** runs the stream as a permanent subscription: it reconnects
+immediately after every clean window close (except a zero-event close well
+under the server's ~45s cadence — a gateway accepting and instantly closing —
+which climbs the backoff ladder instead of hot-looping), backs off on errors
+(1→30s, honouring the server's `RetryAfter`, capped at 60s), stops on
+cancellation or a deliberately ended session, and never throws — errors reach
+your `onError` callback instead. It is what `PouchyCompanionBehaviour` rides
+internally.
+
+### Unity (`PouchyCompanionBehaviour`)
+
+Add the component, set **Base Url** + **Token** in the Inspector, wire the
+UnityEvents, and call `Connect()`. Every event is raised on the **main thread**,
+so handlers can touch Unity APIs safely. The subscription is **always-on**: the
+component rides `EventStreamPump`, so it reconnects through the server's ~45s
+window closes and transient failures for the lifetime of the GameObject
+(stream errors surface on `OnError` and are retried with backoff; a session
+ended with `EndSessionAsync` stops it).
+
+```csharp
+var companion = gameObject.AddComponent<PouchyCompanionBehaviour>();
+companion.Token = sessionToken;
+companion.OnMessage.AddListener(text => chatUI.Append(text));
+companion.OnTyping.AddListener(active => typingDot.SetActive(active));
+companion.Connect();
+// ...later, from a send button:
+companion.SendText("hi!");
+```
+
+### World state (play-along context)
+
+```csharp
+await client.SendWorldStateAsync(new WorldStateEvent {
+    Type = "game.event.boss_spawned",
+    Data = Newtonsoft.Json.Linq.JToken.FromObject(new { name = "Ashen Knight", floor = 3 }),
+    Salience = 0.9,
+});
+```
+
+## Methods
+
+| Method | REST | Notes |
+| --- | --- | --- |
+| `ConnectAsync()` | `POST /api/companion/session` | handshake → `HelloAckPayload`; sets `SessionId`, `Cursor` |
+| `SendTextAsync(text, awaitReply, onDelta, images, turnId)` | `POST …/session/{id}/input` | plain or streaming; always returns the `TurnId` (retry-idempotent — a replayed turn sets `Duplicate`) |
+| `StreamEventsAsync(onEvent, ct)` | `GET …/session/{id}/stream` | SSE; typed `TypedPayload`, cursor auto-advances; byte-silence bounded (`StreamStallTimeout` 60s) |
+| `PendingConfirmsAsync()` | `GET …/session/{id}/confirm` | `List<PendingConfirm>` |
+| `ConfirmActionAsync(confirmId, approve)` | `POST …/session/{id}/confirm` | `ConfirmResolution` |
+| `SendToolResultAsync(callId, ok, result)` | `POST …/session/{id}/tool-result` | returns `allDone` |
+| `SendWorldStateAsync(event \| events)` | `POST …/session/{id}/context` | fills specversion/id/source; `WorldStateAccepted` |
+| `HistoryAsync(limit)` | `GET …/session/{id}/history` | `List<HistoryTurn>` |
+| `RecallAsync(query, limit)` | `GET /api/companion/memory` | `List<RecalledMemory>` |
+| `RememberAsync(fact)` | `POST /api/companion/memory` | needs `memory.write:app` / `:core` |
+| `IngestKnowledgeAsync(text, name, kind, locale)` | `POST /api/companion/knowledge` | — |
+| `GetWalletAsync()` | `GET /api/companion/wallet` | read-only (`wallet.read`) |
+| `SetModalitiesAsync(modalities)` | `POST …/session/{id}/modalities` | — |
+| `PingAsync()` | `POST …/session/{id}/ping` | keep-alive |
+| `EndSessionAsync()` | `POST …/session/{id}/end` | clears `SessionId` |
+
+## Tokens & scopes
+
+A **platform session token** (minted via `POST /v1/sessions`) represents one of
+your end users and may resolve confirms directly. The token's granted scopes
+(`ack.GrantedScopes`) gate memory writes, wallet reads, social messages, etc.
+The scope model, confirm flow, world-state salience, and limits are identical
+across SDKs — see the [Python SDK](https://pypi.org/project/pouchy-companion/)
+for the same token/scopes note, and the full reference at
+[pouchy.ai/sdk](https://pouchy.ai/sdk) and
+[companion-api-reference](https://pouchy.ai/docs/companion-api-reference).
+
+## Errors
+
+Every failed call throws `CompanionError` with `.Status`, `.Code`
+(machine-switchable — `rate_limited`, `turn_pending`, `confirm_resolved`, … see
+`Protocol.ErrorCodes`) and `.RetryAfter` seconds when the server said when to
+come back. `.RetryAfter` is guaranteed **finite and non-negative** — it is read
+from the body's `retryAfterSec` first (it survives a header-stripping proxy),
+then the `Retry-After` header (numeric or RFC 9110 HTTP-date), and anything a
+broken upstream sends outside that domain (negative, `NaN`, `Infinity` — the
+last is reachable from legal JSON via the `1e400` overflow literal) becomes
+`null` rather than a value the handler below cannot sleep. Transport failures
+are wrapped too — `Status` is `0` and `Code` is
+`request_timeout` (the per-request deadline elapsed) or `aborted` (any other
+network failure), with the original exception preserved as `InnerException`.
+
+```csharp
+try { await client.SendTextAsync("hi"); }
+catch (CompanionError e) when (e.Code == "rate_limited")
+{
+    await Task.Delay(TimeSpan.FromSeconds(e.RetryAfter ?? 1));
+}
+```
+
+Not every refusal is worth retrying. `quota_exhausted` (402) means the account's
+monthly allowance is spent — credits, or realtime voice minutes — and nothing
+changes until the plan is upgraded or the 1st (UTC) arrives, so a retry loop on
+it never terminates. Handle it separately from `rate_limited`:
+
+```csharp
+catch (CompanionError e) when (e.Code == Protocol.ErrorCodes.QuotaExhausted)
+{
+    ShowUpgradePrompt(e.Message);  // do NOT retry
+}
+```
+
+## Voice / WebRTC
+
+Not included. This SDK is REST/SSE only; live voice calls need a native WebRTC
+plugin the game supplies. `control.call_ready` / `CallReadyPayload` are part of
+the typed vocabulary, but `startCall` (which returns the WebRTC credentials) is
+not implemented here.
+
+## Not yet ported from the JS SDK
+
+A few JS-SDK surfaces are deliberately unported (recorded decisions, not
+drift — the full ledger with rationale lives at the top of `CHANGELOG.md`):
+`handles`/`contextKinds` hello options, representative mode
+(`visitor`/`pairVisitor`), `GetAvatar`, binary `IngestFile`
+(`IngestKnowledgeAsync` text is covered), and `setToken` live-token swap (a
+Unity host reconnects with a fresh client after ~1h token expiry — the
+session survives the reconnect). Ask (or port) on demand.
+
+## Protocol parity
+
+`Runtime/Protocol.cs` is **generated from the TypeScript source of truth**
+(`src/lib/companion-sdk/protocol.ts`) and drift-tested in CI; the payload models
+in `Runtime/Models.cs` have their field names pinned to the same interfaces, so
+the three SDKs cannot silently diverge on the wire.
+
+The C# is compiled in CI as well, under Unity 2021.3's profile and against the
+UnityEngine 2021.3 reference assemblies — no Unity install or licence required
+on the runner, so the check runs on every change rather than at release time.
+The run pairs with a deliberately-broken sentinel that **must** fail: a compile
+of `#if UNITY_2021_1_OR_NEWER` code proves nothing if the define or the engine
+references quietly stopped resolving, and the sentinel is what makes that
+visible instead of green.