paseo-plugin-zcode-provider 0.4.4 → 0.5.1

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 (59) hide show
  1. package/NOTICE.md +2 -2
  2. package/README.md +18 -13
  3. package/client/account.tsx +13 -22
  4. package/client/goal-pills.ts +252 -0
  5. package/client/goal.tsx +203 -0
  6. package/index.client.tsx +4 -0
  7. package/index.server.ts +12 -4
  8. package/package.json +4 -4
  9. package/paseo-plugin.json +1 -1
  10. package/server/build-info.ts +1 -1
  11. package/server/diagnostics.ts +4 -1
  12. package/server/discovery/manifest.ts +2 -2
  13. package/server/errors.ts +1 -0
  14. package/server/goal-command.ts +32 -0
  15. package/server/goal.ts +58 -0
  16. package/server/host/bridge.ts +3 -0
  17. package/server/mapping.ts +23 -6
  18. package/server/presentation.ts +4 -1
  19. package/server/provider-status.ts +3 -3
  20. package/server/provider.ts +91 -21
  21. package/server/runtime/pins.ts +3 -3
  22. package/server/session.ts +278 -92
  23. package/server/turn-failure.ts +6 -1
  24. package/server/usage.ts +1 -3
  25. package/server/vendor/zcode/NOTICE.md +1 -1
  26. package/server/vendor/zcode/packages/rpc/src/channelClient.ts +18 -3
  27. package/server/vendor/zcode/packages/rpc/src/channelServer.ts +32 -12
  28. package/server/vendor/zcode/packages/rpc/src/channels.shared.ts +8 -1
  29. package/server/vendor/zcode/packages/rpc/src/serialization.ts +9 -3
  30. package/server/vendor/zcode/packages/shared/src/browser-use/command-metadata.ts +2 -0
  31. package/server/vendor/zcode/packages/shared/src/browser-use/commands.ts +2 -0
  32. package/server/vendor/zcode/packages/shared/src/browser-use/result.ts +4 -0
  33. package/server/vendor/zcode/packages/shared/src/gen-ui/contract.ts +246 -0
  34. package/server/vendor/zcode/packages/shared/src/gen-ui/tweakProtocol.ts +143 -0
  35. package/server/vendor/zcode/packages/shared/src/{localTtft.ts → local-ttft/contract.ts} +56 -1
  36. package/server/vendor/zcode/packages/shared/src/mcp-apps/contract.ts +8 -0
  37. package/server/vendor/zcode/packages/shared/src/official-mcp-auth.ts +8 -0
  38. package/server/vendor/zcode/packages/shared/src/protocol.ts +2 -0
  39. package/server/vendor/zcode/packages/shared/src/request-security-edition/verification-policy.ts +9 -1
  40. package/server/vendor/zcode/packages/shared/src/runtimeEnv.ts +10 -0
  41. package/server/vendor/zcode/packages/shared/src/server-remote.ts +2 -0
  42. package/server/vendor/zcode/packages/shared/src/source-server/compatibility.ts +11 -0
  43. package/server/vendor/zcode/packages/shared/src/source-server/contracts.ts +21 -1
  44. package/server/vendor/zcode/packages/shared/src/source-server/errorCodes.ts +27 -9
  45. package/server/vendor/zcode/packages/shared/src/subagent-profile.ts +5 -0
  46. package/server/vendor/zcode/packages/shared/src/validationAppSettings.ts +1 -0
  47. package/server/vendor/zcode/packages/shared/src/zcode-protocol/index.ts +164 -11
  48. package/server/vendor/zcode/packages/shared/src/zcode-protocol-legacy-types.ts +1 -0
  49. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/apply.ts +4 -2
  50. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/command.ts +11 -7
  51. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/delta.ts +2 -0
  52. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/input-intent.ts +2 -0
  53. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.ts +19 -1
  54. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.ts +11 -0
  55. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.ts +20 -1
  56. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-row-meta.ts +8 -0
  57. package/server/vendor/zcode/packages/ui/src/v4/conversationGoalSummaryModel.ts +88 -0
  58. package/server/vendor/zcode/provenance.json +78 -64
  59. package/shared/goal.ts +89 -0
@@ -194,6 +194,8 @@ export interface RemoteWorkspaceSessionSnapshot {
194
194
  lastConnectionStatus: "connected" | "failed";
195
195
  /** 最近一次失败原因;成功后清空 */
196
196
  lastConnectionError?: string;
197
+ /** 最近一次失败的错误码,与 lastConnectionError 同写同清;等待点也写成失败,只看文案分不清两类 */
198
+ lastConnectionErrorCode?: string;
197
199
  }
198
200
 
