@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/dist/index.d.ts CHANGED
@@ -1,291 +1,931 @@
1
- declare interface AgentApiAttachmentEnvelope {
2
- id: string;
3
- filename: string;
4
- [key: string]: unknown;
5
- }
6
-
7
- declare interface AgentApiHeldFreshnessResponse {
8
- ok?: true;
9
- state: "held";
10
- outcome?: "held";
11
- subtype?: "freshness";
12
- reason?: string;
13
- decision?: "local_hold" | "syncing_hold";
14
- producerFactId?: string;
15
- available_actions?: string[];
16
- heldMessages?: AgentApiMessageEnvelope[];
17
- recentUnread?: AgentApiMessageEnvelope[];
18
- newMessageCount?: number;
19
- shownMessageCount?: number;
20
- omittedMessageCount?: number;
21
- mentionAnnotation?: { formalMentionCount: number; [key: string]: unknown };
22
- continueAnywaySuggested?: boolean;
23
- freshnessContextMode?: "inline" | "withheld";
24
- withheldMessageCount?: number;
25
- seenUpToSeq?: number;
26
- seenUpToMessageId?: string | null;
27
- [key: string]: unknown;
28
- }
29
-
30
- declare type AgentApiMessageAuthHeaders = Record<string, string>;
31
-
32
- declare type AgentApiMessageAuthStrategy =
33
- | AgentApiMessageAuthHeaders
34
- | ((request: AgentApiMessageTransportRequest) => AgentApiMessageAuthHeaders | Promise<AgentApiMessageAuthHeaders>);
35
-
36
- declare interface AgentApiMessageClient {
37
- messages: {
38
- send(body: AgentApiSendBody): Promise<AgentApiMessageClientResult>;
39
- };
40
- }
41
-
42
- declare type AgentApiMessageClientError =
43
- | {
44
- kind: "transport";
45
- reason: "transport_error";
46
- message: string;
47
- cause?: unknown;
48
- }
49
- | {
50
- kind: "http";
51
- reason: "http_error";
52
- message: string;
53
- status: number;
54
- errorCode?: string | null;
55
- suggestedNextAction?: string | null;
56
- proxy?: unknown;
57
- response?: unknown;
58
- }
59
- | {
60
- kind: "validation";
61
- reason: Exclude<AgentApiMessageClientErrorReason, "transport_error" | "http_error">;
62
- message: string;
63
- status?: number;
64
- cause?: unknown;
65
- response?: unknown;
66
- };
67
-
68
- declare type AgentApiMessageClientErrorReason =
69
- | "request_contract_mismatch"
70
- | "transport_error"
71
- | "http_error"
72
- | "empty_response"
73
- | "response_contract_mismatch";
74
-
75
- declare interface AgentApiMessageClientFailure {
76
- ok: false;
77
- status?: number;
78
- error: AgentApiMessageClientError;
79
- }
80
-
81
- declare interface AgentApiMessageClientOptions {
82
- baseUrl: string;
83
- headers?: AgentApiMessageAuthHeaders;
84
- auth?: AgentApiMessageAuthStrategy;
85
- fetch?: typeof fetch;
86
- retry?: {
87
- attempts?: number;
88
- };
89
- throttle?: {
90
- beforeRequest?: (request: AgentApiMessageTransportRequest) => Promise<void> | void;
91
- };
92
- }
93
-
94
- declare type AgentApiMessageClientResult = AgentApiMessageClientSuccess | AgentApiMessageClientFailure;
95
-
96
- declare interface AgentApiMessageClientSuccess {
97
- ok: true;
98
- status: number;
99
- data: AgentApiSendResponse;
100
- }
101
-
102
- declare interface AgentApiMessageEnvelope {
103
- seq?: number;
104
- id?: string;
105
- message_id?: string;
106
- timestamp?: string;
107
- createdAt?: string;
108
- senderType?: string;
109
- sender_type?: string;
110
- senderName?: string;
111
- sender_name?: string;
112
- senderDescription?: string | null;
113
- sender_description?: string | null;
114
- channel_type?: string;
115
- channel_name?: string;
116
- parent_channel_type?: string;
117
- parent_channel_name?: string;
118
- content?: string;
119
- attachments?: AgentApiAttachmentEnvelope[];
120
- taskStatus?: string | null;
121
- task_status?: string | null;
122
- taskNumber?: number | null;
123
- task_number?: number | null;
124
- taskAssigneeId?: string | null;
125
- task_assignee_id?: string | null;
126
- taskAssigneeType?: string | null;
127
- task_assignee_type?: string | null;
128
- taskAssigneeName?: string | null;
129
- task_assignee_name?: string | null;
130
- threadId?: string | null;
131
- replyCount?: number | null;
132
- [key: string]: unknown;
133
- }
134
-
135
- declare interface AgentApiMessageTransportRequest {
136
- method: "POST";
137
- path: string;
138
- body: AgentApiSendBody;
139
- }
140
-
141
- declare interface AgentApiSendBody extends AgentApiSendBodyKnownFields {
142
- [key: string]: unknown;
143
- }
144
-
145
- declare interface AgentApiSendBodyKnownFields {
146
- target?: string;
147
- content?: string;
148
- attachmentIds?: string[];
149
- idempotencyKey?: string;
150
- continue?: boolean;
151
- sendDraft?: boolean;
152
- continueAnyway?: boolean;
153
- draftReholdCount?: number;
154
- draftReplacedExisting?: boolean;
155
- seenUpToSeq?: number;
156
- freshnessContextMode?: "inline" | "withheld";
157
- }
158
-
159
- declare type AgentApiSendResponse = AgentApiSendSentResponse | AgentApiHeldFreshnessResponse;
160
-
161
- declare interface AgentApiSendSentResponse {
162
- ok: true;
163
- state: "sent";
164
- messageId: string;
165
- messageSeq?: number;
166
- recentUnread?: AgentApiMessageEnvelope[];
167
- pendingMentionActions?: AgentApiMessageEnvelope[];
168
- unresolvedMentionHandles?: string[];
169
- attention?: {
170
- driveByJoinedToPost?: {
171
- reason?: string;
172
- muteCommand?: string;
173
- stillArrives?: string[];
174
- [key: string]: unknown;
175
- };
176
- [key: string]: unknown;
177
- };
178
- [key: string]: unknown;
179
- }
180
-
181
- /**
182
- * Validate an existing External Agent credential against Raft, derive its
183
- * bound identity from the credential-authenticated `whoami` surface, and save
184
- * it through the caller's explicit store. This does not mint or rotate a
185
- * credential and never returns the credential bytes.
186
- */
187
- export declare function bootstrapRaftCredential(options: BootstrapRaftCredentialOptions): Promise<RaftCredentialIdentity>;
188
-
189
- export declare interface BootstrapRaftCredentialOptions {
190
- /** Raft Server origin whose Agent API will validate the credential. */
191
- serverUrl: string;
192
- /** Existing long-lived External Agent credential (`sk_agent_*`). */
193
- credential: string;
194
- /** Caller-selected durable store. */
195
- store: RaftCredentialStore;
196
- /** Optional fetch implementation for runtimes, tests, or network policy wrappers. */
197
- fetch?: typeof fetch;
198
- }
199
-
200
- /**
201
- * Create a Node.js credential store at one explicit absolute path. The SDK
202
- * never discovers CLI profiles or a home directory. Writes use a same-directory
203
- * temporary file followed by atomic rename, and the final file is mode 0600.
204
- */
205
- export declare function createFileCredentialStore(filePath: string): RaftCredentialStore;
206
-
207
- /**
208
- * Create a typed client for the credential-derived `/internal/agent-api/*`
209
- * surface. The SDK does not read CLI profiles, environment variables, or the
210
- * host user's home directory: the caller chooses and supplies the credential.
211
- */
212
- export declare function createRaftClient(options: CreateRaftClientOptions): RaftClient;
213
-
214
- /** Load the caller-selected credential store and create a normal Raft client. */
215
- export declare function createRaftClientFromStore(options: CreateRaftClientFromStoreOptions): Promise<RaftClient>;
216
-
217
- export declare interface CreateRaftClientFromStoreOptions {
218
- store: RaftCredentialStore;
219
- fetch?: CreateRaftClientOptions["fetch"];
220
- headers?: CreateRaftClientOptions["headers"];
221
- retry?: CreateRaftClientOptions["retry"];
222
- throttle?: CreateRaftClientOptions["throttle"];
223
- }
224
-
225
- export declare interface CreateRaftClientOptions {
226
- /** Raft Server origin, for example `https://api.raft.build`. */
227
- serverUrl: string;
228
- /** Credential bound to exactly one External Agent (`sk_agent_*`). */
229
- credential: string;
230
- /** Optional fetch implementation for runtimes, tests, or network policy wrappers. */
231
- fetch?: typeof fetch;
232
- /** Static request headers. `authorization` is always overwritten by `credential`. */
233
- headers?: Record<string, string>;
234
- /** Bounded transport retries. Defaults to one attempt and is capped at five. */
235
- retry?: AgentApiMessageClientOptions["retry"];
236
- /** Optional caller-owned throttle hook, invoked once per logical request. */
237
- throttle?: AgentApiMessageClientOptions["throttle"];
238
- }
239
-
240
- export declare type RaftClient = AgentApiMessageClient;
241
-
242
- export declare type RaftClientError = AgentApiMessageClientError;
243
-
244
- export declare type RaftClientFailure = AgentApiMessageClientFailure;
245
-
246
- export declare type RaftClientResult = AgentApiMessageClientResult;
247
-
248
- export declare type RaftClientSuccess = AgentApiMessageClientSuccess;
249
-
250
- export declare class RaftCredentialError extends Error {
251
- readonly code: RaftCredentialErrorCode;
252
- readonly name = "RaftCredentialError";
253
- constructor(code: RaftCredentialErrorCode, message: string);
254
- }
255
-
256
- export declare 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";
257
-
258
- export declare interface RaftCredentialIdentity {
259
- serverUrl: string;
260
- agentId: string;
261
- agentName: string;
262
- agentDisplayName: string | null;
263
- serverId: string;
264
- credentialId: string;
265
- scopes: string[];
266
- }
267
-
268
- export declare interface RaftCredentialStore {
269
- load(): Promise<StoredRaftCredential | null>;
270
- /**
271
- * Persist the first credential. Implementations must reject replacement by
272
- * a different credential; saving the identical credential may be a no-op.
273
- */
274
- save(record: StoredRaftCredential): Promise<void>;
275
- }
276
-
277
- export declare class RaftSdkConfigurationError extends Error {
278
- readonly code: RaftSdkConfigurationErrorCode;
279
- readonly name = "RaftSdkConfigurationError";
280
- constructor(code: RaftSdkConfigurationErrorCode, message: string);
281
- }
282
-
283
- export declare type RaftSdkConfigurationErrorCode = "MISSING_SERVER_URL" | "INVALID_SERVER_URL" | "MISSING_AGENT_CREDENTIAL" | "INVALID_AGENT_CREDENTIAL" | "INVALID_CREDENTIAL_PATH";
284
-
285
- export declare interface StoredRaftCredential extends RaftCredentialIdentity {
286
- schemaVersion: 1;
287
- credential: string;
288
- storedAt: string;
289
- }
290
-
291
- export { }
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 };