@celljs/ta-host 4.14.0 → 4.15.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 CHANGED
@@ -10,7 +10,7 @@ The server-side component of `ta serve`. It is functionally equivalent to Codex'
10
10
  | `TaWorkspaceServerImpl` / `TaTerminalServerImpl` / `TaSettingsServerImpl` / `TaPackageServerImpl` / `TaAuthServerImpl` / `RelayBridge` | Other services on the same WebSocket; each forwards to the component below. `TaAccess` rejects HTTP-style calls (`POST /api/<service>` returns 404). |
11
11
  | `TaSettingsServerImpl.setLanguage` | Ta's pages tell the server their language (`zh-CN`, `en-US`), which becomes `TA_LANGUAGE` of the process; the pi packages of the server (ta-agents, ta-cron, ta-bots, ta-computer-use, `/bug`) speak it. The client that set it last wins |
12
12
  | `ExtensionProvidersImpl` | Model providers that pi packages register with `pi.registerProvider` (the agents of `@celljs/ta-agents`, for example) are in the shared model runtime only once extensions loaded. Before any session, `TaAuthServerImpl.listProviders`, the model list of the settings and `openSession` with a `model` first load the user's extensions once, in the home directory (project resources not trusted), so that no sign-in is asked for and a new conversation can pick their models. About 7 MB more than without, measured, and only on the first call |
13
- | `TaAuthServerImpl` | `@Rpc(TaAuthServer)`: runs pi's `/login` flow on the server (OAuth login page, device code, or API key). It sends only the page to open and fields for the user to fill to the initiating connection (`TaClient.onAuthEvent`); the user's answer is sent back via `answer`. The `logout` method deletes stored credentials. Credentials are written to the server-side pi's `auth.json` and shared across all sessions; they are never sent back to the client. |
13
+ | `TaAuthServerImpl` | `@Rpc(TaAuthServer)`: runs pi's `/login` flow on the server (OAuth login page, device code, or API key). It sends only the page to open and fields for the user to fill to the initiating connection (`TaClient.onAuthEvent`); the user's answer is sent back via `answer`. The `logout` method deletes stored credentials. Credentials are written to the server-side pi's `auth.json` and shared across all sessions; they are never sent back to the client. `listCustomProviders` / `saveCustomProvider` / `removeCustomProvider` manage the model services the user adds by their address and key: entries of pi's `models.json` (mode 600, the key written literally, `$` and a leading `!` escaped so that pi never reads it as a variable or a command; fields Ta does not change stay), `options` (context window, max output, `reasoning`, pictures) are written on each model and `headers` on the provider (values escaped the same way, an empty one keeping its value, only names given back); its models are refreshed on save and can be picked at once; `fetchCustomModels` asks the service's `/models` from the server (the key never goes through the browser, and there is no CORS). |
14
14
  | `RelayBridge` | `@Rpc(TaRelayServer)`: reads `relay.json` from the agent directory. When paired devices exist, it connects to Relay and opens a connection to `/api/ws` on this machine for each device (see [@celljs/ta-relay](../ta-relay/README.md)). The `pair` and `unpair` commands work the same as `ta pair`. If no Relay is provided, it uses `https://relay.cellbang.com`. |
15
15
  | `TaWorkingDirectory` | The working directory set by `setWorkingDirectory`, recorded in `ta.json` in the agent directory (`workingDirectory`), persists across restarts. Open sessions are unaffected. |
16
16
  | `TaSessionRegistry` | Manages open sessions. Rejects requests when exceeding `maxSessions`, closes sessions that are idle (no clients, not running, no pending dialogs) for longer than `idleTimeoutMs`. Session files are retained. A session closed while idle or by a restart of ta serve keeps its id (`TaSessionHandles`, `ta-sessions.json` in the agent directory, the latest 200): the next call with that id opens it again from its file, so clients never notice it closed; only `closeSession`, an extension ending the session, or a deleted session file give `CELL_TA_SESSION_NOT_FOUND`. |
@@ -67,6 +67,7 @@ When `ta serve` runs in the cloud or on a server, besides the token, people can
67
67
  | `TA_PUBLIC_URL` | The address at which browsers reach `ta serve`, such as `https://ta.example.com`. The callback of each provider is `<TA_PUBLIC_URL>/sign-in/<github\|google\|wechat\|oidc>/callback`, to register with the provider. Without it, it is worked out from the `Host` of the request and the `X-Forwarded-Proto` / `X-Forwarded-Host` of a reverse proxy |
68
68
  | `sign-in.json` (agent directory) | The ways to sign in, as the variables below: `{ "github": { "clientId", "clientSecret", "url" }, "google": {…}, "wechat": { "appId", "appSecret" }, "oidc": { "issuer", "clientId", "clientSecret", "name" } }`, read as ta serve starts, the environment winning. Those invited sign in with them too, to say who they are (ta-team) |
69
69
  | `TA_GITHUB_CLIENT_ID` / `TA_GITHUB_CLIENT_SECRET` | A GitHub OAuth App; the account is `github:<login>`. `TA_GITHUB_URL` points to a GitHub Enterprise Server |
70
+ | `TA_GITHUB_DEVICE` | When GitHub has no secret set up, those invited sign in with GitHub **by a code** (the device flow, no secret), with Ta's own app by default; `off` turns it off, `<client id>` or `<client id>@<GitHub address>` uses an app of your own with its device flow on |
70
71
  | `TA_GOOGLE_CLIENT_ID` / `TA_GOOGLE_CLIENT_SECRET` | A Google OAuth client (web application); the account is `google:<email>`, verified addresses only |
