@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.
Files changed (51) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +4 -2
  3. package/lib/attachments.d.ts +149 -0
  4. package/lib/attachments.js +26 -0
  5. package/lib/capabilities.d.ts +99 -0
  6. package/lib/capabilities.js +21 -0
  7. package/lib/cmdline.d.ts +52 -0
  8. package/lib/cmdline.js +68 -0
  9. package/lib/credentials.d.ts +92 -0
  10. package/lib/credentials.js +41 -0
  11. package/lib/fs.d.ts +117 -0
  12. package/lib/fs.js +14 -0
  13. package/lib/generated.d.ts +4198 -0
  14. package/lib/generated.js +80 -0
  15. package/lib/index.d.ts +665 -0
  16. package/lib/index.js +151 -0
  17. package/lib/jobs.d.ts +88 -0
  18. package/lib/jobs.js +2 -0
  19. package/lib/llm.d.ts +255 -0
  20. package/lib/llm.js +144 -0
  21. package/lib/local-install.d.ts +38 -0
  22. package/lib/local-install.js +9 -0
  23. package/lib/permissions.d.ts +97 -0
  24. package/lib/permissions.js +11 -0
  25. package/lib/platform.d.ts +167 -0
  26. package/lib/platform.js +74 -0
  27. package/lib/porting.d.ts +51 -0
  28. package/lib/porting.js +752 -0
  29. package/lib/prompt.d.ts +117 -0
  30. package/lib/prompt.js +43 -0
  31. package/lib/runtime-context.d.ts +29 -0
  32. package/lib/runtime-context.js +6 -0
  33. package/lib/schedule-types.d.ts +333 -0
  34. package/lib/schedule-types.js +4 -0
  35. package/lib/session-events.d.ts +194 -0
  36. package/lib/session-events.js +2 -0
  37. package/lib/sessions.d.ts +246 -0
  38. package/lib/sessions.js +2 -0
  39. package/lib/settings.d.ts +86 -0
  40. package/lib/settings.js +13 -0
  41. package/lib/storage.d.ts +144 -0
  42. package/lib/storage.js +62 -0
  43. package/lib/subagents.d.ts +57 -0
  44. package/lib/subagents.js +17 -0
  45. package/lib/subprocess.d.ts +97 -0
  46. package/lib/subprocess.js +8 -0
  47. package/lib/tools.d.ts +212 -0
  48. package/lib/tools.js +2 -0
  49. package/lib/web.d.ts +192 -0
  50. package/lib/web.js +53 -0
  51. package/package.json +40 -3
