@theway-ai/sdk 2.2.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +6 -0
  2. package/docs/PROTOCOL.md +126 -0
  3. package/package.json +2 -1
package/README.md CHANGED
@@ -21,6 +21,12 @@ Published as a public package on the official npm registry (`https://registry.np
21
21
  npm install @theway-ai/sdk
22
22
  ```
23
23
 
24
+ ## Documentation
25
+
26
+ The package ships protocol/spec documentation in [`docs/PROTOCOL.md`](docs/PROTOCOL.md).
27
+ It covers session identity, `SessionSnapshot`, pagination, graph node types, streaming,
28
+ collapse, and compatibility notes.
29
+
24
30
  ## Usage
25
31
 
26
32
  ```ts
package/docs/PROTOCOL.md ADDED
@@ -0,0 +1,126 @@
1
+ # @theway-ai/sdk Protocol Reference
2
+
3
+ This document describes the wire protocol and the main typed APIs exposed by
4
+ `@theway-ai/sdk`. It is intended for developers integrating with the theway
5
+ daemon (`thewayd`).
6
+
7
+ ## Services
8
+
9
+ The SDK wraps the theway gRPC services:
10
+
11
+ | Service | Purpose |
12
+ | --- | --- |
13
+ | `CommandService` | Prompt submission, abort, model/thinking control, control-plane approval |
14
+ | `SessionService` | Session lifecycle, snapshot, history, collapse, graph node reads |
15
+ | `SettingsService` | Daemon settings |
16
+ | `GraphEngineService` | DAG/goal run control and node output |
17
+ | `EventService` | Streaming snapshot/event frames |
18
+ | `Health` | gRPC health checks |
19
+
20
+ ## Session identity
21
+
22
+ - New session resource objects use `id`.
23
+ - `session_id` is retained on requests and legacy responses for compatibility.
24
+ - New clients should prefer `SessionInfo.id` / `SessionSummary.id`.
25
+
26
+ ## SessionSnapshot
27
+
28
+ `getSnapshot(sessionId)` returns a nested `SessionSnapshot`:
29
+
30
+ ```text
31
+ SessionSnapshot
32
+ ├── session: SessionInfo # id, name, cwd, created_at, metadata
33
+ ├── runtime: SessionRuntime # ModelRef, ThinkingLevel, supported_thinking_levels
34
+ ├── feed: SessionFeed # FeedBlock list + incremental cursors
35
+ ├── graphs: SessionGraphState # dags, subagents
36
+ └── lineage: SessionLineage # parent_id, child_ids, collapsed_node_ids
37
+ ```
38
+
39
+ ### Thinking levels
40
+
41
+ The protocol defines a canonical `ThinkingLevel` enum:
42
+
43
+ ```text
44
+ off | minimal | low | medium | high | xhigh
45
+ ```
46
+
47
+ A model may not support every level. `SessionRuntime.supported_thinking_levels`
48
+ is derived from the model's `thinkingLevelMap`; `thinking_level` must be one of
49
+ the supported values.
50
+
51
+ ## Pagination
52
+
53
+ ### GetHistory
54
+
55
+ Reads a session feed page by page.
56
+
57
+ ```ts
58
+ const res = await client.getHistory({
59
+ sessionId: 'sess-1',
60
+ offset: 0,
61
+ limit: 50,
62
+ });
63
+ // res.blocks: FeedBlock[]
64
+ // res.nextOffset
65
+ // res.total?
66
+ ```
67
+
68
+ ### ListSessionGraphNodeMessages
69
+
70
+ Reads one graph node's structured messages (`FeedBlock` list).
71
+
72
+ ```ts
73
+ const res = await client.listSessionGraphNodeMessages(
74
+ 'sess-1',
75
+ 'node-1',
76
+ 0,
77
+ 50,
78
+ );
79
+ ```
80
+
81
+ ## Graph nodes
82
+
83
+ Graph nodes are not all sessions. `SessionGraphNodeType`:
84
+
85
+ | Type | Meaning |
86
+ | --- | --- |
87
+ | `SESSION` | A collapsed session |
88
+ | `DAG_RUN` | A DAG run |
89
+ | `DAG_NODE` | A single DAG node |
90
+ | `SUBAGENT_JOB` | A subagent job |
91
+ | `GOAL_RUN` | A goal run |
92
+
93
+ `getSessionGraphNode(sessionId, nodeId)` returns one node's status/summary.
94
+ `streamSessionGraphNode(sessionId, nodeId)` returns a stream of
95
+ `SessionGraphNodeStreamFrame`:
96
+
97
+ ```text
98
+ node: SessionGraphNode # initial/periodic state
99
+ block: FeedBlock # new structured output
100
+ status: SessionGraphNodeStatus # running/completed/failed/...
101
+ ```
102
+
103
+ ## Collapse
104
+
105
+ `collapseSession(request)` turns the current session into a graph node and
106
+ creates a new session with a compact context.
107
+
108
+ ```ts
109
+ const res = await client.collapseSession({
110
+ sessionId: 'sess-1',
111
+ name: 'phase-2',
112
+ adoptRunningGraphs: false,
113
+ });
114
+ // res.childSessionId
115
+ // res.nodeId
116
+ // res.snapshot
117
+ ```
118
+
119
+ - Default: the old session's running DAG/subagent graph keeps running.
120
+ - `adoptRunningGraphs: true` migrates ownership to the new session.
121
+
122
+ ## Compatibility
123
+
124
+ - `getState()` remains available and returns the legacy `SessionState`.
125
+ - New code should prefer `getSnapshot()`.
126
+ - `session_id` fields on request messages remain the routing identifier.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theway-ai/sdk",
3
- "version": "2.2.0",
3
+ "version": "2.2.1",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -21,6 +21,7 @@
21
21
  "files": [
22
22
  "dist",
23
23
  "proto",
24
+ "docs",
24
25
  "README.md"
25
26
  ],
26
27
  "engines": {