71
72
  | `TA_WECHAT_APP_ID` / `TA_WECHAT_APP_SECRET` | A website app of the WeChat Open Platform (sign-in by scanning); the account is `wechat:<unionid>`, or the openid when the app has no unionid |
72
73
  | `TA_OIDC_ISSUER` / `TA_OIDC_CLIENT_ID` / `TA_OIDC_CLIENT_SECRET` / `TA_OIDC_NAME` | Any OpenID Connect provider (Microsoft Entra, Okta, Keycloak, Authing...), its endpoints found at `<issuer>/.well-known/openid-configuration`; the account is `oidc:<verified email>` (the provider says `email_verified: true`), else `oidc:<sub>`; `TA_OIDC_NAME` is the name on the button |
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  | `TaWorkspaceServerImpl` / `TaTerminalServerImpl` / `TaSettingsServerImpl` / `TaPackageServerImpl` / `TaAuthServerImpl` / `RelayBridge` | 同一条 WebSocket 上的其他服务,各自转给下面的组件;`TaAccess` 拒绝 HTTP 形式的调用(`POST /api/<服务>` 返回 404) |
11
11
  | `TaSettingsServerImpl.setLanguage` | Ta 页面告诉服务端它的语言(`zh-CN`、`en-US`),写进进程的 `TA_LANGUAGE`,服务端的 pi 包(ta-agents、ta-cron、ta-bots、ta-computer-use、`/bug`)按它说话;最后设置的客户端为准 |
12
12
  | `ExtensionProvidersImpl` | pi 包用 `pi.registerProvider` 注册的模型服务(比如 `@celljs/ta-agents` 的外部 Agent),要等扩展加载后才在共享的模型运行时里。还没有会话时,`TaAuthServerImpl.listProviders`、设置的模型列表、带 `model` 的 `openSession` 会先在家目录下加载一次用户的扩展(不信任项目资源),这样不会因为没登录模型服务而要求登录,新对话也能选到它们的模型。实测比不加载多约 7 MB,只在第一次调用时发生 |
13
- | `TaAuthServerImpl` | `@Rpc(TaAuthServer)`:在服务端跑 pi 的 `/login` 流程(OAuth 的登录页或设备码,或 API Key),把要打开的页面、要用户填的内容只发给发起登录的连接(`TaClient.onAuthEvent`),用户的回答用 `answer` 送回;`logout` 删掉存下的凭据。凭据写进服务端 pi 的 `auth.json`,所有会话共用,不会发回客户端 |
13
+ | `TaAuthServerImpl` | `@Rpc(TaAuthServer)`:在服务端跑 pi 的 `/login` 流程(OAuth 的登录页或设备码,或 API Key),把要打开的页面、要用户填的内容只发给发起登录的连接(`TaClient.onAuthEvent`),用户的回答用 `answer` 送回;`logout` 删掉存下的凭据。凭据写进服务端 pi 的 `auth.json`,所有会话共用,不会发回客户端。`listCustomProviders` / `saveCustomProvider` / `removeCustomProvider` 管理用户按地址和 Key 添加的模型服务:写进 pi 的 `models.json`(权限 600,Key 按字面写,`$` 与开头的 `!` 转义,不会被当成变量或命令;Ta 不改的字段保留),`options`(上下文窗口、最大输出、`reasoning`、看图片)写到每个模型上,`headers` 写到服务上(值同样按字面转义,空值保留原值,返回时只给名字);保存后刷新这个服务的模型,马上能选;`fetchCustomModels` 由服务端请求这个服务的 `/models`(Key 不经浏览器,也没有跨域问题) |
14
14
  | `RelayBridge` | `@Rpc(TaRelayServer)`:读 agent 目录的 `relay.json`,有配对的设备时连上 Relay,并替每台设备开一条到本机 `/api/ws` 的连接(见 [@celljs/ta-relay](../ta-relay/README.md));`pair` / `unpair` 与 `ta pair` 相同,没给 Relay 时用 `https://relay.cellbang.com` |
15
15
  | `TaWorkingDirectory` | `setWorkingDirectory` 设的工作目录,记在 agent 目录的 `ta.json`(`workingDirectory`),跨重启保留;已经打开的会话不受影响 |
16
16
  | `TaSessionRegistry` | 打开的会话;超过 `maxSessions` 拒绝,空闲(无客户端、无运行、无待答对话框)超过 `idleTimeoutMs` 关闭,会话文件保留;空闲关闭或 ta serve 重启关掉的会话保留原 id(`TaSessionHandles`,存在 agent 目录的 `ta-sessions.json`,最近 200 个),下次有调用用这个 id 时从会话文件原样重新打开,客户端感觉不到它关过;只有 `closeSession`、扩展结束会话或会话文件已删时才回 `CELL_TA_SESSION_NOT_FOUND` |
@@ -67,6 +67,7 @@ ta:
67
67
  | `TA_PUBLIC_URL` | 浏览器访问 `ta serve` 的地址,如 `https://ta.example.com`。各家的回调地址是 `<TA_PUBLIC_URL>/sign-in/<github\|google\|wechat\|oidc>/callback`,要在服务商那里登记。没有时按请求的 `Host` 和反向代理的 `X-Forwarded-Proto` / `X-Forwarded-Host` 推算 |
