@ftai/plugin-host-api 0.0.0-stage → 2.3.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/LICENSE +21 -0
- package/README.md +4 -2
- package/lib/attachments.d.ts +149 -0
- package/lib/attachments.js +26 -0
- package/lib/capabilities.d.ts +99 -0
- package/lib/capabilities.js +21 -0
- package/lib/cmdline.d.ts +52 -0
- package/lib/cmdline.js +68 -0
- package/lib/credentials.d.ts +92 -0
- package/lib/credentials.js +41 -0
- package/lib/fs.d.ts +117 -0
- package/lib/fs.js +14 -0
- package/lib/generated.d.ts +4198 -0
- package/lib/generated.js +80 -0
- package/lib/index.d.ts +665 -0
- package/lib/index.js +151 -0
- package/lib/jobs.d.ts +88 -0
- package/lib/jobs.js +2 -0
- package/lib/llm.d.ts +255 -0
- package/lib/llm.js +144 -0
- package/lib/local-install.d.ts +38 -0
- package/lib/local-install.js +9 -0
- package/lib/permissions.d.ts +97 -0
- package/lib/permissions.js +11 -0
- package/lib/platform.d.ts +167 -0
- package/lib/platform.js +74 -0
- package/lib/porting.d.ts +51 -0
- package/lib/porting.js +752 -0
- package/lib/prompt.d.ts +117 -0
- package/lib/prompt.js +43 -0
- package/lib/runtime-context.d.ts +29 -0
- package/lib/runtime-context.js +6 -0
- package/lib/schedule-types.d.ts +333 -0
- package/lib/schedule-types.js +4 -0
- package/lib/session-events.d.ts +194 -0
- package/lib/session-events.js +2 -0
- package/lib/sessions.d.ts +246 -0
- package/lib/sessions.js +2 -0
- package/lib/settings.d.ts +86 -0
- package/lib/settings.js +13 -0
- package/lib/storage.d.ts +144 -0
- package/lib/storage.js +62 -0
- package/lib/subagents.d.ts +57 -0
- package/lib/subagents.js +17 -0
- package/lib/subprocess.d.ts +97 -0
- package/lib/subprocess.js +8 -0
- package/lib/tools.d.ts +212 -0
- package/lib/tools.js +2 -0
- package/lib/web.d.ts +192 -0
- package/lib/web.js +53 -0
- package/package.json +40 -3
package/lib/storage.d.ts
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 插件自己的结构化数据(同 0.12 的 `ctx.storageDomain` 与 `defineDomain`)。实现在插件进程里,经 `ctx.storageDomain.open(spec)`
|
|
3
|
+
* 或 `ctx.storage.domain.open(spec)` 使用:读同步取内存;写排进这个域的写链,落盘成功才改内存,再通知这个插件自己的
|
|
4
|
+
* `domain/changed` 监听者。
|
|
5
|
+
*
|
|
6
|
+
* 每个插件一份数据目录,同名的域互不相干,碰不到核心的域。句柄绑在打开它的插件上:插件撤销时等写链落盘再关。
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
/** 域名与表名的写法:可以直接作文件名。 */
|
|
10
|
+
export declare const UNIT_NAME_RE: RegExp;
|
|
11
|
+
export type StorageErrorCode = 'version-mismatch' | 'malformed-medium' | 'closed';
|
|
12
|
+
/** 落盘一层的错误(同 0.12 的 `StorageError`);`code` 是稳定的,`message` 只给人看。 */
|
|
13
|
+
export declare class StorageError extends Error {
|
|
14
|
+
readonly code: StorageErrorCode;
|
|
15
|
+
readonly name = "StorageError";
|
|
16
|
+
constructor(code: StorageErrorCode, message: string, options?: ErrorOptions);
|
|
17
|
+
}
|
|
18
|
+
export type DomainErrorCode = 'already-open' | 'invalid-record' | 'missing-key' | 'closed';
|
|
19
|
+
/** 校验不过的记录的位置:全局槽的 `table`、`key` 是空串。 */
|
|
20
|
+
export interface InvalidRecordDetail {
|
|
21
|
+
readonly table: string;
|
|
22
|
+
readonly key: string;
|
|
23
|
+
}
|
|
24
|
+
export interface DomainErrorOptions extends ErrorOptions {
|
|
25
|
+
/** `code` 是 `invalid-record` 时有。 */
|
|
26
|
+
readonly detail?: InvalidRecordDetail;
|
|
27
|
+
}
|
|
28
|
+
/** 域一层的错误(同 0.12 的 `DomainError`);落盘的错误是 {@link StorageError},不再包一层。 */
|
|
29
|
+
export declare class DomainError extends Error {
|
|
30
|
+
readonly code: DomainErrorCode;
|
|
31
|
+
readonly name = "DomainError";
|
|
32
|
+
readonly detail?: InvalidRecordDetail;
|
|
33
|
+
constructor(code: DomainErrorCode, message: string, options?: DomainErrorOptions);
|
|
34
|
+
}
|
|
35
|
+
/** 记录的 schema,同 0.12 写 zod 的:SDK 不依赖 zod,形状对上(`parse`、`safeParse`)就行。 */
|
|
36
|
+
export interface RecordSchema<T> {
|
|
37
|
+
parse(value: unknown): T;
|
|
38
|
+
safeParse(value: unknown): {
|
|
39
|
+
readonly success: boolean;
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/** 全局槽:schema 与第一次写之前的值(读到初始值时不落盘)。 */
|
|
43
|
+
export interface DomainGlobalSpec<G> {
|
|
44
|
+
readonly schema: RecordSchema<G>;
|
|
45
|
+
readonly initial: G;
|
|
46
|
+
}
|
|
47
|
+
/** 一张表。`K` 只用来推类型(常是品牌字符串),盘上的键就是字符串。 */
|
|
48
|
+
export interface DomainTableSpec<K extends string = string, V = unknown> {
|
|
49
|
+
readonly valueSchema: RecordSchema<V>;
|
|
50
|
+
readonly __key?: K;
|
|
51
|
+
}
|
|
52
|
+
/** 一个域的声明(同 0.12):名字、版本与记录的结构。 */
|
|
53
|
+
export interface DomainSpec {
|
|
54
|
+
/** 同时是文件名,要符合 {@link UNIT_NAME_RE}。只在这个插件自己的目录里生效。 */
|
|
55
|
+
readonly name: string;
|
|
56
|
+
readonly version: number;
|
|
57
|
+
/** `single`(默认)整个域一个文件;`per-record` 每条记录一个文件,记录大或可以丢时用。 */
|
|
58
|
+
readonly layout?: 'single' | 'per-record';
|
|
59
|
+
/** `per-record` 还认的旧版本:声明的 schema 要能读它们。写入一律盖当前版本。 */
|
|
60
|
+
readonly compatibleVersions?: readonly number[];
|
|
61
|
+
/** 打开时记录校验不过怎么办:默认整个打开失败(`invalid-record`);`backup-and-skip` 把这条记录的文件挪开、记日志,当它不存在(只有 `per-record` 有单独的文件可挪)。 */
|
|
62
|
+
readonly invalidRecords?: 'backup-and-skip';
|
|
63
|
+
readonly global?: DomainGlobalSpec<unknown>;
|
|
64
|
+
readonly tables: Record<string, DomainTableSpec>;
|
|
65
|
+
}
|
|
66
|
+
export type TableKeyOf<S extends DomainSpec, N extends keyof S['tables']> = S['tables'][N] extends DomainTableSpec<infer K> ? K : never;
|
|
67
|
+
export type TableValueOf<S extends DomainSpec, N extends keyof S['tables']> = S['tables'][N] extends DomainTableSpec<string, infer V> ? V : never;
|
|
68
|
+
export type GlobalValueOf<S extends DomainSpec> = S['global'] extends DomainGlobalSpec<infer G> ? G : never;
|
|
69
|
+
/** 声明一张表(同 0.12)。 */
|
|
70
|
+
export declare function domainTable<K extends string, V>(schema: RecordSchema<V>): DomainTableSpec<K, V>;
|
|
71
|
+
/** 钉住声明的类型并当场校验(同 0.12):写错的名字、版本与接受 null 的全局槽在插件加载时就抛错,不碰盘。 */
|
|
72
|
+
export declare function defineDomain<S extends DomainSpec>(spec: S): S;
|
|
73
|
+
/** 全局槽的句柄。 */
|
|
74
|
+
export interface DomainGlobal<G> {
|
|
75
|
+
/** 同步读内存;第一次写之前是 `initial`。 */
|
|
76
|
+
get(): G;
|
|
77
|
+
/** 排进写链,落盘后改内存、发通知。 */
|
|
78
|
+
set(value: G): Promise<void>;
|
|
79
|
+
}
|
|
80
|
+
/** 一张表的句柄。记录就是存着的对象,不复制:不要就地改,用 `put`、`update`。 */
|
|
81
|
+
export interface KvTable<K extends string, V> {
|
|
82
|
+
get(key: K): V | undefined;
|
|
83
|
+
/** 快照,迭代期间落下的写入不影响它。 */
|
|
84
|
+
entries(): IterableIterator<[K, V]>;
|
|
85
|
+
keys(): IterableIterator<K>;
|
|
86
|
+
readonly size: number;
|
|
87
|
+
put(key: K, value: V): Promise<void>;
|
|
88
|
+
/** 记录原本就不在时为 false,不写也不发通知。 */
|
|
89
|
+
delete(key: K): Promise<boolean>;
|
|
90
|
+
/** 写链上的读改写:`fn` 看到的是排到它时的值,并发的更新不会交错。键不在时报 `missing-key`。 */
|
|
91
|
+
update(key: K, fn: (current: V) => V): Promise<V>;
|
|
92
|
+
}
|
|
93
|
+
export type DomainGlobalHandleOf<S extends DomainSpec> = S extends {
|
|
94
|
+
readonly global: DomainGlobalSpec<infer G>;
|
|
95
|
+
} ? DomainGlobal<G> : never;
|
|
96
|
+
/** 一个打开的域。 */
|
|
97
|
+
export interface Domain<S extends DomainSpec> {
|
|
98
|
+
readonly name: string;
|
|
99
|
+
readonly global: DomainGlobalHandleOf<S>;
|
|
100
|
+
/** 同一张表总是同一个句柄。没声明的表抛错。 */
|
|
101
|
+
table<N extends keyof S['tables'] & string>(name: N): KvTable<TableKeyOf<S, N>, TableValueOf<S, N>>;
|
|
102
|
+
/** 新的写入立即拒绝,排着的写完(照常发通知)再释放名字。可以重复调用。插件撤销时自动关,不用自己调用。 */
|
|
103
|
+
close(): Promise<void>;
|
|
104
|
+
}
|
|
105
|
+
/** 同 0.12 的 `ctx.storageDomain`,只管调用方插件自己的域。 */
|
|
106
|
+
export interface DomainFacility {
|
|
107
|
+
/**
|
|
108
|
+
* 打开一个域:没有文件时是空的,第一次写时建出。已经开着报 `already-open`,版本不同报 `version-mismatch`,文件读不了报 `malformed-medium`,
|
|
109
|
+
* 记录不合 schema 报 `invalid-record`。
|
|
110
|
+
*/
|
|
111
|
+
open<S extends DomainSpec>(spec: S): Promise<Domain<S>>;
|
|
112
|
+
/** 这个插件开着的域,没类型;要类型的用 `open` 给的句柄。 */
|
|
113
|
+
get(name: string): Domain<DomainSpec> | undefined;
|
|
114
|
+
/** 关掉这个插件开着的全部域。 */
|
|
115
|
+
closeAll(): Promise<void>;
|
|
116
|
+
}
|
|
117
|
+
/** 同 0.12 的 `ctx.storage`:只有 `domain`,不开放后端与挂载。 */
|
|
118
|
+
export interface StorageService {
|
|
119
|
+
readonly domain: DomainFacility;
|
|
120
|
+
}
|
|
121
|
+
/** 域的一次变化:`table`、`key` 是空串时是全局槽。`put` 带新值,`deleted` 不带。 */
|
|
122
|
+
export type DomainChanged = {
|
|
123
|
+
readonly domain: string;
|
|
124
|
+
readonly table: string;
|
|
125
|
+
readonly key: string;
|
|
126
|
+
readonly operation: 'put';
|
|
127
|
+
readonly value: unknown;
|
|
128
|
+
} | {
|
|
129
|
+
readonly domain: string;
|
|
130
|
+
readonly table: string;
|
|
131
|
+
readonly key: string;
|
|
132
|
+
readonly operation: 'deleted';
|
|
133
|
+
readonly value?: never;
|
|
134
|
+
};
|
|
135
|
+
declare module 'cordis' {
|
|
136
|
+
interface Context {
|
|
137
|
+
storage: StorageService;
|
|
138
|
+
storageDomain: DomainFacility;
|
|
139
|
+
}
|
|
140
|
+
interface Events {
|
|
141
|
+
/** 这个插件自己的域落盘之后发,同域按写入顺序;只发给拥有这个域的插件,不广播,核心的域不发。监听者抛错只记日志。 */
|
|
142
|
+
'domain/changed'(change: DomainChanged): void;
|
|
143
|
+
}
|
|
144
|
+
}
|
package/lib/storage.js
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 插件自己的结构化数据(同 0.12 的 `ctx.storageDomain` 与 `defineDomain`)。实现在插件进程里,经 `ctx.storageDomain.open(spec)`
|
|
3
|
+
* 或 `ctx.storage.domain.open(spec)` 使用:读同步取内存;写排进这个域的写链,落盘成功才改内存,再通知这个插件自己的
|
|
4
|
+
* `domain/changed` 监听者。
|
|
5
|
+
*
|
|
6
|
+
* 每个插件一份数据目录,同名的域互不相干,碰不到核心的域。句柄绑在打开它的插件上:插件撤销时等写链落盘再关。
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
/** 域名与表名的写法:可以直接作文件名。 */
|
|
10
|
+
export const UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/;
|
|
11
|
+
/** 落盘一层的错误(同 0.12 的 `StorageError`);`code` 是稳定的,`message` 只给人看。 */
|
|
12
|
+
export class StorageError extends Error {
|
|
13
|
+
code;
|
|
14
|
+
name = 'StorageError';
|
|
15
|
+
constructor(code, message, options) {
|
|
16
|
+
super(message, options);
|
|
17
|
+
this.code = code;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
/** 域一层的错误(同 0.12 的 `DomainError`);落盘的错误是 {@link StorageError},不再包一层。 */
|
|
21
|
+
export class DomainError extends Error {
|
|
22
|
+
code;
|
|
23
|
+
name = 'DomainError';
|
|
24
|
+
detail;
|
|
25
|
+
constructor(code, message, options) {
|
|
26
|
+
super(message, options);
|
|
27
|
+
this.code = code;
|
|
28
|
+
if (options?.detail !== undefined)
|
|
29
|
+
this.detail = options.detail;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
/** 声明一张表(同 0.12)。 */
|
|
33
|
+
export function domainTable(schema) {
|
|
34
|
+
return { valueSchema: schema };
|
|
35
|
+
}
|
|
36
|
+
/** 钉住声明的类型并当场校验(同 0.12):写错的名字、版本与接受 null 的全局槽在插件加载时就抛错,不碰盘。 */
|
|
37
|
+
export function defineDomain(spec) {
|
|
38
|
+
if (!UNIT_NAME_RE.test(spec.name))
|
|
39
|
+
throw new Error(`domain name '${spec.name}' must match ${String(UNIT_NAME_RE)}`);
|
|
40
|
+
if (!Number.isInteger(spec.version) || spec.version < 0)
|
|
41
|
+
throw new Error(`domain '${spec.name}' version must be a non-negative integer, got ${String(spec.version)}`);
|
|
42
|
+
for (const compatible of spec.compatibleVersions ?? []) {
|
|
43
|
+
if (!Number.isInteger(compatible) || compatible < 0 || compatible >= spec.version) {
|
|
44
|
+
throw new Error(`domain '${spec.name}' compatibleVersions entries must be non-negative integers below version ${String(spec.version)}, got ${String(compatible)}`);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
const layout = spec.layout;
|
|
48
|
+
if (layout !== undefined && layout !== 'single' && layout !== 'per-record')
|
|
49
|
+
throw new Error(`domain '${spec.name}' layout must be 'single' or 'per-record', got ${layout}`);
|
|
50
|
+
const policy = spec.invalidRecords;
|
|
51
|
+
if (policy !== undefined && policy !== 'backup-and-skip')
|
|
52
|
+
throw new Error(`domain '${spec.name}' invalidRecords must be 'backup-and-skip' when present, got ${policy}`);
|
|
53
|
+
for (const table of Object.keys(spec.tables)) {
|
|
54
|
+
if (!UNIT_NAME_RE.test(table))
|
|
55
|
+
throw new Error(`domain '${spec.name}' table name '${table}' must match ${String(UNIT_NAME_RE)}`);
|
|
56
|
+
}
|
|
57
|
+
// 盘上的 null 表示「从没写过」,能存 null 的全局槽读回来会变成初始值
|
|
58
|
+
if (spec.global?.schema.safeParse(null).success === true)
|
|
59
|
+
throw new Error(`domain '${spec.name}' global schema must not accept null`);
|
|
60
|
+
return spec;
|
|
61
|
+
}
|
|
62
|
+
//# sourceMappingURL=storage.js.map
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 子 agent 的接口(0.12 的 `ctx.subagents`)。子 agent 在宿主上,与委派工具同一条路径:深度、并发上限、权限与审批都一样。收 agent 句柄的
|
|
3
|
+
* 地方这里收会话 id。形状由扩展点表生成(generated.ts)。
|
|
4
|
+
* @module @ftai/plugin-host-api/subagents
|
|
5
|
+
*/
|
|
6
|
+
import type { SubagentActivationRequest, SubagentCatalogEntry, SubagentDescendantEntry, SubagentInterruptAuthority, SubagentResult, SubagentStartRequest, UserContent } from './generated.ts';
|
|
7
|
+
/** 同 0.12 的 `SubagentError`:`code` 是 `UNAUTHORIZED`、`ACTIVATION_LIMIT_REACHED`、`NOT_RESUMABLE` 等。 */
|
|
8
|
+
export declare class SubagentError extends Error {
|
|
9
|
+
readonly code: string;
|
|
10
|
+
constructor(message: string, code: string, options?: ErrorOptions);
|
|
11
|
+
}
|
|
12
|
+
/** 同 0.12 的 `SubagentDepthError`:委派深度超过上限。形状有变:没有 `attemptedDepth`、`maxDepth`,都在说明里。 */
|
|
13
|
+
export declare class SubagentDepthError extends Error {
|
|
14
|
+
constructor(message: string, options?: ErrorOptions);
|
|
15
|
+
}
|
|
16
|
+
/** `ctx.subagents.startActivation` 的参数(同 0.12 的 `SubagentActivationSpec`)。 */
|
|
17
|
+
export interface SubagentActivationSpec extends Omit<SubagentActivationRequest, 'request'> {
|
|
18
|
+
/** `parent` 是父会话的 id。 */
|
|
19
|
+
readonly request: SubagentStartRequest & {
|
|
20
|
+
/** 不支持:给了报 `UNSUPPORTED_CAPABILITY`。 */
|
|
21
|
+
readonly outputSchema?: never;
|
|
22
|
+
};
|
|
23
|
+
/** 只管建立之前的取消;建立之后用 `dispose`。 */
|
|
24
|
+
readonly signal: AbortSignal;
|
|
25
|
+
}
|
|
26
|
+
/** 一段常驻(同 0.12 的 `SubagentActivation`)。 */
|
|
27
|
+
export interface SubagentActivation {
|
|
28
|
+
readonly childId: string;
|
|
29
|
+
/** 交给子 agent 的初始任务的消息 id。 */
|
|
30
|
+
readonly messageId?: string;
|
|
31
|
+
/** 这一段的结局。子 agent 失败时兑现(`stopReason` 不是 `completed`),宿主不在了才拒绝。 */
|
|
32
|
+
readonly result: Promise<SubagentResult>;
|
|
33
|
+
/** 停下并放开这一段常驻,它的子 agent 一并放开,结算之后兑现。只认这一段,之后续上的不受影响。调用方撤销时自动调用。 */
|
|
34
|
+
dispose(): Promise<void>;
|
|
35
|
+
}
|
|
36
|
+
export interface SubagentSendMessageOptions {
|
|
37
|
+
/** 只管发出之前的取消。 */
|
|
38
|
+
readonly signal: AbortSignal;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* 同 0.12 的 `ctx.subagents`(`SubagentRuntime`)。形状有变:同步的方法要跨进程,都返回 Promise。
|
|
42
|
+
* 宿主的提供者固定为 `spawn`、`fork`,没有 `registerProvider`、`getProvider`。
|
|
43
|
+
*/
|
|
44
|
+
export interface SubagentRuntime {
|
|
45
|
+
/** 在任意父会话下起一个子 agent。父会话空闲且 `delivery: 'parent'` 时,结算通知会开始它的新一轮。 */
|
|
46
|
+
startActivation(spec: SubagentActivationSpec): Promise<SubagentActivation>;
|
|
47
|
+
/** 发消息给直接的子 agent(不常驻时按描述符冷恢复),或常驻的子 agent 发给直接的父 agent。返回消息 id。 */
|
|
48
|
+
sendMessage(sender: string, target: string, content: UserContent[], options: SubagentSendMessageOptions): Promise<string>;
|
|
49
|
+
/** 打断一个常驻的子 agent 当前的这一轮:队列留着,它的子 agent 继续跑;不常驻时什么也不做。 */
|
|
50
|
+
interrupt(target: string, authority: SubagentInterruptAuthority): Promise<void>;
|
|
51
|
+
listChildren(parent: string, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>;
|
|
52
|
+
listDescendants(root: string, signal?: AbortSignal): Promise<SubagentDescendantEntry[]>;
|
|
53
|
+
/** 等这个会话下面在进展的子孙停下,不取消它们;停着等下一次唤醒的不等。结论是有没有等过。 */
|
|
54
|
+
waitForChildren(parent: string): Promise<boolean>;
|
|
55
|
+
/** 提供者的名字。 */
|
|
56
|
+
list(): Promise<string[]>;
|
|
57
|
+
}
|
package/lib/subagents.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** 同 0.12 的 `SubagentError`:`code` 是 `UNAUTHORIZED`、`ACTIVATION_LIMIT_REACHED`、`NOT_RESUMABLE` 等。 */
|
|
2
|
+
export class SubagentError extends Error {
|
|
3
|
+
code;
|
|
4
|
+
constructor(message, code, options) {
|
|
5
|
+
super(message, options);
|
|
6
|
+
this.code = code;
|
|
7
|
+
this.name = 'SubagentError';
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
/** 同 0.12 的 `SubagentDepthError`:委派深度超过上限。形状有变:没有 `attemptedDepth`、`maxDepth`,都在说明里。 */
|
|
11
|
+
export class SubagentDepthError extends Error {
|
|
12
|
+
constructor(message, options) {
|
|
13
|
+
super(message, options);
|
|
14
|
+
this.name = 'SubagentDepthError';
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
//# sourceMappingURL=subagents.js.map
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 插件进程里的子进程服务(同 0.12 的 `ctx.subprocess`):显式给全的启动请求、环境清洗、进程组的宽限终止、等整组退出、
|
|
3
|
+
* 只留尾部的输出收集。进程随调用方的作用域撤销被杀掉。
|
|
4
|
+
*
|
|
5
|
+
* 它不是权限边界,也不经沙箱与审批:插件进程本来就能用 Node 的 `child_process`。要在会话的沙箱里跑命令用别的服务。
|
|
6
|
+
* @module
|
|
7
|
+
*/
|
|
8
|
+
import type { Readable, Writable } from 'node:stream';
|
|
9
|
+
/** stdin:`ignore` 接到空设备;`pipe` 给出 `stdin` 流;`{ data }` 写完就关。 */
|
|
10
|
+
export type SubprocessStdinMode = 'ignore' | 'pipe' | {
|
|
11
|
+
readonly data: string;
|
|
12
|
+
};
|
|
13
|
+
/** 收集一条输出:内存里只留尾部 `maxBytes`;给了 `spill` 时超出后把整条流写进私有临时文件,超过它的 `maxBytes` 就删掉不留。 */
|
|
14
|
+
export interface SubprocessCollect {
|
|
15
|
+
readonly maxBytes: number;
|
|
16
|
+
readonly spill?: {
|
|
17
|
+
readonly maxBytes: number;
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
/** stdout、stderr:`pipe` 给出原始流;`inherit` 接到插件进程的 stderr(stdout 也是,插件进程的 stdout 是协议);对象是收集。 */
|
|
21
|
+
export type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;
|
|
22
|
+
export interface SubprocessStdio {
|
|
23
|
+
readonly stdin: SubprocessStdinMode;
|
|
24
|
+
readonly stdout: SubprocessOutputMode;
|
|
25
|
+
readonly stderr: SubprocessOutputMode;
|
|
26
|
+
}
|
|
27
|
+
/** 一次启动:每一项都显式给出,这里不设默认值。 */
|
|
28
|
+
export interface SubprocessSpawnSpec {
|
|
29
|
+
/** 程序与参数,不经 shell。 */
|
|
30
|
+
readonly argv: readonly string[];
|
|
31
|
+
readonly cwd: string;
|
|
32
|
+
readonly stdio: SubprocessStdio;
|
|
33
|
+
/** 宽限(毫秒,正数):终止时 SIGTERM 之后等这么久再 SIGKILL;进程退出后等收集的管道关上也最多等这么久。Windows 没有宽限,直接结束进程树。 */
|
|
34
|
+
readonly graceMs: number;
|
|
35
|
+
/** 触发时开始终止。时限与原因由调用方管。 */
|
|
36
|
+
readonly signal?: AbortSignal | undefined;
|
|
37
|
+
/** 合并在清洗过的环境上:字符串是有意给的,带凭据的名字也留着;`undefined` 去掉一项。 */
|
|
38
|
+
readonly env?: NodeJS.ProcessEnv | undefined;
|
|
39
|
+
}
|
|
40
|
+
/** 直接子进程的退出(Node 的 `exit` 事件)。不分超时或取消:调用方看自己的 `signal`。 */
|
|
41
|
+
export interface SubprocessOutcome {
|
|
42
|
+
readonly exitCode: number | null;
|
|
43
|
+
readonly signal: NodeJS.Signals | null;
|
|
44
|
+
}
|
|
45
|
+
export interface SubprocessOutputRead {
|
|
46
|
+
/** 从请求的位置起的文字;`lossy` 时是留着的全部尾部。 */
|
|
47
|
+
readonly text: string;
|
|
48
|
+
/** 下次从这里读。 */
|
|
49
|
+
readonly nextOffset: number;
|
|
50
|
+
/** 请求的位置已经滑出尾部窗口,中间缺的只有落盘的文件里有。 */
|
|
51
|
+
readonly lossy: boolean;
|
|
52
|
+
/** 完整输出的文件,建了且没丢时有。 */
|
|
53
|
+
readonly spillPath?: string;
|
|
54
|
+
}
|
|
55
|
+
/** 按整条流的字节偏移读,不消费:几个读者互不影响,退出后照样能读。 */
|
|
56
|
+
export interface SubprocessOutputReader {
|
|
57
|
+
readFrom(fromByte: number): SubprocessOutputRead;
|
|
58
|
+
}
|
|
59
|
+
export interface SubprocessCollectedOutputs {
|
|
60
|
+
readonly stdout?: SubprocessOutputReader;
|
|
61
|
+
readonly stderr?: SubprocessOutputReader;
|
|
62
|
+
}
|
|
63
|
+
/** 一个跑着的子进程与它的进程组。 */
|
|
64
|
+
export interface SubprocessHandle {
|
|
65
|
+
readonly stdin: Writable | undefined;
|
|
66
|
+
readonly stdout: Readable | undefined;
|
|
67
|
+
readonly stderr: Readable | undefined;
|
|
68
|
+
readonly collected: SubprocessCollectedOutputs;
|
|
69
|
+
/** 直接子进程退出后兑现(收集的管道关上或过了宽限);起不来时拒绝。 */
|
|
70
|
+
readonly done: Promise<SubprocessOutcome>;
|
|
71
|
+
/** 开始终止整个进程组。可以重复调用,整组不在了就什么也不做。 */
|
|
72
|
+
terminate(): void;
|
|
73
|
+
/** 等整个进程组都不在,不只是直接子进程。`signal` 先触发时为 false。 */
|
|
74
|
+
waitForExit(signal?: AbortSignal): Promise<boolean>;
|
|
75
|
+
}
|
|
76
|
+
/** 选 shell 用的环境事实。 */
|
|
77
|
+
export interface SubprocessTerminalEnvironment {
|
|
78
|
+
readonly platform: 'posix' | 'windows';
|
|
79
|
+
readonly defaultShell?: string;
|
|
80
|
+
}
|
|
81
|
+
/** 找不到可执行文件。 */
|
|
82
|
+
export declare class SubprocessExecutableNotFoundError extends Error {
|
|
83
|
+
constructor(message: string, options?: ErrorOptions);
|
|
84
|
+
}
|
|
85
|
+
/** 同 0.12 的 `ctx.subprocess`,没有 `spawnTerminal`。 */
|
|
86
|
+
export interface SubprocessService {
|
|
87
|
+
/** 绝对路径核对一下;裸名字按 `PATH`(清洗过的环境加 `env`)找;带分隔符的相对路径报错。 */
|
|
88
|
+
resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
|
|
89
|
+
terminalEnvironment(signal?: AbortSignal): Promise<SubprocessTerminalEnvironment>;
|
|
90
|
+
/** 同步给出句柄。已中止或请求写错时同步抛错;进程起不来时 `done` 拒绝。 */
|
|
91
|
+
spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
|
|
92
|
+
}
|
|
93
|
+
declare module 'cordis' {
|
|
94
|
+
interface Context {
|
|
95
|
+
subprocess: SubprocessService;
|
|
96
|
+
}
|
|
97
|
+
}
|
package/lib/tools.d.ts
ADDED
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 工具执行管线给插件的写法(0.12 `tools` 的 `ToolExecutionResult`、`PostToolDecision`、`ctx.tools.guard` 与 `execute` 的参数、工具卡片的视图)。
|
|
3
|
+
* 线上的类型在 generated.ts;这里是 SDK 另包的一层,由插件运行时翻译(`packages/plugin-runtime/src/tools.ts`)。
|
|
4
|
+
*/
|
|
5
|
+
import type { JsonValue, ToolContent, ToolFailure, UserMessage } from './generated.ts';
|
|
6
|
+
import type { AgentHandle, ToolExecution } from './index.ts';
|
|
7
|
+
/**
|
|
8
|
+
* 成功的结果(0.12 的 `ToolExecutionSuccess`)。形状有变:`value` 只在插件进程里有,核心工具没有,所以是可选的;`content` 只有文本与
|
|
9
|
+
* 已存进附件存储的图片。
|
|
10
|
+
*/
|
|
11
|
+
export interface ToolExecutionSuccess {
|
|
12
|
+
readonly isError: false;
|
|
13
|
+
/** 工具体返回的结果值(按 `output.schema` 校验过),不写进会话。核心工具没有。 */
|
|
14
|
+
readonly value?: JsonValue;
|
|
15
|
+
readonly content: readonly ToolContent[];
|
|
16
|
+
readonly error?: never;
|
|
17
|
+
readonly meta?: JsonValue;
|
|
18
|
+
readonly additionalContexts?: UserMessage[];
|
|
19
|
+
/** 这一批结果记下之后结束这一轮。 */
|
|
20
|
+
readonly concludesTurn?: true;
|
|
21
|
+
}
|
|
22
|
+
/** 失败的结果(0.12 的 `ToolExecutionFailure`)。 */
|
|
23
|
+
export interface ToolExecutionFailure {
|
|
24
|
+
readonly isError: true;
|
|
25
|
+
readonly error: ToolFailure;
|
|
26
|
+
readonly value?: never;
|
|
27
|
+
readonly content: readonly ToolContent[];
|
|
28
|
+
readonly meta?: JsonValue;
|
|
29
|
+
readonly additionalContexts?: UserMessage[];
|
|
30
|
+
readonly concludesTurn?: never;
|
|
31
|
+
}
|
|
32
|
+
/** 一次工具调用的结果(0.12 的 `ToolExecutionResult`)。 */
|
|
33
|
+
export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;
|
|
34
|
+
/**
|
|
35
|
+
* `tools/post-execute` 的结论(0.12 的 `PostToolDecision`):收下、换内容或换结果值、拦下,都可以追加下一次请求的上下文。形状有变:换
|
|
36
|
+
* `value` 只对 TS 插件的工具有效(要用工具自己的 `output` 校验与渲染),核心工具没有 `output`,换它算监听者失败。
|
|
37
|
+
*/
|
|
38
|
+
export type PostToolDecision = {
|
|
39
|
+
readonly kind: 'accept';
|
|
40
|
+
readonly content?: readonly ToolContent[];
|
|
41
|
+
readonly value?: never;
|
|
42
|
+
readonly additionalContexts?: UserMessage[];
|
|
43
|
+
} | {
|
|
44
|
+
readonly kind: 'accept';
|
|
45
|
+
readonly value: JsonValue;
|
|
46
|
+
readonly content?: never;
|
|
47
|
+
readonly additionalContexts?: UserMessage[];
|
|
48
|
+
} | {
|
|
49
|
+
readonly kind: 'block';
|
|
50
|
+
readonly feedback: readonly ToolContent[];
|
|
51
|
+
readonly additionalContexts?: UserMessage[];
|
|
52
|
+
};
|
|
53
|
+
/**
|
|
54
|
+
* 只能拒绝的关口(0.12 的 `ToolGuard`):给出理由即拒绝,`undefined` 不改变结论。形状有变:可以是异步的;抛错、超时或插件进程不在时
|
|
55
|
+
* 当它没表态(0.12 按拒绝),要按拒绝时注册带 {@link ToolGuardOptions.failClosed}。
|
|
56
|
+
*/
|
|
57
|
+
export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined | Promise<string | undefined>;
|
|
58
|
+
/** `ctx.tools.guard` 的选项。 */
|
|
59
|
+
export interface ToolGuardOptions {
|
|
60
|
+
/** 失败即拒绝:关口抛错、超时或插件进程不在时拒绝这次调用,插件进程重启期间照样算数。不给时失败当它没表态。 */
|
|
61
|
+
readonly failClosed?: boolean;
|
|
62
|
+
}
|
|
63
|
+
/** `ctx.tools.execute` 的参数(0.12 的 `ToolExecutionInput`)。形状有变:`agent` 必填,工具的可见范围、权限与沙箱都按它的会话算。 */
|
|
64
|
+
export interface ToolExecutionInput {
|
|
65
|
+
readonly callId: string;
|
|
66
|
+
/** 根调用的 id:嵌套调用传 `exec.rootCallId`,根调用不传。 */
|
|
67
|
+
readonly rootCallId?: string;
|
|
68
|
+
readonly name: string;
|
|
69
|
+
/** 可以写成 JSON 的参数。 */
|
|
70
|
+
readonly arguments: unknown;
|
|
71
|
+
readonly agent: AgentHandle;
|
|
72
|
+
/** 同 0.12 由调用方持有的取消:工具体里调用时传 `exec.signal`,这一轮取消时嵌套的调用才跟着停。 */
|
|
73
|
+
readonly signal: AbortSignal;
|
|
74
|
+
}
|
|
75
|
+
/** `ctx.tools.executionMode` 的参数:调用的名字与参数,`agent` 给出时按它看到的工具判定。 */
|
|
76
|
+
export interface ToolExecutionModeInput {
|
|
77
|
+
readonly name: string;
|
|
78
|
+
readonly arguments: unknown;
|
|
79
|
+
readonly agent?: AgentHandle;
|
|
80
|
+
}
|
|
81
|
+
/** `presentResult` 拿到的结果(0.12 的 `ToolResult`)。 */
|
|
82
|
+
export interface ToolPresentedResult {
|
|
83
|
+
readonly content: readonly ToolContent[];
|
|
84
|
+
readonly isError: boolean;
|
|
85
|
+
readonly meta?: JsonValue;
|
|
86
|
+
}
|
|
87
|
+
export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';
|
|
88
|
+
export interface FileLocation {
|
|
89
|
+
path: string;
|
|
90
|
+
line?: number;
|
|
91
|
+
}
|
|
92
|
+
export interface FileDiff {
|
|
93
|
+
path: string;
|
|
94
|
+
oldText: string | null;
|
|
95
|
+
newText: string;
|
|
96
|
+
}
|
|
97
|
+
/** 待定的通用卡片。 */
|
|
98
|
+
export interface GenericCallView {
|
|
99
|
+
card: 'generic';
|
|
100
|
+
/** 卡片上一直显示的短标题,说明这次调用在做什么。 */
|
|
101
|
+
title: string;
|
|
102
|
+
kind?: ToolCallKind;
|
|
103
|
+
rawInput?: JsonValue;
|
|
104
|
+
content?: ToolContent[];
|
|
105
|
+
locations?: FileLocation[];
|
|
106
|
+
}
|
|
107
|
+
export interface TerminalCallView {
|
|
108
|
+
card: 'terminal';
|
|
109
|
+
title: string;
|
|
110
|
+
description?: string;
|
|
111
|
+
cwd?: string;
|
|
112
|
+
}
|
|
113
|
+
export interface DiffCallView {
|
|
114
|
+
card: 'diff';
|
|
115
|
+
title: string;
|
|
116
|
+
diffs: FileDiff[];
|
|
117
|
+
locations?: FileLocation[];
|
|
118
|
+
}
|
|
119
|
+
/** 工具卡片按参数的待定视图。形状有变:界面现在只用 `title`,其余字段随会话记下,不支持的卡片按通用卡片显示(同 0.12 说明里不支持的界面)。 */
|
|
120
|
+
export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;
|
|
121
|
+
/** 完成的通用卡片:`title` 换标题,`content` 里的文本换展开时看到的结果(给模型的内容不变)。 */
|
|
122
|
+
export interface GenericResultView {
|
|
123
|
+
card: 'generic';
|
|
124
|
+
title?: string;
|
|
125
|
+
content?: ToolContent[];
|
|
126
|
+
}
|
|
127
|
+
export interface TerminalResultView {
|
|
128
|
+
card: 'terminal';
|
|
129
|
+
title?: string;
|
|
130
|
+
output?: string;
|
|
131
|
+
exitCode?: number;
|
|
132
|
+
signal?: string;
|
|
133
|
+
}
|
|
134
|
+
export interface DiffResultView {
|
|
135
|
+
card: 'diff';
|
|
136
|
+
title?: string;
|
|
137
|
+
diffs: FileDiff[];
|
|
138
|
+
}
|
|
139
|
+
export interface SearchLineMatch {
|
|
140
|
+
lineNumber: number;
|
|
141
|
+
line: string;
|
|
142
|
+
}
|
|
143
|
+
export interface SearchFileMatches {
|
|
144
|
+
path: string;
|
|
145
|
+
matches: SearchLineMatch[];
|
|
146
|
+
}
|
|
147
|
+
export interface SearchMatchesResultView {
|
|
148
|
+
card: 'search';
|
|
149
|
+
shape: 'matches';
|
|
150
|
+
title?: string;
|
|
151
|
+
files: SearchFileMatches[];
|
|
152
|
+
truncated: boolean;
|
|
153
|
+
total: number;
|
|
154
|
+
}
|
|
155
|
+
export interface SearchPathsResultView {
|
|
156
|
+
card: 'search';
|
|
157
|
+
shape: 'paths';
|
|
158
|
+
title?: string;
|
|
159
|
+
paths: string[];
|
|
160
|
+
truncated: boolean;
|
|
161
|
+
total: number;
|
|
162
|
+
}
|
|
163
|
+
export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;
|
|
164
|
+
export interface ReadFileLine {
|
|
165
|
+
number: number;
|
|
166
|
+
text: string;
|
|
167
|
+
}
|
|
168
|
+
export interface ReadResultView {
|
|
169
|
+
card: 'read';
|
|
170
|
+
title?: string;
|
|
171
|
+
path: string;
|
|
172
|
+
offset: number;
|
|
173
|
+
lines: ReadFileLine[];
|
|
174
|
+
totalLines: number;
|
|
175
|
+
lang?: string;
|
|
176
|
+
content?: ToolContent[];
|
|
177
|
+
}
|
|
178
|
+
export interface WebSource {
|
|
179
|
+
url: string;
|
|
180
|
+
title?: string;
|
|
181
|
+
snippet?: string;
|
|
182
|
+
publishedAt?: string;
|
|
183
|
+
}
|
|
184
|
+
export interface WebSearchResultView {
|
|
185
|
+
card: 'web';
|
|
186
|
+
kind: 'search';
|
|
187
|
+
title?: string;
|
|
188
|
+
sources: WebSource[];
|
|
189
|
+
answer?: string;
|
|
190
|
+
truncated: boolean;
|
|
191
|
+
}
|
|
192
|
+
export interface WebFetchResultView {
|
|
193
|
+
card: 'web';
|
|
194
|
+
kind: 'fetch';
|
|
195
|
+
title?: string;
|
|
196
|
+
url: string;
|
|
197
|
+
statusCode: number;
|
|
198
|
+
truncated: boolean;
|
|
199
|
+
}
|
|
200
|
+
export type WebResultView = WebSearchResultView | WebFetchResultView;
|
|
201
|
+
/** 工具卡片按结果的完成视图。形状有变:界面现在只用 `title` 与通用卡片的 `content`,见 {@link ToolCallView}。 */
|
|
202
|
+
export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;
|
|
203
|
+
declare module 'cordis' {
|
|
204
|
+
interface EventOptions {
|
|
205
|
+
/**
|
|
206
|
+
* 宿主扩展点的监听者失败(抛错、超时、插件进程不在、答复形状不对)时按这个点的拒绝结论,插件进程重启期间它的拦截点
|
|
207
|
+
* (`tools/pre-execute`、`tools/execute`、`tools/post-execute`)照样算数。不给时失败当它没表态,宿主照常走下游;0.12 是失败
|
|
208
|
+
* 即拒绝。
|
|
209
|
+
*/
|
|
210
|
+
failClosed?: boolean;
|
|
211
|
+
}
|
|
212
|
+
}
|
package/lib/tools.js
ADDED