@ftai/plugin-host-api 0.0.0-stage → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +4 -2
  3. package/lib/attachments.d.ts +149 -0
  4. package/lib/attachments.js +26 -0
  5. package/lib/capabilities.d.ts +99 -0
  6. package/lib/capabilities.js +21 -0
  7. package/lib/cmdline.d.ts +52 -0
  8. package/lib/cmdline.js +68 -0
  9. package/lib/credentials.d.ts +92 -0
  10. package/lib/credentials.js +41 -0
  11. package/lib/fs.d.ts +117 -0
  12. package/lib/fs.js +14 -0
  13. package/lib/generated.d.ts +4198 -0
  14. package/lib/generated.js +80 -0
  15. package/lib/index.d.ts +665 -0
  16. package/lib/index.js +151 -0
  17. package/lib/jobs.d.ts +88 -0
  18. package/lib/jobs.js +2 -0
  19. package/lib/llm.d.ts +255 -0
  20. package/lib/llm.js +144 -0
  21. package/lib/local-install.d.ts +38 -0
  22. package/lib/local-install.js +9 -0
  23. package/lib/permissions.d.ts +97 -0
  24. package/lib/permissions.js +11 -0
  25. package/lib/platform.d.ts +167 -0
  26. package/lib/platform.js +74 -0
  27. package/lib/porting.d.ts +51 -0
  28. package/lib/porting.js +752 -0
  29. package/lib/prompt.d.ts +117 -0
  30. package/lib/prompt.js +43 -0
  31. package/lib/runtime-context.d.ts +29 -0
  32. package/lib/runtime-context.js +6 -0
  33. package/lib/schedule-types.d.ts +333 -0
  34. package/lib/schedule-types.js +4 -0
  35. package/lib/session-events.d.ts +194 -0
  36. package/lib/session-events.js +2 -0
  37. package/lib/sessions.d.ts +246 -0
  38. package/lib/sessions.js +2 -0
  39. package/lib/settings.d.ts +86 -0
  40. package/lib/settings.js +13 -0
  41. package/lib/storage.d.ts +144 -0
  42. package/lib/storage.js +62 -0
  43. package/lib/subagents.d.ts +57 -0
  44. package/lib/subagents.js +17 -0
  45. package/lib/subprocess.d.ts +97 -0
  46. package/lib/subprocess.js +8 -0
  47. package/lib/tools.d.ts +212 -0
  48. package/lib/tools.js +2 -0
  49. package/lib/web.d.ts +192 -0
  50. package/lib/web.js +53 -0
  51. package/package.json +40 -3
