ts SDK fix: adding strict checking (plastic-labs#421)

* fix: adding strict checking and updating readme

* chore: changelog and version

* fix: Add strict validation to all Python and TypeScript classes

* fix: Address Code Rabit Comments

* fix: duplicate searchQuery param in typescript session.context()

* feat: add created_at, is_active fields, and get_message method

* feat: Add pagintion params to sdk

* fix: Remove lazy initalization behavior from sdks

* fix: Address File Upload Validation, add compatibility shims, address review comments

* chore: Docs updates

* fix: Convert session config from API format in Peer.sessions()

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Pass all args to Session constructor in Peer.sessions()

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Preserve createdAt in Peer.refresh(), pass all data in session.peers()

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: changelog for ts

* fix: Review Comments

* fix: Add createAt and to peers call

---------

Co-authored-by: Vineeth Voruganti <13438633+VVoruganti@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

docs/changelog/compatibility-guide.mdx

@@ -10,14 +10,14 @@ This guide helps you match the right SDK version to your Honcho API version. New
 
 <CardGroup cols={2}>
   <Card title="TypeScript SDK" icon="js">
-    **Latest:** v2.0.1
+    **Latest:** v2.1.0
 
     ```bash
     npm install @honcho-ai/sdk
     ```
   </Card>
   <Card title="Python SDK" icon="python">
-    **Latest:** v2.0.1
+    **Latest:** v2.1.0
 
     ```bash
     pip install honcho-ai
@@ -30,7 +30,7 @@ This guide helps you match the right SDK version to your Honcho API version. New
 
 | Honcho API Version | TypeScript SDK | Python SDK |
 |-------------------|---------------|------------|
-| v3.0.3 (Current) | v2.0.1 | v2.0.1 |
+| v3.0.3 (Current) | v2.1.0 | v2.1.0 |
 | v3.0.2 | v2.0.0+ | v2.0.0+ |
 | v3.0.1 | v2.0.0+ | v2.0.0+ |
 | v3.0.0 | v2.0.0+ | v2.0.0+ |

docs/changelog/introduction.mdx

@@ -524,7 +524,30 @@ Welcome to the Honcho changelog! This section documents all notable changes to t
 
     <Tab title="Python SDK">
         [Python SDK](https://pypi.org/project/honcho-ai/)
-        <Update label="v2.0.1 (Current)">
+        <Update label="v2.1.0 (Current)">
+        ### Added
+
+        - `created_at` property on `Peer` and `Session` objects
+        - `is_active` property on `Session` objects
+        - `get_message(message_id)` method on `Session` (sync and async) to fetch a single message by ID
+        - `page`, `size`, and `reverse` pagination parameters on all list methods
+
+        ### Changed
+
+        - **Breaking**: `peer()` and `session()` now always make a get-or-create API call — no more lazy initialization
+        - Response configuration models now tolerate unknown fields from newer servers for forward compatibility
+
+        ### Fixed
+
+        - Sync and async `Session.get_metadata()`, `get_configuration()`, and `refresh()` now refresh cached `created_at` and `is_active` values along with metadata and configuration
+        - `honcho.__version__` now derives from package metadata, with a source-checkout fallback, so it stays aligned with released package versions
+        </Update>
+        <Update label="v2.0.2">
+        ### Changed
+
+        - All input models now reject unknown fields via strict Pydantic validation (`extra="forbid"`). Previously, misspelled or extraneous fields were silently ignored. Now a `ValidationError` is raised with the unrecognized field name.
+        </Update>
+        <Update label="v2.0.1">
             ### Added
 
         - `set_peer_card` method
@@ -638,7 +661,54 @@ Welcome to the Honcho changelog! This section documents all notable changes to t
 
     <Tab title="TypeScript SDK">
         [TypeScript SDK](https://www.npmjs.com/package/@honcho-ai/sdk)
-        <Update label="v2.0.1 (Current)">
+        <Update label="v2.1.0 (Current)">
+        ### Added
+
+        - `createdAt` property on `Peer` and `Session` wrapper objects
+        - `isActive` property on `Session` wrapper objects
+        - `getMessage(messageId)` method on `Session` to fetch a single message by ID
+        - `Peer.representation()`, `Session.representation()`, and `Session.context()` now accept `Message` objects for `searchQuery`
+        - `page`, `size`, and `reverse` pagination controls on all list methods
+
+        ### Changed
+
+        - **Breaking**: `searchQuery` removed from top-level `context()` options — use `representationOptions.searchQuery` instead:
+          ```typescript
+          // Before (v2.0.x)
+          await session.context({ searchQuery: "..." });
+          // After (v2.1.0)
+          await session.context({ representationOptions: { searchQuery: "..." } });
+          ```
+        - List methods (`peers()`, `sessions()`, `messages()`, `workspaces()`) support both the new options object and the legacy raw-filter form
+        - Representation search options now accept strings and content-like objects, including `Message` instances, while rejecting whitespace-only or invalid runtime inputs
+        - **Breaking**: `peer()` and `session()` now always make a get-or-create API call — no more lazy initialization. If you relied on constructing SDK objects without triggering a network request, note that every `peer()` and `session()` call now hits the API:
+          ```typescript
+          // Before (v2.0.x) — no API call
+          const session = honcho.session("my-session");
+          // After (v2.1.0) — makes a get-or-create API call
+          const session = await honcho.session("my-session");
+          ```
+        - Response configuration models now tolerate unknown fields from newer servers for forward compatibility
+        - Moved `@types/node` from `dependencies` to `devDependencies`
+
+        ### Fixed
+
+        - `uploadFile()` now rejects unsupported top-level binary/object inputs and only validates inputs the serializer can actually upload
+        - `uploadFile()` now serializes message configuration using API field names, matching `addMessages()`
+        - Session fetch methods now refresh cached `createdAt` and `isActive` values alongside metadata and configuration
+        </Update>
+        <Update label="v2.0.2">
+        ### Changed
+
+        - Client constructor now rejects unknown options via `.strict()` Zod validation. Previously, misspelled options (e.g., `baseUrl` instead of `baseURL`) were silently ignored, causing the SDK to fall back to defaults. Now a `ZodError` is thrown with the unrecognized key name.
+        - All input schemas now use `.strict()` validation to reject unknown fields.
+        - `FileUploadSchema.configuration` now uses `MessageConfigurationSchema` instead of open record type.
+
+        ### Fixed
+
+        - README example used `baseUrl` instead of `baseURL`.
+        </Update>
+        <Update label="v2.0.1">
         ### Added
 
         - `setPeerCard` method

docs/v2/documentation/core-concepts/configuration.mdx

@@ -353,6 +353,20 @@ import { Honcho } from "@honcho-ai/sdk";
 ```
 </CodeGroup>
 
+### Observation and Peer Join Order
+
+Reasoning tasks are scheduled at the time a message is created, based on which peers are in the session **at that moment**. Honcho does not retroactively schedule reasoning for peers that join later.
+
+This means:
+
+- If Peer C joins a session **after** messages from Peer A and Peer B have already been sent, Peer C will **not** receive reasoning tasks for those earlier messages—even if Peer C has `observe_others` enabled.
+- Peer C will only begin observing new messages sent after they join the session.
+- Similarly, if a peer leaves a session, they stop being included as an observer for any messages sent after their departure.
+
+<Warning>
+There is no retroactive reasoning. If your application needs an observer peer to reason about prior conversation history, add the peer to the session **before** messages are sent. Alternatively use the .chat() endpoint to include the conversation history in the agent's context, regardless of if they were reasoned against or not
+</Warning>
+
 ## Full Configuration Schema Reference
 
 ### Workspace & Session Configuration

docs/v3/documentation/features/advanced/representation-scopes.mdx

@@ -266,6 +266,20 @@ Directional representations update automatically through the reasoning pipeline
 
 The pipeline respects scoping—Honcho's representations reason over messages across all sessions, while directional representations only reason over messages from sessions where the observer was an active participant.
 
+### Peer Join Order Matters
+
+Reasoning tasks are scheduled at the time a message is created, based on which peers are in the session **at that moment**. Honcho does not retroactively schedule reasoning for peers that join later.
+
+This means:
+
+- If Peer C joins a session **after** messages from Peer A and Peer B have already been sent, Peer C will **not** receive reasoning tasks for those earlier messages—even if Peer C has `observe_others=true`.
+- Peer C will only begin observing new messages sent after they join the session.
+- Similarly, if a peer leaves a session, they stop being included as an observer for any messages sent after their departure.
+
+<Warning>
+There is no retroactive reasoning. If your application needs an observer peer to reason about prior conversation history, add the peer to the session **before** messages are sent. Alternatively, use `peer.chat()` to include conversation history in the agent's context whether or not those messages were previously reasoned over.
+</Warning>
+
 <Note>
 Conclusions are cached for fast retrieval. Use `representation()` to retrieve stored conclusions for dashboards and analytics. Use `peer.chat()` when you need query-specific reasoning with natural language.
 </Note>

docs/v3/documentation/features/get-context.mdx

@@ -165,8 +165,8 @@ context = session.context(
     const context = await session.context({
       tokens: 2000,
       peerTarget: "user-123",
-      searchQuery: "What are my coding preferences?",
       representationOptions: {
+        searchQuery: "What are my coding preferences?",
         searchTopK: 10,           // Number of relevant conclusions to fetch
         searchMaxDistance: 0.8,   // Max semantic distance (0.0-1.0)
         includeMostFrequent: true, // Include most frequent conclusions

docs/v3/documentation/reference/sdk.mdx

@@ -218,6 +218,14 @@ const session = await honcho.session(id);
 // List all peers in workspace (returns Page<Peer>)
 const peers = await honcho.peers();
 
+// List with pagination and filtering
+const filtered = await honcho.peers({
+  filters: { metadata: { role: "user" } },
+  page: 1,
+  size: 25,
+  reverse: true
+});
+
 // List all sessions in workspace (returns Page<Session>)
 const sessions = await honcho.sessions();
 
@@ -234,7 +242,7 @@ const workspaces = await honcho.workspaces();
 </CodeGroup>
 
 <Info>
-Peer and session creation is **lazy** - no API calls are made until you actually use the peer or session.
+`peer()` and `session()` always make a get-or-create API call, returning objects with cached metadata, configuration, and timestamps.
 </Info>
 
 ### Peer
@@ -243,7 +251,7 @@ Represents an entity that can participate in conversations:
 
 <CodeGroup>
 ```python Python
-# Create peers (lazy creation - no API call yet)
+# Create peers (get-or-create API call)
 alice = honcho.peer("alice")
 assistant = honcho.peer("assistant")
 
@@ -254,6 +262,7 @@ alice = honcho.peer("bob", config={"role": "user", "active": True}, metadata={"l
 # Peer properties
 print(f"Peer ID: {alice.id}")
 print(f"Workspace: {alice.workspace_id}")
+print(f"Created: {alice.created_at}")  # Available after API fetch
 
 # Chat with peer's representations (supports streaming)
 response = alice.chat("What did I have for breakfast?")
@@ -305,6 +314,7 @@ const assistant = await honcho.peer("assistant");
 
 // Peer properties
 console.log(`Peer ID: ${alice.id}`);
+console.log(`Created: ${alice.createdAt}`);  // Available after API fetch
 
 // Chat with peer's representations (supports streaming)
 const response = await alice.chat("What did I have for breakfast?");
@@ -551,7 +561,7 @@ Manages multi-party conversations:
 
 <CodeGroup>
 ```python Python
-# Create session (like peers, lazy creation)
+# Create session (get-or-create API call)
 session = honcho.session("conversation-1")
 
 # Create with immediate configuration
@@ -561,6 +571,8 @@ session = honcho.session("meeting-1", config={"type": "meeting", "max_peers": 10
 # Session properties
 print(f"Session ID: {session.id}")
 print(f"Workspace: {session.workspace_id}")
+print(f"Created: {session.created_at}")  # Available after API fetch
+print(f"Active: {session.is_active}")    # Available after API fetch
 
 # Peer management
 session.add_peers([alice, assistant])
@@ -579,8 +591,12 @@ session.add_messages([
     assistant.message("Hi Alice! How can I help today?")
 ])
 
-# Get messages
+# Get messages (with optional pagination)
 messages = session.messages()
+messages = session.messages(page=1, size=100, reverse=True)
+
+# Get a single message by ID
+message = session.get_message("message-id")
 
 # Get conversation context
 context = session.context(summary=True, tokens=2000)
@@ -641,6 +657,8 @@ const session = await honcho.session("conversation-1");
 
 // Session properties
 console.log(`Session ID: ${session.id}`);
+console.log(`Created: ${session.createdAt}`);  // Available after API fetch
+console.log(`Active: ${session.isActive}`);    // Available after API fetch
 
 // Peer management
 await session.addPeers([alice, assistant]);
@@ -658,8 +676,12 @@ await session.addMessages([
   assistant.message("Hi Alice! How can I help today?")
 ]);
 
-// Get messages
+// Get messages (with optional pagination)
 const messages = await session.messages();
+const paged = await session.messages({ page: 1, size: 100, reverse: true });
+
+// Get a single message by ID
+const message = await session.getMessage("message-id");
 
 // Get conversation context
 const context = await session.context({ summary: true, tokens: 2000 });
@@ -668,10 +690,10 @@ const context = await session.context({ summary: true, tokens: 2000 });
 const richContext = await session.context({
   tokens: 2000,
   peerTarget: "user",
-  searchQuery: "What are my preferences?",
   peerPerspective: "assistant",
   limitToSession: true,
   representationOptions: {
+    searchQuery: "What are my preferences?",
     searchTopK: 10,
     searchMaxDistance: 0.8,
     includeMostFrequent: true,
@@ -811,12 +833,12 @@ The SessionContext object has the following structure:
 | `tokens` | `int` | Maximum tokens to include |
 | `peer_target` | `str` | Peer ID to get representation for |
 | `peer_perspective` | `str` | Peer ID for perspective (requires peer_target) |
-| `search_query` | `str` or `Message` | Query string or Message object for semantic search |
 | `limit_to_session` | `bool` | Limit representation to session only |
-| `search_top_k` | `int` | Number of semantic search results (1-100) |
-| `search_max_distance` | `float` | Max semantic distance (0.0-1.0) |
-| `include_most_frequent` | `bool` | Include most frequent conclusions |
-| `max_conclusions` | `int` | Max conclusions to include (1-100) |
+| `representationOptions.searchQuery` | `str` or `Message` | Query string or Message object for semantic search |
+| `representationOptions.searchTopK` | `int` | Number of semantic search results (1-100) |
+| `representationOptions.searchMaxDistance` | `float` | Max semantic distance (0.0-1.0) |
+| `representationOptions.includeMostFrequent` | `bool` | Include most frequent conclusions |
+| `representationOptions.maxConclusions` | `int` | Max conclusions to include (1-100) |
 
 ## Advanced Usage
 
@@ -988,23 +1010,46 @@ const actionItems = await session.messages({
 
 ### Pagination
 
+All list methods support `page`, `size`, and `reverse` parameters:
+
 <CodeGroup>
 ```python Python
-# Iterate through all sessions
+# Default pagination (page 1, size 50)
 for session in honcho.sessions():
     print(f"Session: {session.id}")
 
-    # Iterate through session messages
-    for message in session.messages():
-        print(f"  {message.peer_id}: {message.content}")
+# Custom page size
+for message in session.messages(size=100):
+    print(f"  {message.peer_id}: {message.content}")
+
+# Start at a specific page
+page3 = session.messages(page=3, size=25)
+
+# Reverse ordering
+recent_first = session.messages(reverse=True)
+
+# Combine with filters
+filtered = session.messages(filters={"peer_id": "alice"}, size=10)
 ```
 
 ```typescript TypeScript
-// Get paginated results
+// Default pagination (page 1, size 50)
 const peersPage = await honcho.peers();
 
-// Iterate through all items
-for await (const peer of peersPage) {
+// Custom page size and filtering
+const filtered = await honcho.peers({
+  filters: { metadata: { role: "user" } },
+  size: 25
+});
+
+// Start at a specific page
+const page3 = await session.messages({ page: 3, size: 25 });
+
+// Reverse ordering
+const recent = await session.messages({ reverse: true });
+
+// Iterate through all items (auto-paginates)
+for await (const peer of await honcho.peers()) {
   console.log(`Peer: ${peer.id}`);
 }
 
@@ -1048,8 +1093,8 @@ const supportAgent = await honcho.peer(`agent-${agentId}`);
 
 <CodeGroup>
 ```python Python
-# Lazy creation - no API calls until needed
-peers = [honcho.peer(f"user-{i}") for i in range(100)]  # Fast
+# Create peers (each makes a get-or-create call)
+peers = [honcho.peer(f"user-{i}") for i in range(100)]
 
 # Batch operations when possible
 session.add_messages([peer.message(f"Message {i}") for i, peer in enumerate(peers)])
@@ -1059,7 +1104,7 @@ context = session.context(tokens=1500)  # Limit context size
 ```
 
 ```typescript TypeScript
-// Lazy creation - no API calls until needed
+// Create peers (each makes a get-or-create call)
 const peers = await Promise.all(
   Array.from({ length: 100 }, (_, i) => honcho.peer(`user-${i}`))
 );