199
201
  export interface LocalWorkspaceSessionEntry {
@@ -11,6 +11,11 @@ export function readRequestVerificationConfig(
11
11
  ): RequestVerificationConfig | null {
12
12
  return null;
13
13
  }
14
+ export function readValidatedRequestVerificationConfig(
15
+ _configs: RequestVerificationClientConfig | null | undefined,
16
+ ): RequestVerificationConfig | null {
17
+ return null;
18
+ }
14
19
  export function requestVerificationClaimHeaders(
15
20
  _proof: RequestVerificationProof,
16
21
  ): Record<string, string> {
@@ -26,7 +31,10 @@ export function allowRequestVerificationHeaders(
26
31
  ): Record<string, string> {
27
32
  return {};
28
33
  }
29
- export function requiresRequestVerification(_access: { mode: string } | undefined): boolean {
34
+ export function requiresRequestVerification(
35
+ _access: { mode: string } | undefined,
36
+ _config?: RequestVerificationConfig | null,
37
+ ): boolean {
30
38
  return false;
31
39
  }
32
40
  export function isRequestVerificationMessage(_message: string): boolean {
@@ -12,6 +12,10 @@ export const ZCODE_TOOL_ENV_PASSTHROUGH_ENV_KEY = "ZCODE_TOOL_ENV_PASSTHROUGH_JS
12
12
  export const ZCODE_DESKTOP_CONTEXT_PROMPT_ENABLED_ENV = "ZCODE_DESKTOP_CONTEXT_PROMPT_ENABLED";
13
13
  export const ZCODE_CUA_PRODUCT_HELPER_ENV_KEY = "ZCODE_CUA_PRODUCT_HELPER";
14
14
  export const ZCODE_CUA_BROKER_SOCKET_ENV_KEY = "ZCODE_CUA_PERMISSION_BROKER_SOCKET";
15
+ // 官方命令端点(agent 侧代理,技术方案 5.8):地址与 session token 只由 agent 按 session 注入
16
+ // Bash/tool 子进程,不随 agent 全局 env 继承。
17
+ export const ZCODE_OFFICIAL_ENDPOINT_ENV_KEY = "ZCODE_OFFICIAL_ENDPOINT";
18
+ export const ZCODE_OFFICIAL_ENDPOINT_TOKEN_ENV_KEY = "ZCODE_OFFICIAL_ENDPOINT_TOKEN";
15
19
  /** Shared node_repl host marker; unlike the broker bearer values it is not a secret. */
16
20
  export const ZCODE_CUA_NODE_REPL_HOST_ENV_KEY = "ZCODE_CUA_NODE_REPL_HOST";
17
21
  // One-knob local-development bundle. Setting ZCODE_CUA_DEV_MODE implies the internal feature
@@ -70,6 +74,10 @@ const SANITIZED_RUNTIME_ENV_KEYS = [
70
74
  "ZCODE_CUA_PERMISSION_BROKER_TOKEN",
71
75
  "ZCODE_CUA_PERMISSION_BROKER_REFRESH_MARKER",
72
76
  "ZCODE_CUA_PLUGIN_AUTHORITY",
77
+ // 官方命令端点的地址与 token 属于某一个 session,由 agent 定向注入;从父进程继承来的
78
+ // 值(例如嵌套运行的 agent)一律剔除,避免一个 session 拿着另一个 session 的 token。
79
+ ZCODE_OFFICIAL_ENDPOINT_ENV_KEY,
80
+ ZCODE_OFFICIAL_ENDPOINT_TOKEN_ENV_KEY,
73
81
  // Agent OTLP Endpoint/Auth/Identity 只属于 CLI telemetry bootstrap,不能继续泄漏给
74
82
  // Bash、MCP 或模型工具子进程。sanitize 前会捕获到本进程私有 Map,供 Agent 启动边界读取。
75
83
  "OTEL_EXPORTER_OTLP_ENDPOINT",
@@ -101,6 +109,8 @@ const NON_TOOL_PASSTHROUGH_RUNTIME_ENV_KEYS = [
101
109
  ZCODE_CUA_BROKER_SOCKET_ENV_KEY,
102
110
  "ZCODE_CUA_PERMISSION_BROKER_REFRESH_MARKER",
103
111
  "ZCODE_CUA_PLUGIN_AUTHORITY",
112
+ ZCODE_OFFICIAL_ENDPOINT_ENV_KEY,
113
+ ZCODE_OFFICIAL_ENDPOINT_TOKEN_ENV_KEY,
104
114
  ZCODE_REMOTE_RUNTIME_NETWORK_AUTHORITY_ENV_KEY,
105
115
  ZCODE_REMOTE_HTTP_PROXY_ENV_KEY,
106
116
  ZCODE_REMOTE_NO_PROXY_ENV_KEY,
@@ -42,6 +42,7 @@ export const serverRemoteInfoSchema = z.object({
42
42
  virtualProjects: z.literal(true).optional(),
43
43
  // 旧 Server 缺少新增 dynamic event,必须先声明能力再订阅,避免异常打进对端读循环。
44
44
  processResourceTelemetry: z.boolean().optional(),
45
+ remoteConversationTelemetry: z.boolean().optional(),
45
46
  }),
46
47
  });
47
48
 
@@ -65,6 +66,7 @@ export const serverRemoteInfoOutputSchema = z
65
66
  virtualProjects: z.literal(true).optional(),
66
67
  // 输入和严格输出保持同一能力合同,否则新 Server 会在监听前被自身 schema 拒绝。
67
68
  processResourceTelemetry: z.boolean().optional(),
69
+ remoteConversationTelemetry: z.boolean().optional(),
68
70
  })
69
71
  .strict(),
70
72
  })
@@ -8,6 +8,17 @@ export const ZCODE_MIN_COMPATIBLE_VERSION =
8
8
  ? __ZCODE_MIN_COMPATIBLE_VERSION__
9
9
  : ZCODE_VERSION;
10
10
 
11
+ /**
12
+ * 远端服务支持设备卡停止 / 重启合同(`zcode stop --wait` 等,RDLC-01)的首个版本,桌面端据此做版本门禁。
13
+ * 取首个包含本合同的正式版 3.17.0。不提升最低兼容版本。
14
+ *
15
+ * Bug 原因:曾先后取 3.16.2(根版本占位)和 3.16.3(假设下一次发版包含本合同)。实际 v3.16.3 从 release 分支发布、
16
+ * 不含本合同,两次都等于已发布、不支持本合同的版本:旧 CLI 把 `stop --wait` 当成 ack 型 stop、把 `restart` 当成只换 Core,
17
+ * 桌面端收不到最终状态而报失败,但远端已执行停止或换 Core。
18
+ * 只看版本号区分不开开发中与已发布的同号版本,因此取实际首发版本;根版本升到 3.17.0 前开发构建也会显示禁用。
19
+ */
20
+ export const SOURCE_SERVER_LIFECYCLE_CONTROL_MIN_VERSION = "3.17.0";
21
+
11
22
  export const compatibilityManifestSchema = z