68
68
  | `sign-in.json`(智能体目录) | 和下面的环境变量一样配置登录方式:`{ "github": { "clientId", "clientSecret", "url" }, "google": {…}, "wechat": { "appId", "appSecret" }, "oidc": { "issuer", "clientId", "clientSecret", "name" } }`,启动时读取,环境变量优先。邀请进来的人也用这些方式登录说明自己是谁(ta-team) |
69
69
  | `TA_GITHUB_CLIENT_ID` / `TA_GITHUB_CLIENT_SECRET` | GitHub 的 OAuth App;账号是 `github:<用户名>`。`TA_GITHUB_URL` 指向 GitHub Enterprise Server |
70
+ | `TA_GITHUB_DEVICE` | 没配 GitHub 的密钥时,邀请进来的人用 GitHub **输入码登录**(Device Flow,不要密钥),默认用 Ta 自带的应用;`off` 关掉,`<client id>` 或 `<client id>@<GitHub 地址>` 换成自己开了 Device Flow 的应用 |
70
71
  | `TA_GOOGLE_CLIENT_ID` / `TA_GOOGLE_CLIENT_SECRET` | Google 的 OAuth 客户端(Web 应用);账号是 `google:<邮箱>`,只认验证过的邮箱 |
71
72
  | `TA_WECHAT_APP_ID` / `TA_WECHAT_APP_SECRET` | 微信开放平台的网站应用(扫码登录);账号是 `wechat:<unionid>`,应用没有 unionid 时是 openid |
72
73
  | `TA_OIDC_ISSUER` / `TA_OIDC_CLIENT_ID` / `TA_OIDC_CLIENT_SECRET` / `TA_OIDC_NAME` | 任意 OpenID Connect 服务(Microsoft Entra、Okta、Keycloak、Authing……),从 `<issuer>/.well-known/openid-configuration` 找到端点;账号是 `oidc:<验证过的邮箱>`(服务方明确给出 `email_verified: true`),没有时是 `oidc:<sub>`;`TA_OIDC_NAME` 是按钮上的名字 |
@@ -1,6 +1,6 @@
1
1
  import { type CodingAgentOptions, ModelRuntimeProvider } from '@celljs/ai-coding-agent';
2
2
  import { type RpcConnection } from '@celljs/rpc/lib/node';
3
- import { type TaAuthEvent, type TaAuthProvider, TaAuthServer, type TaAuthType } from '@celljs/ta-protocol';
3
+ import { type TaAuthEvent, type TaAuthProvider, TaAuthServer, type TaAuthType, type TaCustomProvider, type TaCustomProviderInput } from '@celljs/ta-protocol';
4
4
  import { ExtensionProviders } from './extension-providers.js';
5
5
  import { TaSessionRegistry } from './host-protocol.js';
6
6
  type ModelRuntime = import('@earendil-works/pi-coding-agent', { with: { 'resolution-mode': 'import' } }).ModelRuntime;
@@ -26,7 +26,7 @@ declare class Login {
26
26
  }
27
27
  export declare namespace AuthServerUtil {
28
28
  /** The ways to sign in, as pi's `/login` lists them, by name. */
29
- function providers(runtime: ModelRuntime, stored: Set<string>): TaAuthProvider[];
29
+ function providers(runtime: ModelRuntime, stored: Set<string>, custom?: Set<string>): TaAuthProvider[];
30
30
  /** pi's AuthEvent as the protocol has it: plain data, and only what a client shows. */
31
31
  function event(event: AuthEvent): TaAuthEvent;
32
32
  }
