paseo-plugin-zcode-provider 0.4.3 → 0.4.4

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.
package/README.md CHANGED
@@ -10,7 +10,7 @@ This is an unofficial plugin. It is not endorsed or maintained by ZCode or Z.ai.
10
10
 
11
11
  | Setting | Requirement |
12
12
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
13
- | Paseo | 0.8.0 or later; development SDK 0.12.0 |
13
+ | Paseo | 0.9.0 or later; development SDK 0.12.0 |
14
14
  | Plugin Node.js | 22.12.0 or later (the Paseo daemon's runtime) |
15
15
  | Managed setup | darwin-arm64, linux-x64, linux-arm64, win-x64, win-arm64 |
16
16
  | ZCode | Managed: 3.16.2 (release `3.16.2-paseo.1`) with Node.js 24.21.0. Overrides: stable Server 3.14.0+ / Agent 0.16.9+ with Node.js 24.14.0+ |
@@ -30,7 +30,7 @@ To follow the `main` branch instead, install the Git repository with `paseo plug
30
30
 
31
31
  ## Setup
32
32
 
33
- Open **Settings → Plugins → zcode-provider → Settings**. The screen has two tabs: **Runtime** installs and removes the runtime, and **Account** signs in and manages model providers.
33
+ Open **Settings → Plugins → zcode-provider → Settings**. The screen has three tabs: **Runtime** installs and removes the runtime, **Account** signs in and manages model providers, and **Timeline** chooses what ZCode agents add to the timeline.
34
34
 
35
35
  On the **Runtime** tab, choose **Download and install**. The screen lists every download, its SHA-256, size and license before you start. Setup runs on the machine hosting the daemon:
36
36
 
@@ -57,6 +57,10 @@ The **Account** tab uses ZCode's own account and provider services, the same one
57
57
 
58
58
  API keys are sent to ZCode, which stores them as Desktop does, and are never shown again. The plugin itself stores no credentials. Afterwards, choose **ZCode** when creating an agent; the model list is refreshed after each change on Paseo 0.9 or later.
59
59
 
60
+ ### Timeline
61
+
62
+ ZCode adds a line when a turn runs on a different model than the previous turn, such as `Model switched magpie/GLM-5.3-Flash → magpie/auto/glm-5.3-flash`. These lines are hidden by default; turn on **Show model changes** on the **Timeline** tab to show them. The setting is stored by Paseo on the daemon host. It decides each line when the line first arrives: lines already shown stay, and lines that arrived while it was off are not added later. A reopened agent shows its history with the current setting (ADR 24).
63
+
60
64
  ### Coding Plan usage
61
65
 
62
66
  On Paseo 0.11 and later, Paseo's **Usage** screen and sidebar usage summary show a **ZCode** card for the signed-in account's Individual Coding Plan (Z.ai or BigModel). It lists the 5-hour, weekly, monthly tool-call and ZCode MCP quotas with their reset times, as ZCode Desktop does. The plugin asks ZCode's official usage service for this plan only, on the same ZCode Server as the Account tab. The service never uses an API key from the environment. Team Plan and Start Plan are not shown. Paseo 0.12.0 does not yet show usage in a ZCode agent's popover.
@@ -82,8 +86,9 @@ The source baseline is `3c5b227649371507ddc4eb46ac5133afe6db1cab` (ZCode 3.16.2,
82
86
  - Text, thoughts, tools, subagent progress, usage and history use V4 snapshots and deltas. Tool output is marked when ZCode truncates it. Usage is cumulative; repeated snapshots do not add it again.
83
87
  - Text submitted during generation uses native guidance. Attachments use the native queue. Paseo reports one run across these native turns and completes it only after all accepted input has been consumed and foreground work has ended.
84
88
  - Paseo sends every message typed in the app during a run as a steer that asks to clear pending permissions. The plugin queues it first, then declines pending permissions, questions and Plan approvals with their deny action until ZCode reads the message, including requests opened in the meantime. Requests that appear after it is read are left to the user. Declining a Plan approval in Plan mode ends ZCode's turn; the message then starts the next native turn in the same Paseo run (ADR 22).
89
+ - A failed turn reports a code classified from the attribution of ZCode's error: `MODEL_RATE_LIMITED`, `MODEL_AUTH_FAILED`, `MODEL_CONTEXT_EXCEEDED`, `MODEL_NETWORK_ERROR`, `MODEL_PROVIDER_ERROR` or `MODEL_REQUEST_FAILED` when the model provider or network failed, and `NATIVE_TURN_FAILED` otherwise. The message is the plugin's own text with the HTTP status and the provider's error code when known. The provider's own message, which can include a quota reset time, is not shown; Coding Plan reset times appear on Paseo 0.11's Usage screen (ADR 23).
85
90
  - Acceptance is reported once, after the native acknowledgement. Unknown delivery results are never automatically resent. Stop identifies the current native execution, disables automatic queue execution and removes pending input. A new explicit run enables the queue again.
86
- - As in ZCode Desktop, successful hooks are not shown. A finished hook invocation appears once, as a notification, only when a hook was blocked, failed, timed out or was cancelled; context compaction also appears once, when it ends. Paseo appends every notification it receives, so progress is not reported.
91
+ - As in ZCode Desktop, successful hooks are not shown. A finished hook invocation appears once, as a notification, only when a hook was blocked, failed, timed out or was cancelled; context compaction also appears once, when it ends. Paseo appends every notification it receives, so progress is not reported. Model changes appear only when turned on (see [Timeline](#timeline)).
87
92
  - Native permission IDs, option values, questions and Plan approval retain their meanings. Question auto-resolution is disabled for each owned Server. Workspace hook trust is reviewed through the official CLI; it is not represented as “allow once.”
88
93
  - Each session owns its Server process and environment. Metadata requests use temporary Servers. Closing stdin gives ZCode time to clean up before process termination.
89
94
 
@@ -3,10 +3,12 @@ import { Pressable, Text, View } from "react-native";
3
3
  import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
4
4
  import { AccountTab } from "./account";
5
5
  import { RuntimeTab } from "./runtime";
6
+ import { TimelineTab } from "./timeline";
6
7
 
7
8
  const TABS = [
8
9
  { id: "runtime", label: "Runtime" },
9
10
  { id: "account", label: "Account" },
11
+ { id: "timeline", label: "Timeline" },
10
12
  ] as const;
11
13
  type Tab = (typeof TABS)[number]["id"];
12
14
 
@@ -76,8 +78,10 @@ export function SettingsScreen(props: PluginSurfaceProps) {
76
78
  <Tabs value={tab} onChange={setTab} theme={props.theme} />
77
79
  {tab === "runtime" ? (
78
80
  <RuntimeTab {...props} />
79
- ) : (
81
+ ) : tab === "account" ? (
80
82
  <AccountTab {...props} onOpenRuntime={() => setTab("runtime")} />
83
+ ) : (
84
+ <TimelineTab {...props} />
81
85
  )}
82
86
  </View>
83
87
  );
@@ -0,0 +1,78 @@
1
+ import { useCallback } from "react";
2
+ import { type PluginSurfaceProps, useSettings } from "@getpaseo/plugin/client";
3
+ import {
4
+ SettingsAction,
5
+ SettingsCard,
6
+ SettingsRow,
7
+ SettingsSection,
8
+ SettingsSwitch,
9
+ } from "@getpaseo/plugin/client/ui";
10
+ import { zcodeTimelineSettings } from "../shared/timeline";
11
+ import { Value } from "./value";
12
+
13
+ const LABEL = "Show model changes";
14
+
15
+ export function TimelineTab({ theme, layout }: PluginSurfaceProps) {
16
+ const settings = useSettings(zcodeTimelineSettings);
17
+ const toggle = useCallback(
18
+ (showModelChanges: boolean) => {
19
+ if (settings.status === "ready")
20
+ void settings.save(
21
+ { ...settings.values, showModelChanges },
22
+ settings.revision,
23
+ );
24
+ },
25
+ [settings],
26
+ );
27
+
28
+ if (settings.status === "loading")
29
+ return (
30
+ <SettingsSection title="Timeline">
31
+ <SettingsCard>
32
+ <SettingsRow label={LABEL}>
33
+ <Value
34
+ color={theme.colors.foregroundMuted}
35
+ compact={layout.compact}
36
+ >
37
+ Loading…
38
+ </Value>
39
+ </SettingsRow>
40
+ </SettingsCard>
41
+ </SettingsSection>
42
+ );
43
+ if (settings.status !== "ready")
44
+ return (
45
+ <SettingsSection title="Timeline">
46
+ <SettingsCard>
47
+ <SettingsRow label={LABEL} error={settings.error} />
48
+ <SettingsAction
49
+ label="Try again"
50
+ actionLabel="Reload"
51
+ onPress={() => void settings.reload()}
52
+ />
53
+ {settings.status === "invalid" ? (
54
+ <SettingsAction
55
+ label="Restore the default"
56
+ actionLabel="Reset"
57
+ disabled={settings.saving}
58
+ onPress={() => void settings.reset()}
59
+ />
60
+ ) : null}
61
+ </SettingsCard>
62
+ </SettingsSection>
63
+ );
64
+ return (
65
+ <SettingsSection title="Timeline">
66
+ <SettingsCard>
67
+ <SettingsSwitch
68
+ label={LABEL}
69
+ hint="Adds a line when ZCode runs a turn on a different model than the previous turn. Applies to lines that arrive after the change; reopened agents show their history with the current setting."
70
+ value={settings.values.showModelChanges}
71
+ disabled={settings.saving}
72
+ error={settings.saveError}
73
+ onValueChange={toggle}
74
+ />
75
+ </SettingsCard>
76
+ </SettingsSection>
77
+ );
78
+ }
package/index.server.ts CHANGED
@@ -5,6 +5,7 @@ import { createHost, createZCodeProvider } from "./server/provider.js";
5
5
  import { ManagedRuntimeInstaller } from "./server/runtime/managed.js";
6
6
  import { createRuntimeSetupHandlers } from "./server/runtime-setup.js";
7
7
  import { createDiagnosticsHandler } from "./server/status.js";
8
+ import { followTimelineSettings } from "./server/timeline-settings.js";
8
9
  import { createUsageSource } from "./server/usage.js";
9
10
  import { zcodeAccountChange, zcodeAccountView } from "./shared/account.js";
10
11
  import { zcodeDiagnostics } from "./shared/diagnostics.js";
@@ -13,9 +14,15 @@ import {
13
14
  zcodeRuntimeRemove,
14
15
  zcodeRuntimeStatus,
15
16
  } from "./shared/runtime-setup.js";
17
+ import { zcodeTimelineSettings } from "./shared/timeline.js";
16
18
 
17
19
  export default function contribute(server: PluginServerContext): () => void {
18
- server.registerProvider(createZCodeProvider());
20
+ const timeline = followTimelineSettings(
21
+ server.registerSettings(zcodeTimelineSettings),
22
+ );
23
+ server.registerProvider(
24
+ createZCodeProvider(undefined, undefined, undefined, timeline.current),
25
+ );
19
26
  server.handle(zcodeDiagnostics, createDiagnosticsHandler());
20
27
  const setup = createRuntimeSetupHandlers(new ManagedRuntimeInstaller());
21
28
  server.handle(zcodeRuntimeStatus, setup.status);
@@ -33,6 +40,7 @@ export default function contribute(server: PluginServerContext): () => void {
33
40
  server.registerUsageSource(usage.source);
34
41
  return () => {
35
42
  usage.dispose();
43
+ timeline.dispose();
36
44
  abort.abort();
37
45
  void account.close();
38
46
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "paseo-plugin-zcode-provider",
3
- "version": "0.4.3",
3
+ "version": "0.4.4",
4
4
  "description": "Unofficial Paseo provider plugin for ZCode, using the official stdio Services Server of the integrated ZCode CLI.",
5
5
  "keywords": [
6
6
  "paseo",
package/paseo-plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "id": "zcode-provider",
3
3
  "requirements": {
4
- "paseo": ">=0.8.0"
4
+ "paseo": ">=0.9.0"
5
5
  }
6
6
  }
@@ -1,2 +1,2 @@
1
1
  // Generated from package.json by npm prepare / prebuild.
2
- export const PROVIDER_VERSION = "0.4.3";
2
+ export const PROVIDER_VERSION = "0.4.4";
@@ -15,6 +15,50 @@ const stages = [
15
15
  "notification",
16
16
  "transport",
17
17
  "session",
18
+ "turn",
19
+ ] as const;
20
+ // ZCode's ModelFailureReason (apps/zcode-cli/packages/contracts/src/model/index.ts at 3c5b227).
21
+ export const modelFailureReasons = [
22
+ "rate_limited",
23
+ "provider_overloaded",
24
+ "server_error",
25
+ "network_error",
26
+ "timeout",
27
+ "stream_idle_timeout",
28
+ "stale_connection",
29
+ "auth_refresh",
30
+ "reasoning_signature_repair",
31
+ "offpeak_queued",
32
+ "auth_failed",
33
+ "cancelled",
34
+ "context_exceeded",
35
+ "invalid_request",
36
+ "provider_not_configured",
37
+ "proxy_error",
38
+ "tls_error",
39
+ "unknown",
40
+ ] as const;
41
+ export type ModelFailureReason = (typeof modelFailureReasons)[number];
42
+ // V4 errorAttributionSchema enums.
43
+ const failureSources = ["provider", "runtime", "tool", "network"] as const;
44
+ const errorPhases = [
45
+ "prepare",
46
+ "configuration",
47
+ "connect",
48
+ "response",
49
+ "stream",
50
+ "parse",
51
+ "validation",
52
+ "unhandled",
53
+ ] as const;
54
+ const exceptionKinds = [
55
+ "api_call",
56
+ "generic",
57
+ "protocol",
58
+ "provider_business",
59
+ "transport",
60
+ "type_error",
61
+ "validation",
18
62
  ] as const;
19
63
  const checks = [
20
64
  "bundle-metadata",
@@ -146,6 +190,44 @@ export interface RuntimeDiagnostic {
146
190
  readonly nativeCode?: number;
147
191
  readonly exitCode?: number;
148
192
  readonly validation?: readonly { path: string; code: string }[];
193
+ readonly failure?: TurnFailureDiagnostic;
194
+ }
195
+
196
+ /** Attribution of a failed turn from V4 `control.lastError`; never its message. */
197
+ export interface TurnFailureDiagnostic {
198
+ readonly source?: string;
199
+ readonly reason?: string;
200
+ readonly errorPhase?: string;
201
+ readonly exceptionKind?: string;
202
+ readonly statusCode?: number;
203
+ readonly providerErrorCode?: string;
204
+ readonly retryable?: boolean;
205
+ }
206
+
207
+ export function reportableStatusCode(
208
+ value: number | undefined,
209
+ ): number | undefined {
210
+ return Number.isInteger(value) && value! >= 100 && value! <= 599
211
+ ? value
212
+ : undefined;
213
+ }
214
+
215
+ /** Provider error codes are free text. Only numeric or word codes such as `1310` or `insufficient_quota` are reported. */
216
+ export function reportableProviderErrorCode(
217
+ value: string | undefined,
218
+ ): string | undefined {
219
+ return value &&
220
+ value.length <= 64 &&
221
+ /^(?:\d+|[A-Za-z]+(?:[_.][A-Za-z]+)*)$/u.test(value)
222
+ ? value
223
+ : undefined;
224
+ }
225
+
226
+ function allowed(
227
+ values: readonly string[],
228
+ value: string | undefined,
229
+ ): string | undefined {
230
+ return value !== undefined && values.includes(value) ? value : undefined;
149
231
  }
150
232
 
151
233
  export function runtimeDiagnostic(
@@ -222,6 +304,21 @@ export function formatDiagnostic(error: unknown): string {
222
304
  for (const key of ["nativeCode", "exitCode"] as const) {
223
305
  if (Number.isSafeInteger(context[key])) result[key] = context[key];
224
306
  }
307
+ if (context.failure) {
308
+ const f = context.failure;
309
+ const failure = Object.fromEntries(
310
+ Object.entries({
311
+ source: allowed(failureSources, f.source),
312
+ reason: allowed(modelFailureReasons, f.reason),
313
+ errorPhase: allowed(errorPhases, f.errorPhase),
314
+ exceptionKind: allowed(exceptionKinds, f.exceptionKind),
315
+ statusCode: reportableStatusCode(f.statusCode),
316
+ providerErrorCode: reportableProviderErrorCode(f.providerErrorCode),
317
+ retryable: typeof f.retryable === "boolean" ? f.retryable : undefined,
318
+ }).filter(([, value]) => value !== undefined),
319
+ );
320
+ if (Object.keys(failure).length) result.failure = failure;
321
+ }
225
322
  if (context.validation)
226
323
  result.validation = context.validation.slice(0, 10).map((issue) => ({
227
324
  path: issue.path
package/server/errors.ts CHANGED
@@ -14,6 +14,13 @@ export type ZCodeErrorCode =
14
14
  | "NATIVE_INPUT_REJECTED"
15
15
  | "NATIVE_TIMEOUT"
16
16
  | "NATIVE_EXITED"
17
+ | "NATIVE_TURN_FAILED"
18
+ | "MODEL_RATE_LIMITED"
19
+ | "MODEL_AUTH_FAILED"
20
+ | "MODEL_CONTEXT_EXCEEDED"
21
+ | "MODEL_NETWORK_ERROR"
22
+ | "MODEL_PROVIDER_ERROR"
23
+ | "MODEL_REQUEST_FAILED"
17
24
  | "AUTH_REQUIRED"
18
25
  | "UNSUPPORTED_CONTENT"
19
26
  | "SESSION_NOT_FOUND"
@@ -458,8 +458,14 @@ function markerText(marker: TimelineMarkerPayload): string {
458
458
  switch (marker.type) {
459
459
  case "compact":
460
460
  return `Context compaction: ${marker.status}`;
461
- case "modelChange":
462
- return `Model: ${marker.toModel} (${marker.toThought})`;
461
+ case "modelChange": {
462
+ // Worded as in ZCode Desktop, which also omits the reasoning level: it
463
+ // does not count as a model change and may be empty.
464
+ const to = `${marker.toProvider}/${marker.toModel}`;
465
+ return marker.fromProvider === undefined || marker.fromModel === undefined
466
+ ? `Using ${to}`
467
+ : `Model switched ${marker.fromProvider}/${marker.fromModel} → ${to}`;
468
+ }
463
469
  case "forkNotice":
464
470
  return "Conversation continued from a parent conversation.";
465
471
  case "forkCreated":
@@ -52,6 +52,10 @@ 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",
@@ -117,6 +121,7 @@ export function createZCodeProvider(
117
121
  bridgeFactory: BridgeFactory = createHost,
118
122
  persistenceStore = new SessionPersistenceStore(),
119
123
  status: ProviderRegistration["status"] = createRuntimeStatus(),
124
+ timeline: () => TimelinePreferences = () => defaultTimelinePreferences,
120
125
  ): ProviderRegistration {
121
126
  return {
122
127
  id: "zcode",
@@ -134,6 +139,7 @@ export function createZCodeProvider(
134
139
  negotiateProviderCapabilities(request.capabilities, CAPABILITIES),
135
140
  bridgeFactory,
136
141
  persistenceStore,
142
+ timeline,
137
143
  );
138
144
  },
139
145
  };
@@ -154,6 +160,7 @@ export class ZCodeConnection implements ProviderConnection {
154
160
  readonly capabilities: readonly string[],
155
161
  private readonly bridgeFactory: BridgeFactory,
156
162
  private readonly persistenceStore: SessionPersistenceStore,
163
+ private readonly timeline: () => TimelinePreferences,
157
164
  ) {}
158
165
 
159
166
  onEvent(listener: (event: ProviderEvent) => void): () => void {
@@ -559,6 +566,7 @@ export class ZCodeConnection implements ProviderConnection {
559
566
  workspace: cwd,
560
567
  snapshot,
561
568
  modelCatalog: selection.models,
569
+ timeline: this.timeline,
562
570
  onClose() {},
563
571
  });
564
572
  if (
@@ -727,7 +735,7 @@ export class ZCodeConnection implements ProviderConnection {
727
735
  state: "failed",
728
736
  error: {
729
737
  code: event.code,
730
- message: "ZCode turn failed",
738
+ message: event.error,
731
739
  diagnostic: event.diagnostic,
732
740
  },
733
741
  });
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,6 +97,7 @@ 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,
98
102
  ) {
99
103
  assertSnapshotWorkspace(snapshot, workspace);
@@ -108,6 +112,7 @@ export class ZCodeSession {
108
112
  workspace: string;
109
113
  snapshot: SessionSnapshot;
110
114
  modelCatalog: readonly ModelOption[];
115
+ timeline: () => TimelinePreferences;
111
116
  onClose: () => void;
112
117
  }): Promise<ZCodeSession> {
113
118
  const session = new ZCodeSession(
@@ -116,6 +121,7 @@ export class ZCodeSession {
116
121
  options.workspace,
117
122
  options.snapshot,
118
123
  options.modelCatalog,
124
+ options.timeline,
119
125
  options.onClose,
120
126
  );
121
127
  session.unlistenFailure = options.bridge.onFailure((error) =>
@@ -133,7 +139,7 @@ export class ZCodeSession {
133
139
  if (row.kind === "turnHeader")
134
140
  session.seenTurns.add(session.productTurn(row));
135
141
  const item = rowTimeline(row);
136
- if (item)
142
+ if (item && !session.omits(row, item.id))
137
143
  session.presented.set(item.id, {
138
144
  item,
139
145
  timestamp: new Date(row.createdAt).toISOString(),
@@ -168,6 +174,22 @@ export class ZCodeSession {
168
174
  );
169
175
  return row.productTurnId;
170
176
  }
177
+ // The setting decides when a marker is first seen. Paseo keeps the items it
178
+ // has received, and a marker shown after a later change would land at the
179
+ // end of the timeline.
180
+ private omits(row: ConversationRow, id: string): boolean {
181
+ if (
182
+ row.kind !== "timelineMarker" ||
183
+ row.marker.type !== "modelChange" ||
184
+ this.presented.has(id)
185
+ )
186
+ return false;
187
+ if (this.omitted.has(id) || !this.timeline().showModelChanges) {
188
+ this.omitted.add(id);
189
+ return true;
190
+ }
191
+ return false;
192
+ }
171
193
  private newRun(): Run {
172
194
  return {
173
195
  id: randomUUID(),
@@ -223,7 +245,7 @@ export class ZCodeSession {
223
245
  ? this.admissions.get(row.sourceCommandId)?.clientMessageId
224
246
  : undefined;
225
247
  const item = rowTimeline(row, clientMessageId);
226
- if (!item) continue;
248
+ if (!item || this.omits(row, item.id)) continue;
227
249
  const entry = { item, timestamp: new Date(row.createdAt).toISOString() };
228
250
  if (isDeepStrictEqual(entry, this.presented.get(item.id))) continue;
229
251
  this.presented.set(item.id, entry);
@@ -378,23 +400,29 @@ export class ZCodeSession {
378
400
  headers.some((h) => h.state === "failed") ||
379
401
  this.state.control.phase === "error";
380
402
  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
- );
403
+ if (failed) {
404
+ // ZCode sets lastError in the frame that fails the turn and clears it
405
+ // when the next turn starts.
406
+ const failure = turnFailure(
407
+ this.state.control.lastError,
408
+ this.bridge.diagnostic,
409
+ );
410
+ this.emit({
411
+ type: "turn_failed",
412
+ turnId: run.id,
413
+ error: failure.message,
414
+ code: failure.code,
415
+ diagnostic: formatDiagnostic(failure),
416
+ });
417
+ } else
418
+ this.emit({
419
+ type:
420
+ run.cancelled ||
421
+ headers.some((h) => h.state === "completedInterrupted")
422
+ ? "turn_canceled"
423
+ : "turn_completed",
424
+ turnId: run.id,
425
+ });
398
426
  this.changed();
399
427
  }
400
428
  private changed(): void {
@@ -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,111 @@
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
+ };
33
+
34
+ const messages: Record<
35
+ TurnFailureCode,
36
+ readonly [summary: string, advice?: string]
37
+ > = {
38
+ NATIVE_TURN_FAILED: ["ZCode turn failed"],
39
+ MODEL_RATE_LIMITED: [
40
+ "The model provider's usage or rate limit was reached",
41
+ "Wait for it to reset or switch models. For a ZCode Coding Plan, Paseo 0.11 and later show the reset times on the Usage screen.",
42
+ ],
43
+ MODEL_AUTH_FAILED: [
44
+ "The model provider is not signed in or rejected the credentials",
45
+ "Check the account and model providers in the Account tab of the zcode-provider Settings.",
46
+ ],
47
+ MODEL_CONTEXT_EXCEEDED: [
48
+ "The conversation exceeds the model's context window",
49
+ "Start a new session or switch to a model with a larger context window.",
50
+ ],
51
+ MODEL_NETWORK_ERROR: [
52
+ "ZCode could not reach the model provider",
53
+ "Check the network connection and try again.",
54
+ ],
55
+ MODEL_PROVIDER_ERROR: [
56
+ "The model provider returned a server error or is overloaded",
57
+ "Try again later.",
58
+ ],
59
+ MODEL_REQUEST_FAILED: ["The model provider rejected the request"],
60
+ };
61
+
62
+ /**
63
+ * Classifies a failed turn by the attribution of V4 `control.lastError`
64
+ * (ADR 23). ZCode's message and detail are never used: they can carry
65
+ * provider text, request content or credentials (ADR 7).
66
+ */
67
+ export function turnFailure(
68
+ lastError: SessionErrorInfo | null,
69
+ context: RuntimeDiagnostic,
70
+ ): AdapterError {
71
+ const attribution = lastError?.attribution;
72
+ const source = attribution?.source ?? lastError?.source;
73
+ const reason = modelFailureReasons.find((r) => r === attribution?.reason);
74
+ const code: TurnFailureCode =
75
+ source === "provider" || source === "network"
76
+ ? ((reason && reasonCodes[reason]) ??
77
+ (source === "network" ? "MODEL_NETWORK_ERROR" : "MODEL_REQUEST_FAILED"))
78
+ : "NATIVE_TURN_FAILED";
79
+ const statusCode = reportableStatusCode(attribution?.statusCode);
80
+ const providerErrorCode = reportableProviderErrorCode(
81
+ attribution?.providerErrorCode,
82
+ );
83
+ const facts = [
84
+ ...(statusCode ? [`HTTP ${statusCode}`] : []),
85
+ ...(providerErrorCode ? [`provider code ${providerErrorCode}`] : []),
86
+ ];
87
+ const [summary, advice] = messages[code];
88
+ return new AdapterError(
89
+ code,
90
+ `${summary}${facts.length ? ` (${facts.join(", ")})` : ""}.${advice ? ` ${advice}` : ""}`,
91
+ {},
92
+ undefined,
93
+ {
94
+ ...context,
95
+ stage: "turn",
96
+ ...(lastError
97
+ ? {
98
+ failure: {
99
+ source,
100
+ reason: attribution?.reason,
101
+ errorPhase: attribution?.errorPhase,
102
+ exceptionKind: attribution?.exceptionKind,
103
+ statusCode: attribution?.statusCode,
104
+ providerErrorCode: attribution?.providerErrorCode,
105
+ retryable: attribution?.retryable,
106
+ },
107
+ }
108
+ : {}),
109
+ },
110
+ );
111
+ }
package/server/usage.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createHash } from "node:crypto";
2
- // Types only, from the module every supported Paseo resolves; Paseo 0.8–0.10
2
+ // Types only, from the module every supported Paseo resolves; Paseo 0.9–0.10
3
3
  // reject `@getpaseo/plugin/server/usage` even as a type import.
4
4
  import type {
5
5
  UsageReport,
@@ -0,0 +1,12 @@
1
+ import { defineSettings } from "@getpaseo/plugin";
2
+ import { z } from "zod";
3
+
4
+ export const zcodeTimelineSettings = defineSettings({
5
+ id: "timeline",
6
+ scope: "host",
7
+ version: 1,
8
+ schema: z.object({ showModelChanges: z.boolean().default(false) }),
9
+ });
10
+ export type TimelinePreferences = z.output<typeof zcodeTimelineSettings.schema>;
11
+ export const defaultTimelinePreferences: TimelinePreferences =
12
+ zcodeTimelineSettings.schema.parse({});