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
@@ -52,12 +52,17 @@ import {
52
52
  import { SessionSnapshotSchema, SessionListSchema } from "./host/schemas.js";
53
53
  import { TimelineSnapshots } from "./timeline.js";
54
54
  import type { NativeSessionEvent } from "./session-types.js";
55
+ import {
56
+ defaultTimelinePreferences,
57
+ type TimelinePreferences,
58
+ } from "../shared/timeline.js";
55
59
 
56
60
  export const CAPABILITIES = [
57
61
  "prompt.message",
58
62
  "prompt.command",
59
63
  "prompt.image",
60
64
  "prompt.steer",
65
+ "session.can_stop_runtime",
61
66
  "session.configure",
62
67
  "session.list",
63
68
  "session.persistence",
@@ -117,6 +122,7 @@ export function createZCodeProvider(
117
122
  bridgeFactory: BridgeFactory = createHost,
118
123
  persistenceStore = new SessionPersistenceStore(),
119
124
  status: ProviderRegistration["status"] = createRuntimeStatus(),
125
+ timeline: () => TimelinePreferences = () => defaultTimelinePreferences,
120
126
  ): ProviderRegistration {
121
127
  return {
122
128
  id: "zcode",
@@ -134,6 +140,7 @@ export function createZCodeProvider(
134
140
  negotiateProviderCapabilities(request.capabilities, CAPABILITIES),
135
141
  bridgeFactory,
136
142
  persistenceStore,
143
+ timeline,
137
144
  );
138
145
  },
139
146
  };
@@ -154,6 +161,7 @@ export class ZCodeConnection implements ProviderConnection {
154
161
  readonly capabilities: readonly string[],
155
162
  private readonly bridgeFactory: BridgeFactory,
156
163
  private readonly persistenceStore: SessionPersistenceStore,
164
+ private readonly timeline: () => TimelinePreferences,
157
165
  ) {}
158
166
 
159
167
  onEvent(listener: (event: ProviderEvent) => void): () => void {
@@ -471,6 +479,15 @@ export class ZCodeConnection implements ProviderConnection {
471
479
  case "session.interrupt":
472
480
  await entry.native.interrupt();
473
481
  break;
482
+ // Paseo asks before releasing an idle runtime; the answer is the reply.
483
+ case "session.can_stop_runtime":
484
+ this.emit({
485
+ type: "session.can_stop_runtime",
486
+ requestId: input.requestId,
487
+ sessionId: input.sessionId,
488
+ canStop: entry.native.canStopRuntime(),
489
+ });
490
+ return;
474
491
  case "session.permission":
475
492
  await entry.native.respondToPermission(
476
493
  input.permissionId,
@@ -546,7 +563,10 @@ export class ZCodeConnection implements ProviderConnection {
546
563
  }
547
564
  : {}),
548
565
  }),
549
- mcpServers: mapMcpServers(config.mcpServers),
566
+ mcpServers: mapMcpServers(
567
+ config.mcpServers,
568
+ host.diagnostic.appVersion,
569
+ ),
550
570
  },
551
571
  SessionSnapshotSchema,
552
572
  60000,
@@ -559,7 +579,10 @@ export class ZCodeConnection implements ProviderConnection {
559
579
  workspace: cwd,
560
580
  snapshot,
561
581
  modelCatalog: selection.models,
582
+ timeline: this.timeline,
562
583
  onClose() {},
584
+ // A non-empty list replaces ZCode's MCP configuration files.
585
+ projectMcpServers: Object.keys(config.mcpServers ?? {}).length === 0,
563
586
  });
564
587
  if (
565
588
  initialModel &&
@@ -727,7 +750,7 @@ export class ZCodeConnection implements ProviderConnection {
727
750
  state: "failed",
728
751
  error: {
729
752
  code: event.code,
730
- message: "ZCode turn failed",
753
+ message: event.error,
731
754
  diagnostic: event.diagnostic,
732
755
  },
733
756
  });
@@ -55,12 +55,12 @@ export const MANAGED_NODE_ARCHIVES: Readonly<
55
55
  // Published by .github/workflows/zcode-runtime-release.yml from the pinned
56
56
  // source with patches/zcode applied (ADR 19). The same archive serves every
57
57
  // managed platform.
