Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ AgentMessage[] → transform_context() → convert_to_llm() → LangChain BaseMe
| `packages/pi-mcp/` | Optional extension `pi-mcp-py` (entry point `pi-mcp`): connects the MCP servers (stdio, http, sse) that an ACP client passes in `session/new`, one runner task per server, tools named `mcp__<server>__<tool>`, `/mcp` command. Core, harness and CLI have no MCP client; they hand the servers over as data (`ClientMcpServer`, `ExtensionAPI.client_mcp_servers`). Design: `docs/specs/2026-10-23-mcp-extension-design.md`. Its tests are left out of a run that did not install the package (the header says so) | — |
| `packaging/agent/` | Builds the agent as a one-file executable (PyInstaller; `build.py`, `zycode-agent.spec`, `entry.py`) and the smoke test over ACP with a fake model server (`smoke.py`). `.github/workflows/agent-binaries.yml` runs both on five platforms and attaches the archives to the GitHub Release after the `Release` workflow. A frozen build has no interpreter: `host.py` starts a frozen `child.py`, and only the OpenAI-format provider is in it. Design and the registry entry draft: `docs/specs/2026-10-31-agent-binaries.md` | — |
| `packages/pi-agent-cli/` | Standard-ACP CLI (`python -m pi_agent_cli`); config `agent.example.toml`, home `~/.pi-python`; TUI binary `zypi` under `tui/`. See [`packages/pi-agent-cli/AGENTS.md`](packages/pi-agent-cli/AGENTS.md) for spawn, config, first run (`--setup` and the terminal login that `initialize` offers to a client that can run one; `zypi` still gets `authMethods: []`), prompt pipeline, and the three permission modes `ask`, `auto` and `always-approve` (Auto: rules, and a model step for a `bash` call that no rule decides: `auto_rules.py`, `auto_classifier.py`, `auto_mode.py`, `permission_modes.py`; design `docs/specs/2026-11-02-auto-mode-design.md`; the pager offers all three, and a clean start is `ask`). The items on the ACP wire beyond standard ACP (`pi/session/delete`, `_meta.sessionId`, and others) are in the register `docs/specs/2026-11-05-acp-extension-registry.md` | — |
| `vscode/` | The VS Code extension `zycode.zycode` (TypeScript, `src/core/` has no `vscode` import). It is an ACP client and a chat view for zycode in VS Code: it starts the agent as a child process, shows permission questions and a diff for `write`/`edit`, runs the first-run setup in a terminal (a walkthrough, a banner and hints guide the first start; the agent's own `--setup` and `auth_required` carry it, no wire item and no agent change), lists past chats of the folder in a view (`session/list`, `session/load`, `pi/session/delete`), and offers the three permission modes `ask`, `auto` and `always-approve` in the chat menu (`always-approve` only after a modal warning, never restored for a new chat, a past chat or a restart, and not in an untrusted workspace; the `zycode.permissionMode` setting stays `ask`/`auto`; it moves the agent with the agent's own `pi/yolo_mode_changed`). The extension never writes `always-approve` through `set_config_option`. A Thinking menu shows `thinking_level` of `agent.toml`; agent 0.9.1 cannot change it live, so a change edits that one line (checked by parsing, after a modal), restarts the agent and reopens the chat (design section 7c). The menu has `max` only for an agent of `MAX_LEVEL_SINCE` (`src/core/thinking.ts`, 1.0.0) or later, because an older agent reads `max` as `off` and says nothing; check that number when the pin moves (`vscode/PACKAGING.md`). One VSIX per platform, each with the bundled `zycode-agent` binary of one Release (pin and sha256 in `agent-assets.json`). Not a Python package: pytest does not read it, and ruff reads only its three Python helpers (`scripts/python_licenses.py`, `test/support/fake_model.py`, `test/support/pty_answers.py`). `.github/workflows/vscode-extension.yml` runs `npm run check` and a `linux-x64` VSIX smoke test for a PR that changes it. `ci.yml` (Ruff, pytest) skips a PR that touches only `vscode/`, `docs/` and that workflow, with no `.py` file (a `paths` filter with `!` patterns; no check is required on `main`, so a skipped run blocks no merge). The same workflow publishes (Trusted Publishing, by hand on `main`, environment `vscode-publish`). 1.0.0 was the first stable release (the pre-release 0.1.0 was uploaded by hand; the 1.0.0 run, run `43181052994` on 2026-11-12, was the first real OIDC publish and worked on the first try on Open VSX and the Marketplace, five targets, no token; the record is in `vscode/RELEASING.md`; the owner tested the install of 1.0.0 and the update from 0.1.0 on Windows (2026-11-12), and the rest of the Windows flow, macOS and Linux in a real VS Code are not verified; stable = even minor, pre-release = odd minor). Do not rename that file or the environment: the registries name them. Local check: `cd vscode; npm run check`. Design: `docs/specs/2026-11-04-vscode-extension-design.md`; make and test a VSIX: `vscode/PACKAGING.md`; releases: `vscode/RELEASING.md` | — |
| `vscode/` | The VS Code extension `zycode.zycode` (TypeScript, `src/core/` has no `vscode` import). It is an ACP client and a chat view for zycode in VS Code: it starts the agent as a child process, shows permission questions and a diff for `write`/`edit`, runs the first-run setup in a terminal (a walkthrough, a banner and hints guide the first start; the agent's own `--setup` and `auth_required` carry it, no wire item and no agent change), lists past chats of the folder in a view (`session/list`, `session/load`, `pi/session/delete`), and offers the three permission modes `ask`, `auto` and `always-approve` in the chat menu (`always-approve` only after a modal warning, never restored for a new chat, a past chat or a restart, and not in an untrusted workspace; the `zycode.permissionMode` setting stays `ask`/`auto`; it moves the agent with the agent's own `pi/yolo_mode_changed`). The extension never writes `always-approve` through `set_config_option`. A Thinking menu shows `thinking_level` of `agent.toml`; agents 0.9.1 and 1.0.0 cannot change it live, so a change edits that one line (checked by parsing, after a modal), restarts the agent and reopens the chat (design section 7c). The menu has `max` only for an agent of `MAX_LEVEL_SINCE` (`src/core/thinking.ts`, 1.0.0) or later, because an older agent reads `max` as `off` and says nothing; check that number when the pin moves (`vscode/PACKAGING.md`). One VSIX per platform, each with the bundled `zycode-agent` binary of one Release (pin and sha256 in `agent-assets.json`; 1.4.0 is the first extension that bundles agent 1.0.0, so its menu has `max` and its Context row shows for a model that has `context_window`). Not a Python package: pytest does not read it, and ruff reads only its three Python helpers (`scripts/python_licenses.py`, `test/support/fake_model.py`, `test/support/pty_answers.py`). `.github/workflows/vscode-extension.yml` runs `npm run check` and a `linux-x64` VSIX smoke test for a PR that changes it. `ci.yml` (Ruff, pytest) skips a PR that touches only `vscode/`, `docs/` and that workflow, with no `.py` file (a `paths` filter with `!` patterns; no check is required on `main`, so a skipped run blocks no merge). The same workflow publishes (Trusted Publishing, by hand on `main`, environment `vscode-publish`). 1.0.0 was the first stable release (the pre-release 0.1.0 was uploaded by hand; the 1.0.0 run, run `43181052994` on 2026-11-12, was the first real OIDC publish and worked on the first try on Open VSX and the Marketplace, five targets, no token; the record is in `vscode/RELEASING.md`; the owner tested the install of 1.0.0 and the update from 0.1.0 on Windows (2026-11-12), and the rest of the Windows flow, macOS and Linux in a real VS Code are not verified; stable = even minor, pre-release = odd minor). Do not rename that file or the environment: the registries name them. Local check: `cd vscode; npm run check`. Design: `docs/specs/2026-11-04-vscode-extension-design.md`; make and test a VSIX: `vscode/PACKAGING.md`; releases: `vscode/RELEASING.md` | — |
| `web/` | Product site for zycode, live at `https://zycode.dev` (static Astro, Node ≥ 22.23.4; English at `/`, Chinese at `/zh/`; Cloudflare Workers static assets, no server of ours). Not a Python package: ruff and pytest do not read it; `.github/workflows/web-ci.yml` runs `npm run check` and `npm run build` for a PR that changes `web/`. A merge to `main` that changes `web/` deploys to `zycode.dev` by itself (Cloudflare Workers Builds, not GitHub Actions). Its claims must stay equal to the README table "Status" and to the benchmark report, and `en.ts` / `zh.ts` keep the same keys. See [`web/README.md`](web/README.md) for commands, deploy, the domain, and the Cloudflare settings that are not in the repository | — |

