@buildanagent/protocol 0.0.0-bootstrap.0 → 0.1.0-alpha.28
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.
- package/LICENSE +54 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +86 -0
- package/dist/entries.d.ts +328 -0
- package/dist/entries.js +83 -0
- package/dist/entries.js.map +1 -0
- package/dist/errors.d.ts +24 -0
- package/dist/errors.js +21 -0
- package/dist/errors.js.map +1 -0
- package/dist/framer.d.ts +35 -0
- package/dist/framer.js +124 -0
- package/dist/framer.js.map +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -0
- package/dist/jsonrpc.d.ts +58 -0
- package/dist/jsonrpc.js +141 -0
- package/dist/jsonrpc.js.map +1 -0
- package/dist/messages.d.ts +305 -0
- package/dist/messages.js +2 -0
- package/dist/messages.js.map +1 -0
- package/llms.txt +88 -0
- package/package.json +42 -5
|
@@ -0,0 +1,305 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The harness protocol's messages: the client's commands, the server's requests and notifications, and the results that
|
|
3
|
+
* answer them. Every message is JSON-RPC 2.0 and carries `"jsonrpc": "2.0"`. These types are the contract, and
|
|
4
|
+
* `schema/protocol.schema.json` is generated from a mirror of them for clients in other languages.
|
|
5
|
+
*/
|
|
6
|
+
import type { ContentBlock, ModelContent } from "@buildanagent/gateway";
|
|
7
|
+
import type { AgentEvent, Resolution, SignedPendingRequest } from "@buildanagent/sdk";
|
|
8
|
+
import type { SessionEntry, TurnEndEntry } from "./entries.js";
|
|
9
|
+
/** A request id: a number or a string. A response carries the id of the request it answers. */
|
|
10
|
+
export type Id = number | string;
|
|
11
|
+
/** Who a client says it is, in `initialize`. */
|
|
12
|
+
export interface ClientInfo {
|
|
13
|
+
name: string;
|
|
14
|
+
version: string;
|
|
15
|
+
}
|
|
16
|
+
/** What a client sends. A command with an `id` gets one response, and `$/cancelRequest` has none. */
|
|
17
|
+
export type ClientCommand = {
|
|
18
|
+
jsonrpc: "2.0";
|
|
19
|
+
id: Id;
|
|
20
|
+
method: "initialize";
|
|
21
|
+
params: {
|
|
22
|
+
clientInfo: ClientInfo;
|
|
23
|
+
capabilities: string[];
|
|
24
|
+
};
|
|
25
|
+
} | {
|
|
26
|
+
jsonrpc: "2.0";
|
|
27
|
+
id: Id;
|
|
28
|
+
method: "session/create";
|
|
29
|
+
params: {
|
|
30
|
+
session?: string;
|
|
31
|
+
cwd: string;
|
|
32
|
+
};
|
|
33
|
+
} | {
|
|
34
|
+
jsonrpc: "2.0";
|
|
35
|
+
id: Id;
|
|
36
|
+
method: "session/open";
|
|
37
|
+
params: {
|
|
38
|
+
session?: string;
|
|
39
|
+
cwd: string;
|
|
40
|
+
/**
|
|
41
|
+
* Replays the session's entries from this sequence number on, as `entry_appended` events, before any live event.
|
|
42
|
+
* A client that last saw `seq` N sends N + 1. A value past the log's end is refused with `InvalidParams`.
|
|
43
|
+
*/
|
|
44
|
+
fromSeq?: number;
|
|
45
|
+
};
|
|
46
|
+
} | {
|
|
47
|
+
jsonrpc: "2.0";
|
|
48
|
+
id: Id;
|
|
49
|
+
method: "session/list";
|
|
50
|
+
params: {
|
|
51
|
+
cursor?: string;
|
|
52
|
+
};
|
|
53
|
+
} | {
|
|
54
|
+
jsonrpc: "2.0";
|
|
55
|
+
id: Id;
|
|
56
|
+
method: "turn/start";
|
|
57
|
+
params: {
|
|
58
|
+
session: string;
|
|
59
|
+
input: ContentBlock[];
|
|
60
|
+
};
|
|
61
|
+
/** A trace context, `traceparent` style, so the turn's spans join the client's trace. */
|
|
62
|
+
trace?: string;
|
|
63
|
+
} | {
|
|
64
|
+
jsonrpc: "2.0";
|
|
65
|
+
id: Id;
|
|
66
|
+
method: "turn/steer" | "turn/followUp";
|
|
67
|
+
params: {
|
|
68
|
+
session: string;
|
|
69
|
+
input: ContentBlock[];
|
|
70
|
+
};
|
|
71
|
+
} | {
|
|
72
|
+
jsonrpc: "2.0";
|
|
73
|
+
id: Id;
|
|
74
|
+
method: "turn/interrupt";
|
|
75
|
+
params: {
|
|
76
|
+
session: string;
|
|
77
|
+
reason?: string;
|
|
78
|
+
};
|
|
79
|
+
} | {
|
|
80
|
+
jsonrpc: "2.0";
|
|
81
|
+
id: Id;
|
|
82
|
+
method: "approval/list";
|
|
83
|
+
params: {
|
|
84
|
+
session: string;
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
/** Experimental: a client opts in by listing the method name in its `initialize` capabilities, or the server answers `NotOptedIn`. */
|
|
88
|
+
| {
|
|
89
|
+
jsonrpc: "2.0";
|
|
90
|
+
id: Id;
|
|
91
|
+
method: "session/checkout" | "session/fork";
|
|
92
|
+
params: {
|
|
93
|
+
session: string;
|
|
94
|
+
entryId: string;
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Withdraws one of the client's own requests by id. A cancelled `turn/start` aborts its turn, which still ends with
|
|
99
|
+
* `turn/settled`; any other request may still be answered as usual.
|
|
100
|
+
*/
|
|
101
|
+
| {
|
|
102
|
+
jsonrpc: "2.0";
|
|
103
|
+
method: "$/cancelRequest";
|
|
104
|
+
params: {
|
|
105
|
+
id: Id;
|
|
106
|
+
};
|
|
107
|
+
};
|
|
108
|
+
/** The server's answer to `initialize`. */
|
|
109
|
+
export interface InitializeResult {
|
|
110
|
+
serverInfo: {
|
|
111
|
+
name: string;
|
|
112
|
+
version: string;
|
|
113
|
+
sdkVersion: string;
|
|
114
|
+
specVersion: "v1";
|
|
115
|
+
};
|
|
116
|
+
/** The SDK's capabilities from `run_start`, plus the harness's own. */
|
|
117
|
+
capabilities: string[];
|
|
118
|
+
/** The methods a client must opt into, by listing each method name in the `capabilities` of its `initialize`. */
|
|
119
|
+
experimental: string[];
|
|
120
|
+
/** The requests still waiting for an answer, re-armed for a client that joins. */
|
|
121
|
+
pending: {
|
|
122
|
+
session: string;
|
|
123
|
+
request: SignedPendingRequest;
|
|
124
|
+
}[];
|
|
125
|
+
}
|
|
126
|
+
/** The answer to a turn command: the server took it, or why it did not. */
|
|
127
|
+
export type Disposition = {
|
|
128
|
+
accepted: true;
|
|
129
|
+
turn: string;
|
|
130
|
+
} | {
|
|
131
|
+
accepted: false;
|
|
132
|
+
reason: "busy" | "locked" | "invalid";
|
|
133
|
+
};
|
|
134
|
+
/** The answer to `session/create` and `session/open`. `head` is the entry the session's HEAD points at, or `null` for a new one. */
|
|
135
|
+
export interface SessionOpened {
|
|
136
|
+
session: string;
|
|
137
|
+
head: string | null;
|
|
138
|
+
}
|
|
139
|
+
/** One session in `session/list`. */
|
|
140
|
+
export interface SessionListItem {
|
|
141
|
+
session: string;
|
|
142
|
+
startedAt: string;
|
|
143
|
+
lastEntryAt: string;
|
|
144
|
+
entryCount: number;
|
|
145
|
+
}
|
|
146
|
+
/** The answer to `session/list`. A `nextCursor` means more sessions follow. */
|
|
147
|
+
export interface SessionList {
|
|
148
|
+
sessions: SessionListItem[];
|
|
149
|
+
nextCursor?: string;
|
|
150
|
+
}
|
|
151
|
+
/** The answer to `turn/interrupt`: whether a turn was running to interrupt. */
|
|
152
|
+
export interface InterruptResult {
|
|
153
|
+
interrupted: boolean;
|
|
154
|
+
}
|
|
155
|
+
/** The answer to `approval/list`. */
|
|
156
|
+
export interface ApprovalList {
|
|
157
|
+
pending: SignedPendingRequest[];
|
|
158
|
+
}
|
|
159
|
+
/** The answer to `session/checkout` and `session/fork`: the session now in use and its HEAD. */
|
|
160
|
+
export interface BranchResult {
|
|
161
|
+
session: string;
|
|
162
|
+
head: string;
|
|
163
|
+
}
|
|
164
|
+
/** The result of each client method, by method name. */
|
|
165
|
+
export interface ClientResultMap {
|
|
166
|
+
initialize: InitializeResult;
|
|
167
|
+
"session/create": SessionOpened;
|
|
168
|
+
"session/open": SessionOpened;
|
|
169
|
+
"session/list": SessionList;
|
|
170
|
+
"turn/start": Disposition;
|
|
171
|
+
"turn/steer": Disposition;
|
|
172
|
+
"turn/followUp": Disposition;
|
|
173
|
+
"turn/interrupt": InterruptResult;
|
|
174
|
+
"approval/list": ApprovalList;
|
|
175
|
+
"session/checkout": BranchResult;
|
|
176
|
+
"session/fork": BranchResult;
|
|
177
|
+
}
|
|
178
|
+
/** What a server request's client answer holds, by method name. */
|
|
179
|
+
export interface ServerResultMap {
|
|
180
|
+
"approval/request": {
|
|
181
|
+
resolutions: Resolution[];
|
|
182
|
+
};
|
|
183
|
+
"clarification/request": {
|
|
184
|
+
resolutions: Resolution[];
|
|
185
|
+
};
|
|
186
|
+
"tool/call": {
|
|
187
|
+
content: ModelContent[];
|
|
188
|
+
isError: boolean;
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
/** A JSON-RPC error object. `code` is one of `ErrorCodes` or a code an extension defines. */
|
|
192
|
+
export interface RpcError {
|
|
193
|
+
code: number;
|
|
194
|
+
message: string;
|
|
195
|
+
data?: unknown;
|
|
196
|
+
}
|
|
197
|
+
/** A response: the result of one request, or an error. An error to a message whose id could not be read has id `null`. */
|
|
198
|
+
export type ResponseMessage<Result> = {
|
|
199
|
+
jsonrpc: "2.0";
|
|
200
|
+
id: Id;
|
|
201
|
+
result: Result;
|
|
202
|
+
} | {
|
|
203
|
+
jsonrpc: "2.0";
|
|
204
|
+
id: Id | null;
|
|
205
|
+
error: RpcError;
|
|
206
|
+
};
|
|
207
|
+
/** What the server asks the client for. The client answers with a response carrying the same id. */
|
|
208
|
+
export type ServerRequest = {
|
|
209
|
+
jsonrpc: "2.0";
|
|
210
|
+
id: string;
|
|
211
|
+
method: "approval/request";
|
|
212
|
+
params: {
|
|
213
|
+
session: string;
|
|
214
|
+
request: SignedPendingRequest;
|
|
215
|
+
group?: string[];
|
|
216
|
+
};
|
|
217
|
+
} | {
|
|
218
|
+
jsonrpc: "2.0";
|
|
219
|
+
id: string;
|
|
220
|
+
method: "clarification/request";
|
|
221
|
+
params: {
|
|
222
|
+
session: string;
|
|
223
|
+
request: SignedPendingRequest;
|
|
224
|
+
};
|
|
225
|
+
} | {
|
|
226
|
+
jsonrpc: "2.0";
|
|
227
|
+
id: string;
|
|
228
|
+
method: "tool/call";
|
|
229
|
+
params: {
|
|
230
|
+
session: string;
|
|
231
|
+
callId: string;
|
|
232
|
+
tool: string;
|
|
233
|
+
input: unknown;
|
|
234
|
+
};
|
|
235
|
+
};
|
|
236
|
+
/** How a turn ended, in `turn/settled`. */
|
|
237
|
+
export interface TurnResultSummary {
|
|
238
|
+
stopReason: TurnEndEntry["stopReason"];
|
|
239
|
+
steps: number;
|
|
240
|
+
/** The turn's cost in US dollars, or `null` when a price is unknown. */
|
|
241
|
+
costUsd: number | null;
|
|
242
|
+
error?: {
|
|
243
|
+
kind: string;
|
|
244
|
+
message: string;
|
|
245
|
+
};
|
|
246
|
+
}
|
|
247
|
+
/** What the harness adds to the SDK's events. */
|
|
248
|
+
export type HarnessEvent = {
|
|
249
|
+
type: "entry_appended";
|
|
250
|
+
entry: SessionEntry;
|
|
251
|
+
} | {
|
|
252
|
+
type: "budget_warning";
|
|
253
|
+
spentUsd: number;
|
|
254
|
+
capUsd: number;
|
|
255
|
+
} | {
|
|
256
|
+
type: "context_fill";
|
|
257
|
+
tokens: number;
|
|
258
|
+
budget: number;
|
|
259
|
+
} | {
|
|
260
|
+
type: "completion_check";
|
|
261
|
+
entry: SessionEntry;
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* The server dropped `count` events of this session because the client was not taking them fast enough. The
|
|
265
|
+
* notification's `seq` is the last dropped event's. Live events go on after the marker. A client recovers the dropped
|
|
266
|
+
* entries with `session/open` and a `fromSeq` one past the last `seq` it received before the marker, and drops by
|
|
267
|
+
* `seq` any entry it then gets twice.
|
|
268
|
+
*/
|
|
269
|
+
| {
|
|
270
|
+
type: "events_dropped";
|
|
271
|
+
count: number;
|
|
272
|
+
};
|
|
273
|
+
/**
|
|
274
|
+
* What the server sends without being asked. `event` carries a sequence number, and every turn ends with `turn/settled`.
|
|
275
|
+
* `$/cancelRequest` withdraws a server request the client has not answered: the server ignores any answer that arrives after the withdrawal.
|
|
276
|
+
*/
|
|
277
|
+
export type ServerNotification = {
|
|
278
|
+
jsonrpc: "2.0";
|
|
279
|
+
method: "event";
|
|
280
|
+
params: {
|
|
281
|
+
session: string;
|
|
282
|
+
seq: number;
|
|
283
|
+
event: AgentEvent | HarnessEvent;
|
|
284
|
+
};
|
|
285
|
+
} | {
|
|
286
|
+
jsonrpc: "2.0";
|
|
287
|
+
method: "turn/settled";
|
|
288
|
+
params: {
|
|
289
|
+
session: string;
|
|
290
|
+
turn: string;
|
|
291
|
+
result: TurnResultSummary;
|
|
292
|
+
};
|
|
293
|
+
} | {
|
|
294
|
+
jsonrpc: "2.0";
|
|
295
|
+
method: "$/cancelRequest";
|
|
296
|
+
params: {
|
|
297
|
+
id: Id;
|
|
298
|
+
};
|
|
299
|
+
};
|
|
300
|
+
/** Everything a client sends: commands, and answers to the server's requests. */
|
|
301
|
+
export type ClientMessage = ClientCommand | ResponseMessage<ServerResultMap[keyof ServerResultMap]>;
|
|
302
|
+
/** Everything a server sends: answers to commands, requests and notifications. */
|
|
303
|
+
export type ServerMessage = ResponseMessage<ClientResultMap[keyof ClientResultMap]> | ServerRequest | ServerNotification;
|
|
304
|
+
/** Any message of the protocol, in either direction. */
|
|
305
|
+
export type ProtocolMessage = ClientMessage | ServerMessage;
|
package/dist/messages.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The harness protocol's messages: the client's commands, the server's requests and notifications, and the results that\n * answer them. Every message is JSON-RPC 2.0 and carries `\"jsonrpc\": \"2.0\"`. These types are the contract, and\n * `schema/protocol.schema.json` is generated from a mirror of them for clients in other languages.\n */\nimport type { ContentBlock, ModelContent } from \"@buildanagent/gateway\";\nimport type { AgentEvent, Resolution, SignedPendingRequest } from \"@buildanagent/sdk\";\nimport type { SessionEntry, TurnEndEntry } from \"./entries.js\";\n\n/** A request id: a number or a string. A response carries the id of the request it answers. */\nexport type Id = number | string;\n\n/** Who a client says it is, in `initialize`. */\nexport interface ClientInfo {\n name: string;\n version: string;\n}\n\n/** What a client sends. A command with an `id` gets one response, and `$/cancelRequest` has none. */\nexport type ClientCommand =\n | {\n jsonrpc: \"2.0\";\n id: Id;\n method: \"initialize\";\n params: { clientInfo: ClientInfo; capabilities: string[] };\n }\n | { jsonrpc: \"2.0\"; id: Id; method: \"session/create\"; params: { session?: string; cwd: string } }\n | {\n jsonrpc: \"2.0\";\n id: Id;\n method: \"session/open\";\n params: {\n session?: string;\n cwd: string;\n /**\n * Replays the session's entries from this sequence number on, as `entry_appended` events, before any live event.\n * A client that last saw `seq` N sends N + 1. A value past the log's end is refused with `InvalidParams`.\n */\n fromSeq?: number;\n };\n }\n | { jsonrpc: \"2.0\"; id: Id; method: \"session/list\"; params: { cursor?: string } }\n | {\n jsonrpc: \"2.0\";\n id: Id;\n method: \"turn/start\";\n params: { session: string; input: ContentBlock[] };\n /** A trace context, `traceparent` style, so the turn's spans join the client's trace. */\n trace?: string;\n }\n | {\n jsonrpc: \"2.0\";\n id: Id;\n method: \"turn/steer\" | \"turn/followUp\";\n params: { session: string; input: ContentBlock[] };\n }\n | { jsonrpc: \"2.0\"; id: Id; method: \"turn/interrupt\"; params: { session: string; reason?: string } }\n | { jsonrpc: \"2.0\"; id: Id; method: \"approval/list\"; params: { session: string } }\n /** Experimental: a client opts in by listing the method name in its `initialize` capabilities, or the server answers `NotOptedIn`. */\n | {\n jsonrpc: \"2.0\";\n id: Id;\n method: \"session/checkout\" | \"session/fork\";\n params: { session: string; entryId: string };\n }\n /**\n * Withdraws one of the client's own requests by id. A cancelled `turn/start` aborts its turn, which still ends with\n * `turn/settled`; any other request may still be answered as usual.\n */\n | { jsonrpc: \"2.0\"; method: \"$/cancelRequest\"; params: { id: Id } };\n\n/** The server's answer to `initialize`. */\nexport interface InitializeResult {\n serverInfo: { name: string; version: string; sdkVersion: string; specVersion: \"v1\" };\n /** The SDK's capabilities from `run_start`, plus the harness's own. */\n capabilities: string[];\n /** The methods a client must opt into, by listing each method name in the `capabilities` of its `initialize`. */\n experimental: string[];\n /** The requests still waiting for an answer, re-armed for a client that joins. */\n pending: { session: string; request: SignedPendingRequest }[];\n}\n\n/** The answer to a turn command: the server took it, or why it did not. */\nexport type Disposition = { accepted: true; turn: string } | { accepted: false; reason: \"busy\" | \"locked\" | \"invalid\" };\n\n/** The answer to `session/create` and `session/open`. `head` is the entry the session's HEAD points at, or `null` for a new one. */\nexport interface SessionOpened {\n session: string;\n head: string | null;\n}\n\n/** One session in `session/list`. */\nexport interface SessionListItem {\n session: string;\n startedAt: string;\n lastEntryAt: string;\n entryCount: number;\n}\n\n/** The answer to `session/list`. A `nextCursor` means more sessions follow. */\nexport interface SessionList {\n sessions: SessionListItem[];\n nextCursor?: string;\n}\n\n/** The answer to `turn/interrupt`: whether a turn was running to interrupt. */\nexport interface InterruptResult {\n interrupted: boolean;\n}\n\n/** The answer to `approval/list`. */\nexport interface ApprovalList {\n pending: SignedPendingRequest[];\n}\n\n/** The answer to `session/checkout` and `session/fork`: the session now in use and its HEAD. */\nexport interface BranchResult {\n session: string;\n head: string;\n}\n\n/** The result of each client method, by method name. */\nexport interface ClientResultMap {\n initialize: InitializeResult;\n \"session/create\": SessionOpened;\n \"session/open\": SessionOpened;\n \"session/list\": SessionList;\n \"turn/start\": Disposition;\n \"turn/steer\": Disposition;\n \"turn/followUp\": Disposition;\n \"turn/interrupt\": InterruptResult;\n \"approval/list\": ApprovalList;\n \"session/checkout\": BranchResult;\n \"session/fork\": BranchResult;\n}\n\n/** What a server request's client answer holds, by method name. */\nexport interface ServerResultMap {\n \"approval/request\": { resolutions: Resolution[] };\n \"clarification/request\": { resolutions: Resolution[] };\n \"tool/call\": { content: ModelContent[]; isError: boolean };\n}\n\n/** A JSON-RPC error object. `code` is one of `ErrorCodes` or a code an extension defines. */\nexport interface RpcError {\n code: number;\n message: string;\n data?: unknown;\n}\n\n/** A response: the result of one request, or an error. An error to a message whose id could not be read has id `null`. */\nexport type ResponseMessage<Result> =\n | { jsonrpc: \"2.0\"; id: Id; result: Result }\n | { jsonrpc: \"2.0\"; id: Id | null; error: RpcError };\n\n/** What the server asks the client for. The client answers with a response carrying the same id. */\nexport type ServerRequest =\n | {\n jsonrpc: \"2.0\";\n id: string;\n method: \"approval/request\";\n params: { session: string; request: SignedPendingRequest; group?: string[] };\n }\n | {\n jsonrpc: \"2.0\";\n id: string;\n method: \"clarification/request\";\n params: { session: string; request: SignedPendingRequest };\n }\n | {\n jsonrpc: \"2.0\";\n id: string;\n method: \"tool/call\";\n params: { session: string; callId: string; tool: string; input: unknown };\n };\n\n/** How a turn ended, in `turn/settled`. */\nexport interface TurnResultSummary {\n stopReason: TurnEndEntry[\"stopReason\"];\n steps: number;\n /** The turn's cost in US dollars, or `null` when a price is unknown. */\n costUsd: number | null;\n error?: { kind: string; message: string };\n}\n\n/** What the harness adds to the SDK's events. */\nexport type HarnessEvent =\n | { type: \"entry_appended\"; entry: SessionEntry }\n | { type: \"budget_warning\"; spentUsd: number; capUsd: number }\n | { type: \"context_fill\"; tokens: number; budget: number }\n | { type: \"completion_check\"; entry: SessionEntry }\n /**\n * The server dropped `count` events of this session because the client was not taking them fast enough. The\n * notification's `seq` is the last dropped event's. Live events go on after the marker. A client recovers the dropped\n * entries with `session/open` and a `fromSeq` one past the last `seq` it received before the marker, and drops by\n * `seq` any entry it then gets twice.\n */\n | { type: \"events_dropped\"; count: number };\n\n/**\n * What the server sends without being asked. `event` carries a sequence number, and every turn ends with `turn/settled`.\n * `$/cancelRequest` withdraws a server request the client has not answered: the server ignores any answer that arrives after the withdrawal.\n */\nexport type ServerNotification =\n | { jsonrpc: \"2.0\"; method: \"event\"; params: { session: string; seq: number; event: AgentEvent | HarnessEvent } }\n | { jsonrpc: \"2.0\"; method: \"turn/settled\"; params: { session: string; turn: string; result: TurnResultSummary } }\n | { jsonrpc: \"2.0\"; method: \"$/cancelRequest\"; params: { id: Id } };\n\n/** Everything a client sends: commands, and answers to the server's requests. */\nexport type ClientMessage = ClientCommand | ResponseMessage<ServerResultMap[keyof ServerResultMap]>;\n\n/** Everything a server sends: answers to commands, requests and notifications. */\nexport type ServerMessage =\n | ResponseMessage<ClientResultMap[keyof ClientResultMap]>\n | ServerRequest\n | ServerNotification;\n\n/** Any message of the protocol, in either direction. */\nexport type ProtocolMessage = ClientMessage | ServerMessage;\n"]}
|
package/llms.txt
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# @buildanagent/protocol
|
|
2
|
+
|
|
3
|
+
> The wire types of the buildanagent harness: the session entry union, the client and server messages and their JSONL framing.
|
|
4
|
+
|
|
5
|
+
The sections of README.md and every public export, generated from this package's README and declaration files in the same commit as its code.
|
|
6
|
+
|
|
7
|
+
## Docs
|
|
8
|
+
|
|
9
|
+
- [Install the alpha with `pnpm add @buildanagent/protocol@alpha`](README.md#install-the-alpha-with-pnpm-add-buildanagentprotocolalpha)
|
|
10
|
+
- [A session file is a list of entries, one per line](README.md#a-session-file-is-a-list-of-entries-one-per-line)
|
|
11
|
+
- [`parseEntry()` reads a line and refuses a format it does not know](README.md#parseentry-reads-a-line-and-refuses-a-format-it-does-not-know)
|
|
12
|
+
- [The JSON Schema describes every entry for other languages](README.md#the-json-schema-describes-every-entry-for-other-languages)
|
|
13
|
+
- [The protocol is JSON-RPC 2.0, one message per line](README.md#the-protocol-is-json-rpc-20-one-message-per-line)
|
|
14
|
+
- [The framer splits on newlines only](README.md#the-framer-splits-on-newlines-only)
|
|
15
|
+
- [The protocol schema covers every message](README.md#the-protocol-schema-covers-every-message)
|
|
16
|
+
- [Over stdio, each message is one line, and stdout carries nothing else](README.md#over-stdio-each-message-is-one-line-and-stdout-carries-nothing-else)
|
|
17
|
+
- [Two outside JSON-RPC libraries read every message the server sends](README.md#two-outside-json-rpc-libraries-read-every-message-the-server-sends)
|
|
18
|
+
|
|
19
|
+
## Exports from `@buildanagent/protocol`
|
|
20
|
+
|
|
21
|
+
- `interface ApprovalList`: The answer to `approval/list`.
|
|
22
|
+
- `type ApprovalPolicy`: When a sandboxed call may ask a person: on request, by granular rule, or never.
|
|
23
|
+
- `interface BranchResult`: The answer to `session/checkout` and `session/fork`: the session now in use and its HEAD.
|
|
24
|
+
- `interface CheckoutEntry`: HEAD moved to another entry.
|
|
25
|
+
- `CLIENT_METHODS`: The methods a client may call.
|
|
26
|
+
- `type ClientCommand`: What a client sends.
|
|
27
|
+
- `interface ClientInfo`: Who a client says it is, in `initialize`.
|
|
28
|
+
- `type ClientMessage`: Everything a client sends: commands, and answers to the server's requests.
|
|
29
|
+
- `interface ClientResultMap`: The result of each client method, by method name.
|
|
30
|
+
- `interface CodeCallEntry`: A tool call that the host's own code chose to make, with no model step.
|
|
31
|
+
- `interface CompactionEntry`: A summary replaced older entries in the context a rebuilt run sends.
|
|
32
|
+
- `interface CompletionCheckEntry`: The commands that checked a finished task, and whether they passed.
|
|
33
|
+
- `decode()`: Reads one message from a line of JSON text or a parsed value, and checks its envelope.
|
|
34
|
+
- `DEFAULT_MAX_LINE_BYTES`: The default bound on one line, in bytes.
|
|
35
|
+
- `type Disposition`: The answer to a turn command: the server took it, or why it did not.
|
|
36
|
+
- `encode()`: Turns a message into one line of JSON ending in `\n`, after the same envelope check `decode()` makes.
|
|
37
|
+
- `interface EntryBase`: The fields every entry has, with its `type`.
|
|
38
|
+
- `interface EnvStampEntry`: The environment a session ran in.
|
|
39
|
+
- `ErrorCodes`: The JSON-RPC error codes the protocol uses: the standard ones, and three of its own in the server-error range.
|
|
40
|
+
- `EXPERIMENTAL_METHODS`: The client methods that need an opt-in, because they may change before a client other than ours uses them.
|
|
41
|
+
- `interface ExtensionLoadedEntry`: An extension was loaded, with the hash of what ran.
|
|
42
|
+
- `FORMAT_VERSION`: The format version of every entry this package writes and reads.
|
|
43
|
+
- `type FramedMessage`: One line of the stream: its parsed JSON, or why it could not be read.
|
|
44
|
+
- `type HarnessEvent`: What the harness adds to the SDK's events.
|
|
45
|
+
- `type Id`: A request id: a number or a string.
|
|
46
|
+
- `interface InitializeResult`: The server's answer to `initialize`.
|
|
47
|
+
- `interface InterruptResult`: The answer to `turn/interrupt`: whether a turn was running to interrupt.
|
|
48
|
+
- `isProtocolError()`: True for a `ProtocolError`, including one from another copy of the package.
|
|
49
|
+
- `class JsonlFramer`: Feed it chunks as they arrive.
|
|
50
|
+
- `interface JsonlFramerOptions`: The options of `JsonlFramer`.
|
|
51
|
+
- `type JsonRpcMessage`: A JSON-RPC message as `decode()` reads it: the envelope is checked, and `params` and `result` are not.
|
|
52
|
+
- `interface LoadoutEntry`: The tools and model in force changed.
|
|
53
|
+
- `interface McpServerRecord`: What an `extension_loaded` entry of tier `mcp` records about the server that connected.
|
|
54
|
+
- `interface MessageBlockEntry`: One content block of a message.
|
|
55
|
+
- `interface MessageEndEntry`: A message is complete: which model wrote it and why it stopped.
|
|
56
|
+
- `type Origin`: Who produced an entry's content.
|
|
57
|
+
- `PACKAGE_NAME`: The package's name.
|
|
58
|
+
- `parseEntry()`: Reads one session entry from a JSON line or an already parsed value, and checks what every reader relies on: it is an object with valid base fields, its `type` is in the union, and a `session_header` has this package's `formatVersion`.
|
|
59
|
+
- `interface PermissionDecisionEntry`: The permission pipeline's decision on one tool call, written for every decision.
|
|
60
|
+
- `type PermissionMode`: How tool calls are decided: `shadow` records what would have happened without doing it.
|
|
61
|
+
- `interface ProductRecordEntry`: A record that the product owns.
|
|
62
|
+
- `class ProtocolError`: The error every `@buildanagent/protocol` function throws.
|
|
63
|
+
- `type ProtocolErrorCode`: Why something was refused.
|
|
64
|
+
- `interface ProtocolErrorOptions`: What a `ProtocolError` carries when it is also a JSON-RPC error a peer can be answered with.
|
|
65
|
+
- `type ProtocolMessage`: Any message of the protocol, in either direction.
|
|
66
|
+
- `type ResponseMessage`: A response: the result of one request, or an error.
|
|
67
|
+
- `interface RpcError`: A JSON-RPC error object.
|
|
68
|
+
- `type SandboxTier`: How strongly a sandbox isolates a run, from none to a micro-VM.
|
|
69
|
+
- `SERVER_NOTIFICATION_METHODS`: The notifications the server sends.
|
|
70
|
+
- `SERVER_REQUEST_METHODS`: The requests the server sends.
|
|
71
|
+
- `type ServerMessage`: Everything a server sends: answers to commands, requests and notifications.
|
|
72
|
+
- `type ServerNotification`: What the server sends without being asked.
|
|
73
|
+
- `type ServerRequest`: What the server asks the client for.
|
|
74
|
+
- `interface ServerResultMap`: What a server request's client answer holds, by method name.
|
|
75
|
+
- `SESSION_ENTRY_TYPES`: The `type` of every entry in the union, in the order the union lists them.
|
|
76
|
+
- `type SessionEntry`: One line of a session file.
|
|
77
|
+
- `interface SessionHeaderEntry`: The first entry of a session file: what ran the session, and which session it came from.
|
|
78
|
+
- `interface SessionList`: The answer to `session/list`.
|
|
79
|
+
- `interface SessionListItem`: One session in `session/list`.
|
|
80
|
+
- `interface SessionOpened`: The answer to `session/create` and `session/open`.
|
|
81
|
+
- `interface ShadowCallEntry`: A call that shadow mode recorded and did not run.
|
|
82
|
+
- `interface SkillLoadedEntry`: A skill's instructions entered the context.
|
|
83
|
+
- `interface SubagentLinkEntry`: A child session exists.
|
|
84
|
+
- `interface ToolResultEntry`: What a tool call returned to the model.
|
|
85
|
+
- `interface TurnEndEntry`: A turn ended, with the stop reason of its run.
|
|
86
|
+
- `interface TurnResultSummary`: How a turn ended, in `turn/settled`.
|
|
87
|
+
- `interface TurnStartEntry`: A turn began.
|
|
88
|
+
- `interface UsageEntry`: The tokens and cost of one model call, a summary or a judge call.
|
package/package.json
CHANGED
|
@@ -1,7 +1,44 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@buildanagent/protocol",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
5
|
-
"license": "
|
|
6
|
-
"
|
|
7
|
-
|
|
3
|
+
"version": "0.1.0-alpha.28",
|
|
4
|
+
"description": "The wire types of the buildanagent harness: the session entry union, the client and server messages and their JSONL framing.",
|
|
5
|
+
"license": "Apache-2.0 OR MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/laudebugs/buildanagent.git",
|
|
9
|
+
"directory": "packages/protocol"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/laudebugs/buildanagent/tree/main/packages/protocol#readme",
|
|
12
|
+
"type": "module",
|
|
13
|
+
"sideEffects": false,
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=22.19.0"
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"dist",
|
|
19
|
+
"llms.txt",
|
|
20
|
+
"LICENSE",
|
|
21
|
+
"LICENSE-APACHE",
|
|
22
|
+
"LICENSE-MIT"
|
|
23
|
+
],
|
|
24
|
+
"exports": {
|
|
25
|
+
".": {
|
|
26
|
+
"types": "./dist/index.d.ts",
|
|
27
|
+
"default": "./dist/index.js"
|
|
28
|
+
}
|
|
29
|
+
},
|
|
30
|
+
"dependencies": {
|
|
31
|
+
"@buildanagent/gateway": "0.1.0-alpha.28",
|
|
32
|
+
"@buildanagent/sdk": "0.1.0-alpha.28"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"@cfworker/json-schema": "4.1.6",
|
|
36
|
+
"zod": "4.6.7"
|
|
37
|
+
},
|
|
38
|
+
"scripts": {
|
|
39
|
+
"build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
|
|
40
|
+
"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.schema.json",
|
|
41
|
+
"test": "vitest run",
|
|
42
|
+
"schema": "tsx scripts/generate-schema.ts"
|
|
43
|
+
}
|
|
44
|
+
}
|