Merge branch 'main' of https://github.com/plastic-labs/honcho

Author: offendingcommit

.claude/skills/honcho-integration/SKILL.md

@@ -139,8 +139,8 @@ response = peer.chat("What does this user prefer?")
 # Async usage (FastAPI, Starlette)
 from honcho import Honcho
 honcho = Honcho(workspace_id="my-app", api_key=os.environ["HONCHO_API_KEY"])
-peer = honcho.aio.peer("user-123")
-response = await peer.chat("What does this user prefer?")
+peer = await honcho.aio.peer("user-123")
+response = await peer.aio.chat("What does this user prefer?")
 ```
 
 Match the client to the framework — check whether the codebase uses `async def` handlers or sync `def` handlers and choose accordingly. The rest of this skill shows sync Python examples; swap to `.aio` equivalents for async codebases.
@@ -188,7 +188,7 @@ Create peers for **every entity** in your business logic - users AND AI assistan
 **Python:**
 
 ```python
-from honcho import PeerConfig
+from honcho.api_types import PeerConfig
 
 # Human users
 user = honcho.peer("user-123")

.claude/skills/honcho-integration/references/bot-frameworks/nanobot/session.py

@@ -13,7 +13,7 @@
 
 if TYPE_CHECKING:
     from honcho import Honcho
-    from honcho.session import SessionPeerConfig
+    from honcho.api_types import SessionPeerConfig
 
 
 @dataclass