### Invariants
Expand Down
7 changes: 4 additions & 3 deletions docs/specs/2026-11-04-vscode-extension-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@
- **Two kinds of trust.** VS Code Workspace Trust decides if the extension starts at all. The agent's own project trust decides if the project may load its extensions. The text of the two prompts says so.
- **Publishing.** Open VSX first, then the Marketplace. The first upload to each (0.1.0, a pre-release) was a hand upload of a VSIX that the packaging script made. The publish workflow (`.github/workflows/vscode-extension.yml`, section 11) runs from `main` by `workflow_dispatch`, with Trusted Publishing and the environment `vscode-publish`; it publishes the stable releases, 1.0.0 first.
- **Added in 1.0.0.** A first-run guide, `always-approve` in the mode menu (with a warning, never restored), a Past chats view (list, open, delete), and a Thinking menu. All four use what the bundled agent already has (0.1.0 bundled 0.9.0; 1.0.0 bundles **0.9.1**): no wire item and no agent change. The Thinking menu edits one line of `agent.toml` and restarts the agent, because 0.9.0 has no live setting (section 7c).
- **Added after 1.0.0.** Markdown in the chat (section 2, rule 5, and D34), and a richer status row (section 7d): the context window and the cost when the agent sends the standard `usage_update`, the time of the turn, and the folder. Agent 0.9.1 sends no `usage_update`, so the Context row does not show with the bundled agent. The agent change that sends it was built on 2026-11-16 (`docs/specs/2026-11-13-agent-context-usage.md`); it is not released, so the row shows after the next agent release and a new pin.
- **Added after 1.0.0.** Markdown in the chat (section 2, rule 5, and D34), and a richer status row (section 7d): the context window and the cost when the agent sends the standard `usage_update`, the time of the turn, and the folder. Agent 0.9.1 sent no `usage_update`, so the Context row did not show with the agent that 1.0.0 and 1.2.0 bundle. The agent change that sends it was built on 2026-11-16 (`docs/specs/2026-11-13-agent-context-usage.md`) and released in agent 1.0.0. Extension 1.4.0 bundles that agent, so the row shows for a model that has `context_window`.
- **Added in 1.4.0.** The pin moves from agent 0.9.1 to agent 1.0.0. The Thinking menu offers the level `max` to an agent of 1.0.0 or later (section 7c), and the Context row shows with the bundled agent (section 7d). The agent still has no live thinking setting: `set_config_option` of 1.0.0 takes only `model` and `mode` (read in `pi_agent_cli/agent.py`), so the menu still edits `agent.toml` and restarts the agent.
- **Not yet.** Model choice, images, `@file`, MCP servers, fallback package, and everything of report section 3.3 from Phase 2 on (section 12).

