@celljs/ta-client 0.0.0-stage → 4.5.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/README.md +19 -2
- package/esm/common/index.d.ts +3 -0
- package/esm/common/index.js +4 -0
- package/esm/common/index.js.map +1 -0
- package/esm/common/session-reducer.d.ts +27 -0
- package/esm/common/session-reducer.js +87 -0
- package/esm/common/session-reducer.js.map +1 -0
- package/esm/common/session-store.d.ts +31 -0
- package/esm/common/session-store.js +80 -0
- package/esm/common/session-store.js.map +1 -0
- package/esm/common/ta-connection.d.ts +54 -0
- package/esm/common/ta-connection.js +129 -0
- package/esm/common/ta-connection.js.map +1 -0
- package/esm/package.json +3 -0
- package/lib/common/index.d.ts +4 -0
- package/lib/common/index.d.ts.map +1 -0
- package/lib/common/index.js +20 -0
- package/lib/common/index.js.map +1 -0
- package/lib/common/session-reducer.d.ts +28 -0
- package/lib/common/session-reducer.d.ts.map +1 -0
- package/lib/common/session-reducer.js +90 -0
- package/lib/common/session-reducer.js.map +1 -0
- package/lib/common/session-reducer.spec.d.ts +2 -0
- package/lib/common/session-reducer.spec.d.ts.map +1 -0
- package/lib/common/session-reducer.spec.js +63 -0
- package/lib/common/session-reducer.spec.js.map +1 -0
- package/lib/common/session-store.d.ts +32 -0
- package/lib/common/session-store.d.ts.map +1 -0
- package/lib/common/session-store.js +84 -0
- package/lib/common/session-store.js.map +1 -0
- package/lib/common/ta-connection.d.ts +55 -0
- package/lib/common/ta-connection.d.ts.map +1 -0
- package/lib/common/ta-connection.js +134 -0
- package/lib/common/ta-connection.js.map +1 -0
- package/package.json +58 -4
- package/src/common/index.ts +3 -0
- package/src/common/session-reducer.spec.ts +70 -0
- package/src/common/session-reducer.ts +122 -0
- package/src/common/session-store.ts +99 -0
- package/src/common/ta-connection.ts +169 -0
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import type { RpcExtensionUIRequest, TaCommandResult, TaEvent } from '@celljs/ta-protocol';
|
|
2
|
+
|
|
3
|
+
export type SessionMessage = TaCommandResult<'get_messages'>['messages'][number];
|
|
4
|
+
|
|
5
|
+
export interface ToolRun {
|
|
6
|
+
toolName: string;
|
|
7
|
+
args: unknown;
|
|
8
|
+
/** The latest partial result while it runs, then the result. */
|
|
9
|
+
result?: unknown;
|
|
10
|
+
status: 'running' | 'done' | 'error';
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** What a UI shows of a session. */
|
|
14
|
+
export interface SessionState {
|
|
15
|
+
/** The agent is working, from the start of a run until it has settled. */
|
|
16
|
+
working: boolean;
|
|
17
|
+
messages: SessionMessage[];
|
|
18
|
+
/** By tool call id. */
|
|
19
|
+
tools: Record<string, ToolRun>;
|
|
20
|
+
/** Dialogs waiting for an answer. */
|
|
21
|
+
pendingUi: RpcExtensionUIRequest[];
|
|
22
|
+
/** What extensions show with `setStatus`. */
|
|
23
|
+
status: Record<string, string>;
|
|
24
|
+
closed: boolean;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
interface ContentBlock {
|
|
28
|
+
type: string;
|
|
29
|
+
[key: string]: unknown;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
type StreamDelta = { type: string; contentIndex?: number; delta?: string; id?: string; toolName?: string };
|
|
33
|
+
|
|
34
|
+
export namespace SessionReducer {
|
|
35
|
+
const DIALOGS = new Set(['select', 'confirm', 'input', 'editor']);
|
|
36
|
+
|
|
37
|
+
export function initial(): SessionState {
|
|
38
|
+
return { working: false, messages: [], tools: {}, pendingUi: [], status: {}, closed: false };
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** The next state; the previous one stays valid, so that UIs can compare by identity. */
|
|
42
|
+
export function reduce(state: SessionState, event: TaEvent): SessionState {
|
|
43
|
+
switch (event.type) {
|
|
44
|
+
case 'agent_start':
|
|
45
|
+
return { ...state, working: true };
|
|
46
|
+
case 'agent_settled':
|
|
47
|
+
return { ...state, working: false };
|
|
48
|
+
case 'message_start':
|
|
49
|
+
return { ...state, messages: [...state.messages, event.message] };
|
|
50
|
+
case 'message_update':
|
|
51
|
+
return withLastMessage(state, message => applyDelta(message, event.assistantMessageEvent as StreamDelta));
|
|
52
|
+
case 'message_end':
|
|
53
|
+
return withLastMessage(state, () => event.message);
|
|
54
|
+
case 'tool_execution_start':
|
|
55
|
+
return withTool(state, event.toolCallId, { toolName: event.toolName, args: event.args, status: 'running' });
|
|
56
|
+
case 'tool_execution_update':
|
|
57
|
+
return withTool(state, event.toolCallId, { ...state.tools[event.toolCallId], result: event.partialResult });
|
|
58
|
+
case 'tool_execution_end':
|
|
59
|
+
return withTool(state, event.toolCallId, { ...state.tools[event.toolCallId], result: event.result, status: event.isError ? 'error' : 'done' });
|
|
60
|
+
case 'extension_ui_request':
|
|
61
|
+
return applyUiRequest(state, event);
|
|
62
|
+
case 'ui_request_resolved':
|
|
63
|
+
return { ...state, pendingUi: state.pendingUi.filter(request => request.id !== event.id) };
|
|
64
|
+
case 'session_closed':
|
|
65
|
+
return { ...state, closed: true, working: false, pendingUi: [] };
|
|
66
|
+
default:
|
|
67
|
+
return state;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function withLastMessage(state: SessionState, update: (message: SessionMessage) => SessionMessage): SessionState {
|
|
72
|
+
if (!state.messages.length) {
|
|
73
|
+
return state;
|
|
74
|
+
}
|
|
75
|
+
const last = state.messages.length - 1;
|
|
76
|
+
return { ...state, messages: [...state.messages.slice(0, last), update(state.messages[last])] };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function withTool(state: SessionState, toolCallId: string, run: ToolRun): SessionState {
|
|
80
|
+
return { ...state, tools: { ...state.tools, [toolCallId]: run } };
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function applyUiRequest(state: SessionState, request: RpcExtensionUIRequest): SessionState {
|
|
84
|
+
if (DIALOGS.has(request.method)) {
|
|
85
|
+
return { ...state, pendingUi: [...state.pendingUi, request] };
|
|
86
|
+
}
|
|
87
|
+
if (request.method === 'setStatus') {
|
|
88
|
+
const { [request.statusKey]: _old, ...status } = state.status;
|
|
89
|
+
return { ...state, status: request.statusText === undefined ? status : { ...status, [request.statusKey]: request.statusText } };
|
|
90
|
+
}
|
|
91
|
+
return state;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function applyDelta(message: SessionMessage, delta: StreamDelta): SessionMessage {
|
|
95
|
+
if (delta.contentIndex === undefined || message.role !== 'assistant') {
|
|
96
|
+
return message;
|
|
97
|
+
}
|
|
98
|
+
const content = [...(message.content as unknown as ContentBlock[])];
|
|
99
|
+
const block = nextBlock(content[delta.contentIndex], delta);
|
|
100
|
+
if (block) {
|
|
101
|
+
content[delta.contentIndex] = block;
|
|
102
|
+
}
|
|
103
|
+
return { ...message, content } as unknown as SessionMessage;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function nextBlock(block: ContentBlock | undefined, delta: StreamDelta): ContentBlock | undefined {
|
|
107
|
+
switch (delta.type) {
|
|
108
|
+
case 'text_start':
|
|
109
|
+
return { type: 'text', text: '' };
|
|
110
|
+
case 'thinking_start':
|
|
111
|
+
return { type: 'thinking', thinking: '' };
|
|
112
|
+
case 'toolcall_start':
|
|
113
|
+
return { type: 'toolCall', id: delta.id, name: delta.toolName, arguments: {} };
|
|
114
|
+
case 'text_delta':
|
|
115
|
+
return block && { ...block, text: `${block.text ?? ''}${delta.delta}` };
|
|
116
|
+
case 'thinking_delta':
|
|
117
|
+
return block && { ...block, thinking: `${block.thinking ?? ''}${delta.delta}` };
|
|
118
|
+
default:
|
|
119
|
+
return undefined;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import type { RpcExtensionUIResponse, TaAttachResult, TaEventEnvelope, TaPromptInput, TaPromptReceipt, TaSessionInfo } from '@celljs/ta-protocol';
|
|
2
|
+
import { SessionReducer, type SessionState } from './session-reducer';
|
|
3
|
+
import type { TaConnection } from './ta-connection';
|
|
4
|
+
|
|
5
|
+
type Listener = (state: SessionState) => void;
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* The state of one open session on a client: for any UI to render and subscribe to. It catches up by
|
|
9
|
+
* itself after a reconnect, from the events it missed or, if those are gone, from the session.
|
|
10
|
+
*/
|
|
11
|
+
export class SessionStore {
|
|
12
|
+
protected current = SessionReducer.initial();
|
|
13
|
+
protected lastSeq?: number;
|
|
14
|
+
protected readonly listeners = new Set<Listener>();
|
|
15
|
+
protected readonly stop: (() => void)[] = [];
|
|
16
|
+
|
|
17
|
+
constructor(
|
|
18
|
+
protected readonly connection: TaConnection,
|
|
19
|
+
readonly sessionId: string,
|
|
20
|
+
) {}
|
|
21
|
+
|
|
22
|
+
get state(): SessionState {
|
|
23
|
+
return this.current;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Starts following the session. */
|
|
27
|
+
async attach(): Promise<TaSessionInfo> {
|
|
28
|
+
this.stop.push(
|
|
29
|
+
this.connection.onEvents(events => this.apply(events)),
|
|
30
|
+
this.connection.onOpen(() => void this.attachAgain()),
|
|
31
|
+
);
|
|
32
|
+
return (await this.attachAgain()).info;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Stops following it. The session goes on. */
|
|
36
|
+
async detach(): Promise<void> {
|
|
37
|
+
for (const stop of this.stop.splice(0)) {
|
|
38
|
+
stop();
|
|
39
|
+
}
|
|
40
|
+
await this.connection.server.detach(this.sessionId);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
subscribe(listener: Listener): () => void {
|
|
44
|
+
this.listeners.add(listener);
|
|
45
|
+
return () => this.listeners.delete(listener);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Sends a message with a new id; a resend after a lost connection must reuse the id. */
|
|
49
|
+
prompt(message: string, input: Partial<TaPromptInput> = {}): Promise<TaPromptReceipt> {
|
|
50
|
+
return this.connection.server.prompt(this.sessionId, { clientMessageId: crypto.randomUUID(), ...input, message });
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
respondUi(response: RpcExtensionUIResponse): Promise<boolean> {
|
|
54
|
+
return this.connection.server.respondUi(this.sessionId, response);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
protected async attachAgain(): Promise<TaAttachResult> {
|
|
58
|
+
const result = await this.connection.server.attach(this.sessionId, this.lastSeq);
|
|
59
|
+
if (this.lastSeq === undefined || result.gap) {
|
|
60
|
+
await this.reload();
|
|
61
|
+
this.lastSeq = result.lastSeq;
|
|
62
|
+
}
|
|
63
|
+
this.apply(result.events);
|
|
64
|
+
this.update({ ...this.current, pendingUi: result.pendingUi, working: result.info.isStreaming });
|
|
65
|
+
return result;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
protected async reload(): Promise<void> {
|
|
69
|
+
const { messages } = await this.connection.server.getMessages(this.sessionId);
|
|
70
|
+
this.update({ ...this.current, messages, tools: {} });
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
protected apply(events: TaEventEnvelope[]): void {
|
|
74
|
+
let state = this.current;
|
|
75
|
+
let replaced = false;
|
|
76
|
+
for (const { sessionId, seq, event } of events) {
|
|
77
|
+
if (sessionId !== this.sessionId || (this.lastSeq !== undefined && seq <= this.lastSeq)) {
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
this.lastSeq = seq;
|
|
81
|
+
state = SessionReducer.reduce(state, event);
|
|
82
|
+
replaced ||= event.type === 'session_replaced';
|
|
83
|
+
}
|
|
84
|
+
// One notification per batch: a UI renders once however many deltas arrived.
|
|
85
|
+
this.update(state);
|
|
86
|
+
if (replaced) {
|
|
87
|
+
void this.reload();
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
protected update(state: SessionState): void {
|
|
92
|
+
if (state !== this.current) {
|
|
93
|
+
this.current = state;
|
|
94
|
+
for (const listener of this.listeners) {
|
|
95
|
+
listener(state);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
import { TA_CLIENT_SERVICE, TA_SERVER_SERVICE, type TaErrorCode, type TaErrorData, type TaEventEnvelope, type TaServer } from '@celljs/ta-protocol';
|
|
2
|
+
|
|
3
|
+
/** A failed call. `code` is set for failures the server names. */
|
|
4
|
+
export class TaRemoteError extends Error {
|
|
5
|
+
constructor(
|
|
6
|
+
message: string,
|
|
7
|
+
readonly code?: TaErrorCode,
|
|
8
|
+
readonly hint?: string,
|
|
9
|
+
) {
|
|
10
|
+
super(message);
|
|
11
|
+
this.name = 'TaRemoteError';
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export interface TaConnectionOptions {
|
|
16
|
+
/** The `url` of serve.json. */
|
|
17
|
+
url: string;
|
|
18
|
+
/** The `token` of serve.json. */
|
|
19
|
+
token: string;
|
|
20
|
+
/** First wait before reconnecting; it doubles up to `maxReconnectDelayMs`. Default 250. */
|
|
21
|
+
reconnectDelayMs?: number;
|
|
22
|
+
/** Default 10000. */
|
|
23
|
+
maxReconnectDelayMs?: number;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
interface PendingCall {
|
|
27
|
+
resolve(result: unknown): void;
|
|
28
|
+
reject(error: Error): void;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
interface RpcMessage {
|
|
32
|
+
id?: number | string | null;
|
|
33
|
+
method?: string;
|
|
34
|
+
params?: unknown[];
|
|
35
|
+
result?: unknown;
|
|
36
|
+
error?: { message: string; data?: { data?: TaErrorData } };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
type EventsListener = (events: TaEventEnvelope[]) => void;
|
|
40
|
+
type OpenListener = () => void;
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* A connection to `ta serve` on the `WebSocket` of the platform, with no other dependency, so that it
|
|
44
|
+
* fits a browser, Electron or a mobile app. It reconnects until closed; `onOpen` runs each time, for
|
|
45
|
+
* attaching again ({@link SessionStore} does).
|
|
46
|
+
*/
|
|
47
|
+
export class TaConnection {
|
|
48
|
+
/** Calls fail when the connection is down; they are not queued, because only the caller knows whether to resend. */
|
|
49
|
+
readonly server: TaServer = new Proxy({} as TaServer, {
|
|
50
|
+
get:
|
|
51
|
+
(_target, method: string) =>
|
|
52
|
+
(...params: unknown[]) =>
|
|
53
|
+
this.call(method, params),
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
protected socket?: WebSocket;
|
|
57
|
+
protected closed = false;
|
|
58
|
+
protected attempts = 0;
|
|
59
|
+
protected reconnectTimer?: ReturnType<typeof setTimeout>;
|
|
60
|
+
protected nextId = 0;
|
|
61
|
+
protected readonly pending = new Map<number, PendingCall>();
|
|
62
|
+
protected readonly eventListeners = new Set<EventsListener>();
|
|
63
|
+
protected readonly openListeners = new Set<OpenListener>();
|
|
64
|
+
|
|
65
|
+
constructor(protected readonly options: TaConnectionOptions) {}
|
|
66
|
+
|
|
67
|
+
/** Resolves when the first connection is open, or rejects if it cannot be made; later losses reconnect. */
|
|
68
|
+
connect(): Promise<void> {
|
|
69
|
+
return new Promise((resolve, reject) => this.open(resolve, reject));
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
close(): void {
|
|
73
|
+
this.closed = true;
|
|
74
|
+
clearTimeout(this.reconnectTimer);
|
|
75
|
+
this.socket?.close();
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
onEvents(listener: EventsListener): () => void {
|
|
79
|
+
this.eventListeners.add(listener);
|
|
80
|
+
return () => this.eventListeners.delete(listener);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
onOpen(listener: OpenListener): () => void {
|
|
84
|
+
this.openListeners.add(listener);
|
|
85
|
+
return () => this.openListeners.delete(listener);
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** With `resolve` and `reject`: the first connection, whose failure is the caller's to handle. */
|
|
89
|
+
protected open(resolve?: () => void, reject?: (error: Error) => void): void {
|
|
90
|
+
let opened = false;
|
|
91
|
+
const url = new URL(this.options.url);
|
|
92
|
+
url.searchParams.set('token', this.options.token);
|
|
93
|
+
const socket = new WebSocket(url);
|
|
94
|
+
this.socket = socket;
|
|
95
|
+
socket.onopen = () => {
|
|
96
|
+
opened = true;
|
|
97
|
+
this.attempts = 0;
|
|
98
|
+
resolve?.();
|
|
99
|
+
for (const listener of this.openListeners) {
|
|
100
|
+
listener();
|
|
101
|
+
}
|
|
102
|
+
};
|
|
103
|
+
socket.onmessage = message => this.receive(String(message.data));
|
|
104
|
+
socket.onclose = () => {
|
|
105
|
+
this.failPending();
|
|
106
|
+
if (reject && !opened) {
|
|
107
|
+
reject(new TaRemoteError(`Cannot connect to ${this.options.url}.`));
|
|
108
|
+
} else {
|
|
109
|
+
this.scheduleReconnect();
|
|
110
|
+
}
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
protected scheduleReconnect(): void {
|
|
115
|
+
if (this.closed) {
|
|
116
|
+
return;
|
|
117
|
+
}
|
|
118
|
+
const { reconnectDelayMs = 250, maxReconnectDelayMs = 10000 } = this.options;
|
|
119
|
+
const delay = Math.min(reconnectDelayMs * 2 ** this.attempts++, maxReconnectDelayMs);
|
|
120
|
+
this.reconnectTimer = setTimeout(() => this.open(), delay);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
protected failPending(): void {
|
|
124
|
+
for (const call of this.pending.values()) {
|
|
125
|
+
call.reject(new TaRemoteError('The connection to ta serve was lost.'));
|
|
126
|
+
}
|
|
127
|
+
this.pending.clear();
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
protected call(method: string, params: unknown[]): Promise<unknown> {
|
|
131
|
+
const socket = this.socket;
|
|
132
|
+
if (socket?.readyState !== WebSocket.OPEN) {
|
|
133
|
+
return Promise.reject(new TaRemoteError('Not connected to ta serve.'));
|
|
134
|
+
}
|
|
135
|
+
const id = ++this.nextId;
|
|
136
|
+
// JSON has no undefined: a left-out optional argument must not arrive as null.
|
|
137
|
+
let length = params.length;
|
|
138
|
+
while (length > 0 && params[length - 1] === undefined) {
|
|
139
|
+
length--;
|
|
140
|
+
}
|
|
141
|
+
return new Promise((resolve, reject) => {
|
|
142
|
+
this.pending.set(id, { resolve, reject });
|
|
143
|
+
socket.send(JSON.stringify({ jsonrpc: '2.0', id, method: `${TA_SERVER_SERVICE}/${method}`, params: params.slice(0, length) }));
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
protected receive(text: string): void {
|
|
148
|
+
const message = JSON.parse(text) as RpcMessage;
|
|
149
|
+
if (message.method === `${TA_CLIENT_SERVICE}/onEvents`) {
|
|
150
|
+
const [events] = message.params as [TaEventEnvelope[]];
|
|
151
|
+
for (const listener of this.eventListeners) {
|
|
152
|
+
listener(events);
|
|
153
|
+
}
|
|
154
|
+
this.socket?.send(JSON.stringify({ jsonrpc: '2.0', id: message.id, result: null }));
|
|
155
|
+
return;
|
|
156
|
+
}
|
|
157
|
+
const call = this.pending.get(message.id as number);
|
|
158
|
+
if (!call) {
|
|
159
|
+
return;
|
|
160
|
+
}
|
|
161
|
+
this.pending.delete(message.id as number);
|
|
162
|
+
if (message.error) {
|
|
163
|
+
const data = message.error.data?.data;
|
|
164
|
+
call.reject(new TaRemoteError(message.error.message, data?.code, data?.hint));
|
|
165
|
+
} else {
|
|
166
|
+
call.resolve(message.result);
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|