@theway-ai/sdk 2.2.0 → 2.2.2

package/docs/PROTOCOL.md

@@ -0,0 +1,126 @@
+# @theway-ai/sdk Protocol Reference
+
+This document describes the wire protocol and the main typed APIs exposed by
+`@theway-ai/sdk`. It is intended for developers integrating with the theway
+daemon (`thewayd`).
+
+## Services
+
+The SDK wraps the theway gRPC services:
+
+| Service | Purpose |
+| --- | --- |
+| `CommandService` | Prompt submission, abort, model/thinking control, control-plane approval |
+| `SessionService` | Session lifecycle, snapshot, history, collapse, graph node reads |
+| `SettingsService` | Daemon settings |
+| `GraphEngineService` | DAG/goal run control and node output |
+| `EventService` | Streaming snapshot/event frames |
+| `Health` | gRPC health checks |
+
+## Session identity
+
+- New session resource objects use `id`.
+- `session_id` is retained on requests and legacy responses for compatibility.
+- New clients should prefer `SessionInfo.id` / `SessionSummary.id`.
+
+## SessionSnapshot
+
+`getSnapshot(sessionId)` returns a nested `SessionSnapshot`:
+
+```text
+SessionSnapshot
+├── session: SessionInfo        # id, name, cwd, created_at, metadata
+├── runtime: SessionRuntime     # ModelRef, ThinkingLevel, supported_thinking_levels
+├── feed: SessionFeed           # FeedBlock list + incremental cursors
+├── graphs: SessionGraphState   # dags, subagents
+└── lineage: SessionLineage     # parent_id, child_ids, collapsed_node_ids
+```
+
+### Thinking levels
+
+The protocol defines a canonical `ThinkingLevel` enum:
+
+```text
+off | minimal | low | medium | high | xhigh
+```
+
+A model may not support every level. `SessionRuntime.supported_thinking_levels`
+is derived from the model's `thinkingLevelMap`; `thinking_level` must be one of
+the supported values.
+
+## Pagination
+
+### GetHistory
+
+Reads a session feed page by page.
+
+```ts
+const res = await client.getHistory({
+  sessionId: 'sess-1',
+  offset: 0,
+  limit: 50,
+});
+// res.blocks: FeedBlock[]
+// res.nextOffset
+// res.total?
+```
+
+### ListSessionGraphNodeMessages
+
+Reads one graph node's structured messages (`FeedBlock` list).
+
+```ts
+const res = await client.listSessionGraphNodeMessages(
+  'sess-1',
+  'node-1',
+  0,
+  50,
+);
+```
+
+## Graph nodes
+
+Graph nodes are not all sessions. `SessionGraphNodeType`:
+
+| Type | Meaning |
+| --- | --- |
+| `SESSION` | A collapsed session |
+| `DAG_RUN` | A DAG run |
+| `DAG_NODE` | A single DAG node |
+| `SUBAGENT_JOB` | A subagent job |
+| `GOAL_RUN` | A goal run |
+
+`getSessionGraphNode(sessionId, nodeId)` returns one node's status/summary.
+`streamSessionGraphNode(sessionId, nodeId)` returns a stream of
+`SessionGraphNodeStreamFrame`:
+
+```text
+node: SessionGraphNode          # initial/periodic state
+block: FeedBlock                # new structured output
+status: SessionGraphNodeStatus  # running/completed/failed/...
+```
+
+## Collapse
+
+`collapseSession(request)` turns the current session into a graph node and
+creates a new session with a compact context.
+
+```ts
+const res = await client.collapseSession({
+  sessionId: 'sess-1',
+  name: 'phase-2',
+  adoptRunningGraphs: false,
+});
+// res.childSessionId
+// res.nodeId
+// res.snapshot
+```
+
+- Default: the old session's running DAG/subagent graph keeps running.
+- `adoptRunningGraphs: true` migrates ownership to the new session.
+
+## Compatibility
+
+- `getState()` remains available and returns the legacy `SessionState`.
+- New code should prefer `getSnapshot()`.
+- `session_id` fields on request messages remain the routing identifier.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theway-ai/sdk",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "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": {
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "proto",
+    "docs",
     "README.md"
   ],
   "engines": {

package/proto/session.proto

@@ -59,12 +59,15 @@ message FeedBlockPatch {
 
 // 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 +190,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 +212,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 +255,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.