@eserstack/noskills-client 0.0.0-stage → 5.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/LICENSE +13 -0
- package/README.md +285 -2
- package/dist/attach.d.ts +85 -0
- package/dist/attach.js +234 -0
- package/dist/cert.d.ts +48 -0
- package/dist/cert.js +197 -0
- package/dist/client.d.ts +85 -0
- package/dist/client.js +205 -0
- package/dist/deadline.d.ts +13 -0
- package/dist/deadline.js +62 -0
- package/dist/errors.d.ts +43 -0
- package/dist/errors.js +61 -0
- package/dist/mod.d.ts +16 -0
- package/dist/mod.js +5 -0
- package/dist/types.d.ts +317 -0
- package/dist/types.js +2 -0
- package/package.json +48 -3
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* noskills-client — browser + Node SDK for the noskills-server daemon.
|
|
3
|
+
*
|
|
4
|
+
* REST calls: createNoskillsClient()
|
|
5
|
+
* WebTransport: attachSession()
|
|
6
|
+
* Cert fingerprint: fetchAndPinCertFingerprint() / getCertFingerprint()
|
|
7
|
+
* Errors: NoskillsTimeoutError, NoskillsResponseError,
|
|
8
|
+
* CertFingerprintError
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
export type { AbortCommand, AttachSession, CallOptions, CertRotatingEvent, ClientCommand, ClientCountEvent, CreateSessionRequest, CreateSessionResponse, DaemonEvent, ErrorEvent, FanoutEvent, ForkCreatedEvent, LoginRequest, LoginResponse, MuxCommand, MuxFrameEvent, NoskillsClientConfig, PermissionDecision, PermissionDecisionEvent, PermissionRequestEvent, PermissionResponseCommand, PermissionResponseRejectedEvent, Project, QueryDoneEvent, RegisterProjectRequest, SdkEvent, Session, SessionMetaEvent, SetModelCommand, SetPermissionModeCommand, SpawnProgressEvent, StopCommand, TranscriptReplayEndEvent, TranscriptReplayStartEvent, UserMessageCommand, WorkerDiedEvent, WorkerReadyEvent, } from "./types.ts";
|
|
13
|
+
export { fetchAndPinCertFingerprint, getCertFingerprint, loadCertFingerprint, storeCertFingerprint, } from "./cert.ts";
|
|
14
|
+
export { createNoskillsClient, NoskillsClient } from "./client.ts";
|
|
15
|
+
export { CertFingerprintError, NoskillsResponseError, NoskillsTimeoutError, } from "./errors.ts";
|
|
16
|
+
export { type AttachOptions, attachSession } from "./attach.ts";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
export { fetchAndPinCertFingerprint, getCertFingerprint, loadCertFingerprint, storeCertFingerprint, } from "./cert.js";
|
|
3
|
+
export { createNoskillsClient, NoskillsClient } from "./client.js";
|
|
4
|
+
export { CertFingerprintError, NoskillsResponseError, NoskillsTimeoutError, } from "./errors.js";
|
|
5
|
+
export { attachSession } from "./attach.js";
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public type definitions for @eserstack/noskills-client.
|
|
3
|
+
*
|
|
4
|
+
* Event shape mirrors the server wire protocol defined in
|
|
5
|
+
* pkg/ajan/noskillsserverfx/fanout.go and wt_attach.go.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import type { FrontendToServer as MuxFrontendFrame, ServerToFrontend as MuxServerFrame } from "@eserstack/mux";
|
|
10
|
+
export interface NoskillsClientConfig {
|
|
11
|
+
/** Base URL of the noskills-server daemon (e.g. "https://localhost:4433"). */
|
|
12
|
+
baseUrl: string;
|
|
13
|
+
/** Bearer token returned by POST /auth/login. */
|
|
14
|
+
token?: string;
|
|
15
|
+
/**
|
|
16
|
+
* SHA-256 fingerprints (32 bytes each) of the daemon's certificate. Every
|
|
17
|
+
* entry goes to the WebTransport API as `serverCertificateHashes`, so a
|
|
18
|
+
* daemon that is rotating its certificate can match either one. Not needed
|
|
19
|
+
* when the operating system trusts the certificate (for example, mkcert).
|
|
20
|
+
*/
|
|
21
|
+
certHashes?: ArrayBuffer[];
|
|
22
|
+
/**
|
|
23
|
+
* Milliseconds a REST call waits for the daemon before it throws a
|
|
24
|
+
* `NoskillsTimeoutError`. Defaults to 10 000. `registerProject` with a git
|
|
25
|
+
* URL waits 300 000 by default instead, since the daemon clones the
|
|
26
|
+
* repository before it answers.
|
|
27
|
+
*/
|
|
28
|
+
timeoutMs?: number;
|
|
29
|
+
}
|
|
30
|
+
/** Options for one REST call or one certificate fingerprint fetch. */
|
|
31
|
+
export interface CallOptions {
|
|
32
|
+
/** Cancels the call; it then rejects with the signal's reason. */
|
|
33
|
+
signal?: AbortSignal;
|
|
34
|
+
/** Milliseconds to wait for this call, in place of the default. */
|
|
35
|
+
timeoutMs?: number;
|
|
36
|
+
}
|
|
37
|
+
export interface LoginRequest {
|
|
38
|
+
pin: string;
|
|
39
|
+
}
|
|
40
|
+
export interface LoginResponse {
|
|
41
|
+
token: string;
|
|
42
|
+
expiresAt: string;
|
|
43
|
+
}
|
|
44
|
+
export interface Project {
|
|
45
|
+
slug: string;
|
|
46
|
+
root: string;
|
|
47
|
+
name?: string;
|
|
48
|
+
}
|
|
49
|
+
export interface RegisterProjectRequest {
|
|
50
|
+
/** Absolute local path to an existing project. */
|
|
51
|
+
path?: string;
|
|
52
|
+
/** Git URL for clone-on-demand. */
|
|
53
|
+
git?: string;
|
|
54
|
+
/** Explicit slug; auto-derived from path/git if omitted. */
|
|
55
|
+
slug?: string;
|
|
56
|
+
}
|
|
57
|
+
export interface Session {
|
|
58
|
+
sessionId: string;
|
|
59
|
+
slug: string;
|
|
60
|
+
startedAt: string;
|
|
61
|
+
}
|
|
62
|
+
export interface CreateSessionRequest {
|
|
63
|
+
/** Resume from an existing session ID. */
|
|
64
|
+
resumeFrom?: string;
|
|
65
|
+
/**
|
|
66
|
+
* Worker flavour to attach with: "agent" (default) or "mux" (terminal
|
|
67
|
+
* multiplexer). The daemon stores no per-session state, so the same value must
|
|
68
|
+
* be passed as `?kind=` on attach.
|
|
69
|
+
*
|
|
70
|
+
* "agent" is served by the ACP worker; "acp" is an accepted synonym for it.
|
|
71
|
+
* Both spellings exist because stored sessions carry either string.
|
|
72
|
+
*/
|
|
73
|
+
kind?: "agent" | "acp" | "mux";
|
|
74
|
+
}
|
|
75
|
+
export interface CreateSessionResponse {
|
|
76
|
+
sessionId: string;
|
|
77
|
+
/** Echoed back from the request; see {@link CreateSessionRequest.kind}. */
|
|
78
|
+
kind?: "agent" | "acp" | "mux";
|
|
79
|
+
}
|
|
80
|
+
export interface SessionMetaEvent {
|
|
81
|
+
type: "session_meta";
|
|
82
|
+
v: number;
|
|
83
|
+
phase: string;
|
|
84
|
+
title?: string;
|
|
85
|
+
model?: string;
|
|
86
|
+
lastIteration?: number;
|
|
87
|
+
}
|
|
88
|
+
export interface TranscriptReplayStartEvent {
|
|
89
|
+
type: "transcript_replay_start";
|
|
90
|
+
v: number;
|
|
91
|
+
}
|
|
92
|
+
export interface TranscriptReplayEndEvent {
|
|
93
|
+
type: "transcript_replay_end";
|
|
94
|
+
v: number;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* One streamed change within an agent turn.
|
|
98
|
+
*
|
|
99
|
+
* This is the event that actually carries model output, and until now it had no
|
|
100
|
+
* variant in {@link DaemonEvent} at all — clients had to cast out of the union
|
|
101
|
+
* to read assistant text.
|
|
102
|
+
*
|
|
103
|
+
* `event` is an ACP `SessionUpdate`: a schema-defined object discriminated by
|
|
104
|
+
* its `sessionUpdate` field (`agent_message_chunk`, `agent_thought_chunk`,
|
|
105
|
+
* `tool_call`, `tool_call_update`, `plan`, …).
|
|
106
|
+
*
|
|
107
|
+
* `sessionUpdate` is optional because this event is persisted to the ledger and
|
|
108
|
+
* replayed verbatim: a session started under an older daemon can replay entries
|
|
109
|
+
* whose payload predates the ACP shape. Narrow on `sessionUpdate` being present
|
|
110
|
+
* before relying on it.
|
|
111
|
+
*/
|
|
112
|
+
export interface SdkEvent {
|
|
113
|
+
type: "sdk_event";
|
|
114
|
+
v: number;
|
|
115
|
+
event: {
|
|
116
|
+
sessionUpdate?: string;
|
|
117
|
+
} & Record<string, unknown>;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* A turn finished. `stopReason` says why the turn ended, and is present only
|
|
121
|
+
* when the agent reported one.
|
|
122
|
+
*/
|
|
123
|
+
export interface QueryDoneEvent {
|
|
124
|
+
type: "query_done";
|
|
125
|
+
v: number;
|
|
126
|
+
stopReason?: "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* The agent is asking to run a tool.
|
|
130
|
+
*
|
|
131
|
+
* Field names here are the ones actually on the wire. The previous declaration
|
|
132
|
+
* claimed `id` and `tool`; the daemon has always sent `requestId` and
|
|
133
|
+
* `toolName`, so any client written against the old type read `undefined`.
|
|
134
|
+
*/
|
|
135
|
+
export interface PermissionRequestEvent {
|
|
136
|
+
type: "permission_request";
|
|
137
|
+
v: number;
|
|
138
|
+
requestId: string;
|
|
139
|
+
toolName: string;
|
|
140
|
+
input: unknown;
|
|
141
|
+
toolUseId: string;
|
|
142
|
+
/** ACP only: the exact choices the agent offered. */
|
|
143
|
+
options?: Array<{
|
|
144
|
+
optionId: string;
|
|
145
|
+
name: string;
|
|
146
|
+
kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
|
|
147
|
+
}>;
|
|
148
|
+
/** ACP only: the tool's category, e.g. `read`, `edit`, `execute`. */
|
|
149
|
+
kind?: string;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* A decision the daemon refused to act on.
|
|
153
|
+
*
|
|
154
|
+
* `reason` distinguishes the two causes: a decision it could not interpret, and
|
|
155
|
+
* one it could not journal durably. An unrecognised decision is rejected rather
|
|
156
|
+
* than interpreted — it used to be rewritten to `allow`, which granted a
|
|
157
|
+
* permission the user was never asked about.
|
|
158
|
+
*/
|
|
159
|
+
export interface PermissionResponseRejectedEvent {
|
|
160
|
+
type: "permission_response_rejected";
|
|
161
|
+
v: number;
|
|
162
|
+
id: string;
|
|
163
|
+
decision: string;
|
|
164
|
+
reason?: string;
|
|
165
|
+
winnerClientId?: string;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* A permission decision, journalled before the agent was told about it.
|
|
169
|
+
*
|
|
170
|
+
* `class` is `write` for tools that change state and `read` otherwise. A
|
|
171
|
+
* `write` decision reaches disk with fdatasync before the agent may act on it,
|
|
172
|
+
* so a crash in between leaves this record absent rather than showing an
|
|
173
|
+
* approval for a tool that never ran.
|
|
174
|
+
*/
|
|
175
|
+
export interface PermissionDecisionEvent {
|
|
176
|
+
type: "permission_decision";
|
|
177
|
+
v: number;
|
|
178
|
+
id: string;
|
|
179
|
+
tool: string;
|
|
180
|
+
decision: string;
|
|
181
|
+
class: "read" | "write";
|
|
182
|
+
}
|
|
183
|
+
export interface ClientCountEvent {
|
|
184
|
+
type: "client_count";
|
|
185
|
+
v: number;
|
|
186
|
+
n: number;
|
|
187
|
+
}
|
|
188
|
+
export interface FanoutEvent {
|
|
189
|
+
type: "fanout";
|
|
190
|
+
v: number;
|
|
191
|
+
from: string;
|
|
192
|
+
payload: unknown;
|
|
193
|
+
}
|
|
194
|
+
export interface WorkerDiedEvent {
|
|
195
|
+
type: "worker_died";
|
|
196
|
+
v: number;
|
|
197
|
+
reason?: string;
|
|
198
|
+
}
|
|
199
|
+
export interface WorkerReadyEvent {
|
|
200
|
+
type: "worker_ready";
|
|
201
|
+
v: number;
|
|
202
|
+
}
|
|
203
|
+
export interface SpawnProgressEvent {
|
|
204
|
+
type: "spawn_progress";
|
|
205
|
+
v: number;
|
|
206
|
+
stage: "starting" | "loading_sdk" | "ready";
|
|
207
|
+
}
|
|
208
|
+
export interface ForkCreatedEvent {
|
|
209
|
+
type: "fork_created";
|
|
210
|
+
v: number;
|
|
211
|
+
parentSessionId: string;
|
|
212
|
+
newSessionId: string;
|
|
213
|
+
atMessageId?: string;
|
|
214
|
+
}
|
|
215
|
+
export interface ErrorEvent {
|
|
216
|
+
type: "error";
|
|
217
|
+
v: number;
|
|
218
|
+
code: string;
|
|
219
|
+
message: string;
|
|
220
|
+
}
|
|
221
|
+
export interface CertRotatingEvent {
|
|
222
|
+
type: "cert_rotating";
|
|
223
|
+
v: number;
|
|
224
|
+
/** SHA-256 hex fingerprint of the incoming leaf cert. */
|
|
225
|
+
newFingerprint: string;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* A mux multiplexer frame, for sessions whose worker hosts a {@link
|
|
229
|
+
* https://jsr.io/@eserstack/mux | mux} server (terminal panes) instead of the
|
|
230
|
+
* one-shot AI agent worker. The whole neutral mux protocol rides inside `frame`.
|
|
231
|
+
* Mux frames are not ledger entries: their `seq` repeats the number of the last
|
|
232
|
+
* ledger line sent, so `?after=` replays only missed ledger events and a
|
|
233
|
+
* reconnecting client gets the current screen from the mux server instead.
|
|
234
|
+
* `frame` is one of the mux server→frontend messages, such as `scene` (full or
|
|
235
|
+
* delta), `screen` or `exit`.
|
|
236
|
+
*/
|
|
237
|
+
export interface MuxFrameEvent {
|
|
238
|
+
type: "mux";
|
|
239
|
+
v: number;
|
|
240
|
+
frame: MuxServerFrame;
|
|
241
|
+
}
|
|
242
|
+
export type DaemonEvent = (SessionMetaEvent | TranscriptReplayStartEvent | TranscriptReplayEndEvent | SdkEvent | QueryDoneEvent | PermissionRequestEvent | PermissionResponseRejectedEvent | PermissionDecisionEvent | ClientCountEvent | FanoutEvent | WorkerDiedEvent | WorkerReadyEvent | SpawnProgressEvent | ForkCreatedEvent | ErrorEvent | CertRotatingEvent | MuxFrameEvent) & {
|
|
243
|
+
seq?: number;
|
|
244
|
+
};
|
|
245
|
+
export interface UserMessageCommand {
|
|
246
|
+
type: "user_message";
|
|
247
|
+
content: string;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* The answer to a `permission_request`, sent with the request's `requestId` as
|
|
251
|
+
* `id`.
|
|
252
|
+
*
|
|
253
|
+
* The daemon accepts exactly these four decisions and answers anything else
|
|
254
|
+
* with `permission_response_rejected`. For an ACP agent it picks the matching
|
|
255
|
+
* option the agent offered: `allow` takes `allow_once`, `allow_always` takes
|
|
256
|
+
* `allow_always`, `deny` takes `reject_once` and `deny_remember` takes
|
|
257
|
+
* `reject_always`. When that kind is missing it takes the other option of the
|
|
258
|
+
* same direction, and with neither it cancels the request.
|
|
259
|
+
*/
|
|
260
|
+
export interface PermissionResponseCommand {
|
|
261
|
+
type: "permission_response";
|
|
262
|
+
id: string;
|
|
263
|
+
decision: PermissionDecision;
|
|
264
|
+
/**
|
|
265
|
+
* Text the daemon forwards to a socket worker with the decision. ACP agents
|
|
266
|
+
* have no field for it and do not receive it.
|
|
267
|
+
*/
|
|
268
|
+
message?: string;
|
|
269
|
+
}
|
|
270
|
+
/** A decision the daemon accepts in a `permission_response`. */
|
|
271
|
+
export type PermissionDecision = "allow" | "allow_always" | "deny" | "deny_remember";
|
|
272
|
+
export interface StopCommand {
|
|
273
|
+
type: "stop";
|
|
274
|
+
}
|
|
275
|
+
export interface AbortCommand {
|
|
276
|
+
type: "abort";
|
|
277
|
+
}
|
|
278
|
+
/**
|
|
279
|
+
* Asks for a different model for the session.
|
|
280
|
+
*
|
|
281
|
+
* The daemon does not act on it: ACP v1 has no request for changing the
|
|
282
|
+
* model, so the daemon logs `set_model is not supported by the agent protocol`
|
|
283
|
+
* and leaves the session as it was. The type stays so that existing callers
|
|
284
|
+
* keep compiling; nothing confirms or rejects the command on the stream.
|
|
285
|
+
*/
|
|
286
|
+
export interface SetModelCommand {
|
|
287
|
+
type: "set_model";
|
|
288
|
+
model: string;
|
|
289
|
+
}
|
|
290
|
+
export interface SetPermissionModeCommand {
|
|
291
|
+
type: "set_permission_mode";
|
|
292
|
+
mode: string;
|
|
293
|
+
}
|
|
294
|
+
/**
|
|
295
|
+
* A mux frontend command for a mux-hosting session: the whole neutral mux
|
|
296
|
+
* frontend→server protocol rides inside `frame` (one of `attach`, `action`, or
|
|
297
|
+
* `resize`). The daemon relays it straight to that session's mux server.
|
|
298
|
+
*/
|
|
299
|
+
export interface MuxCommand {
|
|
300
|
+
type: "mux";
|
|
301
|
+
frame: MuxFrontendFrame;
|
|
302
|
+
}
|
|
303
|
+
export type ClientCommand = UserMessageCommand | PermissionResponseCommand | StopCommand | AbortCommand | SetModelCommand | SetPermissionModeCommand | MuxCommand;
|
|
304
|
+
export interface AttachSession {
|
|
305
|
+
/** Async iterator of parsed DaemonEvent objects from the server. */
|
|
306
|
+
events(): AsyncIterable<DaemonEvent>;
|
|
307
|
+
/** Send a typed command to the server. */
|
|
308
|
+
send(cmd: ClientCommand): Promise<void>;
|
|
309
|
+
/** Close the bidi stream and the underlying WT session. */
|
|
310
|
+
close(): void;
|
|
311
|
+
/**
|
|
312
|
+
* The seq of the last event received from this session.
|
|
313
|
+
* Pass as afterSeq in AttachOptions when reconnecting to skip
|
|
314
|
+
* already-delivered events (mobile network partition recovery).
|
|
315
|
+
*/
|
|
316
|
+
readonly lastSeq: number;
|
|
317
|
+
}
|
package/dist/types.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,51 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@eserstack/noskills-client",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "5.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "https://github.com/eser/stack",
|
|
8
|
+
"directory": "pkg/@eserstack/noskills-client"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist/**/*.js",
|
|
12
|
+
"dist/**/*.d.ts",
|
|
13
|
+
"dist/**/*.json"
|
|
14
|
+
],
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"types": "./dist/mod.d.ts",
|
|
18
|
+
"import": "./dist/mod.js"
|
|
19
|
+
},
|
|
20
|
+
"./types": {
|
|
21
|
+
"types": "./dist/types.d.ts",
|
|
22
|
+
"import": "./dist/types.js"
|
|
23
|
+
},
|
|
24
|
+
"./cert": {
|
|
25
|
+
"types": "./dist/cert.d.ts",
|
|
26
|
+
"import": "./dist/cert.js"
|
|
27
|
+
},
|
|
28
|
+
"./client": {
|
|
29
|
+
"types": "./dist/client.d.ts",
|
|
30
|
+
"import": "./dist/client.js"
|
|
31
|
+
},
|
|
32
|
+
"./attach": {
|
|
33
|
+
"types": "./dist/attach.d.ts",
|
|
34
|
+
"import": "./dist/attach.js"
|
|
35
|
+
},
|
|
36
|
+
"./errors": {
|
|
37
|
+
"types": "./dist/errors.d.ts",
|
|
38
|
+
"import": "./dist/errors.js"
|
|
39
|
+
}
|
|
40
|
+
},
|
|
41
|
+
"dependencies": {
|
|
42
|
+
"@eserstack/mux": "5.0.0",
|
|
43
|
+
"@eserstack/webtransport": "5.0.0"
|
|
44
|
+
},
|
|
45
|
+
"devDependencies": {
|
|
46
|
+
"@eserstack/test-kit": "5.0.0"
|
|
47
|
+
},
|
|
48
|
+
"scripts": {
|
|
49
|
+
"build": "node ../../../etc/scripts/build-library.ts"
|
|
50
|
+
}
|
|
6
51
|
}
|