Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 35 additions & 46 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ jobs:
uses: actions/checkout@v6
with:
repository: zai-org/ZCode
ref: 872ad960de7ec172591f7e1952f7849229f94521
ref: 29628c9acdb81b703bbd4080c207a0e7ce5e276e
path: zcode-source
persist-credentials: false
- uses: actions/setup-node@v6
Expand All @@ -59,48 +59,43 @@ jobs:
run: npm run test:upstream -- "$GITHUB_WORKSPACE/paseo"

runtime:
name: Official stdio runtime contract
runs-on: ubuntu-24.04
timeout-minutes: 40
name: Managed runtime contract (${{ matrix.target }})
strategy:
fail-fast: false
matrix:
include:
- target: darwin-arm64
runner: macos-15
- target: linux-x64
runner: ubuntu-24.04
- target: linux-arm64
runner: ubuntu-24.04-arm
- target: win-x64
runner: windows-2025
- target: win-arm64
runner: windows-11-arm
runs-on: ${{ matrix.runner }}
timeout-minutes: 30
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v6
with:
path: plugin
persist-credentials: false
- uses: actions/checkout@v6
with:
repository: zai-org/ZCode
ref: 872ad960de7ec172591f7e1952f7849229f94521
path: zcode-source
persist-credentials: false
# The plugin runs on the daemon's Node.js; ZCode uses the managed Node.js.
- uses: actions/setup-node@v6
with:
node-version: "24.14.0"
- uses: pnpm/action-setup@v4
with:
version: "10.33.2"
- name: Build the official integrated CLI
working-directory: zcode-source
run: |
pnpm install --frozen-lockfile
pnpm exec tsc -b packages/shared
node scripts/build-zcode.mjs --base-url https://example.invalid/zcode/
- name: Extract outside the source checkout
run: |
mkdir "$RUNNER_TEMP/zcode-runtime"
sha256sum zcode-source/dist/zcode/releases/3.14.0/zcode-3.14.0.tar.gz
tar -xzf zcode-source/dist/zcode/releases/3.14.0/zcode-3.14.0.tar.gz -C "$RUNNER_TEMP/zcode-runtime"
echo "PASEO_ZCODE_RUNTIME=$RUNNER_TEMP/zcode-runtime/zcode" >> "$GITHUB_ENV"
echo "PASEO_ZCODE_NODE=$(command -v node)" >> "$GITHUB_ENV"
- uses: actions/upload-artifact@v4
with:
name: zcode-runtime-linux-x64
path: zcode-source/dist/zcode/releases/3.14.0/zcode-3.14.0.tar.gz
node-version: "22"
cache: npm
- name: Install plugin dependencies
working-directory: plugin
run: npm ci --include=dev
- name: Verify Provider behavior on the official runtime
working-directory: plugin
- name: Install the pinned managed runtime (ADR 15)
run: |
data=$(node -p "require('node:path').join(process.env.RUNNER_TEMP, 'zcode-data')")
echo "XDG_DATA_HOME=$data" >> "$GITHUB_ENV"
XDG_DATA_HOME="$data" npm run setup:managed-runtime
- name: Verify Provider behavior on the managed runtime
# Resume uses Paseo's saved mode and Plan settings (ADR 14).
# The separate test:native-restore tracks unsupported settings-free resume.
run: npm run test:stdio-runtime
Expand All @@ -120,20 +115,14 @@ jobs:
persist-credentials: false
- uses: actions/setup-node@v6
with:
node-version: "24.14.0"
node-version: "22"
cache: npm
- uses: actions/download-artifact@v4
with:
name: zcode-runtime-linux-x64
path: runtime-archive
- name: Configure official runtime
run: |
mkdir "$RUNNER_TEMP/zcode-runtime"
tar -xzf runtime-archive/zcode-3.14.0.tar.gz -C "$RUNNER_TEMP/zcode-runtime"
echo "PASEO_ZCODE_RUNTIME=$RUNNER_TEMP/zcode-runtime/zcode" >> "$GITHUB_ENV"
echo "PASEO_ZCODE_NODE=$(command -v node)" >> "$GITHUB_ENV"
- name: Install dependencies
run: npm ci --include=dev
- name: Install the pinned managed runtime
run: |
echo "XDG_DATA_HOME=$RUNNER_TEMP/zcode-data" >> "$GITHUB_ENV"
XDG_DATA_HOME="$RUNNER_TEMP/zcode-data" npm run setup:managed-runtime
- name: Run isolated real-model E2E
env:
GLM_API_KEY: ${{ secrets.GLM_API_KEY }}
Expand Down
179 changes: 179 additions & 0 deletions .github/workflows/zcode-runtime-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
name: ZCode Runtime Release

