@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/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";
@@ -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
@@ -0,0 +1,2 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ export {};
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "@eserstack/noskills-client",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
  }