@celljs/ta-client 4.9.1 → 4.10.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.
@@ -1,13 +1,51 @@
1
1
  import { TA_ACCESS_SERVICE, TA_AUTH_SERVICE, TA_CLIENT_SERVICE, TA_GATEWAY_SERVICE, TA_PACKAGE_SERVICE, TA_RELAY_SERVICE, TA_REMOTE_SERVICE, TA_SERVER_SERVICE, TA_SETTINGS_SERVICE, TA_TERMINAL_SERVICE, TA_WORKSPACE_SERVICE, TaErrorCode, } from '@celljs/ta-protocol';
2
- /** A failed call. `code` is set for failures the server names. */
2
+ /**
3
+ * A failed call. `code` is set for failures the server names; `rpcCode` is the code of JSON-RPC's error,
4
+ * by which a client tells a method an older ta serve does not have (`TaRemoteError.METHOD_NOT_FOUND`).
5
+ */
3
6
  export class TaRemoteError extends Error {
4
- constructor(message, code, hint) {
7
+ constructor(message, code, hint, rpcCode) {
5
8
  super(message);
6
9
  this.code = code;
7
10
  this.hint = hint;
11
+ this.rpcCode = rpcCode;
8
12
  this.name = 'TaRemoteError';
9
13
  }
14
+ /** The error of a JSON-RPC answer: its code, and the code and hint of ta serve when it named the failure. */
15
+ static of(error) {
16
+ var _a;
17
+ const data = (_a = error.data) === null || _a === void 0 ? void 0 : _a.data;
18
+ return new TaRemoteError(error.message, data === null || data === void 0 ? void 0 : data.code, data === null || data === void 0 ? void 0 : data.hint, error.code);
19
+ }
20
+ /** A call that waited for a connection that did not come back. */
21
+ static notConnected() {
22
+ return new TaRemoteError(TaRemoteError.NOT_CONNECTED, TaErrorCode.CONNECTION_LOST, 'Try again once the connection is back.');
23
+ }
24
+ /**
25
+ * Whether a failure is only that the connection was lost, which mends itself: by its code, or by its
26
+ * words in a text (a web extension shows `error.message`, often inside its own words).
27
+ */
28
+ static isConnectionLost(cause) {
29
+ if (typeof cause === 'string') {
30
+ return cause.includes(TaRemoteError.NOT_CONNECTED) || cause.includes(TaRemoteError.LOST);
31
+ }
32
+ return (cause === null || cause === void 0 ? void 0 : cause.code) === TaErrorCode.CONNECTION_LOST;
33
+ }
34
+ /** Whether the server has no such method: a ta serve from before it was added. */
35
+ static isMethodNotFound(error) {
36
+ return error instanceof TaRemoteError && error.rpcCode === TaRemoteError.METHOD_NOT_FOUND;
37
+ }
10
38
  }
39
+ /** JSON-RPC's code for a method the server does not have. */
40
+ TaRemoteError.METHOD_NOT_FOUND = -32601;
41
+ /** What a call says that waited for a connection that did not come back. */
42
+ TaRemoteError.NOT_CONNECTED = 'Not connected to ta serve.';
43
+ /** What a call says that was sent on a connection lost before its answer. */
44
+ TaRemoteError.LOST = 'The connection to ta serve was lost.';
45
+ /** Methods that only read: sent again after a lost connection. */
46
+ const READ_METHOD = /^(get|list|read|find)[A-Z]/;
47
+ /** Methods whose input carries a clientMessageId, by which ta serve takes a message once however often it comes. */
48
+ const MESSAGE_METHODS = new Set(['prompt', 'steer', 'followUp']);
11
49
  /**
12
50
  * A connection to `ta serve` on the `WebSocket` of the platform, with no other dependency, so that it
13
51
  * fits a browser, Electron or a mobile app. It reconnects until closed; `onOpen` runs each time, for
@@ -15,8 +53,11 @@ export class TaRemoteError extends Error {
15
53
  * over the one WebSocket.
16
54
  *
17
55
  * A call made while the connection is down waits a little for it to come back (`waitForOpenMs`): it was
18
- * not sent. Calls that were sent when the connection was lost fail and are not sent again, because only
19
- * the caller knows whether to resend.
56
+ * not sent. Calls that were sent when the connection was lost fail, unless they are safe to send again
57
+ * (`resendable`: reads, and messages ta serve takes once by their clientMessageId), which wait for the
58
+ * next connection and go again for up to `retryForMs`: on a network that drops now and then, a read or a
59
+ * message is late rather than failed. A call that stalls while nothing comes makes it check the
60
+ * connection (`stallMs`), so that one gone without a word is not waited on for long.
20
61
  */
21
62
  export class TaConnection {
22
63
  constructor(options) {
@@ -46,6 +87,9 @@ export class TaConnection {
46
87
  this.reconnectingListeners = new Set();
47
88
  /** The calls waiting for the connection to open: `go` once it is, `fail` when it is closed. */
48
89
  this.waiting = new Set();
90
+ /** When the last message came, on the clock of Date.now(). */
91
+ this.lastReceivedAt = 0;
92
+ this.probing = false;
49
93
  }
50
94
  /** Resolves when the first connection is open, or rejects if it cannot be made; later losses reconnect. */
51
95
  connect() {
@@ -55,6 +99,7 @@ export class TaConnection {
55
99
  var _a;
56
100
  this.closed = true;
57
101
  clearTimeout(this.reconnectTimer);
102
+ clearInterval(this.stallTimer);
58
103
  for (const call of [...this.waiting]) {
59
104
  call.fail();
60
105
  }
@@ -124,8 +169,12 @@ export class TaConnection {
124
169
  return;
125
170
  }
126
171
  let answered = false;
172
+ const since = Date.now();
173
+ this.probing = true;
127
174
  const timer = setTimeout(() => {
128
- if (!answered && this.socket === socket) {
175
+ this.probing = false;
176
+ // Anything that came meanwhile says it is alive, only slow: the answer waits behind it.
177
+ if (!answered && this.socket === socket && this.lastReceivedAt <= since) {
129
178
  socket.onclose = null;
130
179
  socket.onmessage = null;
131
180
  socket.close();
@@ -133,10 +182,19 @@ export class TaConnection {
133
182
  this.lost(socket, true, true);
134
183
  }
135
184
  }, timeoutMs);
136
- this.server.getServerInfo().then(() => {
185
+ const done = () => {
137
186
  answered = true;
187
+ this.probing = false;
138
188
  clearTimeout(timer);
139
- }, () => clearTimeout(timer));
189
+ };
190
+ // Any answer says the connection is alive, an error too. Asked of what answers at the front: `ta gateway`
191
+ // answers its own service while a Ta behind it is slow, and a Ta service says it has no such service.
192
+ // Sent once, not again after a loss as a read would be: it asks about this connection.
193
+ this.send(TA_GATEWAY_SERVICE, 'getGateway', []).then(done, error => {
194
+ if (error.code !== TaErrorCode.CONNECTION_LOST) {
195
+ done();
196
+ }
197
+ });
140
198
  }
141
199
  /** With `resolve` and `reject`: the first connection, whose failure is the caller's to handle. */
142
200
  open(resolve, reject) {
@@ -202,10 +260,11 @@ export class TaConnection {
202
260
  listener(delay, this.attempts);
203
261
  }
204
262
  }
205
- /** Resolves once the connection is open, or rejects after `waitForOpenMs`, or at once when it is closed. */
206
- opened() {
207
- const { waitForOpenMs = 5000 } = this.options;
208
- const notConnected = () => new TaRemoteError('Not connected to ta serve.', TaErrorCode.CONNECTION_LOST, 'Try again once the connection is back.');
263
+ /** Resolves once the connection is open, or rejects after `waitForOpenMs` (or `waitMs`), or at once when it is closed. */
264
+ opened(waitMs) {
265
+ const { waitForOpenMs: configured = 5000 } = this.options;
266
+ const waitForOpenMs = configured <= 0 ? 0 : (waitMs !== null && waitMs !== void 0 ? waitMs : configured);
267
+ const notConnected = () => TaRemoteError.notConnected();
209
268
  if (this.closed || waitForOpenMs <= 0) {
210
269
  return Promise.reject(notConnected());
211
270
  }
@@ -228,7 +287,7 @@ export class TaConnection {
228
287
  }
229
288
  failPending() {
230
289
  for (const call of this.pending.values()) {
231
- call.reject(new TaRemoteError('The connection to ta serve was lost.', TaErrorCode.CONNECTION_LOST, 'Send it again once the connection is back.'));
290
+ call.reject(new TaRemoteError(TaRemoteError.LOST, TaErrorCode.CONNECTION_LOST, 'Send it again once the connection is back.'));
232
291
  }
233
292
  this.pending.clear();
234
293
  }
@@ -237,10 +296,46 @@ export class TaConnection {
237
296
  get: (_target, method) => (...params) => this.call(name, method, params),
238
297
  });
239
298
  }
299
+ /**
300
+ * Whether a call may go again after a lost connection, as doing it twice does what doing it once does:
301
+ * a read, or a message with its clientMessageId (TaPromptInput), which ta serve takes once.
302
+ */
303
+ static resendable(service, method, params) {
304
+ var _a;
305
+ if (READ_METHOD.test(method)) {
306
+ return true;
307
+ }
308
+ return service === TA_SERVER_SERVICE && MESSAGE_METHODS.has(method) && !!((_a = params[1]) === null || _a === void 0 ? void 0 : _a.clientMessageId);
309
+ }
240
310
  async call(service, method, params) {
311
+ var _a, _b;
312
+ if (!TaConnection.resendable(service, method, params)) {
313
+ if (((_a = this.socket) === null || _a === void 0 ? void 0 : _a.readyState) !== WebSocket.OPEN) {
314
+ await this.opened();
315
+ }
316
+ return this.send(service, method, params);
317
+ }
318
+ const { waitForOpenMs = 5000, retryForMs = waitForOpenMs } = this.options;
319
+ const deadline = Date.now() + Math.max(retryForMs, 1);
320
+ for (;;) {
321
+ if (((_b = this.socket) === null || _b === void 0 ? void 0 : _b.readyState) !== WebSocket.OPEN) {
322
+ await this.opened(Math.max(1, deadline - Date.now()));
323
+ }
324
+ try {
325
+ return await this.send(service, method, params);
326
+ }
327
+ catch (error) {
328
+ if (error.code !== TaErrorCode.CONNECTION_LOST || this.closed || Date.now() >= deadline) {
329
+ throw error;
330
+ }
331
+ }
332
+ }
333
+ }
334
+ /** Sends a call on the open connection; its answer, or its failure when the connection is lost first. */
335
+ send(service, method, params) {
241
336
  var _a;
242
337
  if (((_a = this.socket) === null || _a === void 0 ? void 0 : _a.readyState) !== WebSocket.OPEN) {
243
- await this.opened();
338
+ return Promise.reject(TaRemoteError.notConnected());
244
339
  }
245
340
  const socket = this.socket;
246
341
  const id = ++this.nextId;
@@ -250,12 +345,32 @@ export class TaConnection {
250
345
  length--;
251
346
  }
252
347
  return new Promise((resolve, reject) => {
253
- this.pending.set(id, { resolve, reject });
348
+ this.pending.set(id, { resolve, reject, sentAt: Date.now() });
349
+ this.watchStalls();
254
350
  socket.send(JSON.stringify({ jsonrpc: '2.0', id, method: `${service}/${method}`, params: params.slice(0, length) }));
255
351
  });
256
352
  }
353
+ /** While calls wait for answers: one that waits past `stallMs` with nothing come since makes it check the connection. */
354
+ watchStalls() {
355
+ const { stallMs = 5000 } = this.options;
356
+ if (this.stallTimer !== undefined || stallMs <= 0) {
357
+ return;
358
+ }
359
+ this.stallTimer = setInterval(() => {
360
+ const [oldest] = this.pending.values();
361
+ if (!oldest) {
362
+ clearInterval(this.stallTimer);
363
+ this.stallTimer = undefined;
364
+ return;
365
+ }
366
+ if (!this.probing && Date.now() - Math.max(oldest.sentAt, this.lastReceivedAt) >= stallMs) {
367
+ this.wake(stallMs);
368
+ }
369
+ }, Math.min(1000, stallMs));
370
+ }
257
371
  receive(text) {
258
- var _a, _b, _c, _d, _e, _f;
372
+ var _a, _b, _c, _d, _e;
373
+ this.lastReceivedAt = Date.now();
259
374
  const message = JSON.parse(text);
260
375
  if (message.method === `${TA_CLIENT_SERVICE}/onEvents`) {
261
376
  const [events] = message.params;
@@ -304,8 +419,7 @@ export class TaConnection {
304
419
  }
305
420
  this.pending.delete(message.id);
306
421
  if (message.error) {
307
- const data = (_f = message.error.data) === null || _f === void 0 ? void 0 : _f.data;
308
- call.reject(new TaRemoteError(message.error.message, data === null || data === void 0 ? void 0 : data.code, data === null || data === void 0 ? void 0 : data.hint));
422
+ call.reject(TaRemoteError.of(message.error));
309
423
  }
310
424
  else {
311
425
  call.resolve(message.result);
@@ -19,6 +19,14 @@ export interface SessionWidget {
19
19
  lines: string[];
20
20
  placement: 'aboveEditor' | 'belowEditor';
21
21
  }
22
+ /** A message sent from this client that the session does not have yet: on its way, or `failed` to go. */
23
+ export interface OutboxMessage {
24
+ /** Its clientMessageId. */
25
+ id: string;
26
+ message: SessionMessage;
27
+ /** Why it did not go. */
28
+ failed?: string;
29
+ }
22
30
  export interface SessionState {
23
31
  /** The agent is working, from the start of a run until it has settled. */
24
32
  working: boolean;
@@ -49,6 +57,10 @@ export interface SessionState {
49
57
  compacting?: 'manual' | 'threshold' | 'overflow';
50
58
  /** pi waits to retry a failed request of the model. */
51
59
  retry?: RetryState;
60
+ /** What an extension says the agent does while it works (pi's `setWorkingMessage`). */
61
+ workingMessage?: string;
62
+ /** Which of the last `messages` this client sent that the session does not have yet (SessionStore.send). */
63
+ outbox?: readonly OutboxMessage[];
52
64
  }
53
65
  export declare namespace SessionReducer {
54
66
  function initial(): SessionState;
@@ -57,7 +69,9 @@ export declare namespace SessionReducer {
57
69
  /**
58
70
  * The messages of `next`, with each that is the same as the one of `previous` at its place kept as it
59
71
  * was: a conversation read again after a reconnect has new objects, which a UI would all draw again.
72
+ * `offset`: where `next` starts in `previous` (the difference of their `start`), for a part of the
73
+ * conversation that begins elsewhere, such as one kept on the device that was cut shorter.
60
74
  */
61
- function keep(previous: readonly SessionMessage[], next: SessionMessage[]): SessionMessage[];
75
+ function keep(previous: readonly SessionMessage[], next: SessionMessage[], offset?: number): SessionMessage[];
62
76
  }
63
77
  //# sourceMappingURL=session-reducer.d.ts.map
@@ -26,7 +26,9 @@ var SessionReducer;
26
26
  case 'agent_start':
27
27
  return { ...state, working: true, runStart: state.messages.length };
28
28
  case 'agent_settled':
29
- return { ...state, working: false, retry: undefined };
29
+ return { ...state, working: false, retry: undefined, workingMessage: undefined };
30
+ case 'working_message':
31
+ return { ...state, workingMessage: event.message };
30
32
  case 'message_start':
31
33
  return { ...state, messages: [...state.messages, event.message] };
32
34
  case 'message_update': {
@@ -158,11 +160,13 @@ var SessionReducer;
158
160
  /**
159
161
  * The messages of `next`, with each that is the same as the one of `previous` at its place kept as it
160
162
  * was: a conversation read again after a reconnect has new objects, which a UI would all draw again.
163
+ * `offset`: where `next` starts in `previous` (the difference of their `start`), for a part of the
164
+ * conversation that begins elsewhere, such as one kept on the device that was cut shorter.
161
165
  */
162
- function keep(previous, next) {
163
- let same = previous.length === next.length;
166
+ function keep(previous, next, offset = 0) {
167
+ let same = offset === 0 && previous.length === next.length;
164
168
  const kept = next.map((message, index) => {
165
- const before = previous[index];
169
+ const before = previous[index + offset];
166
170
  if (before && before.role === message.role && before.timestamp === message.timestamp && JSON.stringify(before) === JSON.stringify(message)) {
167
171
  return before;
168
172
  }
@@ -1,12 +1,24 @@
1
1
  import { type RpcExtensionUIResponse, type TaAttachResult, type TaClientToolDefinition, type TaClientToolRequest, type TaClientToolResult, type TaEvent, type TaEventEnvelope, type TaPromptInput, type TaPromptReceipt, type TaSessionInfo } from '@celljs/ta-protocol';
2
- import { type SessionMessage, type SessionState } from './session-reducer';
3
- import type { TaConnection } from './ta-connection';
2
+ import { type OutboxMessage, type SessionMessage, type SessionState } from './session-reducer';
3
+ import { type TaConnection } from './ta-connection';
4
4
  type Listener = (state: SessionState) => void;
5
5
  interface Taken {
6
6
  state: SessionState;
7
7
  applied: TaEvent[];
8
8
  replaced: boolean;
9
9
  }
10
+ /** A message sent from this client that the session has not shown yet. */
11
+ interface Sent extends OutboxMessage {
12
+ text: string;
13
+ /** How it was sent, but its text and id: to send it again the same. */
14
+ input: Partial<TaPromptInput>;
15
+ /** The service took it: the conversation it gives from now on has it. */
16
+ accepted: boolean;
17
+ /** When the connection first could not take it: it waits for the next, shown as on its way, until `holdMs`. */
18
+ heldAt?: number;
19
+ }
20
+ /** How long a message the connection could not take waits for it, on its way, before it shows as failed. */
21
+ export declare const HOLD_MS = 60000;
10
22
  /**
11
23
  * A tool this client runs. Open the session with its `definition` in `clientTools`, and give the tool
12
24
  * to the store, which runs each call and sends the result. Its output is what the model reads; a
@@ -16,6 +28,10 @@ export interface ClientTool {
16
28
  definition: TaClientToolDefinition;
17
29
  run(input: unknown, request: TaClientToolRequest): Promise<string> | string;
18
30
  }
31
+ /** What a store uses of its connection: a TaConnection, or something that stands for one before there is one. */
32
+ export type SessionConnection = Pick<TaConnection, 'server' | 'onEvents' | 'onOpen'>;
33
+ /** What a store shows before it attaches: the conversation as a client kept it (its messages from `start`, and its tool calls). */
34
+ export type SessionSnapshot = Pick<SessionState, 'messages' | 'start' | 'tools'>;
19
35
  export interface SessionStoreOptions {
20
36
  /** The tools of the session this client runs. Other clients may run them too: the first result counts. */
21
37
  clientTools?: ClientTool[];
@@ -24,15 +40,27 @@ export interface SessionStoreOptions {
24
40
  * `loadEarlier` is called: a long conversation shows at once. None: all of it.
25
41
  */
26
42
  pageBytes?: number;
43
+ /**
44
+ * Shown from the start, before it attaches (and without a connection): the conversation as it was last
45
+ * seen. Attached, the messages of the session that are the same keep their objects, so that a UI draws
46
+ * again only what changed.
47
+ */
48
+ initial?: SessionSnapshot;
49
+ /** How long a message the user sent waits for a lost connection to come back (HOLD_MS). */
50
+ holdMs?: number;
27
51
  }
28
52
  /**
29
53
  * The state of one open session on a client: for any UI to render and subscribe to. It catches up by
30
54
  * itself after a reconnect, from the events it missed or, if those are gone, from the session.
31
55
  */
32
56
  export declare class SessionStore {
33
- protected readonly connection: TaConnection;
57
+ protected readonly connection: SessionConnection;
34
58
  readonly sessionId: string;
59
+ /** The session as the service told it. */
35
60
  protected current: SessionState;
61
+ /** `current` with the messages sent from here on their way: what UIs get. */
62
+ protected shown: SessionState;
63
+ protected sent: Sent[];
36
64
  protected lastSeq?: number;
37
65
  protected readonly listeners: Set<Listener>;
38
66
  protected readonly eventListeners: Set<(event: TaEvent) => void>;
@@ -48,7 +76,11 @@ export declare class SessionStore {
48
76
  protected readonly pageBytes?: number;
49
77
  /** The earlier messages on their way. */
50
78
  protected loadingEarlier?: Promise<void>;
51
- constructor(connection: TaConnection, sessionId: string, options?: SessionStoreOptions);
79
+ protected readonly holdMs: number;
80
+ protected holdTimer?: ReturnType<typeof setTimeout>;
81
+ /** The messages held that are being sent again now. */
82
+ protected readonly resending: Set<Sent>;
83
+ constructor(connection: SessionConnection, sessionId: string, options?: SessionStoreOptions);
52
84
  get state(): SessionState;
53
85
  /** Starts following the session. */
54
86
  attach(): Promise<TaSessionInfo>;
@@ -57,8 +89,49 @@ export declare class SessionStore {
57
89
  subscribe(listener: Listener): () => void;
58
90
  /** Each new event of the session, once the state has taken it in. */
59
91
  onEvent(listener: (event: TaEvent) => void): () => void;
60
- /** Sends a message with a new id; a resend after a lost connection must reuse the id. */
92
+ /**
93
+ * Sends a message with a new id; a resend after a lost connection must reuse the id. Sent while the
94
+ * agent is idle, it shows at once at the end of the conversation, with the agent at work, until the
95
+ * session has it (a command, which may add none, does not).
96
+ */
61
97
  prompt(message: string, input?: Partial<TaPromptInput>): Promise<TaPromptReceipt>;
98
+ /**
99
+ * As `prompt`, for what the user typed: a message that fails to go stays in the conversation, marked
100
+ * failed, to send again (`resend`) or take back (`discard`), and this resolves without a receipt. One
101
+ * the connection could not take is not failed: it stays on its way and goes once the store is attached
102
+ * again, as a chat app sends what was typed without network once it is back; only after `holdMs`
103
+ * without a connection does it show as failed.
104
+ */
105
+ send(message: string, input?: Partial<TaPromptInput>): Promise<TaPromptReceipt | undefined>;
106
+ /** Sends again a message that failed, with its id: one that reached the service after all runs once. */
107
+ resend(id: string): Promise<void>;
108
+ /**
109
+ * Takes on the messages that failed to go from another store of the same conversation (one that showed
110
+ * it before this one attached, without the computer), to send again from here.
111
+ */
112
+ carry(from: SessionStore): void;
113
+ /** Takes back a message that failed. */
114
+ discard(id: string): void;
115
+ protected deliver(message: string, input: Partial<TaPromptInput>, keep: boolean): Promise<TaPromptReceipt>;
116
+ /** Sends a message shown as sent, and settles it by the answer. */
117
+ protected go(sent: Sent, full: TaPromptInput, keep: boolean): Promise<TaPromptReceipt>;
118
+ protected add(input: TaPromptInput): Sent;
119
+ /** Keeps a message the connection could not take on its way, unless it waited `holdMs` already. */
120
+ protected hold(sent: Sent): boolean;
121
+ /** The messages held `holdMs` that are not going now show as failed. */
122
+ protected expireHeld(): void;
123
+ /** Attached again: the messages held go now, with their ids, so that one the service had after all runs once. */
124
+ protected sendHeld(): void;
125
+ protected fail(sent: Sent, error: unknown): void;
126
+ protected unsend(sent: Sent): void;
127
+ /** The message sent, once the session has a message of the user: the one of the same text, else the first. */
128
+ protected arrived(message: SessionMessage): void;
129
+ protected static textOf(message: SessionMessage): string | undefined;
130
+ /**
131
+ * `state` with the messages sent from here after it (`outbox` says which they are), and the agent at
132
+ * work for those on their way.
133
+ */
134
+ static withSent(state: SessionState, sent: readonly OutboxMessage[]): SessionState;
62
135
  /**
63
136
  * The service no longer has the session after a reconnect (it restarted, or closed the session while
64
137
  * idle): its file stays, to open again.
@@ -90,6 +163,8 @@ export declare class SessionStore {
90
163
  /** Once the state has the events: their listeners, and the conversation read again if it was replaced. */
91
164
  protected applied({ applied, replaced }: Taken): void;
92
165
  protected update(state: SessionState): void;
166
+ /** UIs get the state with the messages sent, when either changed. */
167
+ protected show(): void;
93
168
  protected runClientTools(state: SessionState): void;
94
169
  /**
95
170
  * Runs a call once, if this client takes it: every page of the user gets it. A result that could not be