12
23
  .object({
13
24
  schemaVersion: z.literal(1),
@@ -127,11 +127,19 @@ export const sourceServerUpdateRequestSchema = z
127
127
  .object({
128
128
  profileId: nonEmptyStringSchema,
129
129
  force: z.boolean().optional(),
130
+ /** 用户已确认把较新的远端切换到本机 Desktop 版本;方向由远端 CLI 判定。 */
131
+ allowDowngrade: z.boolean().optional(),
130
132
  expectedTarget: sourceServerUpdateTargetSchema.optional(),
131
133
  })
132
134
  .strict();
133
135
  export type SourceServerUpdateRequest = z.input<typeof sourceServerUpdateRequestSchema>;
134
136
 
137
+ /**
138
+ * 设备级生命周期操作(停止、重启远端服务,RDLC-01)只接收设备身份;具体走哪条连接由 Host 路由,
139
+ * Renderer 不传 profileId。
140
+ */
141
+ export const sourceServerLifecycleSourceIdSchema = z.string().uuid();
142
+
135
143
  const connectionProfileBaseShape = {
136
144
  profileId: z.string().uuid(),
137
145
  sourceServerId: z.string().uuid().optional(),
@@ -302,6 +310,16 @@ export const sourceServerRunningTaskSchema = z
302
310
  export type SourceServerRunningTask = z.infer<typeof sourceServerRunningTaskSchema>;
303
311
  export const sourceServerRunningTasksSchema = z.array(sourceServerRunningTaskSchema);
304
312
 
313
+ /**
314
+ * 停止 / 重启远端服务确认前按设备读取的运行中任务(RDLC-01)。`available: false` 表示设备没有提供
315
+ * 可信清单(远端输出 null、命令失败或输出不符 schema),不能当作“没有任务”;空数组才是没有任务。
316
+ */
317
+ export const sourceServerRunningTasksResultSchema = z.discriminatedUnion("available", [
318
+ z.object({ available: z.literal(true), tasks: sourceServerRunningTasksSchema }).strict(),
319
+ z.object({ available: z.literal(false) }).strict(),
320
+ ]);
321
+ export type SourceServerRunningTasksResult = z.infer<typeof sourceServerRunningTasksResultSchema>;
322
+
305
323
  /** 只读安装预览;sizeBytes 是安装包实际大小,不代表解压后的磁盘占用。 */
306
324
  export const sourceServerInstallPreviewSchema = z
307
325
  .object({
@@ -323,6 +341,8 @@ export const sourceServerConnectionStateSnapshotSchema = z
323
341
  availableVersion: nonEmptyStringSchema.optional(),
324
342
  minimumVersion: nonEmptyStringSchema.optional(),
325
343
  upgradeTarget: z.enum(["controller", "server"]).optional(),
344
+ /** 远端当前 release 由显式降级安装时,被替换的版本;向导据此不自动升级。 */
345
+ downgradedFrom: nonEmptyStringSchema.optional(),
326
346
  errorCode: publicZCodeErrorCodeSchema.optional(),
327
347
  retryable: z.boolean().optional(),
328
348
  installPreview: sourceServerInstallPreviewSchema.optional(),
@@ -413,7 +433,7 @@ export type SourceServerInstallProgress = z.infer<typeof sourceServerInstallProg
413
433
  export const sourceServerOperationLogSchema = z
414
434
  .object({
415
435
  profileId: z.string().uuid(),
416
- operation: z.enum(["connect", "update"]),
436
+ operation: z.enum(["connect", "update", "stop", "restart"]),
417
437
  phase: nonEmptyStringSchema,
418
438
  level: z.enum(["info", "warn", "error"]),
419
439
  message: z.string(),
@@ -1,15 +1,14 @@
1
1
  import { z } from "zod";
2
2
 
3
- export const SOURCE_SERVER_INSTALL_REQUIRED_ERROR_CODE =
4
- "source-server-install-required" as const;
5
- export const SOURCE_SERVER_UPGRADE_REQUIRED_ERROR_CODE =
6
- "source-server-upgrade-required" as const;
3
+ export const SOURCE_SERVER_INSTALL_REQUIRED_ERROR_CODE = "source-server-install-required" as const;
4
+ export const SOURCE_SERVER_UPGRADE_REQUIRED_ERROR_CODE = "source-server-upgrade-required" as const;
7
5
  export const SOURCE_SERVER_UPDATE_RUNNING_TASKS_ERROR_CODE =
8
6
  "source-server-update-running-tasks" as const;
7
+ export const SOURCE_SERVER_DOWNGRADE_UNCONFIRMED_ERROR_CODE =
8
+ "source-server-downgrade-unconfirmed" as const;
9
9
  export const WORKSPACE_TASK_IDENTITY_CONFLICT_ERROR_CODE =
10
10
  "workspace-task-identity-conflict" as const;
11
- export const WORKSPACE_CONFIG_FILE_CONFLICT_ERROR_CODE =
12
- "workspace-config-file-conflict" as const;
11
+ export const WORKSPACE_CONFIG_FILE_CONFLICT_ERROR_CODE = "workspace-config-file-conflict" as const;
13
12
  export const WORKSPACE_MIGRATION_PLAN_DIVERGED_ERROR_CODE =
14
13
  "workspace-migration-plan-diverged" as const;
15
14
  export const WORKSPACE_SESSION_GENERATION_CHANGED_ERROR_CODE =
@@ -19,6 +18,14 @@ export const REMOTE_WORKSPACE_BIND_SESSION_MISSING_ERROR_CODE =
19
18
  "remote-workspace-bind-session-missing" as const;
20
19
  export const REMOTE_WORKSPACE_DIRECTORY_UNAVAILABLE_ERROR_CODE =
21
20
  "remote-workspace-directory-unavailable" as const;
21
+ /** 远端读取项目目录超过截止时间仍没有返回;目录本身未必不可用,可重试。 */
22
+ export const REMOTE_WORKSPACE_DIRECTORY_UNRESPONSIVE_ERROR_CODE =
23
+ "remote-workspace-directory-unresponsive" as const;
24
+ /**
25
+ * 打开远程项目目录(读取目录 + 登记身份)的截止时间,超时报
26
+ * REMOTE_WORKSPACE_DIRECTORY_UNRESPONSIVE_ERROR_CODE。Main 的 bind 兜底必须晚于它。
27
+ */
28
+ export const REMOTE_WORKSPACE_PREPARATION_TIMEOUT_MS = 30_000;
22
29
  export const REMOTE_RECOVERY_BUDGET_EXHAUSTED_ERROR_CODE =
23
30
  "remote-recovery-budget-exhausted" as const;
24
31
  export const SOURCE_SERVER_IDENTITY_CHANGE_PENDING_ERROR_CODE =
@@ -29,9 +36,16 @@ export const SOURCE_SERVER_REMOVE_CALLBACK_FAILED_ERROR_CODE =
29
36
  "source-server-remove-callback-failed" as const;
30
37
  export const SOURCE_SERVER_REMOVE_PERSIST_FAILED_ERROR_CODE =
31
38
  "source-server-remove-persist-failed" as const;
39
+ /** 远端 Supervisor 停止 Core 失败并进入 stop-failed,仍持有 data-root 锁(R2 §8.1)。 */
40
+ export const SOURCE_SERVER_STOP_FAILED_ERROR_CODE = "source-server-stop-failed" as const;
41
+ /** 远端 Supervisor 在 control 超时内没有应答;CLI 不强杀它(R2 §8.1)。 */
42
+ export const SOURCE_SERVER_CONTROL_UNRESPONSIVE_ERROR_CODE =
43
+ "source-server-control-unresponsive" as const;
32
44
 
33
45
  export const PUBLIC_ZCODE_ERROR_CODES = [
34
46
  "remote-authentication-failed",
47
+ // 服务器在密码之后还要求交互验证(例如动态口令);当前只支持密码、私钥与 SSH agent。
48
+ "remote-authentication-unsupported",
35
49
  "remote-host-unreachable",
36
50
  "remote-connection-timeout",
37
51
  "remote-host-not-found",
@@ -42,11 +56,14 @@ export const PUBLIC_ZCODE_ERROR_CODES = [
42
56
  "remote-install-failed",
43
57
  "remote-space-insufficient",
44
58
  "remote-permission-denied",
59
+ // 远端系统或架构不在支持范围(Windows 原生主机、非 x64/arm64);重试和改用直接下载都无效。
60
+ "remote-platform-unsupported",
45
61
  "remote-connection-canceled",
46
62
  "remote-connection-unknown",
47
63
  SOURCE_SERVER_INSTALL_REQUIRED_ERROR_CODE,
48
64
  SOURCE_SERVER_UPGRADE_REQUIRED_ERROR_CODE,
49
65
  SOURCE_SERVER_UPDATE_RUNNING_TASKS_ERROR_CODE,
66
+ SOURCE_SERVER_DOWNGRADE_UNCONFIRMED_ERROR_CODE,
50
67
  WORKSPACE_TASK_IDENTITY_CONFLICT_ERROR_CODE,
51
68
  WORKSPACE_CONFIG_FILE_CONFLICT_ERROR_CODE,
52
69
  WORKSPACE_MIGRATION_PLAN_DIVERGED_ERROR_CODE,
@@ -54,11 +71,14 @@ export const PUBLIC_ZCODE_ERROR_CODES = [
54
71
  REMOTE_BIND_CANCELED_ERROR_CODE,
55
72
  REMOTE_WORKSPACE_BIND_SESSION_MISSING_ERROR_CODE,
56
73
  REMOTE_WORKSPACE_DIRECTORY_UNAVAILABLE_ERROR_CODE,
74
+ REMOTE_WORKSPACE_DIRECTORY_UNRESPONSIVE_ERROR_CODE,
57
75
  REMOTE_RECOVERY_BUDGET_EXHAUSTED_ERROR_CODE,
58
76
  SOURCE_SERVER_IDENTITY_CHANGE_PENDING_ERROR_CODE,
59
77
  SOURCE_SERVER_REMOVE_CALLBACK_MISSING_ERROR_CODE,
60
78
  SOURCE_SERVER_REMOVE_CALLBACK_FAILED_ERROR_CODE,
61
79
  SOURCE_SERVER_REMOVE_PERSIST_FAILED_ERROR_CODE,
80
+ SOURCE_SERVER_STOP_FAILED_ERROR_CODE,
81
+ SOURCE_SERVER_CONTROL_UNRESPONSIVE_ERROR_CODE,
62
82
  ] as const;
63
83
 
64
84
  export type PublicZCodeErrorCode = (typeof PUBLIC_ZCODE_ERROR_CODES)[number];
@@ -67,8 +87,6 @@ export const publicZCodeErrorCodeSchema = z.enum(PUBLIC_ZCODE_ERROR_CODES);
67
87
 
68
88
  const publicZCodeErrorCodeSet = new Set<string>(PUBLIC_ZCODE_ERROR_CODES);
69
89
 
70
- export function isPublicZCodeErrorCode(
71
- value: unknown,
72
- ): value is PublicZCodeErrorCode {
90
+ export function isPublicZCodeErrorCode(value: unknown): value is PublicZCodeErrorCode {
73
91
  return typeof value === "string" && publicZCodeErrorCodeSet.has(value);
74
92
  }
@@ -18,6 +18,11 @@ export interface AgentProfile {
18
18
  name: string;
19
19
  path?: string;
20
20
  permissionMode?: AgentPermissionMode;
21
+ /**
22
+ * permissionMode 只能收紧父会话模式。插件 loader 在 CLI 进程内设置;
23
+ * 不进入下方跨进程 schema,若被跨边界发送,strict schema 会直接拒绝。
24
+ */
25
+ permissionModeRestrictOnly?: boolean;
21
26
  skills?: readonly string[];
22
27
  source: AgentProfileSource;
23
28
  systemPrompt: string;
@@ -141,6 +141,7 @@ const appWorkspaceSessionEntrySchema = z.discriminatedUnion("kind", [
141
141
  lastOpenedAt: z.number().int().nonnegative(),
142
142
  lastConnectionStatus: z.enum(["connected", "failed"]),
143
143
  lastConnectionError: z.string().optional(),
144
+ lastConnectionErrorCode: z.string().optional(),
144
145
  }),
145
146
  ]);
146
147
 
@@ -85,7 +85,10 @@ import { browserCommandResultSchema } from "../browser-use/result.js";
85
85
  import { appToolSearchModeSchema } from "../app-runtime-preferences.js";
86
86
  import { integratedTerminalShellSelectionSchema } from "../validationAppSettings.js";
87
87
  import { zcodeTaskModeSchema } from "../zcode-task-mode-schema.js";
88
- import { OFFICIAL_MCP_AUTH_PORT_FAILURE_REASONS } from "../official-mcp-auth.js";
88
+ import {
89
+ OFFICIAL_AUTH_CONSUMER_KINDS,
90
+ OFFICIAL_MCP_AUTH_PORT_FAILURE_REASONS,
91
+ } from "../official-mcp-auth.js";
89
92
  import {
90
93
  zcodeSyntheticUserMessageSourceSchema as legacyZcodeSyntheticUserMessageSourceSchema,
91
94
  zcodeDeliveryKindSchema,
@@ -110,7 +113,7 @@ import {
110
113
  zcodeWorkspaceRefSchema,
111
114
  } from "../zcode-protocol-legacy-types.js";
112
115
 
113
- export * from "../localTtft.js";
116
+ export * from "../local-ttft/contract.js";
114
117
  export {
115
118
  hookExecutionProjectionSchema,
116
119
  hookInvocationRowSchema,
@@ -130,9 +133,26 @@ export const ZCODE_PROTOCOL_VERSION = 1 as const;
130
133
  // V4 wire 与 legacy 主协议并存;禁止为了 V4 physical framing 改写 legacy 版本。
131
134
  export const ZCODE_PROTOCOL_V4_WIRE_VERSION = 3 as const;
132
135
  export const zcodeRuntimeCapabilitiesSchema = z.object({
136
+ sessionLifecycleWorkspace: z.boolean().optional(),
137
+ sessionDirectorySource: z.boolean().optional(),
138
+ sessionWorkspaceRouting: z.boolean().optional(),
139
+ genUiContext: z.boolean().optional(),
133
140
  historyFirst: z.boolean().optional(),
134
141
  independentPlanState: z.boolean().optional(),
142
+ /** CLI 认识 rowsRange 的 residency 参数;旧 CLI 会剥掉它并冷恢复,Host 据此拒绝转发。 */
143
+ residentRowsRange: z.boolean().optional(),
135
144
  });
145
+ export const zcodeRuntimeCapabilitiesParamsSchema = z
146
+ .object({
147
+ hostCapabilities: z
148
+ .object({
149
+ sessionDirectorySource: z.boolean().optional(),
150
+ sessionWorkspaceRouting: z.boolean().optional(),
151
+ })
152
+ .strict()
153
+ .optional(),
154
+ })
155
+ .strict();
136
156
  export const zcodeProtocolErrorCodes = {
137
157
  sessionUnavailable: -32004,
138
158
  } as const;
@@ -753,7 +773,9 @@ export const zcodeProtocolMcpServerSchema = z.union([
753
773
  z
754
774
  .object({
755
775
  name: nonEmptyString,
776
+ scope: z.enum(["user", "workspace"]).optional(),
756
777
  command: nonEmptyString,
778
+ cwd: nonEmptyString.optional(),
757
779
  args: z.array(z.string()),
758
780
  env: z.array(zcodeProtocolMcpEntrySchema),
759
781
  isolation: z.enum(["session", "workspace"]).optional(),
@@ -765,6 +787,7 @@ export const zcodeProtocolMcpServerSchema = z.union([
765
787
  z
766
788
  .object({
767
789
  name: nonEmptyString,
790
+ scope: z.enum(["user", "workspace"]).optional(),
768
791
  type: z.enum(["http", "sse"]),
769
792
  url: nonEmptyString,
770
793
  headers: z.array(zcodeProtocolMcpEntrySchema),
@@ -809,9 +832,38 @@ export const MCP_SERVER_FAILURE_KINDS = [
809
832
  ] as const;
810
833
  export const mcpServerFailureKindSchema = z.enum(MCP_SERVER_FAILURE_KINDS);
811
834
  export type McpServerFailureKind = z.infer<typeof mcpServerFailureKindSchema>;
835
+ export const workspaceMcpTrustReviewSchema = z
836
+ .object({
837
+ declarationDigest: z.string().regex(/^[a-f0-9]{64}$/u),
838
+ sourcePaths: z.array(nonEmptyString),
839
+ display: z.string(),
840
+ trusted: z.boolean(),
841
+ configuredEnabled: z.boolean(),
842
+ transport: z.enum(["stdio", "http", "sse"]),
843
+ })
844
+ .strict();
845
+ export type WorkspaceMcpTrustReview = z.infer<typeof workspaceMcpTrustReviewSchema>;
846
+ export const zcodeWorkspaceMcpTrustParamsSchema = z
847
+ .object({
848
+ workspace: zcodeWorkspaceRefSchema,
849
+ serverName: nonEmptyString,
850
+ declarationDigest: z.string().regex(/^[a-f0-9]{64}$/u),
851
+ trusted: z.boolean(),
852
+ })
853
+ .strict();
854
+ export const zcodeWorkspaceMcpTrustResultSchema = z
855
+ .object({
856
+ accepted: z.boolean(),
857
+ reasonCode: z
858
+ .enum(["workspace_mcp_declaration_changed", "workspace_mcp_trust_unavailable"])
859
+ .optional(),
860
+ })
861
+ .strict();
862
+ export type ZCodeWorkspaceMcpTrustResult = z.infer<typeof zcodeWorkspaceMcpTrustResultSchema>;
812
863
  export const zcodeMcpServerStatusSnapshotSchema = z
813
864
  .object({
814
865
  status: zcodeMcpServerStatusKindSchema,
866
+ workspaceTrust: workspaceMcpTrustReviewSchema.optional(),
815
867
  transport: z.enum(["stdio", "http", "sse"]),
816
868
  toolCount: z.number().int().nonnegative(),
817
869
  updatedAt: nonEmptyString,
@@ -1532,6 +1584,11 @@ export const zcodeTurnStartedEventPayloadSchema = z
1532
1584
  input: z.string(),
1533
1585
  inputId: nonEmptyString.optional(),
1534
1586
  queryId: nonEmptyString.optional(),
1587
+ // Bugfix:CLI 会把 Host 准入的后台执行归因写入 turn.started。这里漏声明时,
1588
+ // strict 校验会丢弃整条开始事件,复用中的 Bot 私聊订阅就无法切换到新轮次。
1589
+ automationId: nonEmptyString.optional(),
1590
+ offPeakTaskId: nonEmptyString.optional(),
1591
+ offPeakRunType: z.enum(["init", "resume"]).optional(),
1535
1592
  inputSource: zcodeTurnInputSourceSchema.optional(),
1536
1593
  inputVisibility: zcodeMessageVisibilitySchema.optional(),
1537
1594
  executionKind: z.enum(["agent", "controlOnly"]).optional(),
@@ -2059,7 +2116,7 @@ export {
2059
2116
  type SubagentRuntimeConfig,
2060
2117
  } from "../subagent-runtime-config.js";
2061
2118
  export const zcodeSubagentsReadRuntimeConfigParamsSchema = z
2062
- .object({ sessionId: nonEmptyString })
2119
+ .object({ sessionId: nonEmptyString, workspace: zcodeWorkspaceRefSchema.optional() })
2063
2120
  .strict();
2064
2121
 
2065
2122
  export const ZCODE_SESSION_RUNTIME_PREFERENCES_REQUEST_TIMEOUT_MS = 15_000;
@@ -2068,6 +2125,9 @@ export const zcodeSessionRequestRuntimePreferencesParamsSchema = z
2068
2125
  .object({
2069
2126
  sessionId: nonEmptyString,
2070
2127
  scope: zcodeSessionRuntimePreferencesScopeSchema,
2128
+ workspace: zcodeWorkspaceRefSchema.optional(),
2129
+ // CLI 依据持久化父链给出目录来源;目标 sessionId 仍保留 child 身份。
2130
+ directorySessionId: nonEmptyString.optional(),
2071
2131
  })
2072
2132
  .strict();
2073
2133
  export type ZCodeSessionRequestRuntimePreferencesParams = z.infer<
@@ -2716,6 +2776,7 @@ export type ZCodeBrowserListResult = z.infer<typeof zcodeBrowserListResultSchema
2716
2776
  /** Agent 把一条 browser-use 命令发送给 app 执行。 */
2717
2777
  export const zcodeBrowserExecuteParamsSchema = z
2718
2778
  .object({
2779
+ controlScopeId: nonEmptyString.optional(),
2719
2780
  requestId: nonEmptyString,
2720
2781
  sessionId: nonEmptyString,
2721
2782
  turnId: nonEmptyString.optional(),
@@ -2817,6 +2878,14 @@ export type ZCodeProviderRuntimeHeadersCancelled = z.infer<
2817
2878
  typeof zcodeProviderRuntimeHeadersCancelledSchema
2818
2879
  >;
2819
2880
 
2881
+ // 标准 JSON-RPC error 保留旧版 schema 兼容,不向严格校验的 response 增加字段。
2882
+ export const ZCODE_PROVIDER_CONFIG_NETWORK_ERROR = -32032;
2883
+
2884
+ export const zcodeProviderRuntimeHeadersErrorCode = {
2885
+ configNetwork: "request_verification_config_network",
2886
+ configInvalid: "request_verification_config_invalid",
2887
+ } as const;
2888
+
2820
2889
  export const zcodeProviderRuntimeHeadersResponseSchema = z.discriminatedUnion("headersApplied", [
2821
2890
  z
2822
2891
  .object({
@@ -2851,15 +2920,37 @@ export type ZCodeProviderRuntimeHeadersResponse = z.infer<
2851
2920
  // Agent 进程不是用户身份权威:它把 (pluginId, mcpKey, targetOrigin) 报给 host,由 host
2852
2921
  // 解析当前 Coding Plan 凭证并回传本次请求的身份头。请求侧不含任何秘密。
2853
2922
  // 与 interaction/requestProviderRuntimeHeaders 同类:Agent 发起、host 自动响应、零 UI。
2923
+ //
2924
+ // `consumer` 缺省为 `mcp-server`(旧版 agent 不带该字段),此时必须带 `mcpKey`;
2925
+ // `plugin-command` 是官方插件命令进程经 agent 代理端点发起的请求,没有 MCP,不带 `mcpKey`,
2926
+ // host 按「套餐可选」解析:没有套餐时只给 ZCode 登录身份(技术方案 5.8)。
2854
2927
  export const zcodeOfficialMcpAuthHeadersRequestParamsSchema = z
2855
2928
  .object({
2856
2929
  requestId: nonEmptyString,
2857
2930
  workspace: zcodeWorkspaceRefSchema,
2858
2931
  pluginId: nonEmptyString,
2859
- mcpKey: nonEmptyString,
2932
+ consumer: z.enum(OFFICIAL_AUTH_CONSUMER_KINDS).optional(),
2933
+ mcpKey: nonEmptyString.optional(),
2860
2934
  targetOrigin: nonEmptyString,
2861
2935
  })
2862
- .strict();
2936
+ .strict()
2937
+ .superRefine((params, ctx) => {
2938
+ const isCommand = params.consumer === "plugin-command";
2939
+ if (isCommand && params.mcpKey !== undefined) {
2940
+ ctx.addIssue({
2941
+ code: "custom",
2942
+ message: "plugin-command must not carry mcpKey",
2943
+ path: ["mcpKey"],
2944
+ });
2945
+ }
2946
+ if (!isCommand && params.mcpKey === undefined) {
2947
+ ctx.addIssue({
2948
+ code: "custom",
2949
+ message: "mcpKey is required for mcp-server",
2950
+ path: ["mcpKey"],
2951
+ });
2952
+ }
2953
+ });
2863
2954
  export type ZCodeOfficialMcpAuthHeadersRequestParams = z.infer<
2864
2955
  typeof zcodeOfficialMcpAuthHeadersRequestParamsSchema
2865
2956
  >;
@@ -3911,6 +4002,7 @@ export type ZCodeAutomationProtocol = z.infer<typeof zcodeAutomationProtocolSche
3911
4002
 
3912
4003
  export const zcodeAutomationCreateParamsSchema = z
3913
4004
  .object({
4005
+ workspace: zcodeWorkspaceRefSchema.optional(),
3914
4006
  title: z.string().optional(),
3915
4007
  cronExpr: nonEmptyString,
3916
4008
  relativeDelayMinutes: z.number().int().positive().max(525_600).optional(),
@@ -3954,6 +4046,7 @@ export type ZCodeAutomationCreateProtocolResult = z.infer<typeof zcodeAutomation
3954
4046
 
3955
4047
  export const zcodeAutomationUpdateParamsSchema = z
3956
4048
  .object({
4049
+ workspace: zcodeWorkspaceRefSchema.optional(),
3957
4050
  automationId: nonEmptyString,
3958
4051
  title: nonEmptyString.optional(),
3959
4052
  cronExpr: nonEmptyString.optional(),
@@ -4009,7 +4102,9 @@ export const zcodeAutomationUpdateResultSchema = z
4009
4102
  .strict();
4010
4103
  export type ZCodeAutomationUpdateProtocolResult = z.infer<typeof zcodeAutomationUpdateResultSchema>;
4011
4104
 
4012
- export const zcodeAutomationListParamsSchema = z.object({}).strict();
4105
+ export const zcodeAutomationListParamsSchema = z
4106
+ .object({ workspace: zcodeWorkspaceRefSchema.optional() })
4107
+ .strict();
4013
4108
  export type ZCodeAutomationListProtocolParams = z.infer<typeof zcodeAutomationListParamsSchema>;
4014
4109
  export const zcodeAutomationListResultSchema = z
4015
4110
  .object({ automations: z.array(zcodeAutomationProtocolSchema) })
@@ -4017,7 +4112,7 @@ export const zcodeAutomationListResultSchema = z
4017
4112
  export type ZCodeAutomationListProtocolResult = z.infer<typeof zcodeAutomationListResultSchema>;
4018
4113
 
4019
4114
  export const zcodeAutomationCheckTaskBindingParamsSchema = z
4020
- .object({ targetTaskId: nonEmptyString })
4115
+ .object({ workspace: zcodeWorkspaceRefSchema.optional(), targetTaskId: nonEmptyString })
4021
4116
  .strict();
4022
4117
  export type ZCodeAutomationCheckTaskBindingProtocolParams = z.infer<
4023
4118
  typeof zcodeAutomationCheckTaskBindingParamsSchema
@@ -4030,15 +4125,24 @@ export type ZCodeAutomationCheckTaskBindingProtocolResult = z.infer<
4030
4125
  >;
4031
4126
 
4032
4127
  export const zcodeAutomationDeleteParamsSchema = z
4033
- .object({ automationId: nonEmptyString })
4128
+ .object({ workspace: zcodeWorkspaceRefSchema.optional(), automationId: nonEmptyString })
4034
4129
  .strict();
4035
4130
  export type ZCodeAutomationDeleteProtocolParams = z.infer<typeof zcodeAutomationDeleteParamsSchema>;
4036
4131
  export const zcodeAutomationDeleteResultSchema = z.object({ deleted: z.boolean() }).strict();
4037
4132
  export type ZCodeAutomationDeleteProtocolResult = z.infer<typeof zcodeAutomationDeleteResultSchema>;
4038
4133
 
4134
+ // 执行轮自暂停(CronPauseSelf):automationId 来自 CLI loop state,Host 只在当前 workspace
4135
+ // 内做条件暂停(active 且 enabled 才转 paused)并回报是否生效。
4136
+ export const zcodeAutomationPauseParamsSchema = z
4137
+ .object({ workspace: zcodeWorkspaceRefSchema.optional(), automationId: nonEmptyString })
4138
+ .strict();
4139
+ export type ZCodeAutomationPauseProtocolParams = z.infer<typeof zcodeAutomationPauseParamsSchema>;
4140
+ export const zcodeAutomationPauseResultSchema = z.object({ paused: z.boolean() }).strict();
4141
+ export type ZCodeAutomationPauseProtocolResult = z.infer<typeof zcodeAutomationPauseResultSchema>;
4142
+
4039
4143
  // ---- Off-Peak(闲时任务)会话内创建协议----
4040
4144
  // 与 automation 兄弟并列(独立域,禁止互相复用标记/表)。workspace 由 host 端从
4041
- // 当前 session 注入,不进协议参数(对称 automation/create)。permissionMode 只开放产品
4145
+ // 当前 session 的已协商 workspace 注入。permissionMode 只开放产品
4042
4146
  // 四档词表(D29-4);缺省解析在 host 端(D49-4:yolo / allowed_models 末位 / 最高推理档)。
4043
4147
  export const zcodeOffPeakPermissionModeSchema = z.enum([
4044
4148
  "build",
@@ -4051,6 +4155,7 @@ export type ZCodeOffPeakProtocolPermissionMode = z.infer<typeof zcodeOffPeakPerm
4051
4155
 
4052
4156
  export const zcodeOffPeakCreateParamsSchema = z
4053
4157
  .object({
4158
+ workspace: zcodeWorkspaceRefSchema.optional(),
4054
4159
  title: nonEmptyString,
4055
4160
  prompt: nonEmptyString,
4056
4161
  permissionMode: zcodeOffPeakPermissionModeSchema.optional(),
@@ -4099,14 +4204,56 @@ export const zcodeOffPeakCreateResultSchema = z.discriminatedUnion("ok", [
4099
4204
  ]);
4100
4205
  export type ZCodeOffPeakCreateProtocolResult = z.infer<typeof zcodeOffPeakCreateResultSchema>;
4101
4206
 
4102
- export const zcodeOffPeakListParamsSchema = z.object({}).strict();
4207
+ export const zcodeOffPeakListParamsSchema = z
4208
+ .object({ workspace: zcodeWorkspaceRefSchema.optional() })
4209
+ .strict();
4103
4210
  export type ZCodeOffPeakListProtocolParams = z.infer<typeof zcodeOffPeakListParamsSchema>;
4104
4211
  export const zcodeOffPeakListResultSchema = z
4105
4212
  .object({ tasks: z.array(zcodeOffPeakTaskSnapshotSchema) })
4106
4213
  .strict();
4107
4214
  export type ZCodeOffPeakListProtocolResult = z.infer<typeof zcodeOffPeakListResultSchema>;
4108
4215
 
4216
+ // Session 运行实例生命周期;不同于 session/stop(停止生成)。
4217
+ export const sessionLifecycleParamsSchema = z.object({ sessionId: z.string().min(1) }).strict();
4218
+ export const sessionLifecycleActivationParamsSchema = sessionLifecycleParamsSchema.extend({
4219
+ workspace: zcodeWorkspaceRefSchema.optional(),
4220
+ });
4221
+ export const sessionLifecycleStateSchema = z.enum([
4222
+ "unloaded",
4223
+ "starting",
4224
+ "ready",
4225
+ "stopping",
4226
+ "faulted",
4227
+ ]);
4228
+ export const sessionLifecycleOperationSchema = z.enum(["ensureReady", "stop", "restart"]);
4229
+ export const sessionLifecycleFailureSchema = z
4230
+ .object({
4231
+ operation: sessionLifecycleOperationSchema,
4232
+ code: z.string(),
4233
+ message: z.string(),
4234
+ })
4235
+ .strict();
4236
+ export const sessionLifecycleSnapshotSchema = z
4237
+ .object({
4238
+ sessionId: z.string().min(1),
4239
+ state: sessionLifecycleStateSchema,
4240
+ generation: z.number().int().nonnegative().default(0),
4241
+ revision: z.number().int().nonnegative().default(0),
4242
+ lastError: sessionLifecycleFailureSchema.nullable(),
4243
+ })
4244
+ .strict();
4245
+ export const sessionLifecycleResultSchema = z.object({ completed: z.literal(true) }).strict();
4246
+ export type SessionLifecycleState = z.infer<typeof sessionLifecycleStateSchema>;
4247
+ export type SessionLifecycleOperation = z.infer<typeof sessionLifecycleOperationSchema>;
4248
+ export type SessionLifecycleFailure = z.infer<typeof sessionLifecycleFailureSchema>;
4249
+ export type SessionLifecycleSnapshot = z.infer<typeof sessionLifecycleSnapshotSchema>;
4250
+
4109
4251
  export const zcodeProtocolMethods = {
4252
+ sessionLifecycleChanged: "session/lifecycle/changed",
4253
+ sessionLifecycleGetState: "session/lifecycle/getState",
4254
+ sessionLifecycleEnsureReady: "session/lifecycle/ensureReady",
4255
+ sessionLifecycleStop: "session/lifecycle/stop",
4256
+ sessionLifecycleRestart: "session/lifecycle/restart",
4110
4257
  runtimeCapabilities: "runtime/capabilities",
4111
4258
  computerUseOperationEvent: "computer-use/operation-event",
4112
4259
  sessionCreate: "session/create",
@@ -4162,6 +4309,7 @@ export const zcodeProtocolMethods = {
4162
4309
  workspaceCancelGenerateText: "workspace/cancelGenerateText",
4163
4310
  providerTestModelConnectivity: "provider/testModelConnectivity",
4164
4311
  mcpList: "mcp/list",
4312
+ workspaceMcpTrust: "workspace/mcp/trust",
4165
4313
  mcpReadResource: "mcp/readResource",
4166
4314
  mcpUiOpenInstance: "mcp/uiOpenInstance",
4167
4315
  mcpUiCloseInstance: "mcp/uiCloseInstance",
@@ -4220,6 +4368,7 @@ export const zcodeProtocolMethods = {
4220
4368
  automationCheckTaskBinding: "automation/checkTaskBinding",
4221
4369
  automationList: "automation/list",
4222
4370
  automationDelete: "automation/delete",
4371
+ automationPause: "automation/pause",
4223
4372
  // Off-Peak 会话内创建:与 automation 兄弟并列的独立方法族。
4224
4373
  offPeakCreate: "offPeak/create",
4225
4374
  offPeakList: "offPeak/list",
@@ -4264,6 +4413,10 @@ export const zcodeProtocolSessionMethodContracts = {
4264
4413
  params: zcodeWorkspaceHookTrustGrantParamsSchema,
4265
4414
  result: zcodeWorkspaceHookTrustGrantResultSchema,
4266
4415
  },
4416
+ [zcodeProtocolMethods.workspaceMcpTrust]: {
4417
+ params: zcodeWorkspaceMcpTrustParamsSchema,
4418
+ result: zcodeWorkspaceMcpTrustResultSchema,
4419
+ },
4267
4420
  [zcodeProtocolMethods.mcpList]: {
4268
4421
  params: zcodeMcpListParamsSchema,
4269
4422
  result: zcodeMcpListResultSchema,
@@ -4365,7 +4518,7 @@ export const zcodeStoragePathReadySchema = z
4365
4518
  .strict();
4366
4519
 
4367
4520
  // 桌面本地 TTFT 的严格事实合同;检查点不能替代实际内容帧。
4368
- export { localTtftFactsSchema } from "../localTtft.js";
4521
+ export { localTtftFactsSchema } from "../local-ttft/contract.js";
4369
4522
  // 群来源由可信 Host 注入,V4 命令与持久化输入使用相同运行时校验。
4370
4523
  export {
4371
4524
  botIdentitySchema,
@@ -148,6 +148,7 @@ export const zcodeSessionGoalVerificationTimelineSchema = z
148
148
  export const zcodeSessionInfoSchema = z
149
149
  .object({
150
150
  sessionId: nonEmptyString,
151
+ directorySessionId: nonEmptyString.optional(),
151
152
  workspace: zcodeWorkspaceRefSchema,
152
153
  parentSessionId: nonEmptyString.optional(),
153
154
  traceId: nonEmptyString.optional(),
@@ -85,7 +85,9 @@ export function applyConversationDelta(
85
85
  },
86
86
  };
87
87
  case "row.upserted": {
88
- const index = snapshot.rows.window.findIndex(
88
+ // 窗口内 rowId 唯一(rows.ts:session 内单调、永不复用),从尾部查找与从头查找结果相同。
89
+ // upsert/delta 的目标几乎总是尾部的流式行;从头 findIndex 会让每条 delta 都扫描整段历史。
90
+ const index = snapshot.rows.window.findLastIndex(
89
91
  (row) => row.rowId === delta.row.rowId,
90
92
  );
91
93
  // §4.3:未加载 rowId = no-op(被逐出的行只能经 rows/range 取回)。
@@ -117,7 +119,7 @@ export function applyConversationDelta(
117
119
  };
118
120
  }
119
121
  case "row.delta": {
120
- const index = snapshot.rows.window.findIndex(
122
+ const index = snapshot.rows.window.findLastIndex(
121
123
  (row) => row.rowId === delta.rowId,
122
124
  );
123
125
  const target = snapshot.rows.window[index];