package/lib/fs.d.ts ADDED
@@ -0,0 +1,117 @@
1
+ /**
2
+ * 文件(0.12 的 `ctx.fs`,0.12 的 `fs` 包):与文件工具同一套路径解析、读取与写入,名字与参数照 0.12。
3
+ *
4
+ * 插件进程本来就能用 `node:fs` 读写本机文件,`ctx.fs` 不是权限边界。用它是为了与 read、write 工具对同一个路径得到同一个
5
+ * 文件,写入先经本轮改动记录(`fs/write-intent`,改动面板据此显示与撤销),并受会话的沙箱约束。
6
+ *
7
+ * 与 0.12 不同的地方:
8
+ * - 文件由宿主写(`writeBytes`,0.12 没有;`writeText` 是它按 UTF-8 编码的写法),插件不再自己写、自己围沙箱;
9
+ * - 读取的 `signal` 中止时宿主丢掉这次调用,抛 `signal.reason`(不是 `FS_ABORTED`);写入与编辑的 `signal` 只在发出之前查一次,
10
+ * 发出之后不会写成了却报中止;
11
+ * - 整份文本、一段字节与列目录带上限,超过时报 `FS_TOO_LARGE`,不返回截断的内容(见各方法);
12
+ * - `targetKey` 与 `version` 是普通字符串,不是 0.12 的品牌类型;目标、元数据与写入条件的形状由扩展点表生成(`FsTarget`、
13
+ * `FsInfo`、`FsWriteIntent`),`FsInfo.size` 总是有。
14
+ * @module
15
+ */
16
+ import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsWriteIntent, FsWritten } from './generated.ts';
17
+ /** 文件版本,只用来比较(0.12 是品牌类型)。 */
18
+ export type FsVersion = string;
19
+ import type { ToolExecution } from './index.ts';
20
+ export interface FsWriteBytesOptions {
21
+ /**
22
+ * 发起写入的工具调用:本轮改动记录据此先存下原文件,沙箱按这次调用。给了但调用已经结束时宿主拒绝写入。不给时是插件自己的写入,
23
+ * 按部署默认的模式围住(同 `ctx.sandboxPolicy.resolve()` 不给会话时,越界报 `FS_SANDBOX_DENIED`)。
24
+ */
25
+ readonly execution?: ToolExecution;
26
+ /** 写入条件;不给即无条件新建或覆盖。 */
27
+ readonly expected?: FsWriteIntent;
28
+ readonly signal?: AbortSignal;
29
+ }
30
+ export interface FsEditOptions {
31
+ /**
32
+ * 发起编辑的工具调用。给了时同核心 edit 工具:这个会话的文件工具要读过这个文件(否则 `FS_NOT_OBSERVED`),读到的版本要没过期
33
+ * (否则 `FS_STALE_VERSION`),沙箱按这次调用,改完后文件工具按新版本核对。调用已经结束时宿主拒绝。不给时是插件自己的改动,
34
+ * 不核对读过与否,按部署默认的模式围住(同 `ctx.sandboxPolicy.resolve()` 不给会话时,越界报 `FS_SANDBOX_DENIED`)。
35
+ */
36
+ readonly execution?: ToolExecution;
37
+ /** 调用方要求的版本,与上面的条件都要满足,不能代替它。 */
38
+ readonly expected?: {
39
+ readonly version: string;
40
+ };
41
+ readonly signal?: AbortSignal;
42
+ }
43
+ export declare const FS_ERROR_CODES: readonly ["FS_NOT_FOUND", "FS_NOT_DIRECTORY", "FS_NOT_TEXT", "FS_NOT_REGULAR_FILE", "FS_TOO_LARGE", "FS_PERMISSION_DENIED", "FS_SANDBOX_DENIED", "FS_IO_ERROR", "FS_STALE_VERSION", "FS_NOT_OBSERVED", "FS_AMBIGUOUS_EDIT", "FS_EDIT_NOT_FOUND", "FS_ABORTED"];
44
+ export type FsErrorCode = typeof FS_ERROR_CODES[number];
45
+ /** 文件服务的失败(同 0.12):稳定的错误码与给模型看的说明。 */
46
+ export declare class FsError extends Error {
47
+ readonly code: FsErrorCode;
48
+ constructor(message: string, code: FsErrorCode, options?: ErrorOptions);
49
+ }
50
+ export interface FileSystemService {
51
+ /**
52
+ * 解析路径;相对路径按 `cwd`(不给时用宿主的默认目录),不存在的路径也能定位。
53
+ * @returns 目标;同一个文件得到同一个 `targetKey`。
54
+ */
55
+ resolve(path: string, opts?: {
56
+ readonly cwd?: string;
57
+ readonly signal?: AbortSignal;
58
+ }): Promise<FsTarget>;
59
+ /**
60
+ * 给子进程或别的系统能力用的绝对路径(同步)。
61
+ * @param target - 本进程得到的目标:`resolve`、`listDir` 或 `fs/*` 扩展点给的。
62
+ */
63
+ processPath(target: FsTarget): string;
64
+ /**
65
+ * 宿主上的绝对路径 → 给子进程或别的系统能力用的路径(同步)。插件进程与宿主在同一个文件系统上,绝对路径原样给出
66
+ * (不做 realpath,要与文件工具同一个身份时用 `resolve`)。
67
+ * @returns 不是绝对路径时为 undefined。
68
+ */
69
+ processPathFromHostPath(hostPath: string): string | undefined;
70
+ /** 目标的 `file://` 地址(同步)。目标的要求同 `processPath`。 */
71
+ fileUrl(target: FsTarget): string;
72
+ /** `child` 是 `parent` 本身或在它下面(同步,只比较定位后的路径,不访问文件)。目标的要求同 `processPath`。 */
73
+ contains(parent: FsTarget, child: FsTarget): boolean;
74
+ /** 元数据;不存在时为 undefined。 */
75
+ stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
76
+ /** 路径本身的元数据,不跟随最后一段的符号链接;不存在时为 undefined。相对路径的规则同 `resolve`。 */
77
+ lstat(path: string, opts?: {
78
+ readonly cwd?: string;
79
+ }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
80
+ /** 读出整份 UTF-8 文本:开头的 BOM 去掉,二进制或不是合法 UTF-8 报 `FS_NOT_TEXT`,超过 10 MiB 报 `FS_TOO_LARGE`(用 `streamText`)。 */
81
+ readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
82
+ /** 分块读文本,规则同 `readText`,不限大小。一块向宿主要一次(块的边界没有含义),调用方不要下一块时宿主不多读。 */
83
+ streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
84
+ /**
85
+ * 读出整份文件。
86
+ * @param maxBytes - 上限(含);超过时报 `FS_TOO_LARGE`,不返回截断的内容。
87
+ */
88
+ readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
89
+ /** 按偏移读一段原始字节:文件在这一段里结束时短一些,`offset` 在文件末尾之后时为空。`length` 超过 10 MiB 报 `FS_TOO_LARGE`。 */
90
+ readByteRange(target: FsTarget, range: {
91
+ readonly offset: number;
92
+ readonly length: number;
93
+ }, signal?: AbortSignal): Promise<Uint8Array>;
94
+ /** 列目录的直接子项,按名字排序,不读内容。超过 10000 项报 `FS_TOO_LARGE`,不返回截断的清单。 */
95
+ listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
96
+ /** 写入整份二进制:在目标目录里原子发布,沿用原文件的权限,缺的父目录一并建。 */
97
+ writeBytes(target: FsTarget, data: Uint8Array, options?: FsWriteBytesOptions): Promise<FsWritten>;
98
+ /**
99
+ * 写入整份文本(UTF-8),其余同 `writeBytes`。形状有变:0.12 的参数是 `(target, content, expected, signal, sandboxPolicy)`;
100
+ * 沙箱由宿主按 `execution` 围住,不再由调用方传入。
101
+ */
102
+ writeText(target: FsTarget, content: string, options?: FsWriteBytesOptions): Promise<FsWritten>;
103
+ /**
104
+ * 按字面替换编辑:默认要求恰好出现一次。形状有变:0.12 的参数是 `(target, edit, expected, signal, sandboxPolicy)`,由调用方自己跑
105
+ * `fs/edit-intent`;这里宿主跑,见 {@link FsEditOptions}。与 `writeBytes` 的差别:`writeBytes` 只看调用方给的 `expected`,不用
106
+ * `fs/write-intent` 的条件;`editText` 用 `fs/edit-intent` 的结论。监听者的报错两者都让这次改动失败。
107
+ */
108
+ editText(target: FsTarget, edit: FsEditRequest, options?: FsEditOptions): Promise<FsEditOutcome>;
109
+ /**
110
+ * 监听一个目标:文件只报它自己,目录报直接子项,还不存在的路径等它出现。兑现时监听已经就位。第一处变化起 200ms 内的变化合并成
111
+ * 一次 `changed()`。系统监听挂不上(如监听数量耗尽)时不报错,只是收不到变化。
112
+ * @param changed - 变化时调用;监听意外结束时带上错误,之后不再调用。
113
+ * @param signal - 随时停止,不只是初始化期间(0.12 只管初始化)。调用方的作用域撤销时同样停止。
114
+ * @returns 停止监听,等它停下。
115
+ */
116
+ watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
117
+ }
package/lib/fs.js ADDED
@@ -0,0 +1,14 @@
1
+ export const FS_ERROR_CODES = [
2
+ 'FS_NOT_FOUND', 'FS_NOT_DIRECTORY', 'FS_NOT_TEXT', 'FS_NOT_REGULAR_FILE', 'FS_TOO_LARGE', 'FS_PERMISSION_DENIED', 'FS_SANDBOX_DENIED',
3
+ 'FS_IO_ERROR', 'FS_STALE_VERSION', 'FS_NOT_OBSERVED', 'FS_AMBIGUOUS_EDIT', 'FS_EDIT_NOT_FOUND', 'FS_ABORTED',
4
+ ];
5
+ /** 文件服务的失败(同 0.12):稳定的错误码与给模型看的说明。 */
6
+ export class FsError extends Error {
7
+ code;
8
+ constructor(message, code, options) {
9
+ super(message, options);
10
+ this.code = code;
11
+ this.name = 'FsError';
12
+ }
13
+ }
14
+ //# sourceMappingURL=fs.js.map