## 1. Facts the design rests on
Expand Down Expand Up @@ -352,7 +353,7 @@ Nothing else is needed, so there is **no wire item to add and no agent change**.
| Time of the turn | the clock of the host, from `send` to the end of the turn | in the header after the state: `Working · 1 min 12 s`, then `Ready · last turn 8.4 s` until the next turn; a line of the tooltip | While a turn runs, and after it. |
| Folder | `cwd` of the session | in the line of the agent and the model: `folder pi-python` (the full path is its tooltip); a line of the tooltip of the status bar item | When the chat has a folder. |

**Agent 0.9.1 sends no `usage_update`, so the Context row does not show with the bundled agent.** What was found is in `docs/specs/2026-11-13-agent-context-usage.md`. The agent change that sends `usage_update` (for a model that has `context_window` in `agent.toml`) was built later, on 2026-11-16. It is not released, and no pin was moved.
**Agent 0.9.1 sent no `usage_update`, so the Context row did not show with the agent that extensions 1.0.0 and 1.2.0 bundle.** What was found is in `docs/specs/2026-11-13-agent-context-usage.md`. The agent change that sends `usage_update` (for a model that has `context_window` in `agent.toml`) was built later, on 2026-11-16, and released in agent 1.0.0. Extension 1.4.0 moves the pin to that agent, so the row shows for a model that has `context_window`. The agent sends no cost, so the Cost line does not show. The extension was not run against agent 1.0.0 in a real VS Code window with a real model.

**Design notes.**

Expand Down Expand Up @@ -536,7 +537,7 @@ From the report, section 3.3 (Phase 2 and later), and from the limits above:

## 14. Decisions

