@ftai/plugin-host-api 2.0.0 → 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 (47) hide show
  1. package/lib/attachments.d.ts +112 -1
  2. package/lib/capabilities.d.ts +99 -0
  3. package/lib/capabilities.js +21 -0
  4. package/lib/cmdline.d.ts +52 -0
  5. package/lib/cmdline.js +68 -0
  6. package/lib/credentials.d.ts +92 -0
  7. package/lib/credentials.js +41 -0
  8. package/lib/fs.d.ts +69 -5
  9. package/lib/generated.d.ts +3935 -316
  10. package/lib/generated.js +66 -6
  11. package/lib/index.d.ts +365 -69
  12. package/lib/index.js +44 -3
  13. package/lib/jobs.d.ts +88 -0
  14. package/lib/jobs.js +2 -0
  15. package/lib/llm.d.ts +124 -21
  16. package/lib/llm.js +45 -3
  17. package/lib/local-install.d.ts +38 -0
  18. package/lib/local-install.js +9 -0
  19. package/lib/permissions.d.ts +97 -0
  20. package/lib/permissions.js +11 -0
  21. package/lib/platform.d.ts +167 -0
  22. package/lib/platform.js +74 -0
  23. package/lib/porting.d.ts +23 -7
  24. package/lib/porting.js +692 -67
  25. package/lib/prompt.d.ts +117 -0
  26. package/lib/prompt.js +43 -0
  27. package/lib/runtime-context.d.ts +29 -0
  28. package/lib/runtime-context.js +6 -0
  29. package/lib/schedule-types.d.ts +333 -0
  30. package/lib/schedule-types.js +4 -0
  31. package/lib/session-events.d.ts +194 -0
  32. package/lib/session-events.js +2 -0
  33. package/lib/sessions.d.ts +246 -0
  34. package/lib/sessions.js +2 -0
  35. package/lib/settings.d.ts +86 -0
  36. package/lib/settings.js +13 -0
  37. package/lib/storage.d.ts +144 -0
  38. package/lib/storage.js +62 -0
  39. package/lib/subagents.d.ts +57 -0
  40. package/lib/subagents.js +17 -0
  41. package/lib/subprocess.d.ts +97 -0
  42. package/lib/subprocess.js +8 -0
  43. package/lib/tools.d.ts +212 -0
  44. package/lib/tools.js +2 -0
  45. package/lib/web.d.ts +192 -0
  46. package/lib/web.js +53 -0
  47. package/package.json +1 -1
@@ -1,6 +1,10 @@
1
1
  export type ToolExecution = {
2
2
  token: string;
3
3
  callId: string;
4
+ /**
5
+ * 所在调用树的根调用:嵌套调用(工具体里经 `tools.execute` 发起并带上的)才有,根调用没有,等于 `callId`。
6
+ */
7
+ rootCallId?: string;
4
8
  name: string;
5
9
  /**
6
10
  * 模型给的参数原文(JSON 字符串)。
@@ -38,69 +42,34 @@ export type PreToolDecision = {
38
42
  } | {
39
43
  "kind": "ask";
40
44
  reason?: string;
45
+ /**
46
+ * 给界面的多语言说明(`{ en, zh, … }`,`en` 必有),不落盘。形状不对时当作没给。
47
+ */
48
+ displayReason?: {
49
+ readonly en: string;
50
+ readonly [locale: string]: string;
51
+ };
41
52
  };
42
53
  export type ToolErrorInfo = {
43
54
  name: string;
44
55
  code: string;
45
56
  };
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;
57
+ export type ToolResultData = {
58
+ content: Array<ToolContent>;
59
+ isError: boolean;
60
+ error?: ToolFailure;
78
61
  /**
79
- * 可以为这次调用申请更宽的沙箱模式,同核心的文件工具:宿主给参数表加上 `sandbox_permissions` 与 `justification`,
80
- * 执行之前经审批定下这一次的模式,`fs.writeBytes` 带着这次调用写入时按它围住。参数表里不能自带这两个参数。
62
+ * 记在 tool/result 上给界面用,模型看不到。
81
63
  */
82
- sandboxEscalation?: boolean;
64
+ meta?: JsonValue;
83
65
  /**
84
- * 并发安全(0.12 的 `isConcurrencySafe`):同一条回复里相邻的并发安全调用一起跑。只读、互相不影响的工具才给;
85
- * 不给时独占。
66
+ * 随结果交给模型的上下文:记下结果之后排进插话,下一步交给模型。
86
67
  */
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;
68
+ additionalContexts?: Array<UserMessage>;
96
69
  /**
97
- * 会话当前的工作目录。
70
+ * 这次调用成功后结束这一轮;失败的结果不看它。
98
71
  */
99
- cwd: string;
100
- };
101
- export type ToolOutcome = {
102
- content: Array<ToolContent>;
103
- isError: boolean;
72
+ concludesTurn?: boolean;
104
73
  };
