paseo-plugin-zcode-provider 0.4.3 → 0.5.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 (56) hide show
  1. package/NOTICE.md +2 -2
  2. package/README.md +20 -13
  3. package/client/account.tsx +13 -22
  4. package/client/settings.tsx +5 -1
  5. package/client/timeline.tsx +78 -0
  6. package/index.server.ts +10 -4
  7. package/package.json +4 -4
  8. package/paseo-plugin.json +1 -1
  9. package/server/build-info.ts +1 -1
  10. package/server/diagnostics.ts +100 -0
  11. package/server/discovery/manifest.ts +2 -2
  12. package/server/errors.ts +8 -0
  13. package/server/host/bridge.ts +3 -0
  14. package/server/mapping.ts +23 -6
  15. package/server/presentation.ts +8 -2
  16. package/server/provider-status.ts +3 -3
  17. package/server/provider.ts +25 -2
  18. package/server/runtime/pins.ts +3 -3
  19. package/server/session.ts +96 -32
  20. package/server/timeline-settings.ts +50 -0
  21. package/server/turn-failure.ts +116 -0
  22. package/server/usage.ts +1 -3
  23. package/server/vendor/zcode/NOTICE.md +1 -1
  24. package/server/vendor/zcode/packages/rpc/src/channelClient.ts +18 -3
  25. package/server/vendor/zcode/packages/rpc/src/channelServer.ts +32 -12
  26. package/server/vendor/zcode/packages/rpc/src/channels.shared.ts +8 -1
  27. package/server/vendor/zcode/packages/rpc/src/serialization.ts +9 -3
  28. package/server/vendor/zcode/packages/shared/src/browser-use/command-metadata.ts +2 -0
  29. package/server/vendor/zcode/packages/shared/src/browser-use/commands.ts +2 -0
  30. package/server/vendor/zcode/packages/shared/src/browser-use/result.ts +4 -0
  31. package/server/vendor/zcode/packages/shared/src/gen-ui/contract.ts +246 -0
  32. package/server/vendor/zcode/packages/shared/src/gen-ui/tweakProtocol.ts +143 -0
  33. package/server/vendor/zcode/packages/shared/src/{localTtft.ts → local-ttft/contract.ts} +56 -1
  34. package/server/vendor/zcode/packages/shared/src/mcp-apps/contract.ts +8 -0
  35. package/server/vendor/zcode/packages/shared/src/official-mcp-auth.ts +8 -0
  36. package/server/vendor/zcode/packages/shared/src/protocol.ts +2 -0
  37. package/server/vendor/zcode/packages/shared/src/request-security-edition/verification-policy.ts +9 -1
  38. package/server/vendor/zcode/packages/shared/src/runtimeEnv.ts +10 -0
  39. package/server/vendor/zcode/packages/shared/src/server-remote.ts +2 -0
  40. package/server/vendor/zcode/packages/shared/src/source-server/compatibility.ts +11 -0
  41. package/server/vendor/zcode/packages/shared/src/source-server/contracts.ts +21 -1
  42. package/server/vendor/zcode/packages/shared/src/source-server/errorCodes.ts +27 -9
  43. package/server/vendor/zcode/packages/shared/src/subagent-profile.ts +5 -0
  44. package/server/vendor/zcode/packages/shared/src/validationAppSettings.ts +1 -0
  45. package/server/vendor/zcode/packages/shared/src/zcode-protocol/index.ts +164 -11
  46. package/server/vendor/zcode/packages/shared/src/zcode-protocol-legacy-types.ts +1 -0
  47. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/apply.ts +4 -2
  48. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/command.ts +11 -7
  49. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/delta.ts +2 -0
  50. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/input-intent.ts +2 -0
  51. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.ts +19 -1
  52. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.ts +11 -0
  53. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.ts +20 -1
  54. package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-row-meta.ts +8 -0
  55. package/server/vendor/zcode/provenance.json +71 -63
  56. package/shared/timeline.ts +12 -0
