@workerdeck/client 0.22.0 → 1.0.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/build/index.d.mts +40 -323
- package/build/index.mjs +109 -333
- package/build/index.mjs.map +1 -1
- package/package.json +4 -4
package/build/index.d.mts
CHANGED
|
@@ -1,202 +1,54 @@
|
|
|
1
1
|
import { AttachedFrame, CreateJobRequest, CreateProfileRequest, CreateSessionRequest, FindHostFilesResponse, GetProfileResponse, JobEvent, JobInfo, ListHostDirResponse, ListHostRootsResponse, ListProfilesResponse, McpServerActionRequest, McpServerStatusInfo, MessageAttachment, PermissionMode, ProfileInfo, QueueStats, ReadHostFileResponse, ResolvePermissionRequest, SdkSessionSummary, SessionEvent, SessionFileInfo, SessionInfo, SubmitExecutionResultRequest, SubmitExecutionResultResponse, ToolCallRequestFrame, ToolExecutionOutput, ToolResultBlock, UpdateProfileRequest, UpdateSessionRequest, WriteHostFileRequest, WriteHostFileResponse } from "@workerdeck/protocol";
|
|
2
2
|
|
|
3
|
-
//#region src/
|
|
4
|
-
|
|
5
|
-
* Pure URL logic for gateway hosts — what an operator types, turned into the
|
|
6
|
-
* `baseUrl` a `WorkerDeckClient` takes.
|
|
7
|
-
*
|
|
8
|
-
* Here rather than in each client because there were already two copies (the iOS
|
|
9
|
-
* `Host.apiURL` and the VS Code extension's port) and a third was coming. Every
|
|
10
|
-
* host that lets someone type a gateway address has to normalize it the same
|
|
11
|
-
* way, or the same gateway saved on two devices is two gateways.
|
|
12
|
-
*/
|
|
13
|
-
type HostUrl = {
|
|
14
|
-
baseUrl: string;
|
|
15
|
-
};
|
|
16
|
-
/** Normalized REST base for `WorkerDeckClient`, or undefined if unparseable. */
|
|
17
|
-
declare function apiUrl(host: HostUrl): string | undefined;
|
|
18
|
-
/**
|
|
19
|
-
* Whether this gateway is the machine the caller runs on. Decided from the URL,
|
|
20
|
-
* never by probing paths for existence — two checkouts of the same repo would
|
|
21
|
-
* lie. In a remote development window the caller runs on the remote box, so
|
|
22
|
-
* "loopback" correctly means *that* machine and its paths are real files there.
|
|
23
|
-
*/
|
|
24
|
-
declare function isLoopbackHost(host: HostUrl): boolean;
|
|
25
|
-
//#endregion
|
|
26
|
-
//#region src/host-auth.d.ts
|
|
27
|
-
/**
|
|
28
|
-
* The `ClientOptions` a **browser** needs to reach a gateway that is not its own
|
|
29
|
-
* origin.
|
|
30
|
-
*
|
|
31
|
-
* Here, beside `apiUrl`, for the same reason that is here: every host that lets
|
|
32
|
-
* someone type a gateway address and a key has to present them identically, or
|
|
33
|
-
* the same gateway works in one client and not another. It is browser-shaped on
|
|
34
|
-
* purpose — a Node host (the VS Code extension) sends the key as a header on
|
|
35
|
-
* both transports and needs none of this.
|
|
36
|
-
*
|
|
37
|
-
* Two transports, because a browser has no choice:
|
|
38
|
-
*
|
|
39
|
-
* - **REST** takes `Authorization: Bearer <key>`, like any service client.
|
|
40
|
-
* - **WebSocket** takes `?key=<key>`, because a tab cannot put a header on an
|
|
41
|
-
* upgrade handshake and the gateway's cookie belongs to another origin. The
|
|
42
|
-
* CLI's auth accepts the key this way on upgrades *only*.
|
|
43
|
-
*
|
|
44
|
-
* The query-string transport is the weaker one and is worth naming: unlike a
|
|
45
|
-
* header it is a permanent credential that lands in reverse-proxy access logs.
|
|
46
|
-
* It is confined to the upgrade so what a leaked URL buys is one attach. If a
|
|
47
|
-
* gateway later mints short-lived tickets, only the body of `buildWsUrl`
|
|
48
|
-
* changes — callers of this function do not.
|
|
49
|
-
*/
|
|
50
|
-
declare function hostAuth(options: {
|
|
51
|
-
/** The gateway's API root, as `apiUrl()` returns it (ends in `/v1`). */baseUrl: string; /** The operator's gateway key. Empty means an unauthenticated gateway. */
|
|
52
|
-
key: string;
|
|
53
|
-
}): Pick<ClientOptions, 'headers' | 'buildWsUrl' | 'buildQueueWsUrl'>;
|
|
3
|
+
//#region src/lib/emitter.d.ts
|
|
4
|
+
type Listener<T> = (payload: T) => void;
|
|
54
5
|
//#endregion
|
|
55
|
-
//#region src/
|
|
56
|
-
/** Whatever the ambient `fetch` accepts as a body — `Blob`/`File` in a browser,
|
|
57
|
-
* `Uint8Array` or a string in Node. Derived rather than named (`BodyInit` is a
|
|
58
|
-
* DOM-lib type, and this package compiles against both). */
|
|
59
|
-
type FetchBody = NonNullable<NonNullable<Parameters<typeof fetch>[1]>['body']>;
|
|
60
|
-
type ClientOptions = {
|
|
61
|
-
/** REST base, e.g. "http://127.0.0.1:8787/v1". The ws:// URL is derived from it. */baseUrl: string;
|
|
62
|
-
/** Extra headers for REST calls (auth). Browsers can't set WS headers — use
|
|
63
|
-
* `buildWsUrl` (ticket query param) or cookies for WS auth. */
|
|
64
|
-
headers?: Record<string, string>; /** Override WS URL construction (auth tickets, proxies). */
|
|
65
|
-
buildWsUrl?: (sessionId: string, afterSeq: number, truncateResults?: boolean, imageRefs?: boolean) => string; /** Override the queue WS URL (`{baseUrl}/queue/ws` by default). */
|
|
66
|
-
buildQueueWsUrl?: () => string; /** Injectable for non-browser environments/tests. Defaults to globalThis.WebSocket. */
|
|
67
|
-
WebSocketImpl?: typeof WebSocket;
|
|
68
|
-
fetchImpl?: typeof fetch;
|
|
69
|
-
};
|
|
70
|
-
/**
|
|
71
|
-
* A REST call the gateway refused, carrying the status alongside the message.
|
|
72
|
-
*
|
|
73
|
-
* An `Error` subclass on purpose: every existing `e instanceof Error` check and
|
|
74
|
-
* every `e.message` read keeps working unchanged. The status is what lets a
|
|
75
|
-
* caller tell "this server doesn't have that route" (404 — stop asking) from
|
|
76
|
-
* "that file was too big" (413 — tell the user), which a message string can't.
|
|
77
|
-
*/
|
|
78
|
-
declare class WorkerDeckError extends Error {
|
|
79
|
-
readonly status: number;
|
|
80
|
-
constructor(message: string, status: number);
|
|
81
|
-
}
|
|
6
|
+
//#region src/session-handle.d.ts
|
|
82
7
|
type AttachOptions = {
|
|
83
|
-
|
|
8
|
+
afterSeq?: number;
|
|
84
9
|
reconnect?: boolean;
|
|
85
|
-
/**
|
|
86
|
-
* Ask the gateway to replay an oversized tool result as its **head**, with
|
|
87
|
-
* `truncated`/`total_chars` on the block and the whole thing one
|
|
88
|
-
* {@link WorkerDeckClient.toolResult} call away. Measured after shipping, that
|
|
89
|
-
* is a **0.3%** cut on a real session, not the 68% it was designed against —
|
|
90
|
-
* the projection had counted base64 as text. The mechanism is right and the
|
|
91
|
-
* bytes were elsewhere; see {@link AttachOptions.imageRefs}.
|
|
92
|
-
*
|
|
93
|
-
* Default off, and the default must stay off: **only the unit that renders may
|
|
94
|
-
* ask for it**. `client` and `react` are separate packages an embedder can
|
|
95
|
-
* skew, and a caller that asked for heads without knowing how to fetch the
|
|
96
|
-
* rest would show one as though it were the whole result — the silent lie this
|
|
97
|
-
* rule family exists to prevent. `useClaudeSession` sets it; nothing else here
|
|
98
|
-
* does. Live events are never affected.
|
|
99
|
-
*/
|
|
100
10
|
truncateResults?: boolean;
|
|
101
|
-
/**
|
|
102
|
-
* Ask the gateway to deliver a tool result's base64 image parts as
|
|
103
|
-
* `image_ref` addresses, their bytes one {@link
|
|
104
|
-
* WorkerDeckClient.toolResultImage} call away.
|
|
105
|
-
*
|
|
106
|
-
* This is where the bytes actually were: measured across 214 local sessions,
|
|
107
|
-
* **91% of all tool-result payload is base64 no client renders** — 489 MB
|
|
108
|
-
* against 44 MB of text, two thirds of it from `Read` looking at a PNG. One
|
|
109
|
-
* session's attach fell from 4,550 KB to 771 KB with no image in it.
|
|
110
|
-
*
|
|
111
|
-
* Default off under the same rule as {@link AttachOptions.truncateResults} —
|
|
112
|
-
* only the unit that renders may ask — and its **own** flag rather than a
|
|
113
|
-
* widening of that one, because this family's "additive at protocol 7"
|
|
114
|
-
* argument rests on a client that never asked being unable to receive one, by
|
|
115
|
-
* construction rather than by release archaeology.
|
|
116
|
-
*
|
|
117
|
-
* Unlike truncation this **also applies to live events**. The render path is
|
|
118
|
-
* ref-then-fetch, so bytes arriving live would only be discarded or pinned in
|
|
119
|
-
* client state.
|
|
120
|
-
*/
|
|
121
11
|
imageRefs?: boolean;
|
|
122
12
|
};
|
|
123
13
|
type SessionHandleEvents = {
|
|
124
|
-
|
|
14
|
+
attached: AttachedFrame;
|
|
125
15
|
event: SessionEvent;
|
|
126
|
-
protocolError: string;
|
|
16
|
+
protocolError: string;
|
|
127
17
|
connectionChange: boolean;
|
|
128
|
-
/**
|
|
129
|
-
* A reconnect has been scheduled, carrying how many have failed in a row (1 on
|
|
130
|
-
* the first). The handle retries forever, so "offline" is a judgement a UI makes
|
|
131
|
-
* about how long it has been failing rather than a state reported here.
|
|
132
|
-
*/
|
|
133
18
|
reconnectAttempt: number;
|
|
134
|
-
/**
|
|
135
|
-
* The server is asking this client to execute a tool call in its own sandbox.
|
|
136
|
-
* Answer with {@link SessionHandle.sendToolCallResult} or
|
|
137
|
-
* {@link SessionHandle.sendToolCallError}, echoing the same `executionId`.
|
|
138
|
-
* Ignoring it is safe: the server fails the execution at `expiresAt`.
|
|
139
|
-
*/
|
|
140
19
|
toolCallRequest: ToolCallRequestFrame;
|
|
141
|
-
/** A bridged call no longer needs an answer (turn interrupted, timed out, or
|
|
142
|
-
* the session closed) — abandon any work in progress for this executionId. */
|
|
143
20
|
toolCallCanceled: {
|
|
144
21
|
executionId: string;
|
|
145
22
|
reason: string;
|
|
146
23
|
};
|
|
147
24
|
};
|
|
148
|
-
type Listener<T> = (payload: T) => void;
|
|
149
25
|
declare class SessionHandle {
|
|
150
26
|
#private;
|
|
151
27
|
readonly sessionId: string;
|
|
152
28
|
constructor(client: WorkerDeckClient, sessionId: string, options?: AttachOptions);
|
|
153
29
|
get lastSeq(): number;
|
|
154
30
|
on<K extends keyof SessionHandleEvents>(kind: K, listener: Listener<SessionHandleEvents[K]>): () => void;
|
|
155
|
-
/** Send a message, optionally naming attachments uploaded ahead of it with
|
|
156
|
-
* {@link WorkerDeckClient.uploadAttachment} (ids in the order they should reach
|
|
157
|
-
* the model). An unknown id fails the whole command — the server will not send a
|
|
158
|
-
* message that quietly lost its picture. */
|
|
159
31
|
send(text: string, attachmentIds?: string[]): void;
|
|
160
32
|
approve(requestId: string, updatedInput?: Record<string, unknown>): void;
|
|
161
33
|
deny(requestId: string, message?: string, interrupt?: boolean): void;
|
|
162
34
|
interrupt(): void;
|
|
163
|
-
/**
|
|
164
|
-
* Reset the conversation in place: same session, empty context. The server
|
|
165
|
-
* answers with a `conversation_reset` event.
|
|
166
|
-
*
|
|
167
|
-
* Gate the affordance on `EngineCapabilities.clearContext` (absent = false)
|
|
168
|
-
* rather than calling this blindly — an engine or a server that cannot do it
|
|
169
|
-
* answers with an error frame, which is the wrong way for a user to find out.
|
|
170
|
-
*/
|
|
171
35
|
clearContext(): void;
|
|
172
36
|
setPermissionMode(mode: PermissionMode): void;
|
|
173
|
-
/** Switch the model for subsequent responses; omit `model` for the default. */
|
|
174
37
|
setModel(model?: string): void;
|
|
175
|
-
/** Answer a bridged tool call (see the `toolCallRequest` event). */
|
|
176
38
|
sendToolCallResult(executionId: string, output: ToolExecutionOutput, logs?: string[]): void;
|
|
177
|
-
/** Report that a bridged tool call could not be executed. The failure is fed
|
|
178
|
-
* to the model as tool output, so the agent can adapt rather than stall. */
|
|
179
39
|
sendToolCallError(executionId: string, reason: string, error: string, logs?: string[]): void;
|
|
180
|
-
/** Ask the server to terminate the session (the handle disconnects too). */
|
|
181
40
|
closeSession(): void;
|
|
182
|
-
/** Skip the reconnect backoff and try again now — what a tab returning to the
|
|
183
|
-
* foreground should do, rather than sitting out the remaining delay. No-op
|
|
184
|
-
* while connected or after {@link SessionHandle.detach}. */
|
|
185
41
|
reconnectNow(): void;
|
|
186
|
-
/** Disconnect this handle without touching the session. */
|
|
187
42
|
detach(): void;
|
|
188
43
|
}
|
|
44
|
+
//#endregion
|
|
45
|
+
//#region src/queue-handle.d.ts
|
|
189
46
|
type QueueHandleEvents = {
|
|
190
|
-
|
|
191
|
-
event: JobEvent;
|
|
192
|
-
stats: QueueStats;
|
|
47
|
+
attached: QueueStats;
|
|
48
|
+
event: JobEvent;
|
|
49
|
+
stats: QueueStats;
|
|
193
50
|
connectionChange: boolean;
|
|
194
51
|
};
|
|
195
|
-
/**
|
|
196
|
-
* Live view of the server's job queue over `{basePath}/queue/ws`. The stream is
|
|
197
|
-
* read-only — submit/cancel stay on the REST methods. There is no replay: on
|
|
198
|
-
* (re)connect, re-list jobs and treat the stream as updates from there.
|
|
199
|
-
*/
|
|
200
52
|
declare class QueueHandle {
|
|
201
53
|
#private;
|
|
202
54
|
constructor(client: WorkerDeckClient, options?: {
|
|
@@ -205,203 +57,86 @@ declare class QueueHandle {
|
|
|
205
57
|
on<K extends keyof QueueHandleEvents>(kind: K, listener: Listener<QueueHandleEvents[K]>): () => void;
|
|
206
58
|
detach(): void;
|
|
207
59
|
}
|
|
60
|
+
//#endregion
|
|
61
|
+
//#region src/host-url.d.ts
|
|
62
|
+
type HostUrl = {
|
|
63
|
+
baseUrl: string;
|
|
64
|
+
};
|
|
65
|
+
declare function apiUrl(host: HostUrl): string | undefined;
|
|
66
|
+
declare function isLoopbackHost(host: HostUrl): boolean;
|
|
67
|
+
//#endregion
|
|
68
|
+
//#region src/host-auth.d.ts
|
|
69
|
+
declare function hostAuth(options: {
|
|
70
|
+
baseUrl: string;
|
|
71
|
+
key: string;
|
|
72
|
+
}): Pick<ClientOptions, 'headers' | 'buildWsUrl' | 'buildQueueWsUrl'>;
|
|
73
|
+
//#endregion
|
|
74
|
+
//#region src/index.d.ts
|
|
75
|
+
type FetchBody = NonNullable<NonNullable<Parameters<typeof fetch>[1]>['body']>;
|
|
76
|
+
type ClientOptions = {
|
|
77
|
+
baseUrl: string;
|
|
78
|
+
headers?: Record<string, string>;
|
|
79
|
+
buildWsUrl?: (sessionId: string, afterSeq: number, truncateResults?: boolean, imageRefs?: boolean) => string;
|
|
80
|
+
buildQueueWsUrl?: () => string;
|
|
81
|
+
WebSocketImpl?: typeof WebSocket;
|
|
82
|
+
fetchImpl?: typeof fetch;
|
|
83
|
+
};
|
|
84
|
+
declare class WorkerDeckError extends Error {
|
|
85
|
+
readonly status: number;
|
|
86
|
+
constructor(message: string, status: number);
|
|
87
|
+
}
|
|
208
88
|
declare class WorkerDeckClient {
|
|
209
89
|
#private;
|
|
210
90
|
constructor(options: ClientOptions);
|
|
211
|
-
/**
|
|
212
|
-
* Stable identity of the (gateway, principal) pair this client speaks as:
|
|
213
|
-
* the base URL plus the auth headers it sends, order-insensitively.
|
|
214
|
-
*
|
|
215
|
-
* Exists for client-side caches that must survive the client *instance*
|
|
216
|
-
* being rebuilt (a `useMemo` recreating it when a view switches gateways)
|
|
217
|
-
* without ever sharing an entry across gateways — a session id is unique
|
|
218
|
-
* only within one — or across credentials. Auth that rides outside
|
|
219
|
-
* `headers` (a same-origin cookie, a fetch shim adding the key host-side)
|
|
220
|
-
* is chosen per origin in every such host, so the base URL still separates
|
|
221
|
-
* principals there; an embedder whose principal varies some other way on
|
|
222
|
-
* one base URL should not key anything on this.
|
|
223
|
-
*/
|
|
224
91
|
get identityKey(): string;
|
|
225
92
|
createSession(request: CreateSessionRequest): Promise<SessionInfo>;
|
|
226
93
|
listSessions(): Promise<SessionInfo[]>;
|
|
227
94
|
getSession(id: string): Promise<SessionInfo>;
|
|
228
|
-
/** Rename a session (or clear the name with `null`, restoring the derived
|
|
229
|
-
* title). 409 when the session is parked. */
|
|
230
95
|
updateSession(id: string, patch: UpdateSessionRequest): Promise<SessionInfo>;
|
|
231
96
|
deleteSession(id: string): Promise<SessionInfo>;
|
|
232
|
-
/** List the files currently in a session's scratch filesystem (deliverables the
|
|
233
|
-
* agent wrote; see the `file_delivered` event). 404s when the session's engine
|
|
234
|
-
* has no file store (Claude-engine sessions). */
|
|
235
97
|
listSessionFiles(sessionId: string): Promise<SessionFileInfo[]>;
|
|
236
|
-
/** Download one session file as text. */
|
|
237
98
|
fetchSessionFile(sessionId: string, path: string): Promise<string>;
|
|
238
|
-
/**
|
|
239
|
-
* Upload one file for the session, ahead of the message that will carry it.
|
|
240
|
-
* The returned `id` goes to {@link SessionHandle.send}.
|
|
241
|
-
*
|
|
242
|
-
* The body is the raw bytes — no multipart — so anything `fetch` accepts as a
|
|
243
|
-
* body works: a `File`/`Blob` from a picker, a `Uint8Array`, a string.
|
|
244
|
-
*/
|
|
245
99
|
uploadAttachment(sessionId: string, file: {
|
|
246
100
|
name: string;
|
|
247
101
|
mediaType: string;
|
|
248
102
|
data: FetchBody;
|
|
249
103
|
}): Promise<MessageAttachment>;
|
|
250
|
-
/** Direct URL for an uploaded attachment — an `<img src>` on a cookie-authenticated
|
|
251
|
-
* same-origin server. Header-authenticated clients must fetch it themselves. */
|
|
252
104
|
attachmentUrl(sessionId: string, attachmentId: string): string;
|
|
253
|
-
/**
|
|
254
|
-
* Direct URL for a file the session's ENGINE produced on the host — the
|
|
255
|
-
* `fileId` of a `file_produced` event. Same caveat as `attachmentUrl`: usable
|
|
256
|
-
* as an `<img src>` only where the credential is a same-origin cookie; a
|
|
257
|
-
* header-authenticated client (the phone) fetches it and makes its own blob.
|
|
258
|
-
*
|
|
259
|
-
* Unlike `/fs/read`, this needs no host-file roots and no raised byte cap —
|
|
260
|
-
* see the `file_produced` note in the protocol for why that is sound.
|
|
261
|
-
*/
|
|
262
105
|
producedFileUrl(sessionId: string, fileId: string): string;
|
|
263
|
-
/** Fetch a produced file's bytes. For clients that cannot put a credential on
|
|
264
|
-
* an `<img src>`. Throws {@link WorkerDeckError} with the response status —
|
|
265
|
-
* a 404 means the file is gone from disk, not that the route is missing. */
|
|
266
106
|
readProducedFile(sessionId: string, fileId: string): Promise<Blob>;
|
|
267
|
-
/**
|
|
268
|
-
* The URL behind a `ProjectIcon.image`. Session-scoped, like
|
|
269
|
-
* {@link producedFileUrl}: the fetch rides the same `canSee` gate as every
|
|
270
|
-
* other `/sessions/:id/*` route, and it takes **no path** — the gateway
|
|
271
|
-
* serves whatever its own discovery resolved for this session's cwd.
|
|
272
|
-
*/
|
|
273
107
|
projectIconUrl(sessionId: string): string;
|
|
274
|
-
/**
|
|
275
|
-
* Fetch a project icon's bytes.
|
|
276
|
-
*
|
|
277
|
-
* Here rather than left to each client for the reason `readProducedFile`
|
|
278
|
-
* exists, plus one this route makes sharper: a VS Code webview has **no
|
|
279
|
-
* external `connect-src` at all**, so it cannot point an `<img src>` at a
|
|
280
|
-
* gateway even in principle — the bytes have to come back through a bridged
|
|
281
|
-
* fetch, which is exactly what this wraps. Three clients building the same
|
|
282
|
-
* URL from `baseUrl` was the other half of the argument.
|
|
283
|
-
*
|
|
284
|
-
* Cache the result by `ProjectIcon.image.hash`, never by session: two
|
|
285
|
-
* sessions in one project serve identical bytes, and the hash is on the wire
|
|
286
|
-
* precisely so a client fetches once per project.
|
|
287
|
-
*
|
|
288
|
-
* A 404 is the uniform "no icon" — no project, a glyph-only project, or an
|
|
289
|
-
* icon the gateway refused. It is deliberately not distinguishable, so treat
|
|
290
|
-
* it as "draw no image", never as an error worth reporting.
|
|
291
|
-
*/
|
|
292
108
|
projectIcon(sessionId: string): Promise<Blob>;
|
|
293
|
-
/** The session's MCP servers and their tools, live from the engine. 501 when the
|
|
294
|
-
* session's engine has no MCP surface; 409 while the session is parked. */
|
|
295
109
|
listMcpServers(sessionId: string): Promise<McpServerStatusInfo[]>;
|
|
296
|
-
/** Reconnect, enable or disable one MCP server; answers with the refreshed list. */
|
|
297
110
|
mcpServerAction(sessionId: string, serverName: string, action: McpServerActionRequest['action']): Promise<McpServerStatusInfo[]>;
|
|
298
|
-
/** Direct download URL for a session file (e.g. an <a download> href). Carries
|
|
299
|
-
* no headers — on authenticated servers, use fetchSessionFile instead. */
|
|
300
111
|
sessionFileUrl(sessionId: string, path: string): string;
|
|
301
|
-
/** Resolve a pending permission over REST — the remote-controller counterpart of the
|
|
302
|
-
* WS `permission_decision` command (e.g. answering a job's AskUserQuestion from a
|
|
303
|
-
* webhook consumer; the request rides on job_progress deliveries). Throws if the
|
|
304
|
-
* request is unknown, already resolved, or expired. */
|
|
305
112
|
resolvePermission(sessionId: string, requestId: string, decision: ResolvePermissionRequest): Promise<void>;
|
|
306
|
-
/**
|
|
307
|
-
* Deliver the result of a deferred tool execution — the callback a remote
|
|
308
|
-
* worker (or a human) makes when the work a session parked on is done. The
|
|
309
|
-
* session is rehydrated if its runner was torn down, and the agent loop
|
|
310
|
-
* continues with this as the tool's output.
|
|
311
|
-
*
|
|
312
|
-
* Applied idempotently by `executionId`: a duplicate, or one racing the
|
|
313
|
-
* execution watchdog, resolves with `applied: false` instead of applying twice.
|
|
314
|
-
* Throws (404) when no session is waiting on that id.
|
|
315
|
-
*/
|
|
316
113
|
submitExecutionResult(executionId: string, result: SubmitExecutionResultRequest): Promise<SubmitExecutionResultResponse>;
|
|
317
|
-
/** List the profiles (named Claude Code config dirs) this server declares, filtered
|
|
318
|
-
* to what the caller may use. Feed a result's `name` to createSession({ profile }).
|
|
319
|
-
* Servers predating profiles 404 here — catch and treat as none declared. */
|
|
320
|
-
/** The profiles this caller may use, plus whether it may create new ones.
|
|
321
|
-
* Each profile carries `managed: true` when it is store-backed and therefore
|
|
322
|
-
* editable; profiles declared in server options are not. */
|
|
323
114
|
listProfiles(): Promise<ListProfilesResponse>;
|
|
324
|
-
/** One profile plus a fresh, view-only snapshot of its config directory (settings,
|
|
325
|
-
* skills, agents, commands — env var names only, never values). */
|
|
326
115
|
getProfile(name: string): Promise<GetProfileResponse>;
|
|
327
|
-
/**
|
|
328
|
-
* Create a managed profile. Requires a server with a profile store and a
|
|
329
|
-
* principal allowed to manage profiles; 409 if the name is already taken by a
|
|
330
|
-
* managed or a startup-declared profile.
|
|
331
|
-
*/
|
|
332
116
|
createProfile(profile: CreateProfileRequest): Promise<ProfileInfo>;
|
|
333
|
-
/** Merge into a managed profile. The name is the route: profiles cannot be
|
|
334
|
-
* renamed, since sessions and jobs are already pinned to the old one. */
|
|
335
117
|
updateProfile(name: string, patch: UpdateProfileRequest): Promise<ProfileInfo>;
|
|
336
|
-
/** Delete a managed profile. Startup-declared profiles are refused (403) —
|
|
337
|
-
* they live in the server's options. */
|
|
338
118
|
deleteProfile(name: string): Promise<void>;
|
|
339
|
-
/** List an engine's on-disk sessions (for resume across server restarts).
|
|
340
|
-
* Feed a result's `sessionId` to createSession({ resume }) — under a profile
|
|
341
|
-
* of the same engine. `profile` names whose store to list (claude profiles →
|
|
342
|
-
* the Agent SDK store, codex profiles → CODEX_HOME threads); absent, the
|
|
343
|
-
* server resolves it implicitly when it declares exactly one profile, else
|
|
344
|
-
* lists the Claude engine's store. */
|
|
345
119
|
listSdkSessions(params?: {
|
|
346
120
|
dir?: string;
|
|
347
121
|
limit?: number;
|
|
348
122
|
offset?: number;
|
|
349
123
|
profile?: string;
|
|
350
124
|
}): Promise<SdkSessionSummary[]>;
|
|
351
|
-
/**
|
|
352
|
-
* The host directories this server will let a client browse, and whether it
|
|
353
|
-
* accepts writes. Servers without host-file access configured 404 here — catch
|
|
354
|
-
* and treat as "no file browser", the same way `listProfiles` handles an older
|
|
355
|
-
* server.
|
|
356
|
-
*
|
|
357
|
-
* These are operator-privileged routes: the auth key is the whole authorization
|
|
358
|
-
* story, and they bypass the agent permission flow entirely. See the protocol
|
|
359
|
-
* package's `HostFileRoot` for why that framing is deliberate.
|
|
360
|
-
*/
|
|
361
125
|
listHostRoots(): Promise<ListHostRootsResponse>;
|
|
362
|
-
/** One host directory, not recursive. Symlinks are reported as symlinks, never
|
|
363
|
-
* followed here — read one to find out whether it resolves somewhere allowed. */
|
|
364
126
|
listHostDir(path: string): Promise<ListHostDirResponse>;
|
|
365
|
-
/** Recursive fuzzy file search under one host directory — the `@file` picker's
|
|
366
|
-
* query. Cheap enough to call per keystroke: build directories are skipped and
|
|
367
|
-
* the walk is bounded, truncating rather than erroring. */
|
|
368
127
|
findHostFiles(path: string, query?: string, limit?: number): Promise<FindHostFilesResponse>;
|
|
369
|
-
/** Read one host file. Binary content comes back base64-encoded; the returned
|
|
370
|
-
* `hash` is what a later `writeHostFile` needs as its `expectedHash`. */
|
|
371
128
|
readHostFile(path: string): Promise<ReadHostFileResponse>;
|
|
372
|
-
/**
|
|
373
|
-
* Write one host file, conditionally — always. Pass the `hash` from the read this
|
|
374
|
-
* edit is based on; a 409 means the agent (or anything else) changed the file
|
|
375
|
-
* underneath you, and the edit must be rebased rather than forced. Omit
|
|
376
|
-
* `expectedHash` only to create a file that does not exist yet.
|
|
377
|
-
*/
|
|
378
129
|
writeHostFile(request: WriteHostFileRequest): Promise<WriteHostFileResponse>;
|
|
379
|
-
/** Schedule a one-shot run. The returned job's `sessionId` (once running) can be
|
|
380
|
-
* fed to `attach()` to watch the run live. */
|
|
381
130
|
createJob(request: CreateJobRequest): Promise<JobInfo>;
|
|
382
131
|
listJobs(): Promise<JobInfo[]>;
|
|
383
132
|
getJob(id: string): Promise<JobInfo>;
|
|
384
|
-
/** Cancel a queued or running job. */
|
|
385
133
|
cancelJob(id: string): Promise<JobInfo>;
|
|
386
134
|
queueStats(): Promise<QueueStats>;
|
|
387
135
|
attach(sessionId: string, options?: AttachOptions): SessionHandle;
|
|
388
|
-
/** Stream the job queue live (requires the server to be configured with `queue`).
|
|
389
|
-
* Servers without a queue refuse the socket — check REST first or expect retries. */
|
|
390
136
|
attachQueue(options?: {
|
|
391
137
|
reconnect?: boolean;
|
|
392
138
|
}): QueueHandle;
|
|
393
|
-
/** @internal used by SessionHandle */
|
|
394
139
|
openSocket(sessionId: string, afterSeq: number, truncateResults?: boolean, imageRefs?: boolean): WebSocket;
|
|
395
|
-
/**
|
|
396
|
-
* The whole of a tool result whose replay delivered only its head.
|
|
397
|
-
*
|
|
398
|
-
* `toolUseId` is required and the gateway verifies it against the block: a
|
|
399
|
-
* woken dormant session has a fresh log with fresh seqs, so a `sourceSeq`
|
|
400
|
-
* cached across a gateway restart can name a different event, and being handed
|
|
401
|
-
* another tool's output under the row you pressed is the exact failure this
|
|
402
|
-
* feature exists to remove. A 404 here means "ask again with a fresh attach",
|
|
403
|
-
* not "empty".
|
|
404
|
-
*/
|
|
405
140
|
toolResult(sessionId: string, seq: number, toolUseId: string, options?: {
|
|
406
141
|
imageRefs?: boolean;
|
|
407
142
|
}): Promise<{
|
|
@@ -410,27 +145,9 @@ declare class WorkerDeckClient {
|
|
|
410
145
|
content: ToolResultBlock['content'];
|
|
411
146
|
isError: boolean;
|
|
412
147
|
}>;
|
|
413
|
-
/**
|
|
414
|
-
* One image part's bytes, addressed by the `image_ref` a replay delivered in
|
|
415
|
-
* its place.
|
|
416
|
-
*
|
|
417
|
-
* A `Blob` and not a URL, and that is the whole reason this method exists: an
|
|
418
|
-
* `<img src>` pointing at the gateway carries a credential in exactly one of
|
|
419
|
-
* this project's four clients (the dashboard's same-origin implicit host,
|
|
420
|
-
* where the cookie rides along). Everywhere else — an added cross-origin
|
|
421
|
-
* gateway on a Bearer header, the VS Code webview whose every byte crosses a
|
|
422
|
-
* postMessage bridge, iOS — the URL is unauthenticated and the picture is a
|
|
423
|
-
* broken icon. Fetched rather than pointed at, then handed to
|
|
424
|
-
* `URL.createObjectURL`; `readProducedFile` is the shipped precedent.
|
|
425
|
-
*
|
|
426
|
-
* A 404 means "ask again with a fresh attach": a woken dormant session has a
|
|
427
|
-
* fresh log with fresh seqs, and the gateway refuses a stale address rather
|
|
428
|
-
* than serving another call's pixels under the row you are looking at.
|
|
429
|
-
*/
|
|
430
148
|
toolResultImage(sessionId: string, seq: number, toolUseId: string, partIndex: number): Promise<Blob>;
|
|
431
|
-
/** @internal used by QueueHandle */
|
|
432
149
|
openQueueSocket(): WebSocket;
|
|
433
150
|
}
|
|
434
151
|
//#endregion
|
|
435
|
-
export { AttachOptions, ClientOptions, FetchBody, type HostUrl, QueueHandle, QueueHandleEvents, SessionHandle, SessionHandleEvents, WorkerDeckClient, WorkerDeckError, apiUrl, hostAuth, isLoopbackHost };
|
|
152
|
+
export { type AttachOptions, ClientOptions, FetchBody, type HostUrl, QueueHandle, type QueueHandleEvents, SessionHandle, type SessionHandleEvents, WorkerDeckClient, WorkerDeckError, apiUrl, hostAuth, isLoopbackHost };
|
|
436
153
|
//# sourceMappingURL=index.d.mts.map
|