105
74
  export type ImageRef = {
106
75
  attachmentId: string;
@@ -126,67 +95,291 @@ export type ToolContent = {
126
95
  "type": "image";
127
96
  attachment: ImageRef;
128
97
  };
129
- export type ToolFilter = {
130
- allow?: Array<string>;
131
- deny?: Array<string>;
132
- };
133
- export type PromptSection = {
98
+ export type FileRef = {
99
+ attachmentId: string;
134
100
  name: string;
135
- order: number;
101
+ bytes: number;
102
+ };
103
+ export type UserContent = {
104
+ "type": "text";
136
105
  text: string;
106
+ } | {
107
+ "type": "image";
108
+ attachment: ImageRef;
109
+ } | {
110
+ "type": "file";
111
+ attachment: FileRef;
112
+ };
113
+ export type UserMessage = {
114
+ content: Array<UserContent>;
115
+ /**
116
+ * 消息来源,`kind` 必须是字符串(`user`、`schedule` 等,插件可以用自己的)。
117
+ */
118
+ source: {
119
+ kind: string;
120
+ } & Record<string, unknown>;
121
+ role: UserRole;
122
+ id: string;
137
123
  };
124
+ export type UserRole = "user";
138
125
  export type JsonValue = number | string | boolean | Array<JsonValue> | {
139
126
  [key in string]: JsonValue;
140
127
  } | null;
141
- export type RemoteParam = {
128
+ export type ToolFailure = {
129
+ message: string;
130
+ info?: ToolErrorInfo;
131
+ };
132
+ export type ToolSettled = {
133
+ exec: ToolExecution;
134
+ result: ToolResultData;
135
+ };
136
+ export type PostExecuteDecision = {
137
+ "kind": "accept";
138
+ content?: Array<ToolContent>;
139
+ additionalContexts?: Array<UserMessage>;
140
+ } | {
141
+ "kind": "block";
142
+ feedback: Array<ToolContent>;
143
+ additionalContexts?: Array<UserMessage>;
144
+ };
145
+ export type AgentCreated = {
146
+ agent: AgentRef;
147
+ source: AgentSource;
148
+ };
149
+ export type AgentSource = "startup" | "resume";
150
+ export type AssistantStream = {
151
+ agent: AgentRef;
152
+ frame: StreamFrame;
153
+ };
154
+ export type StreamFrame = {
155
+ "type": "start";
156
+ attemptId: string;
142
157
  /**
143
- * 参数名,只用于报错。
158
+ * 模型调用的序号:这个宿主进程里单调递增,同一个 agent 后面的调用更大,不连续。
144
159
  */
145
- name: string;
160
+ revision: number;
161
+ turn: number;
162
+ step: number;
163
+ } | {
164
+ "type": "chunk";
165
+ attemptId: string;
166
+ revision: number;
146
167
  /**
147
- * 可选参数:界面不给或给 null 都算没给。
168
+ * 这次调用里的第几个 chunk,从 0 数。
148
169
  */
149
- optional: boolean;
170
+ index: number;
150
171
  /**
151
- * 参数类型的 JSON Schema(type、oneOf、properties、required、items、enum、const 的子集,同工具参数的校验)。
172
+ * Unix 毫秒。
152
173
  */
153
- schema: JsonValue;
174
+ time: number;
175
+ turn: number;
176
+ step: number;
177
+ /**
178
+ * v4 的 `StreamChunk`(`text-delta`、`reasoning-delta`、`block-start` 等)。
179
+ */
180
+ chunk: Record<string, unknown>;
181
+ } | {
182
+ "type": "end";
183
+ attemptId: string;
184
+ revision: number;
185
+ /**
186
+ * 这次调用发出的 chunk 帧数。
187
+ */
188
+ index: number;
189
+ outcome: StreamOutcome;
154
190
  };
155
- export type RemoteMethod = {
191
+ export type StreamOutcome = {
192
+ "kind": "committed";
156
193
  /**
157
- * 界面调用的方法名。
194
+ * `assistant/message` 或 `assistant/attempt`。
158
195
  */
159
- name: string;
196
+ eventType: string;
197
+ seq: number;
198
+ } | {
199
+ "kind": "abandoned";
200
+ };
201
+ export type SessionEventNotice = {
202
+ sessionId: string;
203
+ event: Record<string, unknown>;
204
+ };
205
+ export type AgentDisposed = {
206
+ agent: AgentRef;
207
+ };
208
+ export type AgentStatusChange = {
209
+ agent: AgentRef;
210
+ status: AgentStatus;
211
+ };
212
+ export type AgentStatus = "idle" | "running";
213
+ export type AgentFailure = {
214
+ agent: AgentRef;
215
+ turn: number;
216
+ step: number;
217
+ error: AgentErrorInfo;
218
+ };
219
+ export type AgentErrorInfo = {
220
+ message: string;
221
+ code: string;
222
+ };
223
+ export type AgentInboxChange = {
224
+ agent: AgentRef;
225
+ message: UserMessage;
226
+ };
227
+ export type AgentInboxClaimed = {
228
+ agent: AgentRef;
229
+ message: UserMessage;
230
+ turn: number;
231
+ };
232
+ export type PreStep = {
233
+ agent: AgentRef;
234
+ turn: number;
235
+ step: number;
160
236
  /**
161
- * 流式方法(`@Remote({ mode: 'stream' })`):逐条给出结果。
237
+ * 这一步认领的输入(v4 的 Message)。
162
238
  */
163
- stream: boolean;
239
+ messages: Array<UserMessage>;
240
+ };
241
+ export type PreStepDecision = {
242
+ "kind": "enter";
243
+ messages: Array<UserMessage>;
244
+ } | {
245
+ "kind": "reject";
246
+ };
247
+ export type AgentRequest = {
248
+ agent: AgentRef;
249
+ turn: number;
250
+ step: number;
251
+ };
252
+ export type AgentRequestDecision = LlmCallConfig;
253
+ export type LlmCallConfig = {
254
+ provider: string;
255
+ model: string;
256
+ reasoningEffort?: string;
257
+ maxTokens?: number;
258
+ temperature?: number;
259
+ stop?: Array<string>;
260
+ };
261
+ export type AgentRequestError = {
262
+ agent: AgentRef;
263
+ turn: number;
264
+ step: number;
265
+ provider: string;
266
+ failure: RequestFailure;
267
+ };
268
+ export type RequestFailure = {
269
+ message: string;
270
+ code: string;
164
271
  /**
165
- * 按位置的参数(不含宿主代传的最后一个 `signal`),由 `ftai-plugin-remote` 从参数类型生成。宿主调用前按它核对界面给的
166
- * 参数(同 0.12 网关的 `gateway/input-invalid`);没有时不核对(插件的 remote 产物不是这样生成的)。
272
+ * 服务端的 HTTP 状态码。
167
273
  */
168
- params?: Array<RemoteParam>;
274
+ status?: number;
169
275
  };
170
- export type RemoteInvocation = {
171
- method: string;
276
+ export type RequestErrorAction = {
277
+ "kind": "retry";
278
+ };
279
+ export type SystemPromptAssemble = {
172
280
  /**
173
- * 按位置的参数(JSON)。
281
+ * 这次组装所属的 agent;显式组装不带 agent 时没有。
174
282
  */
175
- args: Array<JsonValue>;
283
+ agent?: AgentRef;
284
+ assembly: PromptAssembly;
176
285
  };
177
- export type FsResolved = {
286
+ export type PromptAssembly = {
287
+ sections: Array<AssembledSection>;
288
+ contexts: Array<AssembledContext>;
289
+ tools: Array<ToolSchema>;
290
+ variables: {
291
+ [key in string]: string;
292
+ };
293
+ };
294
+ export type AssembledContext = {
295
+ name: string;
296
+ text: string;
297
+ interpolate?: boolean;
298
+ };
299
+ export type AssembledSection = {
300
+ name: string;
301
+ text: string;
302
+ interpolate?: boolean;
303
+ };
304
+ export type ToolSchema = {
305
+ name: string;
306
+ description: string;
307
+ parameters: Record<string, unknown>;
308
+ };
309
+ export type AssembleDecision = PromptAssembly;
310
+ export type LlmStreamRequest = {
311
+ provider: string;
312
+ model: string;
313
+ messages: Array<RequestMessage>;
314
+ system?: string;
315
+ tools?: Array<ToolSchema>;
316
+ temperature?: number;
317
+ maxTokens?: number;
318
+ stop?: Array<string>;
319
+ reasoningEffort?: string;
320
+ sessionId?: string;
321
+ purpose?: LlmPurpose;
322
+ /**
323
+ * Agent 回路组装的请求(0.12 的 `isAgentLoopRequest`):内容由会话日志决定。
324
+ */
325
+ agentLoop?: boolean;
326
+ };
327
+ export type AssistantContent = {
328
+ "type": "text";
329
+ text: string;
330
+ } | {
331
+ "type": "reasoning";
332
+ text: string;
333
+ } | {
334
+ "type": "tool-call";
335
+ id: string;
336
+ name: string;
337
+ arguments: string;
338
+ };
339
+ export type SystemContent = {
340
+ "type": "text";
341
+ text: string;
342
+ };
343
+ export type RequestMessage = {
344
+ "role": "system";
345
+ content: Array<SystemContent>;
346
+ } | {
347
+ "role": "user";
348
+ content: Array<UserContent>;
349
+ } | {
350
+ "role": "assistant";
351
+ content: Array<AssistantContent>;
352
+ /**
353
+ * 回复的来源(`kind`、`provider`、`model`)与重放状态(`replayState`,`finish` 块给的),原样带回才能原样写回推理与签名。
354
+ */
355
+ source?: {
356
+ kind: 'model';
357
+ provider: string;
358
+ model: string;
359
+ replayState?: unknown;
360
+ };
361
+ } | {
362
+ "role": "tool";
363
+ toolCallId: string;
364
+ content: Array<ToolContent>;
365
+ isError?: boolean;
366
+ };
367
+ export type LlmPurpose = "compaction" | "session-title";
368
+ export type TurnStopping = {
369
+ agent: AgentRef;
370
+ turn: number;
371
+ };
372
+ export type FsIntent = {
178
373
  target: FsTarget;
179
- processPath: string;
374
+ execution?: ToolExecution;
180
375
  };
181
376
  export type FsTarget = {
182
377
  targetKey: string;
183
378
  displayPath: string;
184
379
  };
185
- export type FsFileType = "file" | "directory" | "other";
186
- export type FsInfo = {
187
- version: string;
188
- type: FsFileType;
189
- size: number;
380
+ export type FsFailure = {
381
+ code: string;
382
+ message: string;
190
383
  };
191
384
  export type FsWriteIntent = {
192
385
  "kind": "createIfAbsent";
@@ -194,334 +387,3356 @@ export type FsWriteIntent = {
194
387
  "kind": "replaceIfVersion";
195
388
  version: string;
196
389
  };
197
- export type FsWritten = {
198
- operation: FsWriteOperation;
390
+ export type FsObserved = {
391
+ target: FsTarget;
392
+ observation: FsObservation;
393
+ execution?: ToolExecution;
394
+ };
395
+ export type FsObservation = {
396
+ "kind": "present";
199
397
  version: string;
398
+ } | {
399
+ "kind": "absent";
200
400
  };
201
- export type FsWriteOperation = "create" | "update";
202
- export type ImageUpload = {
203
- data: string;
204
- mediaType: string;
205
- name?: string;
401
+ export type SessionActivityRequest = {
402
+ sessionId: string;
206
403
  };
207
- export type ModelRoute = {
208
- provider: string;
209
- displayName: string;
210
- models: Array<ModelSpec>;
404
+ export type SessionActivityItem = {
405
+ id: string;
406
+ label?: string;
211
407
  };
212
- export type CompletionsCompat = {
408
+ export type SessionActivity = {
409
+ kind: string;
410
+ items?: Array<SessionActivityItem>;
411
+ };
412
+ export type GoalChanged = {
413
+ sessionId: string;
414
+ change: GoalChange;
415
+ };
416
+ export type GoalChange = {
417
+ operation: 'create' | 'edit' | 'pause' | 'resume' | 'complete' | 'block' | 'clear';
213
418
  /**
214
- * 推理模型的系统提示用 developer 角色;不支持时用 system。
419
+ * 变更后的修订;清除时是比清除的那个修订大一的标记。
215
420
  */
216
- supportsDeveloperRole: boolean;
421
+ ref: GoalRef;
217
422
  /**
218
- * 请求体带 `store: false`。
423
+ * 变更后的 Goal;清除时没有。
219
424
  */
220
- supportsStore: boolean;
221
- maxTokensField: MaxTokensField;
425
+ goal?: GoalView;
426
+ };
427
+ export type GoalRef = {
428
+ id: string;
429
+ revision: number;
430
+ };
431
+ export type GoalView = {
432
+ roundsStarted: number;
433
+ createdAt: number;
434
+ updatedAt: number;
435
+ activation: GoalActivation;
436
+ id: string;
437
+ revision: number;
438
+ objective: string;
439
+ phase: GoalPhase;
222
440
  /**
223
- * 推理强度放在请求体顶层的 `reasoning_effort`。
441
+ * 只在受阻时有。
224
442
  */
225
- supportsReasoningEffort: boolean;
443
+ blockedReason?: GoalBlockReason;
444
+ maxGoalRounds: number;
226
445
  };
227
- export type MaxTokensField = "max_tokens" | "max_completion_tokens";
228
- export type ModelApi = "openai-completions" | "openai-responses";
229
- export type ModelSpec = {
446
+ export type GoalActivation = "armed" | "disarmed";
447
+ export type GoalBlockReason = {
448
+ code: string;
449
+ message: string;
450
+ };
451
+ export type GoalPhase = "active" | "paused" | "blocked" | "complete";
452
+ export type GoalActivationChanged = {
453
+ sessionId: string;
230
454
  /**
231
- * 服务端的模型 id,原样放进请求体,也是会话记录的 model。
455
+ * 没有当前的 Goal 时没有。
232
456
  */
457
+ goal?: GoalActivationState;
458
+ };
459
+ export type GoalActivationState = {
233
460
  id: string;
461
+ revision: number;
462
+ activation: GoalActivation;
463
+ };
464
+ export type CompactionSummaryError = {
465
+ sessionId: string;
234
466
  /**
235
- * 模型选择器里的名字。
467
+ * 被压缩的消息事件,按请求里的顺序。
236
468
  */
237
- name: string;
238
- api: ModelApi;
239
- contextWindow: number;
469
+ sourceEventSeqs: Array<number>;
470
+ error: CompactionSummaryFailure;
471
+ };
472
+ export type CompactionSummaryFailure = {
473
+ message: string;
240
474
  /**
241
- * 请求的输出上限(发出前按上下文估算再往下裁)。
475
+ * 模型请求失败时的错误码(`LlmError` 的 `code`);回复不能用(被截断、没有正文)时没有。
242
476
  */
243
- maxOutputTokens: number;
477
+ code?: string;
478
+ };
479
+ export type SubagentRunInfo = {
244
480
  /**
245
- * 可选的推理强度(界面的档位 id,原样发给服务端);空表示不推理,请求不带推理参数。
481
+ * 与成对的 `subagent/end` 相同。
246
482
  */
247
- reasoningEfforts: Array<string>;
248
- defaultReasoningEffort?: string;
483
+ runId: string;
484
+ provider: string;
249
485
  /**
250
- * 接受图片输入。
486
+ * 子会话的 id。
251
487
  */
252
- images: boolean;
488
+ id: string;
253
489
  /**
254
- * 不进模型目录,只供插件按 id 请求(如文档识别用的模型)。
490
+ * 总是 true:宿主的提供者都在本进程里。
255
491
  */
256
- hidden: boolean;
492
+ local: boolean;
493
+ };
494
+ export type SubagentRunEndInfo = {
495
+ runId: string;
496
+ provider: string;
497
+ id: string;
498
+ local: boolean;
499
+ stopReason: 'completed' | 'aborted' | 'error' | 'max-tokens' | 'refusal';
257
500
  /**
258
- * 压缩为输出预留 `max_output_tokens`:只有显式配置了输出上限的模型才预留(0.12 的模型信息此时才带 defaultMaxTokens),
259
- * 其余按不预留算触发压缩的阈值。
501
+ * 子 agent 最后的回复;没有时不给。
260
502
  */
261
- reserveOutput: boolean;
503
+ lastAssistantMessage?: Array<AssistantContent>;
504
+ };
505
+ export type AskUserQuestionRequestEvent = {
506
+ questions: Array<AskUserQuestionItem>;
262
507
  /**
263
- * 只对 Chat Completions 有效;不给时按协议的默认格式发。
508
+ * 提问所属的会话;不给时没有卡片可以显示,只有插件能回答。
264
509
  */
265
- compat?: CompletionsCompat;
510
+ sessionId?: string;
511
+ wait?: AskUserQuestionWait;
266
512
  };
267
- export type RouteCredentials = {
513
+ export type AskUserQuestionOption = {
514
+ label: string;
515
+ description?: string;
516
+ };
517
+ export type AskUserQuestionIntent = {
518
+ "kind": "plan-review";
519
+ approve: string;
520
+ callId?: string;
521
+ };
522
+ export type AskUserQuestionItem = {
523
+ id: string;
524
+ question: string;
268
525
  /**
269
- * 协议的根地址,请求发往 `{baseUrl}/chat/completions` 或 `{baseUrl}/responses`。
526
+ * 随问题显示的补充说明(Markdown)。
270
527
  */
271
- baseUrl: string;
528
+ detail?: string;
529
+ header?: string;
530
+ options?: Array<AskUserQuestionOption>;
531
+ multiSelect?: boolean;
532
+ intent?: AskUserQuestionIntent;
533
+ };
534
+ export type AskUserQuestionWait = {
535
+ callId: string;
536
+ };
537
+ export type AskUserQuestionDecision = {
538
+ "kind": "answered";
539
+ answers: Array<AskUserQuestionAnswerItem>;
540
+ } | {
541
+ "kind": "dismissed";
542
+ } | {
543
+ "kind": "unavailable";
544
+ };
545
+ export type AskUserQuestionAnswerItem = {
546
+ id: string;
547
+ selected: Array<string>;
548
+ custom?: string;
549
+ };
550
+ export type ApprovalRequestEvent = {
551
+ sessionId: string;
552
+ toolName: string;
553
+ callId?: string;
554
+ reason?: string;
272
555
  /**
273
- * 作为 `Authorization: Bearer` 发出;不给就不发。
556
+ * 给界面的多语言说明(`{ en, zh, … }`),不落盘。
274
557
  */
275
- apiKey?: string;
558
+ displayReason?: {
559
+ readonly en: string;
560
+ readonly [locale: string]: string;
561
+ };
562
+ };
563
+ export type ApprovalAnswer = "allowed-once" | "rejected" | "cancelled" | "unavailable";
564
+ export type ToolRegistration = {
276
565
  /**
277
- * 其余请求头。
566
+ * 只对这个 agent 生效(0.12 的 `agent.ctx.tools.register`);不给时为全局。
278
567
  */
279
- headers: {
280
- [key in string]: string;
281
- };
568
+ agent?: string;
569
+ schema: ToolSchema;
570
+ /**
571
+ * 默认要用户审批(`tools/pre-execute` 的默认结论为 ask)。
572
+ */
573
+ needsApproval: boolean;
574
+ /**
575
+ * 可以为这次调用申请更宽的沙箱模式,同核心的文件工具:宿主给参数表加上 `sandbox_permissions` 与 `justification`,
576
+ * 执行之前经审批定下这一次的模式,`fs.writeBytes` 带着这次调用写入时按它围住。参数表里不能自带这两个参数。
577
+ */
578
+ sandboxEscalation?: boolean;
579
+ /**
580
+ * 并发安全(0.12 的 `isConcurrencySafe`):同一条回复里相邻的并发安全调用一起跑。只读、互相不影响的工具才给;
581
+ * 不给时独占。
582
+ */
583
+ concurrencySafe?: boolean;
584
+ /**
585
+ * 插件的 `isConcurrencySafe` 是函数:每次按参数问(`classify`),超时、崩溃或不是 true 都按独占。
586
+ */
587
+ classify?: boolean;
588
+ /**
589
+ * 单个工具的超时(毫秒,0.12 的 `timeoutMs`):到时丢掉执行,记作 `TOOL_TIMEOUT`,工具体的 `exec.signal` 随之触发。
590
+ */
591
+ timeoutMs?: number;
592
+ /**
593
+ * 工具定义上有 `finalizeContent`:结果定下之前问一次(`finalize`)。
594
+ */
595
+ finalizeContent?: boolean;
596
+ /**
597
+ * 工具定义上有 `presentCall`(`present-call`)。
598
+ */
599
+ presentCall?: boolean;
600
+ /**
601
+ * 工具定义上有 `presentResult`(`present-result`)。
602
+ */
603
+ presentResult?: boolean;
282
604
  };
283
- export type LlmModelInfo = {
284
- provider: string;
285
- id: string;
605
+ export type ToolRequest = {
606
+ "op": "execute";
607
+ exec: ToolExecution;
608
+ cwd: string;
609
+ } | {
610
+ "op": "finalize";
611
+ exec: ToolExecution;
612
+ result: ToolResultData;
613
+ } | {
614
+ "op": "classify";
615
+ arguments: string;
616
+ } | {
617
+ "op": "present-call";
618
+ arguments: string;
619
+ } | {
620
+ "op": "present-result";
621
+ arguments: string;
622
+ result: ToolResultData;
623
+ };
624
+ export type ToolReply = ToolResultData | JsonValue;
625
+ export type ToolFilter = {
626
+ allow?: Array<string>;
627
+ deny?: Array<string>;
628
+ };
629
+ export type ToolModeQuery = {
286
630
  name: string;
287
- inputModalities: Array<InputModality>;
288
- context: LlmModelContext;
289
631
  /**
290
- * 只在路由给模型显式配了输出上限时有(同 pi-ai 的 configuredMaxTokens)。
632
+ * 参数原文(JSON 字符串)。
291
633
  */
292
- defaultMaxTokens?: number;
634
+ arguments: string;
635
+ /**
636
+ * 按这个 agent 看到的工具判定;不给时按全局的。
637
+ */
638
+ agent?: string;
293
639
  };
294
- export type InputModality = "text" | "image";
295
- export type LlmModelContext = {
296
- contextWindow: number;
640
+ export type ToolExecutionMode = {
641
+ "kind": "parallel";
642
+ } | {
643
+ "kind": "exclusive";
297
644
  };
298
- export type GenerateRequest = {
299
- provider: string;
300
- model: string;
301
- system?: string;
302
- messages: Array<RequestMessage>;
645
+ export type ToolExecuteInput = {
646
+ callId: string;
303
647
  /**
304
- * 输出上限;不给时用模型的,按上下文估算往下裁。
648
+ * 根调用的 id:嵌套调用传上层的值,根调用不传。
305
649
  */
306
- maxTokens?: number;
650
+ rootCallId?: string;
651
+ name: string;
307
652
  /**
308
- * 推理档位;不给时用模型的默认档位,不推理的模型不带。
653
+ * 参数原文(JSON 字符串)。
309
654
  */
310
- reasoningEffort?: string;
655
+ arguments: string;
311
656
  /**
312
- * 会话 id:协议支持时作提示缓存的键。
657
+ * 代表哪个 agent 执行:工具的可见范围、权限与沙箱都按它的会话算。
313
658
  */
314
- sessionId?: string;
659
+ agent: string;
315
660
  };
316
- export type AssistantContent = {
317
- "type": "text";
318
- text: string;
319
- } | {
320
- "type": "reasoning";
321
- text: string;
661
+ export type ToolExecuted = {
662
+ token: string;
663
+ result: ToolResultData;
322
664
  };
323
- export type FileRef = {
324
- attachmentId: string;
665
+ export type PromptSectionSpec = {
325
666
  name: string;
326
- bytes: number;
667
+ order: number;
668
+ text?: string;
669
+ /**
670
+ * 为 true 时替换文本里的 `{{变量}}`;不写时文本原样保留。
671
+ */
672
+ interpolate?: boolean;
673
+ /**
674
+ * 这一段就是完整的系统提示:瀑布之后恢复为唯一的一段;同时生效的多于一段时这一步失败。
675
+ */
676
+ complete?: boolean;
327
677
  };
328
- export type UserContent = {
329
- "type": "text";
330
- text: string;
331
- } | {
332
- "type": "image";
333
- attachment: ImageRef;
334
- } | {
335
- "type": "file";
336
- attachment: FileRef;
678
+ export type PromptScope = {
679
+ agent?: AgentRef;
337
680
  };
338
- export type RequestMessage = {
339
- "role": "user";
340
- content: Array<UserContent>;
341
- } | {
342
- "role": "assistant";
343
- content: Array<AssistantContent>;
681
+ export type PromptContextSpec = {
682
+ name: string;
683
+ order: number;
684
+ text?: string;
685
+ /**
686
+ * 为 true 时替换文本里的 `{{变量}}`;不写时文本原样保留。
687
+ */
688
+ interpolate?: boolean;
689
+ /**
690
+ * 明确写 false 才是可选的段,才能被收起或被瀑布去掉;不写时不可收起。
691
+ */
692
+ required?: boolean;
344
693
  };
345
- /** 宿主的扩展点:名字 → 交互方式、载荷与结论。 */
346
- export interface HostPoints {
347
- /** 工具执行前:放行、拒绝、取消,或要求审批。默认放行;跨进程超时或崩溃按拒绝。 */
348
- 'tools/pre-execute': {
349
- kind: 'waterfall';
350
- input: ToolExecution;
351
- output: PreToolDecision;
352
- };
694
+ export type ToolProviderResult = {
695
+ schemas: Array<ToolSchema>;
353
696
  /**
354
- * agent 建好:在这里按会话注册工具、提示词段与收起工具,从第一步起生效。新会话(`startup`)在交给调用方之前发:建会话、
355
- * 发送新会话的第一条消息时在输入排进队列之前,分叉(含侧聊与编辑重发)时在返回新会话之前;监听者失败时会话不建,
356
- * 错误原样交回调用方,输入退回。续上已有的会话(`resume`)与新建的子 agent 在第一步之前发,监听者失败只记日志。
697
+ * 同 0.12 的写法收下;只用于校验 `toolOrder`,这里没有这项配置,不起作用。
357
698
  */
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
- };
699
+ knownNames?: Array<string>;
394
700
  };
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;
701
+ export type RemoteParam = {
702
+ /**
703
+ * 参数名,只用于报错。
704
+ */
705
+ name: string;
706
+ /**
707
+ * 可选参数:界面不给或给 null 都算没给。
708
+ */
709
+ optional: boolean;
710
+ /**
711
+ * 参数类型的 JSON Schema(type、oneOf、properties、required、items、enum、const 的子集,同工具参数的校验)。
712
+ */
713
+ schema: JsonValue;
714
+ };
715
+ export type RemoteMethod = {
716
+ /**
717
+ * 界面调用的方法名。
718
+ */
719
+ name: string;
720
+ /**
721
+ * 流式方法(`@Remote({ mode: 'stream' })`):逐条给出结果。
722
+ */
723
+ stream: boolean;
724
+ /**
725
+ * 按位置的参数(不含宿主代传的最后一个 `signal`),由 `ftai-plugin-remote` 从参数类型生成。宿主调用前按它核对界面给的
726
+ * 参数(同 0.12 网关的 `gateway/input-invalid`);没有时不核对(插件的 remote 产物不是这样生成的)。
727
+ */
728
+ params?: Array<RemoteParam>;
729
+ };
730
+ export type RemoteInvocation = {
731
+ method: string;
732
+ /**
733
+ * 按位置的参数(JSON)。
734
+ */
735
+ args: Array<JsonValue>;
736
+ };
737
+ export type PreparedSession = {
738
+ id: string;
739
+ createdAt: number;
740
+ cwd: string;
741
+ };
742
+ export type SessionLifecycle = {
743
+ /**
744
+ * 分叉继承来的事件数,没有继承时为 0。
745
+ */
746
+ inheritedEventCount: number;
747
+ /**
748
+ * 这次进内存时带来的事件数(读进来的是整份日志,分叉的是种子);之后的事件都是这个宿主进程写的。
749
+ */
750
+ firstLiveSeq: number;
751
+ /**
752
+ * 这次进内存之后产生的第一个事件:新分叉的从它自己的继承标记算,读进来的同 `firstLiveSeq`。
753
+ */
754
+ firstLifecycleSeq: number;
755
+ };
756
+ export type MessageProjectionCall = {
757
+ sessionId: string;
758
+ /**
759
+ * 要解释的事件(v4 的行)。
760
+ */
761
+ event: Record<string, unknown>;
762
+ /**
763
+ * 这个事件之前的模型可见节点(事件的 seq),按顺序。
764
+ */
765
+ nodes: Array<number>;
766
+ /**
767
+ * 这个事件之前的日志(v4 的行),日志原文,不含投影的改写。
768
+ */
769
+ events: Array<JsonValue>;
770
+ /**
771
+ * `events` 第一个事件的 seq。
772
+ */
773
+ baseSeq: number;
774
+ /**
775
+ * 之前的投影改写过的消息:节点的 seq 与改写后的消息。
776
+ */
777
+ messages: Array<[number, JsonValue]>;
778
+ };
779
+ export type CreateAgent = {
780
+ /**
781
+ * 不给时宿主生成。已有的会话 id 报 `agent/session-exists`。
782
+ */
783
+ sessionId?: string;
784
+ /**
785
+ * 持有它的 agent;不给时是顶层 agent。
786
+ */
787
+ parentAgent?: string;
788
+ /**
789
+ * 绝对路径;不给时用宿主的默认目录。
790
+ */
791
+ cwd?: string;
792
+ agentOptions?: AgentOptions;
793
+ /**
794
+ * 模型在这个会话(及它的子 agent 的会话)里跑的命令额外加的环境变量,插件放手(`dispose`)或插件进程退出时撤掉。只在
795
+ * 内存里,不记进会话日志,宿主重启后要重新给。宿主自己设的 `FTAI_*` 以宿主的为准;不按名字过滤(宿主自己的环境里名字带
796
+ * KEY、TOKEN 等的变量不交给命令,插件给的照给)。名字不能为空、不能含 `=`,名字与值都不能含 NUL,否则报 `invalid_params`。
797
+ */
798
+ env?: {
799
+ [key in string]: string;
800
+ };
801
+ /**
802
+ * 列不列在用户的会话列表里(桌面端的侧栏、搜索与项目,手机上的列表),不给时列出。只有外部应用(`ftai app`)建的会话能给
803
+ * false,别处给 false 报 `invalid_params`。宿主把它连同应用记进会话,从这个会话分叉出的会话沿用。
804
+ */
805
+ listed?: boolean;
806
+ };
807
+ export type AgentOptions = {
808
+ provider?: string;
809
+ model?: string;
810
+ reasoningEffort?: string;
811
+ maxTokens?: number;
812
+ };
813
+ export type ResumeAgent = {
814
+ /**
815
+ * 不存在的会话 id 报 `agent/session-not-found`。
816
+ */
817
+ resumeSessionId: string;
818
+ parentAgent?: string;
819
+ agentOptions?: AgentOptions;
820
+ /**
821
+ * 同 `CreateAgent` 的 `env`:给了就换掉之前给的,不给时沿用之前给的、还没撤掉的。
822
+ */
823
+ env?: {
824
+ [key in string]: string;
825
+ };
826
+ };
827
+ export type InboxTarget = "next-turn" | "next-step";
828
+ export type AgentCancelCause = {
829
+ "kind": "user";
830
+ } | {
831
+ "kind": "parent";
832
+ } | {
833
+ "kind": "hook";
834
+ reason: string;
835
+ };
836
+ export type CancelOptions = {
837
+ /**
838
+ * 留着待处理的输入;不给时一并丢掉。
839
+ */
840
+ keepInbox?: boolean;
841
+ };
842
+ export type InboxState = {
843
+ nextTurn: Array<UserMessage>;
844
+ nextStep: Array<UserMessage>;
845
+ };
846
+ export type MaintenanceSignal = "started" | "cancelled";
847
+ export type DefaultModelSelection = {
848
+ provider: string;
849
+ model: string;
850
+ reasoningEffort?: string;
851
+ };
852
+ export type FsResolved = {
853
+ target: FsTarget;
854
+ processPath: string;
855
+ };
856
+ export type FsFileType = "file" | "directory" | "other";
857
+ export type FsInfo = {
858
+ version: string;
859
+ type: FsFileType;
860
+ size: number;
861
+ };
862
+ export type FsWritten = {
863
+ operation: FsWriteOperation;
864
+ version: string;
865
+ };
866
+ export type FsWriteOperation = "create" | "update";
867
+ export type FsPathInfo = {
868
+ version: string;
869
+ type: FsPathType;
870
+ size: number;
871
+ };
872
+ export type FsPathType = "file" | "directory" | "symlink" | "other";
873
+ export type FsTextChunk = {
874
+ text: string;
875
+ nextOffset?: number;
876
+ };
877
+ export type FsDirEntry = {
878
+ name: string;
879
+ type: FsFileType;
880
+ target: FsTarget;
881
+ version?: string;
882
+ size?: number;
883
+ };
884
+ export type FsEditRequest = {
885
+ oldString: string;
886
+ newString: string;
887
+ replaceAll: boolean;
888
+ };
889
+ export type FsEditOutcome = {
890
+ version: string;
891
+ before: string;
892
+ after: string;
893
+ };
894
+ export type FsWatchFrame = "ready" | "changed";
895
+ export type ImageAttachmentLimits = {
896
+ maxImageBytes: number;
897
+ maxImagesPerMessage: number;
898
+ maxMessageImageBytes: number;
899
+ maxImagePixels: number;
900
+ maxImageDimension: number;
901
+ mediaTypes: [ImageMediaType, ImageMediaType, ImageMediaType, ImageMediaType];
902
+ };
903
+ export type ImageUpload = {
904
+ data: string;
905
+ mediaType: string;
906
+ name?: string;
907
+ };
908
+ export type ImageRequestTarget = {
909
+ width: number;
910
+ height: number;
911
+ maxBytes: number;
912
+ };
913
+ export type RequestImageVersion = {
914
+ /**
915
+ * 缓存的键,覆盖这次变换的全部输入。
916
+ */
917
+ variantId: string;
918
+ attachment: ImageRef;
919
+ data: string;
920
+ mediaType: ImageMediaType;
921
+ bytes: number;
922
+ width: number;
923
+ height: number;
924
+ hasAlpha: boolean;
925
+ };
926
+ export type FileUpload = {
927
+ data: string;
928
+ name?: string;
929
+ };
930
+ export type FileUploadFrame = {
931
+ "kind": "started";
932
+ upload: string;
933
+ } | {
934
+ "kind": "saved";
935
+ file: FileRef;
936
+ };
937
+ export type RouteDeclaration = {
938
+ retryPolicy?: RetryPolicyConfig;
939
+ /**
940
+ * 按模型 id。
941
+ */
942
+ modelOptions?: {
943
+ [key in string]: RouteModelOptions;
944
+ };
945
+ provider: string;
946
+ displayName: string;
947
+ models: Array<ModelSpec>;
948
+ };
949
+ export type CompletionsCompat = {
950
+ /**
951
+ * 推理模型的系统提示用 developer 角色;不支持时用 system。
952
+ */
953
+ supportsDeveloperRole: boolean;
954
+ /**
955
+ * 请求体带 `store: false`。
956
+ */
957
+ supportsStore: boolean;
958
+ maxTokensField: MaxTokensField;
959
+ /**
960
+ * 推理强度放在请求体顶层的 `reasoning_effort`。
961
+ */
962
+ supportsReasoningEffort: boolean;
963
+ };
964
+ export type MaxTokensField = "max_tokens" | "max_completion_tokens";
965
+ export type ModelApi = "openai-completions" | "openai-responses" | "anthropic-messages";
966
+ export type ModelSpec = {
967
+ /**
968
+ * 服务端的模型 id,原样放进请求体,也是会话记录的 model。
969
+ */
970
+ id: string;
971
+ /**
972
+ * 模型选择器里的名字。
973
+ */
974
+ name: string;
975
+ api: ModelApi;
976
+ contextWindow: number;
977
+ /**
978
+ * 请求的输出上限(发出前按上下文估算再往下裁)。
979
+ */
980
+ maxOutputTokens: number;
981
+ /**
982
+ * 可选的推理强度(界面的档位 id,原样发给服务端);空表示不推理,请求不带推理参数。
983
+ */
984
+ reasoningEfforts: Array<string>;
985
+ defaultReasoningEffort?: string;
986
+ /**
987
+ * 接受图片输入。
988
+ */
989
+ images: boolean;
990
+ /**
991
+ * 不进模型目录,只供插件按 id 请求(如文档识别用的模型)。
992
+ */
993
+ hidden: boolean;
994
+ /**
995
+ * 压缩为输出预留 `max_output_tokens`:只有显式配置了输出上限的模型才预留(0.12 的模型信息此时才带 defaultMaxTokens),
996
+ * 其余按不预留算触发压缩的阈值。
997
+ */
998
+ reserveOutput: boolean;
999
+ /**
1000
+ * 只对 Chat Completions 有效;不给时按协议的默认格式发。
1001
+ */
1002
+ compat?: CompletionsCompat;
1003
+ };
1004
+ export type RetryPolicyConfig = {
1005
+ mode: RetryMode;
1006
+ maxRetries?: number;
1007
+ retryableCodes?: Array<string>;
1008
+ backoff?: BackoffConfig;
1009
+ };
1010
+ export type BackoffConfig = {
1011
+ initialDelayMs?: number;
1012
+ maxDelayMs?: number;
1013
+ jitterRatio?: number;
1014
+ };
1015
+ export type RetryMode = "normal";
1016
+ export type RouteModelOptions = {
1017
+ /**
1018
+ * 一句话说明,原样给 `listModels`、`resolveModelInfo`。
1019
+ */
1020
+ description?: string;
1021
+ imagePricing?: LlmImageRequestPricing;
1022
+ };
1023
+ export type LlmImageRequestPricing = {
1024
+ baseTokens: number;
1025
+ pixelsPerToken?: number;
1026
+ maxTokens?: number;
1027
+ };
1028
+ export type RouteCredentials = {
1029
+ /**
1030
+ * 协议的根地址,请求发往 `{baseUrl}/chat/completions`、`{baseUrl}/responses` 或 `{baseUrl}/v1/messages`。
1031
+ */
1032
+ baseUrl: string;
1033
+ /**
1034
+ * OpenAI 的两种协议作为 `Authorization: Bearer` 发出,Anthropic Messages 作为 `x-api-key`;不给就不发。
1035
+ */
1036
+ apiKey?: string;
1037
+ /**
1038
+ * 其余请求头。
1039
+ */
1040
+ headers: {
1041
+ [key in string]: string;
1042
+ };
1043
+ };
1044
+ export type LlmProviderInfo = {
1045
+ id: string;
1046
+ name: string;
1047
+ };
1048
+ export type InputModality = "text" | "image";
1049
+ export type LlmModelContext = {
1050
+ contextWindow: number;
1051
+ };
1052
+ export type LlmModelInfo = {
1053
+ provider: string;
1054
+ id: string;
1055
+ name: string;
1056
+ inputModalities: Array<InputModality>;
1057
+ context: LlmModelContext;
1058
+ /**
1059
+ * 只在路由给模型显式配了输出上限时有(同 pi-ai 的 configuredMaxTokens)。
1060
+ */
1061
+ defaultMaxTokens?: number;
1062
+ /**
1063
+ * 路由声明的一句话说明。
1064
+ */
1065
+ description?: string;
1066
+ /**
1067
+ * 模型可选的推理档位;不推理的模型没有。
1068
+ */
1069
+ reasoning?: LlmModelReasoningInfo;
1070
+ };
1071
+ export type LlmModelReasoningInfo = {
1072
+ efforts: Array<LlmReasoningEffortInfo>;
1073
+ defaultEffort?: string;
1074
+ };
1075
+ export type LlmReasoningEffortInfo = {
1076
+ id: string;
1077
+ name: string;
1078
+ };
1079
+ export type LlmConfigurableProvider = {
1080
+ provider: string;
1081
+ displayName: string;
1082
+ /**
1083
+ * 配置这个 provider 的设置命名空间。
1084
+ */
1085
+ settingsNs: string;
1086
+ /**
1087
+ * 从命名空间的根到这个 provider 配置的路径;整段都是时为空。
1088
+ */
1089
+ settingsPath: Array<string>;
1090
+ /**
1091
+ * 这条路由是不是只因配置才存在(网关、自建服务);注册方不区分时不给。
1092
+ */
1093
+ declared?: boolean;
1094
+ /**
1095
+ * 配置的问题,给界面提示修复。
1096
+ */
1097
+ error?: string;
1098
+ };
1099
+ export type LlmModelDiscoveryRequest = {
1100
+ provider?: string;
1101
+ baseURL?: string;
1102
+ api?: string;
1103
+ apiKey?: string;
1104
+ };
1105
+ export type LlmDiscoveredModel = {
1106
+ id: string;
1107
+ name?: string;
1108
+ contextWindow?: number;
1109
+ maxTokens?: number;
1110
+ inputModalities?: Array<InputModality>;
1111
+ };
1112
+ export type ResolvedRetryPolicy = {
1113
+ mode: RetryMode;
1114
+ maxRetries: number;
1115
+ retryableCodes: Array<string>;
1116
+ initialDelayMs: number;
1117
+ maxDelayMs: number;
1118
+ jitterRatio: number;
1119
+ };
1120
+ export type BoundCall = {
1121
+ id: string;
1122
+ model: LlmModelInfo;
1123
+ };
1124
+ export type PreparedCallInfo = {
1125
+ config: LlmCallConfig;
1126
+ retryPolicy: ResolvedRetryPolicy;
1127
+ adapterDefaults: LlmCallAdapterDefaults;
1128
+ context: LlmModelContext;
1129
+ inputModalities: Array<InputModality>;
1130
+ };
1131
+ export type LlmCallAdapterDefaults = {
1132
+ reasoningEffort?: boolean;
1133
+ maxTokens?: boolean;
1134
+ };
1135
+ export type GenerateRequest = {
1136
+ provider: string;
1137
+ model: string;
1138
+ system?: string;
1139
+ messages: Array<RequestMessage>;
1140
+ /**
1141
+ * 输出上限;不给时用模型的,按上下文估算往下裁。
1142
+ */
1143
+ maxTokens?: number;
1144
+ /**
1145
+ * 推理档位;不给时用模型的默认档位,不推理的模型不带。
1146
+ */
1147
+ reasoningEffort?: string;
1148
+ /**
1149
+ * 会话 id:协议支持时作提示缓存的键。
1150
+ */
1151
+ sessionId?: string;
1152
+ /**
1153
+ * 给模型的工具声明。
1154
+ */
1155
+ tools?: Array<ToolSchema>;
1156
+ /**
1157
+ * 原样发给服务端,上游不接受时由上游报错。
1158
+ */
1159
+ temperature?: number;
1160
+ /**
1161
+ * 停止词,不包括在输出里。Chat Completions 发给服务端;Responses 没有这个字段,宿主在流里截断并断开上游。
1162
+ */
1163
+ stop?: Array<string>;
1164
+ /**
1165
+ * 现有路由不据此改请求;交给 `llm/stream` 的监听者与自带流式实现的适配器。
1166
+ */
1167
+ purpose?: LlmPurpose;
1168
+ };
1169
+ export type ApprovalConfig = {
1170
+ policy: ApprovalPolicy;
1171
+ };
1172
+ export type ApprovalPolicy = "ask" | "never";
1173
+ export type ApprovalOutcome = "allowed-once" | "rejected" | "cancelled" | "unavailable";
1174
+ export type Workspace = {
1175
+ id: string;
1176
+ path: string;
1177
+ title: string;
1178
+ sessionIds: Array<string>;
1179
+ createdAt: string;
1180
+ updatedAt: string;
1181
+ };
1182
+ export type GoalCreateRequest = {
1183
+ objective: string;
1184
+ /**
1185
+ * 轮数上限,不给时用默认值。不是正的安全整数时报 `GOAL_INVALID_MAX_ROUNDS`。
1186
+ */
1187
+ maxGoalRounds?: number;
1188
+ };
1189
+ export type GoalEditRequest = {
1190
+ objective?: string;
1191
+ maxGoalRounds?: number;
1192
+ };
1193
+ export type CompactionRange = {
1194
+ start: number;
1195
+ end: number;
1196
+ };
1197
+ export type CompactionResult = {
1198
+ compactionId: string;
1199
+ sourceCommandId?: string;
1200
+ startSeq: number;
1201
+ summarySeq: number;
1202
+ endSeq: number;
1203
+ /**
1204
+ * 摘要的文本块。
1205
+ */
1206
+ summary: Array<{
1207
+ type: 'text';
1208
+ text: string;
1209
+ }>;
1210
+ shadowedRange: CompactionRange;
1211
+ /**
1212
+ * 被压缩的节点,按表层的顺序。
1213
+ */
1214
+ shadowedSeqs: Array<number>;
1215
+ shadowedTokenCount: number;
1216
+ };
1217
+ export type CompactionTrigger = "pressure" | "context-overflow";
1218
+ export type SubagentActivationRequest = {
1219
+ /**
1220
+ * 提供者的名字:`spawn` 或 `fork`。
1221
+ */
1222
+ provider: string;
1223
+ /**
1224
+ * 显示用的短标签,记在父会话的子 agent 清单里。
1225
+ */
1226
+ label: string;
1227
+ /**
1228
+ * 指定子会话的 id;不给时生成一个,已有时报 `DUPLICATE_CHILD`。
1229
+ */
1230
+ childId?: string;
1231
+ request: SubagentStartRequest;
1232
+ delivery: SubagentDelivery;
1233
+ };
1234
+ export type SubagentDelivery = "parent" | "caller";
1235
+ export type SubagentStartRequest = {
1236
+ /**
1237
+ * 父会话的 id。
1238
+ */
1239
+ parent: string;
1240
+ /**
1241
+ * 交给子 agent 的内容。
1242
+ */
1243
+ prompt: Array<UserContent>;
1244
+ /**
1245
+ * 子 agent 的起始目录;相对路径按父会话当前的目录解析,不给时沿用父会话当前的目录。
1246
+ */
1247
+ cwd?: string;
1248
+ /**
1249
+ * 盖在父会话路由上的请求配置。
1250
+ */
1251
+ agentOptions?: AgentOptions;
1252
+ /**
1253
+ * 子 agent 委派深度的上限,只能比宿主的上限更严。
1254
+ */
1255
+ maxDepth?: number;
1256
+ /**
1257
+ * 子 agent 看得到的工具,只能在宿主收起的工具之外再收。
1258
+ */
1259
+ toolFilter?: ToolFilter;
1260
+ /**
1261
+ * 替换这个子 agent 的身份段。
1262
+ */
1263
+ persona?: string;
1264
+ };
1265
+ export type SubagentActivationFrame = {
1266
+ "kind": "started";
1267
+ childId: string;
1268
+ messageId: string;
1269
+ runId: string;
1270
+ } | {
1271
+ "kind": "settled";
1272
+ result: SubagentResult;
1273
+ };
1274
+ export type SubagentResult = {
1275
+ /**
1276
+ * 最后一条内容不为空的助手回复。
1277
+ */
1278
+ output: Array<AssistantContent>;
1279
+ stopReason: 'completed' | 'aborted' | 'error' | 'max-tokens' | 'refusal';
1280
+ };
1281
+ export type SubagentInterruptAuthority = {
1282
+ "kind": "user";
1283
+ parentSessionId: string;
1284
+ } | {
1285
+ "kind": "ancestor";
1286
+ agent: string;
1287
+ };
1288
+ export type SubagentCatalogEntry = {
1289
+ id: string;
1290
+ createdAt: number;
1291
+ mode: string;
1292
+ label?: string;
1293
+ };
1294
+ export type SubagentDescendantEntry = {
1295
+ "kind": "child";
1296
+ id: string;
1297
+ parentId: string;
1298
+ depth: number;
1299
+ mode: string;
1300
+ label?: string;
1301
+ activity: 'running' | 'inactive';
1302
+ hasChildren: boolean;
1303
+ } | {
1304
+ "kind": "diagnostic";
1305
+ id: string;
1306
+ parentId: string;
1307
+ depth: number;
1308
+ reason: 'corrupt' | 'unsupported' | 'unavailable';
1309
+ };
1310
+ export type JobDeclaration = {
1311
+ kind: string;
1312
+ label: string;
1313
+ owner?: string;
1314
+ outputLimitBytes?: number;
1315
+ };
1316
+ export type JobControl = {
1317
+ "kind": "started";
1318
+ id: string;
1319
+ } | {
1320
+ "kind": "cancel";
1321
+ reason?: string;
1322
+ };
1323
+ export type JobAppendOptions = {
1324
+ channel?: JobChannel;
1325
+ gapBefore?: boolean;
1326
+ };
1327
+ export type JobChannel = "stdout" | "stderr" | "log";
1328
+ export type JobOutcome = {
1329
+ /**
1330
+ * 只取终态:完成、停下、失败。
1331
+ */
1332
+ status: JobStatus;
1333
+ /**
1334
+ * 状态行里的原因(`exit code: 3`)。
1335
+ */
1336
+ detail?: string;
1337
+ /**
1338
+ * 结果是一个值而不是一条流的任务(如工作流的结果):结束后第一次消费式读取时交出,只交一次。
1339
+ */
1340
+ result?: string;
1341
+ };
1342
+ export type JobStatus = "running" | "stopping" | "completed" | "killed" | "failed";
1343
+ export type JobOutputInfo = {
1344
+ /**
1345
+ * 下一段的起始偏移。
1346
+ */
1347
+ total: number;
1348
+ /**
1349
+ * 最早留着的字节;大于 0 说明开头被丢过。
1350
+ */
1351
+ earliest: number;
1352
+ spillPaths?: Array<string>;
1353
+ };
1354
+ export type JobView = {
1355
+ /**
1356
+ * 注册表给的 id(`<kind>-N`)。
1357
+ */
1358
+ id: string;
1359
+ kind: string;
1360
+ label: string;
1361
+ /**
1362
+ * 归属的会话;没有时任何调用方都看得到。
1363
+ */
1364
+ owner?: string;
1365
+ /**
1366
+ * 交给模型的一次读取与结束通知的字节上限。
1367
+ */
1368
+ outputLimitBytes?: number;
1369
+ status: JobStatus;
1370
+ /**
1371
+ * 生产方当前的进度行(`3/10`);结束时清掉。
1372
+ */
1373
+ progress?: string;
1374
+ detail?: string;
1375
+ startedAt: number;
1376
+ finishedAt?: number;
1377
+ output: JobOutputInfo;
1378
+ };
1379
+ export type JobRead = {
1380
+ chunks: Array<JobChunk>;
1381
+ /**
1382
+ * 上次读到的位置已滑出环,这些段之前有字节丢了。
1383
+ */
1384
+ lossy: boolean;
1385
+ /**
1386
+ * 生产方的结果,结束后第一次读取时交出。
1387
+ */
1388
+ result?: string;
1389
+ job: JobView;
1390
+ };
1391
+ export type JobChunk = {
1392
+ at: number;
1393
+ text: string;
1394
+ channel?: JobChannel;
1395
+ gapBefore?: boolean;
1396
+ };
1397
+ export type JobOutputRead = {
1398
+ chunks: Array<JobChunk>;
1399
+ /**
1400
+ * 下次从哪里接着读(环当前的 `total`)。
1401
+ */
1402
+ next: number;
1403
+ /**
1404
+ * `from` 早于最早留着的字节,这些段之前有字节丢了。
1405
+ */
1406
+ lossy: boolean;
1407
+ };
1408
+ export type KillOutcome = "requested" | "already-finished";
1409
+ export type JobEvent = {
1410
+ "type": "registered";
1411
+ job: JobView;
1412
+ } | {
1413
+ "type": "progress";
1414
+ job: JobView;
1415
+ } | {
1416
+ "type": "stopping";
1417
+ job: JobView;
1418
+ } | {
1419
+ "type": "removed";
1420
+ job: JobView;
1421
+ } | {
1422
+ "type": "settled";
1423
+ job: JobView;
1424
+ cause: JobSettleCause;
1425
+ awaited: boolean;
1426
+ } | {
1427
+ "type": "output";
1428
+ id: string;
1429
+ owner?: string;
1430
+ total: number;
1431
+ };
1432
+ export type JobSettleCause = "producer" | "kill" | "teardown";
1433
+ export type AskUserQuestionAnswer = {
1434
+ answers: Array<AskUserQuestionAnswerItem>;
1435
+ };
1436
+ export type WebFetchRequest = {
1437
+ url: string;
1438
+ };
1439
+ export type WebFetchResult = {
1440
+ /**
1441
+ * 最后一跳的地址。
1442
+ */
1443
+ url: string;
1444
+ statusCode: number;
1445
+ body: WebFetchBody;
1446
+ /**
1447
+ * 正文被上限截断过。
1448
+ */
1449
+ truncated: boolean;
1450
+ };
1451
+ export type WebFetchBody = {
1452
+ "kind": "html";
1453
+ content: string;
1454
+ } | {
1455
+ "kind": "text";
1456
+ content: string;
1457
+ };
1458
+ export type WebSearchRequest = {
1459
+ query: string;
1460
+ /**
1461
+ * 来源条数的上限,多出的截掉并标记 `truncated`。服务端单次最多给 10 条。不给时按服务端的默认。
1462
+ */
1463
+ maxResults?: number;
1464
+ };
1465
+ export type WebSearchResult = {
1466
+ /**
1467
+ * 服务给的总结。
1468
+ */
1469
+ content?: string;
1470
+ sources: Array<WebSearchSource>;
1471
+ truncated: boolean;
1472
+ };
1473
+ export type WebSearchSource = {
1474
+ url: string;
1475
+ title?: string;
1476
+ snippet?: string;
1477
+ publishedAt?: string;
1478
+ };
1479
+ export type SkillInvocationPolicy = {
1480
+ modelInvocable: boolean;
1481
+ userInvocable: boolean;
1482
+ };
1483
+ export type SkillResourceBase = {
1484
+ "kind": "directory";
1485
+ path: string;
1486
+ } | {
1487
+ "kind": "url";
1488
+ url: string;
1489
+ } | {
1490
+ "kind": "opaque";
1491
+ description: string;
1492
+ };
1493
+ export type SkillSummary = {
1494
+ /**
1495
+ * SKILL.md 的绝对路径;插件注册的没给时没有。
1496
+ */
1497
+ path?: string;
1498
+ name: string;
1499
+ description: string;
1500
+ whenToUse?: string;
1501
+ invocation: SkillInvocationPolicy;
1502
+ /**
1503
+ * 来源:目录里的是 `repo`、`user`、`pack`、`system`,插件注册的是它给的值。
1504
+ */
1505
+ source: string;
1506
+ /**
1507
+ * 正文归谁:目录里的是 `filesystem`,插件注册的是插件名。
1508
+ */
1509
+ provider: string;
1510
+ resourceBase?: SkillResourceBase;
1511
+ };
1512
+ export type SkillCatalogSnapshot = {
1513
+ skills: Array<SkillSummary>;
1514
+ /**
1515
+ * 全部 Skill 目录都读到了。有读不了的条目或目录时为 false,读到的照样给出。
1516
+ */
1517
+ complete: boolean;
1518
+ };
1519
+ export type SkillDefinition = {
1520
+ path?: string;
1521
+ name: string;
1522
+ description: string;
1523
+ whenToUse?: string;
1524
+ invocation: SkillInvocationPolicy;
1525
+ source: string;
1526
+ provider: string;
1527
+ resourceBase?: SkillResourceBase;
1528
+ /**
1529
+ * 去掉 frontmatter 的正文。
1530
+ */
1531
+ content: string;
1532
+ metadata?: Record<string, unknown>;
1533
+ };
1534
+ export type SkillRegistration = {
1535
+ /**
1536
+ * 只作显示;正文取 `content`,不读这个文件。
1537
+ */
1538
+ path?: string;
1539
+ name: string;
1540
+ description: string;
1541
+ whenToUse?: string;
1542
+ /**
1543
+ * 不给时模型与用户都能用。
1544
+ */
1545
+ invocation?: SkillInvocationPolicy;
1546
+ source: string;
1547
+ resourceBase?: SkillResourceBase;
1548
+ content: string;
1549
+ metadata?: Record<string, unknown>;
1550
+ };
1551
+ export type CommandRegistration = {
1552
+ definitionId?: string;
1553
+ name: string;
1554
+ description: string;
1555
+ input?: CommandInputDescriptor;
1556
+ /**
1557
+ * `command/run` 记不记用户的输入,默认记。自己的会话事件已经带着输入的写 false,`args` 记成空串。
1558
+ */
1559
+ recordInput?: boolean;
1560
+ };
1561
+ export type CommandInputDescriptor = {
1562
+ /**
1563
+ * 用户输入之前显示的提示。
1564
+ */
1565
+ hint: string;
1566
+ };
1567
+ export type CommandRun = {
1568
+ /**
1569
+ * 这次调用记在 `command/run`、`command/done` 上的编号。
1570
+ */
1571
+ commandId: string;
1572
+ sessionId: string;
1573
+ /**
1574
+ * 命令名后面的原文,含分隔的空白。
1575
+ */
1576
+ rawInput: string;
1577
+ };
1578
+ export type CommandResult = {
1579
+ "kind": "success";
1580
+ text?: string;
1581
+ /**
1582
+ * 拥有更完整呈现的那条会话事件。
1583
+ */
1584
+ sourceEventSeq?: number;
1585
+ } | {
1586
+ "kind": "error";
1587
+ text: string;
1588
+ };
1589
+ export type CommandDescriptor = {
1590
+ /**
1591
+ * 插件给的稳定身份。
1592
+ */
1593
+ definitionId?: string;
1594
+ /**
1595
+ * 小写的命令名,不带斜杠。
1596
+ */
1597
+ name: string;
1598
+ description: string;
1599
+ input?: CommandInputDescriptor;
1600
+ };
1601
+ export type CommandExecution = {
1602
+ commandId: string;
1603
+ result: CommandResult;
1604
+ };
1605
+ export type PermissionCatalog = {
1606
+ options: Array<PresetOption>;
1607
+ defaultOptions: Array<PresetOption>;
1608
+ defaultPreset: string;
1609
+ };
1610
+ export type PresetOption = {
1611
+ value: string;
1612
+ name: string;
1613
+ sandbox?: SandboxMode;
1614
+ approval?: ApprovalPolicy;
1615
+ };
1616
+ export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
1617
+ export type PresetSpec = {
1618
+ sandbox: SandboxMode;
1619
+ approval: ApprovalPolicy;
1620
+ };
1621
+ export type SandboxPolicyRequest = {
1622
+ sessionId?: string;
1623
+ /**
1624
+ * 进行中工具调用的 token:读这次调用定下的模式。
1625
+ */
1626
+ execution?: string;
1627
+ };
1628
+ export type SandboxExecutionPolicy = {
1629
+ mode: SandboxMode;
1630
+ workspaceRoot: string;
1631
+ sessionId?: string;
1632
+ };
1633
+ export type SandboxPolicy = {
1634
+ mode: 'read-only' | 'workspace-write';
1635
+ workspaceRoot: string;
1636
+ sessionId?: string;
1637
+ };
1638
+ export type ConfinedArgv = {
1639
+ argv: Array<string>;
1640
+ enforcement: 'full' | 'partial';
1641
+ denialSignatures: Array<string>;
1642
+ runnerFailureRules: Array<RunnerFailureRule>;
1643
+ };
1644
+ export type RunnerFailureRule = {
1645
+ fatalSignatures: Array<string>;
1646
+ };
1647
+ export type ShellCommandRequest = {
1648
+ command: string;
1649
+ /**
1650
+ * 相对路径接在工作目录后面;不给时用工作目录。
1651
+ */
1652
+ workdir?: string;
1653
+ timeoutMs?: number;
1654
+ onExpiry?: ShellExpiryPolicy;
1655
+ /**
1656
+ * 写给命令的 stdin,写完关上;不给时 stdin 是空的。
1657
+ */
1658
+ stdin?: string;
1659
+ /**
1660
+ * 加给命令的环境变量,在清洗之后合并;`FTAI_*` 由宿主给,不能覆盖。
1661
+ */
1662
+ env?: {
1663
+ [key in string]: string;
1664
+ };
1665
+ /**
1666
+ * 进行中工具调用的 token:按这次调用定下的模式围。不给时是插件自己的命令,按部署默认的模式(同 `sandboxPolicy.resolve()` 不给会话时),断网。
1667
+ */
1668
+ execution?: string;
1669
+ };
1670
+ export type ShellExpiryPolicy = "kill";
1671
+ export type ShellCommandSpec = {
1672
+ command: string;
1673
+ workdir: string;
1674
+ timeoutMs: number;
1675
+ onExpiry: ShellExpiryPolicy;
1676
+ stdin?: string;
1677
+ env?: {
1678
+ [key in string]: string;
1679
+ };
1680
+ execution?: string;
1681
+ };
1682
+ export type ShellFrame = {
1683
+ "kind": "started";
1684
+ id: string;
1685
+ } | {
1686
+ "kind": "finished";
1687
+ outcome: ShellOutcome;
1688
+ };
1689
+ export type ShellOutcome = {
1690
+ status: ShellProcessStatus;
1691
+ exitCode: number | null;
1692
+ signal: string | null;
1693
+ timedOut: boolean;
1694
+ timeoutMs: number;
1695
+ stdout: ShellCollectedOutput;
1696
+ stderr: ShellCollectedOutput;
1697
+ sandbox?: ShellSandboxInfo;
1698
+ /**
1699
+ * 命令没有跑成(起不来、运行器自己失败):错误码与说明,`result()` 以它拒绝。
1700
+ */
1701
+ failure?: ShellFailure;
1702
+ /**
1703
+ * 上一次读取之后到结束的输出。
1704
+ */
1705
+ rest: ShellProcessRead;
1706
+ };
1707
+ export type ShellCollectedOutput = {
1708
+ /**
1709
+ * 截断时是尾部。
1710
+ */
1711
+ text: string;
1712
+ truncated: boolean;
1713
+ spillPath?: string;
1714
+ };
1715
+ export type ShellFailure = {
1716
+ code: string;
1717
+ message: string;
1718
+ };
1719
+ export type ShellProcessRead = {
1720
+ /**
1721
+ * 上一次读取之后的输出,stderr 在 `[stderr]` 一节里。
1722
+ */
1723
+ delta: string;
1724
+ lossy: boolean;
1725
+ stdoutSpillPath?: string;
1726
+ stderrSpillPath?: string;
1727
+ };
1728
+ export type ShellProcessStatus = "running" | "completed" | "killed";
1729
+ export type ShellSandboxInfo = {
1730
+ mode: SandboxMode;
1731
+ denied: boolean;
1732
+ runnerFailed: boolean;
1733
+ };
1734
+ export type ResolvedCredential = {
1735
+ value: string;
1736
+ source: string;
1737
+ };
1738
+ export type CredentialInfo = {
1739
+ /**
1740
+ * `resolve` 此刻能不能给出值。
1741
+ */
1742
+ configured: boolean;
1743
+ /**
1744
+ * 给出值的来源层,同 `ResolvedCredential` 的 `source`;没有配置时没有。
1745
+ */
1746
+ source?: string;
1747
+ /**
1748
+ * `set` 能不能写:插件的空间排在启动环境之前,总能写。
1749
+ */
1750
+ writable: boolean;
1751
+ };
1752
+ export type CredentialRecordInfo = {
1753
+ configured: boolean;
1754
+ kind?: CredentialRecordKind;
1755
+ writable: boolean;
1756
+ };
1757
+ export type CredentialRecordKind = "api-key" | "grant";
1758
+ export type CredentialRecordEntry = {
1759
+ key: string;
1760
+ kind: CredentialRecordKind;
1761
+ };
1762
+ export type CredentialModifyFrame = {
1763
+ "kind": "current";
1764
+ lease: string;
1765
+ record: JsonValue | null;
1766
+ } | {
1767
+ "kind": "settled";
1768
+ record: JsonValue | null;
1769
+ };
1770
+ export type CredentialUpdate = {
1771
+ "kind": "reference";
1772
+ reference: string;
1773
+ } | {
1774
+ "kind": "record";
1775
+ key: string;
1776
+ };
1777
+ export type LoaderEntry = {
1778
+ name: string;
1779
+ enabled: boolean;
1780
+ /**
1781
+ * 必达通道(更新、公告),不能关。
1782
+ */
1783
+ alwaysOn: boolean;
1784
+ /**
1785
+ * 随应用分发的插件。
1786
+ */
1787
+ firstParty: boolean;
1788
+ version?: string;
1789
+ };
1790
+ /** 宿主的扩展点:名字 → 交互方式、载荷与结论。 */
1791
+ export interface HostPoints {
1792
+ /**
1793
+ * 工具执行前:放行、拒绝、取消,或要求审批。默认放行,工具本身要求审批时询问。监听要声明 `tools.intercept`。TS 插件的 `allow`
1794
+ * 代答这个默认询问:要声明 `approval.answer` 并经用户授权,否则照常弹卡、卡上写明插件的建议;代答不弹卡、记为插件代答,审批
1795
+ * 策略 never 时仍被拒、「替我审批」时仍交审查者;规则给的询问与拒绝盖不过。监听者失败当它没表态,带 `failClosed` 的按拒绝。
1796
+ */
1797
+ 'tools/pre-execute': {
1798
+ kind: 'waterfall';
1799
+ input: ToolExecution;
1800
+ output: PreToolDecision;
1801
+ };
1802
+ /**
1803
+ * 包住工具执行:调用 `next` 得到结果(可以再调用一次重试),可以换 `exec.signal`,改不了参数与调用身份,也去不掉调用方的取消。
1804
+ * 工具可能跑很久,不设超时。监听者失败当它没表态:没调用 `next` 时照常执行工具,拿到过结果时用它;调用了还没拿到(插件进程
1805
+ * 不在时工具随之停下)与带 `failClosed` 的这次调用按失败收。
1806
+ */
1807
+ 'tools/execute': {
1808
+ kind: 'waterfall';
1809
+ input: ToolExecution;
1810
+ output: ToolResultData;
1811
+ };
1812
+ /**
1813
+ * 工具结果写进会话之前:收下、换内容、拦下或追加上下文。不调用 `next` 时宿主补跑下游,下游拦下则拦下。监听者失败当它没表态,
1814
+ * 结果照下游的;带 `failClosed` 的换成固定的失败文本,不回退到原文。
1815
+ */
1816
+ 'tools/post-execute': {
1817
+ kind: 'waterfall';
1818
+ input: ToolSettled;
1819
+ output: PostExecuteDecision;
1820
+ };
1821
+ /** 工具结果定下了(按模型给的顺序,紧接着记成 tool/result)。观察点,不等答复。 */
1822
+ 'tools/result': {
1823
+ kind: 'observe';
1824
+ input: ToolSettled;
1825
+ output: void;
1826
+ };
1827
+ /** 工具注册或按 agent 的收起变了:重新读 `ctx.tools.schemas()`。观察点,没有载荷,不按 agent 过滤。 */
1828
+ 'tools/change': {
1829
+ kind: 'observe';
1830
+ input: null;
1831
+ output: void;
1832
+ };
1833
+ /**
1834
+ * agent 建好:在这里按会话注册工具、提示词段与收起工具,从第一步起生效。新会话(`startup`)在交给调用方之前发:建会话、
1835
+ * 发送新会话的第一条消息时在输入排进队列之前,分叉(含侧聊与编辑重发)时在返回新会话之前;监听者失败时会话不建,
1836
+ * 错误原样交回调用方,输入退回。续上已有的会话(`resume`)与新建的子 agent 在第一步之前发,监听者失败只记日志。
1837
+ */
1838
+ 'agent/created': {
1839
+ kind: 'wait';
1840
+ input: AgentCreated;
1841
+ output: void;
1842
+ };
1843
+ /** 模型的流式输出:每次模型调用按 start、若干 chunk、end 的顺序发。 */
1844
+ 'agent/assistant-stream': {
1845
+ kind: 'observe';
1846
+ input: AssistantStream;
1847
+ output: void;
1848
+ };
1849
+ /** 每条落盘的会话事件;插件的会话投影由它驱动。 */
1850
+ 'session/event': {
1851
+ kind: 'observe';
1852
+ input: SessionEventNotice;
1853
+ output: void;
1854
+ };
1855
+ /** 会话进了宿主的内存:新建的、读进来查看或续上的都算。同一个会话之后的 `session/event` 都在它之后。不能否决。 */
1856
+ 'session/created': {
1857
+ kind: 'observe';
1858
+ input: AgentRef;
1859
+ output: void;
1860
+ };
1861
+ /** 会话从宿主的内存卸下:之后的 `session/event` 不会再有,排在 `agent/disposed` 之前。 */
1862
+ 'session/disposed': {
1863
+ kind: 'observe';
1864
+ input: AgentRef;
1865
+ output: void;
1866
+ };
1867
+ /**
1868
+ * 一批事件写下之后(`ctx.sessions.flush` 时再发一次):排在这批的 `session/event` 之后,宿主按顺序等监听者。插件据此
1869
+ * 落盘自己缓冲的事件。写入不等它;只有 `ctx.sessions.flush` 能拿到监听者的失败,其余的只记日志。
1870
+ */
1871
+ 'session/flush': {
1872
+ kind: 'wait';
1873
+ input: AgentRef;
1874
+ output: void;
1875
+ };
1876
+ /** agent 从宿主内存卸下:按它留的注册随之撤销。再用到这个会话时它是一个新的 agent,再发一次 `agent/created`。 */
1877
+ 'agent/disposed': {
1878
+ kind: 'observe';
1879
+ input: AgentDisposed;
1880
+ output: void;
1881
+ };
1882
+ /** agent 在空闲与运行之间切换。 */
1883
+ 'agent/status': {
1884
+ kind: 'observe';
1885
+ input: AgentStatusChange;
1886
+ output: void;
1887
+ };
1888
+ /** 一步或一轮失败。 */
1889
+ 'agent/error': {
1890
+ kind: 'observe';
1891
+ input: AgentFailure;
1892
+ output: void;
1893
+ };
1894
+ /** 一条消息进了收件箱。 */
1895
+ 'agent/inbox/inserted': {
1896
+ kind: 'observe';
1897
+ input: AgentInboxChange;
1898
+ output: void;
1899
+ };
1900
+ /** 一条消息从收件箱被这一轮认领。 */
1901
+ 'agent/inbox/claimed': {
1902
+ kind: 'observe';
1903
+ input: AgentInboxClaimed;
1904
+ output: void;
1905
+ };
1906
+ /** 一条消息从收件箱丢弃(撤下、删除、清空)。 */
1907
+ 'agent/inbox/discarded': {
1908
+ kind: 'observe';
1909
+ input: AgentInboxChange;
1910
+ output: void;
1911
+ };
1912
+ /**
1913
+ * 一步开始之前:内层默认给出认领的输入与有变化时的运行环境快照,监听者在后面追加消息、替换消息或否决这一步(这一轮以
1914
+ * blocked 结束)。消息随之落盘。不调用 `next` 时宿主补跑下游,下游否决则否决。监听者失败当它没表态,带 `failClosed` 的否决。
1915
+ */
1916
+ 'agent/pre-step': {
1917
+ kind: 'waterfall';
1918
+ input: PreStep;
1919
+ output: PreStepDecision;
1920
+ };
1921
+ /**
1922
+ * 模型调用发出之前:调用 `next` 得到这次的配置,返回替换后的配置可以换路由、推理强度与输出上限。换到没注册的路由时这一轮以错误结束;
1923
+ * 监听者失败当它没表态,用下游的配置,带 `failClosed` 的这一轮以错误结束。
1924
+ */
1925
+ 'agent/request': {
1926
+ kind: 'waterfall';
1927
+ input: AgentRequest;
1928
+ output: AgentRequestDecision;
1929
+ };
1930
+ /**
1931
+ * 一次模型请求失败:返回 `{ kind: 'retry' }` 立即再请求一次(退避由监听者自己等),不计入内置重试;默认不接手,走内置的
1932
+ * 重试判断。超时或崩溃按不接手。
1933
+ */
1934
+ 'agent/request-error': {
1935
+ kind: 'waterfall';
1936
+ input: AgentRequestError;
1937
+ output: RequestErrorAction | null;
1938
+ };
1939
+ /**
1940
+ * 每一步组装系统提示之前(`ctx.systemPrompt.assemble` 也经过):调用 `next` 得到下游的组装,返回值就是这次的组装。可以改身份段(`deployment:persona-prefix`)。
1941
+ * 之后宿主恢复完整段,没有完整段时把回复语言段(`deployment:reply-language`)原样固定回身份段之后,运行环境段按注册的取值刷新、补回不可收起的段(沙箱与审批的说明都是),工具清单只认有执行者的工具。
1942
+ * 监听者失败当它没表态,用下游的组装;带 `failClosed` 的这一轮以错误结束。
1943
+ */
1944
+ 'system-prompt/assemble': {
1945
+ kind: 'waterfall';
1946
+ input: SystemPromptAssemble;
1947
+ output: AssembleDecision;
1948
+ };
1949
+ /** 提示词段、运行环境段、变量、工具与工具提供者的注册有变化:不带载荷,监听者看到的已是变化之后的状态。 */
1950
+ 'system-prompt/change': {
1951
+ kind: 'observe';
1952
+ input: null;
1953
+ output: void;
1954
+ };
1955
+ /**
1956
+ * 模型的流式输出,监听者可以改写:Agent 回路(含子 agent)的每次模型调用与插件的 `ctx.llm.stream` 都经过它,写进会话的是
1957
+ * 改写后的结果。调用 `next()` 得到下游的流,每次调用发起一次下游请求;不调用就是自己给出输出。载荷不能改:Agent 的请求由
1958
+ * 会话日志决定。Guardian(自动审批)、标题、压缩等宿主内部的调用不经过它。超时或崩溃时这次调用以 `error` 的 finish 结束。
1959
+ */
1960
+ 'llm/stream': {
1961
+ kind: 'stream';
1962
+ input: LlmStreamRequest;
1963
+ output: JsonValue;
1964
+ };
1965
+ /** 模型路由、模型清单或可配置 provider 的目录变了:按 `listProviders`、`listModels`、`listConfigurableProviders` 重新取。 */
1966
+ 'llm/adapters-updated': {
1967
+ kind: 'observe';
1968
+ input: null;
1969
+ output: void;
1970
+ };
1971
+ /**
1972
+ * 一轮在正常的停止点结束之前:模型不再调用工具、也没有插话时,宿主按顺序等全部监听者返回再记 `turn/end`。监听者在这里
1973
+ * 追加的插件记录落在 `turn/end` 之前;插进来的输入让这一轮再走一步。取消与出错结束的轮次不经过这里(看
1974
+ * `session/event` 里的 `turn/end`);这一轮被取消时不再等。监听者失败只记日志,这一轮照常结束。
1975
+ */
1976
+ 'agent/turn-stopping': {
1977
+ kind: 'wait';
1978
+ input: TurnStopping;
1979
+ output: void;
1980
+ };
1981
+ /**
1982
+ * 整份写入之前(0.12 的 `fs/write-intent`):给出这次写入的条件。只有一个决定者:先返回的监听者说了算,不调用 `next`
1983
+ * (默认是 fs-observation-policy:读过的按读到的版本替换,没读过的只许新建);要在写入之前做事又不改决定的监听者
1984
+ * prepend,调用 `next` 再原样返回(如本轮改动记录先存下原文件)。内层默认无条件。失败时这次写入以这个错误结束。
1985
+ * TS 插件的监听者只能收紧,一律排在最前:不调用 `next` 时宿主补跑下游,结论取更严的(无条件、带条件、报错);监听者
1986
+ * 失败当它没表态,带 `failClosed` 的这次写入失败。TS 插件不能发起,写文件用 `fs.writeBytes`,由宿主在写之前跑它。
1987
+ */
1988
+ 'fs/write-intent': {
1989
+ kind: 'waterfall';
1990
+ input: FsIntent;
1991
+ output: {
1992
+ Ok: FsWriteIntent | null;
1993
+ } | {
1994
+ Err: FsFailure;
1995
+ };
1996
+ };
1997
+ /**
1998
+ * 编辑之前(0.12 的 `fs/edit-intent`):给出这次编辑要核对的版本,或以错误拒绝(没读过的文件 `FS_NOT_OBSERVED`)。
1999
+ * 决定方式与 TS 插件的限制同 `fs/write-intent`;内层默认无条件。TS 插件不能发起,编辑用 `fs.editText`。
2000
+ */
2001
+ 'fs/edit-intent': {
2002
+ kind: 'waterfall';
2003
+ input: FsIntent;
2004
+ output: {
2005
+ Ok: string | null;
2006
+ } | {
2007
+ Err: FsFailure;
2008
+ };
2009
+ };
2010
+ /**
2011
+ * 文件工具确定地看到了一个目标在或不在(0.12 的 `fs/observed`):读到时、确认不在时、写入与编辑之后。观察策略据此决定
2012
+ * 之后的写入条件。TS 插件只能监听:发起不算观察,放宽不了先读后改。
2013
+ */
2014
+ 'fs/observed': {
2015
+ kind: 'observe';
2016
+ input: FsObserved;
2017
+ output: void;
2018
+ };
2019
+ /**
2020
+ * 归档之前问会话还有什么在跑(`archiveSession` 不带 `stopActivity` 时):调用 `next` 得到下游的工作,把自己的加在前面返回。
2021
+ * 非空就拒绝归档,什么都不写。监听者藏不住下游报的工作;超时(60 秒)、崩溃或形状不对时按它没有报(坏插件不能永远挡住归档)。
2022
+ * 登记的写入在排队,监听者里不要调用会改登记的方法,否则等到超时。
2023
+ */
2024
+ 'workspace/session-activity': {
2025
+ kind: 'waterfall';
2026
+ input: SessionActivityRequest;
2027
+ output: Array<SessionActivity>;
2028
+ };
2029
+ /**
2030
+ * 归档之后请各方停下这个会话的工作(`archiveSession` 带 `stopActivity` 时):归档集已经落盘,停下引起的唤醒都已被挡住。监听者
2031
+ * 同时跑,宿主都等到结束;失败或超时(30 秒)只记日志,不影响别的监听者,也不撤销归档。发出停止请求即可,不要等工作结束。
2032
+ */
2033
+ 'workspace/session-stop': {
2034
+ kind: 'wait';
2035
+ input: SessionActivityRequest;
2036
+ output: void;
2037
+ };
2038
+ /** Goal 的一次变更写进了会话:模型的工具、界面、插件与轮次驱动改的都算。 */
2039
+ 'goal/changed': {
2040
+ kind: 'observe';
2041
+ input: GoalChanged;
2042
+ output: void;
2043
+ };
2044
+ /** 这个宿主进程是否在为 Goal 安排轮次变了(激活状态不落盘)。 */
2045
+ 'goal/activation-changed': {
2046
+ kind: 'observe';
2047
+ input: GoalActivationChanged;
2048
+ output: void;
2049
+ };
2050
+ /** 已安排的任务变了(建、改、删、暂停、恢复、转移、投递):重新读 `ctx.schedule`。观察点,没有载荷,一批变化可能合成一次。 */
2051
+ 'schedule/changed': {
2052
+ kind: 'observe';
2053
+ input: null;
2054
+ output: void;
2055
+ };
2056
+ /**
2057
+ * 摘要请求失败、图片卸载也救不了时:监听者写下改动(如插件记录加消息投影)后返回 true,宿主重新计量这段范围、再请求一次;
2058
+ * 救不了就调用 `next`,默认不重试。每次压缩最多重试 3 次。超时(60 秒)或崩溃按不重试。
2059
+ */
2060
+ 'compaction/summary-error': {
2061
+ kind: 'waterfall';
2062
+ input: CompactionSummaryError;
2063
+ output: boolean;
2064
+ };
2065
+ /** 一段子 agent 的常驻开始了(新建或冷恢复,工具与插件起的都算)。与 `subagent/end` 按 `runId` 成对,同一段先发它。观察点,不等答复。 */
2066
+ 'subagent/start': {
2067
+ kind: 'observe';
2068
+ input: SubagentRunInfo;
2069
+ output: void;
2070
+ };
2071
+ /** 一段子 agent 的常驻结算了。观察点,不等答复。 */
2072
+ 'subagent/end': {
2073
+ kind: 'observe';
2074
+ input: SubagentRunEndInfo;
2075
+ output: void;
2076
+ };
2077
+ /**
2078
+ * 向用户提问之前(`ask_user_question` 与 `ctx.userQuestions.ask` 都经过):调用 `next` 交给后面的监听者,最后到界面的提问卡片,等待用户的
2079
+ * 时间不计入监听者的上限;不调用就是替用户作答。监听者抛错、超时(60 秒)或进程不在时不算作答,交给下一个。
2080
+ */
2081
+ 'user-questions/request': {
2082
+ kind: 'waterfall';
2083
+ input: AskUserQuestionRequestEvent;
2084
+ output: AskUserQuestionDecision;
2085
+ };
2086
+ /** Skill 可能变了(开关、安装卸载、能力包、插件注册、磁盘上的改动):不带载荷,按 `ctx.skills` 重新读。 */
2087
+ 'skills/change': {
2088
+ kind: 'observe';
2089
+ input: null;
2090
+ output: void;
2091
+ };
2092
+ /** 命令表变了(注册或撤销):不带载荷,按 `ctx.commands.list` 重新读。不按 agent 过滤。 */
2093
+ 'commands/change': {
2094
+ kind: 'observe';
2095
+ input: null;
2096
+ output: void;
2097
+ };
2098
+ /**
2099
+ * 工具调用要批准时(0.12 的 `approval/request`):返回结论作答,调用 `next` 交给下一个,最里层是界面卡片。监听要声明
2100
+ * `approval.observe`。「替我审批」的会话与审批策略 never 的会话不派发。`allowed-once` 等于用户批准这一次,包括提权;要声明
2101
+ * `approval.answer` 并经用户授权,否则当它没表态、交给下一个,卡上写明插件的建议。`next` 给出拒绝或取消之后不能改成 `allowed-once`,
2102
+ * 改了照 `next` 的结论;`next` 是 `unavailable`(没有应答方)时照样可以作答。抛错、崩溃、自身用时超过 60 秒(等 `next` 的时间
2103
+ * 不算)、返回值不是四种之一时当它没表态,交给下一个(最后是界面的卡片),已经拿到 `next` 的结论时用它;带 `failClosed` 的
2104
+ * 是 `unavailable`,不转放行,也不转下一个。这一轮被取消时是 `cancelled`。
2105
+ */
2106
+ 'approval/request': {
2107
+ kind: 'waterfall';
2108
+ input: ApprovalRequestEvent;
2109
+ output: ApprovalAnswer;
2110
+ };
2111
+ /** 权限预设的目录变了(0.12 的 `permission-presets/catalog-changed`):重新取 `permissionPresets.catalog()`。预设表是写死的,现在不会触发。 */
2112
+ 'permission-presets/catalog-changed': {
2113
+ kind: 'observe';
2114
+ input: null;
2115
+ output: void;
2116
+ };
2117
+ }
2118
+ /** 扩展点名 → 交互方式与 SDK 是否另包一层,运行时按它把监听转发给宿主。 */
2119
+ export declare const HOST_POINTS: {
2120
+ readonly 'tools/pre-execute': {
2121
+ readonly kind: "waterfall";
2122
+ readonly wrapped: true;
2123
+ };
2124
+ readonly 'tools/execute': {
2125
+ readonly kind: "waterfall";
2126
+ readonly wrapped: true;
2127
+ };
2128
+ readonly 'tools/post-execute': {
2129
+ readonly kind: "waterfall";
2130
+ readonly wrapped: true;
2131
+ };
2132
+ readonly 'tools/result': {
2133
+ readonly kind: "observe";
2134
+ readonly wrapped: true;
2135
+ };
2136
+ readonly 'tools/change': {
2137
+ readonly kind: "observe";
2138
+ readonly wrapped: false;
2139
+ };
2140
+ readonly 'agent/created': {
2141
+ readonly kind: "wait";
2142
+ readonly wrapped: true;
2143
+ };
2144
+ readonly 'agent/assistant-stream': {
2145
+ readonly kind: "observe";
2146
+ readonly wrapped: true;
2147
+ };
2148
+ readonly 'session/event': {
2149
+ readonly kind: "observe";
2150
+ readonly wrapped: true;
2151
+ };
2152
+ readonly 'session/created': {
2153
+ readonly kind: "observe";
2154
+ readonly wrapped: true;
2155
+ };
2156
+ readonly 'session/disposed': {
2157
+ readonly kind: "observe";
2158
+ readonly wrapped: true;
2159
+ };
2160
+ readonly 'session/flush': {
2161
+ readonly kind: "wait";
2162
+ readonly wrapped: true;
2163
+ };
2164
+ readonly 'agent/disposed': {
2165
+ readonly kind: "observe";
2166
+ readonly wrapped: true;
2167
+ };
2168
+ readonly 'agent/status': {
2169
+ readonly kind: "observe";
2170
+ readonly wrapped: true;
2171
+ };
2172
+ readonly 'agent/error': {
2173
+ readonly kind: "observe";
2174
+ readonly wrapped: true;
2175
+ };
2176
+ readonly 'agent/inbox/inserted': {
2177
+ readonly kind: "observe";
2178
+ readonly wrapped: true;
2179
+ };
2180
+ readonly 'agent/inbox/claimed': {
2181
+ readonly kind: "observe";
2182
+ readonly wrapped: true;
2183
+ };
2184
+ readonly 'agent/inbox/discarded': {
2185
+ readonly kind: "observe";
2186
+ readonly wrapped: true;
2187
+ };
2188
+ readonly 'agent/pre-step': {
2189
+ readonly kind: "waterfall";
2190
+ readonly wrapped: true;
2191
+ };
2192
+ readonly 'agent/request': {
2193
+ readonly kind: "waterfall";
2194
+ readonly wrapped: true;
2195
+ };
2196
+ readonly 'agent/request-error': {
2197
+ readonly kind: "waterfall";
2198
+ readonly wrapped: true;
2199
+ };
2200
+ readonly 'system-prompt/assemble': {
2201
+ readonly kind: "waterfall";
2202
+ readonly wrapped: true;
2203
+ };
2204
+ readonly 'system-prompt/change': {
2205
+ readonly kind: "observe";
2206
+ readonly wrapped: false;
2207
+ };
2208
+ readonly 'llm/stream': {
2209
+ readonly kind: "stream";
2210
+ readonly wrapped: true;
2211
+ };
2212
+ readonly 'llm/adapters-updated': {
2213
+ readonly kind: "observe";
2214
+ readonly wrapped: false;
2215
+ };
2216
+ readonly 'agent/turn-stopping': {
2217
+ readonly kind: "wait";
2218
+ readonly wrapped: true;
2219
+ };
2220
+ readonly 'fs/write-intent': {
2221
+ readonly kind: "waterfall";
2222
+ readonly wrapped: true;
2223
+ };
2224
+ readonly 'fs/edit-intent': {
2225
+ readonly kind: "waterfall";
2226
+ readonly wrapped: true;
2227
+ };
2228
+ readonly 'fs/observed': {
2229
+ readonly kind: "observe";
2230
+ readonly wrapped: true;
2231
+ };
2232
+ readonly 'workspace/session-activity': {
2233
+ readonly kind: "waterfall";
2234
+ readonly wrapped: false;
2235
+ };
2236
+ readonly 'workspace/session-stop': {
2237
+ readonly kind: "wait";
2238
+ readonly wrapped: false;
2239
+ };
2240
+ readonly 'goal/changed': {
2241
+ readonly kind: "observe";
2242
+ readonly wrapped: false;
2243
+ };
2244
+ readonly 'goal/activation-changed': {
2245
+ readonly kind: "observe";
2246
+ readonly wrapped: false;
2247
+ };
2248
+ readonly 'schedule/changed': {
2249
+ readonly kind: "observe";
2250
+ readonly wrapped: false;
2251
+ };
2252
+ readonly 'compaction/summary-error': {
2253
+ readonly kind: "waterfall";
2254
+ readonly wrapped: false;
2255
+ };
2256
+ readonly 'subagent/start': {
2257
+ readonly kind: "observe";
2258
+ readonly wrapped: false;
2259
+ };
2260
+ readonly 'subagent/end': {
2261
+ readonly kind: "observe";
2262
+ readonly wrapped: false;
2263
+ };
2264
+ readonly 'user-questions/request': {
2265
+ readonly kind: "waterfall";
2266
+ readonly wrapped: true;
2267
+ };
2268
+ readonly 'skills/change': {
2269
+ readonly kind: "observe";
2270
+ readonly wrapped: false;
2271
+ };
2272
+ readonly 'commands/change': {
2273
+ readonly kind: "observe";
2274
+ readonly wrapped: false;
2275
+ };
2276
+ readonly 'approval/request': {
2277
+ readonly kind: "waterfall";
2278
+ readonly wrapped: true;
2279
+ };
2280
+ readonly 'permission-presets/catalog-changed': {
2281
+ readonly kind: "observe";
2282
+ readonly wrapped: false;
2283
+ };
2284
+ };
2285
+ /** 宿主的服务:服务名 → 方法名 → 交互方式、按位置的参数、结论与回调。 */
2286
+ export interface HostServices {
2287
+ /** 注册模型可调用的工具(0.12 的 `ctx.tools`)。 */
2288
+ 'tools': {
2289
+ /** 注册一个工具,执行时经回调回到插件。 */
2290
+ 'register': {
2291
+ kind: 'register';
2292
+ args: [tool: ToolRegistration];
2293
+ output: void;
2294
+ callback: {
2295
+ input: ToolRequest;
2296
+ output: ToolReply;
2297
+ };
2298
+ };
2299
+ /** 按 agent 收起全局工具(多个限制取交集)。 */
2300
+ 'restrict': {
2301
+ kind: 'register';
2302
+ args: [agent: string, filter: ToolFilter];
2303
+ output: void;
2304
+ };
2305
+ /**
2306
+ * 只能拒绝的关口:排在全部 `tools/pre-execute` 与审批之后、工具体之前。回调给出理由即拒绝,给 null 不改变结论;抛错、
2307
+ * 超时或插件进程不在时当它没表态(边界 3),`failClosed` 为 true 时按拒绝。`agent` 给出时只管这个 agent 的调用。要声明
2308
+ * `tools.intercept`。
2309
+ */
2310
+ 'guard': {
2311
+ kind: 'register';
2312
+ args: [agent: string | null, failClosed: boolean | null];
2313
+ output: void;
2314
+ callback: {
2315
+ input: ToolExecution;
2316
+ output: string | null;
2317
+ };
2318
+ };
2319
+ /** 按名字读工具的 schema,不含执行体;`agent` 给出时按它看到的,不给时按全局的。没有时为 null。 */
2320
+ 'get': {
2321
+ kind: 'call';
2322
+ args: [name: string, agent: string | null];
2323
+ output: ToolSchema | null;
2324
+ };
2325
+ /** 看得到的工具的 schema,按名字排好;`agent` 给出时按它看到的(不论延迟加载与否),不给时按全局的。 */
2326
+ 'schemas': {
2327
+ kind: 'call';
2328
+ args: [agent: string | null];
2329
+ output: Array<ToolSchema>;
2330
+ };
2331
+ /** 按参数判定一次调用能否并发;不认识的工具、超时、崩溃或不是 true 都是 `exclusive`。 */
2332
+ 'executionMode': {
2333
+ kind: 'call';
2334
+ args: [query: ToolModeQuery];
2335
+ output: ToolExecutionMode;
2336
+ };
2337
+ /**
2338
+ * 执行一次工具调用,走模型发起时的同一条路:`tools/pre-execute`、审批、`guard`、沙箱、`tools/execute`、`tools/post-execute`。
2339
+ * 不写 tool/call 与 tool/result;要审批时写 approval/asked 与 approval/decided,所以要审批的调用只能在进行中的一轮里。
2340
+ * 没有这个 agent 时报 `agent/session-not-found`,归档的会话报 `agent/session-archived`。
2341
+ */
2342
+ 'execute': {
2343
+ kind: 'call';
2344
+ args: [input: ToolExecuteInput];
2345
+ output: ToolExecuted;
2346
+ };
2347
+ };
2348
+ /**
2349
+ * 系统提示词的段、运行环境段、变量与工具提供者(0.12 的 `ctx.systemPrompt`)。`agent` 给出时只对这个 agent 生效;经回调取值的
2350
+ * 内容在每一步组装之前取好,失败或超时时这一轮以错误结束。
2351
+ */
2352
+ 'systemPrompt': {
2353
+ /** 注册一段;同一层里重名时失败。`text` 不给时经回调取值。 */
2354
+ 'section': {
2355
+ kind: 'register';
2356
+ args: [agent: string | null, section: PromptSectionSpec];
2357
+ output: void;
2358
+ callback: {
2359
+ input: PromptScope;
2360
+ output: string;
2361
+ };
2362
+ };
2363
+ /** 注册一段运行环境;同一层里重名时失败,沙箱与审批说明的名字保留。`text` 不给时经回调取值。 */
2364
+ 'context': {
2365
+ kind: 'register';
2366
+ args: [agent: string | null, context: PromptContextSpec];
2367
+ output: void;
2368
+ callback: {
2369
+ input: PromptScope;
2370
+ output: string;
2371
+ };
2372
+ };
2373
+ /** 收起可选的运行环境段(不可收起的段不受影响),随这项注册撤销。 */
2374
+ 'suppressRuntimeContext': {
2375
+ kind: 'register';
2376
+ args: [agent: string | null];
2377
+ output: void;
2378
+ };
2379
+ /** 注册工具 schema 的提供者:每一步取值,给出的名字必须是这个 agent 看得到的、有执行者的工具。 */
2380
+ 'tools': {
2381
+ kind: 'register';
2382
+ args: [agent: string | null];
2383
+ output: void;
2384
+ callback: {
2385
+ input: PromptScope;
2386
+ output: ToolProviderResult;
2387
+ };
2388
+ };
2389
+ /** 注册提示词变量,经回调取值;同一层里重名时失败。 */
2390
+ 'variable': {
2391
+ kind: 'register';
2392
+ args: [agent: string | null, name: string];
2393
+ output: void;
2394
+ callback: {
2395
+ input: PromptScope;
2396
+ output: string | null;
2397
+ };
2398
+ };
2399
+ /** 只读地组装一次:取值、跑瀑布,不写会话。 */
2400
+ 'assemble': {
2401
+ kind: 'call';
2402
+ args: [agent: string | null];
2403
+ output: PromptAssembly;
2404
+ };
2405
+ /** 按已接受的组装刷新运行环境段:注册着的重新取值,只由瀑布加上的保留,缺的不可收起的段补回。 */
2406
+ 'refreshContext': {
2407
+ kind: 'call';
2408
+ args: [assembly: PromptAssembly, agent: string | null];
2409
+ output: PromptAssembly;
2410
+ };
2411
+ };
2412
+ /**
2413
+ * 插件后端给界面的 remote(0.12 的 `TypertRemoteService`):SDK 的 `TypertRemoteService` 用它挂载命名空间,
2414
+ * 界面经宿主协议的 `pluginRemote.*` 调用。
2415
+ */
2416
+ 'pluginRemote': {
2417
+ /** 挂载一个命名空间,随服务撤销;同名命名空间已挂载时失败。 */
2418
+ 'mount': {
2419
+ kind: 'register';
2420
+ args: [namespace: string, methods: Array<RemoteMethod>];
2421
+ output: void;
2422
+ callback: {
2423
+ input: RemoteInvocation;
2424
+ output: JsonValue;
2425
+ };
2426
+ };
2427
+ };
2428
+ /** 会话日志(0.12 的 `ctx.sessions` 与 `appendPluginRecord`)。 */
2429
+ 'sessions': {
2430
+ /** 追加一条插件记录(可忽略的会话事件,模型看不到),返回它的 seq。 */
2431
+ 'appendPluginRecord': {
2432
+ kind: 'call';
2433
+ args: [sessionId: string, recordType: string, data: JsonValue];
2434
+ output: number;
2435
+ };
2436
+ /**
2437
+ * 会话里已落盘的事件(v4 的行,`sourceEventSeqs` 已展开),按 seq 取 `fromSeq` 到 `toSeq`,两端都含,不给时不限;插件进程
2438
+ * 据此整批折叠会话投影。
2439
+ */
2440
+ 'events': {
2441
+ kind: 'call';
2442
+ args: [sessionId: string, fromSeq: number | null, toSeq: number | null];
2443
+ output: Array<JsonValue>;
2444
+ };
2445
+ /** 完整的会话头(v4 的首行);没有这个会话时为 null。 */
2446
+ 'header': {
2447
+ kind: 'call';
2448
+ args: [sessionId: string];
2449
+ output: JsonValue | null;
2450
+ };
2451
+ /** 模型此刻看得到的事件,按顺序(0.12 的 `session.surface`)。 */
2452
+ 'surface': {
2453
+ kind: 'call';
2454
+ args: [sessionId: string];
2455
+ output: Array<JsonValue>;
2456
+ };
2457
+ /** 下一个事件的 seq,即日志长度(0.12 的 `session.seq`);没有这个会话时为 0。 */
2458
+ 'seq': {
2459
+ kind: 'call';
2460
+ args: [sessionId: string];
2461
+ output: number;
2462
+ };
2463
+ /**
2464
+ * 校验新会话的 id 与工作目录(绝对路径,不给时用宿主的默认目录)并给出会话头的字段,不进内存。已有这个 id 时报
2465
+ * `session/exists`。
2466
+ */
2467
+ 'prepare': {
2468
+ kind: 'call';
2469
+ args: [sessionId: string | null, cwd: string | null];
2470
+ output: PreparedSession;
2471
+ };
2472
+ /**
2473
+ * 把校验过的会话放进内存,发 `session/created`(不发 `agent/created`,要驱动它用 `agents.resume`)。插件拿着它,不按
2474
+ * 空闲卸下,直到 `release` 或插件进程退出。第一次写入时才落盘。
2475
+ */
2476
+ 'enter': {
2477
+ kind: 'call';
2478
+ args: [session: PreparedSession];
2479
+ output: void;
2480
+ };
2481
+ /** 等 `session/created` 发到监听者手里。不在内存里时报 `session/not-found`。 */
2482
+ 'announce': {
2483
+ kind: 'call';
2484
+ args: [sessionId: string];
2485
+ output: void;
2486
+ };
2487
+ /** 放开 `enter`、`fork` 拿着的会话:下一次核对时(最长约 1 分钟)卸下,有人在用时留下。 */
2488
+ 'release': {
2489
+ kind: 'call';
2490
+ args: [sessionId: string];
2491
+ output: void;
2492
+ };
2493
+ /**
2494
+ * 从来源的 `boundary`(含,不给时是最后一个事件)分叉出新会话并拿着它,种子只经这里带入。新会话发 `agent/created`,
2495
+ * 挂到来源所在的工作区。错误码:`session/not-found`、`session/fork-unavailable`、`session/exists`。
2496
+ */
2497
+ 'fork': {
2498
+ kind: 'call';
2499
+ args: [source: string, boundary: number | null, childSessionId: string | null];
2500
+ output: AgentRef;
2501
+ };
2502
+ /**
2503
+ * 等这个会话已发出的 `session/event` 都到了监听者手里,再按顺序等 `session/flush` 的监听者;第一个失败的错误交回。
2504
+ * 宿主记事件时同步落盘,结果总是 true。
2505
+ */
2506
+ 'flush': {
2507
+ kind: 'call';
2508
+ args: [sessionId: string];
2509
+ output: boolean;
2510
+ };
2511
+ /** 会话日志里的几个位置。 */
2512
+ 'lifecycle': {
2513
+ kind: 'call';
2514
+ args: [sessionId: string];
2515
+ output: SessionLifecycle;
2516
+ };
2517
+ /** 追加一条可忽略的事件,返回记下的事件。类型只收插件记录的写法(`plugin:...`),核心事件类型报 `session/event-type-not-allowed`。 */
2518
+ 'append': {
2519
+ kind: 'call';
2520
+ args: [sessionId: string, eventType: string, data: JsonValue];
2521
+ output: JsonValue;
2522
+ };
2523
+ /** 最后一个 `request/header` 的 `header`;还没有请求过时为 null。 */
2524
+ 'requestHeader': {
2525
+ kind: 'call';
2526
+ args: [sessionId: string];
2527
+ output: JsonValue | null;
2528
+ };
2529
+ /** 最后一个 `request/context` 的内容;还没有时为 null。 */
2530
+ 'requestContext': {
2531
+ kind: 'call';
2532
+ args: [sessionId: string];
2533
+ output: JsonValue | null;
2534
+ };
2535
+ /** 模型此刻看到的消息(0.12 的 `session.deriveMessages()`):改写已生效,日志不变。投影失败时报 `session/message-projection-failed`。 */
2536
+ 'deriveMessages': {
2537
+ kind: 'call';
2538
+ args: [sessionId: string];
2539
+ output: Array<JsonValue>;
2540
+ };
2541
+ /** 一条事件(v4 的行)对应的模型可见消息,改写已生效;不产生消息的事件为 null。投影失败同 `deriveMessages`。 */
2542
+ 'deriveEventMessage': {
2543
+ kind: 'call';
2544
+ args: [sessionId: string, event: JsonValue];
2545
+ output: JsonValue | null;
2546
+ };
2547
+ /**
2548
+ * 登记一个事件类型的消息投影(只收 `plugin:...`,`plugin:ftai/` 留给 FtAi 自己):派生消息时宿主经回调问插件。同一个类型只能有一项,
2549
+ * 撤销后这种事件被忽略,消息回到原文。
2550
+ */
2551
+ 'registerMessageProjection': {
2552
+ kind: 'register';
2553
+ args: [eventType: string];
2554
+ output: void;
2555
+ callback: {
2556
+ input: MessageProjectionCall;
2557
+ output: Array<[number, JsonValue]>;
2558
+ };
2559
+ };
2560
+ };
2561
+ /**
2562
+ * agent 的生命周期(0.12 的 `ctx.agents`)。经这里拿到的 agent 不按空闲卸下,直到 `dispose` 或插件进程退出。`create`、
2563
+ * `resume` 的 `env` 给模型在这个会话里跑的命令加环境变量,随持有一起撤掉。要的模型路由没有时报 `llm/provider-unavailable`,
2564
+ * `details` 是 `{ provider, reason }`(`reason` 如 `signed-out`、`unreachable`,没说明时为 null)。
2565
+ */
2566
+ 'agents': {
2567
+ /** 建一个 agent,交出之前发 `agent/created`,监听者失败时不建。 */
2568
+ 'create': {
2569
+ kind: 'call';
2570
+ args: [options: CreateAgent];
2571
+ output: AgentRef;
2572
+ };
2573
+ /** 接手一个已有的会话;这个宿主进程里还没发过 `agent/created` 时在这里发,监听者失败时报错。 */
2574
+ 'resume': {
2575
+ kind: 'call';
2576
+ args: [options: ResumeAgent];
2577
+ output: AgentRef;
2578
+ };
2579
+ /** 放手:停下在跑的一轮(待处理的输入留着)、放手它持有的 agent,等它们停下;没人跟随时会话在下一次核对时(最长约 1 分钟)卸下。 */
2580
+ 'dispose': {
2581
+ kind: 'call';
2582
+ args: [sessionId: string];
2583
+ output: void;
2584
+ };
2585
+ /** 内存里全部的 agent,按建立的先后。 */
2586
+ 'list': {
2587
+ kind: 'call';
2588
+ args: [];
2589
+ output: Array<AgentRef>;
2590
+ };
2591
+ /** 没有持有者的 agent(子 agent 与插件建的带持有者的除外)。 */
2592
+ 'roots': {
2593
+ kind: 'call';
2594
+ args: [];
2595
+ output: Array<AgentRef>;
2596
+ };
2597
+ /** `owner` 是这个 agent 的直接持有者。 */
2598
+ 'isOwnedBy': {
2599
+ kind: 'call';
2600
+ args: [sessionId: string, owner: string];
2601
+ output: boolean;
2602
+ };
2603
+ };
2604
+ /** 驱动一个 agent(0.12 的 `Agent` 上的方法):SDK 包在 agent 的句柄上。子 agent 的会话拒绝写入。 */
2605
+ 'turn': {
2606
+ /** 把消息放进收件箱的一张清单,`wakeup` 时唤醒驱动(这一轮已经取消时插话改排队)。 */
2607
+ 'send': {
2608
+ kind: 'call';
2609
+ args: [sessionId: string, message: UserMessage, target: InboxTarget, wakeup: boolean];
2610
+ output: void;
2611
+ };
2612
+ /** 取消在跑的这一轮或维护任务;不留待处理的输入时先清空它们。没有在跑时只清空。 */
2613
+ 'cancel': {
2614
+ kind: 'call';
2615
+ args: [sessionId: string, cause: AgentCancelCause, options: CancelOptions | null];
2616
+ output: void;
2617
+ };
2618
+ 'status': {
2619
+ kind: 'call';
2620
+ args: [sessionId: string];
2621
+ output: AgentStatus;
2622
+ };
2623
+ /** 等到没有驱动与维护任务在跑,也没有接着要跑的。 */
2624
+ 'whenIdle': {
2625
+ kind: 'call';
2626
+ args: [sessionId: string];
2627
+ output: void;
2628
+ };
2629
+ /** 这个 agent 此刻的请求配置。 */
2630
+ 'options': {
2631
+ kind: 'call';
2632
+ args: [sessionId: string];
2633
+ output: AgentOptions;
2634
+ };
2635
+ 'inbox': {
2636
+ kind: 'call';
2637
+ args: [sessionId: string];
2638
+ output: InboxState;
2639
+ };
2640
+ /** 同数组的 splice:负的 `start` 从末尾算,返回删掉的消息;删掉的记作丢弃。 */
2641
+ 'spliceInbox': {
2642
+ kind: 'call';
2643
+ args: [sessionId: string, target: InboxTarget, start: number, deleteCount: number, inserted: Array<UserMessage>];
2644
+ output: Array<JsonValue>;
2645
+ };
2646
+ /** 撤下一条(记作丢弃),返回它是否还在。 */
2647
+ 'removeFromInbox': {
2648
+ kind: 'call';
2649
+ args: [sessionId: string, messageId: string];
2650
+ output: boolean;
2651
+ };
2652
+ /** 原地换掉一条,返回它是否还在。 */
2653
+ 'replaceInInbox': {
2654
+ kind: 'call';
2655
+ args: [sessionId: string, messageId: string, message: UserMessage];
2656
+ output: boolean;
2657
+ };
2658
+ /** 丢弃全部待处理的输入,先插话后排队。 */
2659
+ 'clearInbox': {
2660
+ kind: 'call';
2661
+ args: [sessionId: string];
2662
+ output: void;
2663
+ };
2664
+ /**
2665
+ * 占住空闲的 agent 做维护(0.12 的 `runMaintenance`):先给一条 `started`;`agent.cancel` 时再给一条 `cancelled`。丢掉流(插件
2666
+ * 做完、取消或插件进程退出)即放开,期间的发送排进队列,放开后接着跑。不空闲时报 `agent/busy`。
2667
+ */
2668
+ 'maintain': {
2669
+ kind: 'stream';
2670
+ args: [sessionId: string];
2671
+ output: MaintenanceSignal;
2672
+ };
2673
+ };
2674
+ /** 新对话的默认模型(0.12 的 `ctx.agentDefaultModel`)。 */
2675
+ 'agentDefaultModel': {
2676
+ /** 当前的默认模型;没有时为 null。 */
2677
+ 'currentSelection': {
2678
+ kind: 'call';
2679
+ args: [];
2680
+ output: DefaultModelSelection | null;
2681
+ };
2682
+ /** 改默认模型,新对话从此用它;模型不可用时报错。 */
2683
+ 'saveSelection': {
2684
+ kind: 'call';
2685
+ args: [selection: DefaultModelSelection];
2686
+ output: void;
2687
+ };
2688
+ };
2689
+ /** 文件(0.12 的 `ctx.fs`):与文件工具同一套路径解析与写入。不是权限边界(TS 插件进程本来就能读写本机文件)。 */
2690
+ 'fs': {
2691
+ /** 解析路径;相对路径按 `cwd`,不给时用宿主的默认目录。不存在的路径也能定位。 */
2692
+ 'resolve': {
2693
+ kind: 'call';
2694
+ args: [path: string, cwd: string | null];
2695
+ output: FsResolved;
2696
+ };
2697
+ /** 元数据;不存在时为 null。 */
2698
+ 'stat': {
2699
+ kind: 'call';
2700
+ args: [target: FsTarget];
2701
+ output: FsInfo | null;
2702
+ };
2703
+ /** 读出整份文件,字节按 base64;超过 `maxBytes` 报 `FS_TOO_LARGE`。 */
2704
+ 'readBytes': {
2705
+ kind: 'call';
2706
+ args: [target: FsTarget, maxBytes: number];
2707
+ output: string;
2708
+ };
2709
+ /**
2710
+ * 写入整份二进制(字节按 base64):`execution`(工具调用的 token)给出时先跑 `fs/write-intent`,本轮改动记录据此
2711
+ * 存下原文件,沙箱按这次调用;调用已经结束或 token 不对时拒绝。不给时是插件自己的写入,按部署默认的模式围住。写入条件只看
2712
+ * `expected`(不给即无条件),不用瀑布的结论。
2713
+ * 在目标目录里原子发布,沿用原文件的权限,缺的父目录一并建。
2714
+ */
2715
+ 'writeBytes': {
2716
+ kind: 'call';
2717
+ args: [target: FsTarget, data: string, execution: string | null, expected: FsWriteIntent | null];
2718
+ output: FsWritten;
2719
+ };
2720
+ /** 路径本身的元数据,不跟随最后一段的符号链接;不存在时为 null。相对路径的规则同 `resolve`。 */
2721
+ 'lstat': {
2722
+ kind: 'call';
2723
+ args: [path: string, cwd: string | null];
2724
+ output: FsPathInfo | null;
2725
+ };
2726
+ /** 读出整份 UTF-8 文本:开头的 BOM 去掉,二进制或不是合法 UTF-8 报 `FS_NOT_TEXT`,超过 10 MiB 报 `FS_TOO_LARGE`。 */
2727
+ 'readText': {
2728
+ kind: 'call';
2729
+ args: [target: FsTarget];
2730
+ output: string;
2731
+ };
2732
+ /**
2733
+ * 从字节偏移 `offset` 读一块文本,判断规则同 `readText`,没有大小上限:SDK 的 `streamText` 逐块调用,调用方不要下一块时
2734
+ * 宿主不多读。不完整的 UTF-8 留给下一块。
2735
+ */
2736
+ 'readTextChunk': {
2737
+ kind: 'call';
2738
+ args: [target: FsTarget, offset: number];
2739
+ output: FsTextChunk;
2740
+ };
2741
+ /** 按偏移读一段原始字节(base64):文件在这一段里结束时短一些,`offset` 在文件末尾之后时为空。`length` 超过 10 MiB 报 `FS_TOO_LARGE`。 */
2742
+ 'readByteRange': {
2743
+ kind: 'call';
2744
+ args: [target: FsTarget, offset: number, length: number];
2745
+ output: string;
2746
+ };
2747
+ /** 列目录的直接子项,不读内容,不保证顺序(SDK 按名字排)。超过 10000 项报 `FS_TOO_LARGE`。 */
2748
+ 'listDir': {
2749
+ kind: 'call';
2750
+ args: [target: FsTarget];
2751
+ output: Array<FsDirEntry>;
2752
+ };
2753
+ /**
2754
+ * 按字面替换编辑。`execution`(工具调用的 token)给出时先跑 `fs/edit-intent`、核对它的结论,沙箱按这次调用,改完发
2755
+ * `fs/observed`;调用已经结束或 token 不对时拒绝。不给时是插件自己的改动,不问瀑布,按部署默认的模式围住(同 `sandboxPolicy.resolve()` 不给会话时)。
2756
+ * `expected` 是调用方要求的版本,与瀑布的结论都要满足。
2757
+ */
2758
+ 'editText': {
2759
+ kind: 'call';
2760
+ args: [target: FsTarget, edit: FsEditRequest, execution: string | null, expected: string | null];
2761
+ output: FsEditOutcome;
2762
+ };
2763
+ };
2764
+ /** 监听文件变化(SDK 的 `ctx.fs.watch`)。不是单独的 `ctx` 服务:实现在文件插件里,不属于 Agent 核心的文件服务。 */
2765
+ 'fsWatch': {
2766
+ /**
2767
+ * 监听一个绝对路径:文件只报它自己,目录报直接子项,不存在的路径等它出现。先给一条 `ready`,200ms 内的变化合并成一条
2768
+ * `changed`。丢掉流即停止。
2769
+ */
2770
+ 'watch': {
2771
+ kind: 'stream';
2772
+ args: [path: string];
2773
+ output: FsWatchFrame;
2774
+ };
2775
+ };
2776
+ /** 附件(0.12 的 `ctx.attachments`)。 */
2777
+ 'attachments': {
2778
+ /** 图片准入的上限。宿主里是常量。 */
2779
+ 'imageLimits': {
2780
+ kind: 'call';
2781
+ args: [];
2782
+ output: ImageAttachmentLimits;
2783
+ };
2784
+ /** 只校验一张图片,不存(0.12 的 `validateImage`):准入与规范化同 `saveImage`。 */
2785
+ 'validateImage': {
2786
+ kind: 'call';
2787
+ args: [image: ImageUpload];
2788
+ output: void;
2789
+ };
2790
+ /** 存一批图片,同 0.12 的 `saveImages`:先整批检查,全部准入、规范化通过才写入;结论与输入同序。 */
2791
+ 'saveImages': {
2792
+ kind: 'call';
2793
+ args: [images: Array<ImageUpload>];
2794
+ output: Array<ImageRef>;
2795
+ };
2796
+ /** 存一张图片(0.12 的 `saveImage`):不做整批的检查。 */
2797
+ 'saveImage': {
2798
+ kind: 'call';
2799
+ args: [image: ImageUpload];
2800
+ output: ImageRef;
2801
+ };
2802
+ /** 读出一张图片并核对(base64):摘要、格式、尺寸与字节数都与引用一致。 */
2803
+ 'readImage': {
2804
+ kind: 'call';
2805
+ args: [image: ImageRef];
2806
+ output: string;
2807
+ };
2808
+ /** 图片对象在宿主上的绝对路径,不读对象。 */
2809
+ 'imageHostPath': {
2810
+ kind: 'call';
2811
+ args: [image: ImageRef];
2812
+ output: string;
2813
+ };
2814
+ /** 一张图片按 `target` 的请求版本(0.12 的 `readImageRequest`),与模型请求共用缓存。 */
2815
+ 'readImageRequest': {
2816
+ kind: 'call';
2817
+ args: [image: ImageRef, target: ImageRequestTarget];
2818
+ output: RequestImageVersion;
2819
+ };
2820
+ /** 原样存下一个文件(0.12 的 `saveFile`、`admitEncodedFile`),不限大小。 */
2821
+ 'saveFile': {
2822
+ kind: 'call';
2823
+ args: [file: FileUpload];
2824
+ output: FileRef;
2825
+ };
2826
+ /**
2827
+ * 分块上传一个文件(SDK 的 `saveFileStream`):先给一条 `started` 带上传编号,之后 `appendFile` 逐块追加、`finishFile` 结束,
2828
+ * 存好后给一条 `saved`。流被丢掉(插件中止、插件进程退出)或两块之间超过 5 分钟没有新块时上传失败,暂存文件删除,不留下半个附件。
2829
+ */
2830
+ 'uploadFile': {
2831
+ kind: 'stream';
2832
+ args: [name: string | null];
2833
+ output: FileUploadFrame;
2834
+ };
2835
+ /** 追加一块(base64)。宿主写不过来时等。 */
2836
+ 'appendFile': {
2837
+ kind: 'call';
2838
+ args: [upload: string, data: string];
2839
+ output: void;
2840
+ };
2841
+ /** 不再有新块;结果由 `uploadFile` 的流给出。 */
2842
+ 'finishFile': {
2843
+ kind: 'call';
2844
+ args: [upload: string];
2845
+ output: void;
2846
+ };
2847
+ /** 从 `offset` 读一块存下的文件(最多 64 KiB,base64),读完时为空。SDK 的 `readFileStream` 逐块调用并核对摘要。 */
2848
+ 'readFileChunk': {
2849
+ kind: 'call';
2850
+ args: [file: FileRef, offset: number];
2851
+ output: string;
2852
+ };
2853
+ /** 文件在宿主上的绝对路径(以文件名结尾),不读对象。 */
2854
+ 'fileHostPath': {
2855
+ kind: 'call';
2856
+ args: [file: FileRef];
2857
+ output: string;
2858
+ };
2859
+ };
2860
+ /** 模型(0.12 的 `ctx.llm`):注册模型路由、按 id 取模型信息、插件直接调用模型。 */
2861
+ 'llm': {
2862
+ /**
2863
+ * 注册一条路由(0.12 的 `registerAdapter`):一个 provider 与它的模型清单,每次请求经回调向插件取地址与凭据,回调的载荷是
2864
+ * provider 名。清单变了就撤销旧的注册、再注册一次。
2865
+ */
2866
+ 'registerRoute': {
2867
+ kind: 'register';
2868
+ args: [route: RouteDeclaration];
2869
+ output: void;
2870
+ callback: {
2871
+ input: string;
2872
+ output: RouteCredentials;
2873
+ };
2874
+ };
2875
+ /**
2876
+ * 注册自带流式实现的路由(0.12 的 `registerAdapter`):插件自己发 HTTP,回调逐块给出 v4 的 StreamChunk,宿主核对形状。
2877
+ * `token` 是插件进程生成的,`replaceAdapterRoutes` 据此找到这项注册。
2878
+ */
2879
+ 'registerAdapter': {
2880
+ kind: 'register';
2881
+ args: [token: string, routes: Array<RouteDeclaration>];
2882
+ output: void;
2883
+ callback: {
2884
+ input: LlmStreamRequest;
2885
+ output: JsonValue;
2886
+ };
2887
+ };
2888
+ /**
2889
+ * 整体替换这项注册的路由,适配器不变:校验不过(`DUPLICATE_ADAPTER`、`INVALID_ADAPTER`)时原样不动,注册已撤销时报
2890
+ * `REGISTRATION_DISPOSED`。
2891
+ */
2892
+ 'replaceAdapterRoutes': {
2893
+ kind: 'call';
2894
+ args: [token: string, routes: Array<RouteDeclaration>];
2895
+ output: void;
2896
+ };
2897
+ /** 注册了的路由,按模型目录的顺序。后台服务刚启动、账号的模型清单还在第一次加载时先等它,最多 10 秒。 */
2898
+ 'listProviders': {
2899
+ kind: 'call';
2900
+ args: [];
2901
+ output: Array<LlmProviderInfo>;
2902
+ };
2903
+ /** 一条路由的模型,藏起来的不列;没有这个 provider 报 `NO_ADAPTER`。路由还没有、第一次加载还没完时先等,同 `listProviders`。 */
2904
+ 'listModels': {
2905
+ kind: 'call';
2906
+ args: [provider: string];
2907
+ output: Array<LlmModelInfo>;
2908
+ };
2909
+ /** 声明可以经配置启用的 provider,随注册撤销。空的、字段不对报 `INVALID_DIRECTORY`,已被声明报 `DUPLICATE_DIRECTORY`。 */
2910
+ 'registerConfigurableProviders': {
2911
+ kind: 'register';
2912
+ args: [token: string, entries: Array<LlmConfigurableProvider>];
2913
+ output: void;
2914
+ };
2915
+ /** 整体替换这项声明;校验不过时原样不动,可以换成空的。 */
2916
+ 'replaceConfigurableProviders': {
2917
+ kind: 'call';
2918
+ args: [token: string, entries: Array<LlmConfigurableProvider>];
2919
+ output: void;
2920
+ };
2921
+ /** 声明了的 provider,按声明的顺序。 */
2922
+ 'listConfigurableProviders': {
2923
+ kind: 'call';
2924
+ args: [];
2925
+ output: Array<LlmConfigurableProvider>;
2926
+ };
2927
+ /** 按设置命名空间注册模型发现,回调问一个端点;同一命名空间已注册报 `DUPLICATE_DISCOVERY`。 */
2928
+ 'registerModelDiscovery': {
2929
+ kind: 'register';
2930
+ args: [settingsNs: string];
2931
+ output: void;
2932
+ callback: {
2933
+ input: LlmModelDiscoveryRequest;
2934
+ output: Array<LlmDiscoveredModel>;
2935
+ };
2936
+ };
2937
+ /** 问一个草稿端点有哪些模型,结果按 id 去重。没有注册报 `NO_DISCOVERY`,`provider` 与 `baseURL` 都没有报 `INVALID_DISCOVERY`。 */
2938
+ 'discoverModels': {
2939
+ kind: 'call';
2940
+ args: [settingsNs: string, request: LlmModelDiscoveryRequest];
2941
+ output: Array<LlmDiscoveredModel>;
2942
+ };
2943
+ /** 路由的重试策略;没有这个 provider 报 `NO_ADAPTER`。 */
2944
+ 'providerRetryPolicy': {
2945
+ kind: 'call';
2946
+ args: [provider: string];
2947
+ output: ResolvedRetryPolicy;
2948
+ };
2949
+ /** 路由给这个模型声明的图片定价;没有这条路由或没有声明时为 null。 */
2950
+ 'imageRequestPricing': {
2951
+ kind: 'call';
2952
+ args: [provider: string, model: string];
2953
+ output: LlmImageRequestPricing | null;
2954
+ };
2955
+ /** 文件附件进请求时的文本,与派发时用的相同。 */
2956
+ 'fileRequestText': {
2957
+ kind: 'call';
2958
+ args: [file: FileRef];
2959
+ output: string;
2960
+ };
2961
+ /** 按模型校验配置、补上路由的默认值(输出上限、推理档位),与 `stream` 共用同一份规则。 */
2962
+ 'resolveCallConfig': {
2963
+ kind: 'call';
2964
+ args: [config: LlmCallConfig];
2965
+ output: LlmCallConfig;
2966
+ };
2967
+ /** `prepareCall` 的第一步:钉住路由的注册快照。句柄是一个 id,不带凭据。 */
2968
+ 'bindCall': {
2969
+ kind: 'call';
2970
+ args: [provider: string, model: string];
2971
+ output: BoundCall;
2972
+ };
2973
+ /** `prepareCall` 的第二步:按钉住的快照校验配置、补上默认值。 */
2974
+ 'configureBoundCall': {
2975
+ kind: 'call';
2976
+ args: [id: string, config: LlmCallConfig];
2977
+ output: PreparedCallInfo;
2978
+ };
2979
+ /** 经钉住的快照派发一次,只能一次:凭据这时才向注册方取。配置对不上或句柄失效时唯一的一块是 `INVALID_PREPARED_CALL` 的 finish。 */
2980
+ 'streamPrepared': {
2981
+ kind: 'stream';
2982
+ args: [id: string, request: GenerateRequest];
2983
+ output: JsonValue;
2984
+ };
2985
+ /** 按 id 取模型信息:没有这个 provider 报 `NO_ADAPTER`,有 provider 没有这个模型报 `UNKNOWN_MODEL`。 */
2986
+ 'resolveModelInfo': {
2987
+ kind: 'call';
2988
+ args: [provider: string, model: string];
2989
+ output: LlmModelInfo;
2990
+ };
2991
+ /**
2992
+ * 直接调用模型:逐条给出会话格式 v4 的 StreamChunk,最后两条是 usage 与 finish;失败也是 finish(`reason.kind` 为
2993
+ * `error`,带 `failure.code`)。不重试。
2994
+ */
2995
+ 'stream': {
2996
+ kind: 'stream';
2997
+ args: [request: GenerateRequest];
2998
+ output: JsonValue;
2999
+ };
3000
+ };
3001
+ /** 审批(0.12 的 `ctx.approval`):读与切换会话的审批策略,工具执行中途申请批准。 */
3002
+ 'approval': {
3003
+ /** 部署默认的审批策略。 */
3004
+ 'config': {
3005
+ kind: 'call';
3006
+ args: [];
3007
+ output: ApprovalConfig;
3008
+ };
3009
+ /** 会话记下的审批策略,不套默认;没有记录时为 null。没有这个会话报 `agent/session-not-found`。 */
3010
+ 'overrideOf': {
3011
+ kind: 'call';
3012
+ args: [sessionId: string];
3013
+ output: ApprovalPolicy | null;
3014
+ };
3015
+ /**
3016
+ * 切换会话的审批策略,给模型一条通知,排进下一步、不唤醒。与生效的策略相同时不写。要声明 `permissions.set`。记下调用方插件;
3017
+ * 子 agent 的会话报 `agent/subagent-session`。
3018
+ */
3019
+ 'setPolicy': {
3020
+ kind: 'call';
3021
+ args: [sessionId: string, policy: ApprovalPolicy];
3022
+ output: void;
3023
+ };
3024
+ /**
3025
+ * 为 `execution`(进行中的工具调用的 token)申请一次批准,记下 `approval/asked` 与 `approval/decided`。
3026
+ * `reason` 记在 asked 里,`displayReason` 只给界面(`{en, zh-CN, …}`)。审批策略是 never 或「替我审批」的会话直接拒绝、
3027
+ * 不弹卡;其余经 `approval/request` 作答,没有应答时是 `unavailable`;这一轮被取消时是 `cancelled`。调用已经结束或 token 不对时报错。
3028
+ */
3029
+ 'request': {
3030
+ kind: 'call';
3031
+ args: [execution: string, reason: string | null, displayReason: JsonValue | null];
3032
+ output: ApprovalOutcome;
3033
+ };
3034
+ };
3035
+ /**
3036
+ * 会话的工作目录(0.12 的 `ctx.workingDirectory`),与界面切换目录同一条路径。可以操作任意会话。错误码同界面:会话不存在或写不了
3037
+ * 时 `ftai-sessions/not-live`,目录不对时 `ftai-sessions/invalid-directory`。
3038
+ */
3039
+ 'workingDirectory': {
3040
+ /** 当前目录,不做 IO。 */
3041
+ 'get': {
3042
+ kind: 'call';
3043
+ args: [sessionId: string];
3044
+ output: string;
3045
+ };
3046
+ /** 确认当前目录还在并返回它;不在了时退回会话的项目目录并告诉模型。 */
3047
+ 'ensure': {
3048
+ kind: 'call';
3049
+ args: [sessionId: string];
3050
+ output: string;
3051
+ };
3052
+ /** 换目录,返回真实路径:相对路径按当前目录解析,必须是已有的目录。写进会话并告诉模型,已经在跑的命令留在原来的目录。 */
3053
+ 'set': {
3054
+ kind: 'call';
3055
+ args: [sessionId: string, path: string];
3056
+ output: string;
3057
+ };
3058
+ /** 没有指定目录的会话用的默认目录。 */
3059
+ 'defaultDirectory': {
3060
+ kind: 'call';
3061
+ args: [];
3062
+ output: string;
3063
+ };
3064
+ };
3065
+ /** 工作区登记(0.12 的 `ctx.workspaceRegistry`),与界面同一份登记、同一条路径。 */
3066
+ 'workspaceRegistry': {
3067
+ /**
3068
+ * 为已有的目录登记工作区,或取回已登记的同一目录(按真实路径)。`title` 只在新建时用,不给时取目录名。路径不对时报
3069
+ * `workspace/invalid-path`。
3070
+ */
3071
+ 'create': {
3072
+ kind: 'call';
3073
+ args: [path: string, title: string | null];
3074
+ output: Workspace;
3075
+ };
3076
+ 'get': {
3077
+ kind: 'call';
3078
+ args: [id: string];
3079
+ output: Workspace | null;
3080
+ };
3081
+ /** 按显示顺序。 */
3082
+ 'list': {
3083
+ kind: 'call';
3084
+ args: [];
3085
+ output: Array<Workspace>;
3086
+ };
3087
+ /** 撤销登记,目录与会话日志都不动;不认识的 id 返回 false。 */
3088
+ 'delete': {
3089
+ kind: 'call';
3090
+ args: [id: string];
3091
+ output: boolean;
3092
+ };
3093
+ /**
3094
+ * 在显示顺序里移动:给了锚点就放到它前面,不给就放到最后。返回整个顺序。没有这个工作区或锚点时报 `workspace/order-invalid`,
3095
+ * 说明就是那个 id。
3096
+ */
3097
+ 'insertBefore': {
3098
+ kind: 'call';
3099
+ args: [id: string, before: string | null];
3100
+ output: Array<string>;
3101
+ };
3102
+ /**
3103
+ * 归档,同时取消置顶:不带 `stopActivity` 时先问 `workspace/session-activity`,有工作就什么都不写、返回这些工作;带上时先写
3104
+ * 归档,再发 `workspace/session-stop`。已归档的直接返回空。没有这个会话时报 `session/not-found`。
3105
+ */
3106
+ 'archiveSession': {
3107
+ kind: 'call';
3108
+ args: [sessionId: string, stopActivity: boolean];
3109
+ output: Array<SessionActivity>;
3110
+ };
3111
+ 'unarchiveSession': {
3112
+ kind: 'call';
3113
+ args: [sessionId: string];
3114
+ output: void;
3115
+ };
3116
+ /** 置顶,排到最前。已归档的报 `workspace/session-archived`,没有这个会话时报 `session/not-found`。 */
3117
+ 'pinSession': {
3118
+ kind: 'call';
3119
+ args: [sessionId: string];
3120
+ output: void;
3121
+ };
3122
+ 'unpinSession': {
3123
+ kind: 'call';
3124
+ args: [sessionId: string];
3125
+ output: void;
3126
+ };
3127
+ /** 按真实路径找工作区;路径不存在时报 `workspace/invalid-path`,目录没有登记时为 null。不写登记。 */
3128
+ 'resolveByPath': {
3129
+ kind: 'call';
3130
+ args: [path: string];
3131
+ output: Workspace | null;
3132
+ };
3133
+ /** 归档集,按归档的先后。 */
3134
+ 'archivedSessionIds': {
3135
+ kind: 'call';
3136
+ args: [];
3137
+ output: Array<string>;
3138
+ };
3139
+ /** 置顶集,最近置顶的在前。 */
3140
+ 'pinnedSessionIds': {
3141
+ kind: 'call';
3142
+ args: [];
3143
+ output: Array<string>;
3144
+ };
3145
+ };
3146
+ /** 会话的 Goal(0.12 的 `ctx.goals`),与界面同一条路径。错误码同 0.12 的 `GoalErrorCode`。可以操作任意会话,只有 `create` 拒绝子 agent 的会话。 */
3147
+ 'goals': {
3148
+ /** 当前的 Goal;没有 Goal 或没有这个会话时为 null。 */
3149
+ 'get': {
3150
+ kind: 'call';
3151
+ args: [sessionId: string];
3152
+ output: GoalView | null;
3153
+ };
3154
+ /** 创建并激活,会话空闲时随即开始第一轮(同界面)。已完成的 Goal 可以被取代,其余阶段的报 `GOAL_ALREADY_EXISTS`。 */
3155
+ 'create': {
3156
+ kind: 'call';
3157
+ args: [sessionId: string, request: GoalCreateRequest];
3158
+ output: GoalView;
3159
+ };
3160
+ /** 改目标和(或)轮数上限,阶段不变;激活着的 Goal 随即接着排轮次。 */
3161
+ 'edit': {
3162
+ kind: 'call';
3163
+ args: [sessionId: string, at: GoalRef, request: GoalEditRequest];
3164
+ output: GoalView;
3165
+ };
3166
+ /** 暂停并解除激活,停下正在跑的这一轮(不论是不是 Goal 的一轮,同界面)。 */
3167
+ 'pause': {
3168
+ kind: 'call';
3169
+ args: [sessionId: string, at: GoalRef];
3170
+ output: GoalView;
3171
+ };
3172
+ /** 继续暂停或受阻的 Goal,或重新激活进行中但未激活的,会话空闲时随即开始下一轮。 */
3173
+ 'resume': {
3174
+ kind: 'call';
3175
+ args: [sessionId: string, at: GoalRef];
3176
+ output: GoalView;
3177
+ };
3178
+ /** 标记完成并解除激活,不停下正在跑的这一轮。 */
3179
+ 'complete': {
3180
+ kind: 'call';
3181
+ args: [sessionId: string, at: GoalRef];
3182
+ output: GoalView;
3183
+ };
3184
+ /** 标记受阻并解除激活,不停下正在跑的这一轮。 */
3185
+ 'block': {
3186
+ kind: 'call';
3187
+ args: [sessionId: string, at: GoalRef, reason: GoalBlockReason];
3188
+ output: GoalView;
3189
+ };
3190
+ /** 清除并解除激活,不停下正在跑的这一轮。返回清除的标记,修订号比清除的那个大一。 */
3191
+ 'clear': {
3192
+ kind: 'call';
3193
+ args: [sessionId: string, at: GoalRef];
3194
+ output: GoalRef;
3195
+ };
3196
+ /** 只解除激活,不改阶段与修订,排着的一轮撤下。没有当前的 Goal 时为 null。 */
3197
+ 'disarm': {
3198
+ kind: 'call';
3199
+ args: [sessionId: string];
3200
+ output: GoalView | null;
3201
+ };
3202
+ };
3203
+ /**
3204
+ * 已安排的任务(0.12 的 `ctx.schedule`),与界面同一条路径。任务是宿主级的:可以往任意会话排任务,`catalog` 能看全部会话的。
3205
+ * 请求与结果按 JSON 传,类型在 SDK 里,由定时插件的边界类型生成。输入不合规时错误码同 0.12 的 `ScheduleInputError`。
3206
+ */
3207
+ 'schedule': {
3208
+ /** 建一个绑定到会话的任务,不打开会话。 */
3209
+ 'create': {
3210
+ kind: 'call';
3211
+ args: [sessionId: string, request: JsonValue];
3212
+ output: JsonValue;
3213
+ };
3214
+ /** 会话里进行中的任务,按存储顺序。 */
3215
+ 'list': {
3216
+ kind: 'call';
3217
+ args: [sessionId: string];
3218
+ output: JsonValue;
3219
+ };
3220
+ /** 全部任务(各种状态)连同绑定的会话。 */
3221
+ 'catalog': {
3222
+ kind: 'call';
3223
+ args: [];
3224
+ output: JsonValue;
3225
+ };
3226
+ /** 发送记录的一页,从新到旧。 */
3227
+ 'history': {
3228
+ kind: 'call';
3229
+ args: [request: JsonValue];
3230
+ output: JsonValue;
3231
+ };
3232
+ /** 删除一个任务,已经排进会话的消息不动。 */
3233
+ 'delete': {
3234
+ kind: 'call';
3235
+ args: [request: JsonValue];
3236
+ output: JsonValue;
3237
+ };
3238
+ /** 先核对再修改:给出的名字、指令与时间替换原来的。 */
3239
+ 'update': {
3240
+ kind: 'call';
3241
+ args: [request: JsonValue];
3242
+ output: JsonValue;
3243
+ };
3244
+ };
3245
+ /**
3246
+ * 上下文压缩(0.12 的 `ctx.compaction`)。调用方中止时压缩收到取消,照常写下带错误的 `compaction/end`。失败的错误码是
3247
+ * `compaction/busy`、`compaction/cancelled`、`compaction/changed`、`compaction/summary`、`compaction/commit`。
3248
+ */
3249
+ 'compaction': {
3250
+ /**
3251
+ * 会话空闲时压缩一次,阈值以下也压(同手动压缩):期间的发送排进队列,结束后接着跑。没有可压的历史时为 null。
3252
+ * `sourceCommandId` 记进压缩事件;这里不写命令事件。
3253
+ */
3254
+ 'compactNow': {
3255
+ kind: 'call';
3256
+ args: [sessionId: string, sourceCommandId: string | null];
3257
+ output: CompactionResult | null;
3258
+ };
3259
+ /** 按触发原因判断要不要压缩(同每步开始前的压力与超窗恢复),没有压缩时为 null。真的要摘要时要在进行中的一轮里。 */
3260
+ 'compactIfNeeded': {
3261
+ kind: 'call';
3262
+ args: [sessionId: string, trigger: CompactionTrigger];
3263
+ output: CompactionResult | null;
3264
+ };
3265
+ };
3266
+ /** 子 agent(0.12 的 `ctx.subagents`):与委派工具同一条路径,深度、并发上限、权限与审批都一样。提供者固定为 `spawn`、`fork`。 */
3267
+ 'subagents': {
3268
+ /** 提供者的名字。 */
3269
+ 'list': {
3270
+ kind: 'call';
3271
+ args: [];
3272
+ output: Array<string>;
3273
+ };
3274
+ /**
3275
+ * 在任意父会话下起一个子 agent:先给一条 `started`,子 agent 结算时给 `settled`,之后流结束。丢掉流不影响子 agent。
3276
+ * 失败码:`NO_PROVIDER`、`DUPLICATE_CHILD`、`ACTIVATION_LIMIT_REACHED`、`ACTIVATION_CLOSING`、`SUBAGENT_DEPTH`、
3277
+ * `agent/session-not-found`、`agent/session-archived`。
3278
+ */
3279
+ 'startActivation': {
3280
+ kind: 'stream';
3281
+ args: [spec: SubagentActivationRequest];
3282
+ output: SubagentActivationFrame;
3283
+ };
3284
+ /** 停下并放开这一段常驻(0.12 的 `activation.dispose`):`runId` 对不上(已经结算、后来又续上了)时什么也不做。结算之后才答复。 */
3285
+ 'disposeActivation': {
3286
+ kind: 'call';
3287
+ args: [childId: string, runId: string];
3288
+ output: void;
3289
+ };
3290
+ /**
3291
+ * 发消息给直接的子 agent(不常驻时按描述符冷恢复),或常驻的子 agent 发给直接的父 agent。返回消息 id。
3292
+ * 失败码:`UNAUTHORIZED`、`NOT_RESUMABLE`、`PARENT_UNAVAILABLE`、`ACTIVATION_LIMIT_REACHED`、`ACTIVATION_CLOSING`。
3293
+ */
3294
+ 'sendMessage': {
3295
+ kind: 'call';
3296
+ args: [sender: string, target: string, content: Array<UserContent>];
3297
+ output: string;
3298
+ };
3299
+ /** 打断一个常驻的子 agent 当前的这一轮:队列留着,它的子 agent 继续跑;不常驻时什么也不做。权限不对时报 `UNAUTHORIZED`。 */
3300
+ 'interrupt': {
3301
+ kind: 'call';
3302
+ args: [target: string, authority: SubagentInterruptAuthority];
3303
+ output: void;
3304
+ };
3305
+ /** 这个会话记下的直接的子 agent,按记下的先后,不含分叉继承的。没有这个会话时报 `agent/session-not-found`。 */
3306
+ 'listChildren': {
3307
+ kind: 'call';
3308
+ args: [parent: string];
3309
+ output: Array<SubagentCatalogEntry>;
3310
+ };
3311
+ /** 这个会话下面整棵树,前序。读不出来的分支给一行 `diagnostic`。没有这个会话时报 `agent/session-not-found`。 */
3312
+ 'listDescendants': {
3313
+ kind: 'call';
3314
+ args: [root: string];
3315
+ output: Array<SubagentDescendantEntry>;
3316
+ };
3317
+ /** 等这个会话下面在进展的子孙停下,不取消它们;停着等下一次唤醒的不等。结论是有没有等过。 */
3318
+ 'waitForChildren': {
3319
+ kind: 'call';
3320
+ args: [parent: string];
3321
+ output: boolean;
3322
+ };
3323
+ };
3324
+ /**
3325
+ * 后台任务(0.12 的 `ctx.jobs`)。工作跑在插件进程里,宿主登记任务、发控制信号;`caller` 是读取方的会话,同 0.12:归属会话的
3326
+ * 任务只有那个会话读得到,不给 `caller` 时只看得到不归属会话的。
3327
+ */
3328
+ 'jobs': {
3329
+ /**
3330
+ * 留下一个任务:先给一条 `started` 带 id,`commit` 之后才可见;之后每次有人要它停下给一条 `cancel`,任务结束时流结束。
3331
+ * `commit` 之前丢掉流时什么也不留;之后丢掉流(插件进程退出)时任务按失败结束。每个插件同时最多 10 个,超出时报
3332
+ * `job/limit-reached`;归属的会话不存在时报 `agent/session-not-found`。
3333
+ */
3334
+ 'start': {
3335
+ kind: 'stream';
3336
+ args: [declaration: JobDeclaration];
3337
+ output: JobControl;
3338
+ };
3339
+ /**
3340
+ * 任务登记完成,从此可见;之前写下的输出与进度随之可见。只有开始它的插件能调用(`append`、`updateProgress`、`reportSpill`、
3341
+ * `finish` 同样),别的插件报 `job/not-producer`。
3342
+ */
3343
+ 'commit': {
3344
+ kind: 'call';
3345
+ args: [id: string];
3346
+ output: void;
3347
+ };
3348
+ /** 追加一段输出(空的丢掉)。结束之后的写入丢掉。到达即生效,不用等答复。 */
3349
+ 'append': {
3350
+ kind: 'call';
3351
+ args: [id: string, text: string, options: JobAppendOptions | null];
3352
+ output: void;
3353
+ };
3354
+ /** 换掉进度行。结束之后的写入丢掉。 */
3355
+ 'updateProgress': {
3356
+ kind: 'call';
3357
+ args: [id: string, line: string];
3358
+ output: void;
3359
+ };
3360
+ /** 每个输出来源现在存着完整输出的文件,按来源顺序,没有时为 null。 */
3361
+ 'reportSpill': {
3362
+ kind: 'call';
3363
+ args: [id: string, paths: Array<string | null>];
3364
+ output: void;
3365
+ };
3366
+ /** 给出结局。第一次算数,之后的忽略;不是终态报 `invalid_params`。 */
3367
+ 'finish': {
3368
+ kind: 'call';
3369
+ args: [id: string, outcome: JobOutcome];
3370
+ output: void;
3371
+ };
3372
+ /** 看得到的任务,按登记的先后。 */
3373
+ 'list': {
3374
+ kind: 'call';
3375
+ args: [caller: string | null];
3376
+ output: Array<JobView>;
3377
+ };
3378
+ /** 没有这个任务报 `job/not-found`,归属别的会话报 `job/foreign`(`read`、`readAt`、`kill`、`wait`、`remove` 同样)。 */
3379
+ 'get': {
3380
+ kind: 'call';
3381
+ args: [id: string, caller: string | null];
3382
+ output: JobView;
3383
+ };
3384
+ /** 消费式读取:给上次读到之后的,结束后第一次读取带上结果。 */
3385
+ 'read': {
3386
+ kind: 'call';
3387
+ args: [id: string, caller: string | null];
3388
+ output: JobRead;
3389
+ };
3390
+ /** 从字节偏移 `from` 读留着的输出,不影响消费式读取的位置。 */
3391
+ 'readAt': {
3392
+ kind: 'call';
3393
+ args: [id: string, from: number, caller: string | null];
3394
+ output: JobOutputRead;
3395
+ };
3396
+ /** 请求停下;结束后的状态说明带上 `reason`。 */
3397
+ 'kill': {
3398
+ kind: 'call';
3399
+ args: [id: string, caller: string | null, reason: string | null];
3400
+ output: KillOutcome;
3401
+ };
3402
+ /** 等到结束或过了 `timeoutMs`(到时任务照常在跑),返回那时的快照。 */
3403
+ 'wait': {
3404
+ kind: 'call';
3405
+ args: [id: string, timeoutMs: number, caller: string | null];
3406
+ output: JobView;
3407
+ };
3408
+ /** 移除一个已经结束的任务;还没结束时报 `job/still-running`。 */
3409
+ 'remove': {
3410
+ kind: 'call';
3411
+ args: [id: string, caller: string | null];
3412
+ output: void;
3413
+ };
3414
+ /** 任务的事件。`owner` 给出时只给这个会话的与不归属会话的任务。丢掉流即退订。 */
3415
+ 'events': {
3416
+ kind: 'stream';
3417
+ args: [owner: string | null];
3418
+ output: JobEvent;
3419
+ };
3420
+ };
3421
+ /** 向用户提问(0.12 的 `ctx.userQuestions`),与模型的 `ask_user_question` 同一条路:先过 `user-questions/request`,最后到界面的卡片。 */
3422
+ 'userQuestions': {
3423
+ /**
3424
+ * 提问并等回答,给出一条就结束。丢掉流(插件中止或插件进程退出)时提问撤回。错误码:`EMPTY_QUESTIONS`、`BAD_INTENT`、
3425
+ * `CALLER_NOT_LIVE`、`DELEGATED_CALLER`、`ASK_CANCELLED`(用户关掉了)、`NO_PROVIDER`(没有人应答)。
3426
+ */
3427
+ 'ask': {
3428
+ kind: 'stream';
3429
+ args: [request: AskUserQuestionRequestEvent];
3430
+ output: AskUserQuestionAnswer;
3431
+ };
3432
+ /** 回答一个正在等待的提问,界面的卡片撤回。这个提问不在等了时为 false;没有逐个回答每个问题时报 `BAD_ANSWER`。 */
3433
+ 'answer': {
3434
+ kind: 'call';
3435
+ args: [sessionId: string, callId: string, answer: AskUserQuestionAnswer];
3436
+ output: boolean;
3437
+ };
3438
+ };
3439
+ /** 抓取(0.12 的 `ctx.web.fetch`),与 `web_fetch` 工具同一套地址校验与上限;搜索在 `webSearch`。 */
3440
+ 'web': {
3441
+ /** 抓一个地址。非 2xx 也是结果;失败的错误码同 `web_fetch`(`WEB_*`)。 */
3442
+ 'fetch': {
3443
+ kind: 'call';
3444
+ args: [request: WebFetchRequest];
3445
+ output: WebFetchResult;
3446
+ };
3447
+ };
3448
+ /** 搜索(SDK 的 `ctx.web.search`)。不是单独的 `ctx` 服务:实现在搜索插件里,抓取在抓取插件里。 */
3449
+ 'webSearch': {
3450
+ /**
3451
+ * 用当前登录的 FtAi 账号搜一次,消耗用户的额度,与 `web_search` 工具相同。没有登录时报 `WEB_PROVIDER_CREDENTIAL_MISSING`,其余失败报
3452
+ * `WEB_PROVIDER_ERROR`。
3453
+ */
3454
+ 'search': {
3455
+ kind: 'call';
3456
+ args: [request: WebSearchRequest];
3457
+ output: WebSearchResult;
3458
+ };
3459
+ };
3460
+ /** Skill(0.12 的 `ctx.skills`):与模型看到的同一份,受用户的开关管。`cwd` 不给时没有项目里的。 */
3461
+ 'skills': {
3462
+ /** 生效的 Skill,按名字排好。 */
3463
+ 'list': {
3464
+ kind: 'call';
3465
+ args: [cwd: string | null];
3466
+ output: Array<SkillSummary>;
3467
+ };
3468
+ /** 同 `list`,另外说明这次是不是全部读到了。 */
3469
+ 'snapshot': {
3470
+ kind: 'call';
3471
+ args: [cwd: string | null];
3472
+ output: SkillCatalogSnapshot;
414
3473
  };
415
- };
416
- /** 系统提示词段(0.12 的 `ctx.systemPrompt`)。 */
417
- 'systemPrompt': {
418
- /** 注册一段;`agent` 给出时只对这个 agent 生效。 */
419
- 'section': {
3474
+ /** 加载生效的那个同名 Skill;没有时为 null。 */
3475
+ 'get': {
3476
+ kind: 'call';
3477
+ args: [name: string, cwd: string | null];
3478
+ output: SkillDefinition | null;
3479
+ };
3480
+ /**
3481
+ * 注册一个 Skill:进模型的 Skill 目录、用户的开关与管理页,随这项注册撤销。优先级在项目的之后、用户的之前。
3482
+ * 错误码:`SKILL_INVALID`、`SKILL_DUPLICATE`(已有插件注册了同名的)。
3483
+ */
3484
+ 'register': {
420
3485
  kind: 'register';
421
- args: [agent: string | null, section: PromptSection];
3486
+ args: [skill: SkillRegistration];
422
3487
  output: void;
423
3488
  };
424
3489
  };
425
- /**
426
- * 插件后端给界面的 remote(0.12 的 `TypertRemoteService`):SDK 的 `TypertRemoteService` 用它挂载命名空间,
427
- * 界面经宿主协议的 `pluginRemote.*` 调用。
428
- */
429
- 'pluginRemote': {
430
- /** 挂载一个命名空间,随服务撤销;同名命名空间已挂载时失败。 */
431
- 'mount': {
3490
+ /** 命令表(0.12 的 `ctx.commands`):插件给用户用的斜杠命令,界面并进输入框的斜杠建议。 */
3491
+ 'commands': {
3492
+ /**
3493
+ * 注册一条命令,经回调执行。`agent` 给出时只对这个 agent 生效,盖住同名的全局命令。同一层里重名报 `COMMAND_DUPLICATE`,
3494
+ * 名字或说明不对报 `COMMAND_INVALID`。
3495
+ */
3496
+ 'register': {
432
3497
  kind: 'register';
433
- args: [namespace: string, methods: Array<RemoteMethod>];
3498
+ args: [agent: string | null, definition: CommandRegistration];
434
3499
  output: void;
435
3500
  callback: {
436
- input: RemoteInvocation;
437
- output: JsonValue;
3501
+ input: CommandRun;
3502
+ output: CommandResult;
438
3503
  };
439
3504
  };
3505
+ /** 这个会话看得到的命令,按名字排好。 */
3506
+ 'list': {
3507
+ kind: 'call';
3508
+ args: [sessionId: string];
3509
+ output: Array<CommandDescriptor>;
3510
+ };
3511
+ /** 这个会话看得到的一条命令的描述,不含处理函数;没有时为 null。 */
3512
+ 'find': {
3513
+ kind: 'call';
3514
+ args: [sessionId: string, name: string];
3515
+ output: CommandDescriptor | null;
3516
+ };
3517
+ /**
3518
+ * 解析一行斜杠命令并执行,不交给模型;前后记 `command/run` 与 `command/done`。不是命令或没有这条命令时为 null。处理函数失败报
3519
+ * `COMMAND_FAILED`;没有这个会话报 `agent/session-not-found`。
3520
+ */
3521
+ 'execute': {
3522
+ kind: 'call';
3523
+ args: [sessionId: string, line: string];
3524
+ output: CommandExecution | null;
3525
+ };
440
3526
  };
441
- /** 会话日志(0.12 的 `ctx.sessions` 与 `appendPluginRecord`)。 */
442
- 'sessions': {
443
- /** 追加一条插件记录(可忽略的会话事件,模型看不到),返回它的 seq。 */
444
- 'appendPluginRecord': {
3527
+ /** 权限预设(0.12 的 `ctx.permissionPresets`):读预设表与会话当前的预设,切换会话的预设。 */
3528
+ 'permissionPresets': {
3529
+ /** 可以切换到的预设名,按声明顺序。 */
3530
+ 'names': {
445
3531
  kind: 'call';
446
- args: [sessionId: string, recordType: string, data: JsonValue];
447
- output: number;
3532
+ args: [];
3533
+ output: Array<string>;
448
3534
  };
449
- /** 会话里已落盘的全部事件(v4 的行,`sourceEventSeqs` 已展开);插件进程据此整批折叠会话投影。 */
450
- 'events': {
3535
+ /** 预设目录。 */
3536
+ 'catalog': {
3537
+ kind: 'call';
3538
+ args: [];
3539
+ output: PermissionCatalog;
3540
+ };
3541
+ /** 新会话的默认预设。 */
3542
+ 'defaultPreset': {
3543
+ kind: 'call';
3544
+ args: [];
3545
+ output: string;
3546
+ };
3547
+ /** 会话当前的预设;开关对不上任何预设时是 `custom`。没有这个会话报 `agent/session-not-found`。 */
3548
+ 'current': {
451
3549
  kind: 'call';
452
3550
  args: [sessionId: string];
453
- output: Array<JsonValue>;
3551
+ output: string;
454
3552
  };
455
- };
456
- /** 文件(0.12 的 `ctx.fs`):与文件工具同一套路径解析与写入。不是权限边界(TS 插件进程本来就能读写本机文件)。 */
457
- 'fs': {
458
- /** 解析路径;相对路径按 `cwd`,不给时用宿主的默认目录。不存在的路径也能定位。 */
3553
+ /** 预设的沙箱模式与审批策略;未知的预设报 `permission/unknown-preset`。 */
459
3554
  'resolve': {
460
3555
  kind: 'call';
461
- args: [path: string, cwd: string | null];
462
- output: FsResolved;
3556
+ args: [name: string];
3557
+ output: PresetSpec;
463
3558
  };
464
- /** 元数据;不存在时为 null。 */
465
- 'stat': {
3559
+ /** 目录里的一项,也收 `custom`;未知的预设报 `permission/unknown-preset`。 */
3560
+ 'optionOf': {
466
3561
  kind: 'call';
467
- args: [target: FsTarget];
468
- output: FsInfo | null;
3562
+ args: [name: string];
3563
+ output: PresetOption;
469
3564
  };
470
- /** 读出整份文件,字节按 base64;超过 `maxBytes` 报 `FS_TOO_LARGE`。 */
471
- 'readBytes': {
3565
+ /**
3566
+ * 切换会话的预设,与界面同一条路径,下一次工具派发起生效;记下调用方插件。要声明 `permissions.set`。任意会话都能收紧或切到别的
3567
+ * 预设;切到完全访问还要声明 `permissions.full-access` 并经用户按插件授权(没授权时问桌面端的用户,最多等 60 秒),用户拒绝、
3568
+ * 超时或桌面端没开时报 `permission/full-access-not-allowed`、会话不动,会话本来就是完全访问时照常。未知的预设报
3569
+ * `permission/unknown-preset`,子 agent 的会话报 `agent/subagent-session`。
3570
+ */
3571
+ 'set': {
472
3572
  kind: 'call';
473
- args: [target: FsTarget, maxBytes: number];
474
- output: string;
3573
+ args: [sessionId: string, name: string];
3574
+ output: void;
475
3575
  };
3576
+ };
3577
+ /** 沙箱策略(0.12 的 `ctx.sandboxPolicy`):只读。写文件用 `ctx.fs`,跑命令用 `ctx.shell`,宿主围住。 */
3578
+ 'sandboxPolicy': {
476
3579
  /**
477
- * 写入整份二进制(字节按 base64):`execution`(工具调用的 token)给出时先跑 `fs/write-intent`,本轮改动记录据此
478
- * 存下原文件;调用已经结束或 token 不对时拒绝。写入条件只看 `expected`(不给即无条件),不用瀑布的结论。
479
- * 在目标目录里原子发布,沿用原文件的权限,缺的父目录一并建。
3580
+ * 解析一次调用的策略:带 `execution` 时是这次工具调用定下的模式,带 `sessionId` 时是会话的,都不带时是部署默认。不收调用方传的模式。
3581
+ * `execution` 不是进行中的调用报 `invalid_params`,两者指向不同的会话同样;没有这个会话报 `agent/session-not-found`。
480
3582
  */
481
- 'writeBytes': {
3583
+ 'resolve': {
482
3584
  kind: 'call';
483
- args: [target: FsTarget, data: string, execution: string | null, expected: FsWriteIntent | null];
484
- output: FsWritten;
3585
+ args: [request: SandboxPolicyRequest];
3586
+ output: SandboxExecutionPolicy;
3587
+ };
3588
+ /** 会话记下的沙箱模式,不套默认;没有记录时为 null。没有这个会话报 `agent/session-not-found`。 */
3589
+ 'overrideOf': {
3590
+ kind: 'call';
3591
+ args: [sessionId: string];
3592
+ output: SandboxMode | null;
3593
+ };
3594
+ /** 部署默认的沙箱模式。 */
3595
+ 'defaultMode': {
3596
+ kind: 'call';
3597
+ args: [];
3598
+ output: SandboxMode;
3599
+ };
3600
+ /** 没有会话目录时的工作区根。 */
3601
+ 'workspaceRoot': {
3602
+ kind: 'call';
3603
+ args: [];
3604
+ output: string;
485
3605
  };
486
3606
  };
487
- /** 附件(0.12 的 `ctx.attachments`)。 */
488
- 'attachments': {
489
- /** 存一批图片,同 0.12 的 `saveImages`:先整批检查,全部准入、规范化通过才写入;结论与输入同序。 */
490
- 'saveImages': {
3607
+ /** 把命令围进沙箱(0.12 的 `ctx.sandbox`):只包启动参数,由调用方自己起进程。 */
3608
+ 'sandbox': {
3609
+ /** 包好的启动参数。完全访问与相对的工作区根报 `invalid_params`;这个平台没有可用的运行器(Windows 现状)报 `SANDBOX_UNAVAILABLE`,绝不回退成不围。 */
3610
+ 'confine': {
491
3611
  kind: 'call';
492
- args: [images: Array<ImageUpload>];
493
- output: Array<ImageRef>;
3612
+ args: [argv: Array<string>, policy: SandboxPolicy];
3613
+ output: ConfinedArgv;
494
3614
  };
495
3615
  };
496
- /** 模型(0.12 的 `ctx.llm`):注册模型路由、按 id 取模型信息、插件直接调用模型。 */
497
- 'llm': {
3616
+ /**
3617
+ * 在沙箱里跑命令(0.12 的 `ctx.shell`)。不收调用方的策略:带 `execution` 时按这次工具调用定下的模式,不带时按部署默认的模式(插件自己的命令),都断网。不弹审批:带调用的在工具入口已经审过。
3618
+ * 环境变量去掉凭据、上限 10 分钟,同核心的 bash。
3619
+ */
3620
+ 'shell': {
3621
+ /** 补齐工作目录、时限与到时策略。时限不是正数报 `invalid_params`,超过 10 分钟按 10 分钟。 */
3622
+ 'resolve': {
3623
+ kind: 'call';
3624
+ args: [request: ShellCommandRequest];
3625
+ output: ShellCommandSpec;
3626
+ };
498
3627
  /**
499
- * 注册一条路由(0.12 的 `registerAdapter`):一个 provider 与它的模型清单,每次请求经回调向插件取地址与凭据,回调的载荷是
500
- * provider 名。清单变了就撤销旧的注册、再注册一次。
3628
+ * 起命令:先给一条 `started`,结束时给一条 `finished`。丢掉流(插件中止、停用或插件进程退出)即停下。命令规则禁止时报 `COMMAND_FORBIDDEN`,
3629
+ * 读不了规则报 `COMMAND_RULES_UNREADABLE`,没有可用的运行器报 `SANDBOX_UNAVAILABLE`,都不起进程。
501
3630
  */
502
- 'registerRoute': {
503
- kind: 'register';
504
- args: [route: ModelRoute];
3631
+ 'execute': {
3632
+ kind: 'stream';
3633
+ args: [spec: ShellCommandSpec];
3634
+ output: ShellFrame;
3635
+ };
3636
+ /** 读上一次读取之后的输出。命令已经结束时报 `shell/not-running`:剩下的在 `finished` 里。 */
3637
+ 'readOutput': {
3638
+ kind: 'call';
3639
+ args: [id: string];
3640
+ output: ShellProcessRead;
3641
+ };
3642
+ /** 停下命令,返回是否这次停下的;已经结束时为否。 */
3643
+ 'kill': {
3644
+ kind: 'call';
3645
+ args: [id: string];
3646
+ output: boolean;
3647
+ };
3648
+ };
3649
+ /**
3650
+ * 凭据(0.12 的 `ctx.credentials`),按插件隔离:记录与 `set`、`unset` 只在调用方插件自己的空间里;`resolve`、`describe` 先查自己的空间,
3651
+ * 再查插件进程的启动环境,别人保管的(FtAi 里配的、别的插件存的、0.12 留下的)要先声明 `credentials.shared`(没声明时报
3652
+ * `plugin/capability-not-declared`),再经用户在界面上允许才读得到,没允许时按没配置答。一方插件读别人保管的不要允许。隔离只在接口这一层:插件进程里的插件之间没有隔离。不归属插件的调用(经 `agent.ctx`)报 `forbidden`。
3653
+ */
3654
+ 'credentials': {
3655
+ /** 解析一个引用;没有配置或没有允许时为 null。引用名不合文法报 `invalid_params`。 */
3656
+ 'resolve': {
3657
+ kind: 'call';
3658
+ args: [reference: string];
3659
+ output: ResolvedCredential | null;
3660
+ };
3661
+ /** 描述一个引用,不含值;同 `resolve` 的分层与允许。 */
3662
+ 'describe': {
3663
+ kind: 'call';
3664
+ args: [reference: string];
3665
+ output: CredentialInfo;
3666
+ };
3667
+ /** 存进调用方自己的空间;空值报 `invalid_params`(用 `unset`)。 */
3668
+ 'set': {
3669
+ kind: 'call';
3670
+ args: [reference: string, value: string];
505
3671
  output: void;
506
- callback: {
507
- input: string;
508
- output: RouteCredentials;
509
- };
510
3672
  };
511
- /** 按 id 取模型信息:没有这个 provider 报 `NO_ADAPTER`,有 provider 没有这个模型报 `UNKNOWN_MODEL`。 */
512
- 'resolveModelInfo': {
3673
+ /** 从调用方自己的空间删掉;本来就没有时什么也不做。 */
3674
+ 'unset': {
513
3675
  kind: 'call';
514
- args: [provider: string, model: string];
515
- output: LlmModelInfo;
3676
+ args: [reference: string];
3677
+ output: void;
3678
+ };
3679
+ /** 读调用方自己的一条记录(`<scope>/<id>`);没有时为 null。 */
3680
+ 'readRecord': {
3681
+ kind: 'call';
3682
+ args: [key: string];
3683
+ output: JsonValue | null;
3684
+ };
3685
+ 'describeRecord': {
3686
+ kind: 'call';
3687
+ args: [key: string];
3688
+ output: CredentialRecordInfo;
3689
+ };
3690
+ /** 调用方自己的全部记录,按地址排好。 */
3691
+ 'listRecords': {
3692
+ kind: 'call';
3693
+ args: [];
3694
+ output: Array<CredentialRecordEntry>;
516
3695
  };
517
3696
  /**
518
- * 直接调用模型:逐条给出会话格式 v4 的 StreamChunk,最后两条是 usage 与 finish;失败也是 finish(`reason.kind` 为
519
- * `error`,带 `failure.code`)。不重试。
3697
+ * 串行化的读—改—写:先给 `current`,等调用方以 `commitRecord` 交回(上限 30 秒,超时报 `credentials/modify-timeout`),
3698
+ * 写下后给 `settled`。丢掉流时什么也不写。
520
3699
  */
521
- 'stream': {
3700
+ 'modifyRecord': {
522
3701
  kind: 'stream';
523
- args: [request: GenerateRequest];
524
- output: JsonValue;
3702
+ args: [key: string];
3703
+ output: CredentialModifyFrame;
3704
+ };
3705
+ /** 交回 `modifyRecord` 的结论:null 表示不改。租约不是调用方的或已经过期报 `credentials/lease-expired`。 */
3706
+ 'commitRecord': {
3707
+ kind: 'call';
3708
+ args: [lease: string, record: JsonValue | null];
3709
+ output: void;
3710
+ };
3711
+ /** 删掉调用方自己的一条记录;本来就没有时什么也不做。 */
3712
+ 'deleteRecord': {
3713
+ kind: 'call';
3714
+ args: [key: string];
3715
+ output: void;
3716
+ };
3717
+ /** 调用方读得到的凭据变了:自己空间里的写入,别人保管、它读得到的引用的写入,允许与撤销。丢掉流即退订。 */
3718
+ 'updates': {
3719
+ kind: 'stream';
3720
+ args: [];
3721
+ output: CredentialUpdate;
3722
+ };
3723
+ };
3724
+ /** 启停插件(0.12 的 `ctx.loader`,FtAi 没有条目树,只开放开关)。与插件页同一条路径,开关记进 `disabled.json`,重启后保持。 */
3725
+ 'loader': {
3726
+ /** 交给插件进程的插件与只有界面一半的插件(含停用的)。 */
3727
+ 'list': {
3728
+ kind: 'call';
3729
+ args: [];
3730
+ output: Array<LoaderEntry>;
3731
+ };
3732
+ /**
3733
+ * 启用或停用一个插件,两半连同绑在这一行上的核心插件一起。先答复再做(插件可以停自己),结果看 `list()`;没有这个插件报 `unknown_plugin`,
3734
+ * 必达通道报 `always_on`,宿主没有插件目录报 `unmanaged`。
3735
+ */
3736
+ 'setEnabled': {
3737
+ kind: 'call';
3738
+ args: [name: string, enabled: boolean];
3739
+ output: void;
525
3740
  };
526
3741
  };
527
3742
  }
@@ -532,12 +3747,23 @@ export declare const HOST_SERVICES: {
532
3747
  readonly methods: {
533
3748
  readonly register: "register";
534
3749
  readonly restrict: "register";
3750
+ readonly guard: "register";
3751
+ readonly get: "call";
3752
+ readonly schemas: "call";
3753
+ readonly executionMode: "call";
3754
+ readonly execute: "call";
535
3755
  };
536
3756
  };
537
3757
  readonly systemPrompt: {
538
3758
  readonly wrapped: true;
539
3759
  readonly methods: {
540
3760
  readonly section: "register";
3761
+ readonly context: "register";
3762
+ readonly suppressRuntimeContext: "register";
3763
+ readonly tools: "register";
3764
+ readonly variable: "register";
3765
+ readonly assemble: "call";
3766
+ readonly refreshContext: "call";
541
3767
  };
542
3768
  };
543
3769
  readonly pluginRemote: {
@@ -551,6 +3777,56 @@ export declare const HOST_SERVICES: {
551
3777
  readonly methods: {
552
3778
  readonly appendPluginRecord: "call";
553
3779
  readonly events: "call";
3780
+ readonly header: "call";
3781
+ readonly surface: "call";
3782
+ readonly seq: "call";
3783
+ readonly prepare: "call";
3784
+ readonly enter: "call";
3785
+ readonly announce: "call";
3786
+ readonly release: "call";
3787
+ readonly fork: "call";
3788
+ readonly flush: "call";
3789
+ readonly lifecycle: "call";
3790
+ readonly append: "call";
3791
+ readonly requestHeader: "call";
3792
+ readonly requestContext: "call";
3793
+ readonly deriveMessages: "call";
3794
+ readonly deriveEventMessage: "call";
3795
+ readonly registerMessageProjection: "register";
3796
+ };
3797
+ };
3798
+ readonly agents: {
3799
+ readonly wrapped: true;
3800
+ readonly methods: {
3801
+ readonly create: "call";
3802
+ readonly resume: "call";
3803
+ readonly dispose: "call";
3804
+ readonly list: "call";
3805
+ readonly roots: "call";
3806
+ readonly isOwnedBy: "call";
3807
+ };
3808
+ };
3809
+ readonly turn: {
3810
+ readonly wrapped: true;
3811
+ readonly methods: {
3812
+ readonly send: "call";
3813
+ readonly cancel: "call";
3814
+ readonly status: "call";
3815
+ readonly whenIdle: "call";
3816
+ readonly options: "call";
3817
+ readonly inbox: "call";
3818
+ readonly spliceInbox: "call";
3819
+ readonly removeFromInbox: "call";
3820
+ readonly replaceInInbox: "call";
3821
+ readonly clearInbox: "call";
3822
+ readonly maintain: "stream";
3823
+ };
3824
+ };
3825
+ readonly agentDefaultModel: {
3826
+ readonly wrapped: false;
3827
+ readonly methods: {
3828
+ readonly currentSelection: "call";
3829
+ readonly saveSelection: "call";
554
3830
  };
555
3831
  };
556
3832
  readonly fs: {
@@ -560,20 +3836,363 @@ export declare const HOST_SERVICES: {
560
3836
  readonly stat: "call";
561
3837
  readonly readBytes: "call";
562
3838
  readonly writeBytes: "call";
3839
+ readonly lstat: "call";
3840
+ readonly readText: "call";
3841
+ readonly readTextChunk: "call";
3842
+ readonly readByteRange: "call";
3843
+ readonly listDir: "call";
3844
+ readonly editText: "call";
3845
+ };
3846
+ };
3847
+ readonly fsWatch: {
3848
+ readonly wrapped: true;
3849
+ readonly methods: {
3850
+ readonly watch: "stream";
563
3851
  };
564
3852
  };
565
3853
  readonly attachments: {
566
3854
  readonly wrapped: true;
567
3855
  readonly methods: {
3856
+ readonly imageLimits: "call";
3857
+ readonly validateImage: "call";
568
3858
  readonly saveImages: "call";
3859
+ readonly saveImage: "call";
3860
+ readonly readImage: "call";
3861
+ readonly imageHostPath: "call";
3862
+ readonly readImageRequest: "call";
3863
+ readonly saveFile: "call";
3864
+ readonly uploadFile: "stream";
3865
+ readonly appendFile: "call";
3866
+ readonly finishFile: "call";
3867
+ readonly readFileChunk: "call";
3868
+ readonly fileHostPath: "call";
569
3869
  };
570
3870
  };
571
3871
  readonly llm: {
572
3872
  readonly wrapped: true;
573
3873
  readonly methods: {
574
3874
  readonly registerRoute: "register";
3875
+ readonly registerAdapter: "register";
3876
+ readonly replaceAdapterRoutes: "call";
3877
+ readonly listProviders: "call";
3878
+ readonly listModels: "call";
3879
+ readonly registerConfigurableProviders: "register";
3880
+ readonly replaceConfigurableProviders: "call";
3881
+ readonly listConfigurableProviders: "call";
3882
+ readonly registerModelDiscovery: "register";
3883
+ readonly discoverModels: "call";
3884
+ readonly providerRetryPolicy: "call";
3885
+ readonly imageRequestPricing: "call";
3886
+ readonly fileRequestText: "call";
3887
+ readonly resolveCallConfig: "call";
3888
+ readonly bindCall: "call";
3889
+ readonly configureBoundCall: "call";
3890
+ readonly streamPrepared: "stream";
575
3891
  readonly resolveModelInfo: "call";
576
3892
  readonly stream: "stream";
577
3893
  };
578
3894
  };
3895
+ readonly approval: {
3896
+ readonly wrapped: true;
3897
+ readonly methods: {
3898
+ readonly config: "call";
3899
+ readonly overrideOf: "call";
3900
+ readonly setPolicy: "call";
3901
+ readonly request: "call";
3902
+ };
3903
+ };
3904
+ readonly workingDirectory: {
3905
+ readonly wrapped: false;
3906
+ readonly methods: {
3907
+ readonly get: "call";
3908
+ readonly ensure: "call";
3909
+ readonly set: "call";
3910
+ readonly defaultDirectory: "call";
3911
+ };
3912
+ };
3913
+ readonly workspaceRegistry: {
3914
+ readonly wrapped: true;
3915
+ readonly methods: {
3916
+ readonly create: "call";
3917
+ readonly get: "call";
3918
+ readonly list: "call";
3919
+ readonly delete: "call";
3920
+ readonly insertBefore: "call";
3921
+ readonly archiveSession: "call";
3922
+ readonly unarchiveSession: "call";
3923
+ readonly pinSession: "call";
3924
+ readonly unpinSession: "call";
3925
+ readonly resolveByPath: "call";
3926
+ readonly archivedSessionIds: "call";
3927
+ readonly pinnedSessionIds: "call";
3928
+ };
3929
+ };
3930
+ readonly goals: {
3931
+ readonly wrapped: true;
3932
+ readonly methods: {
3933
+ readonly get: "call";
3934
+ readonly create: "call";
3935
+ readonly edit: "call";
3936
+ readonly pause: "call";
3937
+ readonly resume: "call";
3938
+ readonly complete: "call";
3939
+ readonly block: "call";
3940
+ readonly clear: "call";
3941
+ readonly disarm: "call";
3942
+ };
3943
+ };
3944
+ readonly schedule: {
3945
+ readonly wrapped: true;
3946
+ readonly methods: {
3947
+ readonly create: "call";
3948
+ readonly list: "call";
3949
+ readonly catalog: "call";
3950
+ readonly history: "call";
3951
+ readonly delete: "call";
3952
+ readonly update: "call";
3953
+ };
3954
+ };
3955
+ readonly compaction: {
3956
+ readonly wrapped: true;
3957
+ readonly methods: {
3958
+ readonly compactNow: "call";
3959
+ readonly compactIfNeeded: "call";
3960
+ };
3961
+ };
3962
+ readonly subagents: {
3963
+ readonly wrapped: true;
3964
+ readonly methods: {
3965
+ readonly list: "call";
3966
+ readonly startActivation: "stream";
3967
+ readonly disposeActivation: "call";
3968
+ readonly sendMessage: "call";
3969
+ readonly interrupt: "call";
3970
+ readonly listChildren: "call";
3971
+ readonly listDescendants: "call";
3972
+ readonly waitForChildren: "call";
3973
+ };
3974
+ };
3975
+ readonly jobs: {
3976
+ readonly wrapped: true;
3977
+ readonly methods: {
3978
+ readonly start: "stream";
3979
+ readonly commit: "call";
3980
+ readonly append: "call";
3981
+ readonly updateProgress: "call";
3982
+ readonly reportSpill: "call";
3983
+ readonly finish: "call";
3984
+ readonly list: "call";
3985
+ readonly get: "call";
3986
+ readonly read: "call";
3987
+ readonly readAt: "call";
3988
+ readonly kill: "call";
3989
+ readonly wait: "call";
3990
+ readonly remove: "call";
3991
+ readonly events: "stream";
3992
+ };
3993
+ };
3994
+ readonly userQuestions: {
3995
+ readonly wrapped: true;
3996
+ readonly methods: {
3997
+ readonly ask: "stream";
3998
+ readonly answer: "call";
3999
+ };
4000
+ };
4001
+ readonly web: {
4002
+ readonly wrapped: true;
4003
+ readonly methods: {
4004
+ readonly fetch: "call";
4005
+ };
4006
+ };
4007
+ readonly webSearch: {
4008
+ readonly wrapped: true;
4009
+ readonly methods: {
4010
+ readonly search: "call";
4011
+ };
4012
+ };
4013
+ readonly skills: {
4014
+ readonly wrapped: true;
4015
+ readonly methods: {
4016
+ readonly list: "call";
4017
+ readonly snapshot: "call";
4018
+ readonly get: "call";
4019
+ readonly register: "register";
4020
+ };
4021
+ };
4022
+ readonly commands: {
4023
+ readonly wrapped: true;
4024
+ readonly methods: {
4025
+ readonly register: "register";
4026
+ readonly list: "call";
4027
+ readonly find: "call";
4028
+ readonly execute: "call";
4029
+ };
4030
+ };
4031
+ readonly permissionPresets: {
4032
+ readonly wrapped: false;
4033
+ readonly methods: {
4034
+ readonly names: "call";
4035
+ readonly catalog: "call";
4036
+ readonly defaultPreset: "call";
4037
+ readonly current: "call";
4038
+ readonly resolve: "call";
4039
+ readonly optionOf: "call";
4040
+ readonly set: "call";
4041
+ };
4042
+ };
4043
+ readonly sandboxPolicy: {
4044
+ readonly wrapped: true;
4045
+ readonly methods: {
4046
+ readonly resolve: "call";
4047
+ readonly overrideOf: "call";
4048
+ readonly defaultMode: "call";
4049
+ readonly workspaceRoot: "call";
4050
+ };
4051
+ };
4052
+ readonly sandbox: {
4053
+ readonly wrapped: true;
4054
+ readonly methods: {
4055
+ readonly confine: "call";
4056
+ };
4057
+ };
4058
+ readonly shell: {
4059
+ readonly wrapped: true;
4060
+ readonly methods: {
4061
+ readonly resolve: "call";
4062
+ readonly execute: "stream";
4063
+ readonly readOutput: "call";
4064
+ readonly kill: "call";
4065
+ };
4066
+ };
4067
+ readonly credentials: {
4068
+ readonly wrapped: true;
4069
+ readonly methods: {
4070
+ readonly resolve: "call";
4071
+ readonly describe: "call";
4072
+ readonly set: "call";
4073
+ readonly unset: "call";
4074
+ readonly readRecord: "call";
4075
+ readonly describeRecord: "call";
4076
+ readonly listRecords: "call";
4077
+ readonly modifyRecord: "stream";
4078
+ readonly commitRecord: "call";
4079
+ readonly deleteRecord: "call";
4080
+ readonly updates: "stream";
4081
+ };
4082
+ };
4083
+ readonly loader: {
4084
+ readonly wrapped: false;
4085
+ readonly methods: {
4086
+ readonly list: "call";
4087
+ readonly setEnabled: "call";
4088
+ };
4089
+ };
579
4090
  };
4091
+ /** 新对话的默认模型(0.12 的 `ctx.agentDefaultModel`)。 */
4092
+ export interface AgentDefaultModelApi {
4093
+ /** 当前的默认模型;没有时为 null。 */
4094
+ currentSelection(signal?: AbortSignal): Promise<DefaultModelSelection | null>;
4095
+ /** 改默认模型,新对话从此用它;模型不可用时报错。 */
4096
+ saveSelection(selection: DefaultModelSelection, signal?: AbortSignal): Promise<void>;
4097
+ }
4098
+ /**
4099
+ * 会话的工作目录(0.12 的 `ctx.workingDirectory`),与界面切换目录同一条路径。可以操作任意会话。错误码同界面:会话不存在或写不了
4100
+ * 时 `ftai-sessions/not-live`,目录不对时 `ftai-sessions/invalid-directory`。
4101
+ */
4102
+ export interface WorkingDirectoryApi {
4103
+ /** 当前目录,不做 IO。 */
4104
+ get(sessionId: string, signal?: AbortSignal): Promise<string>;
4105
+ /** 确认当前目录还在并返回它;不在了时退回会话的项目目录并告诉模型。 */
4106
+ ensure(sessionId: string, signal?: AbortSignal): Promise<string>;
4107
+ /** 换目录,返回真实路径:相对路径按当前目录解析,必须是已有的目录。写进会话并告诉模型,已经在跑的命令留在原来的目录。 */
4108
+ set(sessionId: string, path: string, signal?: AbortSignal): Promise<string>;
4109
+ /** 没有指定目录的会话用的默认目录。 */
4110
+ defaultDirectory(signal?: AbortSignal): Promise<string>;
4111
+ }
4112
+ /** 权限预设(0.12 的 `ctx.permissionPresets`):读预设表与会话当前的预设,切换会话的预设。 */
4113
+ export interface PermissionPresetsApi {
4114
+ /** 可以切换到的预设名,按声明顺序。 */
4115
+ names(signal?: AbortSignal): Promise<Array<string>>;
4116
+ /** 预设目录。 */
4117
+ catalog(signal?: AbortSignal): Promise<PermissionCatalog>;
4118
+ /** 新会话的默认预设。 */
4119
+ defaultPreset(signal?: AbortSignal): Promise<string>;
4120
+ /** 会话当前的预设;开关对不上任何预设时是 `custom`。没有这个会话报 `agent/session-not-found`。 */
4121
+ current(sessionId: string, signal?: AbortSignal): Promise<string>;
4122
+ /** 预设的沙箱模式与审批策略;未知的预设报 `permission/unknown-preset`。 */
4123
+ resolve(name: string, signal?: AbortSignal): Promise<PresetSpec>;
4124
+ /** 目录里的一项,也收 `custom`;未知的预设报 `permission/unknown-preset`。 */
4125
+ optionOf(name: string, signal?: AbortSignal): Promise<PresetOption>;
4126
+ /**
4127
+ * 切换会话的预设,与界面同一条路径,下一次工具派发起生效;记下调用方插件。要声明 `permissions.set`。任意会话都能收紧或切到别的
4128
+ * 预设;切到完全访问还要声明 `permissions.full-access` 并经用户按插件授权(没授权时问桌面端的用户,最多等 60 秒),用户拒绝、
4129
+ * 超时或桌面端没开时报 `permission/full-access-not-allowed`、会话不动,会话本来就是完全访问时照常。未知的预设报
4130
+ * `permission/unknown-preset`,子 agent 的会话报 `agent/subagent-session`。
4131
+ */
4132
+ set(sessionId: string, name: string, signal?: AbortSignal): Promise<void>;
4133
+ }
4134
+ /** 启停插件(0.12 的 `ctx.loader`,FtAi 没有条目树,只开放开关)。与插件页同一条路径,开关记进 `disabled.json`,重启后保持。 */
4135
+ export interface LoaderApi {
4136
+ /** 交给插件进程的插件与只有界面一半的插件(含停用的)。 */
4137
+ list(signal?: AbortSignal): Promise<Array<LoaderEntry>>;
4138
+ /**
4139
+ * 启用或停用一个插件,两半连同绑在这一行上的核心插件一起。先答复再做(插件可以停自己),结果看 `list()`;没有这个插件报 `unknown_plugin`,
4140
+ * 必达通道报 `always_on`,宿主没有插件目录报 `unmanaged`。
4141
+ */
4142
+ setEnabled(name: string, enabled: boolean, signal?: AbortSignal): Promise<void>;
4143
+ }
4144
+ declare module 'cordis' {
4145
+ interface Context {
4146
+ /** 新对话的默认模型(0.12 的 `ctx.agentDefaultModel`)。 */
4147
+ agentDefaultModel: AgentDefaultModelApi;
4148
+ /**
4149
+ * 会话的工作目录(0.12 的 `ctx.workingDirectory`),与界面切换目录同一条路径。可以操作任意会话。错误码同界面:会话不存在或写不了
4150
+ * 时 `ftai-sessions/not-live`,目录不对时 `ftai-sessions/invalid-directory`。
4151
+ */
4152
+ workingDirectory: WorkingDirectoryApi;
4153
+ /** 权限预设(0.12 的 `ctx.permissionPresets`):读预设表与会话当前的预设,切换会话的预设。 */
4154
+ permissionPresets: PermissionPresetsApi;
4155
+ /** 启停插件(0.12 的 `ctx.loader`,FtAi 没有条目树,只开放开关)。与插件页同一条路径,开关记进 `disabled.json`,重启后保持。 */
4156
+ loader: LoaderApi;
4157
+ }
4158
+ interface Events {
4159
+ /** 工具注册或按 agent 的收起变了:重新读 `ctx.tools.schemas()`。观察点,没有载荷,不按 agent 过滤。 */
4160
+ 'tools/change'(input: null): void;
4161
+ /** 提示词段、运行环境段、变量、工具与工具提供者的注册有变化:不带载荷,监听者看到的已是变化之后的状态。 */
4162
+ 'system-prompt/change'(input: null): void;
4163
+ /** 模型路由、模型清单或可配置 provider 的目录变了:按 `listProviders`、`listModels`、`listConfigurableProviders` 重新取。 */
4164
+ 'llm/adapters-updated'(input: null): void;
4165
+ /**
4166
+ * 归档之前问会话还有什么在跑(`archiveSession` 不带 `stopActivity` 时):调用 `next` 得到下游的工作,把自己的加在前面返回。
4167
+ * 非空就拒绝归档,什么都不写。监听者藏不住下游报的工作;超时(60 秒)、崩溃或形状不对时按它没有报(坏插件不能永远挡住归档)。
4168
+ * 登记的写入在排队,监听者里不要调用会改登记的方法,否则等到超时。
4169
+ */
4170
+ 'workspace/session-activity'(input: SessionActivityRequest, next: () => Promise<Array<SessionActivity>>): Array<SessionActivity> | Promise<Array<SessionActivity>>;
4171
+ /**
4172
+ * 归档之后请各方停下这个会话的工作(`archiveSession` 带 `stopActivity` 时):归档集已经落盘,停下引起的唤醒都已被挡住。监听者
4173
+ * 同时跑,宿主都等到结束;失败或超时(30 秒)只记日志,不影响别的监听者,也不撤销归档。发出停止请求即可,不要等工作结束。
4174
+ */
4175
+ 'workspace/session-stop'(input: SessionActivityRequest): void | Promise<void>;
4176
+ /** Goal 的一次变更写进了会话:模型的工具、界面、插件与轮次驱动改的都算。 */
4177
+ 'goal/changed'(input: GoalChanged): void;
4178
+ /** 这个宿主进程是否在为 Goal 安排轮次变了(激活状态不落盘)。 */
4179
+ 'goal/activation-changed'(input: GoalActivationChanged): void;
4180
+ /** 已安排的任务变了(建、改、删、暂停、恢复、转移、投递):重新读 `ctx.schedule`。观察点,没有载荷,一批变化可能合成一次。 */
4181
+ 'schedule/changed'(input: null): void;
4182
+ /**
4183
+ * 摘要请求失败、图片卸载也救不了时:监听者写下改动(如插件记录加消息投影)后返回 true,宿主重新计量这段范围、再请求一次;
4184
+ * 救不了就调用 `next`,默认不重试。每次压缩最多重试 3 次。超时(60 秒)或崩溃按不重试。
4185
+ */
4186
+ 'compaction/summary-error'(input: CompactionSummaryError, next: () => Promise<boolean>): boolean | Promise<boolean>;
4187
+ /** 一段子 agent 的常驻开始了(新建或冷恢复,工具与插件起的都算)。与 `subagent/end` 按 `runId` 成对,同一段先发它。观察点,不等答复。 */
4188
+ 'subagent/start'(input: SubagentRunInfo): void;
4189
+ /** 一段子 agent 的常驻结算了。观察点,不等答复。 */
4190
+ 'subagent/end'(input: SubagentRunEndInfo): void;
4191
+ /** Skill 可能变了(开关、安装卸载、能力包、插件注册、磁盘上的改动):不带载荷,按 `ctx.skills` 重新读。 */
4192
+ 'skills/change'(input: null): void;
4193
+ /** 命令表变了(注册或撤销):不带载荷,按 `ctx.commands.list` 重新读。不按 agent 过滤。 */
4194
+ 'commands/change'(input: null): void;
4195
+ /** 权限预设的目录变了(0.12 的 `permission-presets/catalog-changed`):重新取 `permissionPresets.catalog()`。预设表是写死的,现在不会触发。 */
4196
+ 'permission-presets/catalog-changed'(input: null): void;
4197
+ }
4198
+ }