farming-code 2.2.7 → 2.2.11

package/README.md

@@ -9,279 +9,190 @@
 ![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 an open-source, customizable 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.
-
-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.
-
-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.
-
-For a product-oriented introduction, screenshots, and the architecture diagram, see the [Farming 2 Wiki](https://github.com/zhuwenzhuang/farming/wiki/English).
-
-![Farming Code workspace](./docs/products/code/assets/01-code-workspace.png)
-
-> If you are an AI agent contributing to this repository, read [AGENTS.md](./AGENTS.md) first.
-
-## Why Farming Exists
-
-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.
-
-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 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).
+Run Farming on the development machine where your coding CLIs already work, then return to the same tasks 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.
 
 ## 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.
+With Node.js 22 or newer and at least one supported coding CLI installed and signed in, install and start Farming in one command:
 
 ```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>
+npm install --global farming-code@latest && farming daemon
 ```
 
-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.
+Open the authenticated URL printed by the command, choose **New Agent**, select an Agent and workspace, and start in Chat or Terminal.
 
-## Downloads
+![Farming Code workspace](./docs/products/code/assets/01-code-workspace.png)
 
-The npm package is the default distribution. GitHub release artifacts remain available for manual installation.
+## Two Interfaces, One Runtime
 
-Farming uses these practical deployment shapes:
+Farming 2 provides two complete browser interfaces over the same agents and sessions.
 
-| 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
 
-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.
+The default workbench for reading conversations, intervening in tasks, editing files, and reviewing workspace changes.
 
-## Architecture
+![Farming Code structured Chat](./docs/products/code/assets/11-code-agent-process.png)
 
-```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 CRT
 
-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.
+A keyboard-first control room for watching many agents, opening structured Chat or raw Terminal, searching history, and reading live usage telemetry.
 
-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 CRT dashboard](./docs/products/crt/assets/01-crt-dashboard.png)
 
-## Install And Run
+| | 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/` |
 
-### Install From npm
+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.
 
-```bash
-npm install --global farming-code
-farming daemon
-```
+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.
 
-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`.
+## Farming Net: One Portal For Deployments
 
-### Build From Source
+Farming Net is a separate, token-protected directory for the Farming instances you already run. Its cards can point to a Farming on the current device, a remote development host, an intranet address, or a tunnel. Enrolled targets accept short-lived signed passes, so users keep one portal login instead of a list of deployment URLs and target tokens.
 
 ```bash
-npm install
-npm run release:cli
+FARMING_NET_PORT=6693 FARMING_NET_BASE_PATH=/farming-net npm run start:net
 ```
 
-To build an app bundle:
+The portal keeps its token, signing identity, and private `instances.json` registry under `~/.farming-net/`. It does not proxy target traffic or store target tokens; each destination remains an independent Farming service and explicitly chooses whether to trust the portal. See the [Farming Net guide](./docs/products/net/README.md) for enrollment and the security boundary.
 
-```bash
-npm install
-npm run release:app
-```
+## What You Can Do
 
-The standard app bundle includes production dependencies and launcher scripts, and uses the target system runtime as installed.
+- Group live agents by project, pin or rename important work, track unread activity, search live and historical sessions, and archive or resume tasks.
+- 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.
+- Switch the same provider session between structured Chat and a real PTY Terminal. Supported Codex model, reasoning, Fast, Ultra, and permission changes reach the live workflow; a compatible Terminal applies model changes immediately and confirms the CLI state before accepting the next Composer message.
+- Browse, search, and lightly edit Project Files; inspect a VS Code-derived Git history graph, changed files, Git changes, Diff, and Blame; then open commits or working-copy changes in Review with captured revisions, inline comments, and Reviewed state.
+- Observe CPU/MEM, token-rate, context, quota, provider usage, and CRT daily/live token telemetry when the provider exposes the required data.
+- Continue the same Farming Code task from desktop or phone without moving the Agent process away from the development host.
 
-For Linux x64 systems whose glibc is older than 2.28, build the release asset that carries the pinned legacy runtime:
+![Farming Code project files and blame](./docs/products/code/assets/04-files-editor-blame.png)
 
-```bash
-npm run release:app:legacy-linux
-```
+![Separate Review entry points for tracked and untracked workspace changes](./docs/products/code/assets/10-review-workflow.png)
 
-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.
+## Supported Agent Paths
 
-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:
+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.
 
-```bash
-npm run release:app:linux-compat
-```
+| 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 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.
+Farming hosts CLIs that already work on the same machine. It does not replace provider installation, login, or account configuration.
 
-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.
+## Runtime Defaults And Daemon Commands
 
-### Run A Single-File CLI
+Farming defaults to port `6694`, base path `/farming`, config directory `~/.farming`, and token authentication. The startup log prints a URL similar to:
 
-```bash
-chmod +x farming
-./farming daemon
+```text
+http://development-host:6694/farming?token=<startup-token>
 ```
 
-By default it listens on port `6694`, serves under `/farming`, creates `~/.farming`, enables token auth, and prints a browser URL containing the startup token.
-
-Useful commands:
+Useful daemon commands are:
 
 ```bash
-./farming status
-./farming logs
-./farming url
-./farming stop
+farming status
+farming url
+farming logs
+farming stop
 ```
 
-### Run An App Bundle
+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.
 
-```bash
-tar -xzf farming-<version>-linux-x64.tar.gz
-cd farming-<version>-linux-x64
-./farming
-```
+![Start an Agent](./docs/products/code/assets/02-start-agent-picker.png)
 
-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.
+## Desktop And Mobile
 
-## Development
+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.
 
-```bash
-npm install
-npm start
-```
+<p align="center">
+  <img src="./docs/products/code/assets/05-mobile-agent-chat.jpg" alt="Farming Code on mobile" width="320">
+</p>
 
-For trusted local development only, token auth can be disabled:
+Farming CRT is currently a desktop interface. Use Farming Code from a phone; CRT mobile concepts are not part of the supported product yet.
 
-```bash
-npm run start:no-auth
-```
-
-## Configuration
+## Installation And Updates
 
-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.
+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.
 
-Common settings:
+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.
 
-- `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)
+Source development:
 
-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.
+```bash
+npm install
+npm start
+```
 
-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`.
+For trusted local development only, `npm run start:no-auth` disables token authentication.
 
-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.
+## How It Works
 
-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 WebGL as its single supported product path; the Ghostty web adapter remains an explicit debug path, not a runtime fallback.
 
-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.
-
-## Troubleshooting
-
-- **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
-```
+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.
 
-`releases/` is a local packaging output directory and is not committed.
+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.
 
-## Tests
+## Documentation
 
-```bash
-npm run check
-```
+- [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)
+- [Farming Net deployment portal](./docs/products/net/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)
 
-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).