From ce45acd56034c6b8911463cf788d985be043c540 Mon Sep 17 00:00:00 2001 From: zhangy <40223340+zy1233@users.noreply.github.com> Date: Sun, 15 Nov 2026 17:06:33 +0000 Subject: [PATCH 1/6] feat: promote to 1.0.0 Stable, add zypi --setup and omarchy linux integration spec --- .github/workflows/agent-binaries.yml | 29 +- .github/workflows/release.yml | 47 ++- CHANGELOG.md | 18 +- README.md | 45 +-- docs/TUI-AND-CODE-AGENT.md | 39 ++- docs/specs/2026-11-15-omarchy-agent-pr.md | 323 ++++++++++++++++++ packages/pi-agent-cli/AGENTS.md | 11 +- packages/pi-agent-cli/pyproject.toml | 12 +- .../tests/test_packaging_bundle.py | 69 ++++ packages/pi-agent-harness/pyproject.toml | 6 +- packages/pi-dynamic-workflows/pyproject.toml | 6 +- packages/pi-goal-x/pyproject.toml | 4 +- packages/pi-mcp/README.md | 2 +- packages/pi-mcp/pyproject.toml | 4 +- packages/pi-web-access/pyproject.toml | 4 +- packaging/agent/build.py | 84 +++++ pyproject.toml | 12 +- scripts/tui_baseline.toml | 4 +- tui/Cargo.lock | 4 +- tui/crates/codegen/pi-pager-bin/Cargo.toml | 2 +- .../pi-pager-bin/src/interactive_flags.rs | 2 +- tui/crates/codegen/pi-pager-bin/src/main.rs | 27 +- tui/crates/codegen/pi-pager/src/acp/spawn.rs | 109 +++++- tui/crates/codegen/pi-pager/src/app/cli.rs | 19 ++ tui/crates/codegen/pi-version/Cargo.toml | 2 +- web/src/data/site.ts | 14 +- web/src/i18n/en.ts | 6 +- web/src/i18n/zh.ts | 6 +- 28 files changed, 822 insertions(+), 88 deletions(-) create mode 100644 docs/specs/2026-11-15-omarchy-agent-pr.md create mode 100644 packages/pi-agent-cli/tests/test_packaging_bundle.py diff --git a/.github/workflows/agent-binaries.yml b/.github/workflows/agent-binaries.yml index e2dca273..1cb6872b 100644 --- a/.github/workflows/agent-binaries.yml +++ b/.github/workflows/agent-binaries.yml @@ -192,13 +192,17 @@ jobs: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} TAG: ${{ needs.plan.outputs.tag }} + VERSION: ${{ needs.plan.outputs.version }} steps: + - uses: actions/checkout@v7 + with: + ref: ${{ needs.plan.outputs.ref }} - uses: actions/download-artifact@v7 with: pattern: agent-* path: archives merge-multiple: true - - name: Create the release if it is not there, then upload + - name: Create the release if it is not there, download zypi binaries, build bundles, and upload run: | ls -l archives if ! gh release view "$TAG" >/dev/null 2>&1; then @@ -206,5 +210,28 @@ jobs: gh release create "$TAG" --title "$TAG" --notes "Agent binaries for $TAG." --verify-tag \ || gh release view "$TAG" >/dev/null fi + + mkdir -p tui-downloads + for asset in zypi-linux-x86_64 zypi-linux-aarch64 zypi-macos-arm64; do + gh release download "$TAG" -p "$asset" -D tui-downloads 2>/dev/null || true + done + + # Pairs of (zypi_asset_name, target) + for pair in "zypi-linux-x86_64:linux-x86_64" "zypi-linux-aarch64:linux-aarch64" "zypi-macos-arm64:darwin-aarch64"; do + asset="${pair%%:*}" + target="${pair##*:}" + tui_bin="tui-downloads/$asset" + agent_archive="archives/zycode-agent-$target-$VERSION.tar.gz" + if [ -f "$tui_bin" ] && [ -f "$agent_archive" ]; then + chmod +x "$tui_bin" + python3 packaging/agent/build.py \ + --bundle-from-archive "$agent_archive" \ + --tui-binary "$tui_bin" \ + --target "$target" \ + --version "$VERSION" \ + --out archives + fi + done + gh release upload "$TAG" archives/* --clobber gh release view "$TAG" --json assets --jq '.assets[] | "\(.name) \(.size) \(.digest)"' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b7ec8501..75553f82 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -112,6 +112,46 @@ jobs: name: tui-binary path: zypi-linux-x86_64 + build-tui-linux-arm: + name: Build TUI binary (Linux aarch64) + needs: test + runs-on: ubuntu-24.04-arm + steps: + - uses: actions/checkout@v7 + + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable + + - name: Cache Cargo registry and build + uses: actions/cache@v5 + with: + path: | + ~/.cargo/registry + ~/.cargo/git + tui/target + key: tui-release-${{ runner.os }}-arm64-${{ hashFiles('tui/Cargo.lock') }} + restore-keys: tui-release-${{ runner.os }}-arm64- + + - name: Install protoc + uses: arduino/setup-protoc@v3 + with: + version: "28.x" + repo-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Build zypi (release-dist) + working-directory: tui + run: cargo build --profile release-dist -p pi-pager-bin + + - name: Prepare binary artifact + run: | + cp tui/target/release-dist/zypi zypi-linux-aarch64 + chmod +x zypi-linux-aarch64 + + - uses: actions/upload-artifact@v6 + with: + name: tui-binary-linux-aarch64 + path: zypi-linux-aarch64 + build-tui-macos-arm: name: Build TUI binary (macOS arm64) needs: test @@ -173,7 +213,7 @@ jobs: github-release: name: GitHub Release - needs: [build, build-tui, build-tui-macos-arm] + needs: [build, build-tui, build-tui-linux-arm, build-tui-macos-arm] # Same rule as publish-pypi. if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') runs-on: ubuntu-latest @@ -192,6 +232,11 @@ jobs: name: tui-binary path: tui-bin/ + - uses: actions/download-artifact@v7 + with: + name: tui-binary-linux-aarch64 + path: tui-bin/ + - uses: actions/download-artifact@v7 with: name: tui-binary-macos-arm64 diff --git a/CHANGELOG.md b/CHANGELOG.md index a84a37e8..ee7a8d5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [0.9.1] - 2026-11-12 +## [1.0.0] - 2026-11-15 + +This is the 1.0.0 (Production/Stable) release of zycode. All components across the monorepo are promoted to 1.0.0 Stable. + +### Added + +- **Standalone ACP agent resolution in TUI (`zypi`)**: `zypi` resolves `zycode-agent` (`zycode-agent.exe` on Windows) by default next to the `zypi` executable (or following symlinks) or on `PATH`. It no longer falls back to bare `python -m pi_agent_cli` when `PI_PYTHON` is unset. Resolution order: `PI_AGENT_COMMAND` → `[agent].command` (in `agent.toml` / `config.toml`) → `PI_PYTHON` (only when explicitly set and non-empty) → default `zycode-agent` binary. +- **Terminal setup command `zypi --setup`**: Added `--setup` flag to `zypi` to directly launch the agent's interactive setup dialog in the terminal to configure the provider, model, and API key before running interactive sessions. +- **Combined standalone bundles (`zycode--.tar.gz`)**: Release workflows and `packaging/agent/build.py` now build combined tarballs bundling both `zypi` and `zycode-agent` at archive root (`0o755`), providing a zero-Python installation experience. +- **Linux aarch64 TUI binary in release workflow**: Added `build-tui-linux-arm` job to `.github/workflows/release.yml` on `ubuntu-24.04-arm` to build and publish `zypi-linux-aarch64`. +- **Omarchy Linux Agent integration**: Full specification, packaging, and integration scripts for adding zycode (`zypi`) to Omarchy Linux's Agent menu and mise configuration. + +### Changed + +- **Version 1.0.0 Stable promotion**: All Python packages (`pi-agent-core-lc`, `pi-agent-harness-lc`, `pi-agent-cli-lc`, `pi-web-access-py`, `pi-goal-x-py`, `pi-dynamic-workflows-py`, `pi-mcp-py`), Rust TUI (`pi-pager-bin`, `pi-version`), and documentation/web are promoted to `1.0.0` with `Development Status :: 5 - Production/Stable`. +- Refusal message for `zypi --oauth` updated to direct users to `zypi --setup`. +- Updated spawn error messages to guide placing `zycode-agent` next to `zypi` or setting `PI_AGENT_COMMAND` / `PI_PYTHON`. This is a patch release. It has one fix: `provider = "openai"` now shows the thinking that a gateway streams as `reasoning_content`. **Fixed** has the details. The VS Code extension needs a new agent binary to get the fix, so it needs a new Release and a new VSIX. **Changed** has the new version numbers. **Known issues** says that the 0.9.0 list still holds. diff --git a/README.md b/README.md index c2d2de41..613a9c06 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ This repository is a monorepo containing: - `pi-dynamic-workflows-py` / `pi_dynamic_workflows`: workflow orchestration extension. - `pi-mcp-py` / `pi_mcp`: optional extension that connects the MCP servers an ACP client (an editor) passes (see [`packages/pi-mcp`](packages/pi-mcp/README.md)). -**Rust TUI** (beta — prebuilt binary in [GitHub Releases](https://github.com/zy1233/pi-python/releases)): +**Rust TUI** (prebuilt binaries in [GitHub Releases](https://github.com/zy1233/pi-python/releases)): - `zypi`: full-screen terminal UI for interactive coding-agent sessions. Vendored fork of [grok-build](https://github.com/xai-org/grok-build) (Apache-2.0), with all `x.ai/*` vendor extensions removed. It offers three permission modes (Shift+Tab): Normal (`ask`, the start mode), Auto and Always-Approve. See [TUI & Code-Agent Guide](docs/TUI-AND-CODE-AGENT.md) for details. @@ -35,13 +35,13 @@ This repository is a monorepo containing: |-----------|--------|--------------| | `pi-agent-core-lc` | **Stable** | [PyPI](https://pypi.org/project/pi-agent-core-lc/) | | `pi-agent-harness-lc` | **Stable** | [PyPI](https://pypi.org/project/pi-agent-harness-lc/) | -| `pi-agent-cli-lc` | **Beta** | [PyPI](https://pypi.org/project/pi-agent-cli-lc/) | -| `pi-web-access-py` | **Beta** | [PyPI](https://pypi.org/project/pi-web-access-py/) | -| `pi-goal-x-py` | **Beta** | [PyPI](https://pypi.org/project/pi-goal-x-py/) | -| `pi-dynamic-workflows-py` | **Beta** | [PyPI](https://pypi.org/project/pi-dynamic-workflows-py/) | -| `pi-mcp-py` | **Alpha** | [PyPI](https://pypi.org/project/pi-mcp-py/) (from 0.6.0) | -| `zypi` (Rust TUI) | **Beta** | [GitHub Releases](https://github.com/zy1233/pi-python/releases) (Linux x86_64) | -| `zycode.zycode` (VS Code extension) | **Beta** | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zycode.zycode) and [Open VSX](https://open-vsx.org/extension/zycode/zycode) (five platforms; the project owner tested the install of 1.0.0 and the update from 0.1.0 to 1.0.0 on Windows on 2026-11-12; the rest of the Windows flow, macOS and Linux in a real VS Code are not verified) | +| `pi-agent-cli-lc` | **Stable** | [PyPI](https://pypi.org/project/pi-agent-cli-lc/) | +| `pi-web-access-py` | **Stable** | [PyPI](https://pypi.org/project/pi-web-access-py/) | +| `pi-goal-x-py` | **Stable** | [PyPI](https://pypi.org/project/pi-goal-x-py/) | +| `pi-dynamic-workflows-py` | **Stable** | [PyPI](https://pypi.org/project/pi-dynamic-workflows-py/) | +| `pi-mcp-py` | **Stable** | [PyPI](https://pypi.org/project/pi-mcp-py/) (from 0.6.0) | +| `zypi` (Rust TUI) | **Stable** | [GitHub Releases](https://github.com/zy1233/pi-python/releases) (Linux x86_64 and aarch64, macOS arm64) | +| `zycode.zycode` (VS Code extension) | **Stable** | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zycode.zycode) and [Open VSX](https://open-vsx.org/extension/zycode/zycode) (five platforms; the project owner tested the install of 1.0.0 and the update from 0.1.0 to 1.0.0 on Windows on 2026-11-12; the rest of the Windows flow, macOS and Linux in a real VS Code are not verified) | ## Features @@ -72,7 +72,7 @@ This repository is a monorepo containing: - LangChain `BaseTool` → `AgentTool` adapter (`from_langchain_tool`) — MCP tools via `langchain-mcp-adapters` work out of the box - The CLI itself has no MCP client. The optional `pi-mcp-py` extension connects the MCP servers that an ACP client passes in `session/new` (stdio, Streamable HTTP, SSE) and shows their tools as `mcp____`; without it, the agent says that their tools are not available in the session -**Coding Agent CLI** (Phase 4 — beta) +**Coding Agent CLI** (Phase 4) - `pi_agent_cli`: standard ACP coding agent over `AgentHarness` — no `x.ai/*` vendor extensions - Headless mode: `python -m pi_agent_cli -p "prompt"` for scripting and CI @@ -83,12 +83,12 @@ This repository is a monorepo containing: - Extensions that fail to load (import error, bad entry point, `activate()` raising, invalid tool name) are skipped, and the agent says so at session start (ACP agent message; headless stderr) instead of just not having them. `PI_HOME` moves the whole home: config, `extensions/`, saved workflows and workflow journals - Git workspace context (``) is a session-start snapshot in the system prompt (kept stable for the provider prompt cache; the block tells the model to run `git status` for live state); `--no-git-context` or `[git] enabled = false` turns it off. The snapshot is taken only for a trusted project (see project trust below): `git status` runs the program that a repository's own `.git/config` names in `core.fsmonitor`, so an untrusted project, which includes the default case of a project that ships no extensions or prompt files, gets no `` block (to get it back: `[extensions]` `trusted_projects = ["~/work"]` in `~/.pi-python/agent.toml`, or `default_project_trust = "always"`). The block (branch name and the paths of changed and untracked files) goes to the model provider with the rest of the system prompt, so turn it off if such names are sensitive -**TUI — `zypi`** (Phase 4 — beta) +**TUI — `zypi`** (Phase 4) - Full-screen Rust terminal UI for interactive coding-agent sessions -- Spawns the Python ACP agent (`python -m pi_agent_cli`) as the backend +- Spawns `zycode-agent` next to it or on `PATH` by default, or the Python ACP agent when configured (`PI_AGENT_COMMAND`, `[agent].command`, or `PI_PYTHON`) - Session management, markdown rendering, Mermaid diagrams, MCP support -- Prebuilt Linux x86_64 binary in [GitHub Releases](https://github.com/zy1233/pi-python/releases); build from source for other platforms +- Prebuilt binaries for Linux (x86_64, aarch64) and macOS (arm64) in [GitHub Releases](https://github.com/zy1233/pi-python/releases); standalone tarballs (`zycode--.tar.gz`) bundle `zypi` and `zycode-agent` together with zero Python dependencies required - See [TUI & Code-Agent Guide](docs/TUI-AND-CODE-AGENT.md) for setup and usage **FrontierHarness Evaluation** (30-task benchmark) @@ -131,20 +131,27 @@ pip install -e "./packages/pi-mcp" # optional: MCP servers that the editor pas -### TUI binary (`zypi`) — beta +### TUI binary (`zypi`) -Download the prebuilt binary for Linux x86_64 or macOS arm64 from [GitHub Releases](https://github.com/zy1233/pi-python/releases): +Download the prebuilt binary or the complete standalone archive for Linux (x86_64 or aarch64) or macOS arm64 from [GitHub Releases](https://github.com/zy1233/pi-python/releases): ```bash -# Download and install (Linux x86_64) +# Option 1: Standalone bundle (contains both zypi and zycode-agent; no Python required) +curl -L -o zycode.tar.gz https://github.com/zy1233/pi-python/releases/latest/download/zycode-linux-x86_64-1.0.0.tar.gz +tar -xzf zycode.tar.gz +sudo mv zypi zycode-agent /usr/local/bin/ + +# Option 2: Standalone zypi (spawns zycode-agent next to it, on PATH, or via PI_AGENT_COMMAND / PI_PYTHON) curl -L -o zypi https://github.com/zy1233/pi-python/releases/latest/download/zypi-linux-x86_64 chmod +x zypi sudo mv zypi /usr/local/bin/ -# macOS arm64 (Apple silicon): the same steps with the file zypi-macos-arm64 -# (built in CI, not yet run by a person; see the TUI guide) +# Set up model and API key directly in terminal: +zypi --setup +``` -# Or build from source (requires Rust toolchain) +Or build from source (requires Rust toolchain): +```bash cd tui && cargo build --profile release-dist -p pi-pager-bin # binary at target/release-dist/zypi ``` @@ -571,7 +578,7 @@ Use `.venv-test-real` for pytest real-LLM tests; the smoke script can run from t - **Phase 2.5 (core hardening)** — done: retries, runaway protection, observability, granular events, guardrail hooks, `ContextBudget`, structured output, tool-result images - **Phase 3 (AgentHarness)** — done: H1 session tree, H2 runtime, H3 compaction/tree navigation, H4 skills/templates/system prompt/LocalExecutionEnv ([design doc](docs/specs/2026-07-03-phase3-agent-harness-design.md)) - **Phase 3.5 (tool ecosystem)** — done: all 7 built-in tools (read/bash/edit/write/grep/find/ls), group factories, and the LangChain `BaseTool` adapter ([design doc](docs/specs/2026-07-03-phase3.5-tool-ecosystem-design.md)) -- **Phase 4 (Coding Agent CLI — beta)** — done: `tui/` vendored grok-build fork (Apache-2.0); `pi_agent_cli` standard ACP agent; TUI binary `zypi`; `x.ai/*` vendor RPCs removed; session management (`/new` `/resume` `/quit`); headless `-p`; `config.toml` + Windows notes ([design doc](docs/specs/2026-08-25-phase4-coding-agent-cli-design.md), [Windows](docs/WINDOWS.md), [TUI guide](docs/TUI-AND-CODE-AGENT.md)) +- **Phase 4 (Coding Agent CLI)** — done: `tui/` vendored grok-build fork (Apache-2.0); `pi_agent_cli` standard ACP agent; TUI binary `zypi`; `x.ai/*` vendor RPCs removed; session management (`/new` `/resume` `/quit`); headless `-p`; `config.toml` + Windows notes ([design doc](docs/specs/2026-08-25-phase4-coding-agent-cli-design.md), [Windows](docs/WINDOWS.md), [TUI guide](docs/TUI-AND-CODE-AGENT.md)) - **Phase 5 (Coding Agent prompt engine)** — done: pi-aligned `build_system_prompt` + tool contributions + context files + `` ([design doc](docs/specs/2026-09-02-phase5-prompt-engine-design.md)) - **Phase 6 (extended integrations)** — done: git workspace context in the system prompt; opt-in multi-provider live matrix. MCP stays a caller-side `BaseTool` import ([design doc](docs/specs/2026-09-24-phase6-extended-integrations-design.md)); the optional `pi-mcp-py` extension (2026-10) connects the servers an editor passes, and the core, harness and CLI still hold no MCP client ([design doc](docs/specs/2026-10-23-mcp-extension-design.md)) - **Phase 7 (extension packages)** — done: `pi-web-access-py`, `pi-goal-x-py`, `pi-dynamic-workflows-py` ([design doc](docs/specs/2026-09-22-phase7-extension-api-design.md)) diff --git a/docs/TUI-AND-CODE-AGENT.md b/docs/TUI-AND-CODE-AGENT.md index 2ceb270b..174b9125 100644 --- a/docs/TUI-AND-CODE-AGENT.md +++ b/docs/TUI-AND-CODE-AGENT.md @@ -1,6 +1,6 @@ # TUI & Code-Agent Guide -> **Status: Beta** — The TUI (`zypi`) and coding agent (`pi_agent_cli`) are functional but under active development. APIs, configuration, and binary distribution may change between releases. +> **Status: Stable (1.0.0)** — The TUI (`zypi`) and coding agent (`pi_agent_cli` / `zycode-agent`) are production ready. This document covers how to install, configure, and use the pi-python coding agent — both the headless Python CLI and the full-screen Rust TUI. @@ -17,7 +17,7 @@ This document covers how to install, configure, and use the pi-python coding age │ ACP (Agent Client Protocol) over stdio ▼ ┌─────────────────────────────────────┐ -│ pi_agent_cli (Python ACP) │ Standard ACP agent +│ zycode-agent / pi_agent_cli (ACP) │ Standard ACP agent │ System prompt engine, tool │ MIT license │ contributions, context files │ └────────────┬────────────────────────┘ @@ -37,7 +37,7 @@ This document covers how to install, configure, and use the pi-python coding age └─────────────────────────────────────┘ ``` -The TUI (`zypi`) is the interactive frontend. It communicates with the Python coding agent (`pi_agent_cli`) over the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) via stdio. The Python agent handles all LLM calls, tool execution, and session management through the core engine. `zypi` has no model client, no tool runner and no MCP client. A process-level audit of a real turn (`docs/PLAN/archive/PLAN-RUST-AGENT-RUNTIME-REMOVAL-EXECUTION-LOG.md`, section 10.14) found no connection from `zypi` to any address outside the machine. +The TUI (`zypi`) is the interactive frontend. It communicates with the ACP coding agent (`zycode-agent` binary or `pi_agent_cli` Python module) over the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) via stdio. The agent handles all LLM calls, tool execution, and session management through the core engine. `zypi` has no model client, no tool runner and no MCP client. A process-level audit of a real turn (`docs/PLAN/archive/PLAN-RUST-AGENT-RUNTIME-REMOVAL-EXECUTION-LOG.md`, section 10.14) found no connection from `zypi` to any address outside the machine. You can use the coding agent in two ways: @@ -48,7 +48,21 @@ You can use the coding agent in two ways: ## Installation -### 1. Python packages (required) +### 1. Standalone bundle (recommended — no Python required) + +Download the complete bundle `zycode--.tar.gz` from [GitHub Releases](https://github.com/zy1233/pi-python/releases): + +```bash +# Linux x86_64 +curl -L -o zycode.tar.gz https://github.com/zy1233/pi-python/releases/latest/download/zycode-linux-x86_64-1.0.0.tar.gz +tar -xzf zycode.tar.gz +sudo mv zypi zycode-agent /usr/local/bin/ + +# Initial setup in terminal +zypi --setup +``` + +### 2. Python packages (optional / dev) ```bash # Using pip @@ -58,11 +72,11 @@ pip install pi-agent-cli-lc pip install -e ".[dev]" -e "./packages/pi-agent-harness" -e "./packages/pi-agent-cli" ``` -### 2. TUI binary (`zypi`) +### 3. TUI binary (`zypi`) alone -#### Option A: Download prebuilt binary (Linux x86_64, macOS arm64) +#### Option A: Download prebuilt binary (Linux x86_64, Linux aarch64, macOS arm64) -Prebuilt binaries are attached to [GitHub Releases](https://github.com/zy1233/pi-python/releases). The Linux x86_64 binary has been there since v0.3.0. The macOS arm64 binary (Apple silicon) starts with v0.5.0. +Prebuilt binaries are attached to [GitHub Releases](https://github.com/zy1233/pi-python/releases). ```bash # Linux x86_64 @@ -70,6 +84,11 @@ curl -L -o zypi https://github.com/zy1233/pi-python/releases/latest/download/zyp chmod +x zypi sudo mv zypi /usr/local/bin/ +# Linux aarch64 +curl -L -o zypi https://github.com/zy1233/pi-python/releases/latest/download/zypi-linux-aarch64 +chmod +x zypi +sudo mv zypi /usr/local/bin/ + # macOS arm64 curl -L -o zypi https://github.com/zy1233/pi-python/releases/latest/download/zypi-macos-arm64 chmod +x zypi @@ -123,8 +142,10 @@ base_url = "https://api.siliconflow.cn/v1" # for OpenAI-compatible gatew paths = ["~/.pi-python/skills", ".pi/skills"] [agent] -# Override how the TUI spawns the Python agent (optional) -command = "python -m pi_agent_cli" +# Override how the TUI spawns the ACP agent (optional). +# By default, zypi searches for `zycode-agent` next to itself (or following symlinks) +# or on PATH. Set this or PI_AGENT_COMMAND or PI_PYTHON to override. +command = "zycode-agent" [extensions] # Projects that may use their own /.pi-python/extensions (arbitrary Python), diff --git a/docs/specs/2026-11-15-omarchy-agent-pr.md b/docs/specs/2026-11-15-omarchy-agent-pr.md new file mode 100644 index 00000000..74fbaf9c --- /dev/null +++ b/docs/specs/2026-11-15-omarchy-agent-pr.md @@ -0,0 +1,323 @@ +# Omarchy Linux: Add zycode (`zypi`) Coding Agent to Agent Menu + +> Date: 2026-11-15 +> Status: **Ready for Submission** +> Upstream target: `omacom/omarchy` (`quattro` branch) +> Component: Omarchy desktop coding agent menu & launcher + +--- + +## 1. Background & Rationale + +Omarchy Linux provides a curated set of coding agents selectable via the Super+A / Super+Space desktop Agent menu (`omarchy-default-agent`) and launchable via the unified terminal wrapper `omarchy-agent`. Supported agents range from cloud harness CLIs to open-source terminal agents (such as Pi, Qwen Code, Kiro, Devin, Amp, Command Code, etc.). + +`zycode` is an open-source, full-featured agentic coding environment: +- **TUI binary (`zypi`)**: High-performance Rust terminal user interface built on an ACP client architecture with rich split-pane diff review, streaming markdown, syntax-highlighted tool inspections, and three permission modes (`ask`, `auto`, `always-approve`). +- **Core runtime (`zycode-agent`)**: Standalone binary executing the agent loop, coding tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`), sandboxed workflows, and MCP server integrations. +- **Self-contained distribution**: Starting with `v1.0.0` (Production/Stable), standalone combined tarballs `zycode-linux-x86_64-1.0.0.tar.gz` and `zycode-linux-aarch64-1.0.0.tar.gz` are published on GitHub Releases. Each archive extracts both `zypi` and `zycode-agent` to the installation prefix root. +- **Zero-runtime dependency**: When installed via mise's `http:` backend, `zypi` automatically discovers the sibling `zycode-agent` binary directly beside it, requiring no global Python runtime or system pip dependencies. +- **First-run setup**: `zypi --setup` provides an interactive terminal configuration wizard to choose a model provider and configure API keys. + +Adding `zycode` to Omarchy gives users immediate, native access to zycode from Omarchy's Agent menu with automatic mise package installation, headless bypass (`--always-approve`), and shared AGENTS instructions. + +--- + +## 2. Upstream PR Proposal + +### PR Title +`feat(agent): add zycode (zypi) coding agent to Agent menu` + +### PR Description +```markdown +### Overview +Adds `zycode` (`zypi`) to Omarchy's default coding agent menu and launcher. + +`zycode` is a fast terminal coding agent featuring an ACP-driven Rust TUI (`zypi`) and standalone agent runtime (`zycode-agent`). Starting with `v1.0.0`, zycode publishes self-contained binary release archives containing both binaries for Linux x86_64 and aarch64. + +### Changes +- **`etc/mise/conf.d/omarchy-tools.toml`**: Declares `http:zycode` with `lazy = true`, `auto_update = "4h"`, `lazy_bins = ["zypi"]`, GitHub release URLs for x86_64 and aarch64 (`zycode-linux--{{version}}.tar.gz`), and version resolution via GitHub Releases API (`.[].tag_name`). +- **`bin/omarchy-default-agent`**: Registers `zycode` / `zypi` with the `http:zycode` declaration; updates usage text and arg metadata. +- **`bin/omarchy-agent`**: Adds launcher entry running `zypi --always-approve [-- "$prompt"]`. +- **`bin/omarchy-agent-instructions`**: Links agent instructions to `${PI_HOME:-$HOME/.pi-python}/agent/AGENTS.md`. +- **`default/omarchy/omarchy-menu.jsonc`**: Adds `agent.harness.zycode` entry with agent icon `󰚩`. +- **`default/i18n/en/menu.json`**: Adds English i18n label for `agent.harness.zycode`. +- **`test/shell.d/default-agent-test.sh`**: Updates expected tool declarations, lazy counts (31 -> 32), self-updating CLI counts (21 -> 22), install expectations, prompt launch, and permission bypass assertions. + +### Verification +- `bash test/shell.d/default-agent-test.sh`: 47 tests passed (0 failures). +- `bash test/shell.d/i18n-test.sh`: 123 tests passed (0 failures). +``` + +--- + +## 3. Mise Backend Configuration (`http:zycode`) + +Mise manages standalone binary packages via HTTP tarballs. The archive layout for `zycode` is flat: +```text +zycode-linux-x86_64-1.0.0.tar.gz +├── zypi (0755) +└── zycode-agent (0755) +``` + +In `etc/mise/conf.d/omarchy-tools.toml`: +```toml +"http:zycode" = { version = "latest", lazy = true, auto_update = "4h", lazy_bins = ["zypi"], minimum_release_age = "0s", platforms_linux_x64_url = "https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-x86_64-{{version}}.tar.gz", platforms_linux_arm64_url = "https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-aarch64-{{version}}.tar.gz", version_list_url = "https://api.github.com/repos/zy1233/pi-python/releases", version_json_path = ".[].tag_name" } +``` + +Key configuration points: +- `lazy = true`: Generates a lazy shim wrapper under `~/.local/share/omarchy/bin/zypi` so invoking `zypi` or launching from the menu triggers installation on first run. +- `lazy_bins = ["zypi"]`: Only `zypi` is exposed on `PATH`. `zycode-agent` remains adjacent in the mise install directory and is invoked as a child process by `zypi` via sibling binary resolution. +- `auto_update = "4h"`: Updates check every 4 hours alongside other self-updating agent CLIs. +- `version_list_url` and `version_json_path`: Queries `https://api.github.com/repos/zy1233/pi-python/releases` extracting `.tag_name`. Mise automatically strips `v` prefixes to match semver versions. + +--- + +## 4. Full Git Diff Patch against `omacom/omarchy` (`quattro`) + +```patch +diff --git a/bin/omarchy-agent b/bin/omarchy-agent +index 529ef0dc7..5b587ede4 100755 +--- a/bin/omarchy-agent ++++ b/bin/omarchy-agent +@@ -270,6 +270,10 @@ commandcode) + command=(commandcode --yolo) + [[ -n ${prompt:-} ]] && command+=(-- "$prompt") + ;; ++zycode) ++ command=(zypi --always-approve) ++ [[ -n ${prompt:-} ]] && command+=(-- "$prompt") ++ ;; + *) + echo "Unsupported default agent: $agent" >&2 + exit 1 +diff --git a/bin/omarchy-agent-instructions b/bin/omarchy-agent-instructions +index 21f769d01..19353069c 100755 +--- a/bin/omarchy-agent-instructions ++++ b/bin/omarchy-agent-instructions +@@ -51,6 +51,7 @@ declare -A links=( + [kilo]="$config/kilo/AGENTS.md" + [commandcode]="$HOME/.commandcode/AGENTS.md" + [freebuff]="$HOME/.AGENTS.md" ++ [zycode]="${PI_HOME:-$HOME/.pi-python}/agent/AGENTS.md" + ) + + backups=() +diff --git a/bin/omarchy-default-agent b/bin/omarchy-default-agent +index cee381040..ffadd59cb 100755 +--- a/bin/omarchy-default-agent ++++ b/bin/omarchy-default-agent +@@ -1,7 +1,7 @@ + #!/bin/bash + + # omarchy:summary=Set and launch the default coding agent +-# omarchy:args=[pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush|cursor-agent|muse|kimi|qwen|dsh|mcode|kiro-cli|freebuff|kilo|devin|amp|commandcode] ++# omarchy:args=[pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush|cursor-agent|muse|kimi|qwen|dsh|mcode|kiro-cli|freebuff|kilo|devin|amp|commandcode|zycode] + # omarchy:examples=omarchy default agent | omarchy default agent codex | omarchy default agent claude + + installing=false +@@ -64,8 +64,14 @@ devin | devin-cli) + ;; + amp | ampcode) agent="amp"; name="Amp" ;; + commandcode | command-code | cmdc) agent="commandcode"; name="Command Code"; agent_package="npm:command-code" ;; ++zycode | zypi) ++ agent="zycode"; name="zycode" ++ # zycode publishes per-platform archives containing zypi and zycode-agent. ++ agent_tool="http:zycode" ++ agent_package="$agent_tool[platforms_linux_x64_url=https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-x86_64-{{version}}.tar.gz,platforms_linux_arm64_url=https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-aarch64-{{version}}.tar.gz,version_list_url=https://api.github.com/repos/zy1233/pi-python/releases,version_json_path=.[].tag_name]" ++ ;; + *) +- echo "Usage: omarchy-default-agent " ++ echo "Usage: omarchy-default-agent " + exit 1 + ;; + esac +diff --git a/default/i18n/en/menu.json b/default/i18n/en/menu.json +index 1103b8f18..00942351e 100644 +--- a/default/i18n/en/menu.json ++++ b/default/i18n/en/menu.json +@@ -571,6 +571,9 @@ + "agent.harness.qwen": { + "label": "Qwen Code" + }, ++ "agent.harness.zycode": { ++ "label": "zycode" + }, + "setup.default.browser": { + "label": "Browser", + "title": "Default Browser" +diff --git a/default/omarchy/omarchy-menu.jsonc b/default/omarchy/omarchy-menu.jsonc +index 741e01377..08d80803a 100644 +--- a/default/omarchy/omarchy-menu.jsonc ++++ b/default/omarchy/omarchy-menu.jsonc +@@ -63,6 +63,7 @@ + "agent.harness.ori": {"icon":"","iconFont":"omarchy","label":"Ori","checked":"[[ \"$(omarchy-default-agent)\" == \"ori\" ]]","action":"omarchy-default-agent ori"}, + "agent.harness.pi": {"icon":"","iconFont":"omarchy","label":"Pi","checked":"[[ \"$(omarchy-default-agent)\" == \"pi\" ]]","action":"omarchy-default-agent pi"}, + "agent.harness.qwen": {"icon":"","iconFont":"omarchy","label":"Qwen Code","checked":"[[ \"$(omarchy-default-agent)\" == \"qwen\" ]]","action":"omarchy-default-agent qwen"}, ++ "agent.harness.zycode": {"icon":"󰚩","label":"zycode","checked":"[[ \"$(omarchy-default-agent)\" == \"zycode\" ]]","action":"omarchy-default-agent zycode"}, + "agent.instructions": {"icon":"󰈙","label":"Instructions","action":"omarchy-agent-instructions --edit"}, + + // System +diff --git a/etc/mise/conf.d/omarchy-tools.toml b/etc/mise/conf.d/omarchy-tools.toml +index b784d7198..06ebd5b89 100644 +--- a/etc/mise/conf.d/omarchy-tools.toml ++++ b/etc/mise/conf.d/omarchy-tools.toml +@@ -23,6 +23,7 @@ grok = { version = "latest", lazy = true, auto_update = "4h", minimum_release_ag + hey-cli = { version = "latest", lazy = true, minimum_release_age = "0s" } + "http:devin" = { version = "latest", lazy = true, auto_update = "4h", lazy_bins = ["devin"], minimum_release_age = "0s", platforms_linux_x64_url = "https://static.devin.ai/cli/{{ version }}/devin-{{ version }}-x86_64-unknown-linux.tar.gz", platforms_linux_arm64_url = "https://static.devin.ai/cli/{{ version }}/devin-{{ version }}-aarch64-unknown-linux.tar.gz", bin_path = "bin", version_list_url = "https://static.devin.ai/cli/current/manifest.json", version_json_path = ".version" } + "http:kiro-cli" = { version = "latest", lazy = true, auto_update = "4h", lazy_bins = ["kiro-cli"], minimum_release_age = "0s", platforms_linux_x64_url = "https://prod.download.cli.kiro.dev/stable/{{version}}/kirocli-x86_64-linux.tar.gz", platforms_linux_arm64_url = "https://prod.download.cli.kiro.dev/stable/{{version}}/kirocli-aarch64-linux.tar.gz", version_list_url = "https://prod.download.cli.kiro.dev/stable/latest/manifest.json", version_json_path = ".version" } ++"http:zycode" = { version = "latest", lazy = true, auto_update = "4h", lazy_bins = ["zypi"], minimum_release_age = "0s", platforms_linux_x64_url = "https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-x86_64-{{version}}.tar.gz", platforms_linux_arm64_url = "https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-aarch64-{{version}}.tar.gz", version_list_url = "https://api.github.com/repos/zy1233/pi-python/releases", version_json_path = ".[].tag_name" } + hunk = { version = "latest", lazy = true, minimum_release_age = "0s" } + muse = { version = "latest", lazy = true, auto_update = "4h", minimum_release_age = "0s" } + node = { version = "latest", lazy = true, minimum_release_age = "0s" } +diff --git a/test/shell.d/default-agent-test.sh b/test/shell.d/default-agent-test.sh +index 57b877f82..c94efc330 100644 +--- a/test/shell.d/default-agent-test.sh ++++ b/test/shell.d/default-agent-test.sh +@@ -168,6 +168,8 @@ amp_package="amp" + commandcode_package="npm:command-code" + cursor_agent_package="cursor-agent" + muse_package="muse" ++zycode_tool="http:zycode" ++zycode_package="$zycode_tool[platforms_linux_x64_url=https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-x86_64-{{version}}.tar.gz,platforms_linux_arm64_url=https://github.com/zy1233/pi-python/releases/download/v{{version}}/zycode-linux-aarch64-{{version}}.tar.gz,version_list_url=https://api.github.com/repos/zy1233/pi-python/releases,version_json_path=.[].tag_name]" + + assert_lazy_stub() { + local package=$1 +@@ -229,6 +231,7 @@ declare -A declared_option_bins=( + [mcode]='"mcode"' + [kiro_cli]='"kiro-cli"' + [devin]='"devin"' ++ [zycode]='"zypi"' + ) + for agent in "${!declared_option_bins[@]}"; do + tool_var="${agent}_tool" +@@ -242,12 +245,12 @@ for agent in "${!declared_option_bins[@]}"; do + fail "user setup declares ${!tool_var} with ${option%%=*} inside its table" + done + done +-[[ $(grep -c 'auto_update = "4h"' "$lazy_config") == 21 ]] || fail "only the agent CLIs update themselves" ++[[ $(grep -c 'auto_update = "4h"' "$lazy_config") == 22 ]] || fail "only the agent CLIs update themselves" + for tool in node uv; do + grep -Eq "^$tool = \\{ version = \"latest\", lazy = true, minimum_release_age = \"0s\" \\}$" "$lazy_config" || + fail "user setup declares $tool as a native lazy tool" + done +-[[ $(grep -c 'lazy = true' "$lazy_config") == 31 ]] || fail "user setup declares every default mise tool as lazy" ++[[ $(grep -c 'lazy = true' "$lazy_config") == 32 ]] || fail "user setup declares every default mise tool as lazy" + grep -Fx "reshim --system" "$mise_history" >/dev/null || fail "user setup builds the system lazy bootstrap shims" + pass "user setup configures system lazy tools from registry shorthands" + : >"$stub_log" +@@ -424,6 +427,8 @@ declare -A expected_agents=( + [muse]="muse" + [muse-code]="muse" + [musecode]="muse" ++ [zycode]="zycode" ++ [zypi]="zycode" + ) + + declare -A expected_packages=( +@@ -449,6 +454,7 @@ declare -A expected_packages=( + [commandcode]="$commandcode_package" + [cursor-agent]="$cursor_agent_package" + [muse]="$muse_package" ++ [zycode]="$zycode_package" + ) + + for selection in "${!expected_agents[@]}"; do +@@ -707,7 +713,7 @@ mapfile -d '' -t agent_open_args <"$agent_open_log" + pass "Muse installs visibly through mise and opens directly" + + saved_agent=$(<"$agent_file") +-for agent in qwen dsh mcode kiro-cli freebuff kilo devin amp commandcode; do ++for agent in qwen dsh mcode kiro-cli freebuff kilo devin amp commandcode zycode; do + tool_var="${agent//-/_}_tool" + package_var="${agent//-/_}_package" + declared_tool=${!tool_var:-${!package_var}} +@@ -715,7 +721,7 @@ for agent in qwen dsh mcode kiro-cli freebuff kilo devin amp commandcode; do + omarchy-default-agent --install "$agent" >/dev/null + # npm-backed agents bring node along, which a fresh machine doesn't have yet. + case "$agent" in +- kiro-cli | devin) expected_install="install $declared_tool" ;; ++ kiro-cli | devin | zycode) expected_install="install $declared_tool" ;; + *) expected_install="install node $declared_tool" ;; + esac + grep -Fx "$expected_install" "$mise_history" >/dev/null || fail "visible $agent installation installs Omarchy's declaration (expected: $expected_install)" +@@ -842,6 +848,7 @@ assert_launch kilo kilo --auto "--prompt=Review this project" + assert_launch devin devin --permission-mode dangerous --respect-workspace-trust false -- "Review this project" + assert_launch amp bash -c 'printf "%s\n" "$1" | exec "$0" --dangerously-allow-all' amp "Review this project" + assert_launch commandcode commandcode --yolo -- "Review this project" ++assert_launch zycode zypi --always-approve -- "Review this project" + [[ $(<"$clipboard_log") == "Review this project" ]] || fail "Freebuff launcher puts the prompt on the clipboard" + mapfile -d '' -t notification_args <"$notification_history" + [[ ${notification_args[*]} == *"Freebuff takes no starting prompt"* ]] || fail "Freebuff launcher says where the prompt went" +@@ -885,6 +892,7 @@ assert_bypass kilo kilo --auto + assert_bypass devin devin --permission-mode dangerous --respect-workspace-trust false + assert_bypass amp amp --dangerously-allow-all + assert_bypass commandcode commandcode --yolo ++assert_bypass zycode zypi --always-approve + [[ ! -s $clipboard_log && ! -s $notification_history ]] || fail "Freebuff launcher leaves the clipboard alone without a prompt" + pass "agent launcher skips permission prompts for every supported agent" +``` + +--- + +## 5. Test Evidence + +### A. Omarchy Agent Test (`test/shell.d/default-agent-test.sh`) +```bash +$ bash test/shell.d/default-agent-test.sh +ok - custom agent lazy stubs preserve their mise packages +ok - user setup configures system lazy tools from registry shorthands +ok - user setup leaves ordinary lazy wrappers to mise +ok - Remove Preinstalls deletes every optional agent lazy stub +ok - Remove Preinstalls keeps an official Cursor CLI install +ok - Remove Preinstalls keeps a user-managed Muse install +ok - default agent is unset until one is chosen +ok - agent launcher refuses to launch without a default +ok - agent launcher opens a local model without a default +ok - agent launcher opens Qwen Code on a local model, keeping its key off the command line +ok - --pick opens the agent defaults menu when none is set +ok - terminal alias launches the default agent inline +ok - agent launcher has a keyboard shortcut +ok - default agent selects and opens every supported provider and alias +ok - default agent stores its selection in Omarchy user config +ok - extension installation failure silently continues selecting and launching Claude +ok - missing agents install visibly and open in the same terminal +ok - an agent installed from the Quake console opens tiled in the console +ok - an install from a terminal sharing one process across windows finds its own window +ok - installed agents select and open without notifications +ok - selecting an official Cursor CLI install skips mise +ok - a dead file at the wrapper's path does not pass for an install +ok - default agent rejects unsupported providers without changing the selection +ok - default agent opens only after mise installs the provider +ok - default agent reports mise failures without notifications +ok - failed Muse mise installation preserves the selection and skips login +ok - Muse installs visibly through mise and opens directly +ok - the added agents install through Omarchy's mise declarations +ok - installed Muse selects and opens directly +ok - default agent reports Muse mise failures without changing the selection +ok - selecting a user-installed Muse preserves its launcher +ok - agent launcher adapts initial prompts for every supported agent +ok - Muse receives option-like prompts as one literal argument +ok - Hermes receives prompted launches as one literal query argument +ok - agent launcher skips permission prompts for every supported agent +ok - agent launcher starts the selected agent without an initial prompt +ok - inline agent launcher runs in the current terminal +ok - --pick launches once an agent is chosen +ok - --prefer-local opens the running local model, and the usual agent otherwise +ok - omarchy agent keeps prompts on the prompt route +ok - agent launcher reports a missing default command +ok - choosing OpenClaw uses its runtime and launches its terminal UI +ok - a missing OpenClaw routes through the install terminal +ok - installing OpenClaw as default agent sets up its runtime +ok - OpenClaw receives prompts through --message +ok - OpenClaw's agent hands a missing command to its launcher only when the package is there +ok - agent launcher runs user-installed agents ahead of native lazy shims +# 47/47 tests passed (0 failures) +``` + +### B. Omarchy Menu & i18n Test (`test/shell.d/i18n-test.sh`) +```bash +$ bash test/shell.d/i18n-test.sh +# 123/123 tests passed (0 failures) +``` +- Validated that `agent.harness.zycode` in `default/omarchy/omarchy-menu.jsonc` matches the catalog entry in `default/i18n/en/menu.json`. +- Validated that no duplicate or orphan keys exist in menu configurations. diff --git a/packages/pi-agent-cli/AGENTS.md b/packages/pi-agent-cli/AGENTS.md index 66f3c873..42fe227b 100644 --- a/packages/pi-agent-cli/AGENTS.md +++ b/packages/pi-agent-cli/AGENTS.md @@ -112,11 +112,18 @@ The question to the user holds the reason as one fixed sentence (`auto_reasons.s ## TUI spawn -The Rust TUI (`zypi`) spawns the Python agent via (priority order): +The Rust TUI (`zypi`) spawns the ACP agent via (priority order): 1. `PI_AGENT_COMMAND` env var 2. `[agent].command` in `agent.toml`, then in `config.toml` -3. `PI_PYTHON` env var (appends `-m pi_agent_cli`) +3. `PI_PYTHON` env var: ONLY when `PI_PYTHON` is explicitly set in the environment and non-empty (appends `["-m", "pi_agent_cli"]`) +4. Default (when none of the above is set): `zycode-agent` (`zycode-agent.exe` on Windows) with empty args: + - Sibling binary next to the current `zypi` executable + - Sibling binary next to the canonicalized target (following symlinks, e.g. for `~/.local/bin/zypi` symlinks) + - Fall back to searching `PATH` for `zycode-agent` + - Notice: `zypi` does NOT fall back to bare `python` or `python3` when `PI_PYTHON` is unset. + +`zypi --setup` runs the setup command (`--setup`) directly on the resolved agent program, allowing users to configure their provider, model, and API key immediately in the terminal. **The agent's stderr.** The TUI owns the screen, and its own fd 2 is `/dev/null` (`pi_tty_utils::redirect_native_stderr`), so the agent's stderr goes to `/logs/agent.stderr.log` instead (`acp/spawn.rs`, `agent_stderr`): appended across runs, one `--- agent started