@celljs/ta-protocol 4.11.0 → 4.13.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.
@@ -0,0 +1,140 @@
1
+ /**
2
+ * The people let into a Ta besides its user (docs/design/ta-team.md): who calls (a principal), what they may do
3
+ * (actions of a catalog) and on what (a resource). `ta serve` checks every call of a principal other than the
4
+ * owner in one place, by the authorizer a package gives it (TaExtensionHost.team); without one, only the owner
5
+ * may do anything.
6
+ */
7
+ /** The user of the Ta: its own pages, devices and token. Everyone else is let in by a package. */
8
+ export declare const TA_OWNER = "owner";
9
+ /** A principal that holds a link of invitation only: `invite:<id>`. It may only ask to be let in. */
10
+ export declare const TA_INVITE_PREFIX = "invite:";
11
+ /** Something of Ta that can be shared with one let in on its own: an agent or a channel (of ta-channels). */
12
+ export interface TaSharedRef {
13
+ kind: 'agent' | 'channel';
14
+ id: string;
15
+ }
16
+ /** What an action is done on. */
17
+ export interface TaResource {
18
+ /** `session`: a conversation, by its file; `dir`: a directory or a file in it, by its path; `agent`, `channel`: one of ta-channels, by its id. */
19
+ kind: 'session' | 'dir' | 'agent' | 'channel';
20
+ /** The session file, the path, or the id of the agent or channel. */
21
+ id: string;
22
+ /** A session: where it works. */
23
+ cwd?: string;
24
+ /** A session: the agent it is the conversation of (TaHostTeam.link): who may use the agent may use it. */
25
+ of?: TaSharedRef;
26
+ }
27
+ /** Why a call was refused: the action it needs and on what, as the catalog names it. */
28
+ export interface TaDenial {
29
+ action: string;
30
+ resource?: TaResource;
31
+ /** False: asking would not help (a folder Ta keeps to itself, a role that never reaches there); the page offers no Ask. */
32
+ askable?: boolean;
33
+ }
34
+ /**
35
+ * Data of a package that is the Ta's and not a page's (what its host writes, as the agents and channels of ta-channels):
36
+ * pages of those let in read the owner's value, as `view` lets each see it, and do not write it (TaHostTeam.shareData).
37
+ */
38
+ export interface TaSharedData {
39
+ /** Keys, or prefixes ending with `/` (`messages/`). */
40
+ keys: readonly string[];
41
+ /** What a principal other than the owner sees of a value; undefined: nothing. */
42
+ view(principal: string, key: string, value: unknown): unknown;
43
+ }
44
+ /** One line of the record of what those let in did (TaAuthorizer.record): every call and every tool of their runs. */
45
+ export interface TaAuditEvent {
46
+ principal: string;
47
+ /** `call`: of a service of ta serve (`TaServer.prompt`); `tool`: of a run they asked (`bash`). */
48
+ kind: 'call' | 'tool' | 'connect';
49
+ name: string;
50
+ /** The action of the catalog it needed. */
51
+ action?: string;
52
+ resource?: TaResource;
53
+ allowed: boolean;
54
+ /** What the call or tool was given, cut short (a command, a path, the first words of a message). */
55
+ summary?: string;
56
+ /** The session of a tool. */
57
+ sessionFile?: string;
58
+ /** Refused: why, as the authorizer said. */
59
+ denial?: TaDenial;
60
+ }
61
+ /**
62
+ * Decides what a principal other than the owner may do. `check` is called for each call, so it is quick and
63
+ * synchronous; it answers what the call needs when it is refused. It knows nothing of packages: what their hosts and
64
+ * tools need, they declare (TaPermissionManifest), and ta serve asks the authorizer about that action.
65
+ */
66
+ export interface TaAuthorizer {
67
+ check(principal: string, action: string, resource?: TaResource): true | TaDenial;
68
+ /** A principal created something it is the author of: a conversation. */
69
+ created?(principal: string, resource: TaResource): void;
70
+ /** What a principal did, allowed or not, for the record. */
71
+ record?(event: TaAuditEvent): void;
72
+ /** Whether one more connection of a principal is let in now, that many open: the limits of the owner. */
73
+ admit?(principal: string, connections: number, everyone: number): boolean;
74
+ /** Whether a principal may start one more run now, that many of those let in going (the limit of the owner). */
75
+ mayRun?(principal: string, running: number): boolean;
76
+ /** Who a principal is, for the pages of theirs (TaServerInfo.member). */
77
+ describe?(principal: string): TaMemberInfo | undefined;
78
+ }
79
+ /**
80
+ * What a package says the calls of its host and its tools need of one let in (`pi.permissions` of its package.json), so
81
+ * that the knowledge stays with the package: `host` by method (`request:<kind>` for a method that takes requests by
82
+ * `kind`, `*` for the rest), `tools` by name. A value is an action of the catalog, `anyone` (anyone let in: the method
83
+ * checks the caller itself) or `invite` (one holding a link of invitation too). Undeclared: TA_UNDECLARED.
84
+ */
85
+ export interface TaPermissionManifest {
86
+ host?: Readonly<Record<string, string>>;
87
+ tools?: Readonly<Record<string, string>>;
88
+ }
89
+ /** What a call of the host of a package or a tool that its package does not declare needs: as much as installing one. */
90
+ export declare const TA_UNDECLARED = "extensions.install";
91
+ export declare namespace TaPermissionUtil {
92
+ /** The manifest of a package.json's `pi`, as far as it is one. */
93
+ function read(pi: unknown): TaPermissionManifest;
94
+ /** What a method of a host needs, the kind of its request first. */
95
+ function host(manifest: TaPermissionManifest | undefined, method: string, kind?: string): string;
96
+ }
97
+ /** One let in, as their pages know themselves (TaServerInfo.member). */
98
+ export interface TaMemberInfo {
99
+ id: string;
100
+ name: string;
101
+ /** The name of their role. */
102
+ role: string;
103
+ /** Whose Ta it is. */
104
+ owner: string;
105
+ }
106
+ /**
107
+ * The event of the window by which a page asks the package that lets people in to ask for an action (a CustomEvent whose
108
+ * `detail` is the TaDenial): the notice of a refused call has a button for it.
109
+ */
110
+ export declare const TA_ACCESS_REQUEST_EVENT = "ta:access-request";
111
+ /** `data` of the error of a refused call (TaErrorCode.FORBIDDEN). */
112
+ export interface TaForbiddenData extends TaDenial {
113
+ code: 'CELL_TA_FORBIDDEN';
114
+ hint: string;
115
+ }
116
+ /** An action of the catalog: what the pages show, the server checks and the model is told. */
117
+ export interface TaActionInfo {
118
+ /** `<area>.<verb>`. */
119
+ id: string;
120
+ area: TaActionArea;
121
+ title: {
122
+ en: string;
123
+ 'zh-CN': string;
124
+ };
125
+ /** Given for a directory: its scope is a list of directories. */
126
+ scoped?: boolean;
127
+ /** Reaches beyond what Ta checks (a command can touch any file): only for people trusted. */
128
+ risky?: boolean;
129
+ }
130
+ export type TaActionArea = 'chat' | 'agent' | 'channel' | 'task' | 'files' | 'commands' | 'hosts' | 'models' | 'cron' | 'extensions' | 'settings' | 'members' | 'audit';
131
+ /** Every action of Ta itself; packages add their own (`pi.permissions` of their package.json). */
132
+ export declare const TA_ACTIONS: readonly TaActionInfo[];
133
+ export declare namespace TaActionUtil {
134
+ function info(id: string): TaActionInfo | undefined;
135
+ /** Its title in a language such as `zh-CN`; the id for an action of no catalog. */
136
+ function title(id: string, language: string): string;
137
+ /** Whether `path` is `dir` or inside it; both absolute, `/` separated. */
138
+ function inside(dir: string, path: string): boolean;
139
+ }
140
+ //# sourceMappingURL=team-protocol.d.ts.map
@@ -0,0 +1,105 @@
1
+ "use strict";
2
+ /**
3
+ * The people let into a Ta besides its user (docs/design/ta-team.md): who calls (a principal), what they may do
4
+ * (actions of a catalog) and on what (a resource). `ta serve` checks every call of a principal other than the
5
+ * owner in one place, by the authorizer a package gives it (TaExtensionHost.team); without one, only the owner
6
+ * may do anything.
7
+ */
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.TaActionUtil = exports.TA_ACTIONS = exports.TA_ACCESS_REQUEST_EVENT = exports.TaPermissionUtil = exports.TA_UNDECLARED = exports.TA_INVITE_PREFIX = exports.TA_OWNER = void 0;
10
+ /** The user of the Ta: its own pages, devices and token. Everyone else is let in by a package. */
11
+ exports.TA_OWNER = 'owner';
12
+ /** A principal that holds a link of invitation only: `invite:<id>`. It may only ask to be let in. */
13
+ exports.TA_INVITE_PREFIX = 'invite:';
14
+ /** What a call of the host of a package or a tool that its package does not declare needs: as much as installing one. */
15
+ exports.TA_UNDECLARED = 'extensions.install';
16
+ var TaPermissionUtil;
17
+ (function (TaPermissionUtil) {
18
+ /** The manifest of a package.json's `pi`, as far as it is one. */
19
+ function read(pi) {
20
+ const given = pi === null || pi === void 0 ? void 0 : pi.permissions;
21
+ const map = (value) => value && typeof value === 'object' && !Array.isArray(value)
22
+ ? Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'))
23
+ : undefined;
24
+ const host = map(given === null || given === void 0 ? void 0 : given.host);
25
+ const tools = map(given === null || given === void 0 ? void 0 : given.tools);
26
+ return { ...(host ? { host } : {}), ...(tools ? { tools } : {}) };
27
+ }
28
+ TaPermissionUtil.read = read;
29
+ /** What a method of a host needs, the kind of its request first. */
30
+ function host(manifest, method, kind) {
31
+ var _a, _b, _c, _d;
32
+ const host = (_a = manifest === null || manifest === void 0 ? void 0 : manifest.host) !== null && _a !== void 0 ? _a : {};
33
+ const own = (key) => (Object.prototype.hasOwnProperty.call(host, key) ? host[key] : undefined);
34
+ return (_d = (_c = (_b = (kind ? own(`${method}:${kind}`) : undefined)) !== null && _b !== void 0 ? _b : own(method)) !== null && _c !== void 0 ? _c : own('*')) !== null && _d !== void 0 ? _d : exports.TA_UNDECLARED;
35
+ }
36
+ TaPermissionUtil.host = host;
37
+ })(TaPermissionUtil || (exports.TaPermissionUtil = TaPermissionUtil = {}));
38
+ /**
39
+ * The event of the window by which a page asks the package that lets people in to ask for an action (a CustomEvent whose
40
+ * `detail` is the TaDenial): the notice of a refused call has a button for it.
41
+ */
42
+ exports.TA_ACCESS_REQUEST_EVENT = 'ta:access-request';
43
+ const action = (id, en, zh, more = {}) => ({
44
+ id,
45
+ area: id.split('.')[0],
46
+ title: { en, 'zh-CN': zh },
47
+ ...more,
48
+ });
49
+ /** Every action of Ta itself; packages add their own (`pi.permissions` of their package.json). */
50
+ exports.TA_ACTIONS = [
51
+ action('chat.view', 'See conversations', '查看对话'),
52
+ action('chat.send', 'Send in conversations', '在对话里发消息'),
53
+ action('chat.create', 'Start conversations', '新建对话'),
54
+ action('chat.stop', 'Stop a reply', '停止回复'),
55
+ action('chat.manage', 'Rename, archive and close conversations', '改名、归档、关闭对话'),
56
+ action('chat.share', 'Share by a link', '生成分享链接'),
57
+ action('agent.view', 'See agents', '查看智能体'),
58
+ action('agent.use', 'Talk with agents', '和智能体对话'),
59
+ action('agent.edit', 'Create, change and remove agents', '新建、修改、删除智能体'),
60
+ action('channel.view', 'See channels', '查看频道'),
61
+ action('channel.post', 'Post in channels', '在频道里发言'),
62
+ action('channel.manage', 'Create and change channels', '新建、管理频道'),
63
+ action('task.view', 'See tasks', '查看任务'),
64
+ action('task.create', 'Hand out tasks', '派任务'),
65
+ action('task.manage', 'Take over and stop tasks', '接管、停止任务'),
66
+ action('files.read', 'Read files', '读文件', { scoped: true }),
67
+ action('files.write', 'Change files', '改文件', { scoped: true }),
68
+ action('commands.run', 'Let Ta run commands', '让 Ta 运行命令', { scoped: true, risky: true }),
69
+ action('commands.terminal', 'Open terminals', '打开终端', { scoped: true, risky: true }),
70
+ action('hosts.use', 'Use remote hosts', '使用远程主机', { risky: true }),
71
+ action('models.use', 'Use the models', '使用模型'),
72
+ action('models.manage', 'Sign in to models', '登录和更换模型账号'),
73
+ action('cron.view', 'See scheduled tasks', '查看定时任务'),
74
+ action('cron.manage', 'Change scheduled tasks', '管理定时任务'),
75
+ action('extensions.use', 'Use extensions', '使用扩展'),
76
+ action('extensions.install', 'Install and turn off extensions', '安装、停用扩展'),
77
+ action('settings.view', 'See settings', '查看设置'),
78
+ action('settings.manage', 'Change settings', '修改设置'),
79
+ action('members.view', 'See members', '查看成员'),
80
+ action('members.invite', 'Invite people', '邀请别人'),
81
+ action('members.approve', 'Answer requests', '处理申请'),
82
+ action('members.roles', 'Change roles and members', '管理角色和成员'),
83
+ action('audit.view', 'See the record', '查看记录'),
84
+ ];
85
+ var TaActionUtil;
86
+ (function (TaActionUtil) {
87
+ const byId = new Map(exports.TA_ACTIONS.map(one => [one.id, one]));
88
+ function info(id) {
89
+ return byId.get(id);
90
+ }
91
+ TaActionUtil.info = info;
92
+ /** Its title in a language such as `zh-CN`; the id for an action of no catalog. */
93
+ function title(id, language) {
94
+ const found = byId.get(id);
95
+ return found ? (language.startsWith('zh') ? found.title['zh-CN'] : found.title.en) : id;
96
+ }
97
+ TaActionUtil.title = title;
98
+ /** Whether `path` is `dir` or inside it; both absolute, `/` separated. */
99
+ function inside(dir, path) {
100
+ const base = dir.replace(/\/+$/, '');
101
+ return path === base || path.startsWith(`${base}/`) || base === '';
102
+ }
103
+ TaActionUtil.inside = inside;
104
+ })(TaActionUtil || (exports.TaActionUtil = TaActionUtil = {}));
105
+ //# sourceMappingURL=team-protocol.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@celljs/ta-protocol",
3
- "version": "4.11.0",
3
+ "version": "4.13.0",
4
4
  "description": "The protocol between ta serve and its clients",
5
5
  "homepage": "https://github.com/cellbang/cell",
6
6
  "bugs": {