@@ -101,7 +101,7 @@ def _get_or_create_peer(self, peer_id: str) -> Any:
         """
         Get or create a Honcho peer.
 
-        Peers are lazy -- no API call until first use.
+        As of v2.1.0, peer() always makes a get-or-create API call.
         Observation settings are controlled per-session via SessionPeerConfig.
 
         Args:
@@ -138,7 +138,7 @@ def _get_or_create_honcho_session(
         session = self.honcho.session(session_id)
 
         # Configure peer observation settings
-        from honcho.session import SessionPeerConfig
+        from honcho.api_types import SessionPeerConfig
         user_config = SessionPeerConfig(observe_me=True, observe_others=True)
         ai_config = SessionPeerConfig(observe_me=False, observe_others=True)
 

.claude/skills/migrate-honcho-py/DETAILED-CHANGES.md

@@ -476,3 +476,132 @@ from honcho.api_types import SessionPeerConfig
 ```
 
 **Note:** `MessageCreateParam` (singular) is now `MessageCreateParams` (plural).
+
+---
+
+## 14. Card Method Deprecation and set_card (v2.0.1)
+
+### Before (v2.0.0)
+
+```python
+card: list[str] | None = peer.card()
+```
+
+### After (v2.0.1+)
+
+```python
+# get_card() is the preferred method
+card: list[str] | None = peer.get_card()
+
+# card() still works but emits a deprecation warning
+card = peer.card()  # Deprecated
+
+# New: set_card()
+updated = peer.set_card(["Fact 1", "Fact 2"])
+updated = peer.set_card(["Fact 1"], target="other-peer")
+
+# Async variants
+card = await peer.aio.get_card()
+await peer.aio.set_card(["Fact 1"])
+```
+
+---
+
+## 15. Strict Input Validation (v2.0.2)
+
+All Pydantic input models now use `extra="forbid"`, raising `ValidationError` for unknown fields.
+
+```python
+from honcho.api_types import PeerConfig
+
+# This now raises ValidationError instead of silently ignoring the typo
+PeerConfig(observe_mee=True)  # ValidationError: extra fields not permitted
+```
+
+---
+
+## 16. peer() and session() Always Make API Calls (v2.1.0)
+
+### Before (v2.0.x)
+
+```python
+# Without options: lazy object, no API call
+peer = client.peer("user-123")
+# peer.created_at was None
+
+# With options: made API call
+peer = client.peer("user-123", metadata={"key": "value"})
+```
+
+### After (v2.1.0+)
+
+```python
+# Always makes a get-or-create API call
+peer = client.peer("user-123")
+# peer.created_at is now always populated
+
+# Async
+peer = await client.aio.peer("user-123")
+```
+
+All Peer/Session objects now have `created_at` populated immediately after construction.
+
+---
+
+## 17. New Properties: created_at, is_active (v2.1.0)
+
+```python
+# Peer
+peer = client.peer("user-123")
+print(peer.created_at)  # datetime | None
+
+# Session
+session = client.session("sess-1")
+print(session.created_at)  # datetime | None
+print(session.is_active)   # bool | None
+
+# These are refreshed by get_metadata(), get_configuration(), and refresh()
+peer.refresh()
+session.refresh()
+```
+
+---
+
+## 18. get_message() on Session (v2.1.0)
+
+```python
+# Fetch a single message by ID
+msg = session.get_message("msg-abc123")
+print(msg.content, msg.created_at)
+
+# Async
+msg = await session.aio.get_message("msg-abc123")
+```
+
+---
+
+## 19. Pagination Parameters (v2.1.0)
+
+All list methods now accept `page`, `size`, and `reverse`:
+
+```python
+# Defaults: page=1, size=50, reverse=False
+peers_page = client.peers(page=2, size=25, reverse=True)
+
+# Returns SyncPage / AsyncPage with:
+print(peers_page.total)        # Total items
+print(peers_page.pages)        # Total pages
+print(peers_page.has_next_page())
+
+# Works on:
+# client.peers(), client.sessions()
+# peer.sessions()
+# session.messages()
+# scope.list()
+```
+
+---
+
+## 20. Broader HTTP Retry Logic (v2.1.1)
+
+The SDK now catches `httpx.NetworkError` and `httpx.RemoteProtocolError` for retry in addition to `httpx.TimeoutException` and `httpx.ConnectError`. This is transparent — no code changes needed.

.claude/skills/migrate-honcho-py/MIGRATION-CHECKLIST.md

@@ -4,7 +4,7 @@ Use this checklist to track migration progress. Copy into your working notes and
 
 ## Dependencies
 
-- [ ] Update `honcho` package to v2.0.0
+- [ ] Update `honcho` package to v2.1.1
 - [ ] Remove any `honcho-core` imports
 
 ## Async Architecture Changes
@@ -113,6 +113,39 @@ Use this checklist to track migration progress. Copy into your working notes and
   - `UnprocessableEntityError`, `RateLimitError`, `ServerError`
   - `TimeoutError`, `ConnectionError`
 
+## Card Method Updates (v2.0.1)
+
+- [ ] Replace `peer.card()` with `peer.get_card()` (card() is deprecated)
+- [ ] Use `peer.set_card(list[str])` if setting peer cards
+
+## Strict Validation (v2.0.2)
+
+- [ ] Verify no input models pass unknown/misspelled fields (now raises `ValidationError`)
+- [ ] Check for typos in `PeerConfig`, `SessionConfiguration`, `WorkspaceConfiguration` fields
+
+## peer() / session() API Call Change (v2.1.0)
+
+- [ ] Update code that relied on lazy `peer()` / `session()` — they now always make API calls
+- [ ] Add `await` if using async and previously didn't need it for lazy construction
+
+## New Properties (v2.1.0)
+
+- [ ] Use `peer.created_at` / `session.created_at` where creation time is needed
+- [ ] Use `session.is_active` where session active status is needed
+
+## New Methods (v2.1.0)
+
+- [ ] Use `session.get_message(message_id)` to fetch single messages by ID
+
+## Pagination Parameters (v2.1.0)
+
+- [ ] Add `page`, `size`, `reverse` parameters to list calls where needed:
+  - [ ] `client.peers()`
+  - [ ] `client.sessions()`
+  - [ ] `peer.sessions()`
+  - [ ] `session.messages()`
+  - [ ] `scope.list()`
+
 ## Final Verification
 
 - [ ] Run type checker (mypy/pyright) with no errors

.claude/skills/migrate-honcho-py/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: migrate-honcho
-description: Migrates Honcho Python SDK code from v1.6.0 to v2.0.0. Use when upgrading honcho package, fixing breaking changes after upgrade, or when errors mention AsyncHoncho, observations, Representation class, .core property, or get_config methods.
+description: Migrates Honcho Python SDK code from v1.6.0 to v2.1.1. Use when upgrading honcho package, fixing breaking changes after upgrade, or when errors mention AsyncHoncho, observations, Representation class, .core property, or get_config methods.
 ---
 
-# Honcho Python SDK Migration (v1.6.0 → v2.0.0)
+# Honcho Python SDK Migration (v1.6.0 → v2.1.1)
 
 ## Overview
 
-This skill migrates code from `honcho` Python SDK v1.6.0 to v2.0.0 (required for Honcho 3.0.0+).
+This skill migrates code from `honcho` Python SDK v1.6.0 to v2.1.1 (required for Honcho 3.0.0+).
 
 **Key breaking changes:**
 
@@ -184,18 +184,92 @@ updated = client.update_message(message=msg, metadata={"key": "value"}, session=
 updated = session.update_message(message=msg, metadata={"key": "value"})
 ```
 
-### 10. Update card() return type
+### 10. Update card() return type and method name
 
 ```python
 # Before
 card: str = peer.card()  # Returns str
 
-# After
-card: list[str] | None = peer.card()  # Returns list[str] | None
+# After (v2.0.0+)
+card: list[str] | None = peer.get_card()  # Returns list[str] | None
 if card:
     print("\n".join(card))
+
+# peer.card() still works but is deprecated — use get_card()
+
+# New in v2.0.1: set_card()
+peer.set_card(["Prefers dark mode", "Located in US"])
+```
+
+### 11. Strict input validation (v2.0.2+)
+
+All input models now reject unknown fields via `extra="forbid"` Pydantic validation. Previously, misspelled or extraneous fields were silently ignored.
+
+```python
+# Before (v2.0.1 and earlier) — silently ignored
+peer = client.peer("user-1", configuration=PeerConfig(observe_mee=True))  # typo silently ignored
+
+# After (v2.0.2+) — raises ValidationError
+peer = client.peer("user-1", configuration=PeerConfig(observe_mee=True))  # ValidationError!
+```
+
+### 12. peer() and session() always make API calls (v2.1.0+)
+
+**Breaking**: `peer()` and `session()` now always make a get-or-create API call. Previously, calling without metadata/configuration returned a lazy object with no API call.
+
+```python
+# Before (v2.0.x) — no API call without options
+peer = client.peer("user-123")  # Lazy, no network request
+
+# After (v2.1.0+) — always hits the API
+peer = client.peer("user-123")  # Makes POST to /peers (get-or-create)
+
+# Async
+peer = await client.aio.peer("user-123")  # Also always hits API
 ```
 
+### 13. New properties and methods (v2.1.0+)
+
+```python
+# created_at on Peer and Session
+peer = client.peer("user-123")
+print(peer.created_at)  # datetime | None
+
+session = client.session("sess-1")
+print(session.created_at)  # datetime | None
+
+# is_active on Session
+print(session.is_active)  # bool | None
+
+# get_message() on Session
+msg = session.get_message("msg-id")
+# Async: msg = await session.aio.get_message("msg-id")
+```
+
+### 14. Pagination parameters on list methods (v2.1.0+)
+
+All list methods now accept `page`, `size`, and `reverse` parameters:
+
+```python
+# Before (v2.0.x) — only filters
+peers_page = client.peers(filters={"metadata": {"role": "admin"}})
+
+# After (v2.1.0+) — pagination controls
+peers_page = client.peers(
+    filters={"metadata": {"role": "admin"}},
+    page=2,
+    size=25,
+    reverse=True
+)
+
+# Works on: client.peers(), client.sessions(), peer.sessions(),
+# session.messages(), scope.list()
+```
+
+### 15. Broader HTTP retry logic (v2.1.1+)
+
+The SDK now retries on `httpx.TimeoutException`, `httpx.NetworkError`, and `httpx.RemoteProtocolError` (previously only `httpx.TimeoutException` and `httpx.ConnectError`). These are mapped to the SDK's `TimeoutError` and `ConnectionError` respectively. No code changes needed — this is transparent.
+
 ## Quick Reference Table
 
 | v1.6.0 | v2.0.0 |
@@ -222,6 +296,8 @@ if card:
 | `.get_peer_config()` | `.get_peer_configuration()` |
 | `.set_peer_config()` | `.set_peer_configuration()` |
 | `client.update_message()` | `session.update_message()` |
+| `peer.card()` | `peer.get_card()` *(card() deprecated)* |
+| *(new)* | `peer.set_card(list[str])` |
 | `chat(stream=True)` | `chat_stream()` |
 | `include_most_derived=` | `include_most_frequent=` |
 | `max_observations=` | `max_conclusions=` |
@@ -230,6 +306,10 @@ if card:
 | `PeerContext` | `PeerContextResponse` |
 | `DeriverStatus` | `QueueStatusResponse` |
 | `client.core` | *(removed)* |
+| *(new v2.1.0)* | `peer.created_at` / `session.created_at` |
+| *(new v2.1.0)* | `session.is_active` |
+| *(new v2.1.0)* | `session.get_message(id)` |
+| *(new v2.1.0)* | `page=`, `size=`, `reverse=` on list methods |
 
 ## Detailed Reference