**Status of D15 to D33:** the user adopted all of them as recommended (2026-11-12, 14:49 Asia/Shanghai: "都按你的建议", one answer for every decision). Each row marked (adopted) is built as the row says. The bundled agent of 1.0.0 is **0.9.1** (`agent-assets.json`, pinned with size and sha256).
**Status of D15 to D33:** the user adopted all of them as recommended (2026-11-12, 14:49 Asia/Shanghai: "都按你的建议", one answer for every decision). Each row marked (adopted) is built as the row says. The bundled agent of extension 1.0.0 is **0.9.1** (`agent-assets.json`, pinned with size and sha256). Extension 1.4.0 bundles agent 1.0.0.

**Status of D34 and D35:** both are newer (2026-11-12, after 1.0.0). D34 is the answer of the user to a question with three options: the user chose option A. D35 is a part of the work for D34. The user was not asked about D35.

Expand Down
8 changes: 4 additions & 4 deletions docs/specs/2026-11-13-agent-context-usage.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Context use and cost from the agent: investigation record

> Date: 2026-11-13 (investigation); 2026-11-16 (built).
> Status: **built (Plan A), not released.** Sections 1 to 3 are the investigation of 2026-11-13. They describe agent 0.9.1, and they are not changed. Section 4 says what the agent does now.
> Status: **built (Plan A) and released in agent 1.0.0 (2026-11-16); the extension bundles that agent from 1.4.0.** Sections 1 to 3 are the investigation of 2026-11-13. They describe agent 0.9.1, and they are not changed. Section 4 says what the agent does now.
> Reason: the user asked for the context use in the status row of the VS Code extension. On 2026-11-13 the user said: if the agent must change, write down the result of the investigation, and do not make the change. On 2026-11-16 the user asked for the change, with Plan A (option A of section 4, item 1, in the first version of this record).
> Related: `docs/specs/2026-11-04-vscode-extension-design.md` section 7d (the extension side, which is built); `docs/specs/2026-11-05-acp-extension-registry.md` section 5; the entry of 2026-10-13 in `docs/PLAN/archive/PLAN-RUST-AGENT-RUNTIME-REMOVAL-EXECUTION-LOG.md` (the pager had the same question).

Expand Down Expand Up @@ -65,11 +65,11 @@ The change follows the proposal of the first version of this record. The differe

An agent change is not enough. The extension bundles one fixed agent binary. After the change: release the agent, then change `zycodeAgentVersion` and the size and the sha256 in `vscode/agent-assets.json`, then release the extension. A user who sets `zycode.agentPath` gets the change as soon as that program is new.

At the extension release, change the sentences that say that the bundled agent sends no `usage_update`: `vscode/README.md` (the Context row), `vscode/CHANGELOG.md` and design section 7d. They are true for agent 0.9.1 only.
At the extension release, change the sentences that say that the bundled agent sends no `usage_update`: `vscode/README.md` (the Context row), `vscode/CHANGELOG.md` and design section 7d. They are true for agent 0.9.1 only. **Done** in extension 1.4.0 (2026-11-16): the pin moved to agent 1.0.0 and these three places say that the Context row shows for a model that has `context_window`.

## 7. Decisions

1. Change the agent? **Yes** (the user, 2026-11-16). It is built, and it is not released.
1. Change the agent? **Yes** (the user, 2026-11-16). It is built, and it is released in agent 1.0.0.
2. The source of the window size: **A** (section 4, item 1).
3. Compaction by the real window, in the same change? **Yes.** It follows from setting `Model.context_window`. It has its own test, and a guard for small windows (section 4, item 5).
4. Teach the pager to read `usage_update`? **Open.** Not decided, not built.
Expand All @@ -82,4 +82,4 @@ It does what needs no agent change (design section 7d):
- It measures the time of the turn with its own clock.
- It shows the folder of the chat.

With agent 0.9.1, which the extension bundles now, the Context row does not show. With an agent that has the change in section 4, it shows for a model that has a `context_window`. The extension reads the message in tests with a fake agent. Its chat controller ran once against the changed agent (section 4, item 7). The extension has not been run against the changed agent in a real VS Code.
With agent 0.9.1, which extensions 1.0.0 and 1.2.0 bundle, the Context row does not show. With an agent that has the change in section 4 (agent 1.0.0, which extension 1.4.0 bundles), it shows for a model that has a `context_window`. The extension reads the message in tests with a fake agent. Its chat controller ran once against the changed agent (section 4, item 7). The extension has not been run against the changed agent in a real VS Code.
Loading
Loading