58
- export const MANAGED_ZCODE_VERSION = "3.16.2";
58
+ export const MANAGED_ZCODE_VERSION = "3.17.2";
59
59
  const MANAGED_ZCODE_RELEASE = `${MANAGED_ZCODE_VERSION}-paseo.1`;
60
60
  export const MANAGED_ZCODE_ARCHIVE: PinnedArchive = {
61
61
  url: `https://github.com/supermomonga/paseo-plugin-zcode-provider/releases/download/zcode-runtime-v${MANAGED_ZCODE_RELEASE}/zcode-runtime-${MANAGED_ZCODE_RELEASE}.tar.gz`,
62
- sha256: "01f3ee802f4c0b24c4023e366485120416a6acc92ec899a9edf7f2fc76eaa17d",
63
- size: 82_516_181,
62
+ sha256: "24e3a9b03260d7b800958ccba4cfdc8233eee67936170636da79d440245bd15d",
63
+ size: 83_086_942,
64
64
  };
65
65
 
66
66
  export function managedPlatform(
package/server/session.ts CHANGED
@@ -50,6 +50,8 @@ import type {
50
50
  } from "./session-types.js";
51
51
  import { AdapterError } from "./errors.js";
52
52
  import { diagnosticError, formatDiagnostic } from "./diagnostics.js";
53
+ import { turnFailure } from "./turn-failure.js";
54
+ import type { TimelinePreferences } from "../shared/timeline.js";
53
55
  interface Admission {
54
56
  clientMessageId?: string;
55
57
  accepted: boolean;
@@ -76,6 +78,7 @@ export class ZCodeSession {
76
78
  private readonly seenTurns = new Set<string>();
77
79
  private readonly publicTurns = new Map<string, string>();
78
80
  private readonly presented = new Map<string, NativeTimelineEntry>();
81
+ private readonly omitted = new Set<string>();
79
82
  private readonly pending = new Map<string, PresentedInteraction>();
80
83
  private readonly answering = new Set<string>();
81
84
  private readonly resolvedInteractions = new Set<string>();
@@ -94,7 +97,10 @@ export class ZCodeSession {
94
97
  private readonly workspace: string,
95
98
  private readonly snapshot: SessionSnapshot,
96
99
  private modelCatalog: readonly ModelOption[],
100
+ private readonly timeline: () => TimelinePreferences,
97
101
  private readonly onClose: () => void,
102
+ /** False when Paseo's MCP servers replace the project's configuration. */
103
+ private readonly projectMcpServers: boolean,
98
104
  ) {
99
105
  assertSnapshotWorkspace(snapshot, workspace);
100
106
  this.id = snapshot.session.sessionId;
@@ -108,7 +114,9 @@ export class ZCodeSession {
108
114
  workspace: string;
109
115
  snapshot: SessionSnapshot;
110
116
  modelCatalog: readonly ModelOption[];
117
+ timeline: () => TimelinePreferences;
111
118
  onClose: () => void;
119
+ projectMcpServers: boolean;
112
120
  }): Promise<ZCodeSession> {
113
121
  const session = new ZCodeSession(
114
122
  options.bridge,
@@ -116,7 +124,9 @@ export class ZCodeSession {
116
124
  options.workspace,
117
125
  options.snapshot,
118
126
  options.modelCatalog,
127
+ options.timeline,
119
128
  options.onClose,
129
+ options.projectMcpServers,
120
130
  );
121
131
  session.unlistenFailure = options.bridge.onFailure((error) =>
122
132
  session.runtimeFailed(error),
@@ -133,7 +143,7 @@ export class ZCodeSession {
133
143
  if (row.kind === "turnHeader")
134
144
  session.seenTurns.add(session.productTurn(row));
135
145
  const item = rowTimeline(row);
136
- if (item)
146
+ if (item && !session.omits(row, item.id))
137
147
  session.presented.set(item.id, {
138
148
  item,
139
149
  timestamp: new Date(row.createdAt).toISOString(),
@@ -168,6 +178,22 @@ export class ZCodeSession {
168
178
  );
169
179
  return row.productTurnId;
170
180
  }
181
+ // The setting decides when a marker is first seen. Paseo keeps the items it
182
+ // has received, and a marker shown after a later change would land at the
183
+ // end of the timeline.
184
+ private omits(row: ConversationRow, id: string): boolean {
185
+ if (
186
+ row.kind !== "timelineMarker" ||
187
+ row.marker.type !== "modelChange" ||
188
+ this.presented.has(id)
189
+ )
190
+ return false;
191
+ if (this.omitted.has(id) || !this.timeline().showModelChanges) {
192
+ this.omitted.add(id);
193
+ return true;
194
+ }
195
+ return false;
196
+ }
171
197
  private newRun(): Run {
172
198
  return {
173
199
  id: randomUUID(),
@@ -223,7 +249,7 @@ export class ZCodeSession {
223
249
  ? this.admissions.get(row.sourceCommandId)?.clientMessageId
224
250
  : undefined;
225
251
  const item = rowTimeline(row, clientMessageId);
226
- if (!item) continue;
252
+ if (!item || this.omits(row, item.id)) continue;
227
253
  const entry = { item, timestamp: new Date(row.createdAt).toISOString() };
228
254
  if (isDeepStrictEqual(entry, this.presented.get(item.id))) continue;
229
255
  this.presented.set(item.id, entry);
@@ -294,19 +320,18 @@ export class ZCodeSession {
294
320
  this.state.pendingInteractions.some(
295
321
  (i) => i.kind === "workspaceHookReview",
296
322
  )
297
- ) {
298
- const item: ProviderTimelineItem = {
299
- id: "zcode:hook-trust",
300
- type: "notification",
301
- level: "warning",
302
- message:
303
- "ZCode workspace hooks require trust review. Review them with the official zcode hooks trust command.",
304
- };
305
- if (!this.presented.has(item.id)) {
306
- this.presented.set(item.id, { item });
307
- this.runEvent({ type: "timeline", item });
308
- }
309
- }
323
+ )
324
+ this.warnOnce(
325
+ "zcode:hook-trust",
326
+ "ZCode workspace hooks require trust review. Review them with the official zcode hooks trust command.",
327
+ );
328
+ // ZCode 3.17 counts the project's declarations even when Paseo's servers
329
+ // replace them, so the warning only applies to the project's configuration.
330
+ if (this.projectMcpServers && this.state.workspaceMcpAdmission)
331
+ this.warnOnce(
332
+ "zcode:mcp-trust",
333
+ "ZCode has not started this project's MCP servers because they are not trusted. Trust them in ZCode Desktop under Settings → MCP Servers, then start a new session.",
334
+ );
310
335
  this.changed();
311
336
  const run = this.active;
312
337
  if (
@@ -349,6 +374,17 @@ export class ZCodeSession {
349
374
  );
350
375
  }
351
376
  }
377
+ private warnOnce(id: string, message: string): void {
378
+ if (this.presented.has(id)) return;
379
+ const item: ProviderTimelineItem = {
380
+ id,
381
+ type: "notification",
382
+ level: "warning",
383
+ message,
384
+ };
385
+ this.presented.set(id, { item });
386
+ this.runEvent({ type: "timeline", item });
387
+ }
352
388
  private maybeComplete(): void {
353
389
  const run = this.active;
354
390
  if (
@@ -378,23 +414,29 @@ export class ZCodeSession {
378
414
  headers.some((h) => h.state === "failed") ||
379
415
  this.state.control.phase === "error";
380
416
  this.active = undefined;
381
- this.emit(
382
- failed
383
- ? {
384
- type: "turn_failed",
385
- turnId: run.id,
386
- error: "ZCode execution failed",
387
- code: "NATIVE_PROTOCOL_ERROR",
388
- }
389
- : {
390
- type:
391
- run.cancelled ||
392
- headers.some((h) => h.state === "completedInterrupted")
393
- ? "turn_canceled"
394
- : "turn_completed",
395
- turnId: run.id,
396
- },
397
- );
417
+ if (failed) {
418
+ // ZCode sets lastError in the frame that fails the turn and clears it
419
+ // when the next turn starts.
420
+ const failure = turnFailure(
421
+ this.state.control.lastError,
422
+ this.bridge.diagnostic,
423
+ );
424
+ this.emit({
425
+ type: "turn_failed",
426
+ turnId: run.id,
427
+ error: failure.message,
428
+ code: failure.code,
429
+ diagnostic: formatDiagnostic(failure),
430
+ });
431
+ } else
432
+ this.emit({
433
+ type:
434
+ run.cancelled ||
435
+ headers.some((h) => h.state === "completedInterrupted")
436
+ ? "turn_canceled"
437
+ : "turn_completed",
438
+ turnId: run.id,
439
+ });
398
440
  this.changed();
399
441
  }
400
442
  private changed(): void {
@@ -438,6 +480,28 @@ export class ZCodeSession {
438
480
  hasActiveTurn(): boolean {
439
481
  return !!this.active;
440
482
  }
483
+ /**
484
+ * Whether closing loses no native work (Paseo's idle runtime cleanup).
485
+ * Background Bash, subagents and workflow runs outlive the foreground turn,
486
+ * and an active goal continues on its own. Only `running` work counts, as in
487
+ * ZCode's own `hasBackgroundWork`: a finished one stays `resultPending` even
488
+ * after the turn that delivered its result.
489
+ */
490
+ canStopRuntime(): boolean {
491
+ this.assertOpen();
492
+ const state = this.state;
493
+ return (
494
+ !this.active &&
495
+ !this.pendingAdmissions &&
496
+ this.conversation.idle &&
497
+ !state.pendingInteractions.length &&
498
+ !state.pendingCommands.length &&
499
+ !state.backgroundWorks.some((w) => w.status === "running") &&
500
+ !state.subagents?.running.length &&
501
+ state.goal?.status !== "active" &&
502
+ state.goal?.status !== "verifying"
503
+ );
504
+ }
441
505
  subscribe(listener: (event: NativeSessionEvent) => void): () => void {
442
506
  this.listeners.add(listener);
443
507
  listener({ type: "usage_updated", usage: usage(this.state) });
@@ -0,0 +1,50 @@
1
+ import type {
2
+ PluginSettings,
3
+ PluginSettingsState,
4
+ } from "@getpaseo/plugin/server";
5
+ import { logger } from "./logger.js";
6
+ import {
7
+ defaultTimelinePreferences,
8
+ type TimelinePreferences,
9
+ type zcodeTimelineSettings,
10
+ } from "../shared/timeline.js";
11
+
12
+ type Schema = (typeof zcodeTimelineSettings)["schema"];
13
+
14
+ /**
15
+ * Follows the saved timeline settings. The defaults apply until the first read
16
+ * completes and while the stored document is invalid.
17
+ */
18
+ export function followTimelineSettings(settings: PluginSettings<Schema>): {
19
+ current: () => TimelinePreferences;
20
+ dispose: () => void;
21
+ } {
22
+ let current = defaultTimelinePreferences,
23
+ changed = false,
24
+ disposed = false;
25
+ const apply = (state: PluginSettingsState<Schema>) => {
26
+ if (disposed) return;
27
+ if (state.status === "invalid")
28
+ logger.log("warn", "zcode.settings.timeline.invalid");
29
+ current =
30
+ state.status === "ready" ? state.values : defaultTimelinePreferences;
31
+ };
32
+ const unsubscribe = settings.subscribe((state) => {
33
+ changed = true;
34
+ apply(state);
35
+ });
36
+ settings.read().then(
37
+ (state) => {
38
+ // A save notified meanwhile is newer than this read.
39
+ if (!changed) apply(state);
40
+ },
41
+ (error: unknown) => logger.error("zcode.settings.timeline.failed", error),
42
+ );
43
+ return {
44
+ current: () => current,
45
+ dispose() {
46
+ disposed = true;
47
+ void unsubscribe();
48
+ },
49
+ };
50
+ }
@@ -0,0 +1,116 @@
1
+ import type { SessionErrorInfo } from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.js";
2
+ import { AdapterError, type ZCodeErrorCode } from "./errors.js";
3
+ import {
4
+ modelFailureReasons,
5
+ reportableProviderErrorCode,
6
+ reportableStatusCode,
7
+ type ModelFailureReason,
8
+ type RuntimeDiagnostic,
9
+ } from "./diagnostics.js";
10
+
11
+ type TurnFailureCode = Extract<
12
+ ZCodeErrorCode,
13
+ "NATIVE_TURN_FAILED" | `MODEL_${string}`
14
+ >;
15
+
16
+ // Reasons without an entry fall back to the attribution source.
17
+ const reasonCodes: Partial<Record<ModelFailureReason, TurnFailureCode>> = {
18
+ rate_limited: "MODEL_RATE_LIMITED",
19
+ offpeak_queued: "MODEL_RATE_LIMITED",
20
+ auth_failed: "MODEL_AUTH_FAILED",
21
+ auth_refresh: "MODEL_AUTH_FAILED",
22
+ provider_not_configured: "MODEL_AUTH_FAILED",
23
+ context_exceeded: "MODEL_CONTEXT_EXCEEDED",
24
+ network_error: "MODEL_NETWORK_ERROR",
25
+ timeout: "MODEL_NETWORK_ERROR",
26
+ stream_idle_timeout: "MODEL_NETWORK_ERROR",
27
+ stale_connection: "MODEL_NETWORK_ERROR",
28
+ proxy_error: "MODEL_NETWORK_ERROR",
29
+ tls_error: "MODEL_NETWORK_ERROR",
30
+ server_error: "MODEL_PROVIDER_ERROR",
31
+ provider_overloaded: "MODEL_PROVIDER_ERROR",
32
+ content_filter: "MODEL_CONTENT_FILTERED",
33
+ };
34
+
35
+ const messages: Record<
36
+ TurnFailureCode,
37
+ readonly [summary: string, advice?: string]
38
+ > = {
39
+ NATIVE_TURN_FAILED: ["ZCode turn failed"],
40
+ MODEL_RATE_LIMITED: [
41
+ "The model provider's usage or rate limit was reached",
42
+ "Wait for it to reset or switch models. For a ZCode Coding Plan, Paseo shows the reset times on the Usage screen.",
43
+ ],
44
+ MODEL_AUTH_FAILED: [
45
+ "The model provider is not signed in or rejected the credentials",
46
+ "Check the account and model providers in the Account tab of the zcode-provider Settings.",
47
+ ],
48
+ MODEL_CONTEXT_EXCEEDED: [
49
+ "The conversation exceeds the model's context window",
50
+ "Start a new session or switch to a model with a larger context window.",
51
+ ],
52
+ MODEL_NETWORK_ERROR: [
53
+ "ZCode could not reach the model provider",
54
+ "Check the network connection and try again.",
55
+ ],
56
+ MODEL_PROVIDER_ERROR: [
57
+ "The model provider returned a server error or is overloaded",
58
+ "Try again later.",
59
+ ],
60
+ MODEL_CONTENT_FILTERED: [
61
+ "The model provider's content filter blocked the reply",
62
+ "Rephrase the request or switch models.",
63
+ ],
64
+ MODEL_REQUEST_FAILED: ["The model provider rejected the request"],
65
+ };
66
+
67
+ /**
68
+ * Classifies a failed turn by the attribution of V4 `control.lastError`
69
+ * (ADR 23). ZCode's message and detail are never used: they can carry
70
+ * provider text, request content or credentials (ADR 7).
71
+ */
72
+ export function turnFailure(
73
+ lastError: SessionErrorInfo | null,
74
+ context: RuntimeDiagnostic,
75
+ ): AdapterError {
76
+ const attribution = lastError?.attribution;
77
+ const source = attribution?.source ?? lastError?.source;
78
+ const reason = modelFailureReasons.find((r) => r === attribution?.reason);
79
+ const code: TurnFailureCode =
80
+ source === "provider" || source === "network"
81
+ ? ((reason && reasonCodes[reason]) ??
82
+ (source === "network" ? "MODEL_NETWORK_ERROR" : "MODEL_REQUEST_FAILED"))
83
+ : "NATIVE_TURN_FAILED";
84
+ const statusCode = reportableStatusCode(attribution?.statusCode);
85
+ const providerErrorCode = reportableProviderErrorCode(
86
+ attribution?.providerErrorCode,
87
+ );
88
+ const facts = [
89
+ ...(statusCode ? [`HTTP ${statusCode}`] : []),
90
+ ...(providerErrorCode ? [`provider code ${providerErrorCode}`] : []),
91
+ ];
92
+ const [summary, advice] = messages[code];
93
+ return new AdapterError(
94
+ code,
95
+ `${summary}${facts.length ? ` (${facts.join(", ")})` : ""}.${advice ? ` ${advice}` : ""}`,
96
+ {},
97
+ undefined,
98
+ {
99
+ ...context,
100
+ stage: "turn",
101
+ ...(lastError
102
+ ? {
103
+ failure: {
104
+ source,
105
+ reason: attribution?.reason,
106
+ errorPhase: attribution?.errorPhase,
107
+ exceptionKind: attribution?.exceptionKind,
108
+ statusCode: attribution?.statusCode,
109
+ providerErrorCode: attribution?.providerErrorCode,
110
+ retryable: attribution?.retryable,
111
+ },
112
+ }
113
+ : {}),
114
+ },
115
+ );
116
+ }
package/server/usage.ts CHANGED
@@ -1,6 +1,4 @@
1
1
  import { createHash } from "node:crypto";
2
- // Types only, from the module every supported Paseo resolves; Paseo 0.8–0.10
3
- // reject `@getpaseo/plugin/server/usage` even as a type import.
4
2
  import type {
5
3
  UsageReport,
6
4
  UsageSourceRegistration,
@@ -234,7 +232,7 @@ export interface UsageSourceOptions {
234
232
  }
235
233
 
236
234
  /**
237
- * Coding Plan quota for Paseo's Usage screen (Paseo 0.11+), read through
235
+ * Coding Plan quota for Paseo's Usage screen, read through
238
236
  * ZCode's official usage-stats service on the account Server (ADR 18).
239
237
  */
240
238
  export function createUsageSource(
@@ -49,7 +49,7 @@ AI 生成的代码、命令、解释、文件和建议可能存在错误、遗
49
49
  | 手机远程控制 | 启用远程控制并完成配对后,桌面与手机网页经外部 relay 交换会话内容、输入、任务状态、权限请求与附件预览等协议消息;relay 负责鉴权、配对、心跳与消息透传,不运行任务。配对与连接会发送设备、窗口与会话标识。relay 地址随发行配置确定,可由 `ZCODE_WEB_REMOTE_CONTROL_RELAY_WS_URL` 覆盖。 |
50
50
  | Bots 第三方聊天接入 | 配置 Bot 后,所选第三方聊天平台(如 Telegram、飞书/Lark)的消息可驱动任务;Bot 按回复模式把助手回复、工具调用、文件变更摘要及权限请求发送到该平台,平台方可获得这些内容。Bot 凭据保存在本地凭据服务,配置文件只保存引用。 |
51
51
  | 营销触达与奖励中心 | 登录后可从业务服务获取营销 Banner/弹窗配置及资源包并展示;点击、关闭等操作会上报确认/取消事件,领取类操作会调用套餐领取接口。奖励中心以内嵌网页打开,桥接接口向该页面提供主题、语言和登录状态。 |
52
- | 安装、插件获取、远端部署与更新 | 安装、发现、认证、部署和更新会访问仓库、包服务、插件市场、CDN 或更新服务器;统一 CLI 安装脚本会从配置的分发源读取版本清单并下载发行包。桌面自动更新受发行形态和运行条件控制,启用后可在启动及周期检查时请求更新清单,携带平台、渠道、设备等信息;平台取值可区分架构,版本信息还会影响更新选择。开源构建默认不启用自动更新(构建期可选能力);启用时,开发构建与打包版都接受 `ZCODE_UPDATE_FEED_URL` 环境变量及 `--zcode-update-feed-url` 启动参数覆盖更新源,用于诊断与应急。下载的代码可能随后被安装或执行,远端部署还可能将本地已有或下载的组件上传/复制到目标环境。下载检查、实际安装及运行组件的控制条件不同,不能统一描述成每步都先弹出确认。 |
52
+ | 安装、插件获取、远端部署与更新 | 安装、发现、认证、部署和更新会访问仓库、包服务、插件市场、CDN 或更新服务器;统一 CLI 安装脚本会从配置的分发源读取版本清单并下载发行包。桌面自动更新受发行形态和运行条件控制,启用后可在启动及周期检查时请求更新清单,携带平台、渠道、设备等信息;平台取值可区分架构,版本信息还会影响更新选择。开源构建默认不启用自动更新(构建期可选能力);启用时,仅未打包开发态接受 `ZCODE_UPDATE_FEED_URL` 环境变量及 `--zcode-update-feed-url` 启动参数覆盖更新源,用于诊断;打包应用忽略这两个入口,继续使用既有服务端 manifest 入口。下载的代码可能随后被安装或执行,远端部署还可能将本地已有或下载的组件上传/复制到目标环境。下载检查、实际安装及运行组件的控制条件不同,不能统一描述成每步都先弹出确认。 |
53
53
  | 工具、Hook、工作流与自动任务的交付或发布 | Shell、终端、Git、Node REPL、浏览器、插件、MCP 或工作流可以读取任务涉及的数据、向相应目标服务上传文件或生成物,并改变外部服务状态;生命周期 Hook 和已配置的定时/后台任务也可触发程序。权限规则、模式、插件配置及系统账号决定执行范围,不能保证每份外发内容都由用户逐项选择或每次外发都有独立确认。发布、发送、购买或部署完成后,本地取消或撤销不一定能恢复外部状态;权限边界见第二节。 |
54
54
  | 开发测试、调试与请求录制 | 显式运行相关开发工具时,可向配置的真实模型或工具服务发送测试提示、样例资料及认证头;配置为真实上游的录制代理可转发请求,不能因名称含测试/录制就认为完全离线。请求轨迹和调试文件还可能在本地保存模型内容;这些工具的触发入口与普通产品运行不同。 |
55
55
  | 构建、签名与维护者发布 | 显式运行安装、构建或发布脚本时,可下载依赖、原生二进制和运行时,将构建材料复制到发布共享目录、推送 Git,或交给签名工具、Apple 公证服务处理。外部签名工具及另行配置的 CI、存储和分发服务具有自己的网络行为;本仓未展开的流程不能仅凭脚本名称推定已核验。相关调用具有不同的启动入口、环境和凭据要求。CLI SEA 共享目录发布与上传会先校验第三方声明材料,校验失败会阻断该发布流程。当前 native-search 准备步骤按目标平台校验并解包仓库内置归档,本步骤不下载这些归档;Node 等其他组件有各自的下载链路。 |
@@ -99,6 +99,7 @@ export class ChannelClient implements IChannelClient, IDisposable {
99
99
  "taskId",
100
100
  "traceId",
101
101
  "retryable",
102
+ "profileId",
102
103
  ] as const;
103
104
  for (const key of passthroughKeys) {
104
105
  const value = response.data[key];
@@ -170,7 +171,18 @@ export class ChannelClient implements IChannelClient, IDisposable {
170
171
  });
171
172
 
172
173
  this.handlers.set(id, (response) => {
173
- emitter.fire((response as { data: any }).data);
174
+ if (response.type === ResponseType.EventFire) {
175
+ emitter.fire(response.data);
176
+ } else if (response.type === ResponseType.EventError) {
177
+ // 订阅失败必须结束其监听器,不能把错误对象写入终端等正常事件流,也不能继续保留旧请求。
178
+ this.handlers.delete(id);
179
+ this.activeRequests.delete(emitter);
180
+ emitter.dispose();
181
+ const error = new Error(response.data.message);
182
+ error.name = response.data.name;
183
+ if (response.data.stack) error.stack = response.data.stack.join("\n");
184
+ console.error(`RPC event subscription failed: ${channelName}.${name}`, error);
185
+ }
174
186
  });
175
187
 
176
188
  return emitter.event;
@@ -208,9 +220,11 @@ export class ChannelClient implements IChannelClient, IDisposable {
208
220
  }
209
221
 
210
222
  private onBuffer(message: VSBuffer): void {
223
+ // 修复原因:同一 protocol 上还有反向 ChannelServer(host ↔ 远端 WebSocket 两端都是),对方发来的
224
+ // 请求也会到这里。原来先解码消息体再判断类型,每条请求都被完整解码两次,大请求(例如数据同步的
225
+ // 归档)白白多花一倍 CPU。修法:先读消息头,只解码属于本端的响应体。
211
226
  const reader = new BufferReader(message);
212
227
  const header = deserialize(reader);
213
- const body = deserialize(reader);
214
228
  const type = header[0] as ResponseType;
215
229
 
216
230
  switch (type) {
@@ -220,11 +234,12 @@ export class ChannelClient implements IChannelClient, IDisposable {
220
234
  case ResponseType.PromiseSuccess:
221
235
  case ResponseType.PromiseError:
222
236
  case ResponseType.EventFire:
237
+ case ResponseType.EventError:
223
238
  case ResponseType.PromiseErrorObj:
224
239
  this.onResponse({
225
240
  type,
226
241
  id: header[1],
227
- data: body,
242
+ data: deserialize(reader),
228
243
  } as IRawResponse);
229
244
  return;
230
245
  }
@@ -48,6 +48,7 @@ export class ChannelServer<TContext = string> implements IChannelServer<TContext
48
48
  case ResponseType.PromiseSuccess:
49
49
  case ResponseType.PromiseError:
50
50
  case ResponseType.EventFire:
51
+ case ResponseType.EventError:
51
52
  case ResponseType.PromiseErrorObj:
52
53
  this.send([response.type, response.id], response.data);
53
54
  return;
@@ -66,9 +67,10 @@ export class ChannelServer<TContext = string> implements IChannelServer<TContext
66
67
  }
67
68
 
68
69
  private onRawMessage(message: VSBuffer): void {
70
+ // 修复原因:同一 protocol 上还有反向 ChannelClient,对方发来的响应也会到这里;原来先解码消息体
71
+ // 再判断类型,每条响应都被完整解码两次。修法:先读消息头,只解码属于本端的请求体。
69
72
  const reader = new BufferReader(message);
70
73
  const header = deserialize(reader);
71
- const body = deserialize(reader);
72
74
  const type = header[0] as RequestType;
73
75
 
74
76
  switch (type) {
@@ -78,7 +80,7 @@ export class ChannelServer<TContext = string> implements IChannelServer<TContext
78
80
  id: header[1],
79
81
  channelName: header[2],
80
82
  name: header[3],
81
- arg: body,
83
+ arg: deserialize(reader),
82
84
  });
83
85
  return;
84
86
  case RequestType.EventListen:
@@ -87,7 +89,7 @@ export class ChannelServer<TContext = string> implements IChannelServer<TContext
87
89
  id: header[1],
88
90
  channelName: header[2],
89
91
  name: header[3],
90
- arg: body,
92
+ arg: deserialize(reader),
91
93
  });
92
94
  return;
93
95
  case RequestType.PromiseCancel:
@@ -147,6 +149,7 @@ export class ChannelServer<TContext = string> implements IChannelServer<TContext
147
149
  taskId?: unknown;
148
150
  traceId?: unknown;
149
151
  retryable?: unknown;
152
+ profileId?: unknown;
150
153
  } = {
151
154
  message: error.message,
152
155
  name: error.name,
@@ -164,6 +167,9 @@ export class ChannelServer<TContext = string> implements IChannelServer<TContext
164
167
  "taskId",
165
168
  "traceId",
166
169
  "retryable",
170
+ // Bug 原因:Host 的远程等待点(需要安装/升级、补凭据)用 profileId 指明实际操作线路;
171
+ // 旧白名单丢掉它,侧栏项目只能把不含凭据的目标交给向导,确认安装后报“SSH 认证失败”。
172
+ "profileId",
167
173
  ] as const;
168
174
  for (const key of passthroughKeys) {
169
175
  const value = errorRecord[key];
@@ -205,18 +211,32 @@ export class ChannelServer<TContext = string> implements IChannelServer<TContext
205
211
  return;
206
212
  }
207
213
 
208
- const disposable = channel.listen(
209
- this.ctx,
210
- request.name,
211
- request.arg,
212
- )((data) => {
214
+ try {
215
+ const disposable = channel.listen(
216
+ this.ctx,
217
+ request.name,
218
+ request.arg,
219
+ )((data) => {
220
+ this.sendResponse({
221
+ id: request.id,
222
+ data,
223
+ type: ResponseType.EventFire,
224
+ });
225
+ });
226
+ this.activeRequests.set(request.id, disposable);
227
+ } catch (error) {
228
+ // 已结束的终端等资源会拒绝迟到订阅;该拒绝属于本次请求,不能逃逸并退出整个 Host。
229
+ // 独立失败帧不会被旧客户端当作业务事件,也不会建立无法释放的活动订阅。
213
230
  this.sendResponse({
214
231
  id: request.id,
215
- data,
216
- type: ResponseType.EventFire,
232
+ type: ResponseType.EventError,
233
+ data: {
234
+ name: error instanceof Error ? error.name : "Error",
235
+ message: error instanceof Error ? error.message : String(error),
236
+ ...(error instanceof Error && error.stack ? { stack: error.stack.split("\n") } : {}),
237
+ },
217
238
  });
218
- });
219
- this.activeRequests.set(request.id, disposable);
239
+ }
220
240
  }
221
241
 
222
242
  private disposeActiveRequest(id: number): void {