@theway-ai/sdk 2.2.1 → 2.3.0

package/docs/PROTOCOL.md

@@ -50,21 +50,24 @@ the supported values.
 
 ## Pagination
 
-### GetHistory
+### ListSessionMessages
 
-Reads a session feed page by page.
+Reads the full message history of a session's active branch page by page.
 
 ```ts
-const res = await client.getHistory({
-  sessionId: 'sess-1',
-  offset: 0,
-  limit: 50,
-});
-// res.blocks: FeedBlock[]
-// res.nextOffset
-// res.total?
+const page = await client.listSessionMessages('sess-1', 50);
+// page.blocks: FeedBlock[] (oldest → newest within the page)
+// page.nextBeforeEntryId: string | undefined — pass as beforeEntryId for the
+//   previous page
+// page.hasMore: boolean
+// page.total: number
+
+const older = await client.listSessionMessages('sess-1', 50, page.nextBeforeEntryId);
 ```
 
+The server caps `limit` at 500. `GetSnapshot` carries the current feed
+projection only; full history always goes through `ListSessionMessages`.
+
 ### ListSessionGraphNodeMessages
 
 Reads one graph node's structured messages (`FeedBlock` list).
@@ -121,6 +124,6 @@ const res = await client.collapseSession({
 
 ## Compatibility
 
-- `getState()` remains available and returns the legacy `SessionState`.
-- New code should prefer `getSnapshot()`.
+- The previous flat state / snapshot-shaped history client methods were
+  removed; use `getSnapshot()` + `listSessionMessages()`.
 - `session_id` fields on request messages remain the routing identifier.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theway-ai/sdk",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "TypeScript SDK for the theway gRPC daemon (five theway.grpc.v1 domain services + grpc.health.v1). Typed client for all RPCs, generated from the domain proto files via ts-proto.",
   "license": "MIT",
   "repository": {

package/proto/events.proto

@@ -10,7 +10,7 @@ import "session.proto";
 // Unified envelope for StreamEvents / WebSocket frames.
 message StreamFrame {
   oneof payload {
-    SessionState snapshot = 1; // connection start + periodic full state
+    SessionSnapshot snapshot = 1; // connection start + full resync frames
     StreamEvent event = 2; // high-frequency increment
   }
 }

package/proto/graph_engine.proto

@@ -138,7 +138,7 @@ message GraphSkipResponse {
 }
 
 // Checkpoints are organized by session: a session owns its runs
-// (DagRun.session_id), and `SessionState.dags` mounts the live graph status
+// (DagRun.session_id), and `SessionSnapshot.graph_state.dags` mounts the live graph status
 // under that session. Checkpoint exports one run or the session's whole graph
 // set as portable JSON snapshots; restore revives them back under the session.
 message GraphCheckpointRequest {

package/proto/session.proto

@@ -9,62 +9,25 @@ import "commands.proto";
 import "extensions.proto";
 import "graph_engine.proto";
 
-// Full session state (the structured form of the former WireSnapshot JSON).
-// Low-frequency, whole-replacement: GetState / stream snapshot frames.
-message SessionState {
-  string session_id = 1;
-  string model = 2;
-  repeated ProviderGroup model_catalog = 3;
-  string cwd = 4;
-  bool busy = 5;
-  uint32 queued_count = 6;
-  optional TriggerPollStatus latest_trigger_poll = 7;
-  optional GoalSnapshot goal = 8;
-  optional ControlPlanePromptSnapshot control_plane_prompt = 9;
-  SidebarSnapshot sidebar = 10;
-  repeated FeedBlock feed_blocks = 11;
-  repeated string feed_lines = 12;
-  // graph mode (P1/P2 fill these):
-  repeated DagRunSnapshot dags = 13;
-  repeated SubagentJobSnapshot subagents = 14;
-  // TUI display settings pushed from the daemon (read from config.toml).
-  optional uint32 tui_max_feed_lines = 15;
-  // Token usage + context window for the live session.
-  optional ContextUsage context_usage = 16;
-  // Absolute index of feed_lines[0] in the full transcript (issue #35):
-  // stream snapshots carry only rows appended since the last publish; the
-  // initial get_state snapshot carries everything (base 0).
-  uint64 feed_lines_base = 17;
-  // Incremental gRPC snapshot frames require this many blocks to already be
-  // present on the consumer. Zero denotes a full replacement frame.
-  uint64 feed_blocks_base = 18;
-  // Appends/replacements since feed_blocks_base. Full frames leave this empty.
-  repeated FeedBlockPatch feed_block_patches = 19;
-  // Runtime-extension status is additive; older clients ignore this field.
-  ExtensionSnapshot extensions = 20;
-  // Session-cumulative token usage: total input, cached input, non-cached
-  // input, output, and cache write totals for the current session.
-  ContextUsage session_context_usage = 21;
-  // Active thinking level ("off" | "minimal" | "low" | "medium" | "high" |
-  // "xhigh"); empty for older daemons.
-  string thinking_level = 22;
-}
-
+// Incremental transcript patch: appends/replacements since a consumer cursor.
 message FeedBlockPatch {
   // index == consumer length appends; index < length replaces; index > length
-  // is a gap and requires a full GetState resync.
+  // is a gap and requires a full snapshot resync.
   uint64 index = 1;
   FeedBlock block = 2;
 }
 
 // Token usage for the current/last turn, plus the model's context window size.
 message ContextUsage {
-  uint64 input_tokens = 1;
-  uint64 output_tokens = 2;
-  uint64 cache_read_tokens = 3;
-  uint64 cache_write_tokens = 4;
-  uint64 total_tokens = 5;
-  uint32 context_window = 6;
+  uint64 cached_tokens = 1;
+  uint64 new_tokens = 2;
+  uint64 total_input_tokens = 3;
+  uint64 output_tokens = 4;
+  uint64 cache_write_tokens = 5;
+  optional double provider_cache_hit_rate = 6;
+  optional double prefix_cache_hit_rate = 7;
+  optional uint64 prefix_hit_tokens = 8;
+  uint32 context_window = 9;
 }
 
 message ProviderGroup {
@@ -187,9 +150,10 @@ message FeedBlock {
     UserBlock user = 1;
     AssistantBlock assistant = 2;
     ThinkingBlock thinking = 3;
-    ToolBlock tool = 4;
     ToolResultBlock tool_result = 5;
     PlainBlock plain = 6;
+    ToolCallBlock tool_call = 7;
+    ErrorBlock error = 8;
   }
 }
 
@@ -208,10 +172,18 @@ message ThinkingBlock {
   optional string timestamp = 2; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
 }
 
-message ToolBlock {
+message ToolCallBlock {
   string name = 1;
   string args = 2;
-  optional string timestamp = 3; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+  optional string metadata = 3; // Optional tool-call metadata (JSON string).
+  optional string timestamp = 4; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message ErrorBlock {
+  string message = 1;
+  optional string code = 2;
+  bool recoverable = 3;
+  optional string timestamp = 4; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
 }
 
 message ToolResultBlock {
@@ -243,6 +215,7 @@ message SessionSummary {
   optional string preview = 10;
   map<string, string> metadata = 11;
   optional string last_activity_at_rfc3339 = 12; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+  string tree_prefix = 14; // Pi-style tree prefix (`├─ ` / `└─ ` / `│ `) for fork-lineage display.
 }
 
 // Thinking levels supported by the runtime.
@@ -293,6 +266,10 @@ message SessionRuntime {
   optional GoalSnapshot goal = 9;
   optional ControlPlanePromptSnapshot control_plane_prompt = 10;
   ExtensionSnapshot extensions = 11;
+  // Full rendered system context for the next request (base prompt + skills +
+  // tool inventory + working directory + memory + lineage). Mirrors the
+  // request/header epoch snapshot in deepseek-harness session logs.
+  string system_context = 12;
 }
 
 // Transcript plane of a session snapshot.
@@ -322,7 +299,8 @@ message SessionLineage {
   optional string collapsed_into_session_id = 6;
 }
 
-// Full structured session snapshot: the nested successor of SessionState.
+// Full structured session snapshot: the single-version authoritative current
+// state shape served by GetSnapshot and StreamEvents snapshot frames.
 message SessionSnapshot {
   string session_id = 1;
   SessionInfo info = 2;
@@ -332,6 +310,28 @@ message SessionSnapshot {
   SessionLineage lineage = 6;
 }
 
+// Cursor-paginated read of the session's full message history. Entries are
+// addressed by storage entry id; `before_entry_id` returns the page of
+// message blocks strictly older than that entry.
+message ListSessionMessagesRequest {
+  string session_id = 1;
+  // Omitted = newest page of the active branch.
+  optional string before_entry_id = 2;
+  // Page size; server caps at 500.
+  uint32 limit = 3;
+}
+
+message SessionMessagePage {
+  string session_id = 1;
+  // Oldest → newest within the page.
+  repeated FeedBlock blocks = 2;
+  // Entry id of the oldest message in this page; empty when no older page.
+  optional string next_before_entry_id = 3;
+  bool has_more = 4;
+  // Total message count on the active branch.
+  uint64 total = 5;
+}
+
 // Collapse a session into a graph node, optionally under another session.
 message CollapseSessionRequest {
   string session_id = 1;
@@ -465,13 +465,10 @@ message ClearCredentialRequest {
 }
 
 service SessionService {
-  // Full structured state (binary protobuf). Kept for compatibility; new
-  // clients should use GetSnapshot / GetHistory.
-  rpc GetState(SessionStateRequest) returns (SessionState);
-  // Full nested session snapshot (session-snapshot-collapse contract).
+  // Full nested session snapshot: the single authoritative current snapshot.
   rpc GetSnapshot(SessionStateRequest) returns (SessionSnapshot);
-  // Session history as a snapshot-shaped transcript (session-snapshot-collapse).
-  rpc GetHistory(SessionStateRequest) returns (SessionSnapshot);
+  // Cursor-paginated full message history on the session's active branch.
+  rpc ListSessionMessages(ListSessionMessagesRequest) returns (SessionMessagePage);
   // Collapse a session into a graph node (session-snapshot-collapse).
   rpc CollapseSession(CollapseSessionRequest) returns (CollapseSessionResponse);
   rpc GetSessionGraphNode(GetSessionGraphNodeRequest) returns (GetSessionGraphNodeResponse);