# Builds the integrated ZCode CLI from the pinned, unmodified public source,
# adds upstream license material, verifies it on every managed platform and
# publishes it only for zcode-runtime-v<version> tags (ADR 15).
on:
push:
tags: ["zcode-runtime-v*"]
pull_request:
paths:
- .github/workflows/zcode-runtime-release.yml
- scripts/package-zcode-runtime.mjs
- scripts/zcode-manifest.mjs
- scripts/check-stdio-runtime.mjs
- server/discovery/manifest.ts
workflow_dispatch:

permissions:
contents: read

concurrency:
group: zcode-runtime-${{ github.ref }}
cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}

env:
# The same Node.js builds the archive and runs Server/Agent in verification.
NODE_VERSION: "24.21.0"

jobs:
build:
name: Build runtime archive
runs-on: ubuntu-24.04
timeout-minutes: 30
outputs:
version: ${{ steps.package.outputs.version }}
commit: ${{ steps.package.outputs.commit }}
asset: ${{ steps.package.outputs.asset }}
sha256: ${{ steps.package.outputs.sha256 }}
size: ${{ steps.package.outputs.size }}
steps:
- uses: actions/checkout@v6
with:
path: plugin
persist-credentials: false
- uses: actions/setup-node@v6
with:
node-version: ${{ env.NODE_VERSION }}
- name: Install plugin dependencies
working-directory: plugin
run: npm ci --include=dev
- name: Resolve pinned ZCode source
id: source
working-directory: plugin
run: echo "commit=$(node scripts/package-zcode-runtime.mjs commit)" >> "$GITHUB_OUTPUT"
- uses: actions/checkout@v6
with:
repository: zai-org/ZCode
ref: ${{ steps.source.outputs.commit }}
path: zcode-source
persist-credentials: false
- uses: pnpm/action-setup@v4
with:
version: "10.33.2"
- name: Build the official integrated CLI
working-directory: zcode-source
run: |
pnpm install --frozen-lockfile
pnpm exec tsc -b packages/shared
node scripts/build-zcode.mjs --base-url https://example.invalid/zcode/
- name: Add upstream notices and build provenance
id: package
working-directory: plugin
env:
TAG: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }}
run: node scripts/package-zcode-runtime.mjs package --source ../zcode-source --out ../runtime-release ${TAG:+--tag "$TAG"}
- uses: actions/upload-artifact@v4
with:
name: zcode-runtime
path: runtime-release/
if-no-files-found: error

verify:
name: Verify ${{ matrix.target }}
needs: build
strategy:
fail-fast: false
matrix:
include:
- target: darwin-arm64
runner: macos-15
- target: linux-x64
runner: ubuntu-24.04
- target: linux-arm64
runner: ubuntu-24.04-arm
- target: win-x64
runner: windows-2025
- target: win-arm64
runner: windows-11-arm
runs-on: ${{ matrix.runner }}
timeout-minutes: 30
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v6
with:
persist-credentials: false
- uses: actions/setup-node@v6
with:
node-version: ${{ env.NODE_VERSION }}
cache: npm
- uses: actions/download-artifact@v4
with:
name: zcode-runtime
path: runtime-archive
- name: Check the archive and extract it outside the checkout
env:
ASSET: ${{ needs.build.outputs.asset }}
SHA256: ${{ needs.build.outputs.sha256 }}
run: |
actual=$(node -e "const c=require('node:crypto').createHash('sha256');c.update(require('node:fs').readFileSync(process.argv[1]));console.log(c.digest('hex'))" "runtime-archive/$ASSET")
test "$actual" = "$SHA256"
mkdir ../zcode-runtime
tar -xzf "runtime-archive/$ASSET" -C ../zcode-runtime
for file in LICENSE NOTICE.md THIRD-PARTY-NOTICES.md BUILD-INFO.json; do
test -f "../zcode-runtime/zcode/$file"
done
echo "PASEO_ZCODE_RUNTIME=$(node -p "require('node:path').resolve('../zcode-runtime/zcode')")" >> "$GITHUB_ENV"
echo "PASEO_ZCODE_NODE=$(node -p process.execPath)" >> "$GITHUB_ENV"
- name: Install plugin dependencies
run: npm ci --include=dev
- name: Verify Provider behavior on the runtime
# Resume uses Paseo's saved mode and Plan settings (ADR 14).
run: npm run test:stdio-runtime

