@celljs/ta-protocol 4.5.1 → 4.6.1

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.
Files changed (73) hide show
  1. package/README.md +6 -5
  2. package/esm/common/auth-protocol.d.ts +89 -0
  3. package/esm/common/auth-protocol.js +3 -0
  4. package/esm/common/auth-protocol.js.map +1 -0
  5. package/esm/common/index.d.ts +6 -0
  6. package/esm/common/index.js +6 -0
  7. package/esm/common/index.js.map +1 -1
  8. package/esm/common/package-protocol.d.ts +92 -0
  9. package/esm/common/package-protocol.js +3 -0
  10. package/esm/common/package-protocol.js.map +1 -0
  11. package/esm/common/pi-types.d.ts +1 -0
  12. package/esm/common/relay-protocol.d.ts +28 -0
  13. package/esm/common/relay-protocol.js +3 -0
  14. package/esm/common/relay-protocol.js.map +1 -0
  15. package/esm/common/settings-protocol.d.ts +42 -0
  16. package/esm/common/settings-protocol.js +22 -0
  17. package/esm/common/settings-protocol.js.map +1 -0
  18. package/esm/common/ta-extension-host.d.ts +44 -0
  19. package/esm/common/ta-extension-host.js +8 -0
  20. package/esm/common/ta-extension-host.js.map +1 -0
  21. package/esm/common/ta-protocol.d.ts +110 -8
  22. package/esm/common/ta-protocol.js +21 -0
  23. package/esm/common/ta-protocol.js.map +1 -1
  24. package/esm/common/workspace-protocol.d.ts +91 -0
  25. package/esm/common/workspace-protocol.js +7 -0
  26. package/esm/common/workspace-protocol.js.map +1 -0
  27. package/lib/common/auth-protocol.d.ts +90 -0
  28. package/lib/common/auth-protocol.d.ts.map +1 -0
  29. package/lib/common/auth-protocol.js +6 -0
  30. package/lib/common/auth-protocol.js.map +1 -0
  31. package/lib/common/index.d.ts +6 -0
  32. package/lib/common/index.d.ts.map +1 -1
  33. package/lib/common/index.js +6 -0
  34. package/lib/common/index.js.map +1 -1
  35. package/lib/common/package-protocol.d.ts +93 -0
  36. package/lib/common/package-protocol.d.ts.map +1 -0
  37. package/lib/common/package-protocol.js +6 -0
  38. package/lib/common/package-protocol.js.map +1 -0
  39. package/lib/common/pi-types.d.ts +1 -0
  40. package/lib/common/pi-types.d.ts.map +1 -1
  41. package/lib/common/relay-protocol.d.ts +29 -0
  42. package/lib/common/relay-protocol.d.ts.map +1 -0
  43. package/lib/common/relay-protocol.js +6 -0
  44. package/lib/common/relay-protocol.js.map +1 -0
  45. package/lib/common/settings-protocol.d.ts +43 -0
  46. package/lib/common/settings-protocol.d.ts.map +1 -0
  47. package/lib/common/settings-protocol.js +25 -0
  48. package/lib/common/settings-protocol.js.map +1 -0
  49. package/lib/common/ta-extension-host.d.ts +45 -0
  50. package/lib/common/ta-extension-host.d.ts.map +1 -0
  51. package/lib/common/ta-extension-host.js +11 -0
  52. package/lib/common/ta-extension-host.js.map +1 -0
  53. package/lib/common/ta-protocol.d.ts +110 -8
  54. package/lib/common/ta-protocol.d.ts.map +1 -1
  55. package/lib/common/ta-protocol.js +22 -1
  56. package/lib/common/ta-protocol.js.map +1 -1
  57. package/lib/common/ta-protocol.spec.js +21 -0
  58. package/lib/common/ta-protocol.spec.js.map +1 -1
  59. package/lib/common/workspace-protocol.d.ts +92 -0
  60. package/lib/common/workspace-protocol.d.ts.map +1 -0
  61. package/lib/common/workspace-protocol.js +10 -0
  62. package/lib/common/workspace-protocol.js.map +1 -0
  63. package/package.json +1 -1
  64. package/src/common/auth-protocol.ts +56 -0
  65. package/src/common/index.ts +6 -0
  66. package/src/common/package-protocol.ts +99 -0
  67. package/src/common/pi-types.ts +1 -0
  68. package/src/common/relay-protocol.ts +28 -0
  69. package/src/common/settings-protocol.ts +66 -0
  70. package/src/common/ta-extension-host.ts +52 -0
  71. package/src/common/ta-protocol.spec.ts +30 -1
  72. package/src/common/ta-protocol.ts +123 -7
  73. package/src/common/workspace-protocol.ts +102 -0