@@ -41,12 +41,22 @@ export declare class TaAuthServerImpl implements TaAuthServer {
41
41
  protected readonly extensionProviders: ExtensionProviders;
42
42
  protected readonly codingAgentOptions?: CodingAgentOptions;
43
43
  protected readonly logins: Map<string, Login>;
44
+ /** Writes of models.json, one after another. */
45
+ protected writing: Promise<unknown>;
44
46
  protected readonly watched: WeakSet<RpcConnection>;
45
47
  listProviders(): Promise<TaAuthProvider[]>;
46
48
  login(providerId: string, type: TaAuthType): Promise<string>;
47
49
  answer(loginId: string, promptId: string, value: string): Promise<boolean>;
48
50
  cancel(loginId: string): Promise<void>;
49
51
  logout(providerId: string): Promise<void>;
52
+ listCustomProviders(): Promise<TaCustomProvider[]>;
53
+ saveCustomProvider(input: TaCustomProviderInput): Promise<TaCustomProvider>;
54
+ removeCustomProvider(id: string): Promise<void>;
55
+ fetchCustomModels(input: Pick<TaCustomProviderInput, 'id' | 'api' | 'baseUrl' | 'apiKey' | 'headers'>): Promise<string[]>;
56
+ protected modelsFile(): Promise<string>;
57
+ protected readModels(): Promise<Record<string, unknown>>;
58
+ /** models.json changed by `change`, written whole and only the user may read it: it holds keys. */
59
+ protected writeModels<T>(change: (data: Record<string, unknown>) => [Record<string, unknown>, T]): Promise<T>;
50
60
  protected run(runtime: ModelRuntime, login: Login, providerId: string, type: TaAuthType): Promise<void>;
51
61
  /**
52
62
  * Open sessions that have no model, because none was signed in when they opened, take one of the
@@ -8,11 +8,14 @@ var __metadata = (this && this.__metadata) || function (k, v) {
8
8
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
9
9
  };
10
10
  import { randomBytes } from 'node:crypto';
11
+ import { readFile, rename, writeFile } from 'node:fs/promises';
12
+ import { join } from 'node:path';
11
13
  import { CODING_AGENT_OPTIONS, ModelRuntimeProvider, PiSdkUtil } from '@celljs/ai-coding-agent';
12
14
  import { Autowired, Value } from '@celljs/core';
13
15
  import { Rpc } from '@celljs/rpc';
14
16
  import { RpcContext } from '@celljs/rpc/lib/node';
15
- import { TaAuthServer, TaClient } from '@celljs/ta-protocol';
17
+ import { TaAuthServer, TaClient, } from '@celljs/ta-protocol';
18
+ import { CustomProviderUtil } from './custom-providers.js';
16
19
  import { ExtensionProviders } from './extension-providers.js';
17
20
  import { TaSessionRegistry } from './host-protocol.js';
18
21
  import { TaErrors } from './ta-errors.js';
@@ -72,7 +75,7 @@ class Login {
72
75
  export var AuthServerUtil;
73
76
  (function (AuthServerUtil) {
74
77
  /** The ways to sign in, as pi's `/login` lists them, by name. */
75
- function providers(runtime, stored) {
78
+ function providers(runtime, stored, custom = new Set()) {
76
79
  var _a;
77
80
  var _b;
78
81
  const list = [];
@@ -88,6 +91,10 @@ export var AuthServerUtil;
88
91
  stored: stored.has(provider.id),
89
92
  subscription: ((_a = provider.auth.oauth) === null || _a === void 0 ? void 0 : _a.isSubscription) === true,
90
93
  };
94
+ if (custom.has(provider.id)) {
95
+ list.push({ ...base, type: 'api_key', interactive: true, custom: true });
96
+ continue;
97
+ }
91
98
  if (provider.auth.oauth) {
92
99
  list.push({ ...base, type: 'oauth', interactive: true });
93
100
  }
@@ -122,6 +129,8 @@ export var AuthServerUtil;
122
129
  let TaAuthServerImpl = class TaAuthServerImpl {
123
130
  constructor() {
124
131
  this.logins = new Map();
132
+ /** Writes of models.json, one after another. */
133
+ this.writing = Promise.resolve();
125
134
  this.watched = new WeakSet();
126
135
  }
127
136
  listProviders() {
@@ -130,7 +139,10 @@ let TaAuthServerImpl = class TaAuthServerImpl {
130
139
  // Those of pi packages count, as in a session: an agent of ta-agents needs no sign-in here.
131
140
  await this.extensionProviders.ensure();
132
141
  const stored = new Set((await runtime.listCredentials()).map(credential => credential.providerId));
133
- return AuthServerUtil.providers(runtime, stored);
142
+ // A models.json that does not read lists no provider as added here, rather than none at all.
143
+ const models = await this.readModels().catch(() => ({}));
144
+ const custom = new Set(CustomProviderUtil.list(models).map(provider => provider.id));
145
+ return AuthServerUtil.providers(runtime, stored, custom);
134
146
  });
135
147
  }
136
148
  login(providerId, type) {
@@ -166,6 +178,93 @@ let TaAuthServerImpl = class TaAuthServerImpl {
166
178
  logout(providerId) {
167
179
  return TaErrors.guard(async () => (await this.modelRuntimeProvider.provide()).logout(providerId));
168
180
  }
181
+ listCustomProviders() {
182
+ return TaErrors.guard(async () => CustomProviderUtil.list(await this.readModels()));
183
+ }
184
+ saveCustomProvider(input) {
185
+ return TaErrors.guard(async () => {
186
+ const clean = CustomProviderUtil.clean(input);
187
+ if (clean.models.length === 0) {
188
+ throw TaErrors.invalidArgument('A provider needs a model.', 'Give the id of at least one model of the service.');
189
+ }
190
+ const runtime = await this.modelRuntimeProvider.provide();
191
+ // Their providers' ids are taken too.
192
+ await this.extensionProviders.ensure();
193
+ const id = await this.writeModels(data => {
194
+ var _a;
195
+ const entries = CustomProviderUtil.entries(data);
196
+ if (clean.id !== undefined && !CustomProviderUtil.read(clean.id, entries[clean.id])) {
197
+ throw TaErrors.invalidArgument(`${clean.id} is not a provider added by its address.`, 'Pick one of listCustomProviders, or leave out the id to add one.');
198
+ }
199
+ const id = (_a = clean.id) !== null && _a !== void 0 ? _a : CustomProviderUtil.newId(clean.name, taken => taken in entries || !!runtime.getProvider(taken));
200
+ return [CustomProviderUtil.save(data, id, clean), id];
201
+ });
202
+ await runtime.refresh({ providers: [id] });
203
+ await this.giveModels(runtime, id);
204
+ const saved = CustomProviderUtil.read(id, CustomProviderUtil.entries(await this.readModels())[id]);
205
+ if (!saved) {
206
+ throw TaErrors.invalidArgument(`${id} could not be saved.`, 'Look at models.json of the agent directory.');
207
+ }
208
+ return saved;
209
+ });
210
+ }
211
+ removeCustomProvider(id) {
212
+ return TaErrors.guard(async () => {
213
+ await this.writeModels(data => {
214
+ if (!CustomProviderUtil.read(id, CustomProviderUtil.entries(data)[id])) {
215
+ throw TaErrors.invalidArgument(`${id} is not a provider added by its address.`, 'Pick one of listCustomProviders.');
216
+ }
217
+ return [CustomProviderUtil.remove(data, id), id];
218
+ });
219
+ await (await this.modelRuntimeProvider.provide()).refresh({ providers: [id] });
220
+ });
221
+ }
222
+ fetchCustomModels(input) {
223
+ return TaErrors.guard(async () => {
224
+ var _a;
225
+ const clean = CustomProviderUtil.clean({ ...input, models: [] });
226
+ // Not typed again: the key kept of the provider, as pi resolves it.
227
+ const key = clean.apiKey || (clean.id ? (_a = (await (await this.modelRuntimeProvider.provide()).getAuth(clean.id))) === null || _a === void 0 ? void 0 : _a.auth.apiKey : undefined);
228
+ // A header left empty is the one kept, when it is a value and not a variable or a command.
229
+ const kept = clean.id ? CustomProviderUtil.storedHeaders(CustomProviderUtil.entries(await this.readModels())[clean.id]) : {};
230
+ const headers = clean.headers ? CustomProviderUtil.headersWith(clean.headers, kept) : kept;
231
+ const request = CustomProviderUtil.modelsRequest(clean.api, clean.baseUrl, key, headers);
232
+ const response = await fetch(request.url, { headers: request.headers, signal: AbortSignal.timeout(15000) });
233
+ if (!response.ok) {
234
+ throw TaErrors.invalidArgument(`${request.url} answered ${response.status} ${response.statusText}`.trim(), 'Check the address and the key, or type the ids of the models.');
235
+ }
236
+ return CustomProviderUtil.modelIds(await response.json());
237
+ });
238
+ }
239
+ async modelsFile() {
240
+ var _a;
241
+ var _b;
242
+ const agentDir = (_b = (_a = this.codingAgentOptions) === null || _a === void 0 ? void 0 : _a.agentDir) !== null && _b !== void 0 ? _b : (await PiSdkUtil.load()).getAgentDir();
243
+ return join(agentDir, 'models.json');
244
+ }
245
+ async readModels() {
246
+ try {
247
+ return JSON.parse(await readFile(await this.modelsFile(), 'utf8'));
248
+ }
249
+ catch (error) {
250
+ if (error.code === 'ENOENT') {
251
+ return {};
252
+ }
253
+ throw error;
254
+ }
255
+ }
256
+ /** models.json changed by `change`, written whole and only the user may read it: it holds keys. */
257
+ writeModels(change) {
258
+ const write = this.writing.then(async () => {
259
+ const file = await this.modelsFile();
260
+ const [data, result] = change(await this.readModels());
261
+ await writeFile(`${file}.tmp`, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
262
+ await rename(`${file}.tmp`, file);
263
+ return result;
264
+ });
265
+ this.writing = write.catch(() => undefined);
266
+ return write;
267
+ }
169
268
  async run(runtime, login, providerId, type) {
170
269
  try {
171
270
  const settings = await this.settingsManager();
@@ -0,0 +1,50 @@
1
+ import { type TaCustomApi, type TaCustomModelOptions, type TaCustomProvider, type TaCustomProviderInput } from '@celljs/ta-protocol';
2
+ type Json = Record<string, unknown>;
3
+ type OptionKey = keyof TaCustomModelOptions;
4
+ /** The key of a provider added without one (a server on the user's computer): pi offers a provider's models only once it has a key. */
5
+ export declare const NO_KEY = "none";
6
+ /**
7
+ * The providers the user adds by their address, as entries of pi's models.json: `baseUrl`, `api`, `apiKey` and
8
+ * `models` of an id pi has no provider for. What else an entry or a model holds (headers, compat, a context window
9
+ * written by hand) stays when Ta changes it.
10
+ */
11
+ export declare namespace CustomProviderUtil {
12
+ /** The options every model has alike, and those they do not. */
13
+ function options(models: Json[]): {
14
+ options: TaCustomModelOptions;
15
+ mixed: OptionKey[];
16
+ };
17
+ /** A model with the options set: left out keeps, null or false removes. */
18
+ function withOptions(model: Json, given: NonNullable<TaCustomProviderInput['options']>): Json;
19
+ /** A value pi resolves to itself (one Ta wrote), unescaped; undefined for a variable or a command. */
20
+ function plain(value: string): string | undefined;
21
+ /** The headers a provider sends that are plain values, by name. */
22
+ function storedHeaders(entry: unknown): Record<string, string>;
23
+ /** The headers given, with an empty value taking the one kept of that name. */
24
+ function headersWith(given: Record<string, string> | undefined, kept: Record<string, string>): Record<string, string>;
25
+ /** The entries of models.json, by id. */
26
+ function entries(data: Json): Json;
27
+ /** An entry Ta shows as one added by its address: an address, an API of the list and models of its own. */
28
+ function read(id: string, value: unknown): TaCustomProvider | undefined;
29
+ function list(data: Json): TaCustomProvider[];
30
+ /**
31
+ * A key as pi reads it literally: pi runs a value that starts with `!` as a command and puts in the variable of
32
+ * `$NAME`, so `$` is written `$$` and a first `!` `$!`.
33
+ */
34
+ function literal(key: string): string;
35
+ /** The input made plain, or the reason it is not one. */
36
+ function clean(input: TaCustomProviderInput): Required<Pick<TaCustomProviderInput, 'name' | 'api' | 'baseUrl' | 'models'>> & TaCustomProviderInput;
37
+ /** An id for a new provider of that name: of letters, digits and dashes, and none that is taken. */
38
+ function newId(name: string, taken: (id: string) => boolean): string;
39
+ /** models.json with the provider saved; its other entries, and what Ta does not change of this one, stay. */
40
+ function save(data: Json, id: string, input: ReturnType<typeof clean>): Json;
41
+ function remove(data: Json, id: string): Json;
42
+ /** Where a service lists its models, and the headers that carry the key, by its API. */
43
+ function modelsRequest(kind: TaCustomApi, baseUrl: string, key: string | undefined, extra?: Record<string, string>): {
44
+ url: string;
45
+ headers: Record<string, string>;
46
+ };
47
+ /** The ids of a list of models: OpenAI's and Anthropic's `data[].id`, Google's `models[].name` without `models/`. */
48
+ function modelIds(body: unknown): string[];
49
+ }
50
+ export {};
@@ -0,0 +1,335 @@
1
+ import { TA_CUSTOM_APIS } from '@celljs/ta-protocol';
2
+ import { TaErrors } from './ta-errors.js';
3
+ const OPTION_KEYS = ['contextWindow', 'maxTokens', 'reasoning', 'images'];
4
+ /** A name of a header, as HTTP has them. */
5
+ const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
6
+ /** More tokens than any model has. */
7
+ const MAX_TOKENS = 100000000;
8
+ /** The key of a provider added without one (a server on the user's computer): pi offers a provider's models only once it has a key. */
9
+ export const NO_KEY = 'none';
10
+ /**
11
+ * The providers the user adds by their address, as entries of pi's models.json: `baseUrl`, `api`, `apiKey` and
12
+ * `models` of an id pi has no provider for. What else an entry or a model holds (headers, compat, a context window
13
+ * written by hand) stays when Ta changes it.
14
+ */
15
+ export var CustomProviderUtil;
16
+ (function (CustomProviderUtil) {
17
+ function object(value) {
18
+ return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
19
+ }
20
+ function api(value) {
21
+ return TA_CUSTOM_APIS.find(each => each === value);
22
+ }
23
+ /** What a model of models.json says of an option. */
24
+ function option(model, key) {
25
+ switch (key) {
26
+ case 'reasoning':
27
+ return model.reasoning === true;
28
+ case 'images':
29
+ return Array.isArray(model.input) && model.input.includes('image');
30
+ default:
31
+ return typeof model[key] === 'number' ? model[key] : undefined;
32
+ }
33
+ }
34
+ /** The options every model has alike, and those they do not. */
35
+ function options(models) {
36
+ const options = {};
37
+ const mixed = [];
38
+ for (const key of OPTION_KEYS) {
39
+ const values = new Set(models.map(model => option(model, key)));
40
+ if (values.size > 1) {
41
+ mixed.push(key);
42
+ }
43
+ else if (values.size === 1) {
44
+ const [value] = values;
45
+ if (value !== undefined) {
46
+ options[key] = value;
47
+ }
48
+ }
49
+ }
50
+ return { options: options, mixed };
51
+ }
52
+ CustomProviderUtil.options = options;
53
+ /** A model with the options set: left out keeps, null or false removes. */
54
+ function withOptions(model, given) {
55
+ const next = { ...model };
56
+ for (const key of OPTION_KEYS) {
57
+ const value = given[key];
58
+ if (value === undefined) {
59
+ continue;
60
+ }
61
+ const field = key === 'images' ? 'input' : key;
62
+ if (value === null || value === false) {
63
+ delete next[field];
64
+ }
65
+ else if (key === 'images') {
66
+ next.input = ['text', 'image'];
67
+ }
68
+ else {
69
+ next[field] = value;
70
+ }
71
+ }
72
+ return next;
73
+ }
74
+ CustomProviderUtil.withOptions = withOptions;
75
+ /** A value pi resolves to itself (one Ta wrote), unescaped; undefined for a variable or a command. */
76
+ function plain(value) {
77
+ if (value.startsWith('!')) {
78
+ return undefined;
79
+ }
80
+ let text = '';
81
+ for (let at = 0; at < value.length; at++) {
82
+ if (value[at] !== '$') {
83
+ text += value[at];
84
+ }
85
+ else if (value[at + 1] === '$' || value[at + 1] === '!') {
86
+ text += value[++at];
87
+ }
88
+ else {
89
+ return undefined;
90
+ }
91
+ }
92
+ return text;
93
+ }
94
+ CustomProviderUtil.plain = plain;
95
+ /** The headers a provider sends that are plain values, by name. */
96
+ function storedHeaders(entry) {
97
+ var _a;
98
+ var _b;
99
+ const headers = (_b = object((_a = object(entry)) === null || _a === void 0 ? void 0 : _a.headers)) !== null && _b !== void 0 ? _b : {};
100
+ const found = {};
101
+ for (const [name, value] of Object.entries(headers)) {
102
+ const resolved = typeof value === 'string' ? plain(value) : undefined;
103
+ if (resolved !== undefined) {
104
+ found[name] = resolved;
105
+ }
106
+ }
107
+ return found;
108
+ }
109
+ CustomProviderUtil.storedHeaders = storedHeaders;
110
+ /** The headers given, with an empty value taking the one kept of that name. */
111
+ function headersWith(given, kept) {
112
+ const headers = {};
113
+ for (const [name, value] of Object.entries(given !== null && given !== void 0 ? given : {})) {
114
+ const resolved = value || kept[name];
115
+ if (resolved) {
116
+ headers[name] = resolved;
117
+ }
118
+ }
119
+ return headers;
120
+ }
121
+ CustomProviderUtil.headersWith = headersWith;
122
+ /** The entries of models.json, by id. */
123
+ function entries(data) {
124
+ var _a;
125
+ return (_a = object(data.providers)) !== null && _a !== void 0 ? _a : {};
126
+ }
127
+ CustomProviderUtil.entries = entries;
128
+ /** An entry Ta shows as one added by its address: an address, an API of the list and models of its own. */
129
+ function read(id, value) {
130
+ var _a;
131
+ const entry = object(value);
132
+ const kind = api(entry === null || entry === void 0 ? void 0 : entry.api);
133
+ if (!entry || !kind || typeof entry.baseUrl !== 'string' || !Array.isArray(entry.models)) {
134
+ return undefined;
135
+ }
136
+ const entries = entry.models.map(model => object(model)).filter((model) => typeof (model === null || model === void 0 ? void 0 : model.id) === 'string');
137
+ const models = entries.map(model => model.id);
138
+ const key = entry.apiKey;
139
+ return {
140
+ id,
141
+ name: typeof entry.name === 'string' && entry.name ? entry.name : id,
142
+ api: kind,
143
+ baseUrl: entry.baseUrl,
144
+ hasKey: typeof key === 'string' && key !== '' && key !== NO_KEY,
145
+ models,
146
+ ...options(entries),
147
+ headers: Object.keys((_a = object(entry.headers)) !== null && _a !== void 0 ? _a : {}),
148
+ };
149
+ }
150
+ CustomProviderUtil.read = read;
151
+ function list(data) {
152
+ return Object.entries(entries(data))
153
+ .map(([id, value]) => read(id, value))
154
+ .filter((provider) => !!provider)
155
+ .sort((a, b) => a.name.localeCompare(b.name));
156
+ }
157
+ CustomProviderUtil.list = list;
158
+ /**
159
+ * A key as pi reads it literally: pi runs a value that starts with `!` as a command and puts in the variable of
160
+ * `$NAME`, so `$` is written `$$` and a first `!` `$!`.
161
+ */
162
+ function literal(key) {
163
+ const escaped = key.replace(/\$/g, '$$$$');
164
+ return escaped.startsWith('!') ? `$${escaped}` : escaped;
165
+ }
166
+ CustomProviderUtil.literal = literal;
167
+ /** The input made plain, or the reason it is not one. */
168
+ function clean(input) {
169
+ const kind = api(input === null || input === void 0 ? void 0 : input.api);
170
+ if (!kind) {
171
+ throw TaErrors.invalidArgument(`${String(input === null || input === void 0 ? void 0 : input.api)} is not an API Ta takes.`, `Use one of ${TA_CUSTOM_APIS.join(', ')}.`);
172
+ }
173
+ const baseUrl = typeof input.baseUrl === 'string' ? input.baseUrl.trim().replace(/\/+$/, '') : '';
174
+ let url;
175
+ try {
176
+ url = new URL(baseUrl);
177
+ }
178
+ catch (_a) {
179
+ url = undefined;
180
+ }
181
+ if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
182
+ throw TaErrors.invalidArgument(`${baseUrl || 'An empty address'} is not an address of a service.`, 'Give its http(s) URL, e.g. https://api.example.com/v1.');
183
+ }
184
+ const models = [...new Set((Array.isArray(input.models) ? input.models : []).map(model => String(model).trim()).filter(Boolean))];
185
+ const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : url.host;
186
+ const apiKey = typeof input.apiKey === 'string' ? input.apiKey.trim() : undefined;
187
+ return { ...input, name, api: kind, baseUrl, apiKey, models, options: cleanOptions(input.options), headers: cleanHeaders(input.headers) };
188
+ }
189
+ CustomProviderUtil.clean = clean;
190
+ function cleanOptions(given) {
191
+ const options = object(given);
192
+ if (!options) {
193
+ return undefined;
194
+ }
195
+ const clean = {};
196
+ for (const key of OPTION_KEYS) {
197
+ const value = options[key];
198
+ if (value === undefined || value === null) {
199
+ clean[key] = value;
200
+ }
201
+ else if (key === 'reasoning' || key === 'images') {
202
+ if (typeof value !== 'boolean') {
203
+ throw TaErrors.invalidArgument(`${key} is ${JSON.stringify(value)}, not true or false.`, 'Give a boolean, or null to remove it.');
204
+ }
205
+ clean[key] = value;
206
+ }
207
+ else if (typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= MAX_TOKENS) {
208
+ clean[key] = value;
209
+ }
210
+ else {
211
+ throw TaErrors.invalidArgument(`${key} is ${JSON.stringify(value)}, not a number of tokens.`, 'Give a whole number above 0, or null to remove it.');
212
+ }
213
+ }
214
+ return clean;
215
+ }
216
+ function cleanHeaders(given) {
217
+ const headers = object(given);
218
+ if (!headers) {
219
+ return undefined;
220
+ }
221
+ const clean = {};
222
+ for (const [raw, value] of Object.entries(headers)) {
223
+ const name = raw.trim();
224
+ if (!name) {
225
+ continue;
226
+ }
227
+ if (!HEADER_NAME.test(name) || typeof value !== 'string' || /[\r\n]/.test(value)) {
228
+ throw TaErrors.invalidArgument(`${name} is not a header Ta sends.`, 'Give a name of letters, digits and dashes, and a value of one line.');
229
+ }
230
+ clean[name] = value.trim();
231
+ }
232
+ return clean;
233
+ }
234
+ /** An id for a new provider of that name: of letters, digits and dashes, and none that is taken. */
235
+ function newId(name, taken) {
236
+ const base = name
237
+ .toLowerCase()
238
+ .replace(/[^a-z0-9]+/g, '-')
239
+ .replace(/^-+|-+$/g, '')
240
+ .slice(0, 40) || 'custom';
241
+ let id = base;
242
+ for (let n = 2; taken(id); n++) {
243
+ id = `${base}-${n}`;
244
+ }
245
+ return id;
246
+ }
247
+ CustomProviderUtil.newId = newId;
248
+ /** models.json with the provider saved; its other entries, and what Ta does not change of this one, stay. */
249
+ function save(data, id, input) {
250
+ var _a, _b;
251
+ const providers = { ...entries(data) };
252
+ const before = (_a = object(providers[id])) !== null && _a !== void 0 ? _a : {};
253
+ const models = Array.isArray(before.models) ? before.models : [];
254
+ const entry = {
255
+ ...before,
256
+ name: input.name,
257
+ baseUrl: input.baseUrl,
258
+ api: input.api,
259
+ models: input.models.map(model => { var _a, _b; return withOptions((_a = object(models.find(each => { var _a; return ((_a = object(each)) === null || _a === void 0 ? void 0 : _a.id) === model; }))) !== null && _a !== void 0 ? _a : { id: model }, (_b = input.options) !== null && _b !== void 0 ? _b : {}); }),
260
+ };
261
+ if (input.headers) {
262
+ const kept = (_b = object(before.headers)) !== null && _b !== void 0 ? _b : {};
263
+ const headers = {};
264
+ for (const [name, value] of Object.entries(input.headers)) {
265
+ if (value) {
266
+ headers[name] = literal(value);
267
+ }
268
+ else if (typeof kept[name] === 'string') {
269
+ headers[name] = kept[name];
270
+ }
271
+ }
272
+ if (Object.keys(headers).length > 0) {
273
+ entry.headers = headers;
274
+ }
275
+ else {
276
+ delete entry.headers;
277
+ }
278
+ }
279
+ if (input.apiKey) {
280
+ entry.apiKey = literal(input.apiKey);
281
+ }
282
+ else if (input.apiKey === '' || typeof before.apiKey !== 'string') {
283
+ entry.apiKey = NO_KEY;
284
+ }
285
+ providers[id] = entry;
286
+ return { ...data, providers };
287
+ }
288
+ CustomProviderUtil.save = save;
289
+ function remove(data, id) {
290
+ const providers = { ...entries(data) };
291
+ delete providers[id];
292
+ return { ...data, providers };
293
+ }
294
+ CustomProviderUtil.remove = remove;
295
+ /** Where a service lists its models, and the headers that carry the key, by its API. */
296
+ function modelsRequest(kind, baseUrl, key, extra = {}) {
297
+ const request = authRequest(kind, baseUrl, key);
298
+ // Those of the provider last: a gateway may take its key in a header of its own.
299
+ return { url: request.url, headers: { ...request.headers, ...extra } };
300
+ }
301
+ CustomProviderUtil.modelsRequest = modelsRequest;
302
+ function authRequest(kind, baseUrl, key) {
303
+ const base = baseUrl.replace(/\/+$/, '');
304
+ const real = key && key !== NO_KEY ? key : undefined;
305
+ switch (kind) {
306
+ case 'anthropic-messages':
307
+ // pi's address of Anthropic has no /v1, which its client adds.
308
+ return {
309
+ url: /\/v\d+$/.test(base) ? `${base}/models` : `${base}/v1/models`,
310
+ headers: { 'anthropic-version': '2023-06-01', ...(real ? { 'x-api-key': real } : {}) },
311
+ };
312
+ case 'google-generative-ai':
313
+ return { url: `${base}/models`, headers: real ? { 'x-goog-api-key': real } : {} };
314
+ default:
315
+ return { url: `${base}/models`, headers: real ? { Authorization: `Bearer ${real}` } : {} };
316
+ }
317
+ }
318
+ /** The ids of a list of models: OpenAI's and Anthropic's `data[].id`, Google's `models[].name` without `models/`. */
319
+ function modelIds(body) {
320
+ var _a;
321
+ const json = (_a = object(body)) !== null && _a !== void 0 ? _a : {};
322
+ const ids = [
323
+ ...(Array.isArray(json.data) ? json.data : []).map(model => { var _a; return (_a = object(model)) === null || _a === void 0 ? void 0 : _a.id; }),
324
+ ...(Array.isArray(json.models) ? json.models : []).map(model => {
325
+ var _a, _b;
326
+ const item = object(model);
327
+ const name = (_b = (_a = item === null || item === void 0 ? void 0 : item.name) !== null && _a !== void 0 ? _a : item === null || item === void 0 ? void 0 : item.id) !== null && _b !== void 0 ? _b : item === null || item === void 0 ? void 0 : item.model;
328
+ return typeof name === 'string' ? name.replace(/^models\//, '') : undefined;
329
+ }),
330
+ ];
331
+ return [...new Set(ids.filter((id) => typeof id === 'string' && id !== ''))].sort((a, b) => a.localeCompare(b));
332
+ }
333
+ CustomProviderUtil.modelIds = modelIds;
334
+ })(CustomProviderUtil || (CustomProviderUtil = {}));
335
+ //# sourceMappingURL=custom-providers.js.map