@celljs/ta-protocol 4.8.0 → 4.9.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.en.md +2 -2
- package/README.md +2 -2
- package/esm/common/access-protocol.d.ts +73 -0
- package/esm/common/access-protocol.js +9 -0
- package/esm/common/gateway-protocol.d.ts +81 -0
- package/esm/common/gateway-protocol.js +3 -0
- package/esm/common/index.d.ts +2 -0
- package/esm/common/index.js +2 -0
- package/esm/common/location.d.ts +5 -0
- package/esm/common/location.js +12 -0
- package/esm/common/package-protocol.d.ts +60 -1
- package/esm/common/package-protocol.js +12 -0
- package/esm/common/relay-protocol.d.ts +17 -0
- package/esm/common/settings-protocol.d.ts +2 -0
- package/esm/common/ta-extension-host.d.ts +9 -0
- package/esm/common/ta-extension-host.js +6 -0
- package/esm/common/ta-protocol.d.ts +110 -4
- package/esm/common/ta-protocol.js +33 -0
- package/esm/common/workspace-protocol.d.ts +12 -1
- package/esm/common/workspace-protocol.js +16 -0
- package/lib/common/access-protocol.d.ts +74 -0
- package/lib/common/access-protocol.js +12 -0
- package/lib/common/gateway-protocol.d.ts +82 -0
- package/lib/common/gateway-protocol.js +6 -0
- package/lib/common/index.d.ts +2 -0
- package/lib/common/index.js +2 -0
- package/lib/common/location.d.ts +5 -0
- package/lib/common/location.js +12 -0
- package/lib/common/package-protocol.d.ts +60 -1
- package/lib/common/package-protocol.js +13 -1
- package/lib/common/relay-protocol.d.ts +17 -0
- package/lib/common/settings-protocol.d.ts +2 -0
- package/lib/common/ta-extension-host.d.ts +9 -0
- package/lib/common/ta-extension-host.js +7 -1
- package/lib/common/ta-protocol.d.ts +110 -4
- package/lib/common/ta-protocol.js +34 -1
- package/lib/common/workspace-protocol.d.ts +12 -1
- package/lib/common/workspace-protocol.js +17 -1
- package/package.json +3 -2
- package/esm/common/auth-protocol.js.map +0 -1
- package/esm/common/index.js.map +0 -1
- package/esm/common/location.js.map +0 -1
- package/esm/common/package-protocol.js.map +0 -1
- package/esm/common/pi-types.js.map +0 -1
- package/esm/common/relay-protocol.js.map +0 -1
- package/esm/common/remote-protocol.js.map +0 -1
- package/esm/common/settings-protocol.js.map +0 -1
- package/esm/common/ta-extension-host.js.map +0 -1
- package/esm/common/ta-protocol.js.map +0 -1
- package/esm/common/workspace-protocol.js.map +0 -1
- package/lib/common/auth-protocol.d.ts.map +0 -1
- package/lib/common/auth-protocol.js.map +0 -1
- package/lib/common/index.d.ts.map +0 -1
- package/lib/common/index.js.map +0 -1
- package/lib/common/location.d.ts.map +0 -1
- package/lib/common/location.js.map +0 -1
- package/lib/common/location.spec.d.ts +0 -2
- package/lib/common/location.spec.d.ts.map +0 -1
- package/lib/common/location.spec.js +0 -58
- package/lib/common/location.spec.js.map +0 -1
- package/lib/common/package-protocol.d.ts.map +0 -1
- package/lib/common/package-protocol.js.map +0 -1
- package/lib/common/pi-types.d.ts.map +0 -1
- package/lib/common/pi-types.js.map +0 -1
- package/lib/common/relay-protocol.d.ts.map +0 -1
- package/lib/common/relay-protocol.js.map +0 -1
- package/lib/common/remote-protocol.d.ts.map +0 -1
- package/lib/common/remote-protocol.js.map +0 -1
- package/lib/common/settings-protocol.d.ts.map +0 -1
- package/lib/common/settings-protocol.js.map +0 -1
- package/lib/common/ta-extension-host.d.ts.map +0 -1
- package/lib/common/ta-extension-host.js.map +0 -1
- package/lib/common/ta-protocol.d.ts.map +0 -1
- package/lib/common/ta-protocol.js.map +0 -1
- package/lib/common/ta-protocol.spec.d.ts +0 -2
- package/lib/common/ta-protocol.spec.d.ts.map +0 -1
- package/lib/common/ta-protocol.spec.js +0 -41
- package/lib/common/ta-protocol.spec.js.map +0 -1
- package/lib/common/workspace-protocol.d.ts.map +0 -1
- package/lib/common/workspace-protocol.js.map +0 -1
- package/src/common/auth-protocol.ts +0 -56
- package/src/common/index.ts +0 -10
- package/src/common/location.spec.ts +0 -62
- package/src/common/location.ts +0 -177
- package/src/common/package-protocol.ts +0 -99
- package/src/common/pi-types.ts +0 -11
- package/src/common/relay-protocol.ts +0 -28
- package/src/common/remote-protocol.ts +0 -76
- package/src/common/settings-protocol.ts +0 -73
- package/src/common/ta-extension-host.ts +0 -97
- package/src/common/ta-protocol.spec.ts +0 -48
- package/src/common/ta-protocol.ts +0 -352
- package/src/common/workspace-protocol.ts +0 -120
|
@@ -1,73 +0,0 @@
|
|
|
1
|
-
import type { TaServer } from './ta-protocol';
|
|
2
|
-
|
|
3
|
-
export const TaSettingsServer = Symbol('TaSettingsServer');
|
|
4
|
-
export const TA_SETTINGS_SERVICE = 'TaSettingsServer';
|
|
5
|
-
|
|
6
|
-
/** Where a setting of ta is kept: pi's `settings.json` of the user (the agent directory), or of a project (`.ta/` of its directory), which wins. */
|
|
7
|
-
export type TaSettingsScope = 'user' | 'project';
|
|
8
|
-
|
|
9
|
-
/** A setting of ta that clients show and change; the key is its path in pi's `settings.json`. */
|
|
10
|
-
export interface TaSettingSpec {
|
|
11
|
-
key: string;
|
|
12
|
-
/** `model`: `<provider>/<model id>`, kept by pi as `defaultProvider` and `defaultModel`. */
|
|
13
|
-
type: 'boolean' | 'number' | 'string' | 'enum' | 'model';
|
|
14
|
-
values?: readonly string[];
|
|
15
|
-
/** What pi does when no file sets it; none when pi decides by itself (the model, a thinking level). */
|
|
16
|
-
default?: boolean | number | string;
|
|
17
|
-
}
|
|
18
|
-
|
|
19
|
-
/** The settings of ta that clients change, as pi names them; other keys of the files are left as they are. */
|
|
20
|
-
export const TA_SETTINGS: readonly TaSettingSpec[] = [
|
|
21
|
-
{ key: 'model', type: 'model' },
|
|
22
|
-
{ key: 'defaultThinkingLevel', type: 'enum', values: ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] },
|
|
23
|
-
{ key: 'transport', type: 'enum', values: ['auto', 'sse', 'websocket', 'websocket-cached'], default: 'auto' },
|
|
24
|
-
{ key: 'steeringMode', type: 'enum', values: ['one-at-a-time', 'all'], default: 'one-at-a-time' },
|
|
25
|
-
{ key: 'followUpMode', type: 'enum', values: ['one-at-a-time', 'all'], default: 'one-at-a-time' },
|
|
26
|
-
{ key: 'compaction.enabled', type: 'boolean', default: true },
|
|
27
|
-
{ key: 'compaction.reserveTokens', type: 'number', default: 16384 },
|
|
28
|
-
{ key: 'compaction.keepRecentTokens', type: 'number', default: 20000 },
|
|
29
|
-
{ key: 'retry.enabled', type: 'boolean', default: true },
|
|
30
|
-
{ key: 'retry.maxRetries', type: 'number', default: 3 },
|
|
31
|
-
{ key: 'codemode.mode', type: 'enum', values: ['only', 'on'], default: 'only' },
|
|
32
|
-
{ key: 'enableSkillCommands', type: 'boolean', default: true },
|
|
33
|
-
{ key: 'images.autoResize', type: 'boolean', default: true },
|
|
34
|
-
{ key: 'images.blockImages', type: 'boolean', default: false },
|
|
35
|
-
{ key: 'shellPath', type: 'string' },
|
|
36
|
-
{ key: 'shellCommandPrefix', type: 'string' },
|
|
37
|
-
];
|
|
38
|
-
|
|
39
|
-
/** The settings of ta (TA_SETTINGS) in the files of the user and of a project: only the keys each file sets. */
|
|
40
|
-
export interface TaSettingsSnapshot {
|
|
41
|
-
user: Record<string, unknown>;
|
|
42
|
-
project: Record<string, unknown>;
|
|
43
|
-
/** The directory of the project. */
|
|
44
|
-
cwd: string;
|
|
45
|
-
userFile: string;
|
|
46
|
-
projectFile: string;
|
|
47
|
-
/**
|
|
48
|
-
* pi reads the settings of a project only when the user trusts it. Changing them from a client trusts a
|
|
49
|
-
* project that has nothing else to trust yet; one with extensions or skills of its own is trusted in `ta`.
|
|
50
|
-
*/
|
|
51
|
-
projectTrusted: boolean;
|
|
52
|
-
/** `<provider>/<model id>` of the models with credentials, for the model setting. */
|
|
53
|
-
models: string[];
|
|
54
|
-
/** The names of those of `models` that have one other than their id. */
|
|
55
|
-
modelNames?: Record<string, string>;
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
/** The settings of ta in pi's `settings.json` files, on the same WebSocket as {@link TaServer}. */
|
|
59
|
-
export interface TaSettingsServer {
|
|
60
|
-
/** The settings of ta (TA_SETTINGS) of the user and of the project in `cwd` (default: the server's directory). */
|
|
61
|
-
getSettings(cwd?: string): Promise<TaSettingsSnapshot>;
|
|
62
|
-
/**
|
|
63
|
-
* Sets settings of ta in one file, by key of TA_SETTINGS; `null` removes a key, so that the project
|
|
64
|
-
* follows the user and the user pi's default. Open sessions read them again; the model and the thinking
|
|
65
|
-
* level are for new sessions.
|
|
66
|
-
*/
|
|
67
|
-
updateSettings(scope: TaSettingsScope, changes: Record<string, unknown>, cwd?: string): Promise<TaSettingsSnapshot>;
|
|
68
|
-
/**
|
|
69
|
-
* The language the user reads (`zh-CN`, `en-US`), for what the server and the pi packages it runs say:
|
|
70
|
-
* it is `TA_LANGUAGE` of the process of ta serve, which they read. The client that set it last wins.
|
|
71
|
-
*/
|
|
72
|
-
setLanguage(language: string): Promise<void>;
|
|
73
|
-
}
|
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
import type { TaPackageServer } from './package-protocol';
|
|
2
|
-
import type { TaServer } from './ta-protocol';
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* What `ta serve` gives the server side of a package: the sessions and the data of packages, in its own
|
|
6
|
-
* process, without a token. A subset of TaServer and TaPackageServer: it can open, drive, stop and close
|
|
7
|
-
* sessions (best those it opened: closing one takes it from every client), not remove anything.
|
|
8
|
-
*/
|
|
9
|
-
export interface TaExtensionHost
|
|
10
|
-
extends Pick<
|
|
11
|
-
TaServer,
|
|
12
|
-
| 'getServerInfo'
|
|
13
|
-
| 'listSessions'
|
|
14
|
-
| 'openSession'
|
|
15
|
-
| 'closeSession'
|
|
16
|
-
| 'setSessionName'
|
|
17
|
-
| 'prompt'
|
|
18
|
-
| 'followUp'
|
|
19
|
-
| 'abort'
|
|
20
|
-
| 'getState'
|
|
21
|
-
| 'getLastAssistantText'
|
|
22
|
-
>,
|
|
23
|
-
Pick<TaPackageServer, 'getExtensionData' | 'setExtensionData' | 'listPackages'> {
|
|
24
|
-
/** The agent directory of Ta (`~/.ta/agent`): its `extensions/` holds the packages of the user. */
|
|
25
|
-
readonly agentDir: string;
|
|
26
|
-
/** Where the conversation of a session file works, as clients name it (a path or an `ssh://` location), without opening it; undefined when it cannot be read. */
|
|
27
|
-
sessionCwd(sessionFile: string): Promise<string | undefined>;
|
|
28
|
-
/** Keys of the data of a package that changed, by a page or by the server, as they change; `cwd` for a key of a directory. */
|
|
29
|
-
onExtensionData(listener: (name: string, key: string, cwd?: string) => void): () => void;
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
/**
|
|
33
|
-
* What the module of `pi.host` returns: anything the package's pi extensions should reach. Its web
|
|
34
|
-
* extension calls its methods with TaPackageServer.callPackageHost, with JSON values.
|
|
35
|
-
*/
|
|
36
|
-
export interface TaPackageService {
|
|
37
|
-
/** `ta serve` stops, or the package is turned off. */
|
|
38
|
-
dispose?(): void | Promise<void>;
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* The default export of a module that a package names in `pi.host` of its package.json. `ta serve` runs it
|
|
43
|
-
* once when it starts (or when the package is turned on), for built-in packages; `ta` without `serve`
|
|
44
|
-
* does not run it.
|
|
45
|
-
*/
|
|
46
|
-
export type TaPackageHostFactory = (host: TaExtensionHost) => TaPackageService | undefined | Promise<TaPackageService | undefined>;
|
|
47
|
-
|
|
48
|
-
/**
|
|
49
|
-
* The event of pi's `pi.events` by which a pi extension asks for the host of its package:
|
|
50
|
-
* `pi.events.emit(TA_HOST_EVENT, { name, resolve })`. Under `ta serve` `resolve` is called at once, if
|
|
51
|
-
* the extension asks after loading (on `session_start`, or in a tool); under `ta` alone nobody answers,
|
|
52
|
-
* and the extension should say its tools need `ta serve`.
|
|
53
|
-
*/
|
|
54
|
-
export const TA_HOST_EVENT = 'ta:host';
|
|
55
|
-
|
|
56
|
-
/**
|
|
57
|
-
* The event of pi's `pi.events` by which an extension whose tools change files without pi's `edit` and
|
|
58
|
-
* `write` (another coding agent's own tools, ta-agents) says which, as soon as it knows and before the
|
|
59
|
-
* write if it can: `pi.events.emit(TA_FILE_WRITE_EVENT, file)`. The list of changed files (ta-changes)
|
|
60
|
-
* keeps what the file holds then.
|
|
61
|
-
*/
|
|
62
|
-
export const TA_FILE_WRITE_EVENT = 'ta:file-write';
|
|
63
|
-
|
|
64
|
-
export interface TaFileWrite {
|
|
65
|
-
/** Absolute, on the machine where the session's tools work. */
|
|
66
|
-
path: string;
|
|
67
|
-
/** Its text before the change, when known (a diff of the agent); null: there was no file. */
|
|
68
|
-
before?: string | null;
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
export interface TaHostRequest {
|
|
72
|
-
/** The `name` of the package.json. */
|
|
73
|
-
name: string;
|
|
74
|
-
resolve(answer: TaHostAnswer): void;
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
export interface TaHostAnswer {
|
|
78
|
-
host: TaExtensionHost;
|
|
79
|
-
/** What the module of `pi.host` of the package returned; undefined when it has none or failed. */
|
|
80
|
-
service?: TaPackageService;
|
|
81
|
-
/** The files of the session that asked, where its tools read and write. */
|
|
82
|
-
files: TaSessionFiles;
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
/**
|
|
86
|
-
* The files of a session where its tools work: on the machine of `ta serve`, or on the one of an
|
|
87
|
-
* `ssh://` directory (ExecEnvironment). Paths are those {@link resolve} gives.
|
|
88
|
-
*/
|
|
89
|
-
export interface TaSessionFiles {
|
|
90
|
-
/** The path a tool of the session (read, edit, write) works on for a path of its arguments. */
|
|
91
|
-
resolve(path: string): string;
|
|
92
|
-
/** The bytes of a file; undefined when there is no file there. */
|
|
93
|
-
read(path: string): Promise<Uint8Array | undefined>;
|
|
94
|
-
/** Writes a file, and the directories it needs. */
|
|
95
|
-
write(path: string, data: Uint8Array): Promise<void>;
|
|
96
|
-
remove(path: string): Promise<void>;
|
|
97
|
-
}
|
|
@@ -1,48 +0,0 @@
|
|
|
1
|
-
import { describe, expect, it } from 'bun:test';
|
|
2
|
-
import { TA_AUTH_SERVICE, TaAuthServer } from './auth-protocol';
|
|
3
|
-
import { TA_PACKAGE_SERVICE, TaPackageServer } from './package-protocol';
|
|
4
|
-
import { TA_RELAY_SERVICE, TaRelayServer } from './relay-protocol';
|
|
5
|
-
import { TA_REMOTE_SERVICE, TaRemoteServer } from './remote-protocol';
|
|
6
|
-
import { TA_SETTINGS_SERVICE, TaSettingsServer } from './settings-protocol';
|
|
7
|
-
import { type PiCommandMethod, TA_CLIENT_SERVICE, TA_SERVER_SERVICE, TaClient, TaErrorCode, TaMessageContext, TaServer } from './ta-protocol';
|
|
8
|
-
import { TA_TERMINAL_SERVICE, TA_WORKSPACE_SERVICE, TaTerminalServer, TaWorkspaceServer } from './workspace-protocol';
|
|
9
|
-
|
|
10
|
-
/**
|
|
11
|
-
* Fails to compile when pi's RPC mode has a command that TaServer has no method for: after an upgrade of
|
|
12
|
-
* pi, add the method, doing what pi's `rpc-mode` does for it.
|
|
13
|
-
*/
|
|
14
|
-
type MissingPiCommands = Exclude<PiCommandMethod, keyof TaServer>;
|
|
15
|
-
const everyPiCommand: [MissingPiCommands] extends [never] ? true : MissingPiCommands = true;
|
|
16
|
-
|
|
17
|
-
describe('ta protocol', () => {
|
|
18
|
-
it('names each failure with a distinct CELL_TA_ code', () => {
|
|
19
|
-
const codes = Object.values(TaErrorCode);
|
|
20
|
-
expect(new Set(codes).size).toBe(codes.length);
|
|
21
|
-
for (const code of codes) {
|
|
22
|
-
expect(code).toStartWith('CELL_TA_');
|
|
23
|
-
}
|
|
24
|
-
});
|
|
25
|
-
|
|
26
|
-
it('routes JSON-RPC methods by the names of the service symbols', () => {
|
|
27
|
-
expect(TaServer.description).toBe(TA_SERVER_SERVICE);
|
|
28
|
-
expect(TaClient.description).toBe(TA_CLIENT_SERVICE);
|
|
29
|
-
expect(TaWorkspaceServer.description).toBe(TA_WORKSPACE_SERVICE);
|
|
30
|
-
expect(TaTerminalServer.description).toBe(TA_TERMINAL_SERVICE);
|
|
31
|
-
expect(TaSettingsServer.description).toBe(TA_SETTINGS_SERVICE);
|
|
32
|
-
expect(TaPackageServer.description).toBe(TA_PACKAGE_SERVICE);
|
|
33
|
-
expect(TaAuthServer.description).toBe(TA_AUTH_SERVICE);
|
|
34
|
-
expect(TaRelayServer.description).toBe(TA_RELAY_SERVICE);
|
|
35
|
-
expect(TaRemoteServer.description).toBe(TA_REMOTE_SERVICE);
|
|
36
|
-
});
|
|
37
|
-
|
|
38
|
-
it('has a method of TaServer for each command of pi', () => {
|
|
39
|
-
expect(everyPiCommand).toBe(true);
|
|
40
|
-
});
|
|
41
|
-
|
|
42
|
-
it('leaves the context of a message out of what is shown', () => {
|
|
43
|
-
const message = TaMessageContext.wrap('[#test]\nMembers:\n- @a', '@a hi\nthere');
|
|
44
|
-
expect(message).toStartWith('<context>\n');
|
|
45
|
-
expect(TaMessageContext.strip(message)).toBe('@a hi\nthere');
|
|
46
|
-
expect(TaMessageContext.strip('no <context> here')).toBe('no <context> here');
|
|
47
|
-
});
|
|
48
|
-
});
|
|
@@ -1,352 +0,0 @@
|
|
|
1
|
-
import type { TaAuthEvent } from './auth-protocol';
|
|
2
|
-
import type { ImageContent, JsonAgentSessionEvent, RpcCommand, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcResponse, ThinkingLevel } from './pi-types';
|
|
3
|
-
import type { TaRemoteEvent } from './remote-protocol';
|
|
4
|
-
|
|
5
|
-
export const TaServer = Symbol('TaServer');
|
|
6
|
-
export const TaClient = Symbol('TaClient');
|
|
7
|
-
|
|
8
|
-
/** Path of the WebSocket endpoint of `ta serve`, and the JSON-RPC method prefixes of both sides. */
|
|
9
|
-
export const TA_WEBSOCKET_PATH = '/api/ws';
|
|
10
|
-
export const TA_SERVER_SERVICE = 'TaServer';
|
|
11
|
-
export const TA_CLIENT_SERVICE = 'TaClient';
|
|
12
|
-
|
|
13
|
-
/** The file `ta serve` writes in the agent directory, readable only by its user. */
|
|
14
|
-
export const TA_SERVE_FILE = 'serve.json';
|
|
15
|
-
|
|
16
|
-
/** The contents of {@link TA_SERVE_FILE}: how to reach the running `ta serve`. */
|
|
17
|
-
export interface TaServeInfo {
|
|
18
|
-
url: string;
|
|
19
|
-
token: string;
|
|
20
|
-
pid: number;
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
/** What a client needs to know of the server before it opens a session. */
|
|
24
|
-
export interface TaServerInfo {
|
|
25
|
-
/** The version of ta. */
|
|
26
|
-
version: string;
|
|
27
|
-
/**
|
|
28
|
-
* Where a client opens a session when the user names no directory: the one set with
|
|
29
|
-
* `setWorkingDirectory`, else the working directory of `ta serve`, or of its execution environment.
|
|
30
|
-
*/
|
|
31
|
-
cwd: string;
|
|
32
|
-
/** The user who runs `ta serve`, as the system names them: whose Ta the client is signed in to. */
|
|
33
|
-
user: string;
|
|
34
|
-
/** The name of the machine of `ta serve`, without a `.local` suffix. */
|
|
35
|
-
host: string;
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
/** The stable `code` of each failure of a {@link TaServer} call. */
|
|
39
|
-
export const TaErrorCode = {
|
|
40
|
-
SESSION_NOT_FOUND: 'CELL_TA_SESSION_NOT_FOUND',
|
|
41
|
-
SESSION_LOCKED: 'CELL_TA_SESSION_LOCKED',
|
|
42
|
-
TOO_MANY_SESSIONS: 'CELL_TA_TOO_MANY_SESSIONS',
|
|
43
|
-
MESSAGE_CONFLICT: 'CELL_TA_MESSAGE_CONFLICT',
|
|
44
|
-
MODEL_NOT_FOUND: 'CELL_TA_MODEL_NOT_FOUND',
|
|
45
|
-
INVALID_ARGUMENT: 'CELL_TA_INVALID_ARGUMENT',
|
|
46
|
-
COMMAND_FAILED: 'CELL_TA_COMMAND_FAILED',
|
|
47
|
-
/** No provider of models is signed in for the model, or there is no model: sign in (TaAuthServer) first. */
|
|
48
|
-
NOT_SIGNED_IN: 'CELL_TA_NOT_SIGNED_IN',
|
|
49
|
-
/** Raised by the client, not the server: the call could not reach ta serve, or its answer was lost with the connection. */
|
|
50
|
-
CONNECTION_LOST: 'CELL_TA_CONNECTION_LOST',
|
|
51
|
-
} as const;
|
|
52
|
-
export type TaErrorCode = (typeof TaErrorCode)[keyof typeof TaErrorCode];
|
|
53
|
-
|
|
54
|
-
/** The JSON-RPC error code of every failure of a {@link TaServer} call; `data.code` tells them apart. */
|
|
55
|
-
export const TA_RPC_ERROR_CODE = -32050;
|
|
56
|
-
|
|
57
|
-
export interface TaErrorData {
|
|
58
|
-
code: TaErrorCode;
|
|
59
|
-
/** One sentence on what to do about it. */
|
|
60
|
-
hint: string;
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
/** A command name of pi's RPC mode (`get_state`, `follow_up`, ...). */
|
|
64
|
-
export type TaCommand = Extract<RpcResponse, { success: true }>['command'];
|
|
65
|
-
|
|
66
|
-
/** The answer to `forkToFile`. */
|
|
67
|
-
export interface TaForkFileResult {
|
|
68
|
-
/** The new conversation; none when nothing comes before the message: then a new conversation starts. */
|
|
69
|
-
sessionFile?: string;
|
|
70
|
-
/** The message of the user left out (`before`), for the box of the new conversation. */
|
|
71
|
-
text?: string;
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
/** The answer to `navigateTree`, which pi's RPC mode does not have. */
|
|
75
|
-
export interface TaNavigateResult {
|
|
76
|
-
cancelled: boolean;
|
|
77
|
-
editorText?: string;
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
/** `get_state` → `getState`. */
|
|
81
|
-
type CamelCase<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
|
|
82
|
-
|
|
83
|
-
/** The method of TaServer for each command of pi's RPC mode: TaServer has one for each (see its spec). */
|
|
84
|
-
export type PiCommandMethod = CamelCase<RpcCommand['type']>;
|
|
85
|
-
|
|
86
|
-
/** What pi's RPC mode answers to a command. */
|
|
87
|
-
export type TaCommandResult<C extends TaCommand> = Extract<RpcResponse, { command: C; success: true }> extends { data: infer D } ? D : undefined;
|
|
88
|
-
|
|
89
|
-
/** A tool the client runs: the model calls it like any other tool, the server asks the client for the result. */
|
|
90
|
-
export interface TaClientToolDefinition {
|
|
91
|
-
/** Letters, digits, `_` and `-`, starting with a letter; best not the name of another tool of the session. */
|
|
92
|
-
name: string;
|
|
93
|
-
description: string;
|
|
94
|
-
/** JSON schema of the arguments, an object schema. */
|
|
95
|
-
parameters: Record<string, unknown>;
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
export interface TaOpenSessionOptions {
|
|
99
|
-
/** Working directory of the session: a path of the machine of the server, or an `ssh://` location of another (TaLocation). */
|
|
100
|
-
cwd: string;
|
|
101
|
-
/** Opens this session file; default: a new session. */
|
|
102
|
-
sessionFile?: string;
|
|
103
|
-
/** `<provider>/<model id>`; default: pi's settings. */
|
|
104
|
-
model?: string;
|
|
105
|
-
thinkingLevel?: ThinkingLevel;
|
|
106
|
-
/** Tools the client runs; fixed when the session opens, so the tool list stays stable for prompt caching. */
|
|
107
|
-
clientTools?: TaClientToolDefinition[];
|
|
108
|
-
/** Added to the system prompt, as pi's `--append-system-prompt`: a role the client gives the agent. */
|
|
109
|
-
appendSystemPrompt?: string;
|
|
110
|
-
/** Sessions a package opens for its own work (the name of the package): clients list them apart, folded. */
|
|
111
|
-
group?: string;
|
|
112
|
-
}
|
|
113
|
-
|
|
114
|
-
export interface TaSessionInfo {
|
|
115
|
-
/** The id of this open session; stays the same through `newSession`, `switchSession` and `fork`. */
|
|
116
|
-
sessionId: string;
|
|
117
|
-
/** The id of the conversation pi has open now. */
|
|
118
|
-
piSessionId: string;
|
|
119
|
-
cwd: string;
|
|
120
|
-
sessionFile?: string;
|
|
121
|
-
sessionName?: string;
|
|
122
|
-
/** The first line of the first message of the user, which a list shows when the session has no name. */
|
|
123
|
-
firstMessage?: string;
|
|
124
|
-
/** `<provider>/<model id>`. */
|
|
125
|
-
model?: string;
|
|
126
|
-
isStreaming: boolean;
|
|
127
|
-
messageCount: number;
|
|
128
|
-
/** Number of clients attached. */
|
|
129
|
-
attached: number;
|
|
130
|
-
createdAt: number;
|
|
131
|
-
/** When the last message came; `createdAt` before the first. */
|
|
132
|
-
updatedAt: number;
|
|
133
|
-
/** TaOpenSessionOptions.group. */
|
|
134
|
-
group?: string;
|
|
135
|
-
}
|
|
136
|
-
|
|
137
|
-
export interface TaPromptInput {
|
|
138
|
-
/** May start with a block of context for the model, which clients do not show: see {@link TaMessageContext}. */
|
|
139
|
-
message: string;
|
|
140
|
-
images?: ImageContent[];
|
|
141
|
-
/** Chosen by the client, unique per message: sending the same one again does not run it again. */
|
|
142
|
-
clientMessageId: string;
|
|
143
|
-
/** What to do when the agent is running; only for `prompt`. Default: `followUp`. */
|
|
144
|
-
streamingBehavior?: 'steer' | 'followUp';
|
|
145
|
-
}
|
|
146
|
-
|
|
147
|
-
/**
|
|
148
|
-
* A message of the user may start with a `<context>` block: what the model reads besides the message
|
|
149
|
-
* (where it is said, who is there, what was said before), which a client leaves out when it shows it.
|
|
150
|
-
*/
|
|
151
|
-
export namespace TaMessageContext {
|
|
152
|
-
const BLOCK = /^<context>\n?[\s\S]*?\n?<\/context>\n?/;
|
|
153
|
-
|
|
154
|
-
export function wrap(context: string, message: string): string {
|
|
155
|
-
return `<context>\n${context}\n</context>\n${message}`;
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
/** The message without its context: what the user sees of it. */
|
|
159
|
-
export function strip(message: string): string {
|
|
160
|
-
return message.replace(BLOCK, '');
|
|
161
|
-
}
|
|
162
|
-
}
|
|
163
|
-
|
|
164
|
-
/**
|
|
165
|
-
* The server has taken the message; it says nothing about the run. A run is finished at the
|
|
166
|
-
* `agent_settled` event, when its history is on disk.
|
|
167
|
-
*/
|
|
168
|
-
export interface TaPromptReceipt {
|
|
169
|
-
clientMessageId: string;
|
|
170
|
-
/** `accepted`: it runs now; `queued`: after the current work; `duplicate`: this id was taken before. */
|
|
171
|
-
status: 'accepted' | 'queued' | 'duplicate';
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
/** An extension's dialog was answered by another client, or expired. */
|
|
175
|
-
export interface TaUiRequestResolved {
|
|
176
|
-
type: 'ui_request_resolved';
|
|
177
|
-
id: string;
|
|
178
|
-
}
|
|
179
|
-
|
|
180
|
-
/** An extension threw while handling an event. */
|
|
181
|
-
export interface TaExtensionError {
|
|
182
|
-
type: 'extension_error';
|
|
183
|
-
extensionPath: string;
|
|
184
|
-
event: string;
|
|
185
|
-
error: string;
|
|
186
|
-
}
|
|
187
|
-
|
|
188
|
-
/** The open session now shows another conversation (`newSession`, `switchSession`, `fork`, `clone`, `navigateTree`): read it again. */
|
|
189
|
-
export interface TaSessionReplaced {
|
|
190
|
-
type: 'session_replaced';
|
|
191
|
-
info: TaSessionInfo;
|
|
192
|
-
}
|
|
193
|
-
|
|
194
|
-
/** The session was closed; no more events come. */
|
|
195
|
-
export interface TaSessionClosed {
|
|
196
|
-
type: 'session_closed';
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
/**
|
|
200
|
-
* The model called a tool of `clientTools`: a client that runs it answers with `respondClientTool`.
|
|
201
|
-
* It goes to every attached client; the first answer counts, and `client_tool_resolved` tells the others.
|
|
202
|
-
*/
|
|
203
|
-
export interface TaClientToolRequest {
|
|
204
|
-
type: 'client_tool_request';
|
|
205
|
-
/** The id of the tool call. */
|
|
206
|
-
id: string;
|
|
207
|
-
toolName: string;
|
|
208
|
-
input: unknown;
|
|
209
|
-
}
|
|
210
|
-
|
|
211
|
-
/** A call of a client tool was answered, or ended because the run was aborted or the session closed. */
|
|
212
|
-
export interface TaClientToolResolved {
|
|
213
|
-
type: 'client_tool_resolved';
|
|
214
|
-
id: string;
|
|
215
|
-
}
|
|
216
|
-
|
|
217
|
-
export type TaEvent =
|
|
218
|
-
| JsonAgentSessionEvent
|
|
219
|
-
| RpcExtensionUIRequest
|
|
220
|
-
| TaUiRequestResolved
|
|
221
|
-
| TaExtensionError
|
|
222
|
-
| TaClientToolRequest
|
|
223
|
-
| TaClientToolResolved
|
|
224
|
-
| TaSessionReplaced
|
|
225
|
-
| TaSessionClosed;
|
|
226
|
-
|
|
227
|
-
export interface TaEventEnvelope {
|
|
228
|
-
sessionId: string;
|
|
229
|
-
/** Increases by one per event of the session. */
|
|
230
|
-
seq: number;
|
|
231
|
-
event: TaEvent;
|
|
232
|
-
}
|
|
233
|
-
|
|
234
|
-
export interface TaAttachResult {
|
|
235
|
-
info: TaSessionInfo;
|
|
236
|
-
/** The events after `afterSeq`. */
|
|
237
|
-
events: TaEventEnvelope[];
|
|
238
|
-
/** The dialogs still waiting for an answer. */
|
|
239
|
-
pendingUi: RpcExtensionUIRequest[];
|
|
240
|
-
/** The calls of client tools still waiting for a result. */
|
|
241
|
-
pendingClientTools: TaClientToolRequest[];
|
|
242
|
-
/**
|
|
243
|
-
* What the extensions show now (`setStatus`, `setWidget`), as a terminal keeps it on screen: a client
|
|
244
|
-
* that attaches draws it, whatever it missed. None from a server before it.
|
|
245
|
-
*/
|
|
246
|
-
shownUi?: RpcExtensionUIRequest[];
|
|
247
|
-
/** Seq of the last event of the session. */
|
|
248
|
-
lastSeq: number;
|
|
249
|
-
/** Some events after `afterSeq` are gone: read the conversation again with `getMessages`. */
|
|
250
|
-
gap: boolean;
|
|
251
|
-
}
|
|
252
|
-
|
|
253
|
-
export interface TaClientToolResult {
|
|
254
|
-
/** The `id` of the request. */
|
|
255
|
-
id: string;
|
|
256
|
-
/** What the model reads. */
|
|
257
|
-
output: string;
|
|
258
|
-
/** The tool failed: `output` says why. */
|
|
259
|
-
isError?: boolean;
|
|
260
|
-
}
|
|
261
|
-
|
|
262
|
-
/**
|
|
263
|
-
* The sessions of `ta serve`, over JSON-RPC 2.0 on a WebSocket. Besides opening, attaching and answering,
|
|
264
|
-
* each method is the command of pi's RPC mode with the same name in camelCase, on the open session
|
|
265
|
-
* `sessionId` (see PiCommandMethod). The same WebSocket carries the other services of ta serve, each
|
|
266
|
-
* under its own name: TaWorkspaceServer, TaTerminalServer, TaSettingsServer, TaPackageServer, TaRemoteServer and others.
|
|
267
|
-
*/
|
|
268
|
-
export interface TaServer {
|
|
269
|
-
getServerInfo(): Promise<TaServerInfo>;
|
|
270
|
-
/**
|
|
271
|
-
* Makes `cwd` the working directory of the server (TaServerInfo.cwd), for every client, and across
|
|
272
|
-
* restarts: where conversations open when the user names no directory. Sessions already open stay where they are.
|
|
273
|
-
*/
|
|
274
|
-
setWorkingDirectory(cwd: string): Promise<TaServerInfo>;
|
|
275
|
-
openSession(options: TaOpenSessionOptions): Promise<TaSessionInfo>;
|
|
276
|
-
closeSession(sessionId: string): Promise<void>;
|
|
277
|
-
listSessions(): Promise<TaSessionInfo[]>;
|
|
278
|
-
/** Starts sending the events of the session to this connection. */
|
|
279
|
-
attach(sessionId: string, afterSeq?: number): Promise<TaAttachResult>;
|
|
280
|
-
detach(sessionId: string): Promise<void>;
|
|
281
|
-
/** Answers a dialog; false when it was answered before or expired. */
|
|
282
|
-
respondUi(sessionId: string, response: RpcExtensionUIResponse): Promise<boolean>;
|
|
283
|
-
/** Answers a call of a client tool; false when nobody waits for it. */
|
|
284
|
-
respondClientTool(sessionId: string, result: TaClientToolResult): Promise<boolean>;
|
|
285
|
-
|
|
286
|
-
prompt(sessionId: string, input: TaPromptInput): Promise<TaPromptReceipt>;
|
|
287
|
-
steer(sessionId: string, input: TaPromptInput): Promise<TaPromptReceipt>;
|
|
288
|
-
followUp(sessionId: string, input: TaPromptInput): Promise<TaPromptReceipt>;
|
|
289
|
-
abort(sessionId: string): Promise<void>;
|
|
290
|
-
clearQueue(sessionId: string): Promise<TaCommandResult<'clear_queue'>>;
|
|
291
|
-
newSession(sessionId: string, parentSession?: string): Promise<TaCommandResult<'new_session'>>;
|
|
292
|
-
getState(sessionId: string): Promise<TaCommandResult<'get_state'>>;
|
|
293
|
-
setModel(sessionId: string, provider: string, modelId: string): Promise<TaCommandResult<'set_model'>>;
|
|
294
|
-
cycleModel(sessionId: string): Promise<TaCommandResult<'cycle_model'>>;
|
|
295
|
-
getAvailableModels(sessionId: string): Promise<TaCommandResult<'get_available_models'>>;
|
|
296
|
-
setThinkingLevel(sessionId: string, level: ThinkingLevel): Promise<void>;
|
|
297
|
-
cycleThinkingLevel(sessionId: string): Promise<TaCommandResult<'cycle_thinking_level'>>;
|
|
298
|
-
getAvailableThinkingLevels(sessionId: string): Promise<TaCommandResult<'get_available_thinking_levels'>>;
|
|
299
|
-
setSteeringMode(sessionId: string, mode: 'all' | 'one-at-a-time'): Promise<void>;
|
|
300
|
-
setFollowUpMode(sessionId: string, mode: 'all' | 'one-at-a-time'): Promise<void>;
|
|
301
|
-
compact(sessionId: string, customInstructions?: string): Promise<TaCommandResult<'compact'>>;
|
|
302
|
-
setAutoCompaction(sessionId: string, enabled: boolean): Promise<void>;
|
|
303
|
-
setAutoRetry(sessionId: string, enabled: boolean): Promise<void>;
|
|
304
|
-
abortRetry(sessionId: string): Promise<void>;
|
|
305
|
-
bash(sessionId: string, command: string, excludeFromContext?: boolean): Promise<TaCommandResult<'bash'>>;
|
|
306
|
-
abortBash(sessionId: string): Promise<void>;
|
|
307
|
-
getSessionStats(sessionId: string): Promise<TaCommandResult<'get_session_stats'>>;
|
|
308
|
-
exportHtml(sessionId: string, outputPath?: string): Promise<TaCommandResult<'export_html'>>;
|
|
309
|
-
switchSession(sessionId: string, sessionPath: string): Promise<TaCommandResult<'switch_session'>>;
|
|
310
|
-
/**
|
|
311
|
-
* A new conversation from an entry, as pi's `/fork`: `before` (the default) a message of the user, which
|
|
312
|
-
* it leaves out and gives back as `text`; `at` any entry, which it keeps.
|
|
313
|
-
*/
|
|
314
|
-
fork(sessionId: string, entryId: string, position?: 'before' | 'at'): Promise<TaCommandResult<'fork'>>;
|
|
315
|
-
/**
|
|
316
|
-
* The new conversation of `fork` in a file of its own, with pi's `createBranchedSession`; the session
|
|
317
|
-
* stays where it is. Open the file with `openSession` to go on with it.
|
|
318
|
-
*/
|
|
319
|
-
forkToFile(sessionId: string, entryId: string, position?: 'before' | 'at'): Promise<TaForkFileResult>;
|
|
320
|
-
clone(sessionId: string): Promise<TaCommandResult<'clone'>>;
|
|
321
|
-
getForkMessages(sessionId: string): Promise<TaCommandResult<'get_fork_messages'>>;
|
|
322
|
-
getEntries(sessionId: string, since?: string): Promise<TaCommandResult<'get_entries'>>;
|
|
323
|
-
getTree(sessionId: string): Promise<TaCommandResult<'get_tree'>>;
|
|
324
|
-
/**
|
|
325
|
-
* Goes to an entry in the same conversation, as pi's `/tree`: the branch left stays in the tree. To a
|
|
326
|
-
* message of the user, it goes to what came before and gives the message back as `editorText`.
|
|
327
|
-
*/
|
|
328
|
-
navigateTree(sessionId: string, targetId: string): Promise<TaNavigateResult>;
|
|
329
|
-
getLastAssistantText(sessionId: string): Promise<TaCommandResult<'get_last_assistant_text'>>;
|
|
330
|
-
setSessionName(sessionId: string, name: string): Promise<void>;
|
|
331
|
-
getMessages(sessionId: string): Promise<TaCommandResult<'get_messages'>>;
|
|
332
|
-
getCommands(sessionId: string): Promise<TaCommandResult<'get_commands'>>;
|
|
333
|
-
/** Loads extensions, skills, prompts and themes again, as pi's `/reload` does. */
|
|
334
|
-
reload(sessionId: string): Promise<void>;
|
|
335
|
-
}
|
|
336
|
-
|
|
337
|
-
/** What a client implements. Events come in batches: one message per frame, however fast the model streams. */
|
|
338
|
-
export interface TaClient {
|
|
339
|
-
onEvents(events: TaEventEnvelope[]): Promise<void>;
|
|
340
|
-
/** Output of a terminal of this connection; with `exitCode`, the terminal has ended. */
|
|
341
|
-
onTerminalData(terminalId: string, data: string, exitCode?: number): Promise<void>;
|
|
342
|
-
/**
|
|
343
|
-
* Keys of the data of a package (setExtensionData) that changed, by this client or another, or by the
|
|
344
|
-
* package on the server; with `cwd`, keys of that directory. It comes for the data this connection
|
|
345
|
-
* read, at most every few hundred milliseconds, with the keys of that time together.
|
|
346
|
-
*/
|
|
347
|
-
onExtensionData(name: string, keys: string[], cwd?: string): Promise<void>;
|
|
348
|
-
/** What happens during a sign-in this connection started (TaAuthServer.login). */
|
|
349
|
-
onAuthEvent(loginId: string, event: TaAuthEvent): Promise<void>;
|
|
350
|
-
/** What happens with the remote machines, once this connection called TaRemoteServer.watch. */
|
|
351
|
-
onRemoteEvent(event: TaRemoteEvent): Promise<void>;
|
|
352
|
-
}
|