Skip to content

Support ZCode 3.17.2 - #95

Merged
supermomonga merged 4 commits into
mainfrom
feat/zcode-upgrade-v3172
Nov 9, 2026
Merged

supermomonga merged 4 commits into
mainfrom
feat/zcode-upgrade-v3172

Conversation

@supermomonga

@supermomonga supermomonga commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Closes #70
Closes #84

Problem

  • ZCode 3.16.3 and 3.17.2 were unreviewed, and the managed runtime was still 3.16.2-paseo.1.
  • 3.16.3 has no public source: no tag, no GitHub Release, and no upstream commit whose root package.json is 3.16.3. Upstream then tagged v3.17.1 (a60ba6a) and v3.17.2 (a9fe401) again, with GitHub Releases. The changelog lists only 3.16.3 and 3.17.2 after 3.16.2, so this PR moves straight to 3.17.2 and reviews 3.16.3 from its notes.
  • Reading the 3.16.2 → 3.17.2 source turned up three things the provider has to handle (below). One of them predates 3.17 but matters more now.

Source and build

  • Baseline. The tag v3.17.2 (a9fe401eede6e6e5e01be9048679c206fe6f02d9). A tag satisfies ADR 15 directly. ADR 20 gets a dated note: prefer a matching tag, and keep the untagged-commit rule for releases like 3.16.1/3.16.2.
  • Vendored contracts. 126 files are resynchronized: 3 added, 1 removed, 28 changed. All V4/RPC additions are optional fields, query methods and a new EventError RPC frame.
    • sync-zcode-source.mjs --write failed on a vendored file the new baseline no longer needs. It now deletes such files; verification still rejects unexpected files.
  • Patch. The ADR 19 patch target is byte-identical to 3.16.2 (blob 0a9b571) and applies unchanged. Only its header's target commit changed; the SHA-256 is now 6f670f8….
  • Build. build-zcode.mjs, builtin-provider-config.mjs, the archive layout, Node 24.14.0+ and pnpm 10.33.2 are unchanged. The result is Server 3.17.2 / Agent 0.17.1.

Provider changes

  • App version in model requests (fix). The Agent puts ZCODE_APP_VERSION in User-Agent/X-ZCode-App-Version, or its CLI version without it.
    • Desktop sets it for its Server, and 3.17.2 added it to the remote Core because gateways reject clients by version. The stdio entry the provider uses does not set it, so the provider's requests said ZCode/0.17.1.
    • The bridge now passes the runtime's version, as Desktop does. ZCode Sites' CLI reads the same value.
  • Content-filtered replies (ADR 23). Since 3.17.1, an empty reply that the provider's content filter stopped (content-filter/content_filter/GLM's sensitive) fails at once with reason: "content_filter" instead of being retried. That reason is outside ModelFailureReason, so it fell to MODEL_REQUEST_FAILED and was dropped from the diagnostic. It is now MODEL_CONTENT_FILTERED.
  • Project MCP trust (3.17.1). A project's MCP servers are not connected until they are trusted in Desktop (Settings → MCP Servers). There is no CLI command, and no interaction appears, only V4 workspaceMcpAdmission.
    • Paseo's servers carry no source. ZCode treats them as project declarations when the project declares the same name or its config is unreadable, and blocks them. The provider now sends the new protocol scope: "user" (as Desktop does for user servers), only to 3.17.1+ Servers, because older strict schemas reject it.
    • Warning. A session that uses the project's MCP configuration (Paseo passed no servers) now gets a one-time warning while servers await trust. ZCode counts the project's declarations even when Paseo's list replaces them, so no warning is shown then.

Reviewed, no code change

  • ZCode Sites (new official plugin, defaultEnabled): its CLI runs from Bash and authenticates through the Server's official endpoint, which the stdio Server builds too. Only its panel is Desktop-only, and that panel's tools are hidden from the model. It is not suppressed; deployment itself is untested.
  • Plan mode tightening and subagent permission inheritance add no interaction kinds; build + Plan just asks more.
  • Custom command ! blocks become ordinary Bash calls.
  • Quota-stopped workflows stay stopped(provider). ZCode itself lets the session be reclaimed and resumes them on the next open, so the ADR 25 veto is unchanged. resultPending is still never cleared.
  • Guide drain now takes all waiting guides at one boundary. Each guide still has its own userInput row, so ADR 22 holds.
  • Account and usage. oauth, setting (CAS), provider-settings and usage-stats are unchanged where the provider uses them. Provider templates grew (Kimi, MiniMax M3.1 Flash, …).
  • Computer Use. Multi-cursor support is Helper-only. ZCODE_CUA_PRODUCT_HELPER and mcp__node_repl__js are unchanged.