@@ -28,6 +28,7 @@ export const enum ResponseType {
28
28
  PromiseError = 202,
29
29
  PromiseErrorObj = 203,
30
30
  EventFire = 204,
31
+ EventError = 205,
31
32
  }
32
33
 
33
34
  export type IRawResponse =
@@ -50,10 +51,16 @@ export type IRawResponse =
50
51
  taskId?: unknown;
51
52
  traceId?: unknown;
52
53
  retryable?: unknown;
54
+ profileId?: unknown;
53
55
  };
54
56
  }
55
57
  | { type: ResponseType.PromiseErrorObj; id: number; data: any }
56
- | { type: ResponseType.EventFire; id: number; data: any };
58
+ | { type: ResponseType.EventFire; id: number; data: any }
59
+ | {
60
+ type: ResponseType.EventError;
61
+ id: number;
62
+ data: { name: string; message: string; stack?: string[] };
63
+ };
57
64
 
58
65
  export type IHandler = (response: IRawResponse) => void;
59
66
 
@@ -217,11 +217,17 @@ export function deserialize(reader: IReader): any {
217
217
  }
218
218
  }
219
219
 
220
- function encodeRpcJsonValue(_key: string, value: unknown): unknown {
221
- if (value instanceof Uint8Array) {
220
+ function encodeRpcJsonValue(this: unknown, key: string, value: unknown): unknown {
221
+ // Bug 根因:JSON.stringify 先调用 toJSON 再调用 replacer。Node Buffer(Uint8Array 子类,技能 / 插件
222
+ // 归档都是 gzip 产出的 Buffer)到这里已被展开成 {type:"Buffer",data:[...]},不进 base64 标记:体积约 3.6 倍,
223
+ // 每一跳解码 1500 万个数字的数组(15MB 归档单跳十几秒,渲染进程卡住),约 28MB 以上的插件还超出远端
224
+ // WebSocket 单条消息 100MiB 上限;接收端拿到的是普通对象,归档大小检查读不到 byteLength。
225
+ // 修法:按 holder 上的原值判断是否为二进制。
226
+ const original = (this as Record<string, unknown>)[key];
227
+ if (original instanceof Uint8Array) {
222
228
  return {
223
229
  [RPC_NESTED_UINT8_ARRAY_MARKER]: true,
224
- [RPC_NESTED_UINT8_ARRAY_BASE64_KEY]: bytesToBase64(value),
230
+ [RPC_NESTED_UINT8_ARRAY_BASE64_KEY]: bytesToBase64(original),
225
231
  };
226
232
  }
227
233
  return value;
@@ -114,6 +114,8 @@ export const browserCommandMethodSchema = z.enum([
114
114
  "markDeliverable",
115
115
  "markHandoff",
116
116
  "nameSession",
117
+ "openScope",
118
+ "releaseScope",
117
119
  "turnEnded",
118
120
  "closeSession",
119
121
  "cancelRequest",
@@ -577,6 +577,8 @@ export const browserCommandSchema = z.discriminatedUnion("method", [
577
577
  deliverable: z.boolean().optional(),
578
578
  })
579
579
  .strict(),
580
+ z.object({ method: z.literal("openScope") }).strict(),
581
+ z.object({ method: z.literal("releaseScope"), closeTabs: z.boolean().optional() }).strict(),
580
582
  z.object({ method: z.literal("turnEnded"), turnId: z.string().min(1).optional() }).strict(),
581
583
  // closeTabs:连同该 session 名下的 tab 一起关(含已释放回该 session 的)。只给永不回来认领的
582
584
  // session 用——dwf 子代理(docs/browser-use/2026-07-14-browser-tab-conversation-isolation-spec.md §2.3)。
@@ -95,6 +95,10 @@ export type BrowserRecordingJob = z.infer<typeof browserRecordingJobSchema>;
95
95
  export const browserCommandResultSchema = z
96
96
  .object({
97
97
  ok: z.boolean(),
98
+ scope: z
99
+ .object({ id: z.string().min(1), state: z.enum(["open", "released", "absent", "rejected"]) })
100
+ .strict()
101
+ .optional(),
98
102
  state: browserPageStateSchema.optional(),
99
103
  snapshot: browserSnapshotSchema.optional(),
100
104
  image: z
@@ -0,0 +1,246 @@
1
+ import { z } from "zod";
2
+ export * from "./tweakProtocol.js";
3
+
4
+ export const GEN_UI_HTML_MAX_BYTES = 5_000_000;
5
+ export const GEN_UI_STATE_MAX_BYTES = 16 * 1024;
6
+ export const GEN_UI_STATE_MAX_ENTRIES = 100;
7
+ export const GEN_UI_CONTEXT_MAX_BYTES = 64 * 1024;
8
+ export const GEN_UI_GLOBALS_EVENT = "zcode:set_globals";
9
+ export const GEN_UI_STATE_CONTEXT_KEY = "zcode/genUiState";
10
+ export const GEN_UI_TWEAK_CONTEXT_KEY = "zcode/genUiTweaks";
11
+ export const GEN_UI_STYLE_CONTEXT_KEY = "zcode/genUiStyles";
12
+ export const genUiStyleVariablesSchema = z.record(
13
+ z.string().regex(/^--gen-ui-[a-z-]+$/),
14
+ z.string(),
15
+ );
16
+ export const GEN_UI_STATE_METHOD = "zcode/gen-ui/state";
17
+ export const GEN_UI_FOLLOW_UP_METHOD = "zcode/gen-ui/follow-up";
18
+ export const GEN_UI_TWEAK_METHOD = "zcode/gen-ui/tweak";
19
+ export const GEN_UI_PRESENTATION_METHOD = "zcode/gen-ui/presentation";
20
+ export const GEN_UI_STATIC_DOMAINS = [
21
+ "cdnjs.cloudflare.com",
22
+ "esm.sh",
23
+ "cdn.jsdelivr.net",
24
+ "unpkg.com",
25
+ "fonts.googleapis.com",
26
+ "fonts.gstatic.com",
27
+ "fonts.bunny.net",
28
+ // 自有 CDN:visualize/gen-ui 页面引用 zcode.z.ai 上的图片等静态资源(与上面公共 CDN 同走 resourceDomains,
29
+ // 会同时进 img/script/style/media/font 五类 src,可控性高于公共 CDN)
30
+ "zcode.z.ai",
31
+ ] as const;
32
+
33
+ /** This is a wire-format check. The executor owns normalization and filesystem authorization. */
34
+ export const genUiPathSchema = z
35
+ .string()
36
+ .min(1)
37
+ .max(4096)
38
+ .refine((path) => {
39
+ if (path.includes("\0") || /[\r\n]/u.test(path)) return false;
40
+ const segments = path.split(/[\\/]/u);
41
+ return (
42
+ /^(?:\/|[A-Za-z]:[\\/]|\\\\)/u.test(path) &&
43
+ !segments.includes("..") &&
44
+ /^[a-z0-9]+(?:-[a-z0-9]+)*\.html$/u.test(segments.at(-1) ?? "")
45
+ );
46
+ }, "Expected an absolute executor path to a lowercase-hyphenated HTML file");
47
+ export const genUiReferenceSchema = z
48
+ .object({
49
+ path: genUiPathSchema,
50
+ title: z.string().max(250).optional(),
51
+ mode: z.enum(["wide"]).optional(),
52
+ })
53
+ .strict();
54
+ export type GenUiReference = z.infer<typeof genUiReferenceSchema>;
55
+
56
+ export const genUiScopeSchema = z
57
+ .object({
58
+ workspacePath: z.string().min(1).max(4096),
59
+ workspaceIdentity: z.string().max(4096).optional(),
60
+ sessionId: z.string().min(1).max(512),
61
+ })
62
+ .strict();
63
+ export type GenUiScope = z.infer<typeof genUiScopeSchema>;
64
+ export const genUiStateTargetSchema = genUiScopeSchema.extend({ path: genUiPathSchema });
65
+ export type GenUiStateTarget = z.infer<typeof genUiStateTargetSchema>;
66
+
67
+ function serializeJson(value: unknown): string {
68
+ return JSON.stringify(value, (_key, item: unknown) => {
69
+ if (
70
+ typeof item === "undefined" ||
71
+ typeof item === "function" ||
72
+ typeof item === "symbol" ||
73
+ typeof item === "bigint" ||
74
+ (typeof item === "number" && !Number.isFinite(item))
75
+ ) {
76
+ throw new Error("Widget state must contain JSON values only");
77
+ }
78
+ return item;
79
+ });
80
+ }
81
+ export const genUiWidgetStateSchema = z
82
+ .object({
83
+ modelContent: z.unknown().default(null),
84
+ privateContent: z.unknown().default(null),
85
+ })
86
+ .strict()
87
+ .transform((state, context) => {
88
+ try {
89
+ const serialized = serializeJson(state);
90
+ if (new TextEncoder().encode(serialized).byteLength > GEN_UI_STATE_MAX_BYTES) {
91
+ throw new Error("Widget state exceeds 16 KiB");
92
+ }
93
+ return JSON.parse(serialized) as { modelContent: unknown; privateContent: unknown };
94
+ } catch (error) {
95
+ context.addIssue({
96
+ code: "custom",
97
+ message: error instanceof Error ? error.message : "Invalid widget state",
98
+ });
99
+ return z.NEVER;
100
+ }
101
+ });
102
+ export type GenUiWidgetState = z.infer<typeof genUiWidgetStateSchema>;
103
+ export const genUiFollowUpSchema = z
104
+ .object({
105
+ prompt: z
106
+ .string()
107
+ .trim()
108
+ .min(1)
109
+ .max(64 * 1024),
110
+ title: z.string().max(250).optional(),
111
+ })
112
+ .strict();
113
+
114
+ export interface GenUiDocument {
115
+ path: string;
116
+ html: string;
117
+ }
118
+ const controlBase = {
119
+ id: z.string().regex(/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/),
120
+ label: z.string().min(1).max(120),
121
+ reference: z
122
+ .string()
123
+ .regex(/^[\w./:@$#-]{1,160}$/u)
124
+ .optional(),
125
+ };
126
+ export const genUiTweakControlSchema = z.discriminatedUnion("type", [
127
+ z
128
+ .object({
129
+ ...controlBase,
130
+ type: z.literal("slider"),
131
+ value: z.number().finite(),
132
+ min: z.number().finite(),
133
+ max: z.number().finite(),
134
+ step: z.number().positive().optional(),
135
+ unit: z.string().max(24).optional(),
136
+ })
137
+ .strict(),
138
+ z
139
+ .object({
140
+ ...controlBase,
141
+ type: z.literal("color"),
142
+ value: z.string().regex(/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i),
143
+ })
144
+ .strict(),
145
+ z.object({ ...controlBase, type: z.literal("toggle"), value: z.boolean() }).strict(),
146
+ z
147
+ .object({
148
+ ...controlBase,
149
+ type: z.literal("select"),
150
+ value: z.string().max(120),
151
+ options: z
152
+ .array(
153
+ z.union([
154
+ z.string().min(1).max(120),
155
+ z.object({ label: z.string().min(1).max(120), value: z.string().max(120) }).strict(),
156
+ ]),
157
+ )
158
+ .min(1)
159
+ .max(12),
160
+ })
161
+ .strict(),
162
+ ]);
163
+ export const genUiTweakSchema = z
164
+ .object({
165
+ title: z.string().min(1).max(120),
166
+ controls: z.array(genUiTweakControlSchema).min(1).max(12),
167
+ })
168
+ .strict()
169
+ .superRefine((input, ctx) => {
170
+ const ids = new Set<string>();
171
+ for (const control of input.controls) {
172
+ if (
173
+ ids.has(control.id) ||
174
+ (control.type === "slider" &&
175
+ (control.min >= control.max ||
176
+ control.value < control.min ||
177
+ control.value > control.max)) ||
178
+ (control.type === "select" &&
179
+ !control.options.some(
180
+ (option) => (typeof option === "string" ? option : option.value) === control.value,
181
+ ))
182
+ )
183
+ ctx.addIssue({ code: "custom", message: "Invalid or duplicate tweak control" });
184
+ ids.add(control.id);
185
+ }
186
+ });
187
+ export type GenUiTweak = z.infer<typeof genUiTweakSchema>;
188
+ export type GenUiTweakValues = Record<string, string | number | boolean>;
189
+ export interface GenUiStateEntry {
190
+ path: string;
191
+ state: GenUiWidgetState;
192
+ }
193
+ export interface GenUiStateChange {
194
+ target: GenUiStateTarget;
195
+ state: GenUiWidgetState | null;
196
+ }
197
+ export function buildGenUiScopeKey(scope: GenUiScope): string {
198
+ return JSON.stringify([scope.workspaceIdentity?.trim() || scope.workspacePath, scope.sessionId]);
199
+ }
200
+ export function buildGenUiStateKey(target: GenUiStateTarget): string {
201
+ return JSON.stringify([buildGenUiScopeKey(target), target.path]);
202
+ }
203
+ export function selectGenUiModelContext(entries: readonly GenUiStateEntry[]): GenUiModelContext {
204
+ const selected: GenUiModelContext = [];
205
+ for (const entry of [...entries]
206
+ .sort((a, b) => a.path.localeCompare(b.path))
207
+ .slice(0, GEN_UI_STATE_MAX_ENTRIES)) {
208
+ const parsed = genUiWidgetStateSchema.safeParse(entry.state);
209
+ if (!parsed.success || parsed.data.modelContent === null) continue;
210
+ const next = { path: entry.path, state: parsed.data.modelContent };
211
+ if (
212
+ new TextEncoder().encode(JSON.stringify([...selected, next])).length >
213
+ GEN_UI_CONTEXT_MAX_BYTES
214
+ )
215
+ break;
216
+ selected.push(next);
217
+ }
218
+ return genUiModelContextSchema.parse(selected);
219
+ }
220
+
221
+ export const genUiModelContextSchema = z
222
+ .array(z.object({ path: genUiPathSchema, state: z.unknown() }).strict())
223
+ .max(GEN_UI_STATE_MAX_ENTRIES)
224
+ .transform((entries, context) => {
225
+ try {
226
+ const serialized = serializeJson(entries);
227
+ if (
228
+ new TextEncoder().encode(serialized).byteLength > GEN_UI_CONTEXT_MAX_BYTES ||
229
+ entries.some(
230
+ (entry) =>
231
+ new TextEncoder().encode(serializeJson(entry.state)).byteLength >
232
+ GEN_UI_STATE_MAX_BYTES,
233
+ )
234
+ ) {
235
+ throw new Error("Gen UI model context exceeds its size limit");
236
+ }
237
+ return JSON.parse(serialized) as Array<{ path: string; state: unknown }>;
238
+ } catch (error) {
239
+ context.addIssue({
240
+ code: "custom",
241
+ message: error instanceof Error ? error.message : "Invalid Gen UI model context",
242
+ });
243
+ return z.NEVER;
244
+ }
245
+ });
246
+ export type GenUiModelContext = z.infer<typeof genUiModelContextSchema>;
@@ -0,0 +1,143 @@
1
+ import { z } from "zod";
2
+
3
+ const value = z.union([z.string(), z.number().finite(), z.boolean()]);
4
+ const base = {
5
+ callback: z.string().min(1).max(128),
6
+ label: z.string().min(1).max(120),
7
+ reference: z.string().max(160).optional(),
8
+ };
9
+ export const genUiAnnotationControlSchema = z.discriminatedUnion("type", [
10
+ z
11
+ .object({
12
+ ...base,
13
+ type: z.literal("range"),
14
+ currentValue: z.number().finite(),
15
+ min: z.number().finite(),
16
+ max: z.number().finite(),
17
+ step: z.number().positive(),
18
+ })
19
+ .strict(),
20
+ z
21
+ .object({
22
+ ...base,
23
+ type: z.literal("color"),
24
+ currentValue: z.string().regex(/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i),
25
+ })
26
+ .strict(),
27
+ z.object({ ...base, type: z.literal("toggle"), currentValue: z.boolean() }).strict(),
28
+ z
29
+ .object({
30
+ ...base,
31
+ type: z.literal("select"),
32
+ currentValue: z.string().max(120),
33
+ options: z
34
+ .array(z.object({ label: z.string().min(1).max(120), value: z.string().max(120) }).strict())
35
+ .min(1)
36
+ .max(12),
37
+ })
38
+ .strict(),
39
+ ]);
40
+ export type GenUiAnnotationControl = z.infer<typeof genUiAnnotationControlSchema>;
41
+ export function isGenUiAnnotationValue(
42
+ control: GenUiAnnotationControl,
43
+ candidate: unknown,
44
+ ): candidate is string | number | boolean {
45
+ switch (control.type) {
46
+ case "range":
47
+ return (
48
+ typeof candidate === "number" &&
49
+ Number.isFinite(candidate) &&
50
+ candidate >= control.min &&
51
+ candidate <= control.max
52
+ );
53
+ case "color":
54
+ return (
55
+ typeof candidate === "string" &&
56
+ /^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(candidate)
57
+ );
58
+ case "toggle":
59
+ return typeof candidate === "boolean";
60
+ case "select":
61
+ return (
62
+ typeof candidate === "string" &&
63
+ control.options.some((option) => option.value === candidate)
64
+ );
65
+ }
66
+ }
67
+ const annotationControls = z
68
+ .object({
69
+ controlsMode: z.literal("replace"),
70
+ controls: z.array(genUiAnnotationControlSchema).min(1).max(12),
71
+ })
72
+ .strict()
73
+ .superRefine((input, ctx) => {
74
+ const callbacks = new Set(input.controls.map((control) => control.callback));
75
+ if (
76
+ callbacks.size !== input.controls.length ||
77
+ input.controls.some((control) => !isGenUiAnnotationValue(control, control.currentValue)) ||
78
+ JSON.stringify(input).length > 16384
79
+ ) {
80
+ ctx.addIssue({ code: "custom", message: "Invalid annotation controls" });
81
+ }
82
+ });
83
+ const target = z
84
+ .object({
85
+ id: z.string().min(1).max(128),
86
+ label: z.string().min(1).max(80),
87
+ selector: z.string().max(1024),
88
+ tagName: z.string().min(1).max(120),
89
+ rect: z
90
+ .object({
91
+ x: z.number().finite(),
92
+ y: z.number().finite(),
93
+ width: z.number().nonnegative(),
94
+ height: z.number().nonnegative(),
95
+ })
96
+ .strict(),
97
+ })
98
+ .strict();
99
+ const registration = {
100
+ registrationId: z.string().min(1).max(128),
101
+ annotationControls,
102
+ targets: z.array(target).length(1),
103
+ };
104
+ export const genUiTweakMessageSchema = z.discriminatedUnion("type", [
105
+ z.object({ type: z.literal("register"), ...registration }).strict(),
106
+ z.object({ type: z.literal("update"), ...registration }).strict(),
107
+ z.object({ type: z.literal("dispose"), registrationId: registration.registrationId }).strict(),
108
+ z
109
+ .object({
110
+ type: z.literal("select"),
111
+ registrationId: registration.registrationId,
112
+ targetId: target.shape.id,
113
+ })
114
+ .strict(),
115
+ z.object({ type: z.literal("escape") }).strict(),
116
+ ]);
117
+ export type GenUiTweakMessage = z.infer<typeof genUiTweakMessageSchema>;
118
+ export const genUiTweakResultSchema = z
119
+ .object({ annotationControls: annotationControls.optional() })
120
+ .strict();
121
+ export type GenUiTweakResult = z.infer<typeof genUiTweakResultSchema>;
122
+ export const genUiTweakAnnotationSchema = z
123
+ .object({
124
+ active: z.boolean(),
125
+ selection: z
126
+ .object({ registrationId: registration.registrationId, targetId: target.shape.id })
127
+ .nullable(),
128
+ changes: z
129
+ .array(
130
+ z
131
+ .object({
132
+ registrationId: registration.registrationId,
133
+ targetId: target.shape.id,
134
+ annotationControlChanges: z
135
+ .array(z.object({ callback: base.callback, previousValue: value, value }).strict())
136
+ .max(12),
137
+ })
138
+ .strict(),
139
+ )
140
+ .max(64),
141
+ })
142
+ .strict();
143
+ export type GenUiTweakAnnotation = z.infer<typeof genUiTweakAnnotationSchema>;
@@ -44,7 +44,12 @@ export const LOCAL_TTFT_CLOCK_TTL_MS = 60_000;
44
44
  const time = z.number().finite().nonnegative();
45
45
  const identifier = z.string().min(1).max(128);
46
46
  export const localTtftContextSchema = z
47
- .object({ version: z.literal(1), observationId: z.string().uuid() })
47
+ .object({
48
+ version: z.literal(1),
49
+ observationId: z.string().uuid(),
50
+ // 本地默认采集不能顺带开启云端;在一次发送开始时冻结出口选择。
51
+ localOnly: z.literal(true).optional(),
52
+ })
48
53
  .strict();
49
54
  export type LocalTtftContext = z.infer<typeof localTtftContextSchema>;
50
55
  export const localTtftClockSchema = z
@@ -123,6 +128,7 @@ export const localTtftRecordSchema = z
123
128
  .object({
124
129
  version: z.literal(1),
125
130
  observationId: z.string().uuid(),
131
+ localOnly: z.literal(true).optional(),
126
132
  commandId: identifier.optional(),
127
133
  sessionId: identifier.optional(),
128
134
  turnId: identifier.optional(),
@@ -190,3 +196,52 @@ export type LocalTtftBatch = z.infer<typeof localTtftBatchSchema>;
190
196
  export function localTtftNow(): number {
191
197
  return performance.timeOrigin + performance.now();
192
198
  }
199
+
200
+ /** 有界异步诊断队列;文件 I/O 由宿主 adapter 注入,不参与业务等待。 */
201
+ export function createLocalTtftLogQueue(
202
+ write: (entries: readonly { path: string; line: string }[], dropped: number) => Promise<void>,
203
+ maxChars = 262_144,
204
+ ) {
205
+ let entries: { path: string; line: string }[] = [];
206
+ let chars = 0;
207
+ let dropped = 0;
208
+ let draining: Promise<void> | undefined;
209
+ const drain = async () => {
210
+ while (entries.length) {
211
+ const batch = entries;
212
+ entries = [];
213
+ chars = 0;
214
+ try {
215
+ await write(batch, dropped);
216
+ } catch {
217
+ dropped += batch.length;
218
+ }
219
+ }
220
+ };
221
+ const schedule = () => {
222
+ draining ??= Promise.resolve()
223
+ .then(drain)
224
+ .finally(() => {
225
+ draining = undefined;
226
+ // drain 的 Promise 收口前仍可能有新记录进入,不能让它等下一次业务日志才落盘。
227
+ if (entries.length) schedule();
228
+ });
229
+ };
230
+ return {
231
+ enqueue(entry: { path: string; line: string }): void {
232
+ if (chars + entry.line.length > maxChars) {
233
+ dropped++;
234
+ return;
235
+ }
236
+ entries.push(entry);
237
+ chars += entry.line.length;
238
+ schedule();
239
+ },
240
+ async flush(): Promise<void> {
241
+ while (draining) await draining;
242
+ },
243
+ get dropped(): number {
244
+ return dropped;
245
+ },
246
+ };
247
+ }
@@ -98,6 +98,8 @@ export interface McpAppResourceMeta {
98
98
  heightHint?: number;
99
99
  minFrameHeight?: number;
100
100
  showInline?: boolean;
101
+ /** 资源级显式后台保留申请;缺省不保留,实际回收由宿主裁决。 */
102
+ backgroundRetention?: boolean;
101
103
  }
102
104
  /** 随沙箱句柄回到 renderer 的资源级呈现信息;CSP 与放宽只在 main 生效,不回传。 */
103
105
  export type PluginSandboxResourceMeta = Omit<McpAppResourceMeta, "csp" | "cspRelaxations">;
@@ -152,6 +154,11 @@ export {
152
154
  export const MCP_APPS_WIDGET_STATE_EXPERIMENTAL_KEY = "zcode/widgetState";
153
155
  export const MCP_APPS_RESOURCE_SUBSCRIBE_EXPERIMENTAL_KEY = "zcode/resourceSubscribe";
154
156
  export const MCP_APPS_SURFACE_EXPERIMENTAL_KEY = "zcode/surface";
157
+ /**
158
+ * 宿主允许插件文档内部创建子 frame(srcdoc / about:blank 预览、声明的 frameDomains)而不把它当作页面重载撤销实例。
159
+ * 旧宿主会在子 frame 导航时停止页面;需要嵌套预览的插件据此键降级,而不是创建 frame 后被释放。
160
+ */
161
+ export const MCP_APPS_NESTED_FRAMES_EXPERIMENTAL_KEY = "zcode/nestedFrames";
155
162
  /**
156
163
  * ZCode 扩展方法 `ui/set-widget-state { widgetState }`(MCP Apps 无 widgetState):页面把界面状态交给宿主
157
164
  * renderer 内存保存(不持久化,会话内重挂载可恢复);初值经 hostContext 的 `zcode/widgetState` 键随握手下发。
@@ -245,6 +252,7 @@ export interface PluginSandboxRegisterRequestPayload {
245
252
  minFrameHeight?: number;
246
253
  /** 资源级强制常驻标记,随句柄 resourceMeta 回 renderer。 */
247
254
  showInline?: boolean;
255
+ backgroundRetention?: boolean;
248
256
  }
249
257
  /** host 内部使用的登记输入:去掉传输层 requestId。 */
250
258
  export type PluginSandboxRegisterInput = Omit<PluginSandboxRegisterRequestPayload, "requestId">;
@@ -93,6 +93,14 @@ export const OFFICIAL_MCP_AUTH_PORT_FAILURE_REASONS = [
93
93
  export type OfficialMcpAuthPortFailureReason =
94
94
  (typeof OFFICIAL_MCP_AUTH_PORT_FAILURE_REASONS)[number];
95
95
 
96
+ /**
97
+ * 身份头的消费方类型。`mcp-server` 是官方 MCP(缺省,旧版 agent 不带该字段);
98
+ * `plugin-command` 是官方插件的命令进程,经 agent 侧代理端点访问 zcode-server(技术方案 5.8)。
99
+ */
100
+ export const OFFICIAL_AUTH_CONSUMER_KINDS = ["mcp-server", "plugin-command"] as const;
101
+
102
+ export type OfficialAuthConsumerKind = (typeof OFFICIAL_AUTH_CONSUMER_KINDS)[number];
103
+
96
104
  /** MCP adapter 侧的完整失败分类,包含网络层结果。仅用于 record status 与日志。 */
97
105
  export type OfficialMcpAuthFailureKind =
98
106
  | OfficialMcpAuthFailureReason
@@ -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
  })