farming-code 2.2.6 → 2.2.8

package/README.md

@@ -9,279 +9,177 @@
 ![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)
 ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-555)
 
-Farming is a remote browser workspace for AI coding agents. The current public product line is **Farming 2**.
+Farming is a browser workspace for supervising AI coding agents on a development machine. It keeps several live agents, structured conversations, real terminals, project files, review, history, and runtime controls in one place—without moving the repository or agent processes into the browser.
 
-It brings remote terminal sessions, Codex / Claude Code, project-scoped agents, open editors, file search, lightweight editing, git review tools, usage signals, and machine status into one browser page. The goal is to reduce the context switching that usually happens between SSH, an IDE, browser tabs, monitoring pages, and separate agent panels.
+Run Farming beside the coding CLIs you already use, then return to the same work from a desktop or phone. Closing the browser does not stop the agents; the native PTY host can also preserve live terminal sessions while the Farming server restarts.
 
-Farming is designed around remote hosting. Agents, shells, project files, and git state keep running on the remote machine. A desktop browser is good for editing, reviewing, searching, and long follow-up sessions; a mobile browser is good for checking progress, switching sessions, and sending a short intervention while away from the desk.
+## Two Interfaces, One Runtime
 
-The browser exposes two live interfaces over the same backend: Farming Code at `/farming/code/` and the original CRT interface at `/farming/crt/`. `/farming/` continues to open Farming Code. If Code cannot start or render, the failure view keeps the live CRT interface visible behind the bounded error details, without restarting running agents.
+Farming 2 provides two complete browser interfaces over the same agents and sessions.
 