Verification (macOS arm64)

  • Local checks. typecheck, npm test (24 files, 238 tests), build, format:check, check:zcode-source (126 files) and check:zcode-patches (clean v3.17.2 checkout) pass.
    • The new bridge test fails without the fix.
    • The MCP warning test fails both when the condition is removed and when the warning is suppressed.
  • test:upstream against Paseo v0.15.3 (d91ae138). All checks pass.
  • Local patched 3.17.2 build. Built from v3.17.2 with Node 24.21.0, pnpm 10.33.2 and ZCODE_ENV=production, then packaged as 3.17.2-paseo.0. It is not published.
    • test:stdio-runtime. All checks pass, including three new ones:
      • The model request carries the runtime version (before the fix: '0.17.1' !== '3.17.2').
      • A sensitive reply arrives as MODEL_CONTENT_FILTERED with exactly one model request.
      • Paseo's MCP tool reaches the model although the project declares the same server name. Without scope, this fails on 3.17.2 (the tool is missing).
    • test:e2e. Real model, isolated data: all passed.
    • test:native-restore. Still fails as recorded (expected edit + Plan ON, got yolo + Plan OFF).
  • Pinned 3.16.2-paseo.1 with the new code. test:stdio-runtime passes; the 3.17-only checks are gated.

Managed runtime 3.17.2-paseo.1

After the first CI run passed, zcode-runtime-v3.17.2-paseo.1 was pushed on f0dd526.

  • Release. Run 42576870272 built it, verified it on all five platforms, attested it and published it as a non-latest release.
  • Asset. zcode-runtime-3.17.2-paseo.1.tar.gz, 83,086,942 bytes, SHA-256 24e3a9b03260d7b800958ccba4cfdc8233eee67936170636da79d440245bd15d.
  • Checks on the downloaded asset.
    • gh attestation verify confirms the release workflow at that tag, with source f0dd526.
    • BUILD-INFO.json records a9fe401 (3.17.2) and patch 6f670f8…; the bundled patch is byte-identical to the repository's.
    • The built-in provider configuration is the production file.
  • Pinned in f2da56e.
    • The plugin's installer set it up into a temporary XDG_DATA_HOME, and test:stdio-runtime passed on it with source: managed (Server 3.17.2, Agent 0.17.1).
    • CI run 42578515911 then passed the managed-runtime contract on all five platforms, including the three new checks and the ADR 19 "hidden" branch, and the real-model E2E on the pinned runtime.
  • Flaky PR build. On the pin commit, the PR-triggered release build (run 42578515834) failed twice in upstream's pnpm install with ERR_PNPM_ENOENT (renaming into node_modules/tsup/node_modules/esbuild), then passed on the third attempt.
    • The runner image was the same as in the passing runs, and the same source had built twice before.
    • This looks like a pnpm race under upstream's node-linker=hoisted. It is recorded but not worked around.
  • Existing users need to reinstall from the Runtime tab, because the pin changed.

Not verified

  • Real data. Account-tab sign-in and Coding Plan usage on 3.17.2. This machine's Desktop is 3.16.3, and starting a 3.17.2 Server on shared data could migrate it ahead of Desktop.
  • ZCode Sites deployment.
  • MCP trust from Desktop. Whether trust granted in Desktop applies to the provider's sessions. This is inferred from the shared store path.
  • Platforms. Linux/Windows beyond CI.

Upstream tagged v3.17.1 and v3.17.2 again, so the baseline is the tag
v3.17.2 (a9fe401). 3.16.3 has no public source and is reviewed from its
changelog only. The vendored contracts are resynchronized (126 files);
the sync script now deletes vendored files the new baseline no longer
needs instead of failing. The ADR 19 patch applies unchanged; only its
target commit changed.
- Give the Server the runtime's ZCode version in ZCODE_APP_VERSION, as
  Desktop and 3.17.2's remote Core do. Without it the Agent reported the
  CLI version (0.17.1) in model request headers.
- Classify replies that the provider's content filter blocked, which
  ZCode 3.17.1+ fails at once with reason content_filter, as
  MODEL_CONTENT_FILTERED (ADR 23).
- Mark the MCP servers Paseo passes as user servers on 3.17.1+, so the
  new project MCP trust review does not block them when the project
  declares the same name, and warn when a session that uses the
  project's MCP configuration has servers awaiting trust.

Closes #70
Closes #84
zcode-runtime-v3.17.2-paseo.1 was built, verified on all five managed
platforms, attested and published from f0dd526 by run 42576870272.
Existing users need to reinstall the runtime from the Runtime tab.
@supermomonga
supermomonga merged commit 8f904d0 into main Nov 9, 2026
26 of 31 checks passed
@supermomonga
supermomonga deleted the feat/zcode-upgrade-v3172 branch November 9, 2026 08:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support ZCode 3.17.2 Support ZCode 3.16.3

1 participant