@celljs/ta-protocol 4.15.1 → 4.16.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,5 +1,114 @@
1
1
  export declare const TaGatewayServer: unique symbol;
2
2
  export declare const TA_GATEWAY_SERVICE = "TaGatewayServer";
3
+ import type { TaAgentActivity } from './usage-protocol.js';
4
+ /**
5
+ * Who one is on a gateway. `owner`: of TA_GATEWAY_ADMINS, set where the gateway runs, which nobody takes away
6
+ * from the console; manages everything and everyone. `admin`: made one by an owner in the console; manages
7
+ * members and their limits, not owners, other admins or the gateway's defaults. `member`: their own Ta only.
8
+ */
9
+ export type TaGatewayRole = 'owner' | 'admin' | 'member';
10
+ /**
11
+ * What a member may use. In the defaults of the gateway, a limit left out is none; in the limits of one account,
12
+ * one left out is the default's and `null` is none.
13
+ */
14
+ export interface TaGatewayLimits {
15
+ /** Minutes a month their sandbox may run, free. */
16
+ freeMinutes?: number | null;
17
+ /**
18
+ * Tokens a month their agents may take through the models of the gateway (models.json of the gateway), counted
19
+ * by the gateway as it passes the calls; past them, calls are refused until the next month.
20
+ */
21
+ monthlyTokens?: number | null;
22
+ /** Messages a minute they may send their agents (prompts, steering, follow-ups). */
23
+ promptsPerMinute?: number | null;
24
+ /** Pages connected at once. */
25
+ connections?: number | null;
26
+ /** The providers of sandboxes they may pick; all when left out. */
27
+ providers?: string[] | null;
28
+ /** Whether they may run their Ta in a Ta service of their own. */
29
+ own?: boolean | null;
30
+ }
31
+ /** Why one's Ta does not start: suspended by an administrator, or this month's free minutes used up. */
32
+ export type TaQuotaBlock = 'suspended' | 'minutes';
33
+ /** What one used of what one may, this month (of UTC), as one sees it and administrators do. */
34
+ export interface TaQuotaState {
35
+ /** `YYYY-MM`. */
36
+ month: string;
37
+ /** When the month's minutes and tokens start again. */
38
+ resetsAt: number;
39
+ /** Minutes the sandbox ran, as the gateway counts them; `bonus`: given by an administrator this month, on top of `limit`. */
40
+ minutes: {
41
+ used: number;
42
+ limit?: number;
43
+ bonus: number;
44
+ };
45
+ /**
46
+ * Tokens this month. `metered`: counted by the gateway, whose models the sandbox calls through it, and held to
47
+ * `limit`; else as the agents' sessions say, shown only (the sandbox is the member's, its files too).
48
+ */
49
+ tokens: {
50
+ used: number;
51
+ cost: number;
52
+ limit?: number;
53
+ metered: boolean;
54
+ };
55
+ promptsPerMinute?: number;
56
+ connections?: number;
57
+ blocked?: TaQuotaBlock;
58
+ }
59
+ /** One hour of what agents took: tokens and dollars. */
60
+ export interface TaUsagePoint {
61
+ at: number;
62
+ input: number;
63
+ output: number;
64
+ /** Every token, read from a cache or written to one too. */
65
+ tokens: number;
66
+ cost: number;
67
+ turns: number;
68
+ }
69
+ export interface TaUsageShare {
70
+ tokens: number;
71
+ cost: number;
72
+ turns: number;
73
+ }
74
+ /**
75
+ * What the agents of the gateway, or of one account, took since `since`, by hour; a page groups the hours into
76
+ * its own days. A sandbox that does not run answers with what it said last (`stale`).
77
+ */
78
+ export interface TaUsageTrend {
79
+ since: number;
80
+ hours: TaUsagePoint[];
81
+ byModel: (TaUsageShare & {
82
+ model: string;
83
+ })[];
84
+ byTenant: (TaUsageShare & {
85
+ tenantId: string;
86
+ })[];
87
+ /** Tenants whose numbers are those read last, their sandbox not running now. */
88
+ stale: string[];
89
+ readAt: number;
90
+ }
91
+ /** What an administrator did, kept by the gateway (audit.jsonl), newest first. */
92
+ export interface TaGatewayAuditEntry {
93
+ at: number;
94
+ /** The account that did it, or `cli` for `ta gateway link`. */
95
+ actor: string;
96
+ /** The method, such as `setTenantLimits`. */
97
+ action: string;
98
+ /** The account it was done to. */
99
+ target?: string;
100
+ detail?: string;
101
+ }
102
+ /** The defaults of the gateway and who manages it. */
103
+ export interface TaGatewayPolicy {
104
+ defaults: TaGatewayLimits;
105
+ /** Owners (`fixed`, of TA_GATEWAY_ADMINS) and admins made in the console. */
106
+ admins: {
107
+ account: string;
108
+ role: 'owner' | 'admin';
109
+ }[];
110
+ idleMinutes: number;
111
+ }
3
112
  /**
4
113
  * Where the Ta of a tenant runs: a sandbox of the gateway's provider (a container, a machine), or a Ta service
5
114
  * of the user's own. `starting` until it answers; `failed` with `error` when it did not start.
@@ -34,12 +143,89 @@ export interface TaEnvironmentInfo {
34
143
  /** That of a Ta service of the user's; never its token. */
35
144
  url?: string;
36
145
  }
146
+ /** What the sandbox of a tenant takes now, as far as its provider tells (`docker` does): none for a stopped one. */
147
+ export interface TaSandboxUsage {
148
+ /** Percent of one CPU: 150 is one and a half. */
149
+ cpu?: number;
150
+ /** Bytes of memory in use, and the most it may take. */
151
+ memory?: number;
152
+ memoryLimit?: number;
153
+ }
154
+ /**
155
+ * What an agent of a tenant does, as the console shows it: `working` in a turn, `waiting` on a dialog for the
156
+ * user, `asking` the user to decide, else `idle`.
157
+ */
158
+ export type TaAgentStatus = 'working' | 'waiting' | 'asking' | 'idle';
159
+ /** How many conversations a tenant's Ta has open, and how many work or wait for their user now. */
160
+ export interface TaAgentCounts {
161
+ sessions: number;
162
+ working: number;
163
+ waiting: number;
164
+ }
165
+ /** What one conversation of a tenant's Ta has taken so far: pi's statistics of a session. */
166
+ export interface TaAgentStats {
167
+ userMessages: number;
168
+ assistantMessages: number;
169
+ toolCalls: number;
170
+ tokens: {
171
+ input: number;
172
+ output: number;
173
+ cacheRead: number;
174
+ cacheWrite: number;
175
+ total: number;
176
+ };
177
+ /** In dollars, as the model's prices make it; 0 for a model without them. */
178
+ cost: number;
179
+ /** Of its context window, 0 to 100, when known. */
180
+ context?: number;
181
+ }
182
+ /**
183
+ * A conversation open in a tenant's Ta, as an administrator sees it: what runs, on which model, at what cost;
184
+ * never what was said (its first or last message), only a name its user gave it.
185
+ */
186
+ export interface TaAgentSession {
187
+ sessionId: string;
188
+ /** The name its user gave it, if any. */
189
+ name?: string;
190
+ cwd: string;
191
+ /** `<provider>/<model id>`. */
192
+ model?: string;
193
+ status: TaAgentStatus;
194
+ messageCount: number;
195
+ /** Pages attached to it now. */
196
+ attached: number;
197
+ createdAt: number;
198
+ updatedAt: number;
199
+ /** TaOpenSessionOptions.group: a task of the double, a member of a channel. */
200
+ group?: string;
201
+ stats?: TaAgentStats;
202
+ }
203
+ /** The agents of a tenant's Ta, read when asked (getTenantAgents). */
204
+ export interface TaTenantAgents {
205
+ sessions: TaAgentSession[];
206
+ totals: TaAgentCounts & {
207
+ toolCalls: number;
208
+ tokens: number;
209
+ cost: number;
210
+ };
211
+ readAt: number;
212
+ }
37
213
  /** A tenant, as an administrator sees it: one per account, its own sandbox. */