publish:
name: Publish runtime release
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/zcode-runtime-v')
needs: [build, verify]
runs-on: ubuntu-24.04
timeout-minutes: 10
permissions:
contents: write
id-token: write
attestations: write
steps:
- uses: actions/download-artifact@v4
with:
name: zcode-runtime
path: release
- uses: actions/attest-build-provenance@v4
with:
subject-path: release/${{ needs.build.outputs.asset }}
- name: Create the GitHub release
env:
GH_TOKEN: ${{ github.token }}
TAG: ${{ github.ref_name }}
VERSION: ${{ needs.build.outputs.version }}
COMMIT: ${{ needs.build.outputs.commit }}
ASSET: ${{ needs.build.outputs.asset }}
SHA256: ${{ needs.build.outputs.sha256 }}
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
run: |
cat > notes.md <<EOF
Unofficial build of the ZCode integrated CLI distribution for paseo-plugin-zcode-provider's managed setup. It is not endorsed or maintained by ZCode or Z.ai.

- Source: https://github.com/zai-org/ZCode/tree/$COMMIT (ZCode $VERSION, unmodified)
- Asset: \`$ASSET\`
- SHA-256: \`$SHA256\`
- Built and verified by: $RUN_URL

ZCode first-party code is licensed under Apache-2.0. Third-party components keep their own terms. The archive contains the upstream LICENSE, NOTICE.md and THIRD-PARTY-NOTICES.md.
EOF
gh release create "$TAG" "release/$ASSET" release/SHA256SUMS \
--repo "$GITHUB_REPOSITORY" \
--verify-tag \
--latest=false \
--title "ZCode runtime $VERSION (unofficial build)" \
--notes-file notes.md
16 changes: 9 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

## Project Structure

This plugin connects Paseo's public Provider API to the official stdio Services Server included in the integrated ZCode CLI distribution.
This plugin connects Paseo's public Provider API to the official stdio Services Server included in the integrated ZCode CLI distribution. The Setup screen installs a pinned build of that distribution and Node.js (ADR 15).

- `index.server.ts` / `index.client.tsx`: Server and settings UI registration.
- `server/`: Provider, sessions, and persistence. `discovery/` locates installations; `host/` and `protocol/` handle startup, communication, and validation.
- `client/`: React Native diagnostics UI. `shared/` contains types and contracts shared by the server and client.
- `server/`: Provider, sessions, and persistence. `discovery/` locates installations; `runtime/` pins and installs the managed runtime; `host/` and `protocol/` handle startup, communication, and validation.
- `client/`: React Native Setup and Diagnostics screens. `shared/` contains types and contracts shared by the server and client.
- `test/`: Integration tests and `fake-host.ts`. Unit tests also live in `server/`.
- `scripts/`: Build, upstream integration, and runtime verification scripts. `docs/` contains development procedures, verification records, and ADRs. Images live in `images/` and `icon.svg`.

Expand All @@ -20,6 +20,7 @@ Use Node.js **22.12.0 or later** and npm.
- `npm run build`: Generate `dist/index.server.js` and verify that the runtime SDK is not included in the bundle.
- `npm run format:check` / `npm run format`: Check or apply Prettier formatting.
- `npm run test:upstream -- /absolute/path/to/paseo`: Verify integration using the actual compiler and Provider adapter from a supported Paseo checkout. See `docs/development.md` for the target commit.
- `npm run setup:managed-runtime`: Install the pinned managed runtime with the plugin's installer. Set `XDG_DATA_HOME` to keep it out of your real data directory.
- `npm run test:runtime -- /absolute/path/to/workspace`: Initialize the installed host and retrieve the model list. No prompts are sent.
- `npm run test:e2e`: Opt-in real-model checks on macOS/Linux using `GLM_API_KEY` (Z.ai Coding Plan), isolated ZCode data, and the installed host. Also runs in eligible PR CI jobs; separate from `npm test`. See `docs/development.md` for coverage and secret requirements.

Expand Down Expand Up @@ -48,11 +49,12 @@ PRs should describe the problem, the resulting behavior, related issues, verific
Identify the root cause and do not add ad hoc workarounds. Add backward compatibility logic only when explicitly instructed. Consult the existing `docs/adr/` for design decisions. Do not commit credentials, conversation content, generated artifacts, or the local `mise.local.toml`. Use `gh` for GitHub operations and investigations.

- If `ghq` is installed on the local machine and the Paseo source repository has been cloned at `$(ghq root)/getpaseo/paseo`, it is recommended to consult that checkout when investigating Paseo's implementation.
- Limit implementations and proposed solutions to this Paseo plugin. Do not modify Paseo or ZCode itself, or require a fork, source patch, or patched upstream runtime. Building official ZCode from unmodified source for verification is allowed.
- Limit implementations and proposed solutions to this Paseo plugin. Do not modify Paseo or ZCode itself, or require a fork, source patch, or patched upstream runtime. Building official ZCode from unmodified source is allowed for verification and for the runtime release (ADR 15).

- Use `~/ghq/github.com/zai-org/ZCode` as the implementation reference. Record commit SHA and source paths; do not extract Electron/deb bundles for source investigation.
- Current source baseline: `872ad960de7ec172591f7e1952f7849229f94521`. Verify vendored RPC/V4 source with `npm run check:zcode-source`. Keep `server/vendor/zcode` unformatted and retain its license/provenance.
- Require `PASEO_ZCODE_RUNTIME` and ordinary Node.js 24.14.0+ via `PASEO_ZCODE_NODE`. CLI installation and updates belong to the user. Never fall back to Desktop/Electron.
- `npm run test:stdio-runtime` uses the real runtime with isolated data and a local model fixture. Resume guarantees require both Paseo's saved `mode` and `settings.plan_mode`; failures of this supported contract block release. Keep source SHA, distribution hashes, runtime versions and actual OS coverage separate.
- Current source baseline: `29628c9acdb81b703bbd4080c207a0e7ce5e276e`. Verify vendored RPC/V4 source with `npm run check:zcode-source`. Keep `server/vendor/zcode` unformatted and retain its license/provenance.
- The managed runtime is the default (ADR 15): Node.js from nodejs.org and the `zcode-runtime-v<version>` release of this repository, both pinned by SHA-256 in `server/runtime/pins.ts` and installed only when the user starts setup. Setup RPCs never accept URLs, paths or versions from clients. `PASEO_ZCODE_RUNTIME` plus ordinary Node.js 24.14.0+ via `PASEO_ZCODE_NODE` override it; one variable alone is an error. Never fall back to Desktop/Electron.
- To ship a new ZCode version, update the source baseline, push a `zcode-runtime-v<version>` tag so `.github/workflows/zcode-runtime-release.yml` builds, verifies on all managed platforms and publishes the archive, then pin the published SHA-256 and size. Never replace an existing release asset.
- `npm run test:stdio-runtime` uses the real runtime (override pair or managed runtime under `XDG_DATA_HOME`) with isolated data and a local model fixture. Resume guarantees require both Paseo's saved `mode` and `settings.plan_mode`; failures of this supported contract block release. Keep source SHA, distribution hashes, runtime versions and actual OS coverage separate.
- `npm run test:native-restore` separately checks resume without explicit settings. The pinned upstream fails this unsupported path; retain its nonzero exit and run it when evaluating runtime updates. It is not a required CI or release condition (ADR 14).
- Persistence handles use version 3. Do not migrate old Paseo handles or introduce Plan restoration storage.
Loading
Loading