@@ -1,4 +1,5 @@
1
- import type { ImageContent, JsonAgentSessionEvent, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcResponse, ThinkingLevel } from './pi-types';
1
+ import type { TaAuthEvent } from './auth-protocol';
2
+ import type { ImageContent, JsonAgentSessionEvent, RpcCommand, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcResponse, ThinkingLevel } from './pi-types';
2
3
 
3
4
  export const TaServer = Symbol('TaServer');
4
5
  export const TaClient = Symbol('TaClient');
@@ -18,6 +19,17 @@ export interface TaServeInfo {
18
19
  pid: number;
19
20
  }
20
21
 
22
+ /** What a client needs to know of the server before it opens a session. */
23
+ export interface TaServerInfo {
24
+ /** The version of ta. */
25
+ version: string;
26
+ /**
27
+ * Where a client opens a session when the user names no directory: the one set with
28
+ * `setWorkingDirectory`, else the working directory of `ta serve`, or of its execution environment.
29
+ */
30
+ cwd: string;
31
+ }
32
+
21
33
  /** The stable `code` of each failure of a {@link TaServer} call. */
22
34
  export const TaErrorCode = {
23
35
  SESSION_NOT_FOUND: 'CELL_TA_SESSION_NOT_FOUND',
@@ -27,6 +39,10 @@ export const TaErrorCode = {
27
39
  MODEL_NOT_FOUND: 'CELL_TA_MODEL_NOT_FOUND',
28
40
  INVALID_ARGUMENT: 'CELL_TA_INVALID_ARGUMENT',
29
41
  COMMAND_FAILED: 'CELL_TA_COMMAND_FAILED',
42
+ /** No provider of models is signed in for the model, or there is no model: sign in (TaAuthServer) first. */
43
+ NOT_SIGNED_IN: 'CELL_TA_NOT_SIGNED_IN',
44
+ /** Raised by the client, not the server: the call could not reach ta serve, or its answer was lost with the connection. */
45
+ CONNECTION_LOST: 'CELL_TA_CONNECTION_LOST',
30
46
  } as const;
31
47
  export type TaErrorCode = (typeof TaErrorCode)[keyof typeof TaErrorCode];
32
48
 
@@ -42,13 +58,35 @@ export interface TaErrorData {
42
58
  /** A command name of pi's RPC mode (`get_state`, `follow_up`, ...). */
43
59
  export type TaCommand = Extract<RpcResponse, { success: true }>['command'];
44
60
 
61
+ /** The answer to `forkToFile`. */
62
+ export interface TaForkFileResult {
63
+ /** The new conversation; none when nothing comes before the message: then a new conversation starts. */
64
+ sessionFile?: string;
65
+ /** The message of the user left out (`before`), for the box of the new conversation. */
66
+ text?: string;
67
+ }
68
+
69
+ /** The answer to `navigateTree`, which pi's RPC mode does not have. */
70
+ export interface TaNavigateResult {
71
+ cancelled: boolean;
72
+ editorText?: string;
73
+ }
74
+
75
+ /** `get_state` → `getState`. */
76
+ type CamelCase<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
77
+
78
+ /** The method of TaServer for each command of pi's RPC mode: TaServer has one for each (see its spec). */
79
+ export type PiCommandMethod = CamelCase<RpcCommand['type']>;
80
+
45
81
  /** What pi's RPC mode answers to a command. */
46
82
  export type TaCommandResult<C extends TaCommand> = Extract<RpcResponse, { command: C; success: true }> extends { data: infer D } ? D : undefined;
47
83
 
84
+ /** A tool the client runs: the model calls it like any other tool, the server asks the client for the result. */
48
85
  export interface TaClientToolDefinition {
86
+ /** Letters, digits, `_` and `-`, starting with a letter; best not the name of another tool of the session. */
49
87
  name: string;
50
88
  description: string;
51
- /** JSON schema of the arguments. */
89
+ /** JSON schema of the arguments, an object schema. */
52
90
  parameters: Record<string, unknown>;
53
91
  }
54
92
 
@@ -62,6 +100,10 @@ export interface TaOpenSessionOptions {
62
100
  thinkingLevel?: ThinkingLevel;
63
101
  /** Tools the client runs; fixed when the session opens, so the tool list stays stable for prompt caching. */
64
102
  clientTools?: TaClientToolDefinition[];
103
+ /** Added to the system prompt, as pi's `--append-system-prompt`: a role the client gives the agent. */
104
+ appendSystemPrompt?: string;
105
+ /** Sessions a package opens for its own work (the name of the package): clients list them apart, folded. */
106
+ group?: string;
65
107
  }
66
108
 
67
109
  export interface TaSessionInfo {
@@ -72,6 +114,8 @@ export interface TaSessionInfo {
72
114
  cwd: string;
73
115
  sessionFile?: string;
74
116
  sessionName?: string;
117
+ /** The first line of the first message of the user, which a list shows when the session has no name. */
118
+ firstMessage?: string;
75
119
  /** `<provider>/<model id>`. */
76
120
  model?: string;
77
121
  isStreaming: boolean;
@@ -79,9 +123,14 @@ export interface TaSessionInfo {
79
123
  /** Number of clients attached. */
80
124
  attached: number;
81
125
  createdAt: number;
126
+ /** When the last message came; `createdAt` before the first. */
127
+ updatedAt: number;
128
+ /** TaOpenSessionOptions.group. */
129
+ group?: string;
82
130
  }
83
131
 
84
132
  export interface TaPromptInput {
133
+ /** May start with a block of context for the model, which clients do not show: see {@link TaMessageContext}. */
85
134
  message: string;
86
135
  images?: ImageContent[];
87
136
  /** Chosen by the client, unique per message: sending the same one again does not run it again. */
@@ -90,6 +139,23 @@ export interface TaPromptInput {
90
139
  streamingBehavior?: 'steer' | 'followUp';
91
140
  }
92
141
 
142
+ /**
143
+ * A message of the user may start with a `<context>` block: what the model reads besides the message
144
+ * (where it is said, who is there, what was said before), which a client leaves out when it shows it.
145
+ */
146
+ export namespace TaMessageContext {
147
+ const BLOCK = /^<context>\n?[\s\S]*?\n?<\/context>\n?/;
148
+
149
+ export function wrap(context: string, message: string): string {
150
+ return `<context>\n${context}\n</context>\n${message}`;
151
+ }
152
+
153
+ /** The message without its context: what the user sees of it. */
154
+ export function strip(message: string): string {
155
+ return message.replace(BLOCK, '');
156
+ }
157
+ }
158
+
93
159
  /**
94
160
  * The server has taken the message; it says nothing about the run. A run is finished at the
95
161
  * `agent_settled` event, when its history is on disk.
@@ -114,7 +180,7 @@ export interface TaExtensionError {
114
180
  error: string;
115
181
  }
116
182
 
117
- /** The open session now shows another conversation (`newSession`, `switchSession`, `fork`, `clone`): read it again. */
183
+ /** The open session now shows another conversation (`newSession`, `switchSession`, `fork`, `clone`, `navigateTree`): read it again. */
118
184
  export interface TaSessionReplaced {
119
185
  type: 'session_replaced';
120
186
  info: TaSessionInfo;
@@ -125,20 +191,31 @@ export interface TaSessionClosed {
125
191
  type: 'session_closed';
126
192
  }
127
193
 
128
- /** The model called a tool of `clientTools`: answer with `respondClientTool`. */
194
+ /**
195
+ * The model called a tool of `clientTools`: a client that runs it answers with `respondClientTool`.
196
+ * It goes to every attached client; the first answer counts, and `client_tool_resolved` tells the others.
197
+ */
129
198
  export interface TaClientToolRequest {
130
199
  type: 'client_tool_request';
200
+ /** The id of the tool call. */
131
201
  id: string;
132
202
  toolName: string;
133
203
  input: unknown;
134
204
  }
135
205
 
206
+ /** A call of a client tool was answered, or ended because the run was aborted or the session closed. */
207
+ export interface TaClientToolResolved {
208
+ type: 'client_tool_resolved';
209
+ id: string;
210
+ }
211
+
136
212
  export type TaEvent =
137
213
  | JsonAgentSessionEvent
138
214
  | RpcExtensionUIRequest
139
215
  | TaUiRequestResolved
140
216
  | TaExtensionError
141
217
  | TaClientToolRequest
218
+ | TaClientToolResolved
142
219
  | TaSessionReplaced
143
220
  | TaSessionClosed;
144
221
 
@@ -155,6 +232,8 @@ export interface TaAttachResult {
155
232
  events: TaEventEnvelope[];
156
233
  /** The dialogs still waiting for an answer. */
157
234
  pendingUi: RpcExtensionUIRequest[];
235
+ /** The calls of client tools still waiting for a result. */
236
+ pendingClientTools: TaClientToolRequest[];
158
237
  /** Seq of the last event of the session. */
159
238
  lastSeq: number;
160
239
  /** Some events after `afterSeq` are gone: read the conversation again with `getMessages`. */
@@ -162,16 +241,27 @@ export interface TaAttachResult {
162
241
  }
163
242
 
164
243
  export interface TaClientToolResult {
244
+ /** The `id` of the request. */
165
245
  id: string;
246
+ /** What the model reads. */
166
247
  output: string;
248
+ /** The tool failed: `output` says why. */
167
249
  isError?: boolean;
168
250
  }
169
251
 
170
252
  /**
171
- * `ta serve`, over JSON-RPC 2.0 on a WebSocket. Besides opening, attaching and answering, each method
172
- * is the command of pi's RPC mode with the same name in camelCase, on the open session `sessionId`.
253
+ * The sessions of `ta serve`, over JSON-RPC 2.0 on a WebSocket. Besides opening, attaching and answering,
254
+ * each method is the command of pi's RPC mode with the same name in camelCase, on the open session
255
+ * `sessionId` (see PiCommandMethod). The same WebSocket carries the other services of ta serve, each
256
+ * under its own name: TaWorkspaceServer, TaTerminalServer, TaSettingsServer and TaPackageServer.
173
257
  */
174
258
  export interface TaServer {
259
+ getServerInfo(): Promise<TaServerInfo>;
260
+ /**
261
+ * Makes `cwd` the working directory of the server (TaServerInfo.cwd), for every client, and across
262
+ * restarts: where conversations open when the user names no directory. Sessions already open stay where they are.
263
+ */
264
+ setWorkingDirectory(cwd: string): Promise<TaServerInfo>;
175
265
  openSession(options: TaOpenSessionOptions): Promise<TaSessionInfo>;
176
266
  closeSession(sessionId: string): Promise<void>;
177
267
  listSessions(): Promise<TaSessionInfo[]>;
@@ -207,18 +297,44 @@ export interface TaServer {
207
297
  getSessionStats(sessionId: string): Promise<TaCommandResult<'get_session_stats'>>;
208
298
  exportHtml(sessionId: string, outputPath?: string): Promise<TaCommandResult<'export_html'>>;
209
299
  switchSession(sessionId: string, sessionPath: string): Promise<TaCommandResult<'switch_session'>>;
210
- fork(sessionId: string, entryId: string): Promise<TaCommandResult<'fork'>>;
300
+ /**
301
+ * A new conversation from an entry, as pi's `/fork`: `before` (the default) a message of the user, which
302
+ * it leaves out and gives back as `text`; `at` any entry, which it keeps.
303
+ */
304
+ fork(sessionId: string, entryId: string, position?: 'before' | 'at'): Promise<TaCommandResult<'fork'>>;
305
+ /**
306
+ * The new conversation of `fork` in a file of its own, with pi's `createBranchedSession`; the session
307
+ * stays where it is. Open the file with `openSession` to go on with it.
308
+ */
309
+ forkToFile(sessionId: string, entryId: string, position?: 'before' | 'at'): Promise<TaForkFileResult>;
211
310
  clone(sessionId: string): Promise<TaCommandResult<'clone'>>;
212
311
  getForkMessages(sessionId: string): Promise<TaCommandResult<'get_fork_messages'>>;
213
312
  getEntries(sessionId: string, since?: string): Promise<TaCommandResult<'get_entries'>>;
214
313
  getTree(sessionId: string): Promise<TaCommandResult<'get_tree'>>;
314
+ /**
315
+ * Goes to an entry in the same conversation, as pi's `/tree`: the branch left stays in the tree. To a
316
+ * message of the user, it goes to what came before and gives the message back as `editorText`.
317
+ */
318
+ navigateTree(sessionId: string, targetId: string): Promise<TaNavigateResult>;
215
319
  getLastAssistantText(sessionId: string): Promise<TaCommandResult<'get_last_assistant_text'>>;
216
320
  setSessionName(sessionId: string, name: string): Promise<void>;
217
321
  getMessages(sessionId: string): Promise<TaCommandResult<'get_messages'>>;
218
322
  getCommands(sessionId: string): Promise<TaCommandResult<'get_commands'>>;
323
+ /** Loads extensions, skills, prompts and themes again, as pi's `/reload` does. */
324
+ reload(sessionId: string): Promise<void>;
219
325
  }
220
326
 
221
327
  /** What a client implements. Events come in batches: one message per frame, however fast the model streams. */
222
328
  export interface TaClient {
223
329
  onEvents(events: TaEventEnvelope[]): Promise<void>;
330
+ /** Output of a terminal of this connection; with `exitCode`, the terminal has ended. */
331
+ onTerminalData(terminalId: string, data: string, exitCode?: number): Promise<void>;
332
+ /**
333
+ * Keys of the data of a package (setExtensionData) that changed, by this client or another, or by the
334
+ * package on the server; with `cwd`, keys of that directory. It comes for the data this connection
335
+ * read, at most every few hundred milliseconds, with the keys of that time together.
336
+ */
337
+ onExtensionData(name: string, keys: string[], cwd?: string): Promise<void>;
338
+ /** What happens during a sign-in this connection started (TaAuthServer.login). */
339
+ onAuthEvent(loginId: string, event: TaAuthEvent): Promise<void>;
224
340
  }
@@ -0,0 +1,102 @@
1
+ import type { TaServer } from './ta-protocol';
2
+
3
+ /** Where the page loads the bytes of workspace files from: see {@link TaWorkspaceServer.fileUrl}. */
4
+ export const TA_FILES_PATH = '/api/files';
5
+
6
+ export const TaWorkspaceServer = Symbol('TaWorkspaceServer');
7
+ export const TA_WORKSPACE_SERVICE = 'TaWorkspaceServer';
8
+ export const TaTerminalServer = Symbol('TaTerminalServer');
9
+ export const TA_TERMINAL_SERVICE = 'TaTerminalServer';
10
+
11
+ /** An entry of a directory of the workspace. */
12
+ export interface TaDirEntry {
13
+ name: string;
14
+ /** Relative to the directory the call names as `cwd`, with `/`. */
15
+ path: string;
16
+ kind: 'file' | 'directory';
17
+ size?: number;
18
+ }
19
+
20
+ export interface TaFileContent {
21
+ path: string;
22
+ size: number;
23
+ /** Not text: `text` is left out. */
24
+ binary: boolean;
25
+ /** Larger than the limit (1 MB): `text` holds the start. */
26
+ truncated: boolean;
27
+ text?: string;
28
+ }
29
+
30
+ export interface TaRunCommandOptions {
31
+ /** Default: the server's directory. */
32
+ cwd?: string;
33
+ /** Written to the standard input, which is then closed. */
34
+ input?: string;
35
+ /** Default 30 s, at most 120 s; the process is killed then. */
36
+ timeoutMs?: number;
37
+ /** Of each of stdout and stderr; default 1 MB, at most 8 MB. */
38
+ maxBytes?: number;
39
+ }
40
+
41
+ export interface TaCommandOutput {
42
+ stdout: string;
43
+ stderr: string;
44
+ /** null when it was killed (`timedOut`) or ended by a signal. */
45
+ exitCode: number | null;
46
+ /** An output was longer than `maxBytes`: it holds the start. */
47
+ truncated: boolean;
48
+ timedOut: boolean;
49
+ }
50
+
51
+ /**
52
+ * The files of a directory of the machine of `ta serve` and programs run there, on the same WebSocket as
53
+ * {@link TaServer}. Paths are relative to `cwd` (default: the server's directory) and may not leave it;
54
+ * the work runs in the execution environment of `cwd`, as the tools of a session do.
55
+ */
56
+ export interface TaWorkspaceServer {
57
+ /** Directories first, then by name; `.git` is left out. */
58
+ listDirectory(path: string, cwd?: string): Promise<TaDirEntry[]>;
59
+ readFile(path: string, cwd?: string): Promise<TaFileContent>;
60
+ /** Writes the text of a file; its directory must be there. */
61
+ writeFile(path: string, text: string, cwd?: string): Promise<void>;
62
+ /**
63
+ * A URL of this server, under {@link TA_FILES_PATH}, that answers the bytes of a file of `cwd`, for
64
+ * what the page shows as it is: an image, a video, a page with what it loads next to it. The URL needs
65
+ * no token, so that a page loads the files beside it with relative URLs; each `cwd` has its own
66
+ * secret part. Pages are answered sandboxed: they run in an origin of their own, not the server's.
67
+ */
68
+ fileUrl(path: string, cwd?: string): Promise<string>;
69
+ /** Paths of files whose name matches `query` loosely, best first; ignored files are left out. */
70
+ findFiles(query: string, cwd?: string, limit?: number): Promise<string[]>;
71
+ /**
72
+ * Runs a program with its arguments, without a shell, in the execution environment of `cwd`, and
73
+ * answers its output once it ends: what packages build on (git, rg) instead of a method each.
74
+ */
75
+ runCommand(command: string, args: string[], options?: TaRunCommandOptions): Promise<TaCommandOutput>;
76
+ }
77
+
78
+ export interface TaTerminalInfo {
79
+ terminalId: string;
80
+ cwd: string;
81
+ shell: string;
82
+ /** False: plain pipes (no `script` on the server, or Windows): full-screen programs do not draw right. */
83
+ pty: boolean;
84
+ }
85
+
86
+ export interface TaOpenTerminalOptions {
87
+ /** Default: the server's directory. */
88
+ cwd?: string;
89
+ cols: number;
90
+ rows: number;
91
+ }
92
+
93
+ /** The shells of a connection, on the same WebSocket as {@link TaServer}. */
94
+ export interface TaTerminalServer {
95
+ /** A shell of this connection; its output comes by TaClient.onTerminalData. It closes 30 s after the connection drops. */
96
+ openTerminal(options: TaOpenTerminalOptions): Promise<TaTerminalInfo>;
97
+ writeTerminal(terminalId: string, data: string): Promise<void>;
98
+ resizeTerminal(terminalId: string, cols: number, rows: number): Promise<void>;
99
+ closeTerminal(terminalId: string): Promise<void>;
100
+ /** The terminals of this connection that are still open. */
101
+ listTerminals(): Promise<TaTerminalInfo[]>;
102
+ }