@ftai/plugin-host-api 0.0.0-stage → 2.0.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,579 @@
1
+ export type ToolExecution = {
2
+ token: string;
3
+ callId: string;
4
+ name: string;
5
+ /**
6
+ * 模型给的参数原文(JSON 字符串)。
7
+ */
8
+ arguments: string;
9
+ agent: AgentRef;
10
+ /**
11
+ * 发起这次调用的那一步实际用的模型(代替 0.12 插件读的 `agent.session.requestHeader().config`);子 agent 里是子
12
+ * agent 自己的。不是模型发起的调用没有。
13
+ */
14
+ model?: ModelRef;
15
+ };
16
+ export type AgentRef = {
17
+ /**
18
+ * agent 的 id,也是它的会话 id。
19
+ */
20
+ id: string;
21
+ /**
22
+ * 会话的工作目录。
23
+ */
24
+ cwd?: string;
25
+ };
26
+ export type ModelRef = {
27
+ provider: string;
28
+ model: string;
29
+ };
30
+ export type PreToolDecision = {
31
+ "kind": "allow";
32
+ } | {
33
+ "kind": "deny";
34
+ reason: string;
35
+ info?: ToolErrorInfo;
36
+ } | {
37
+ "kind": "cancel";
38
+ } | {
39
+ "kind": "ask";
40
+ reason?: string;
41
+ };
42
+ export type ToolErrorInfo = {
43
+ name: string;
44
+ code: string;
45
+ };
46
+ export type AgentCreated = {
47
+ agent: AgentRef;
48
+ source: AgentSource;
49
+ };
50
+ export type AgentSource = "startup" | "resume";
51
+ export type AssistantStream = {
52
+ agent: AgentRef;
53
+ frame: StreamFrame;
54
+ };
55
+ export type StreamFrame = {
56
+ attemptId: string;
57
+ turn: number;
58
+ step: number;
59
+ /**
60
+ * v4 的 `StreamChunk`(`text-delta`、`reasoning-delta`、`block-start` 等)。
61
+ */
62
+ chunk: Record<string, unknown>;
63
+ };
64
+ export type SessionEventNotice = {
65
+ sessionId: string;
66
+ event: Record<string, unknown>;
67
+ };
68
+ export type ToolRegistration = {
69
+ /**
70
+ * 只对这个 agent 生效(0.12 的 `agent.ctx.tools.register`);不给时为全局。
71
+ */
72
+ agent?: string;
73
+ schema: ToolSchema;
74
+ /**
75
+ * 默认要用户审批(`tools/pre-execute` 的默认结论为 ask)。
76
+ */
77
+ needsApproval: boolean;
78
+ /**
79
+ * 可以为这次调用申请更宽的沙箱模式,同核心的文件工具:宿主给参数表加上 `sandbox_permissions` 与 `justification`,
80
+ * 执行之前经审批定下这一次的模式,`fs.writeBytes` 带着这次调用写入时按它围住。参数表里不能自带这两个参数。
81
+ */
82
+ sandboxEscalation?: boolean;
83
+ /**
84
+ * 并发安全(0.12 的 `isConcurrencySafe`):同一条回复里相邻的并发安全调用一起跑。只读、互相不影响的工具才给;
85
+ * 不给时独占。
86
+ */
87
+ concurrencySafe?: boolean;
88
+ };
89
+ export type ToolSchema = {
90
+ name: string;
91
+ description: string;
92
+ parameters: Record<string, unknown>;
93
+ };
94
+ export type ToolCall = {
95
+ exec: ToolExecution;
96
+ /**
97
+ * 会话当前的工作目录。
98
+ */
99
+ cwd: string;
100
+ };
101
+ export type ToolOutcome = {
102
+ content: Array<ToolContent>;
103
+ isError: boolean;
104
+ };
105
+ export type ImageRef = {
106
+ attachmentId: string;
107
+ mediaType: ImageMediaType;
108
+ width: number;
109
+ height: number;
110
+ bytes: number;
111
+ name?: string;
112
+ /**
113
+ * 规范化缩小过时,应用 EXIF 方向之后、缩小之前的尺寸。
114
+ */
115
+ originalDimensions?: Dimensions;
116
+ };
117
+ export type Dimensions = {
118
+ width: number;
119
+ height: number;
120
+ };
121
+ export type ImageMediaType = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
122
+ export type ToolContent = {
123
+ "type": "text";
124
+ text: string;
125
+ } | {
126
+ "type": "image";
127
+ attachment: ImageRef;
128
+ };
129
+ export type ToolFilter = {
130
+ allow?: Array<string>;
131
+ deny?: Array<string>;
132
+ };
133
+ export type PromptSection = {
134
+ name: string;
135
+ order: number;
136
+ text: string;
137
+ };
138
+ export type JsonValue = number | string | boolean | Array<JsonValue> | {
139
+ [key in string]: JsonValue;
140
+ } | null;
141
+ export type RemoteParam = {
142
+ /**
143
+ * 参数名,只用于报错。
144
+ */
145
+ name: string;
146
+ /**
147
+ * 可选参数:界面不给或给 null 都算没给。
148
+ */
149
+ optional: boolean;
150
+ /**
151
+ * 参数类型的 JSON Schema(type、oneOf、properties、required、items、enum、const 的子集,同工具参数的校验)。
152
+ */
153
+ schema: JsonValue;
154
+ };
155
+ export type RemoteMethod = {
156
+ /**
157
+ * 界面调用的方法名。
158
+ */
159
+ name: string;
160
+ /**
161
+ * 流式方法(`@Remote({ mode: 'stream' })`):逐条给出结果。
162
+ */
163
+ stream: boolean;
164
+ /**
165
+ * 按位置的参数(不含宿主代传的最后一个 `signal`),由 `ftai-plugin-remote` 从参数类型生成。宿主调用前按它核对界面给的
166
+ * 参数(同 0.12 网关的 `gateway/input-invalid`);没有时不核对(插件的 remote 产物不是这样生成的)。
167
+ */
168
+ params?: Array<RemoteParam>;
169
+ };
170
+ export type RemoteInvocation = {
171
+ method: string;
172
+ /**
173
+ * 按位置的参数(JSON)。
174
+ */
175
+ args: Array<JsonValue>;
176
+ };
177
+ export type FsResolved = {
178
+ target: FsTarget;
179
+ processPath: string;
180
+ };
181
+ export type FsTarget = {
182
+ targetKey: string;
183
+ displayPath: string;
184
+ };
185
+ export type FsFileType = "file" | "directory" | "other";
186
+ export type FsInfo = {
187
+ version: string;
188
+ type: FsFileType;
189
+ size: number;
190
+ };
191
+ export type FsWriteIntent = {
192
+ "kind": "createIfAbsent";
193
+ } | {
194
+ "kind": "replaceIfVersion";
195
+ version: string;
196
+ };
197
+ export type FsWritten = {
198
+ operation: FsWriteOperation;
199
+ version: string;
200
+ };
201
+ export type FsWriteOperation = "create" | "update";
202
+ export type ImageUpload = {
203
+ data: string;
204
+ mediaType: string;
205
+ name?: string;
206
+ };
207
+ export type ModelRoute = {
208
+ provider: string;
209
+ displayName: string;
210
+ models: Array<ModelSpec>;
211
+ };
212
+ export type CompletionsCompat = {
213
+ /**
214
+ * 推理模型的系统提示用 developer 角色;不支持时用 system。
215
+ */
216
+ supportsDeveloperRole: boolean;
217
+ /**
218
+ * 请求体带 `store: false`。
219
+ */
220
+ supportsStore: boolean;
221
+ maxTokensField: MaxTokensField;
222
+ /**
223
+ * 推理强度放在请求体顶层的 `reasoning_effort`。
224
+ */
225
+ supportsReasoningEffort: boolean;
226
+ };
227
+ export type MaxTokensField = "max_tokens" | "max_completion_tokens";
228
+ export type ModelApi = "openai-completions" | "openai-responses";
229
+ export type ModelSpec = {
230
+ /**
231
+ * 服务端的模型 id,原样放进请求体,也是会话记录的 model。
232
+ */
233
+ id: string;
234
+ /**
235
+ * 模型选择器里的名字。
236
+ */
237
+ name: string;
238
+ api: ModelApi;
239
+ contextWindow: number;
240
+ /**
241
+ * 请求的输出上限(发出前按上下文估算再往下裁)。
242
+ */
243
+ maxOutputTokens: number;
244
+ /**
245
+ * 可选的推理强度(界面的档位 id,原样发给服务端);空表示不推理,请求不带推理参数。
246
+ */
247
+ reasoningEfforts: Array<string>;
248
+ defaultReasoningEffort?: string;
249
+ /**
250
+ * 接受图片输入。
251
+ */
252
+ images: boolean;
253
+ /**
254
+ * 不进模型目录,只供插件按 id 请求(如文档识别用的模型)。
255
+ */
256
+ hidden: boolean;
257
+ /**
258
+ * 压缩为输出预留 `max_output_tokens`:只有显式配置了输出上限的模型才预留(0.12 的模型信息此时才带 defaultMaxTokens),
259
+ * 其余按不预留算触发压缩的阈值。
260
+ */
261
+ reserveOutput: boolean;
262
+ /**
263
+ * 只对 Chat Completions 有效;不给时按协议的默认格式发。
264
+ */
265
+ compat?: CompletionsCompat;
266
+ };
267
+ export type RouteCredentials = {
268
+ /**
269
+ * 协议的根地址,请求发往 `{baseUrl}/chat/completions` 或 `{baseUrl}/responses`。
270
+ */
271
+ baseUrl: string;
272
+ /**
273
+ * 作为 `Authorization: Bearer` 发出;不给就不发。
274
+ */
275
+ apiKey?: string;
276
+ /**
277
+ * 其余请求头。
278
+ */
279
+ headers: {
280
+ [key in string]: string;
281
+ };
282
+ };
283
+ export type LlmModelInfo = {
284
+ provider: string;
285
+ id: string;
286
+ name: string;
287
+ inputModalities: Array<InputModality>;
288
+ context: LlmModelContext;
289
+ /**
290
+ * 只在路由给模型显式配了输出上限时有(同 pi-ai 的 configuredMaxTokens)。
291
+ */
292
+ defaultMaxTokens?: number;
293
+ };
294
+ export type InputModality = "text" | "image";
295
+ export type LlmModelContext = {
296
+ contextWindow: number;
297
+ };
298
+ export type GenerateRequest = {
299
+ provider: string;
300
+ model: string;
301
+ system?: string;
302
+ messages: Array<RequestMessage>;
303
+ /**
304
+ * 输出上限;不给时用模型的,按上下文估算往下裁。
305
+ */
306
+ maxTokens?: number;
307
+ /**
308
+ * 推理档位;不给时用模型的默认档位,不推理的模型不带。
309
+ */
310
+ reasoningEffort?: string;
311
+ /**
312
+ * 会话 id:协议支持时作提示缓存的键。
313
+ */
314
+ sessionId?: string;
315
+ };
316
+ export type AssistantContent = {
317
+ "type": "text";
318
+ text: string;
319
+ } | {
320
+ "type": "reasoning";
321
+ text: string;
322
+ };
323
+ export type FileRef = {
324
+ attachmentId: string;
325
+ name: string;
326
+ bytes: number;
327
+ };
328
+ export type UserContent = {
329
+ "type": "text";
330
+ text: string;
331
+ } | {
332
+ "type": "image";
333
+ attachment: ImageRef;
334
+ } | {
335
+ "type": "file";
336
+ attachment: FileRef;
337
+ };
338
+ export type RequestMessage = {
339
+ "role": "user";
340
+ content: Array<UserContent>;
341
+ } | {
342
+ "role": "assistant";
343
+ content: Array<AssistantContent>;
344
+ };
345
+ /** 宿主的扩展点:名字 → 交互方式、载荷与结论。 */
346
+ export interface HostPoints {
347
+ /** 工具执行前:放行、拒绝、取消,或要求审批。默认放行;跨进程超时或崩溃按拒绝。 */
348
+ 'tools/pre-execute': {
349
+ kind: 'waterfall';
350
+ input: ToolExecution;
351
+ output: PreToolDecision;
352
+ };
353
+ /**
354
+ * agent 建好:在这里按会话注册工具、提示词段与收起工具,从第一步起生效。新会话(`startup`)在交给调用方之前发:建会话、
355
+ * 发送新会话的第一条消息时在输入排进队列之前,分叉(含侧聊与编辑重发)时在返回新会话之前;监听者失败时会话不建,
356
+ * 错误原样交回调用方,输入退回。续上已有的会话(`resume`)与新建的子 agent 在第一步之前发,监听者失败只记日志。
357
+ */
358
+ 'agent/created': {
359
+ kind: 'wait';
360
+ input: AgentCreated;
361
+ output: void;
362
+ };
363
+ /** 模型的流式输出,每段一次;跨进程时按批推送。 */
364
+ 'agent/assistant-stream': {
365
+ kind: 'observe';
366
+ input: AssistantStream;
367
+ output: void;
368
+ };
369
+ /** 每条落盘的会话事件;插件的会话投影由它驱动。 */
370
+ 'session/event': {
371
+ kind: 'observe';
372
+ input: SessionEventNotice;
373
+ output: void;
374
+ };
375
+ }
376
+ /** 扩展点名 → 交互方式与 SDK 是否另包一层,运行时按它把监听转发给宿主。 */
377
+ export declare const HOST_POINTS: {
378
+ readonly 'tools/pre-execute': {
379
+ readonly kind: "waterfall";
380
+ readonly wrapped: true;
381
+ };
382
+ readonly 'agent/created': {
383
+ readonly kind: "wait";
384
+ readonly wrapped: true;
385
+ };
386
+ readonly 'agent/assistant-stream': {
387
+ readonly kind: "observe";
388
+ readonly wrapped: true;
389
+ };
390
+ readonly 'session/event': {
391
+ readonly kind: "observe";
392
+ readonly wrapped: true;
393
+ };
394
+ };
395
+ /** 宿主的服务:服务名 → 方法名 → 交互方式、按位置的参数、结论与回调。 */
396
+ export interface HostServices {
397
+ /** 注册模型可调用的工具(0.12 的 `ctx.tools`)。 */
398
+ 'tools': {
399
+ /** 注册一个工具,执行时经回调回到插件。 */
400
+ 'register': {
401
+ kind: 'register';
402
+ args: [tool: ToolRegistration];
403
+ output: void;
404
+ callback: {
405
+ input: ToolCall;
406
+ output: ToolOutcome;
407
+ };
408
+ };
409
+ /** 按 agent 收起全局工具(多个限制取交集)。 */
410
+ 'restrict': {
411
+ kind: 'register';
412
+ args: [agent: string, filter: ToolFilter];
413
+ output: void;
414
+ };
415
+ };
416
+ /** 系统提示词段(0.12 的 `ctx.systemPrompt`)。 */
417
+ 'systemPrompt': {
418
+ /** 注册一段;`agent` 给出时只对这个 agent 生效。 */
419
+ 'section': {
420
+ kind: 'register';
421
+ args: [agent: string | null, section: PromptSection];
422
+ output: void;
423
+ };
424
+ };
425
+ /**
426
+ * 插件后端给界面的 remote(0.12 的 `TypertRemoteService`):SDK 的 `TypertRemoteService` 用它挂载命名空间,
427
+ * 界面经宿主协议的 `pluginRemote.*` 调用。
428
+ */
429
+ 'pluginRemote': {
430
+ /** 挂载一个命名空间,随服务撤销;同名命名空间已挂载时失败。 */
431
+ 'mount': {
432
+ kind: 'register';
433
+ args: [namespace: string, methods: Array<RemoteMethod>];
434
+ output: void;
435
+ callback: {
436
+ input: RemoteInvocation;
437
+ output: JsonValue;
438
+ };
439
+ };
440
+ };
441
+ /** 会话日志(0.12 的 `ctx.sessions` 与 `appendPluginRecord`)。 */
442
+ 'sessions': {
443
+ /** 追加一条插件记录(可忽略的会话事件,模型看不到),返回它的 seq。 */
444
+ 'appendPluginRecord': {
445
+ kind: 'call';
446
+ args: [sessionId: string, recordType: string, data: JsonValue];
447
+ output: number;
448
+ };
449
+ /** 会话里已落盘的全部事件(v4 的行,`sourceEventSeqs` 已展开);插件进程据此整批折叠会话投影。 */
450
+ 'events': {
451
+ kind: 'call';
452
+ args: [sessionId: string];
453
+ output: Array<JsonValue>;
454
+ };
455
+ };
456
+ /** 文件(0.12 的 `ctx.fs`):与文件工具同一套路径解析与写入。不是权限边界(TS 插件进程本来就能读写本机文件)。 */
457
+ 'fs': {
458
+ /** 解析路径;相对路径按 `cwd`,不给时用宿主的默认目录。不存在的路径也能定位。 */
459
+ 'resolve': {
460
+ kind: 'call';
461
+ args: [path: string, cwd: string | null];
462
+ output: FsResolved;
463
+ };
464
+ /** 元数据;不存在时为 null。 */
465
+ 'stat': {
466
+ kind: 'call';
467
+ args: [target: FsTarget];
468
+ output: FsInfo | null;
469
+ };
470
+ /** 读出整份文件,字节按 base64;超过 `maxBytes` 报 `FS_TOO_LARGE`。 */
471
+ 'readBytes': {
472
+ kind: 'call';
473
+ args: [target: FsTarget, maxBytes: number];
474
+ output: string;
475
+ };
476
+ /**
477
+ * 写入整份二进制(字节按 base64):`execution`(工具调用的 token)给出时先跑 `fs/write-intent`,本轮改动记录据此
478
+ * 存下原文件;调用已经结束或 token 不对时拒绝。写入条件只看 `expected`(不给即无条件),不用瀑布的结论。
479
+ * 在目标目录里原子发布,沿用原文件的权限,缺的父目录一并建。
480
+ */
481
+ 'writeBytes': {
482
+ kind: 'call';
483
+ args: [target: FsTarget, data: string, execution: string | null, expected: FsWriteIntent | null];
484
+ output: FsWritten;
485
+ };
486
+ };
487
+ /** 附件(0.12 的 `ctx.attachments`)。 */
488
+ 'attachments': {
489
+ /** 存一批图片,同 0.12 的 `saveImages`:先整批检查,全部准入、规范化通过才写入;结论与输入同序。 */
490
+ 'saveImages': {
491
+ kind: 'call';
492
+ args: [images: Array<ImageUpload>];
493
+ output: Array<ImageRef>;
494
+ };
495
+ };
496
+ /** 模型(0.12 的 `ctx.llm`):注册模型路由、按 id 取模型信息、插件直接调用模型。 */
497
+ 'llm': {
498
+ /**
499
+ * 注册一条路由(0.12 的 `registerAdapter`):一个 provider 与它的模型清单,每次请求经回调向插件取地址与凭据,回调的载荷是
500
+ * provider 名。清单变了就撤销旧的注册、再注册一次。
501
+ */
502
+ 'registerRoute': {
503
+ kind: 'register';
504
+ args: [route: ModelRoute];
505
+ output: void;
506
+ callback: {
507
+ input: string;
508
+ output: RouteCredentials;
509
+ };
510
+ };
511
+ /** 按 id 取模型信息:没有这个 provider 报 `NO_ADAPTER`,有 provider 没有这个模型报 `UNKNOWN_MODEL`。 */
512
+ 'resolveModelInfo': {
513
+ kind: 'call';
514
+ args: [provider: string, model: string];
515
+ output: LlmModelInfo;
516
+ };
517
+ /**
518
+ * 直接调用模型:逐条给出会话格式 v4 的 StreamChunk,最后两条是 usage 与 finish;失败也是 finish(`reason.kind` 为
519
+ * `error`,带 `failure.code`)。不重试。
520
+ */
521
+ 'stream': {
522
+ kind: 'stream';
523
+ args: [request: GenerateRequest];
524
+ output: JsonValue;
525
+ };
526
+ };
527
+ }
528
+ /** 服务名 → SDK 是否另包一层、各方法的交互方式;运行时据此建代理与路由。 */
529
+ export declare const HOST_SERVICES: {
530
+ readonly tools: {
531
+ readonly wrapped: true;
532
+ readonly methods: {
533
+ readonly register: "register";
534
+ readonly restrict: "register";
535
+ };
536
+ };
537
+ readonly systemPrompt: {
538
+ readonly wrapped: true;
539
+ readonly methods: {
540
+ readonly section: "register";
541
+ };
542
+ };
543
+ readonly pluginRemote: {
544
+ readonly wrapped: true;
545
+ readonly methods: {
546
+ readonly mount: "register";
547
+ };
548
+ };
549
+ readonly sessions: {
550
+ readonly wrapped: true;
551
+ readonly methods: {
552
+ readonly appendPluginRecord: "call";
553
+ readonly events: "call";
554
+ };
555
+ };
556
+ readonly fs: {
557
+ readonly wrapped: true;
558
+ readonly methods: {
559
+ readonly resolve: "call";
560
+ readonly stat: "call";
561
+ readonly readBytes: "call";
562
+ readonly writeBytes: "call";
563
+ };
564
+ };
565
+ readonly attachments: {
566
+ readonly wrapped: true;
567
+ readonly methods: {
568
+ readonly saveImages: "call";
569
+ };
570
+ };
571
+ readonly llm: {
572
+ readonly wrapped: true;
573
+ readonly methods: {
574
+ readonly registerRoute: "register";
575
+ readonly resolveModelInfo: "call";
576
+ readonly stream: "stream";
577
+ };
578
+ };
579
+ };
@@ -0,0 +1,20 @@
1
+ // 由 apps/rust-host/crates/ext 的扩展点表生成,不要手改:改表之后运行
2
+ // UPDATE_GENERATED=1 cargo test --manifest-path apps/rust-host/Cargo.toml -p ftai-ext
3
+ /** 扩展点名 → 交互方式与 SDK 是否另包一层,运行时按它把监听转发给宿主。 */
4
+ export const HOST_POINTS = {
5
+ 'tools/pre-execute': { kind: 'waterfall', wrapped: true },
6
+ 'agent/created': { kind: 'wait', wrapped: true },
7
+ 'agent/assistant-stream': { kind: 'observe', wrapped: true },
8
+ 'session/event': { kind: 'observe', wrapped: true },
9
+ };
10
+ /** 服务名 → SDK 是否另包一层、各方法的交互方式;运行时据此建代理与路由。 */
11
+ export const HOST_SERVICES = {
12
+ 'tools': { wrapped: true, methods: { 'register': 'register', 'restrict': 'register' } },
13
+ 'systemPrompt': { wrapped: true, methods: { 'section': 'register' } },
14
+ 'pluginRemote': { wrapped: true, methods: { 'mount': 'register' } },
15
+ 'sessions': { wrapped: true, methods: { 'appendPluginRecord': 'call', 'events': 'call' } },
16
+ 'fs': { wrapped: true, methods: { 'resolve': 'call', 'stat': 'call', 'readBytes': 'call', 'writeBytes': 'call' } },
17
+ 'attachments': { wrapped: true, methods: { 'saveImages': 'call' } },
18
+ 'llm': { wrapped: true, methods: { 'registerRoute': 'register', 'resolveModelInfo': 'call', 'stream': 'stream' } },
19
+ };
20
+ //# sourceMappingURL=generated.js.map