38
214
  export interface TaGatewayTenant {
39
215
  id: string;
40
216
  account: string;
41
217
  name?: string;
218
+ avatar?: string;
42
219
  environment: TaEnvironmentInfo;
220
+ /** Read with the console (getConsole), of a running sandbox whose provider tells it. */
221
+ usage?: TaSandboxUsage;
222
+ /** Read with the console, of a running sandbox of the gateway's; none for a Ta service of the user's. */
223
+ agents?: TaAgentCounts;
224
+ role: TaGatewayRole;
225
+ quota: TaQuotaState;
226
+ /** Its own limits, over the defaults. */
227
+ limits?: TaGatewayLimits;
228
+ suspended?: boolean;
43
229
  /** Browsers connected now. */
44
230
  connections: number;
45
231
  createdAt: number;
@@ -57,8 +243,46 @@ export interface TaGatewayInfo {
57
243
  options: TaEnvironmentOption[];
58
244
  /** Whether a Ta service of one's own may be used (`ownEnvironments` of sandboxes.json). */
59
245
  own: boolean;
60
- /** May let accounts in (TA_GATEWAY_ADMINS) and see the tenants. */
246
+ /** May let accounts in and see the tenants: an owner or an admin. */
61
247
  admin: boolean;
248
+ role: TaGatewayRole;
249
+ /** What one used this month of what one may. */
250
+ quota: TaQuotaState;
251
+ }
252
+ /** A provider of sandboxes, as the console shows it. */
253
+ export interface TaGatewayProvider extends TaEnvironmentOption {
254
+ /** That of tenants that picked none. */
255
+ default: boolean;
256
+ /** The tenants whose Ta it runs. */
257
+ tenants: number;
258
+ /** Whether the console can show the log of a sandbox of it (getTenantLogs). */
259
+ logs: boolean;
260
+ }
261
+ /** The console of a gateway, for its administrators: the gateway, its providers, its tenants. */
262
+ export interface TaGatewayConsole {
263
+ /** Of Ta, which the gateway is part of. */
264
+ version?: string;
265
+ startedAt: number;
266
+ /** TA_PUBLIC_URL: where people reach the gateway. */
267
+ publicUrl?: string;
268
+ providers: TaGatewayProvider[];
269
+ /** Whether users may run their Ta in a Ta service of their own. */
270
+ own: boolean;
271
+ /** Minutes after which a sandbox nobody is connected to stops; 0: it keeps running. */
272
+ idleMinutes: number;
273
+ tenants: TaGatewayTenant[];
274
+ /** Accounts that signed in and wait to be let in (TaAccessServer). */
275
+ requests: number;
276
+ /** That of the one who looks. */
277
+ role: TaGatewayRole;
278
+ policy: TaGatewayPolicy;
279
+ /** The providers of models the gateway gives its sandboxes (models.json of the gateway), without their keys. */
280
+ models: {
281
+ id: string;
282
+ name?: string;
283
+ api: string;
284
+ models: number;
285
+ }[];
62
286
  }
63
287
  /**
64
288
  * `ta gateway`: each account that signs in is a tenant with a Ta of its own, in a sandbox of its own, which
@@ -78,4 +302,46 @@ export interface TaGatewayServer {
78
302
  listTenants(): Promise<TaGatewayTenant[]>;
79
303
  /** For administrators: stops the sandbox of a tenant, which starts again when it connects. */
80
304
  stopTenant(tenantId: string): Promise<void>;
305
+ /** For administrators: the gateway, its providers and its tenants, with what their sandboxes take. */
306
+ getConsole(): Promise<TaGatewayConsole>;
307
+ /** For administrators: starts the sandbox of a tenant, whoever is connected; resolves once its Ta answers. */
308
+ startTenant(tenantId: string): Promise<void>;
309
+ /** For administrators: stops the sandbox of a tenant and starts it again; its browsers connect again. */
310
+ restartTenant(tenantId: string): Promise<void>;
311
+ /** For administrators: the conversations open in the Ta of a tenant, with what each takes; none when its sandbox does not run. */
312
+ getTenantAgents(tenantId: string): Promise<TaTenantAgents>;
313
+ /** For administrators: the last lines (200 by default, 2000 at most) its sandbox wrote, when its provider keeps them. */
314
+ getTenantLogs(tenantId: string, lines?: number): Promise<string>;
315
+ /**
316
+ * For administrators: a link that signs in as the account once, within a day, and lets it in, as
317
+ * `ta gateway link` prints: its path (`/sign-in/link/…`), to put after the address of the gateway.
318
+ */
319
+ createSignInLink(account: string, name?: string): Promise<string>;
320
+ /** For administrators: what agents took, of the gateway or of one tenant, over the last `days` (1 to 31). */
321
+ getUsageTrend(days: number, tenantId?: string): Promise<TaUsageTrend>;
322
+ /** For administrators: the latest tool calls and failures of an agent of a tenant, newest first. */
323
+ getAgentActivity(tenantId: string, sessionId: string): Promise<TaAgentActivity[]>;
324
+ /** For administrators: the defaults and who manages the gateway. */
325
+ getPolicy(): Promise<TaGatewayPolicy>;
326
+ /** For owners: the limits of everyone without their own. */
327
+ setDefaultLimits(limits: TaGatewayLimits): Promise<TaGatewayPolicy>;
328
+ /** For administrators, of a member (owners: of anyone): their own limits over the defaults; `null` drops them. */
329
+ setTenantLimits(tenantId: string, limits: TaGatewayLimits | null): Promise<void>;
330
+ /** For administrators: free minutes this month on top of the limit (negative takes some back, never below none). */
331
+ grantMinutes(tenantId: string, minutes: number): Promise<void>;
332
+ /** For administrators: a suspended account's Ta stops and does not start until it is let go again. */
333
+ setSuspended(tenantId: string, suspended: boolean): Promise<void>;
334
+ /** For owners: makes an account that signed in an admin, or a member again. Owners stay owners. */
335
+ setRole(account: string, role: 'admin' | 'member'): Promise<TaGatewayPolicy>;
336
+ /** For administrators: what administrators did lately, newest first, `limit` at most (100 by default). */
337
+ getAudit(limit?: number): Promise<TaGatewayAuditEntry[]>;
338
+ /**
339
+ * A token of one's own account for another Ta to use one's sandbox as a cloud workspace (`ta://<name>`, its
340
+ * exec server at `/api/exec` of the gateway) or to open one's Ta: a sign-in, listed with one's browsers in
341
+ * Access, signed out there. `url`: TA_PUBLIC_URL, where the gateway is reached.
342
+ */
343
+ createAccessToken(label?: string): Promise<{
344
+ token: string;
345
+ url?: string;
346
+ }>;
81
347
  }