-For a product-oriented introduction, screenshots, and the architecture diagram, see the [Farming 2 Wiki](https://github.com/zhuwenzhuang/farming/wiki/English).
+### Farming Code
 
-![Farming Code workspace](./docs/products/code/assets/01-code-workspace.png)
+The default workbench for reading conversations, intervening in tasks, editing files, and reviewing an evolving change.
 
-> If you are an AI agent contributing to this repository, read [AGENTS.md](./AGENTS.md) first.
+![Farming Code structured Chat](./docs/products/code/assets/11-code-agent-process.png)
 
-## Why Farming Exists
+### Farming CRT
 
-Current AI-agent interfaces are often chat-session lists. They are not great at showing which long-running task matters now, which agent is waiting, which one is stale, and where a human should intervene.
+A keyboard-first control room for watching many agents, opening structured Chat or raw Terminal, searching history, and reading live usage telemetry.
 
-Farming first solves the practical workbench problem: put the tools needed to supervise coding agents into one remote UI. Longer term, it explores attention management through a Main Agent that can observe, coordinate, and summarize multiple child agents.
+![Farming CRT dashboard](./docs/products/crt/assets/01-crt-dashboard.png)
 
-## Farming 2
-
-Farming 2 turns the project into a remote coding workbench:
-
-- start and manage Codex, Claude, OpenCode, Qoder, bash, and zsh sessions in the browser;
-- discover and resume local Codex, Claude, OpenCode, and Qoder session history, then reconnect it to live Farming terminals;
-- group agents by project;
-- open Project Files with Open Editors, file tree, search, Monaco editing, Markdown/image preview, git changes, diff, and blame;
-- click terminal `path:line` references and HTTP URLs;
-- set Codex / Claude launch profiles for permissions, model, and speed where the underlying runtime supports them; App Server Codex updates permissions on its current thread, while terminal-owned sessions restart and resume when they already have a provider session id, or start fresh when no resumable id exists yet;
-- attach text and images to composer messages;
-- view lightweight usage, context, token-rate, quota, and CPU/MEM signals where available;
-- access the same remote service from desktop and mobile browsers.
-
-Screenshots, install details, and product notes are in [Farming 2 product guide](./docs/products/code/README.md).
-
-## Quick Start
-
-The easiest path is the npm package. Run Farming on the same development machine where `codex` or `claude` already works in a normal shell.
-
-```bash
-npm install --global farming-code
-farming daemon
-```
-
-Farming defaults to port `6694`, base path `/farming`, config directory `~/.farming`, and token auth. The first authenticated start generates a random readable token and stores it in `~/.farming/.session-token`; later restarts and upgrades reuse that token unless `FARMING_TOKEN` is explicitly set. In Chinese time zones this is a Chinese haiku-style passphrase by default; Japanese time zones use Japanese haiku-style passphrases, and other time zones use English passphrases. The startup log prints a URL like:
-
-```text
-http://linux-host:6694/farming?token=<startup-token>
-```
+| | Farming Code | Farming CRT |
+| --- | --- | --- |
+| Best for | Long follow-ups, files, editing, diffs, review | At-a-glance monitoring, keyboard control, terminal work, telemetry |
+| Live session | Structured Chat and real PTY Terminal | Phosphor Chat and real xterm Terminal |
+| Navigation | Project sidebar, Search, History, Files | Stable Agent bays and keyboard-driven consoles |
+| Appearance | Light and dark | CRT effects, terminal font size, optional Dynamic Heat |
+| Entry | `/farming/code/` or `/farming/` | `/farming/crt/` |
 
-Open that URL in a desktop or mobile browser, click `New Agent`, choose `Codex`, `Claude Code`, `bash`, or `zsh`, select a workspace, and start working.
+Switching interfaces does not restart or duplicate an Agent. If Farming Code cannot start or render, its bounded diagnostic view leaves the live CRT surface available rather than hiding the running sessions.
 
-## Downloads
+The complete current capability map and screenshot tour are in the [Farming 2 product overview](./docs/products/README.md). See the focused [Farming Code guide](./docs/products/code/README.md) and [Farming CRT guide](./docs/products/crt/README.md) for the full workflows.
 
-The npm package is the default distribution. GitHub release artifacts remain available for manual installation.
+## What You Can Do
 
-Farming uses these practical deployment shapes:
+- Group live agents by project, pin important work, rename sessions, track unread activity, and archive or resume work.
+- Use structured ACP Chat for Codex, Claude Code, OpenCode, and Qoder. Plans, reasoning, tools, permission requests, embedded terminals, child sessions, attachments, queued follow-ups, and exact change summaries remain available without overwhelming the final answer.
+- Open a real PTY Terminal when exact CLI behavior matters. Chat / Terminal changes the actual runtime and safely resumes the same provider session when its identity is available.
+- Change supported live Codex model, reasoning, Fast, Ultra, and permission settings. Terminal changes are applied to the running workflow before the next message rather than being limited to a future launch profile.
+- Browse Project Files, Open Editors, search with ripgrep, edit with Monaco, preview Markdown and images, follow `path:line` links, inspect git changes, diffs, and blame.
+- Review one evolving change across revisions, keep findings tied to the compared revision, mark files reviewed, and inspect meaningful deltas instead of treating every Agent turn as a separate review.
+- Search live Agents and the supported provider-session archive, then open, continue, restore, or resume the matching work.
+- Observe CPU/MEM, token-rate, context, quota, provider usage, and CRT daily/live token telemetry when the provider exposes the required data.
+- Use the same service from desktop and mobile browsers, with layouts designed for the amount of attention available on each device.
 
-| Environment | Artifact | When to use it |
-| --- | --- | --- |
-| macOS and Linux | `npm install --global farming-code` | Default path. Requires Node.js 22 or newer and a system runtime that can load `node-pty`. |
-| Standalone use | platform CLI from GitHub Releases | Manual installation for environments that do not want npm; upgrades remain manual. |
-| Directory deployment | `farming-<version>-<platform>-<arch>.tar.gz` | App bundle with production dependencies and launcher scripts; it uses the target system runtime. |
-| Legacy Linux x64 (glibc < 2.28) | `farming-<version>-linux-x64-legacy-glibc228.tar.gz` | First-install bootstrap with a pinned glibc 2.28 runtime. It installs Farming under `~/.farming/npm`; later one-click updates use npm like the default installation. A Node.js 22 executable and npm are still required. |
-| Custom older Linux build | `farming-<version>-linux-x64-glibc217.tar.gz` | Separately built bundle that rebuilds `node-pty` against a glibc 2.17 baseline; it still needs a usable target Node.js runtime. |
+![Farming Code project files and blame](./docs/products/code/assets/04-files-editor-blame.png)
 
-If you want Farming to launch Codex or Claude Code, install and log in to those CLIs on the same machine first. Farming hosts their CLI sessions; it does not replace their installation or account setup.
+![Farming Review](./docs/products/code/assets/10-review-workflow.png)
 
-## Architecture
+## Supported Agent Paths
 
-```text
-Browser skins
-  React + Vite + Monaco + terminal renderer
-        |
-        | HTTP / WebSocket
-        v
-Farming core
-  Express server + token auth + agent manager + session providers
-        |
-        | native pty host + session engine
-        v
-Execution environment
-  bash / zsh / Codex / Claude Code
-```
+Farming discovers installed CLIs on the host. The richer structured runtime currently applies to providers with ACP support; other detected coding agents remain first-class terminal sessions.
 
-The backend owns agent lifecycle, WebSocket state sync, session engines, workspace file APIs, session providers, model/profile discovery, usage collection, and configuration. Frontend skins organize those capabilities into different experiences. New interactive sessions use the native pty host by default, keeping node-pty agent processes outside the Farming server process so the server and browser can reconnect to live terminals. The native pty host persists across Farming server restarts unless `FARMING_NATIVE_PTY_HOST_PERSIST=0` is set, then exits after an idle grace period once no live sessions or clients remain. Set `FARMING_SESSION_ENGINE=local` only when debugging the in-process node-pty engine.
+| Agent | Structured Chat | Native Terminal | History / resume |
+| --- | --- | --- | --- |
+| Codex | ACP | Yes | Yes |
+| Claude Code | ACP | Yes | Yes |
+| OpenCode | ACP | Yes | Yes |
+| Qoder | ACP | Yes | Yes |
+| Qwen Code | — | Yes | CLI-dependent |
+| Aider | — | Yes | CLI-dependent |
+| GitHub Copilot CLI | — | Yes | CLI-dependent |
+| Amazon Q | — | Yes | CLI-dependent |
+| bash / zsh | — | Yes | No provider-session resume |
 
-The browser terminal renderer defaults to xterm.js. The older Ghostty web renderer is still kept as an explicit debug path through `localStorage.farmingTerminalEngine = 'ghostty'`.
+Farming hosts CLIs that already work on the same machine. It does not replace provider installation, login, or account configuration.
 
-## Install And Run
+## Quick Start
 
-### Install From npm
+Install Node.js 22 or newer, install and sign in to at least one supported coding CLI, then run:
 
 ```bash
 npm install --global farming-code
 farming daemon
 ```
 
-Open **Settings → Updates** to check and install a newer npm version in one click. Farming installs the new package while the current server is still running, restarts only after installation succeeds, and attempts to restore the previous version if the new server cannot start. The equivalent manual command is `npm install --global farming-code@latest`.
-
-### Build From Source
-
-```bash
-npm install
-npm run release:cli
-```
-
-To build an app bundle:
+Farming defaults to port `6694`, base path `/farming`, config directory `~/.farming`, and token authentication. The startup log prints a URL similar to:
 
-```bash
-npm install
-npm run release:app
+```text
+http://development-host:6694/farming?token=<startup-token>
 ```
 
-The standard app bundle includes production dependencies and launcher scripts, and uses the target system runtime as installed.
-
-For Linux x64 systems whose glibc is older than 2.28, build the release asset that carries the pinned legacy runtime:
+Open it, choose **New Agent**, select an Agent and workspace, and start in Chat or Terminal. Useful daemon commands are:
 
 ```bash
-npm run release:app:legacy-linux
+farming status
+farming url
+farming logs
+farming stop
 ```
 
-The resulting `farming-<version>-linux-x64-legacy-glibc228.tar.gz` is a bootstrap package. It extracts the runtime to `~/.farming/glibc228`, installs the bundled Farming release into the private prefix `~/.farming/npm`, and writes a stable compatibility launcher at `~/.farming/bin/farming`. Later updates install `farming-code` into that same prefix through npm, then restart with the compatibility launcher; the tarball is not downloaded again for ordinary application updates.
+The first authenticated start stores a readable random token in `~/.farming/.session-token`; restarts and upgrades reuse it unless `FARMING_TOKEN` overrides it. Token language defaults to the host time zone: Chinese, Japanese, or English.
 
-For a separately built `node-pty` ABI baseline, run the following command inside a clean Linux x64 builder that has glibc 2.17, Node.js 22+, GCC/G++, Make, and Python 3:
+![Start an Agent](./docs/products/code/assets/02-start-agent-picker.png)
 
-```bash
-npm run release:app:linux-compat
-```
+## Desktop And Mobile
 
-The command forces `node-pty` to build from source and rejects the archive unless its native module requires no newer than glibc 2.17. Install it remotely with `FARMING_REMOTE=user@host FARMING_RELEASE_TARBALL=<archive> npm run release:remote:linux-compat`. This ABI-focused bundle still uses the target machine's Node.js and libc.
+Desktop keeps the project, conversation, files, and review close together. Mobile focuses one conversation, terminal, or file at a time and moves navigation into a drawer, making it useful for checking progress and sending a short intervention.
 
-When a clean source checkout is already present on a provisioned Linux x64 builder host, `scripts/build-linux-compat-release-on-builder.sh` automates the remaining container build, ABI verification, packaged bash-agent smoke, and artifact output. Set `FARMING_COMPAT_IMAGE` to an image that already exists on that host. The script uses `--pull=never` and disables container networking by default so release builds reuse existing images and caches instead of downloading infrastructure implicitly; set `FARMING_COMPAT_ALLOW_NETWORK=1` only when an intentional cache refresh is required.
+<p align="center">
+  <img src="./docs/products/code/assets/05-mobile-agent-chat.jpg" alt="Farming Code on mobile" width="320">
+  &nbsp;&nbsp;
+  <img src="./docs/products/crt/assets/09-crt-mobile-dashboard.jpg" alt="Farming CRT on mobile" width="320">
+</p>
 
-### Run A Single-File CLI
+## Installation And Updates
 
-```bash
-chmod +x farming
-./farming daemon
-```
+The npm package is the default distribution. **Settings → Updates** can upgrade npm installations in place: Farming installs the new package while the current server stays alive, restarts only after installation succeeds, and attempts rollback when the new server cannot start.
 
-By default it listens on port `6694`, serves under `/farming`, creates `~/.farming`, enables token auth, and prints a browser URL containing the startup token.
+GitHub Releases also provide standalone CLI and directory bundles. Legacy Linux x64 hosts can use the `linux-x64-legacy-glibc228` first-install bootstrap; subsequent application updates use the same private npm prefix. A separately built glibc 2.17 ABI bundle remains available for controlled environments. See [GitHub Releases](https://github.com/zhuwenzhuang/farming/releases) for current assets and release notes.
 
-Useful commands:
-
-```bash
-./farming status
-./farming logs
-./farming url
-./farming stop
-```
-
-### Run An App Bundle
-
-```bash
-tar -xzf farming-<version>-linux-x64.tar.gz
-cd farming-<version>-linux-x64
-./farming
-```
-
-The standard bundle uses the target machine's ordinary Node.js and native runtime. On a legacy Linux x64 host, download the `-legacy-glibc228.tar.gz` bundle instead and run `./farming` once. After bootstrap, use `~/.farming/bin/farming`; that stable launcher keeps npm updates, server restarts, and PTY child processes on the bundled compatibility runtime.
-
-## Development
+Source development:
 
 ```bash
 npm install
 npm start
 ```
 
-For trusted local development only, token auth can be disabled:
-
-```bash
-npm run start:no-auth
-```
-
-## Configuration
-
-Runtime settings are stored in `~/.farming/settings.json`.
-Agent session metadata is stored separately in `~/.farming/sessions/`. Farming
-uses stable `fsess_*` files for its own Agent records; live `agent-...` ids and
-Codex / Claude provider session ids are stored as metadata on those records.
-The main Projects page membership lives in `sessions/index.json` and is exposed
-as `mainPageSessionKeys` only for API compatibility.
-Archived run history is stored in `~/.farming/history/runs.json`, not in
-`settings.json`.
-Theme overrides, the startup token, server pid/state/log files, and native pty
-host logs live under the same config directory.
-
-Common settings:
+For trusted local development only, `npm run start:no-auth` disables token authentication.
 
-- `defaultLaunchAgent`
-- `agentLaunchProfiles.codex`
-- `agentLaunchProfiles.claude`
-- `agentHomes` (home metadata for Codex, Claude, OpenCode, and Qoder; each provider keeps a non-removable `default` home)
-- `workspaceHistory`
-- `dangerouslySkipAgentPermissionsByDefault` (launch supported coding agents such as Codex, Claude, OpenCode, Qoder, Qwen, Aider, GitHub Copilot CLI, and Amazon Q with their provider-specific dangerous permission-skip flags by default)
+## How It Works
 
-Native terminal sessions are owned by a Farming pty host reached through a local socket derived from `configDir`. By default the host is preserved during server shutdown so a restarted Farming server can recover live terminals; after the last live session and client disappear, the host shuts itself down after a short idle grace period. Set `FARMING_NATIVE_PTY_HOST_PERSIST=0` to tie the host lifetime to the server process. Terminal work should target the native pty host and xterm.js path.
-
-Update behavior follows the installation method. npm installations and legacy Linux installations bootstrapped from `-legacy-glibc228.tar.gz` read versions from the npm registry and provide one-click upgrades in **Settings → Updates**. They install into their existing npm prefix while the old service remains alive, then restart and roll back on startup failure. Source checkouts update through Git, and standalone CLI artifacts are replaced manually. Standard app-bundle installations remain a directory-deployment path and may use a trusted HTTP(S) package directory or manifest URL stored as `settings.updateUrl`.
-
-The simplest source is an HTTP(S) directory URL ending in `/` that lists platform-tagged `farming-<version>-<platform>-<arch>.tar.gz` app bundles and an adjacent `<bundle>.sha256` file for every bundle. Farming verifies the selected bundle's SHA-256 and archive layout before extraction, then runs its installer.
-
-Example deployment templates:
+```text
+Farming Code / Farming CRT
+  React, Monaco, xterm.js, CRT browser skin
+                 │ HTTP + WebSocket
+                 ▼
+Farming core
+  auth, Agent manager, ACP, history, files, review, usage
+                 │ native PTY host + session providers
+                 ▼
+Development host
+  repositories, shells, Codex, Claude Code, OpenCode, Qoder, ...
+```
 
-- `config/farming.deploy.env.example`
-- `config/farming.install.env.example`
+The backend owns lifecycle, authentication, session routing, workspace boundaries, history, and configuration. Interactive terminal sessions use a separate native PTY host by default, allowing browser and server reconnection without replacing the live process. The browser terminal renderer defaults to xterm.js; the Ghostty web adapter remains an explicit debug path.
 
-Real `.env` files are ignored by git.
+Runtime settings live in `~/.farming/settings.json`. Farming session metadata, the project membership index, archived runs, theme settings, update state, logs, and the startup token use separate files under `~/.farming/`. External provider histories remain read-only integrations.
 
 ## Security
 
-Farming controls real terminals and agent processes on the target machine. Run it on trusted development hosts and trusted networks. Do not expose it directly to the public internet without an additional layer such as VPN, SSH tunnel, HTTPS reverse proxy, or network ACLs.
-
-The startup token protects both HTTP and WebSocket traffic. It is generated on first authenticated startup, persisted in `~/.farming/.session-token`, and reused across restarts and upgrades. The generated token is designed to be easier to copy than a long hexadecimal secret: Chinese time zones get a Chinese haiku-style passphrase by default, Japanese time zones get a Japanese haiku-style passphrase, and other time zones get an English passphrase. `FARMING_TOKEN_LOCALE=zh|ja|en|auto` can override generation behavior for a new token.
-
-`FARMING_DISABLE_AUTH=1` is only for trusted local development. Terminal-owned Codex / Claude sessions apply a permission change by restarting with the selected CLI flags, resuming when a provider session id is available and starting fresh otherwise. App Server Codex applies the new approval and sandbox policy to its existing thread without a CLI restart.
-
-See [SECURITY.md](./SECURITY.md) for the reporting policy and deployment notes.
+Farming controls real terminals and files on the target machine. Run it on a trusted development host and trusted network. Do not expose it directly to the public internet without a VPN, SSH tunnel, HTTPS reverse proxy, or equivalent access control.
 
-## Troubleshooting
+Token authentication protects HTTP and WebSocket traffic. `FARMING_DISABLE_AUTH=1` is only for trusted local development. Workspace file APIs validate paths against the selected project root. See [SECURITY.md](./SECURITY.md) for reporting and deployment guidance.
 
-- **No `codex` or `claude` option works**: verify the CLI is installed, logged in, and runnable from a normal shell on the same host.
-- **Native PTY cannot start**: verify the target system's Node.js and packaged `node-pty` runtime are compatible. On Linux x64 with glibc older than 2.28, use the `-legacy-glibc228` app bundle.
-- **Port already in use**: pass `--port <port>` or let the default daemon mode choose the next available port when no explicit port is provided.
-- **Phone cannot connect**: use the network URL printed by the server and make sure the phone can reach the target machine.
-- **Lost the token URL**: run `./farming url`, or check `./farming logs`.
-
-## Repository Layout
-
-```text
-farming/
-├── .gitattributes          # Source archive export rules
-├── backend/                 # Node.js server, session engines, and backend APIs
-├── src/                     # React + Vite frontend; Farming Code helpers live under src/components/code/
-├── frontend/skins/crt/      # Independent live CRT entry, app, and visual effects
-├── frontend/*.js            # Shared terminal/session browser bridges
-├── docs/products/code/      # Farming Code product docs and screenshots
-├── docs/products/crt/       # CRT skin layout docs
-├── config/                  # deployment / install templates
-├── scripts/                 # release, deployment, screenshots, tests
-├── tests/e2e/               # Playwright browser flows
-├── pkg.config.cjs
-└── bin/farming
-```
+## Documentation
 
-`releases/` is a local packaging output directory and is not committed.
+- [Farming 2 product overview and capability map](./docs/products/README.md)
+- [Farming Code guide](./docs/products/code/README.md)
+- [Farming CRT guide](./docs/products/crt/README.md)
+- [Mobile guide](./docs/products/code/mobile-guide.md)
+- [ACP runtime](./docs/products/code/acp-runtime.md)
+- [Review foundation](./docs/products/code/review-foundation.md)
+- [Release history](https://github.com/zhuwenzhuang/farming/releases)
+- [Contributor instructions](./AGENTS.md)
 
-## Tests
-
-```bash
-npm run check
-```
-
-Common individual checks:
+## Development Checks
 
 ```bash
 npm test
 npm run typecheck
 npm run lint
+FARMING_BASE_PATH=/farming npm run build
 npm run test:e2e:playwright
 ```
 
-## Authors
+Product screenshots are generated from an anonymous demo workspace with real browser flows:
 
-- [zhuwenzhuang](https://github.com/zhuwenzhuang)
-- [l4wei](https://github.com/l4wei)
-
-## Contributing
-
-Issues and pull requests are welcome. Start with [CONTRIBUTING.md](./CONTRIBUTING.md), and keep user-facing docs updated when behavior or packaging changes.
+```bash
+npm run docs:product:screenshots
+```
 
 ## License
 
-Farming is released under the MIT License. See [LICENSE](./LICENSE).
+Farming is released under the [MIT License](./LICENSE). Third-party notices are listed in [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).