@botiverse/raft-sdk 0.1.1 → 0.2.0
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/README.md +171 -4
- package/dist/cjs/index.cjs +7655 -6488
- package/dist/esm/index.js +7643 -6457
- package/dist/index.d.ts +931 -291
- package/package.json +12 -9
package/dist/index.d.ts
CHANGED
|
@@ -1,291 +1,931 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
}
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
}
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
}
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
//#region ../shared/src/agentApiMessageContract.d.ts
|
|
3
|
+
interface AgentApiStructuredMention {
|
|
4
|
+
type: "user" | "agent";
|
|
5
|
+
id: string;
|
|
6
|
+
name: string;
|
|
7
|
+
}
|
|
8
|
+
interface AgentApiExternalMessageProvenance {
|
|
9
|
+
schema: "external-message-provenance.v1";
|
|
10
|
+
provider: string;
|
|
11
|
+
workspace_id: string;
|
|
12
|
+
conversation_id: string;
|
|
13
|
+
message_id: string;
|
|
14
|
+
actor_id: string;
|
|
15
|
+
actor_kind: "human" | "guest" | "remote" | "bot" | "unknown";
|
|
16
|
+
projection_id: string;
|
|
17
|
+
}
|
|
18
|
+
interface AgentApiSendBodyKnownFields {
|
|
19
|
+
target?: string;
|
|
20
|
+
content?: string;
|
|
21
|
+
attachmentIds?: string[];
|
|
22
|
+
idempotencyKey?: string;
|
|
23
|
+
reconcileOnly?: boolean;
|
|
24
|
+
continue?: boolean;
|
|
25
|
+
sendDraft?: boolean;
|
|
26
|
+
continueAnyway?: boolean;
|
|
27
|
+
draftReholdCount?: number;
|
|
28
|
+
draftReplacedExisting?: boolean;
|
|
29
|
+
seenUpToSeq?: number;
|
|
30
|
+
seenExactSeqs?: number[];
|
|
31
|
+
freshnessContextMode?: "inline" | "withheld";
|
|
32
|
+
}
|
|
33
|
+
interface AgentApiSendBody extends AgentApiSendBodyKnownFields {
|
|
34
|
+
[key: string]: unknown;
|
|
35
|
+
}
|
|
36
|
+
interface AgentApiSendV2Body extends AgentApiSendBodyKnownFields {
|
|
37
|
+
mentions?: AgentApiStructuredMention[];
|
|
38
|
+
[key: string]: unknown;
|
|
39
|
+
}
|
|
40
|
+
interface AgentApiAttachmentEnvelope {
|
|
41
|
+
id: string;
|
|
42
|
+
filename: string;
|
|
43
|
+
[key: string]: unknown;
|
|
44
|
+
}
|
|
45
|
+
interface AgentApiMessageEnvelope {
|
|
46
|
+
seq?: number;
|
|
47
|
+
id?: string;
|
|
48
|
+
message_id?: string;
|
|
49
|
+
timestamp?: string;
|
|
50
|
+
createdAt?: string;
|
|
51
|
+
senderType?: string;
|
|
52
|
+
sender_type?: string;
|
|
53
|
+
senderName?: string;
|
|
54
|
+
sender_name?: string;
|
|
55
|
+
senderDescription?: string | null;
|
|
56
|
+
sender_description?: string | null;
|
|
57
|
+
external_message?: AgentApiExternalMessageProvenance;
|
|
58
|
+
channel_type?: string;
|
|
59
|
+
channel_name?: string;
|
|
60
|
+
parent_channel_type?: string;
|
|
61
|
+
parent_channel_name?: string;
|
|
62
|
+
content?: string;
|
|
63
|
+
attachments?: AgentApiAttachmentEnvelope[];
|
|
64
|
+
taskStatus?: string | null;
|
|
65
|
+
task_status?: string | null;
|
|
66
|
+
taskNumber?: number | null;
|
|
67
|
+
task_number?: number | null;
|
|
68
|
+
taskAssigneeId?: string | null;
|
|
69
|
+
task_assignee_id?: string | null;
|
|
70
|
+
taskAssigneeType?: string | null;
|
|
71
|
+
task_assignee_type?: string | null;
|
|
72
|
+
taskAssigneeName?: string | null;
|
|
73
|
+
task_assignee_name?: string | null;
|
|
74
|
+
threadId?: string | null;
|
|
75
|
+
replyCount?: number | null;
|
|
76
|
+
[key: string]: unknown;
|
|
77
|
+
}
|
|
78
|
+
interface AgentApiHeldFreshnessResponse {
|
|
79
|
+
ok?: true;
|
|
80
|
+
state: "held";
|
|
81
|
+
outcome?: "held";
|
|
82
|
+
subtype?: "freshness";
|
|
83
|
+
reason?: string;
|
|
84
|
+
decision?: "local_hold" | "syncing_hold";
|
|
85
|
+
producerFactId?: string;
|
|
86
|
+
available_actions?: string[];
|
|
87
|
+
heldMessages?: AgentApiMessageEnvelope[];
|
|
88
|
+
recentUnread?: AgentApiMessageEnvelope[];
|
|
89
|
+
newMessageCount?: number;
|
|
90
|
+
shownMessageCount?: number;
|
|
91
|
+
omittedMessageCount?: number;
|
|
92
|
+
mentionAnnotation?: {
|
|
93
|
+
formalMentionCount: number;
|
|
94
|
+
[key: string]: unknown;
|
|
95
|
+
};
|
|
96
|
+
continueAnywaySuggested?: boolean;
|
|
97
|
+
freshnessContextMode?: "inline" | "withheld";
|
|
98
|
+
withheldMessageCount?: number;
|
|
99
|
+
seenUpToSeq?: number;
|
|
100
|
+
seenUpToMessageId?: string | null;
|
|
101
|
+
/** Lowest seq inside the displayed held window (--before anchor for browsing older). */
|
|
102
|
+
firstShownSeq?: number;
|
|
103
|
+
/** Thread-start anchor for thread targets (freshness-hold digest). */
|
|
104
|
+
threadParentMessage?: {
|
|
105
|
+
seq: number;
|
|
106
|
+
messageId?: string;
|
|
107
|
+
senderName?: string | null;
|
|
108
|
+
createdAt?: string | null;
|
|
109
|
+
content?: string;
|
|
110
|
+
};
|
|
111
|
+
[key: string]: unknown;
|
|
112
|
+
}
|
|
113
|
+
interface AgentApiSendSentResponse {
|
|
114
|
+
ok: true;
|
|
115
|
+
state: "sent";
|
|
116
|
+
messageId: string;
|
|
117
|
+
messageSeq?: number;
|
|
118
|
+
recentUnread?: AgentApiMessageEnvelope[];
|
|
119
|
+
pendingMentionActions?: AgentApiMessageEnvelope[];
|
|
120
|
+
unresolvedMentionHandles?: string[];
|
|
121
|
+
attention?: {
|
|
122
|
+
driveByJoinedToPost?: {
|
|
123
|
+
reason?: string;
|
|
124
|
+
muteCommand?: string;
|
|
125
|
+
stillArrives?: string[];
|
|
126
|
+
[key: string]: unknown;
|
|
127
|
+
};
|
|
128
|
+
[key: string]: unknown;
|
|
129
|
+
};
|
|
130
|
+
[key: string]: unknown;
|
|
131
|
+
}
|
|
132
|
+
interface AgentApiSendNotFoundResponse {
|
|
133
|
+
ok: true;
|
|
134
|
+
state: "not_found";
|
|
135
|
+
reconciliation: true;
|
|
136
|
+
[key: string]: unknown;
|
|
137
|
+
}
|
|
138
|
+
interface AgentApiSendCommittedResponse {
|
|
139
|
+
ok: true;
|
|
140
|
+
state: "committed";
|
|
141
|
+
messageId: string;
|
|
142
|
+
messageSeq?: number;
|
|
143
|
+
reconciliation: true;
|
|
144
|
+
receiptComplete: false;
|
|
145
|
+
[key: string]: unknown;
|
|
146
|
+
}
|
|
147
|
+
type AgentApiSendResponse = AgentApiSendSentResponse | AgentApiHeldFreshnessResponse | AgentApiSendNotFoundResponse | AgentApiSendCommittedResponse;
|
|
148
|
+
//#endregion
|
|
149
|
+
//#region ../shared/src/agentApiMessageClient.d.ts
|
|
150
|
+
type AgentApiMessageClientErrorReason = "request_contract_mismatch" | "transport_error" | "http_error" | "empty_response" | "response_contract_mismatch";
|
|
151
|
+
type AgentApiMessageClientError = {
|
|
152
|
+
kind: "transport";
|
|
153
|
+
reason: "transport_error";
|
|
154
|
+
message: string;
|
|
155
|
+
cause?: unknown;
|
|
156
|
+
} | {
|
|
157
|
+
kind: "http";
|
|
158
|
+
reason: "http_error";
|
|
159
|
+
message: string;
|
|
160
|
+
status: number;
|
|
161
|
+
errorCode?: string | null;
|
|
162
|
+
suggestedNextAction?: string | null;
|
|
163
|
+
proxy?: unknown;
|
|
164
|
+
response?: unknown;
|
|
165
|
+
} | {
|
|
166
|
+
kind: "validation";
|
|
167
|
+
reason: Exclude<AgentApiMessageClientErrorReason, "transport_error" | "http_error">;
|
|
168
|
+
message: string;
|
|
169
|
+
status?: number;
|
|
170
|
+
cause?: unknown;
|
|
171
|
+
response?: unknown;
|
|
172
|
+
};
|
|
173
|
+
interface AgentApiMessageClientSuccess {
|
|
174
|
+
ok: true;
|
|
175
|
+
status: number;
|
|
176
|
+
data: AgentApiSendResponse;
|
|
177
|
+
}
|
|
178
|
+
interface AgentApiMessageClientFailure {
|
|
179
|
+
ok: false;
|
|
180
|
+
status?: number;
|
|
181
|
+
error: AgentApiMessageClientError;
|
|
182
|
+
}
|
|
183
|
+
type AgentApiMessageClientResult = AgentApiMessageClientSuccess | AgentApiMessageClientFailure;
|
|
184
|
+
interface AgentApiMessageTransportRequest {
|
|
185
|
+
method: "POST";
|
|
186
|
+
path: string;
|
|
187
|
+
body: AgentApiSendBody | AgentApiSendV2Body;
|
|
188
|
+
}
|
|
189
|
+
type AgentApiMessageAuthHeaders = Record<string, string>;
|
|
190
|
+
type AgentApiMessageAuthStrategy = AgentApiMessageAuthHeaders | ((request: AgentApiMessageTransportRequest) => AgentApiMessageAuthHeaders | Promise<AgentApiMessageAuthHeaders>);
|
|
191
|
+
interface AgentApiMessageClientOptions {
|
|
192
|
+
baseUrl: string;
|
|
193
|
+
headers?: AgentApiMessageAuthHeaders;
|
|
194
|
+
auth?: AgentApiMessageAuthStrategy;
|
|
195
|
+
fetch?: typeof fetch;
|
|
196
|
+
retry?: {
|
|
197
|
+
attempts?: number;
|
|
198
|
+
};
|
|
199
|
+
throttle?: {
|
|
200
|
+
beforeRequest?: (request: AgentApiMessageTransportRequest) => Promise<void> | void;
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
interface AgentApiMessageClient {
|
|
204
|
+
messages: {
|
|
205
|
+
send(body: AgentApiSendBody): Promise<AgentApiMessageClientResult>;
|
|
206
|
+
sendV2(body: AgentApiSendV2Body): Promise<AgentApiMessageClientResult>;
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
//#endregion
|
|
210
|
+
//#region ../shared/src/agentApiChannelJoin.d.ts
|
|
211
|
+
interface RaftChannelJoinRequest {
|
|
212
|
+
/** Visible regular channel target, for example `#engineering`. */
|
|
213
|
+
target: string;
|
|
214
|
+
}
|
|
215
|
+
type RaftChannelJoinOperation = "validate_target" | "server_info" | "resolve_target" | "channel_join";
|
|
216
|
+
type RaftChannelJoinTransportError = {
|
|
217
|
+
kind: "transport";
|
|
218
|
+
reason: "transport_error";
|
|
219
|
+
message: string;
|
|
220
|
+
cause?: unknown;
|
|
221
|
+
} | {
|
|
222
|
+
kind: "http";
|
|
223
|
+
reason: "http_error";
|
|
224
|
+
message: string;
|
|
225
|
+
status: number;
|
|
226
|
+
errorCode?: string | null;
|
|
227
|
+
suggestedNextAction?: string | null;
|
|
228
|
+
proxy?: unknown;
|
|
229
|
+
response?: unknown;
|
|
230
|
+
} | {
|
|
231
|
+
kind: "validation";
|
|
232
|
+
reason: string;
|
|
233
|
+
message: string;
|
|
234
|
+
status?: number;
|
|
235
|
+
cause?: unknown;
|
|
236
|
+
response?: unknown;
|
|
237
|
+
};
|
|
238
|
+
type RaftChannelJoinError = RaftChannelJoinTransportError | {
|
|
239
|
+
kind: "validation";
|
|
240
|
+
reason: "invalid_target" | "target_not_found";
|
|
241
|
+
message: string;
|
|
242
|
+
};
|
|
243
|
+
interface RaftChannelJoinSuccess {
|
|
244
|
+
ok: true;
|
|
245
|
+
status: number;
|
|
246
|
+
data: {
|
|
247
|
+
state: "joined" | "already_joined";
|
|
248
|
+
target: string;
|
|
249
|
+
channelId: string;
|
|
250
|
+
};
|
|
251
|
+
}
|
|
252
|
+
interface RaftChannelJoinFailure {
|
|
253
|
+
ok: false;
|
|
254
|
+
status?: number;
|
|
255
|
+
operation: RaftChannelJoinOperation;
|
|
256
|
+
error: RaftChannelJoinError;
|
|
257
|
+
}
|
|
258
|
+
type RaftChannelJoinResult = RaftChannelJoinSuccess | RaftChannelJoinFailure;
|
|
259
|
+
type RaftChannelJoinClientResult<T> = {
|
|
260
|
+
ok: true;
|
|
261
|
+
status: number;
|
|
262
|
+
data: T;
|
|
263
|
+
} | {
|
|
264
|
+
ok: false;
|
|
265
|
+
status?: number;
|
|
266
|
+
error: RaftChannelJoinTransportError;
|
|
267
|
+
};
|
|
268
|
+
interface RaftChannelJoinClient<TChannelId extends string = string> {
|
|
269
|
+
server: {
|
|
270
|
+
info(): Promise<RaftChannelJoinClientResult<{
|
|
271
|
+
channels: Array<{
|
|
272
|
+
id: TChannelId;
|
|
273
|
+
name: string;
|
|
274
|
+
joined: boolean;
|
|
275
|
+
}>;
|
|
276
|
+
}>>;
|
|
277
|
+
};
|
|
278
|
+
channels: {
|
|
279
|
+
join(params: {
|
|
280
|
+
channelId: TChannelId;
|
|
281
|
+
}): Promise<RaftChannelJoinClientResult<{
|
|
282
|
+
ok: true;
|
|
283
|
+
}>>;
|
|
284
|
+
};
|
|
285
|
+
}
|
|
286
|
+
//#endregion
|
|
287
|
+
//#region src/channelJoin.d.ts
|
|
288
|
+
export declare function parseRaftRegularChannelTarget(target: string): string | null;
|
|
289
|
+
/**
|
|
290
|
+
* Resolve a visible channel target and join it through the typed Agent API.
|
|
291
|
+
*
|
|
292
|
+
* This is the shared behavior used by both `createRaftClient()` and the Raft
|
|
293
|
+
* CLI. It intentionally does not make message send implicitly join channels.
|
|
294
|
+
*/
|
|
295
|
+
export declare function joinRaftChannelByTarget<TChannelId extends string>(client: RaftChannelJoinClient<TChannelId>, request: RaftChannelJoinRequest): Promise<RaftChannelJoinResult>;
|
|
296
|
+
//#endregion
|
|
297
|
+
//#region ../shared/src/index.d.ts
|
|
298
|
+
/**
|
|
299
|
+
* Scrubbed, classified runtime-error facts that are safe to cross the daemon
|
|
300
|
+
* protocol boundary. Keep every vocabulary closed: upstream exception names,
|
|
301
|
+
* messages, paths, payloads, and arbitrary diagnostic fields do not belong on
|
|
302
|
+
* this carrier.
|
|
303
|
+
*/
|
|
304
|
+
declare const RUNTIME_ERROR_CLASSES: readonly ["RuntimeError", "InputTooLargeError", "RateLimitError", "AuthError", "LauncherError", "NotFoundError", "ModelConfigError", "TimeoutError", "ProviderConnectionError", "ProviderStreamError", "ProviderServerError", "ProviderApiError", "OperationAbortedError", "ToolArgumentParseError"];
|
|
305
|
+
type RuntimeErrorClass = (typeof RUNTIME_ERROR_CLASSES)[number];
|
|
306
|
+
declare const RUNTIME_ERROR_REASONS: readonly ["unclassified_runtime_error", "input_too_large", "rate_limited", "auth_failed", "launcher_error", "not_found", "model_config_error", "provider_timeout", "provider_connection_error", "provider_stream_error", "provider_server_error", "provider_api_error", "operation_aborted", "model_tool_args_invalid"];
|
|
307
|
+
type RuntimeErrorReason = (typeof RUNTIME_ERROR_REASONS)[number];
|
|
308
|
+
declare const RUNTIME_ERROR_REASON_PROVENANCES: readonly ["runtime_error_event", "codex_native_reason", "daemon_fallback", "codex_stderr_signature"];
|
|
309
|
+
type RuntimeErrorReasonProvenance = (typeof RUNTIME_ERROR_REASON_PROVENANCES)[number];
|
|
310
|
+
declare const RUNTIME_CONFIG_VERSION: 1;
|
|
311
|
+
type RuntimeId = "builtin" | "claude" | "codex" | "grok" | "antigravity" | "kimi-sdk" | "kimi" | "copilot" | "cursor" | "gemini" | "opencode" | "pi" | "external";
|
|
312
|
+
/**
|
|
313
|
+
* Claude Code runtime provider config.
|
|
314
|
+
*
|
|
315
|
+
* `apiKey` is intentionally still a plaintext persisted field in the current
|
|
316
|
+
* runtime-config capability. This is a known gap, not a managed-secret or
|
|
317
|
+
* SecretRef contract.
|
|
318
|
+
*/
|
|
319
|
+
type ClaudeRuntimeProviderConfig = {
|
|
320
|
+
kind: "default";
|
|
321
|
+
} | {
|
|
322
|
+
kind: "custom";
|
|
323
|
+
apiUrl: string;
|
|
324
|
+
apiKey: string;
|
|
325
|
+
};
|
|
326
|
+
/**
|
|
327
|
+
* Pi runtime provider config.
|
|
328
|
+
*
|
|
329
|
+
* `apiKey` is intentionally still a plaintext persisted field in the current
|
|
330
|
+
* runtime-config capability. This is a known gap, not a managed-secret or
|
|
331
|
+
* SecretRef contract.
|
|
332
|
+
*/
|
|
333
|
+
type PiRuntimeProviderConfig = {
|
|
334
|
+
kind: "default";
|
|
335
|
+
} | {
|
|
336
|
+
kind: "pi-builtin";
|
|
337
|
+
providerId: string;
|
|
338
|
+
apiKey: string;
|
|
339
|
+
};
|
|
340
|
+
/**
|
|
341
|
+
* Built-in / Quick Start provider config.
|
|
342
|
+
*
|
|
343
|
+
* `apiKey` is intentionally still a plaintext persisted field in the current
|
|
344
|
+
* runtime-config capability. This is a known gap, not a managed-secret,
|
|
345
|
+
* secret-store, or SecretRef contract.
|
|
346
|
+
*/
|
|
347
|
+
type BuiltInRuntimeProviderConfig = {
|
|
348
|
+
/** Server-managed credential reference; contains no provider secret. */
|
|
349
|
+
kind: "connection";
|
|
350
|
+
connectionId: string;
|
|
351
|
+
} | {
|
|
352
|
+
kind: "preset";
|
|
353
|
+
providerId: BuiltInRuntimeProviderId;
|
|
354
|
+
apiKey: string;
|
|
355
|
+
} | {
|
|
356
|
+
kind: "gateway";
|
|
357
|
+
providerId: BuiltInRuntimeGatewayProviderId;
|
|
358
|
+
baseUrl: string;
|
|
359
|
+
apiKey: string;
|
|
360
|
+
/**
|
|
361
|
+
* Operator-declared capability for a custom gateway model. Omission is
|
|
362
|
+
* migration-compatible and has the same conservative meaning as false.
|
|
363
|
+
*/
|
|
364
|
+
supportsImageInput?: boolean;
|
|
365
|
+
};
|
|
366
|
+
declare const BUILTIN_RUNTIME_PROVIDER_ENV_KEYS: {
|
|
367
|
+
readonly deepseek: "DEEPSEEK_API_KEY";
|
|
368
|
+
readonly minimax: "MINIMAX_API_KEY";
|
|
369
|
+
readonly "minimax-cn": "MINIMAX_CN_API_KEY";
|
|
370
|
+
readonly zai: "ZAI_API_KEY";
|
|
371
|
+
readonly "zai-coding-cn": "ZAI_CODING_CN_API_KEY";
|
|
372
|
+
readonly moonshotai: "MOONSHOT_API_KEY";
|
|
373
|
+
readonly "moonshotai-cn": "MOONSHOT_API_KEY";
|
|
374
|
+
readonly "kimi-coding": "KIMI_API_KEY";
|
|
375
|
+
readonly "qwen-token-plan": "QWEN_TOKEN_PLAN_API_KEY";
|
|
376
|
+
readonly "qwen-token-plan-cn": "QWEN_TOKEN_PLAN_CN_API_KEY";
|
|
377
|
+
readonly openrouter: "OPENROUTER_API_KEY";
|
|
378
|
+
readonly openai: "OPENAI_API_KEY";
|
|
379
|
+
readonly anthropic: "ANTHROPIC_API_KEY";
|
|
380
|
+
readonly google: "GEMINI_API_KEY";
|
|
381
|
+
readonly xai: "XAI_API_KEY";
|
|
382
|
+
readonly xiaomi: "XIAOMI_API_KEY";
|
|
383
|
+
};
|
|
384
|
+
type BuiltInRuntimeProviderId = keyof typeof BUILTIN_RUNTIME_PROVIDER_ENV_KEYS;
|
|
385
|
+
declare const BUILTIN_RUNTIME_GATEWAY_PROVIDERS: readonly [{
|
|
386
|
+
readonly id: "openai-compatible";
|
|
387
|
+
readonly envKey: "OPENAI_API_KEY";
|
|
388
|
+
readonly baseUrlEnvKey: "OPENAI_BASE_URL";
|
|
389
|
+
}, {
|
|
390
|
+
readonly id: "anthropic-compatible";
|
|
391
|
+
readonly envKey: "ANTHROPIC_API_KEY";
|
|
392
|
+
readonly baseUrlEnvKey: "ANTHROPIC_BASE_URL";
|
|
393
|
+
}];
|
|
394
|
+
type BuiltInRuntimeGatewayProviderId = typeof BUILTIN_RUNTIME_GATEWAY_PROVIDERS[number]["id"];
|
|
395
|
+
type RuntimeModelConfig = {
|
|
396
|
+
kind: "preset";
|
|
397
|
+
id: string;
|
|
398
|
+
} | {
|
|
399
|
+
kind: "custom";
|
|
400
|
+
name: string;
|
|
401
|
+
};
|
|
402
|
+
type RuntimeModeConfig = {
|
|
403
|
+
kind: "default";
|
|
404
|
+
} | {
|
|
405
|
+
kind: "fast";
|
|
406
|
+
};
|
|
407
|
+
interface RuntimeConfigBase {
|
|
408
|
+
version: typeof RUNTIME_CONFIG_VERSION;
|
|
409
|
+
model: RuntimeModelConfig;
|
|
410
|
+
mode: RuntimeModeConfig;
|
|
411
|
+
reasoningEffort?: RuntimeReasoningEffort | null;
|
|
412
|
+
envVars?: Record<string, string> | null;
|
|
413
|
+
}
|
|
414
|
+
type ClaudeRuntimeConfig = RuntimeConfigBase & {
|
|
415
|
+
runtime: "claude";
|
|
416
|
+
provider?: ClaudeRuntimeProviderConfig;
|
|
417
|
+
command?: string | null;
|
|
418
|
+
};
|
|
419
|
+
type PiRuntimeConfig = RuntimeConfigBase & {
|
|
420
|
+
runtime: "pi";
|
|
421
|
+
provider?: PiRuntimeProviderConfig;
|
|
422
|
+
command?: never;
|
|
423
|
+
};
|
|
424
|
+
type BuiltInRuntimeConfig = RuntimeConfigBase & {
|
|
425
|
+
runtime: "builtin";
|
|
426
|
+
provider: BuiltInRuntimeProviderConfig;
|
|
427
|
+
hostUserState: "forbidden";
|
|
428
|
+
/** Opt in to extensions installed in the host Pi agent directory. */
|
|
429
|
+
loadLocalPlugins?: boolean;
|
|
430
|
+
command?: never;
|
|
431
|
+
};
|
|
432
|
+
type ProviderlessRuntimeId = Exclude<RuntimeId, "builtin" | "claude" | "pi">;
|
|
433
|
+
type ProviderlessRuntimeConfig = RuntimeConfigBase & {
|
|
434
|
+
runtime: ProviderlessRuntimeId;
|
|
435
|
+
provider?: never;
|
|
436
|
+
command?: never;
|
|
437
|
+
};
|
|
438
|
+
type RuntimeConfig = BuiltInRuntimeConfig | ClaudeRuntimeConfig | PiRuntimeConfig | ProviderlessRuntimeConfig;
|
|
439
|
+
type ProfileVisibilityMembershipStatus = "active" | "left" | "removed";
|
|
440
|
+
interface ProfileCreatedAgentSummary {
|
|
441
|
+
id: string;
|
|
442
|
+
name: string;
|
|
443
|
+
displayName: string | null;
|
|
444
|
+
avatarUrl: string | null;
|
|
445
|
+
runtime: string;
|
|
446
|
+
external?: boolean;
|
|
447
|
+
status: AgentStatus;
|
|
448
|
+
}
|
|
449
|
+
type ProfileCreatorSummary = {
|
|
450
|
+
type: "human";
|
|
451
|
+
id: string;
|
|
452
|
+
name: string;
|
|
453
|
+
displayName: string | null;
|
|
454
|
+
avatarUrl: string | null;
|
|
455
|
+
gravatarHash: string;
|
|
456
|
+
} | {
|
|
457
|
+
type: "agent";
|
|
458
|
+
id: string;
|
|
459
|
+
name: string;
|
|
460
|
+
displayName: string | null;
|
|
461
|
+
avatarUrl: string | null;
|
|
462
|
+
deletedAt: string | null;
|
|
463
|
+
};
|
|
464
|
+
interface HumanProfileView {
|
|
465
|
+
kind: "human";
|
|
466
|
+
id: string;
|
|
467
|
+
isSelf: boolean;
|
|
468
|
+
name: string;
|
|
469
|
+
displayName: string | null;
|
|
470
|
+
description: string | null;
|
|
471
|
+
avatarUrl: string | null;
|
|
472
|
+
email: string | null;
|
|
473
|
+
role: "owner" | "admin" | "member" | "guest" | null;
|
|
474
|
+
joinedAt: string | null;
|
|
475
|
+
membershipStatus: ProfileVisibilityMembershipStatus;
|
|
476
|
+
createdAgents: ProfileCreatedAgentSummary[];
|
|
477
|
+
}
|
|
478
|
+
interface AgentProfileView {
|
|
479
|
+
kind: "agent";
|
|
480
|
+
id: string;
|
|
481
|
+
isSelf: boolean;
|
|
482
|
+
name: string;
|
|
483
|
+
displayName: string | null;
|
|
484
|
+
description: string | null;
|
|
485
|
+
avatarUrl: string | null;
|
|
486
|
+
status: AgentStatus;
|
|
487
|
+
serverRole: "owner" | "admin" | "member" | null;
|
|
488
|
+
runtime: string;
|
|
489
|
+
external?: boolean;
|
|
490
|
+
model: string;
|
|
491
|
+
runtimeConfig?: RuntimeConfig | null;
|
|
492
|
+
lastRuntimeError?: AgentRuntimeErrorState | null;
|
|
493
|
+
reasoningEffort: ReasoningEffort | null;
|
|
494
|
+
executionMode: "byoc" | "cloud" | string | null;
|
|
495
|
+
computerId: string | null;
|
|
496
|
+
computerName: string | null;
|
|
497
|
+
computerHostname: string | null;
|
|
498
|
+
daemonVersion: string | null;
|
|
499
|
+
creator: ProfileCreatorSummary | null;
|
|
500
|
+
createdAgents: ProfileCreatedAgentSummary[];
|
|
501
|
+
createdAt: string;
|
|
502
|
+
deletedAt: string | null;
|
|
503
|
+
}
|
|
504
|
+
type ProfileView = HumanProfileView | AgentProfileView;
|
|
505
|
+
type AgentStatus = "active" | "inactive" | "stopped";
|
|
506
|
+
interface AgentRuntimeErrorState {
|
|
507
|
+
message: string;
|
|
508
|
+
at: string;
|
|
509
|
+
launchId?: string | null;
|
|
510
|
+
actionRequired: boolean;
|
|
511
|
+
/** #688(c): typed diagnostic tuple durable with the crash state. Absent for
|
|
512
|
+
* untyped/legacy error authority (stays null), present only when a valid typed
|
|
513
|
+
* RuntimeErrorActivityDiagnostic carrier established the authority. */
|
|
514
|
+
errorClass?: RuntimeErrorClass;
|
|
515
|
+
errorReason?: RuntimeErrorReason;
|
|
516
|
+
fingerprint?: string;
|
|
517
|
+
reasonProvenance?: RuntimeErrorReasonProvenance;
|
|
518
|
+
}
|
|
519
|
+
type KnownReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
|
|
520
|
+
/**
|
|
521
|
+
* Persisted agent-row reasoning values remain the closed, database-backed
|
|
522
|
+
* vocabulary. Runtime-owned vocabularies live inside RuntimeConfig instead.
|
|
523
|
+
*/
|
|
524
|
+
type ReasoningEffort = KnownReasoningEffort;
|
|
525
|
+
type RuntimeReasoningEffort = ReasoningEffort | (string & {});
|
|
526
|
+
//#endregion
|
|
527
|
+
//#region ../shared/src/agentApiContract.d.ts
|
|
528
|
+
declare const agentApiProfileUpdateBodySchema: z.ZodObject<{
|
|
529
|
+
avatarUrl: z.ZodOptional<z.ZodString>;
|
|
530
|
+
displayName: z.ZodOptional<z.ZodString>;
|
|
531
|
+
description: z.ZodOptional<z.ZodString>;
|
|
532
|
+
}, z.core.$loose>;
|
|
533
|
+
declare const agentApiProfileViewSchema: z.ZodType<ProfileView>;
|
|
534
|
+
declare const agentApiActionPrepareBodySchema: z.ZodObject<{
|
|
535
|
+
target: z.ZodString;
|
|
536
|
+
action: z.ZodDiscriminatedUnion<[z.ZodObject<{
|
|
537
|
+
type: z.ZodLiteral<"channel:create">;
|
|
538
|
+
name: z.ZodString;
|
|
539
|
+
visibility: z.ZodDefault<z.ZodEnum<{
|
|
540
|
+
public: "public";
|
|
541
|
+
private: "private";
|
|
542
|
+
}>>;
|
|
543
|
+
description: z.ZodOptional<z.ZodString>;
|
|
544
|
+
initialHumans: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
545
|
+
initialAgents: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
546
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
547
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
548
|
+
type: z.ZodLiteral<"agent:create">;
|
|
549
|
+
name: z.ZodString;
|
|
550
|
+
description: z.ZodOptional<z.ZodString>;
|
|
551
|
+
suggestedComputer: z.ZodOptional<z.ZodString>;
|
|
552
|
+
requiredComputer: z.ZodOptional<z.ZodString>;
|
|
553
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
554
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
555
|
+
type: z.ZodLiteral<"channel:add_member">;
|
|
556
|
+
channel: z.ZodString;
|
|
557
|
+
humans: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
558
|
+
agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
559
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
560
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
561
|
+
type: z.ZodLiteral<"integration:approve_agent_login">;
|
|
562
|
+
requestId: z.ZodUUID;
|
|
563
|
+
agentId: z.ZodUUID;
|
|
564
|
+
agentName: z.ZodString;
|
|
565
|
+
clientId: z.ZodUUID;
|
|
566
|
+
clientKey: z.ZodString;
|
|
567
|
+
clientName: z.ZodString;
|
|
568
|
+
scopes: z.ZodArray<z.ZodString>;
|
|
569
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
570
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
571
|
+
type: z.ZodLiteral<"integration:install_marketplace_app">;
|
|
572
|
+
clientId: z.ZodUUID;
|
|
573
|
+
clientKey: z.ZodString;
|
|
574
|
+
clientName: z.ZodString;
|
|
575
|
+
clientNameSha256: z.ZodString;
|
|
576
|
+
agentId: z.ZodUUID;
|
|
577
|
+
agentName: z.ZodString;
|
|
578
|
+
scopes: z.ZodArray<z.ZodString>;
|
|
579
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
580
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
581
|
+
description: z.ZodOptional<z.ZodString>;
|
|
582
|
+
category: z.ZodOptional<z.ZodString>;
|
|
583
|
+
homepageUrl: z.ZodOptional<z.ZodString>;
|
|
584
|
+
agentManifestUrl: z.ZodOptional<z.ZodString>;
|
|
585
|
+
type: z.ZodLiteral<"integration:register_app">;
|
|
586
|
+
name: z.ZodString;
|
|
587
|
+
clientKey: z.ZodOptional<z.ZodString>;
|
|
588
|
+
returnUrl: z.ZodString;
|
|
589
|
+
scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
590
|
+
unsafeDemoUrlOverride: z.ZodOptional<z.ZodBoolean>;
|
|
591
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
592
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
593
|
+
name: z.ZodOptional<z.ZodString>;
|
|
594
|
+
description: z.ZodOptional<z.ZodString>;
|
|
595
|
+
category: z.ZodOptional<z.ZodString>;
|
|
596
|
+
homepageUrl: z.ZodOptional<z.ZodString>;
|
|
597
|
+
returnUrl: z.ZodOptional<z.ZodString>;
|
|
598
|
+
agentManifestUrl: z.ZodOptional<z.ZodString>;
|
|
599
|
+
type: z.ZodLiteral<"integration:update_app_registration">;
|
|
600
|
+
clientKey: z.ZodString;
|
|
601
|
+
scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
602
|
+
unsafeDemoUrlOverride: z.ZodOptional<z.ZodBoolean>;
|
|
603
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
604
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
605
|
+
type: z.ZodLiteral<"integration:recover_app_owner">;
|
|
606
|
+
clientKey: z.ZodString;
|
|
607
|
+
targetAgent: z.ZodString;
|
|
608
|
+
draftHint: z.ZodOptional<z.ZodString>;
|
|
609
|
+
}, z.core.$strip>], "type">;
|
|
610
|
+
}, z.core.$loose>;
|
|
611
|
+
declare const agentApiServerUpdateBodySchema: z.ZodObject<{
|
|
612
|
+
name: z.ZodOptional<z.ZodString>;
|
|
613
|
+
hideHumansFromMembers: z.ZodOptional<z.ZodBoolean>;
|
|
614
|
+
}, z.core.$loose>;
|
|
615
|
+
declare const agentApiServerUpdateResponseSchema: z.ZodObject<{
|
|
616
|
+
id: z.ZodString;
|
|
617
|
+
name: z.ZodString;
|
|
618
|
+
hideHumansFromMembers: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
619
|
+
avatarUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
620
|
+
}, z.core.$loose>;
|
|
621
|
+
declare const agentApiActionPrepareResponseSchema: z.ZodObject<{
|
|
622
|
+
messageId: z.ZodString;
|
|
623
|
+
metadata: z.ZodObject<{
|
|
624
|
+
kind: z.ZodLiteral<"action-card">;
|
|
625
|
+
}, z.core.$loose>;
|
|
626
|
+
}, z.core.$loose>;
|
|
627
|
+
declare const agentApiAppConfigPatchBodySchema: z.ZodObject<{
|
|
628
|
+
expectedRevision: z.ZodNumber;
|
|
629
|
+
set: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
630
|
+
unset: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
631
|
+
}, z.core.$strict>;
|
|
632
|
+
declare const agentApiAppConfigResponseSchema: z.ZodObject<{
|
|
633
|
+
appId: z.ZodString;
|
|
634
|
+
revision: z.ZodNumber;
|
|
635
|
+
schema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
|
|
636
|
+
type: z.ZodLiteral<"boolean">;
|
|
637
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
638
|
+
type: z.ZodLiteral<"integer">;
|
|
639
|
+
minimum: z.ZodNumber;
|
|
640
|
+
maximum: z.ZodNumber;
|
|
641
|
+
}, z.core.$strict>]>>;
|
|
642
|
+
defaults: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
|
|
643
|
+
overrides: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
|
|
644
|
+
effective: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>>;
|
|
645
|
+
}, z.core.$loose>;
|
|
646
|
+
type AgentApiAppConfigResponse = z.infer<typeof agentApiAppConfigResponseSchema>;
|
|
647
|
+
type AgentApiProfileUpdateBody = z.infer<typeof agentApiProfileUpdateBodySchema>;
|
|
648
|
+
type AgentApiProfileView = z.infer<typeof agentApiProfileViewSchema>;
|
|
649
|
+
type AgentApiActionPrepareResponse = z.infer<typeof agentApiActionPrepareResponseSchema>;
|
|
650
|
+
type AgentApiServerUpdateBody = z.infer<typeof agentApiServerUpdateBodySchema>;
|
|
651
|
+
type AgentApiServerUpdateResponse = z.infer<typeof agentApiServerUpdateResponseSchema>;
|
|
652
|
+
//#endregion
|
|
653
|
+
//#region src/events.d.ts
|
|
654
|
+
interface RaftEventsReceiveRequest {
|
|
655
|
+
/** Numeric lower bound (exclusive). "latest" applies no numeric filter; it does not skip queued messages. */
|
|
656
|
+
since?: number | "latest";
|
|
657
|
+
/** Integer 1..200. Server default: 50. */
|
|
658
|
+
limit?: number;
|
|
659
|
+
}
|
|
660
|
+
interface RaftEventAttachment {
|
|
661
|
+
id: string;
|
|
662
|
+
filename: string;
|
|
663
|
+
mimeType?: string;
|
|
664
|
+
sizeBytes?: number;
|
|
665
|
+
}
|
|
666
|
+
/** External provenance is attribution, never Raft membership or user authority. */
|
|
667
|
+
interface RaftEventExternalMessage {
|
|
668
|
+
schema: "external-message-provenance.v1";
|
|
669
|
+
provider: string;
|
|
670
|
+
workspace_id: string;
|
|
671
|
+
conversation_id: string;
|
|
672
|
+
message_id: string;
|
|
673
|
+
actor_id: string;
|
|
674
|
+
actor_kind: "human" | "guest" | "remote" | "bot" | "unknown";
|
|
675
|
+
projection_id: string;
|
|
676
|
+
}
|
|
677
|
+
/** A projection of an inbox message, not a general lifecycle event. Missing legacy metadata stays absent. */
|
|
678
|
+
interface RaftEvent {
|
|
679
|
+
type: "message";
|
|
680
|
+
messageId?: string;
|
|
681
|
+
seq?: number;
|
|
682
|
+
content?: string;
|
|
683
|
+
timestamp?: string;
|
|
684
|
+
senderType: "human" | "agent" | "system" | "third_party_app" | "unknown";
|
|
685
|
+
senderName?: string;
|
|
686
|
+
channelId?: string;
|
|
687
|
+
channelName?: string;
|
|
688
|
+
channelType?: string;
|
|
689
|
+
parentChannelName?: string;
|
|
690
|
+
parentChannelType?: string;
|
|
691
|
+
attachments: RaftEventAttachment[];
|
|
692
|
+
externalMessage?: RaftEventExternalMessage;
|
|
693
|
+
}
|
|
694
|
+
interface RaftEventsReceiveData {
|
|
695
|
+
events: RaftEvent[];
|
|
696
|
+
lastSeenSeq: number | null;
|
|
697
|
+
lastSeenMessageId: string | null;
|
|
698
|
+
hasMore: boolean;
|
|
699
|
+
/** Server-provided batch hint; not a per-message thread target or proof of permission to reply. */
|
|
700
|
+
replyTarget: string | null;
|
|
701
|
+
}
|
|
702
|
+
interface RaftEventsReceiveError {
|
|
703
|
+
code: "INVALID_REQUEST" | "TRANSPORT_ERROR" | "HTTP_ERROR" | "INVALID_RESPONSE";
|
|
704
|
+
/** Safe SDK text; raw transport errors and response bodies are never included. */
|
|
705
|
+
message: string;
|
|
706
|
+
}
|
|
707
|
+
type RaftEventsReceiveResult = {
|
|
708
|
+
ok: true;
|
|
709
|
+
status: number;
|
|
710
|
+
data: RaftEventsReceiveData;
|
|
711
|
+
} | {
|
|
712
|
+
ok: false;
|
|
713
|
+
status?: number;
|
|
714
|
+
error: RaftEventsReceiveError;
|
|
715
|
+
};
|
|
716
|
+
//#endregion
|
|
717
|
+
//#region src/context.d.ts
|
|
718
|
+
/** The bound External Agent. */
|
|
719
|
+
interface RaftContextAgent {
|
|
720
|
+
id: string;
|
|
721
|
+
name: string;
|
|
722
|
+
displayName: string | null;
|
|
723
|
+
description: string | null;
|
|
724
|
+
runtime: string;
|
|
725
|
+
external: boolean;
|
|
726
|
+
}
|
|
727
|
+
/** The single Server the credential is bound to. */
|
|
728
|
+
interface RaftContextServer {
|
|
729
|
+
id: string;
|
|
730
|
+
slug: string;
|
|
731
|
+
name: string;
|
|
732
|
+
}
|
|
733
|
+
interface RaftContextData {
|
|
734
|
+
agent: RaftContextAgent;
|
|
735
|
+
server: RaftContextServer;
|
|
736
|
+
/** Capabilities granted to this credential, for example `send` or `read`. */
|
|
737
|
+
capabilities: string[];
|
|
738
|
+
/** The rendered operating guide for External Agents; null for daemon-managed agents. */
|
|
739
|
+
guide: string | null;
|
|
740
|
+
}
|
|
741
|
+
interface RaftContextError {
|
|
742
|
+
code: "TRANSPORT_ERROR" | "HTTP_ERROR" | "INVALID_RESPONSE";
|
|
743
|
+
/** Safe SDK text; raw transport errors and response bodies are never included. */
|
|
744
|
+
message: string;
|
|
745
|
+
}
|
|
746
|
+
type RaftContextResult = {
|
|
747
|
+
ok: true;
|
|
748
|
+
status: number;
|
|
749
|
+
data: RaftContextData;
|
|
750
|
+
} | {
|
|
751
|
+
ok: false;
|
|
752
|
+
status?: number;
|
|
753
|
+
error: RaftContextError;
|
|
754
|
+
};
|
|
755
|
+
//#endregion
|
|
756
|
+
//#region src/manage.d.ts
|
|
757
|
+
type RaftProfile = AgentApiProfileView;
|
|
758
|
+
type RaftProfileUpdate = AgentApiProfileUpdateBody;
|
|
759
|
+
type RaftServerUpdate = AgentApiServerUpdateBody;
|
|
760
|
+
type RaftServerProfile = AgentApiServerUpdateResponse;
|
|
761
|
+
type RaftActionPrepareRequest = z.input<typeof agentApiActionPrepareBodySchema>;
|
|
762
|
+
type RaftActionPrepared = AgentApiActionPrepareResponse;
|
|
763
|
+
type RaftAppConfig = AgentApiAppConfigResponse;
|
|
764
|
+
type RaftAppConfigPatch = z.input<typeof agentApiAppConfigPatchBodySchema>;
|
|
765
|
+
interface RaftApiError {
|
|
766
|
+
code: "INVALID_REQUEST" | "TRANSPORT_ERROR" | "HTTP_ERROR" | "INVALID_RESPONSE";
|
|
767
|
+
/** Safe SDK text; raw transport errors and response bodies are never included. */
|
|
768
|
+
message: string;
|
|
769
|
+
/** The Server's stable machine code for an HTTP rejection, when it sends one. */
|
|
770
|
+
errorCode?: string;
|
|
771
|
+
}
|
|
772
|
+
type RaftApiResult<T> = {
|
|
773
|
+
ok: true;
|
|
774
|
+
status: number;
|
|
775
|
+
data: T;
|
|
776
|
+
} | {
|
|
777
|
+
ok: false;
|
|
778
|
+
status?: number;
|
|
779
|
+
error: RaftApiError;
|
|
780
|
+
};
|
|
781
|
+
interface RaftAvatarUpload {
|
|
782
|
+
/** Image bytes: JPEG, PNG, GIF, or WebP, at most 5 MB. */
|
|
783
|
+
data: Blob | Uint8Array;
|
|
784
|
+
filename: string;
|
|
785
|
+
mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
|
|
786
|
+
}
|
|
787
|
+
interface RaftManageClient {
|
|
788
|
+
profile: {
|
|
789
|
+
/** Show your own profile, or another visible profile with `{ target: "@name" }`. Needs `read`. */
|
|
790
|
+
show(request?: {
|
|
791
|
+
target?: string;
|
|
792
|
+
}): Promise<RaftApiResult<RaftProfile>>;
|
|
793
|
+
/** Update your display name, description, or avatar URL. Needs `send`. */
|
|
794
|
+
update(request: RaftProfileUpdate): Promise<RaftApiResult<RaftProfile>>;
|
|
795
|
+
/** Upload an avatar image. Needs `send`. */
|
|
796
|
+
updateAvatar(upload: RaftAvatarUpload): Promise<RaftApiResult<RaftProfile>>;
|
|
797
|
+
};
|
|
798
|
+
server: {
|
|
799
|
+
/** Rename the Server or change member visibility. Needs `server` and owner/admin role. */
|
|
800
|
+
update(request: RaftServerUpdate): Promise<RaftApiResult<RaftServerProfile>>;
|
|
801
|
+
};
|
|
802
|
+
actions: {
|
|
803
|
+
/** Post an action card that a human confirms. Needs `tasks`. */
|
|
804
|
+
prepare(request: RaftActionPrepareRequest): Promise<RaftApiResult<RaftActionPrepared>>;
|
|
805
|
+
};
|
|
806
|
+
apps: {
|
|
807
|
+
/** Read a built-in app's configuration for this agent. Needs `read`. */
|
|
808
|
+
getConfig(appId: string): Promise<RaftApiResult<RaftAppConfig>>;
|
|
809
|
+
/** Atomically change a built-in app's configuration. Needs `tasks`. */
|
|
810
|
+
patchConfig(appId: string, patch: RaftAppConfigPatch): Promise<RaftApiResult<RaftAppConfig>>;
|
|
811
|
+
};
|
|
812
|
+
}
|
|
813
|
+
//#endregion
|
|
814
|
+
//#region src/client.d.ts
|
|
815
|
+
type RaftClient = AgentApiMessageClient & RaftManageClient & {
|
|
816
|
+
events: {
|
|
817
|
+
/** Nonblocking inbox pull. Returned messages are acknowledged before the response; never automatically retried. */
|
|
818
|
+
receive(request?: RaftEventsReceiveRequest): Promise<RaftEventsReceiveResult>;
|
|
819
|
+
};
|
|
820
|
+
channels: {
|
|
821
|
+
join(request: RaftChannelJoinRequest): Promise<RaftChannelJoinResult>;
|
|
822
|
+
};
|
|
823
|
+
agent: {
|
|
824
|
+
/** Read the bound agent, its Server (id, slug, name), and credential capabilities. */
|
|
825
|
+
context(): Promise<RaftContextResult>;
|
|
826
|
+
};
|
|
827
|
+
};
|
|
828
|
+
type RaftClientError = AgentApiMessageClientError;
|
|
829
|
+
type RaftClientFailure = AgentApiMessageClientFailure;
|
|
830
|
+
type RaftClientResult = AgentApiMessageClientResult;
|
|
831
|
+
type RaftClientSuccess = AgentApiMessageClientSuccess;
|
|
832
|
+
type RaftSdkConfigurationErrorCode = "MISSING_SERVER_URL" | "INVALID_SERVER_URL" | "MISSING_AGENT_CREDENTIAL" | "INVALID_AGENT_CREDENTIAL" | "INVALID_CREDENTIAL_PATH";
|
|
833
|
+
export declare class RaftSdkConfigurationError extends Error {
|
|
834
|
+
readonly code: RaftSdkConfigurationErrorCode;
|
|
835
|
+
readonly name = "RaftSdkConfigurationError";
|
|
836
|
+
constructor(code: RaftSdkConfigurationErrorCode, message: string);
|
|
837
|
+
}
|
|
838
|
+
interface CreateRaftClientOptions {
|
|
839
|
+
/** Raft Server origin, for example `https://api.raft.build`. */
|
|
840
|
+
serverUrl: string;
|
|
841
|
+
/** Credential bound to exactly one External Agent (`sk_agent_*`). */
|
|
842
|
+
credential: string;
|
|
843
|
+
/** Optional fetch implementation for runtimes, tests, or network policy wrappers. */
|
|
844
|
+
fetch?: typeof fetch;
|
|
845
|
+
/** Static request headers. `authorization` is always overwritten by `credential`. */
|
|
846
|
+
headers?: Record<string, string>;
|
|
847
|
+
/** Bounded transport retries. Defaults to one attempt and is capped at five. events.receive always uses one attempt. */
|
|
848
|
+
retry?: AgentApiMessageClientOptions["retry"];
|
|
849
|
+
/** Optional caller-owned throttle hook, invoked once per logical request. */
|
|
850
|
+
throttle?: RaftClientThrottleOptions;
|
|
851
|
+
}
|
|
852
|
+
interface RaftClientTransportRequest {
|
|
853
|
+
method: string;
|
|
854
|
+
path: string;
|
|
855
|
+
body?: unknown;
|
|
856
|
+
}
|
|
857
|
+
interface RaftClientThrottleOptions {
|
|
858
|
+
beforeRequest?: (request: RaftClientTransportRequest) => Promise<void> | void;
|
|
859
|
+
}
|
|
860
|
+
/**
|
|
861
|
+
* Create a typed client for the credential-derived `/internal/agent-api/*`
|
|
862
|
+
* surface. The SDK does not read CLI profiles, environment variables, or the
|
|
863
|
+
* host user's home directory: the caller chooses and supplies the credential.
|
|
864
|
+
*/
|
|
865
|
+
export declare function createRaftClient(options: CreateRaftClientOptions): RaftClient;
|
|
866
|
+
//#endregion
|
|
867
|
+
//#region src/credential.d.ts
|
|
868
|
+
interface RaftCredentialIdentity {
|
|
869
|
+
serverUrl: string;
|
|
870
|
+
agentId: string;
|
|
871
|
+
agentName: string;
|
|
872
|
+
agentDisplayName: string | null;
|
|
873
|
+
serverId: string;
|
|
874
|
+
credentialId: string;
|
|
875
|
+
scopes: string[];
|
|
876
|
+
}
|
|
877
|
+
interface StoredRaftCredential extends RaftCredentialIdentity {
|
|
878
|
+
schemaVersion: 1;
|
|
879
|
+
credential: string;
|
|
880
|
+
storedAt: string;
|
|
881
|
+
}
|
|
882
|
+
interface RaftCredentialStore {
|
|
883
|
+
load(): Promise<StoredRaftCredential | null>;
|
|
884
|
+
/**
|
|
885
|
+
* Persist the first credential. Implementations must reject replacement by
|
|
886
|
+
* a different credential; saving the identical credential may be a no-op.
|
|
887
|
+
*/
|
|
888
|
+
save(record: StoredRaftCredential): Promise<void>;
|
|
889
|
+
}
|
|
890
|
+
type RaftCredentialErrorCode = "CREDENTIAL_REJECTED" | "CREDENTIAL_VERIFY_FAILED" | "CREDENTIAL_RESPONSE_INVALID" | "CREDENTIAL_SCOPE_MISSING" | "CREDENTIAL_STORE_READ_FAILED" | "CREDENTIAL_STORE_WRITE_FAILED" | "CREDENTIAL_STORE_CONFLICT" | "CREDENTIAL_NOT_FOUND";
|
|
891
|
+
export declare class RaftCredentialError extends Error {
|
|
892
|
+
readonly code: RaftCredentialErrorCode;
|
|
893
|
+
readonly name = "RaftCredentialError";
|
|
894
|
+
constructor(code: RaftCredentialErrorCode, message: string);
|
|
895
|
+
}
|
|
896
|
+
interface BootstrapRaftCredentialOptions {
|
|
897
|
+
/** Raft Server origin whose Agent API will validate the credential. */
|
|
898
|
+
serverUrl: string;
|
|
899
|
+
/** Existing long-lived External Agent credential (`sk_agent_*`). */
|
|
900
|
+
credential: string;
|
|
901
|
+
/** Caller-selected durable store. */
|
|
902
|
+
store: RaftCredentialStore;
|
|
903
|
+
/** Optional fetch implementation for runtimes, tests, or network policy wrappers. */
|
|
904
|
+
fetch?: typeof fetch;
|
|
905
|
+
}
|
|
906
|
+
interface CreateRaftClientFromStoreOptions {
|
|
907
|
+
store: RaftCredentialStore;
|
|
908
|
+
fetch?: CreateRaftClientOptions["fetch"];
|
|
909
|
+
headers?: CreateRaftClientOptions["headers"];
|
|
910
|
+
retry?: CreateRaftClientOptions["retry"];
|
|
911
|
+
throttle?: CreateRaftClientOptions["throttle"];
|
|
912
|
+
}
|
|
913
|
+
/**
|
|
914
|
+
* Validate an existing External Agent credential against Raft, derive its
|
|
915
|
+
* bound identity from the credential-authenticated `whoami` surface, and save
|
|
916
|
+
* it through the caller's explicit store. This does not mint or rotate a
|
|
917
|
+
* credential and never returns the credential bytes.
|
|
918
|
+
*/
|
|
919
|
+
export declare function bootstrapRaftCredential(options: BootstrapRaftCredentialOptions): Promise<RaftCredentialIdentity>;
|
|
920
|
+
/** Load the caller-selected credential store and create a normal Raft client. */
|
|
921
|
+
export declare function createRaftClientFromStore(options: CreateRaftClientFromStoreOptions): Promise<RaftClient>;
|
|
922
|
+
//#endregion
|
|
923
|
+
//#region src/fileCredentialStore.d.ts
|
|
924
|
+
/**
|
|
925
|
+
* Create a Node.js credential store at one explicit absolute path. The SDK
|
|
926
|
+
* never discovers CLI profiles or a home directory. Writes use a same-directory
|
|
927
|
+
* temporary file followed by atomic rename, and the final file is mode 0600.
|
|
928
|
+
*/
|
|
929
|
+
export declare function createFileCredentialStore(filePath: string): RaftCredentialStore;
|
|
930
|
+
//#endregion
|
|
931
|
+
export type { BootstrapRaftCredentialOptions, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftManageClient, RaftProfile, RaftProfileUpdate, RaftSdkConfigurationErrorCode, RaftServerProfile, RaftServerUpdate, StoredRaftCredential };
|