@@ -13,4 +13,5 @@ export * from './settings-protocol.js';
13
13
  export * from './ta-extension-host.js';
14
14
  export * from './ta-protocol.js';
15
15
  export * from './team-protocol.js';
16
+ export * from './usage-protocol.js';
16
17
  export * from './workspace-protocol.js';
@@ -13,5 +13,6 @@ export * from './settings-protocol.js';
13
13
  export * from './ta-extension-host.js';
14
14
  export * from './ta-protocol.js';
15
15
  export * from './team-protocol.js';
16
+ export * from './usage-protocol.js';
16
17
  export * from './workspace-protocol.js';
17
18
  //# sourceMappingURL=index.js.map
@@ -6,6 +6,12 @@
6
6
  */
7
7
  export declare namespace TaLocation {
8
8
  const SSH = "ssh://";
9
+ /**
10
+ * A directory of a cloud workspace: `ta://<name>/<path>`, the sandbox of a Ta gateway (or any Ta service)
11
+ * the user added under that name, reached over its WebSocket (`/api/exec`), not ssh. Its host, as the
12
+ * functions here take it, is `ta://<name>`.
13
+ */
14
+ const CLOUD = "ta://";
9
15
  /** A directory of another machine. */
10
16
  interface Remote {
11
17
  host: string;
@@ -13,6 +19,14 @@ export declare namespace TaLocation {
13
19
  path: string;
14
20
  }
15
21
  function isRemote(location: string): boolean;
22
+ /** Whether a host is a cloud workspace (`ta://<name>`), not one of ssh. */
23
+ function isCloud(host: string | undefined): boolean;
24
+ /** Whether a name may name a cloud workspace: lower-case letters, digits and -, 40 at most. */
25
+ function isCloudName(name: string): boolean;
26
+ /** `ta://<name><path>`. */
27
+ function cloud(name: string, path?: string): string;
28
+ /** The name of a cloud workspace, of its host or of a location there. */
29
+ function cloudName(hostOrLocation: string): string | undefined;
16
30
  /** undefined for a path of the machine of ta serve; throws for an `ssh://` location that is not one. */
17
31
  function parse(location: string): Remote | undefined;
18
32
  function isHost(host: string): boolean;
@@ -31,7 +45,10 @@ export declare namespace TaLocation {
31
45
  * cannot hold (`-i`, `-J`, `-o ProxyCommand=…`) belong in ~/.ssh/config: they come back as `options`.
32
46
  */
33
47
  function readHost(input: string): HostInput;
34
- /** `ssh://<host><path>`; `path` absolute, or empty for the home directory. */
48
+ /**
49
+ * The location of a path on a host: `ssh://<host><path>`, or `ta://<name><path>` for the host of a cloud
50
+ * workspace; `path` absolute, or empty for the home directory.
51
+ */
35
52
  function ssh(host: string, path?: string): string;
36
53
  /**
37
54
  * A host as a list shows it, short: the name of the machine, without the user, the port and the domain
@@ -7,17 +7,58 @@
7
7
  export var TaLocation;
8
8
  (function (TaLocation) {
9
9
  TaLocation.SSH = 'ssh://';
10
+ /**
11
+ * A directory of a cloud workspace: `ta://<name>/<path>`, the sandbox of a Ta gateway (or any Ta service)
12
+ * the user added under that name, reached over its WebSocket (`/api/exec`), not ssh. Its host, as the
13
+ * functions here take it, is `ta://<name>`.
14
+ */
15
+ TaLocation.CLOUD = 'ta://';
16
+ const CLOUD_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
10
17
  /** Letters, digits and `_ . @ : % + - [ ]`, not first a `-`: ssh must not read a host as an option. */
11
18
  const HOST = /^(?!-)[\w.@:%+[\]-]+$/;
12
19
  function isRemote(location) {
13
- return location.startsWith(TaLocation.SSH);
20
+ return location.startsWith(TaLocation.SSH) || location.startsWith(TaLocation.CLOUD);
14
21
  }
15
22
  TaLocation.isRemote = isRemote;
23
+ /** Whether a host is a cloud workspace (`ta://<name>`), not one of ssh. */
24
+ function isCloud(host) {
25
+ return !!host && host.startsWith(TaLocation.CLOUD);
26
+ }
27
+ TaLocation.isCloud = isCloud;
28
+ /** Whether a name may name a cloud workspace: lower-case letters, digits and -, 40 at most. */
29
+ function isCloudName(name) {
30
+ return CLOUD_NAME.test(name);
31
+ }
32
+ TaLocation.isCloudName = isCloudName;
33
+ /** `ta://<name><path>`. */
34
+ function cloud(name, path = '') {
35
+ return `${TaLocation.CLOUD}${name}${path ? normalize(path) : ''}`;
36
+ }
37
+ TaLocation.cloud = cloud;
38
+ /** The name of a cloud workspace, of its host or of a location there. */
39
+ function cloudName(hostOrLocation) {
40
+ if (!hostOrLocation.startsWith(TaLocation.CLOUD)) {
41
+ return undefined;
42
+ }
43
+ const rest = hostOrLocation.slice(TaLocation.CLOUD.length);
44
+ const slash = rest.indexOf('/');
45
+ return slash < 0 ? rest : rest.slice(0, slash);
46
+ }
47
+ TaLocation.cloudName = cloudName;
16
48
  /** undefined for a path of the machine of ta serve; throws for an `ssh://` location that is not one. */
17
49
  function parse(location) {
50
+ var _a;
18
51
  if (!isRemote(location)) {
19
52
  return undefined;
20
53
  }
54
+ if (location.startsWith(TaLocation.CLOUD)) {
55
+ const name = (_a = cloudName(location)) !== null && _a !== void 0 ? _a : '';
56
+ if (!isCloudName(name)) {
57
+ throw new Error(`${JSON.stringify(location)} names no cloud workspace: write ta://<name>/<path>.`);
58
+ }
59
+ const path = location.slice(TaLocation.CLOUD.length + name.length);
60
+ return { host: `${TaLocation.CLOUD}${name}`, path: path ? normalize(path) : '' };
61
+ }
21
62
  const rest = location.slice(TaLocation.SSH.length);
22
63
  const slash = rest.indexOf('/');
23
64
  const host = slash < 0 ? rest : rest.slice(0, slash);
@@ -29,7 +70,7 @@ export var TaLocation;
29
70
  }
30
71
  TaLocation.parse = parse;
31
72
  function isHost(host) {
32
- return HOST.test(host);
73
+ return isCloud(host) ? isCloudName(host.slice(TaLocation.CLOUD.length)) : HOST.test(host);
33
74
  }
34
75
  TaLocation.isHost = isHost;
35
76
  /** Options of ssh without a value, which change nothing for Ta. */
@@ -109,9 +150,12 @@ export var TaLocation;
109
150
  return isHost(host) ? { host } : { error: 'invalid' };
110
151
  }
111
152
  TaLocation.readHost = readHost;
112
- /** `ssh://<host><path>`; `path` absolute, or empty for the home directory. */
153
+ /**
154
+ * The location of a path on a host: `ssh://<host><path>`, or `ta://<name><path>` for the host of a cloud
155
+ * workspace; `path` absolute, or empty for the home directory.
156
+ */
113
157
  function ssh(host, path = '') {
114
- return `${TaLocation.SSH}${host}${path ? normalize(path) : ''}`;
158
+ return isCloud(host) ? `${host}${path ? normalize(path) : ''}` : `${TaLocation.SSH}${host}${path ? normalize(path) : ''}`;
115
159
  }
116
160
  TaLocation.ssh = ssh;
117
161
  /**
@@ -119,6 +163,9 @@ export var TaLocation;
119
163
  * (`me@dev.example.com:2222` is `dev`); an address whole.
120
164
  */
121
165
  function hostLabel(host) {
166
+ if (isCloud(host)) {
167
+ return host.slice(TaLocation.CLOUD.length);
168
+ }
122
169
  const name = host
123
170
  .replace(/^[^@]*@/, '')
124
171
  .replace(/^\[(.*)\](?::\d+)?$/, '$1')
@@ -1,11 +1,13 @@
1
1
  export declare const TaRemoteServer: unique symbol;
2
2
  export declare const TA_REMOTE_SERVICE = "TaRemoteServer";
3
- /** A machine ta serve can reach with ssh. */
3
+ /** A machine ta serve can reach with ssh, or a cloud workspace it reaches over a WebSocket. */
4
4
  export interface TaRemoteHost {
5
- /** What follows `ssh://` in a location (TaLocation). */
5
+ /** What follows `ssh://` in a location (TaLocation), or `ta://<name>` for a cloud workspace. */
6
6
  host: string;
7
- /** A Host of ~/.ssh/config, or one opened before. */
8
- source: 'config' | 'recent';
7
+ /** A Host of ~/.ssh/config, one opened before, or a cloud workspace added (TaRemoteServer.addCloudHost). */
8
+ source: 'config' | 'recent' | 'cloud';
9
+ /** Of a cloud workspace: the address of its Ta gateway or Ta service, never its token. */
10
+ url?: string;
9
11
  /** ta serve is connected to it now. */
10
12
  connected: boolean;
11
13
  }
@@ -67,6 +69,12 @@ export interface TaRemoteServer {
67
69
  addHost(host: string): Promise<void>;
68
70
  /** Disconnects from a host and drops it from the list; one of ~/.ssh/config stays there. */
69
71
  removeHost(host: string): Promise<void>;
72
+ /**
73
+ * A cloud workspace, `ta://<name>`: the sandbox of the account of `token` on the Ta gateway at `url` (or the
74
+ * machine of a Ta service, with its token), whose directories conversations work in while the agent stays here.
75
+ * Checked by connecting first; kept with its token, which never comes back.
76
+ */
77
+ addCloudHost(name: string, url: string, token: string): Promise<TaRemoteHost>;
70
78
  /**
71
79
  * A location as the user wrote it, whole: `~/src`, `ssh://<host>` (its home), `ssh://<host>/~/src`, or a path
72
80
  * relative to the default directory; one already whole as it is. Connects to the host when it needs its home.
@@ -80,6 +80,8 @@ export declare const TaErrorCode: {
80
80
  readonly NOT_SIGNED_IN: 'CELL_TA_NOT_SIGNED_IN';
81
81
  /** Behind a gateway (`ta gateway`): the environment of the tenant did not start; TaGatewayServer changes or restarts it. */
82
82
  readonly ENVIRONMENT_FAILED: 'CELL_TA_ENVIRONMENT_FAILED';
83
+ /** Behind a gateway: more messages a minute than one may send; try again in a moment. */
84
+ readonly RATE_LIMITED: 'CELL_TA_RATE_LIMITED';
83
85
  /** One let in by the user (docs/design/ta-team.md) may not do this: `data` says the action it needs (TaForbiddenData). */
84
86
  readonly FORBIDDEN: 'CELL_TA_FORBIDDEN';
85
87
  /** As many runs of people let in go as the owner lets at once (docs/design/ta-team.md 9): try again once one ended. */
@@ -34,6 +34,8 @@ export const TaErrorCode = {
34
34
  NOT_SIGNED_IN: 'CELL_TA_NOT_SIGNED_IN',
35
35
  /** Behind a gateway (`ta gateway`): the environment of the tenant did not start; TaGatewayServer changes or restarts it. */
36
36
  ENVIRONMENT_FAILED: 'CELL_TA_ENVIRONMENT_FAILED',
37
+ /** Behind a gateway: more messages a minute than one may send; try again in a moment. */
38
+ RATE_LIMITED: 'CELL_TA_RATE_LIMITED',
37
39
  /** One let in by the user (docs/design/ta-team.md) may not do this: `data` says the action it needs (TaForbiddenData). */
38
40
  FORBIDDEN: 'CELL_TA_FORBIDDEN',
39
41
  /** As many runs of people let in go as the owner lets at once (docs/design/ta-team.md 9): try again once one ended. */
@@ -0,0 +1,42 @@
1
+ export declare const TaUsageServer: unique symbol;
2
+ export declare const TA_USAGE_SERVICE = "TaUsageServer";
3
+ /** What the turns of a model took in one hour (`at`, its start), from the sessions of this Ta. */
4
+ export interface TaUsageBucket {
5
+ at: number;
6
+ /** `<provider>/<model id>`. */
7
+ model: string;
8
+ input: number;
9
+ output: number;
10
+ cacheRead: number;
11
+ cacheWrite: number;
12
+ /** In dollars, as the model's prices make it. */
13
+ cost: number;
14
+ /** Answers of the model. */
15
+ turns: number;
16
+ }
17
+ /**
18
+ * Something an agent did lately, as one watching it sees it: a tool it called (its name, whether it worked, how
19
+ * long it took) or a call of the model that failed. Never its arguments or what it returned; of an error, its first
20
+ * line, cut short.
21
+ */
22
+ export interface TaAgentActivity {
23
+ at: number;
24
+ kind: 'tool' | 'model';
25
+ /** The tool's name, or the model's. */
26
+ name: string;
27
+ ok: boolean;
28
+ /** A tool call without its result yet. */
29
+ running?: boolean;
30
+ error?: string;
31
+ ms?: number;
32
+ }
33
+ /**
34
+ * What the agents of this Ta took and did, read from the files of its sessions: for a gateway's console, and
35
+ * any page that shows spending. Nothing said in them leaves.
36
+ */
37
+ export interface TaUsageServer {
38
+ /** The hours since `since` (a time), by model; an hour with nothing is left out. */
39
+ getUsage(since: number): Promise<TaUsageBucket[]>;
40
+ /** The latest of what the agent of an open session did, newest first, `limit` at most (50 by default, 200 at most). */
41
+ getActivity(sessionId: string, limit?: number): Promise<TaAgentActivity[]>;
42
+ }
@@ -0,0 +1,3 @@
1
+ export const TaUsageServer = Symbol('TaUsageServer');
2
+ export const TA_USAGE_SERVICE = 'TaUsageServer';
3
+ //# sourceMappingURL=usage-protocol.js.map
@@ -1,5 +1,114 @@
1
1
  export declare const TaGatewayServer: unique symbol;
2
2
  export declare const TA_GATEWAY_SERVICE = "TaGatewayServer";
3
+ import type { TaAgentActivity } from './usage-protocol';
4
+ /**
5
+ * Who one is on a gateway. `owner`: of TA_GATEWAY_ADMINS, set where the gateway runs, which nobody takes away
6
+ * from the console; manages everything and everyone. `admin`: made one by an owner in the console; manages
7
+ * members and their limits, not owners, other admins or the gateway's defaults. `member`: their own Ta only.
8
+ */
9
+ export type TaGatewayRole = 'owner' | 'admin' | 'member';
10
+ /**
11
+ * What a member may use. In the defaults of the gateway, a limit left out is none; in the limits of one account,
12
+ * one left out is the default's and `null` is none.
13
+ */
14
+ export interface TaGatewayLimits {
15
+ /** Minutes a month their sandbox may run, free. */
16
+ freeMinutes?: number | null;
17
+ /**
18
+ * Tokens a month their agents may take through the models of the gateway (models.json of the gateway), counted
19
+ * by the gateway as it passes the calls; past them, calls are refused until the next month.
20
+ */
21
+ monthlyTokens?: number | null;
22
+ /** Messages a minute they may send their agents (prompts, steering, follow-ups). */
23
+ promptsPerMinute?: number | null;
24
+ /** Pages connected at once. */
25
+ connections?: number | null;
26
+ /** The providers of sandboxes they may pick; all when left out. */
27
+ providers?: string[] | null;
28
+ /** Whether they may run their Ta in a Ta service of their own. */
29
+ own?: boolean | null;
30
+ }
31
+ /** Why one's Ta does not start: suspended by an administrator, or this month's free minutes used up. */
32
+ export type TaQuotaBlock = 'suspended' | 'minutes';
33
+ /** What one used of what one may, this month (of UTC), as one sees it and administrators do. */
34
+ export interface TaQuotaState {
35
+ /** `YYYY-MM`. */
36
+ month: string;
37
+ /** When the month's minutes and tokens start again. */
38
+ resetsAt: number;
39
+ /** Minutes the sandbox ran, as the gateway counts them; `bonus`: given by an administrator this month, on top of `limit`. */
40
+ minutes: {
41
+ used: number;
42
+ limit?: number;
43
+ bonus: number;
44
+ };
45
+ /**
46
+ * Tokens this month. `metered`: counted by the gateway, whose models the sandbox calls through it, and held to
47
+ * `limit`; else as the agents' sessions say, shown only (the sandbox is the member's, its files too).
48
+ */
49
+ tokens: {
50
+ used: number;
51
+ cost: number;
52
+ limit?: number;
53
+ metered: boolean;
54
+ };
55
+ promptsPerMinute?: number;
56
+ connections?: number;
57
+ blocked?: TaQuotaBlock;
58
+ }
59
+ /** One hour of what agents took: tokens and dollars. */
60
+ export interface TaUsagePoint {
61
+ at: number;
62
+ input: number;
63
+ output: number;
64
+ /** Every token, read from a cache or written to one too. */
65
+ tokens: number;
66
+ cost: number;
67
+ turns: number;
68
+ }
69
+ export interface TaUsageShare {
70
+ tokens: number;
71
+ cost: number;
72
+ turns: number;
73
+ }
74
+ /**
75
+ * What the agents of the gateway, or of one account, took since `since`, by hour; a page groups the hours into
76
+ * its own days. A sandbox that does not run answers with what it said last (`stale`).
77
+ */
78
+ export interface TaUsageTrend {
79
+ since: number;
80
+ hours: TaUsagePoint[];
81
+ byModel: (TaUsageShare & {
82
+ model: string;
83
+ })[];
84
+ byTenant: (TaUsageShare & {
85
+ tenantId: string;
86
+ })[];
87
+ /** Tenants whose numbers are those read last, their sandbox not running now. */
88
+ stale: string[];
89
+ readAt: number;
90
+ }
91
+ /** What an administrator did, kept by the gateway (audit.jsonl), newest first. */
92
+ export interface TaGatewayAuditEntry {
93
+ at: number;
94
+ /** The account that did it, or `cli` for `ta gateway link`. */
95
+ actor: string;
96
+ /** The method, such as `setTenantLimits`. */
97
+ action: string;
98
+ /** The account it was done to. */
99
+ target?: string;
100
+ detail?: string;
101
+ }
102
+ /** The defaults of the gateway and who manages it. */
103
+ export interface TaGatewayPolicy {
104
+ defaults: TaGatewayLimits;
105
+ /** Owners (`fixed`, of TA_GATEWAY_ADMINS) and admins made in the console. */
106
+ admins: {
107
+ account: string;
108
+ role: 'owner' | 'admin';
109
+ }[];
110
+ idleMinutes: number;
111
+ }
3
112
  /**
4
113
  * Where the Ta of a tenant runs: a sandbox of the gateway's provider (a container, a machine), or a Ta service
5
114
  * of the user's own. `starting` until it answers; `failed` with `error` when it did not start.
@@ -34,12 +143,89 @@ export interface TaEnvironmentInfo {
34
143
  /** That of a Ta service of the user's; never its token. */
35
144
  url?: string;
36
145
  }
146
+ /** What the sandbox of a tenant takes now, as far as its provider tells (`docker` does): none for a stopped one. */
147
+ export interface TaSandboxUsage {
148
+ /** Percent of one CPU: 150 is one and a half. */
149
+ cpu?: number;
150
+ /** Bytes of memory in use, and the most it may take. */
151
+ memory?: number;
152
+ memoryLimit?: number;
153
+ }
154
+ /**
155
+ * What an agent of a tenant does, as the console shows it: `working` in a turn, `waiting` on a dialog for the
156
+ * user, `asking` the user to decide, else `idle`.
157
+ */
158
+ export type TaAgentStatus = 'working' | 'waiting' | 'asking' | 'idle';
159
+ /** How many conversations a tenant's Ta has open, and how many work or wait for their user now. */
160
+ export interface TaAgentCounts {
161
+ sessions: number;
162
+ working: number;
163
+ waiting: number;
164
+ }
165
+ /** What one conversation of a tenant's Ta has taken so far: pi's statistics of a session. */
166
+ export interface TaAgentStats {
167
+ userMessages: number;
168
+ assistantMessages: number;
169
+ toolCalls: number;
170
+ tokens: {
171
+ input: number;
172
+ output: number;
173
+ cacheRead: number;
174
+ cacheWrite: number;
175
+ total: number;
176
+ };
177
+ /** In dollars, as the model's prices make it; 0 for a model without them. */
178
+ cost: number;
179
+ /** Of its context window, 0 to 100, when known. */
180
+ context?: number;
181
+ }
182
+ /**
183
+ * A conversation open in a tenant's Ta, as an administrator sees it: what runs, on which model, at what cost;
184
+ * never what was said (its first or last message), only a name its user gave it.
185
+ */
186
+ export interface TaAgentSession {
187
+ sessionId: string;
188
+ /** The name its user gave it, if any. */
189
+ name?: string;
190
+ cwd: string;
191
+ /** `<provider>/<model id>`. */
192
+ model?: string;
193
+ status: TaAgentStatus;
194
+ messageCount: number;
195
+ /** Pages attached to it now. */
196
+ attached: number;
197
+ createdAt: number;
198
+ updatedAt: number;
199
+ /** TaOpenSessionOptions.group: a task of the double, a member of a channel. */
200
+ group?: string;
201
+ stats?: TaAgentStats;
202
+ }
203
+ /** The agents of a tenant's Ta, read when asked (getTenantAgents). */
204
+ export interface TaTenantAgents {
205
+ sessions: TaAgentSession[];
206
+ totals: TaAgentCounts & {
207
+ toolCalls: number;
208
+ tokens: number;
209
+ cost: number;
210
+ };
211
+ readAt: number;
212
+ }
37
213
  /** A tenant, as an administrator sees it: one per account, its own sandbox. */
38
214
  export interface TaGatewayTenant {
39
215
  id: string;
40
216
  account: string;
41
217
  name?: string;
218
+ avatar?: string;
42
219
  environment: TaEnvironmentInfo;
220
+ /** Read with the console (getConsole), of a running sandbox whose provider tells it. */
221
+ usage?: TaSandboxUsage;
222
+ /** Read with the console, of a running sandbox of the gateway's; none for a Ta service of the user's. */
223
+ agents?: TaAgentCounts;
224
+ role: TaGatewayRole;
225
+ quota: TaQuotaState;
226
+ /** Its own limits, over the defaults. */
227
+ limits?: TaGatewayLimits;
228
+ suspended?: boolean;
43
229
  /** Browsers connected now. */
44
230
  connections: number;
45
231
  createdAt: number;
@@ -57,8 +243,46 @@ export interface TaGatewayInfo {
57
243
  options: TaEnvironmentOption[];
58
244
  /** Whether a Ta service of one's own may be used (`ownEnvironments` of sandboxes.json). */
59
245
  own: boolean;
60
- /** May let accounts in (TA_GATEWAY_ADMINS) and see the tenants. */
246
+ /** May let accounts in and see the tenants: an owner or an admin. */
61
247
  admin: boolean;
248
+ role: TaGatewayRole;
249
+ /** What one used this month of what one may. */
250
+ quota: TaQuotaState;
251
+ }
252
+ /** A provider of sandboxes, as the console shows it. */
253
+ export interface TaGatewayProvider extends TaEnvironmentOption {
254
+ /** That of tenants that picked none. */
255
+ default: boolean;
256
+ /** The tenants whose Ta it runs. */
257
+ tenants: number;
258
+ /** Whether the console can show the log of a sandbox of it (getTenantLogs). */
259
+ logs: boolean;
260
+ }
261
+ /** The console of a gateway, for its administrators: the gateway, its providers, its tenants. */
262
+ export interface TaGatewayConsole {
263
+ /** Of Ta, which the gateway is part of. */
264
+ version?: string;
265
+ startedAt: number;
266
+ /** TA_PUBLIC_URL: where people reach the gateway. */
267
+ publicUrl?: string;
268
+ providers: TaGatewayProvider[];
269
+ /** Whether users may run their Ta in a Ta service of their own. */
270
+ own: boolean;
271
+ /** Minutes after which a sandbox nobody is connected to stops; 0: it keeps running. */
272
+ idleMinutes: number;
273
+ tenants: TaGatewayTenant[];
274
+ /** Accounts that signed in and wait to be let in (TaAccessServer). */
275
+ requests: number;
276
+ /** That of the one who looks. */
277
+ role: TaGatewayRole;
278
+ policy: TaGatewayPolicy;
279
+ /** The providers of models the gateway gives its sandboxes (models.json of the gateway), without their keys. */
280
+ models: {
281
+ id: string;
282
+ name?: string;
283
+ api: string;
284
+ models: number;
285
+ }[];
62
286
  }
63
287
  /**
64
288
  * `ta gateway`: each account that signs in is a tenant with a Ta of its own, in a sandbox of its own, which
@@ -78,5 +302,47 @@ export interface TaGatewayServer {
78
302
  listTenants(): Promise<TaGatewayTenant[]>;
79
303
  /** For administrators: stops the sandbox of a tenant, which starts again when it connects. */
80
304
  stopTenant(tenantId: string): Promise<void>;
305
+ /** For administrators: the gateway, its providers and its tenants, with what their sandboxes take. */
306
+ getConsole(): Promise<TaGatewayConsole>;
307
+ /** For administrators: starts the sandbox of a tenant, whoever is connected; resolves once its Ta answers. */
308
+ startTenant(tenantId: string): Promise<void>;
309
+ /** For administrators: stops the sandbox of a tenant and starts it again; its browsers connect again. */
310
+ restartTenant(tenantId: string): Promise<void>;
311
+ /** For administrators: the conversations open in the Ta of a tenant, with what each takes; none when its sandbox does not run. */
312
+ getTenantAgents(tenantId: string): Promise<TaTenantAgents>;
313
+ /** For administrators: the last lines (200 by default, 2000 at most) its sandbox wrote, when its provider keeps them. */
314
+ getTenantLogs(tenantId: string, lines?: number): Promise<string>;
315
+ /**
316
+ * For administrators: a link that signs in as the account once, within a day, and lets it in, as
317
+ * `ta gateway link` prints: its path (`/sign-in/link/…`), to put after the address of the gateway.
318
+ */
319
+ createSignInLink(account: string, name?: string): Promise<string>;
320
+ /** For administrators: what agents took, of the gateway or of one tenant, over the last `days` (1 to 31). */
321
+ getUsageTrend(days: number, tenantId?: string): Promise<TaUsageTrend>;
322
+ /** For administrators: the latest tool calls and failures of an agent of a tenant, newest first. */
323
+ getAgentActivity(tenantId: string, sessionId: string): Promise<TaAgentActivity[]>;
324
+ /** For administrators: the defaults and who manages the gateway. */
325
+ getPolicy(): Promise<TaGatewayPolicy>;
326
+ /** For owners: the limits of everyone without their own. */
327
+ setDefaultLimits(limits: TaGatewayLimits): Promise<TaGatewayPolicy>;
328
+ /** For administrators, of a member (owners: of anyone): their own limits over the defaults; `null` drops them. */
329
+ setTenantLimits(tenantId: string, limits: TaGatewayLimits | null): Promise<void>;
330
+ /** For administrators: free minutes this month on top of the limit (negative takes some back, never below none). */
331
+ grantMinutes(tenantId: string, minutes: number): Promise<void>;
332
+ /** For administrators: a suspended account's Ta stops and does not start until it is let go again. */
333
+ setSuspended(tenantId: string, suspended: boolean): Promise<void>;
334
+ /** For owners: makes an account that signed in an admin, or a member again. Owners stay owners. */
335
+ setRole(account: string, role: 'admin' | 'member'): Promise<TaGatewayPolicy>;
336
+ /** For administrators: what administrators did lately, newest first, `limit` at most (100 by default). */
337
+ getAudit(limit?: number): Promise<TaGatewayAuditEntry[]>;
338
+ /**
339
+ * A token of one's own account for another Ta to use one's sandbox as a cloud workspace (`ta://<name>`, its
340
+ * exec server at `/api/exec` of the gateway) or to open one's Ta: a sign-in, listed with one's browsers in
341
+ * Access, signed out there. `url`: TA_PUBLIC_URL, where the gateway is reached.
342
+ */
343
+ createAccessToken(label?: string): Promise<{
344
+ token: string;
345
+ url?: string;
346
+ }>;
81
347
  }
82
348
  //# sourceMappingURL=gateway-protocol.d.ts.map
@@ -13,5 +13,6 @@ export * from './settings-protocol';
13
13
  export * from './ta-extension-host';
14
14
  export * from './ta-protocol';
15
15
  export * from './team-protocol';
16
+ export * from './usage-protocol';
16
17
  export * from './workspace-protocol';
17
18
  //# sourceMappingURL=index.d.ts.map
@@ -29,5 +29,6 @@ __exportStar(require("./settings-protocol"), exports);
29
29
  __exportStar(require("./ta-extension-host"), exports);
30
30
  __exportStar(require("./ta-protocol"), exports);
31
31
  __exportStar(require("./team-protocol"), exports);
32
+ __exportStar(require("./usage-protocol"), exports);
32
33
  __exportStar(require("./workspace-protocol"), exports);
33
34
  //# sourceMappingURL=index.js.map
@@ -6,6 +6,12 @@
6
6
  */
7
7
  export declare namespace TaLocation {
8
8
  const SSH = "ssh://";
9
+ /**
10
+ * A directory of a cloud workspace: `ta://<name>/<path>`, the sandbox of a Ta gateway (or any Ta service)
11
+ * the user added under that name, reached over its WebSocket (`/api/exec`), not ssh. Its host, as the
12
+ * functions here take it, is `ta://<name>`.
13
+ */
14
+ const CLOUD = "ta://";
9
15
  /** A directory of another machine. */
10
16
  interface Remote {
11
17
  host: string;
@@ -13,6 +19,14 @@ export declare namespace TaLocation {
13
19
  path: string;
14
20
  }
15
21
  function isRemote(location: string): boolean;
22
+ /** Whether a host is a cloud workspace (`ta://<name>`), not one of ssh. */
23
+ function isCloud(host: string | undefined): boolean;
24
+ /** Whether a name may name a cloud workspace: lower-case letters, digits and -, 40 at most. */
25
+ function isCloudName(name: string): boolean;
26
+ /** `ta://<name><path>`. */
27
+ function cloud(name: string, path?: string): string;
28
+ /** The name of a cloud workspace, of its host or of a location there. */
29
+ function cloudName(hostOrLocation: string): string | undefined;
16
30
  /** undefined for a path of the machine of ta serve; throws for an `ssh://` location that is not one. */
17
31
  function parse(location: string): Remote | undefined;
18
32
  function isHost(host: string): boolean;
@@ -31,7 +45,10 @@ export declare namespace TaLocation {
31
45
  * cannot hold (`-i`, `-J`, `-o ProxyCommand=…`) belong in ~/.ssh/config: they come back as `options`.
32
46
  */
33
47
  function readHost(input: string): HostInput;
34
- /** `ssh://<host><path>`; `path` absolute, or empty for the home directory. */
48
+ /**
49
+ * The location of a path on a host: `ssh://<host><path>`, or `ta://<name><path>` for the host of a cloud
50
+ * workspace; `path` absolute, or empty for the home directory.
51
+ */
35
52
  function ssh(host: string, path?: string): string;
36
53
  /**
37
54
  * A host as a list shows it, short: the name of the machine, without the user, the port and the domain
@@ -10,17 +10,58 @@ exports.TaLocation = void 0;
10
10
  var TaLocation;
11
11
  (function (TaLocation) {
12
12
  TaLocation.SSH = 'ssh://';
13
+ /**
14
+ * A directory of a cloud workspace: `ta://<name>/<path>`, the sandbox of a Ta gateway (or any Ta service)
15
+ * the user added under that name, reached over its WebSocket (`/api/exec`), not ssh. Its host, as the
16
+ * functions here take it, is `ta://<name>`.
17
+ */
18
+ TaLocation.CLOUD = 'ta://';
19
+ const CLOUD_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
13
20
  /** Letters, digits and `_ . @ : % + - [ ]`, not first a `-`: ssh must not read a host as an option. */
14
21
  const HOST = /^(?!-)[\w.@:%+[\]-]+$/;
15
22
  function isRemote(location) {
16
- return location.startsWith(TaLocation.SSH);
23
+ return location.startsWith(TaLocation.SSH) || location.startsWith(TaLocation.CLOUD);
17
24
  }
18
25
  TaLocation.isRemote = isRemote;
26
+ /** Whether a host is a cloud workspace (`ta://<name>`), not one of ssh. */
27
+ function isCloud(host) {
28
+ return !!host && host.startsWith(TaLocation.CLOUD);
29
+ }
30
+ TaLocation.isCloud = isCloud;
31
+ /** Whether a name may name a cloud workspace: lower-case letters, digits and -, 40 at most. */
32
+ function isCloudName(name) {
33
+ return CLOUD_NAME.test(name);
34
+ }
35
+ TaLocation.isCloudName = isCloudName;
36
+ /** `ta://<name><path>`. */
37
+ function cloud(name, path = '') {
38
+ return `${TaLocation.CLOUD}${name}${path ? normalize(path) : ''}`;
39
+ }
40
+ TaLocation.cloud = cloud;
41
+ /** The name of a cloud workspace, of its host or of a location there. */
42
+ function cloudName(hostOrLocation) {
43
+ if (!hostOrLocation.startsWith(TaLocation.CLOUD)) {
44
+ return undefined;
45
+ }
46
+ const rest = hostOrLocation.slice(TaLocation.CLOUD.length);
47
+ const slash = rest.indexOf('/');
48
+ return slash < 0 ? rest : rest.slice(0, slash);
49
+ }
50
+ TaLocation.cloudName = cloudName;
19
51
  /** undefined for a path of the machine of ta serve; throws for an `ssh://` location that is not one. */
20
52
  function parse(location) {
53
+ var _a;
21
54
  if (!isRemote(location)) {
22
55
  return undefined;
23
56
  }
57
+ if (location.startsWith(TaLocation.CLOUD)) {
58
+ const name = (_a = cloudName(location)) !== null && _a !== void 0 ? _a : '';
59
+ if (!isCloudName(name)) {
60
+ throw new Error(`${JSON.stringify(location)} names no cloud workspace: write ta://<name>/<path>.`);
61
+ }
62
+ const path = location.slice(TaLocation.CLOUD.length + name.length);
63
+ return { host: `${TaLocation.CLOUD}${name}`, path: path ? normalize(path) : '' };
64
+ }
24
65
  const rest = location.slice(TaLocation.SSH.length);
25
66
  const slash = rest.indexOf('/');
26
67
  const host = slash < 0 ? rest : rest.slice(0, slash);
@@ -32,7 +73,7 @@ var TaLocation;
32
73
  }
33
74
  TaLocation.parse = parse;
34
75
  function isHost(host) {
35
- return HOST.test(host);
76
+ return isCloud(host) ? isCloudName(host.slice(TaLocation.CLOUD.length)) : HOST.test(host);
36
77
  }
37
78
  TaLocation.isHost = isHost;
38
79
  /** Options of ssh without a value, which change nothing for Ta. */
@@ -112,9 +153,12 @@ var TaLocation;
112
153
  return isHost(host) ? { host } : { error: 'invalid' };
113
154
  }
114
155
  TaLocation.readHost = readHost;
115
- /** `ssh://<host><path>`; `path` absolute, or empty for the home directory. */
156
+ /**
157
+ * The location of a path on a host: `ssh://<host><path>`, or `ta://<name><path>` for the host of a cloud
158
+ * workspace; `path` absolute, or empty for the home directory.
159
+ */
116
160
  function ssh(host, path = '') {
117
- return `${TaLocation.SSH}${host}${path ? normalize(path) : ''}`;
161
+ return isCloud(host) ? `${host}${path ? normalize(path) : ''}` : `${TaLocation.SSH}${host}${path ? normalize(path) : ''}`;
118
162
  }
119
163
  TaLocation.ssh = ssh;
120
164
  /**
@@ -122,6 +166,9 @@ var TaLocation;
122
166
  * (`me@dev.example.com:2222` is `dev`); an address whole.
123
167
  */
124
168
  function hostLabel(host) {
169
+ if (isCloud(host)) {
170
+ return host.slice(TaLocation.CLOUD.length);
171
+ }
125
172
  const name = host
126
173
  .replace(/^[^@]*@/, '')
127
174
  .replace(/^\[(.*)\](?::\d+)?$/, '$1')
@@ -1,11 +1,13 @@
1
1
  export declare const TaRemoteServer: unique symbol;
2
2
  export declare const TA_REMOTE_SERVICE = "TaRemoteServer";
3
- /** A machine ta serve can reach with ssh. */
3
+ /** A machine ta serve can reach with ssh, or a cloud workspace it reaches over a WebSocket. */
4
4
  export interface TaRemoteHost {
5
- /** What follows `ssh://` in a location (TaLocation). */
5
+ /** What follows `ssh://` in a location (TaLocation), or `ta://<name>` for a cloud workspace. */
6
6
  host: string;
7
- /** A Host of ~/.ssh/config, or one opened before. */
8
- source: 'config' | 'recent';
7
+ /** A Host of ~/.ssh/config, one opened before, or a cloud workspace added (TaRemoteServer.addCloudHost). */
8
+ source: 'config' | 'recent' | 'cloud';
9
+ /** Of a cloud workspace: the address of its Ta gateway or Ta service, never its token. */
10
+ url?: string;
9
11
  /** ta serve is connected to it now. */
10
12
  connected: boolean;
11
13
  }
@@ -67,6 +69,12 @@ export interface TaRemoteServer {
67
69
  addHost(host: string): Promise<void>;
68
70
  /** Disconnects from a host and drops it from the list; one of ~/.ssh/config stays there. */
69
71
  removeHost(host: string): Promise<void>;
72
+ /**
73
+ * A cloud workspace, `ta://<name>`: the sandbox of the account of `token` on the Ta gateway at `url` (or the
74
+ * machine of a Ta service, with its token), whose directories conversations work in while the agent stays here.
75
+ * Checked by connecting first; kept with its token, which never comes back.
76
+ */
77
+ addCloudHost(name: string, url: string, token: string): Promise<TaRemoteHost>;
70
78
  /**
71
79
  * A location as the user wrote it, whole: `~/src`, `ssh://<host>` (its home), `ssh://<host>/~/src`, or a path
72
80
  * relative to the default directory; one already whole as it is. Connects to the host when it needs its home.
@@ -80,6 +80,8 @@ export declare const TaErrorCode: {
80
80
  readonly NOT_SIGNED_IN: 'CELL_TA_NOT_SIGNED_IN';
81
81
  /** Behind a gateway (`ta gateway`): the environment of the tenant did not start; TaGatewayServer changes or restarts it. */
82
82
  readonly ENVIRONMENT_FAILED: 'CELL_TA_ENVIRONMENT_FAILED';
83
+ /** Behind a gateway: more messages a minute than one may send; try again in a moment. */
84
+ readonly RATE_LIMITED: 'CELL_TA_RATE_LIMITED';
83
85
  /** One let in by the user (docs/design/ta-team.md) may not do this: `data` says the action it needs (TaForbiddenData). */
84
86
  readonly FORBIDDEN: 'CELL_TA_FORBIDDEN';
85
87
  /** As many runs of people let in go as the owner lets at once (docs/design/ta-team.md 9): try again once one ended. */
@@ -37,6 +37,8 @@ exports.TaErrorCode = {
37
37
  NOT_SIGNED_IN: 'CELL_TA_NOT_SIGNED_IN',
38
38
  /** Behind a gateway (`ta gateway`): the environment of the tenant did not start; TaGatewayServer changes or restarts it. */
39
39
  ENVIRONMENT_FAILED: 'CELL_TA_ENVIRONMENT_FAILED',
40
+ /** Behind a gateway: more messages a minute than one may send; try again in a moment. */
41
+ RATE_LIMITED: 'CELL_TA_RATE_LIMITED',
40
42
  /** One let in by the user (docs/design/ta-team.md) may not do this: `data` says the action it needs (TaForbiddenData). */
41
43
  FORBIDDEN: 'CELL_TA_FORBIDDEN',
42
44
  /** As many runs of people let in go as the owner lets at once (docs/design/ta-team.md 9): try again once one ended. */
@@ -0,0 +1,43 @@
1
+ export declare const TaUsageServer: unique symbol;
2
+ export declare const TA_USAGE_SERVICE = "TaUsageServer";
3
+ /** What the turns of a model took in one hour (`at`, its start), from the sessions of this Ta. */
4
+ export interface TaUsageBucket {
5
+ at: number;
6
+ /** `<provider>/<model id>`. */
7
+ model: string;
8
+ input: number;
9
+ output: number;
10
+ cacheRead: number;
11
+ cacheWrite: number;
12
+ /** In dollars, as the model's prices make it. */
13
+ cost: number;
14
+ /** Answers of the model. */
15
+ turns: number;
16
+ }
17
+ /**
18
+ * Something an agent did lately, as one watching it sees it: a tool it called (its name, whether it worked, how
19
+ * long it took) or a call of the model that failed. Never its arguments or what it returned; of an error, its first
20
+ * line, cut short.
21
+ */
22
+ export interface TaAgentActivity {
23
+ at: number;
24
+ kind: 'tool' | 'model';
25
+ /** The tool's name, or the model's. */
26
+ name: string;
27
+ ok: boolean;
28
+ /** A tool call without its result yet. */
29
+ running?: boolean;
30
+ error?: string;
31
+ ms?: number;
32
+ }
33
+ /**
34
+ * What the agents of this Ta took and did, read from the files of its sessions: for a gateway's console, and
35
+ * any page that shows spending. Nothing said in them leaves.
36
+ */
37
+ export interface TaUsageServer {
38
+ /** The hours since `since` (a time), by model; an hour with nothing is left out. */
39
+ getUsage(since: number): Promise<TaUsageBucket[]>;
40
+ /** The latest of what the agent of an open session did, newest first, `limit` at most (50 by default, 200 at most). */
41
+ getActivity(sessionId: string, limit?: number): Promise<TaAgentActivity[]>;
42
+ }
43
+ //# sourceMappingURL=usage-protocol.d.ts.map
@@ -0,0 +1,6 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.TA_USAGE_SERVICE = exports.TaUsageServer = void 0;
4
+ exports.TaUsageServer = Symbol('TaUsageServer');
5
+ exports.TA_USAGE_SERVICE = 'TaUsageServer';
6
+ //# sourceMappingURL=usage-protocol.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@celljs/ta-protocol",
3
- "version": "4.15.1",
3
+ "version": "4.16.0",
4
4
  "description": "The protocol between ta serve and its clients",
5
5
  "homepage": "https://github.com/cellbang/ta",
6
6
  "bugs": {