ai.pouchy.companion 0.1.0-preview.5

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# 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: the JS SDK 0.35.0 per-request header deadline
+> (`requestTimeoutMs`) needs no port here — every request already runs under
+> `CompanionClientOptions.Timeout` (CompanionClient.cs). Recorded so the
+> cross-SDK parity ledger stays 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.
+
+## 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,208 @@
+# 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# itself is pending its first Unity/CI compile pass** — it was written
+> without a local .NET toolchain. Please report compile issues 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.5"
+  }
+}
+```
+
+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`:
+
+```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);
+```
+
+### 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.
+
+```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 |
+| `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 README](../python-sdk/README.md) for the same
+token/scopes note, and the full reference at [pouchy.ai/sdk](https://pouchy.ai/sdk)
+and `docs/companion-api-reference.md`.
+
+## 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. 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));
+}
+```
+
+## 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.