@@ -0,0 +1,38 @@
1
+ /**
2
+ * 插件进程所在的本机安装(SDK 2.2):插件自己的数据目录与缓存目录,与连上同一个后台服务的命令行 `ftai`。实现在插件进程里。
3
+ *
4
+ * 给要在本机落大文件、或要拉起外部应用的插件用:例如插件下载一个运行包放进自己的缓存目录,再由那个应用经 `ftai app` 连回
5
+ * FtAi(docs/rust-host/cli.md「外部应用」)。
6
+ * @module
7
+ */
8
+ /** 本机的 `ftai`。 */
9
+ export interface LocalCli {
10
+ /** 可执行文件的绝对路径。 */
11
+ readonly path: string;
12
+ /**
13
+ * 运行它时要带上的环境变量:后台服务启动时的全部 `FTAI_*`,不多不少。`ftai` 环境里的 `FTAI_*` 与在跑的后台服务不同时,
14
+ * 它会按「构建不同」替换掉那个后台服务,所以原样带上这一份,别的 `FTAI_*` 不要加。`ctx.subprocess` 会去掉 `FTAI_*`,
15
+ * 要经它的 `env` 显式交回去;交给外部应用时,也要让它把这一份原样交给它起的 `ftai`。
16
+ */
17
+ readonly env: Readonly<Record<string, string>>;
18
+ }
19
+ export interface LocalInstall {
20
+ /**
21
+ * 这个插件自己的数据目录(绝对路径),放用户的数据,可能还不存在,用时自己建。`ctx.storageDomain` 与 `ctx.settings` 的文件
22
+ * 也在这里(`storages/` 与 `settings.json`),插件自己的文件放在别的子目录里。卸载插件时默认留下,重装后接着用;用户在卸载
23
+ * 确认里勾选删除时连同整个目录删掉。
24
+ */
25
+ readonly dataDir: string;
26
+ /**
27
+ * 这个插件自己的缓存目录(绝对路径),放能重新得到的内容,如下载的运行包,可能还不存在,用时自己建。插件没在运行时宿主可能
28
+ * 清空它,插件要能自己重新下载;卸载插件时一定删掉。用户的数据不要放在这里。
29
+ */
30
+ readonly cacheDir: string;
31
+ /** 本机的 `ftai`;宿主旁边没有时为 undefined(如测试)。 */
32
+ readonly cli: LocalCli | undefined;
33
+ }
34
+ declare module 'cordis' {
35
+ interface Context {
36
+ readonly localInstall: LocalInstall;
37
+ }
38
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * 插件进程所在的本机安装(SDK 2.2):插件自己的数据目录与缓存目录,与连上同一个后台服务的命令行 `ftai`。实现在插件进程里。
3
+ *
4
+ * 给要在本机落大文件、或要拉起外部应用的插件用:例如插件下载一个运行包放进自己的缓存目录,再由那个应用经 `ftai app` 连回
5
+ * FtAi(docs/rust-host/cli.md「外部应用」)。
6
+ * @module
7
+ */
8
+ export {};
9
+ //# sourceMappingURL=local-install.js.map
@@ -0,0 +1,97 @@
1
+ /**
2
+ * 审批、沙箱与 shell 另包的一层(`ctx.approval`、`ctx.sandboxPolicy`、`ctx.sandbox`、`ctx.shell`):接口同 0.12,跨进程后都是异步的,
3
+ * 0.12 收 agent 句柄的参数这里收会话 id。放开给第三方,但失败时的结论不放宽:出错、超时、崩溃一律不放行。逐项的差别见移植指南的对照表,
4
+ * 产品约束见 docs/rust-host/plugin-parity.md。
5
+ * @module
6
+ */
7
+ import type { ApprovalConfig, ApprovalOutcome, ApprovalPolicy, ApprovalRequestEvent, ConfinedArgv, SandboxExecutionPolicy, SandboxMode, SandboxPolicy, ShellCollectedOutput, ShellCommandRequest, ShellCommandSpec, ShellProcessRead, ShellProcessStatus, ShellSandboxInfo } from './generated.ts';
8
+ import type { ToolExecution } from './index.ts';
9
+ /** 审批(0.12 的 `ApprovalService`)。 */
10
+ export interface ApprovalService {
11
+ /** 部署默认的审批策略。 */
12
+ config(): Promise<ApprovalConfig>;
13
+ /** 会话记下的审批策略,不套默认;没有记录时是 undefined。 */
14
+ overrideOf(sessionId: string): Promise<ApprovalPolicy | undefined>;
15
+ /** 切换会话的审批策略。与生效的策略相同时不写;子 agent 的会话拒绝。模型会收到一条通知,不说是谁改的。 */
16
+ setPolicy(sessionId: string, policy: ApprovalPolicy): Promise<void>;
17
+ /** 为进行中的工具调用申请一次批准。只有 `allowed-once` 算批准。 */
18
+ request(execution: ToolExecution, reason?: string, displayReason?: {
19
+ readonly en: string;
20
+ readonly [locale: string]: string;
21
+ }): Promise<ApprovalOutcome>;
22
+ }
23
+ /** `approval/request` 的监听者拿到的请求。`signal` 在这一轮取消或宿主不再等时触发。 */
24
+ export interface ApprovalRequest extends ApprovalRequestEvent {
25
+ readonly signal: AbortSignal;
26
+ }
27
+ /** `ctx.sandboxPolicy.resolve` 的入参。`execution` 同 `ctx.fs`:进行中工具调用的句柄。 */
28
+ export interface SandboxPolicyQuery {
29
+ readonly sessionId?: string;
30
+ readonly execution?: ToolExecution;
31
+ }
32
+ /** 沙箱策略(0.12 的 `SandboxPolicyService`):只读,不收调用方传的模式。 */
33
+ export interface SandboxPolicyService {
34
+ /** 带 `execution` 时是这次工具调用定下的模式,带 `sessionId` 时是会话的,都不带时是部署默认。 */
35
+ resolve(request?: SandboxPolicyQuery): Promise<SandboxExecutionPolicy>;
36
+ /** 会话记下的沙箱模式,不套默认;没有记录时是 undefined。 */
37
+ overrideOf(sessionId: string): Promise<SandboxMode | undefined>;
38
+ defaultMode(): Promise<SandboxMode>;
39
+ workspaceRoot(): Promise<string>;
40
+ }
41
+ /** 同 0.12:没有可用的运行器时的错误码。 */
42
+ export declare const SANDBOX_UNAVAILABLE = "SANDBOX_UNAVAILABLE";
43
+ /** 同 0.12:要求受限执行而这个平台没有可用的运行器。绝不回退成不围。 */
44
+ export declare class SandboxUnavailableError extends Error {
45
+ readonly code = "SANDBOX_UNAVAILABLE";
46
+ constructor(message: string, options?: ErrorOptions);
47
+ }
48
+ /** 把命令围进沙箱(0.12 的 `SandboxProvider`):只包启动参数,进程由调用方起。 */
49
+ export interface SandboxProvider {
50
+ /** 模式只收 `read-only`、`workspace-write`。没有可用的运行器时抛 {@link SandboxUnavailableError}。 */
51
+ confine(argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): Promise<ConfinedArgv>;
52
+ }
53
+ /** `ctx.shell.resolve` 的入参(0.12 的 `ShellExecRequest`)。没有 `sandboxPolicy`、`dshEnv`、`stdoutMaxBytes`,写了报 `invalid_params`。 */
54
+ export interface ShellExecRequest extends Omit<ShellCommandRequest, 'execution'> {
55
+ /** 同 `ctx.fs`:进行中工具调用的句柄,按这次调用定下的模式围。不给时是插件自己的命令,按部署默认的模式,断网。 */
56
+ readonly execution?: ToolExecution;
57
+ /** 触发时停下命令。 */
58
+ signal?: AbortSignal;
59
+ }
60
+ /** `ctx.shell.resolve` 的结果(0.12 的 `ShellExecSpec`)。 */
61
+ export interface ShellExecSpec extends ShellCommandSpec {
62
+ signal?: AbortSignal;
63
+ }
64
+ /** 跑完的结果(0.12 的 `ShellRunResult`)。非零退出、超时与中止都不算失败。 */
65
+ export interface ShellRunResult {
66
+ exitCode: number | null;
67
+ signal: string | null;
68
+ /** 到时限被停下。与 `aborted` 只有一个成立。 */
69
+ timedOut: boolean;
70
+ /** 调用方的 `signal` 或插件撤销先停下了它。 */
71
+ aborted: boolean;
72
+ timeoutMs: number;
73
+ stdout: ShellCollectedOutput;
74
+ stderr: ShellCollectedOutput;
75
+ sandbox?: ShellSandboxInfo;
76
+ }
77
+ /** 一条在跑的命令(0.12 的 `ShellExecution`)。`status`、`exitCode`、`signal`、`sandbox` 在结束时更新。 */
78
+ export interface ShellExecution {
79
+ readonly status: ShellProcessStatus;
80
+ readonly exitCode: number | null;
81
+ readonly signal: string | null;
82
+ readonly sandbox?: ShellSandboxInfo;
83
+ /** 命令结束时兑现,不会拒绝。 */
84
+ readonly done: Promise<void>;
85
+ /** 等它结束给出结果;命令没有跑成(起不来、运行器失败)时拒绝。 */
86
+ result(): Promise<ShellRunResult>;
87
+ /** 上一次读取之后的输出,消费式,stderr 在 `[stderr]` 一节里。 */
88
+ readOutput(): Promise<ShellProcessRead>;
89
+ /** 停下命令,返回是否这次停下的;已经结束时为否。 */
90
+ kill(): Promise<boolean>;
91
+ }
92
+ /** 在沙箱里跑命令(0.12 的 `ShellExecutor`)。带 `execution` 时按这次工具调用定下的模式,不带时按部署默认的模式(插件自己的命令),都断网。命令随调用方插件撤销停下。 */
93
+ export interface ShellExecutor {
94
+ resolve(request: ShellExecRequest): Promise<ShellExecSpec>;
95
+ /** 命令规则禁止(`COMMAND_FORBIDDEN`)、没有可用的运行器({@link SandboxUnavailableError})时拒绝,不起进程。 */
96
+ execute(spec: ShellExecSpec): Promise<ShellExecution>;
97
+ }
@@ -0,0 +1,11 @@
1
+ /** 同 0.12:没有可用的运行器时的错误码。 */
2
+ export const SANDBOX_UNAVAILABLE = 'SANDBOX_UNAVAILABLE';
3
+ /** 同 0.12:要求受限执行而这个平台没有可用的运行器。绝不回退成不围。 */
4
+ export class SandboxUnavailableError extends Error {
5
+ code = SANDBOX_UNAVAILABLE;
6
+ constructor(message, options) {
7
+ super(message, options);
8
+ this.name = 'SandboxUnavailableError';
9
+ }
10
+ }
11
+ //# sourceMappingURL=permissions.js.map
@@ -0,0 +1,167 @@
1
+ /**
2
+ * 工作区登记、Goal、已安排的任务与压缩(0.12 的 `ctx.workspaceRegistry`、`ctx.goals`、`ctx.schedule`、`ctx.compaction`),名字与参数顺序
3
+ * 照 0.12,与界面走同一条路径。形状变化见移植指南的对照表,共同的三点:
4
+ *
5
+ * - 全部是异步的(跨进程);
6
+ * - 0.12 收 agent 句柄的参数,这里收会话 id(`sessionId`),可以操作任意会话;
7
+ * - 工作目录(`ctx.workingDirectory`)没有另包一层,类型在 generated.ts。
8
+ * @module
9
+ */
10
+ import type { CompactionResult, CompactionTrigger, GoalBlockReason, GoalChange, GoalCreateRequest, GoalEditRequest, GoalRef, GoalView, SessionActivity, Workspace } from './generated.ts';
11
+ import type { ScheduleCatalogEntry, ScheduleCreateRequest, ScheduleDeleteResult, ScheduleDeliveryHistoryRequest, ScheduleDeliveryHistoryResult, ScheduleRecord, ScheduleTaskRequest, ScheduleUpdateRequest, ScheduleUpdateResult } from './schedule-types.ts';
12
+ export type * from './schedule-types.ts';
13
+ /** 就是字符串:0.12 的品牌类型。 */
14
+ export type GoalId = string;
15
+ /** 就是字符串:0.12 的品牌类型。 */
16
+ export type ScheduleId = string;
17
+ /** 没有这个会话时报 `session/not-found` 的两个操作(同 0.12)。 */
18
+ export declare class WorkspaceUnknownSessionError extends Error {
19
+ readonly sessionId: string;
20
+ constructor(sessionId: string, verb: 'archive' | 'pin', options?: ErrorOptions);
21
+ }
22
+ /** 不带 `stopActivity` 归档时会话还有工作:什么都没写,`activity` 列出要先停下的(同 0.12)。 */
23
+ export declare class WorkspaceActiveSessionError extends Error {
24
+ readonly sessionId: string;
25
+ readonly activity: readonly SessionActivity[];
26
+ constructor(sessionId: string, activity: readonly SessionActivity[]);
27
+ }
28
+ /** 置顶已归档的会话(同 0.12):置顶与归档互斥。 */
29
+ export declare class WorkspaceArchivedSessionPinError extends Error {
30
+ readonly sessionId: string;
31
+ constructor(sessionId: string, options?: ErrorOptions);
32
+ }
33
+ /** 排序时工作区或锚点不在登记里(同 0.12)。 */
34
+ export declare class WorkspaceOrderInvalidError extends Error {
35
+ readonly workspaceId: string;
36
+ constructor(workspaceId: string, options?: ErrorOptions);
37
+ }
38
+ export interface ArchiveSessionOptions {
39
+ /** 先写归档,再请各方停下这个会话的工作(`workspace/session-stop`);不带时会话有工作就拒绝。 */
40
+ readonly stopActivity?: boolean;
41
+ }
42
+ /** 工作区登记。工作区是读到那一刻的数据,不是 0.12 的活对象。 */
43
+ export interface WorkspaceRegistry {
44
+ /**
45
+ * 为已有的目录登记工作区,或取回已登记的同一目录(按真实路径)。
46
+ * @param title 只在新建时用,不给时取目录名。
47
+ */
48
+ create(path: string, title?: string): Promise<Workspace>;
49
+ get(id: string): Promise<Workspace | undefined>;
50
+ /** 按显示顺序。 */
51
+ list(): Promise<Workspace[]>;
52
+ /** 撤销登记,目录与会话日志都不动;不认识的 id 返回 false。 */
53
+ delete(id: string): Promise<boolean>;
54
+ /**
55
+ * 在显示顺序里移动:给了锚点就放到它前面,不给就放到最后。
56
+ * @returns 整个顺序。
57
+ * @throws {WorkspaceOrderInvalidError} 没有这个工作区或锚点。
58
+ */
59
+ insertBefore(id: string, before?: string): Promise<readonly string[]>;
60
+ /**
61
+ * 归档,同时取消置顶。已归档的直接返回。
62
+ * @throws {WorkspaceActiveSessionError} 不带 `stopActivity` 而会话有工作。
63
+ * @throws {WorkspaceUnknownSessionError} 没有这个会话。
64
+ */
65
+ archiveSession(sessionId: string, options?: ArchiveSessionOptions): Promise<void>;
66
+ unarchiveSession(sessionId: string): Promise<void>;
67
+ /**
68
+ * 置顶,排到最前。已置顶的直接返回。
69
+ * @throws {WorkspaceArchivedSessionPinError} 会话已归档。
70
+ * @throws {WorkspaceUnknownSessionError} 没有这个会话。
71
+ */
72
+ pinSession(sessionId: string): Promise<void>;
73
+ unpinSession(sessionId: string): Promise<void>;
74
+ /** 按真实路径找工作区,不写登记。路径不存在时报错,目录没有登记时为 undefined。 */
75
+ resolveByPath(path: string): Promise<Workspace | undefined>;
76
+ /** 归档集,按归档的先后(0.12 是同步的属性)。 */
77
+ archivedSessionIds(): Promise<readonly string[]>;
78
+ /** 置顶集,最近置顶的在前(0.12 是同步的属性)。 */
79
+ pinnedSessionIds(): Promise<readonly string[]>;
80
+ }
81
+ export declare const GOAL_ERROR_CODES: readonly ["GOAL_AGENT_NOT_LIVE", "GOAL_NOT_FOUND", "GOAL_ALREADY_EXISTS", "GOAL_STALE_REVISION", "GOAL_INVALID_OBJECTIVE", "GOAL_INVALID_MAX_ROUNDS", "GOAL_INVALID_BLOCK_REASON", "GOAL_INVALID_EDIT", "GOAL_INVALID_TRANSITION"];
82
+ export type GoalErrorCode = typeof GOAL_ERROR_CODES[number];
83
+ /** 读写 Goal 被拒绝(同 0.12)。日志里的 Goal 记录不合规则、会话写不了时是普通的 Error。 */
84
+ export declare class GoalError extends Error {
85
+ readonly code: GoalErrorCode;
86
+ constructor(message: string, code: GoalErrorCode, options?: ErrorOptions);
87
+ }
88
+ /** 变更的种类(0.12 的 `GoalOperation`)。 */
89
+ export type GoalOperation = GoalChange['operation'];
90
+ /** 会话的 Goal。写操作按 id 与修订号比较并交换,过期的修订报 `GOAL_STALE_REVISION`。 */
91
+ export interface GoalService {
92
+ /** 当前的 Goal;没有 Goal 或没有这个会话时为 undefined。 */
93
+ get(sessionId: string): Promise<GoalView | undefined>;
94
+ /** 创建并激活,会话空闲时随即开始第一轮(同界面)。不给 `maxGoalRounds` 时上限是 256 轮。子 agent 的会话拒绝。 */
95
+ create(sessionId: string, request: GoalCreateRequest): Promise<GoalView>;
96
+ /** 改目标和(或)轮数上限,阶段不变。 */
97
+ edit(sessionId: string, ref: GoalRef, request: GoalEditRequest): Promise<GoalView>;
98
+ /** 暂停并解除激活,停下正在跑的这一轮(同界面;0.12 的服务不停,由调用方停)。 */
99
+ pause(sessionId: string, ref: GoalRef): Promise<GoalView>;
100
+ /** 继续暂停或受阻的 Goal,或重新激活进行中但未激活的,会话空闲时随即开始下一轮。 */
101
+ resume(sessionId: string, ref: GoalRef): Promise<GoalView>;
102
+ complete(sessionId: string, ref: GoalRef): Promise<GoalView>;
103
+ block(sessionId: string, ref: GoalRef, reason: GoalBlockReason): Promise<GoalView>;
104
+ /** 清除,留下标记。返回的修订号比清除的那个大一。 */
105
+ clear(sessionId: string, ref: GoalRef): Promise<GoalRef>;
106
+ /** 只解除激活,不改阶段与修订,排着的一轮撤下。没有当前的 Goal 时为 undefined。 */
107
+ disarm(sessionId: string): Promise<GoalView | undefined>;
108
+ }
109
+ export declare const SCHEDULE_INPUT_ERROR_CODES: readonly ["invalid_prompt", "invalid_selector", "invalid_rule", "invalid_time_zone", "not_future", "time_out_of_range", "frequency_too_high", "subagent_session"];
110
+ export type ScheduleInputErrorCode = typeof SCHEDULE_INPUT_ERROR_CODES[number];
111
+ /** 任务的规则或目标会话不合规(同 0.12)。 */
112
+ export declare class ScheduleInputError extends Error {
113
+ readonly code: ScheduleInputErrorCode;
114
+ constructor(code: ScheduleInputErrorCode, message: string, options?: ErrorOptions);
115
+ }
116
+ /** 删除的请求(0.12 的 `ScheduleDeleteRequest`)。 */
117
+ export type ScheduleDeleteRequest = ScheduleTaskRequest;
118
+ /** 已安排的任务:宿主级的,可以往任意会话排,都不打开会话。 */
119
+ export interface ScheduleService {
120
+ /**
121
+ * 建一个绑定到会话的任务。
122
+ * @throws {ScheduleInputError} 规则不合规,或会话是子 agent 的(投递永远到不了)。
123
+ */
124
+ create(sessionId: string, request: ScheduleCreateRequest, signal?: AbortSignal): Promise<ScheduleRecord>;
125
+ /** 会话里进行中的任务,按存储顺序。 */
126
+ list(request: {
127
+ readonly sessionId: string;
128
+ }): Promise<ScheduleRecord[]>;
129
+ /** 全部会话的任务(各种状态,比 0.12 多 `paused`),按下一次的时刻、再按 id 排序。 */
130
+ catalog(): Promise<ScheduleCatalogEntry[]>;
131
+ /** 发送记录的一页,从新到旧;找不到任务或游标时是带 `code` 的结果。 */
132
+ history(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>;
133
+ /** 删除一个任务,已经排进会话的消息不动;找不到时 `deleted` 为 false。 */
134
+ delete(request: ScheduleDeleteRequest, signal?: AbortSignal): Promise<ScheduleDeleteResult>;
135
+ /** 先核对再修改;不合规、找不到或冲突时是不改动的结果,不抛错。 */
136
+ update(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<ScheduleUpdateResult>;
137
+ }
138
+ export declare const MANUAL_COMPACTION_ERROR_CODES: readonly ["busy", "cancelled", "changed", "summary", "commit", "persistence"];
139
+ export type ManualCompactionErrorCode = typeof MANUAL_COMPACTION_ERROR_CODES[number];
140
+ /** 压缩没做成(同 0.12)。宿主记事件时同步落盘,不会有 `persistence`。 */
141
+ export declare class ManualCompactionError extends Error {
142
+ readonly code: ManualCompactionErrorCode;
143
+ constructor(code: ManualCompactionErrorCode, message: string, options?: ErrorOptions);
144
+ }
145
+ /** 上下文压缩。`signal` 中止时抛它的原因;已经开始的压缩收到取消,在日志里照常收尾。 */
146
+ export interface CompactionService {
147
+ /**
148
+ * 会话空闲时压缩一次,阈值以下也压。期间的发送排进队列,结束后接着跑。
149
+ * @param sourceCommandId 记进压缩事件;这里不写命令事件。
150
+ * @returns 没有可压的历史时为 null。
151
+ * @throws {ManualCompactionError} 会话不空闲是 `busy`。
152
+ */
153
+ compactNow(sessionId: string, signal?: AbortSignal, sourceCommandId?: string): Promise<CompactionResult | null>;
154
+ /**
155
+ * 按触发原因判断要不要压缩。真的要摘要时要在进行中的一轮里(如 `agent/pre-step` 的监听者),否则以 `summary` 失败。
156
+ * @returns 没有压缩时为 null。
157
+ */
158
+ compactIfNeeded(sessionId: string, trigger: CompactionTrigger, signal?: AbortSignal): Promise<CompactionResult | null>;
159
+ }
160
+ declare module 'cordis' {
161
+ interface Context {
162
+ workspaceRegistry: WorkspaceRegistry;
163
+ goals: GoalService;
164
+ schedule: ScheduleService;
165
+ compaction: CompactionService;
166
+ }
167
+ }
@@ -0,0 +1,74 @@
1
+ /** 没有这个会话时报 `session/not-found` 的两个操作(同 0.12)。 */
2
+ export class WorkspaceUnknownSessionError extends Error {
3
+ sessionId;
4
+ constructor(sessionId, verb, options) {
5
+ super(`cannot ${verb} session '${sessionId}': live sessions and session persistence hold no such session`, options);
6
+ this.sessionId = sessionId;
7
+ this.name = 'WorkspaceUnknownSessionError';
8
+ }
9
+ }
10
+ /** 不带 `stopActivity` 归档时会话还有工作:什么都没写,`activity` 列出要先停下的(同 0.12)。 */
11
+ export class WorkspaceActiveSessionError extends Error {
12
+ sessionId;
13
+ activity;
14
+ constructor(sessionId, activity) {
15
+ super(`cannot archive session '${sessionId}': the session is active (${activity.map((entry) => entry.kind).join(', ')})`);
16
+ this.sessionId = sessionId;
17
+ this.activity = activity;
18
+ this.name = 'WorkspaceActiveSessionError';
19
+ }
20
+ }
21
+ /** 置顶已归档的会话(同 0.12):置顶与归档互斥。 */
22
+ export class WorkspaceArchivedSessionPinError extends Error {
23
+ sessionId;
24
+ constructor(sessionId, options) {
25
+ super(`cannot pin session '${sessionId}': the session is archived`, options);
26
+ this.sessionId = sessionId;
27
+ this.name = 'WorkspaceArchivedSessionPinError';
28
+ }
29
+ }
30
+ /** 排序时工作区或锚点不在登记里(同 0.12)。 */
31
+ export class WorkspaceOrderInvalidError extends Error {
32
+ workspaceId;
33
+ constructor(workspaceId, options) {
34
+ super(`cannot reorder unknown workspace '${workspaceId}'`, options);
35
+ this.workspaceId = workspaceId;
36
+ this.name = 'WorkspaceOrderInvalidError';
37
+ }
38
+ }
39
+ export const GOAL_ERROR_CODES = [
40
+ 'GOAL_AGENT_NOT_LIVE', 'GOAL_NOT_FOUND', 'GOAL_ALREADY_EXISTS', 'GOAL_STALE_REVISION', 'GOAL_INVALID_OBJECTIVE', 'GOAL_INVALID_MAX_ROUNDS',
41
+ 'GOAL_INVALID_BLOCK_REASON', 'GOAL_INVALID_EDIT', 'GOAL_INVALID_TRANSITION',
42
+ ];
43
+ /** 读写 Goal 被拒绝(同 0.12)。日志里的 Goal 记录不合规则、会话写不了时是普通的 Error。 */
44
+ export class GoalError extends Error {
45
+ code;
46
+ constructor(message, code, options) {
47
+ super(message, options);
48
+ this.code = code;
49
+ this.name = 'GoalError';
50
+ }
51
+ }
52
+ export const SCHEDULE_INPUT_ERROR_CODES = [
53
+ 'invalid_prompt', 'invalid_selector', 'invalid_rule', 'invalid_time_zone', 'not_future', 'time_out_of_range', 'frequency_too_high', 'subagent_session',
54
+ ];
55
+ /** 任务的规则或目标会话不合规(同 0.12)。 */
56
+ export class ScheduleInputError extends Error {
57
+ code;
58
+ constructor(code, message, options) {
59
+ super(message, options);
60
+ this.code = code;
61
+ this.name = 'ScheduleInputError';
62
+ }
63
+ }
64
+ export const MANUAL_COMPACTION_ERROR_CODES = ['busy', 'cancelled', 'changed', 'summary', 'commit', 'persistence'];
65
+ /** 压缩没做成(同 0.12)。宿主记事件时同步落盘,不会有 `persistence`。 */
66
+ export class ManualCompactionError extends Error {
67
+ code;
68
+ constructor(code, message, options) {
69
+ super(message, options);
70
+ this.code = code;
71
+ this.name = 'ManualCompactionError';
72
+ }
73
+ }
74
+ //# sourceMappingURL=platform.js.map
@@ -0,0 +1,51 @@
1
+ /**
2
+ * 对照表:0.12 写法(0.12 插件契约)的每项服务、扩展点与常用函数在 SDK 2.x 里的对应(docs/rust-host/architecture.md
3
+ * 「移植路径」)。插件契约文档里的对照表、codemod 的改写与插件运行时加载失败的提示都取自这里。
4
+ *
5
+ * 覆盖面由测试守住(tests/porting-table.test.ts):0.12 宿主的 255 项核心接口(tests/fixtures/dsh-core-surface.json,补齐的
6
+ * 方案与阶段见 docs/rust-host/plugin-parity.md)、0.12 契约的 17 项服务、现有 TS 插件与 0.12 模板用到的全部 0.12 导出、服务、
7
+ * 成员与扩展点都要有一行;写着 SDK 对应名字的行,SDK 里要真有这个导出。
8
+ *
9
+ * 0.12 是 dsh 0.2.1-alpha.2,表以它为准;也覆盖第三方插件实际依赖的 dsh 0.1.0-rc.7 到 0.2.2-rc.1(docs/rust-host/dsh-porting-plan.md
10
+ * 的 A5):形状与 0.12 不同的在说明里按版本写明(「dsh 0.2.2-rc.1 起…」),只在别的版本里有的服务也各有一行
11
+ * (tests/fixtures/dsh-services-versions.json)。
12
+ *
13
+ * 表里的 `@deepseek-ai/*` 是 0.12 插件里写的旧包名,仓库已不依赖这些包:留着是为了给按 0.12 写的第三方插件指出对应,
14
+ * codemod 也要按它们认出要改写的引用。
15
+ * @module @ftai/plugin-host-api/porting
16
+ */
17
+ /**
18
+ * - `same`:同名同形,换 import 即可(codemod 自动改);
19
+ * - `changed`:形状有变,`note` 写改法(codemod 只插 TODO,不改写;标了 `awaited`、`brand` 或名字不同的除外);
20
+ * - `removed`:不再提供,`note` 写替代;
21
+ * - `pending`:宿主还没有提供,`note` 写由哪个阶段提供(plugin-parity.md);在此之前用到这项服务的插件加载失败。
22
+ */
23
+ export type PortingStatus = 'same' | 'changed' | 'removed' | 'pending';
24
+ export interface PortingEntry {
25
+ /**
26
+ * 0.12 一侧:服务写成 `ctx.<服务名>`,服务的成员写成 `ctx.<服务名>.<成员>`,扩展点写成它的名字(如 `tools/pre-execute`),
27
+ * 包的导出写成 `<包名>#<导出名>`(默认导出写成 `<包名>#default`),类型上的成员写成 `<包名>#<类型>.<成员>`(如
28
+ * `@deepseek-ai/dsh-agent#Agent.cancel`),插件清单与入口的配置写成它的名字。
29
+ */
30
+ readonly legacy: string;
31
+ readonly status: PortingStatus;
32
+ /**
33
+ * SDK 一侧的对应:`@ftai/plugin-sdk/host#<导出名>`、`ctx.<服务名>`、`cordis#<导出名>` 或扩展点名;没有时不写。
34
+ * 导出名与 0.12 不同时,codemod 连引用一起改名。
35
+ */
36
+ readonly sdk?: string;
37
+ /** 改法、替代或由谁提供;同名同形时可以不写。 */
38
+ readonly note?: string;
39
+ /** 形状有变,但照 0.12 写的用法多数不用改(如载荷换成句柄、用法不变):codemod 不在用到它的地方插 TODO。 */
40
+ readonly todo?: false;
41
+ /**
42
+ * 同步读取跨进程后变成 Promise,codemod 自动加 `await`,所在函数改成 async;加不了的地方(顶层、构造函数、数组方法的回调等)
43
+ * 照旧插 TODO。`call` 是调用的结果,`read` 是读属性的结果。
44
+ */
45
+ readonly awaited?: 'call' | 'read';
46
+ /** 0.12 的品牌类型:值是包装函数,SDK 里就是字符串。codemod 去掉 `X(...)` 包装,import 改成只引类型。 */
47
+ readonly brand?: true;
48
+ }
49
+ export declare const PORTING_TABLE: readonly PortingEntry[];
50
+ /** 按 0.12 一侧的名字查一行。 */
51
+ export declare function portingOf(legacy: string): PortingEntry | undefined;