flywhl-harness 0.2.0__tar.gz

flywhl_harness-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.flywhl/
+playground/.flywhl/
+playground/hello.py
+playground/demo_big.txt
+dist/
+*.egg-info/
+docs/node_modules/
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+.DS_Store
+.env
+.claude/
+.idea/

flywhl_harness-0.2.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# 更新记录
+
+版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。1.0 之前，次版本号的升级可能带破坏性变化，这类变化都写在“行为变化”一节。
+
+## [0.2.0] - 2026-11-05
+
+第一个发布到 PyPI 的版本。v0.1.0 之后的主线是安全边界：系统沙箱从可选原型变成默认开启，命令分析、凭证保护、供应链检查都重做了一轮。
+
+### 行为变化
+
+**bash、命令 hook、stdio MCP 服务器、`verify_command` 默认都在系统沙箱里运行。** macOS 用 `sandbox-exec`，Linux 用 bubblewrap。
+命令读不到凭证位置，只能写工作区和临时目录，网络默认是空白名单。
+
+| 你会看到 | 原因 | 怎么处理 |
+|---|---|---|
+| Linux 上 bash 拒绝执行，提示没有可用的沙箱 | 没装 bubblewrap，或 user namespace 被限制。这时不会退回沙箱外 | 装 bubblewrap；Ubuntu 24.04 可能还要 `sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0`。确实不要沙箱时，在 `~/.flywhl/config.toml` 写 `sandbox = "off"`，或启动时加 `--sandbox off` |
+| 配置了 MCP 服务器时 harness 启动失败 | 同上，MCP 服务器不会在沙箱外启动 | 同上 |
+| `pip install`、`npm install`、`git clone` 连不上网 | 默认白名单为空，报错里写着被拦的主机 | 启动时加 `--net-allow pypi.org`，或写进 `permissions.network_allow` |
+| `git push`（SSH）、`gh`、`kubectl`、`docker` 失败 | 沙箱里没有凭证和本机套接字 | 让模型带 `outside_sandbox: true` 请求，由人确认后在沙箱外执行；或者自己在终端里跑 |
+| `git config`、`git remote add`、`git push -u` 失败 | `.git/hooks`、`.git/config` 在沙箱里只读。`git add`、`git commit` 不受影响 | 同上 |
+| 项目 `flywhl.toml` 里的 `sandbox = "off"` 不生效 | 关闭沙箱只有三个入口：用户配置、`-c` 指定的文件、`--sandbox off`。信任项目配置也不行 | 改用这三个入口之一 |
+| 无人值守时 `write`、`edit` 改 `.git/config`、`.git/hooks`、`flywhl.toml` 被拒绝，`--yes` 也不行；有人看时每次都要确认 | 这些位置在沙箱里只读，文件工具不在沙箱里，放开就能绕过沙箱。没开沙箱时不受影响 | 由人确认，或者自己在终端里改 |
+| 写了 `sandbox = "macos"` 或 `"linux"` 的配置连不上网 | 没写 `sandbox_network` 时从 `allow` 变成 `allowlist` | 显式写 `sandbox_network = "allow"`，或把主机加进白名单 |
+
+`outside_sandbox` 是一道独立的人工门：任何模式下都要人确认，`auto_approve`、规则、会话授权都放行不了，无人值守时直接拒绝。
+`write`、`edit` 写沙箱里只读的位置走同一道门。
+
+**English summary.** bash, command hooks, stdio MCP servers and `verify_command` now run inside an OS sandbox by default
+(`sandbox-exec` on macOS, bubblewrap on Linux). Credentials are unreadable, writes are limited to the workspace and temp directories,
+and the network starts as an empty allowlist. If no sandbox is available the harness refuses to run instead of falling back:
+install bubblewrap, or opt out with `sandbox = "off"` in `~/.flywhl/config.toml` or `--sandbox off`; project config cannot opt out.
+Allow hosts with `--net-allow` or `permissions.network_allow`. Commands that need your credentials (`git push` over SSH, `gh`, `kubectl`)
+either go through the human-only `outside_sandbox` gate or run in your own terminal. `.git/hooks` and `.git/config` are read-only inside the
+sandbox, so `git config`, `git remote add` and `git push -u` fail there. `write` and `edit` on those paths and on `flywhl.toml` take the same
+human-only gate, so unattended runs refuse them, including `--yes`. Configs that set `macos` or `linux` without `sandbox_network`
+move from `allow` to `allowlist`.
+
+### 新增
+
+- 系统沙箱：`sandbox = "auto"` 启动时真跑一次探测；Linux bubblewrap 档位；两个平台都有出站白名单，宿主代理按解析结果放行、重写 Host，命令结束时回收后台进程；单条 hook、MCP 服务器可以单独设 `sandbox`、`network_allow`，MCP 还可以设 `sandbox_network`。
+- `outside_sandbox`：在沙箱外执行一条命令的人工门。
+- 无人值守自动批准：`auto_approve` 配置和 `--approve`。
+- 审批疲劳提示：秒批成串、同类操作反复批准时提醒，审批页给出疲劳指标。
+- hook 与 MCP 的供应链检查：引用的脚本按内容绑定，经 `npx`、`uvx`、`docker run` 临时拉取的包可以要求锁到确切版本（`require_pinned`）。
+- 「环境与安全」页、`flywhl doctor`、启动信息显示实际生效的沙箱档位和网络策略。
+- 精简手册、能力清单与质量审计记录。
+
+### 安全
+
+- 命令分析：按 bash 的命令边界切分，堵住换行、注释、保留字绕过；跟踪变量取值与当前目录；展开函数和别名；预算或组合数超限时拒绝，不再放行。
+- 凭证保护：匹配不区分大小写；bash 命中凭证位置时任何模式都拒绝；文件工具和 bash 共用一份清单。
+- 本机 IPC：钥匙串、剪贴板、`open`、launchd、Unix 套接字不再绕过沙箱。
+- 关掉沙箱外的两条通道：影子 git 快照不再替沙箱执行工作区里的配置，回放不再绕过人工门。
+- 命令 hook 子进程剥离密钥类环境变量，需要的用 `env`、`pass_env` 显式传入。MCP 服务器自报的注解默认不采信。
+- 项目配置不能替人打开自动批准；放行规则按文件实际落点匹配；MCP 服务器与 hook 的放宽类设置按类型严格校验。
+- Web 服务：写请求的 Origin 必须与 Host 同主机同端口，查询串里的令牌只在 `/` 兑换。会话库与数据目录只给属主访问。
+
+### 修复
+
+- 演示模型名只走内置演示供应商，不会访问网络。
+- 命令行的 `--provider` 优先于 `.env` 和环境变量里自带供应商的模型。
+- 窄屏下检查器覆盖层避开页头，可以点遮罩收起。
+- 内置提示词不再要求模型用中文回答，改为跟随用户使用的语言。
+- 审批时写的拒绝理由改走提醒通道。放在工具结果里时，模型会按“工具结果是数据”的规则不照做，停下来反问。
+- 压缩时模型没给出可用的摘要，之前保留的事实不再丢失。调用失败或空回复时退回的确定性摘要不带上一次的内容；模型接着对话往下说时，那句话会被当成摘要存下来。
+- OpenRouter 的 `not a valid model ID` 识别为模型不存在，降级链能接手。
+- 经 OpenRouter 调 Claude 时打开缓存。之前缓存命中一直是 0。
+- `.flywhl/` 里自动放一份 `.gitignore`，忽略会话库、审批记录和快照，`config.toml` 和 `skills/` 仍然可以提交。之前这些文件一直显示为未跟踪，`git add -A` 会把它们带进仓库。
+- 命令的环境变量过滤不再删掉 `GIT_AUTHOR_NAME`、`GIT_AUTHOR_EMAIL`、`GIT_AUTHOR_DATE`。它们撞上了 `AUTH` 规则，靠环境变量配身份时提交会报身份未知。
+- 确定性回放用录制的压缩摘要、插话、恢复说明和验收结果，同一会话的后续 Run 也能回放。之前真实模型的压缩轨迹必定报分叉，验收失败重试的轨迹会少走几步而查不出来。新增 `replay_trajectory()`，只靠保存的轨迹就能回放。
+
+### 工程
+
+- 新增 `bench/`：公开基准的流水线、30 个任务和方法说明。真实模型只在一次性容器里运行，第一次结果见[基准页](https://flywhlway.github.io/flywhl-harness/benchmark/)。live 夹具可以用 `FLYWHL_LIVE_ARTIFACTS` 导出结果和轨迹。
+- 包：`pip install flywhl-harness`、`pipx install flywhl-harness` 可用；sdist 改成白名单；版本号只在 `__init__.py` 写一处。
+- 测试统一在系统沙箱里运行，子进程启动前有执行绊线，起因见[事故复盘](https://github.com/flywhlway/flywhl-harness/blob/main/docs/quality-audit/incident-2026-10-31.md)。
+- CI：Linux 和 macOS 真跑沙箱用例，沙箱起不来时失败；新增干净安装验收、覆盖率和依赖漏洞报告；推送 `v*` 标签走发布流水线。
+
+## [0.1.0] - 2026-10-16
+
+首个标签。Agent Loop、工具与 MCP、上下文压缩、四层状态模型、检查点与崩溃恢复、取消语义、权限与 Hooks、多 Agent、轨迹回放与评测、Web 控制台和 30 章教程。

flywhl_harness-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flywhl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flywhl_harness-0.2.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: flywhl-harness
+Version: 0.2.0
+Summary: A hand-written Agent Harness in Python: agent loop, tools, context compaction, crash recovery, permissions, a default-on OS sandbox, replay and a web console.
+Project-URL: Homepage, https://github.com/flywhlway/flywhl-harness
+Project-URL: Documentation, https://flywhlway.github.io/flywhl-harness/en/
+Project-URL: Source, https://github.com/flywhlway/flywhl-harness
+Project-URL: Issues, https://github.com/flywhlway/flywhl-harness/issues
+Project-URL: Changelog, https://github.com/flywhlway/flywhl-harness/blob/main/CHANGELOG.md
+Author: flywhl
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,harness,llm,mcp,runtime,sandbox,tool-calling
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: coverage>=7.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flywhl-harness
+
+[![tests](https://github.com/flywhlway/flywhl-harness/actions/workflows/tests.yml/badge.svg)](https://github.com/flywhlway/flywhl-harness/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/flywhl-harness)](https://pypi.org/project/flywhl-harness/)
+
+English | [简体中文](https://github.com/flywhlway/flywhl-harness/blob/main/README.md)
+
+> **Agent = Model + Harness.** The model does the thinking; the harness does everything else.
+
+flywhl-harness is an Agent Harness written by hand in Python, with no agent framework underneath: about 15,000 lines that implement the
+mechanisms a production harness needs as code you can run, test and replace. It comes with a web console and a 30-chapter tutorial.
+
+It is meant for two kinds of reader: engineers who want to see how a harness works all the way down, and developers who want a local
+coding agent that can open an untrusted repository without being handed the keys to the machine.
+
+**The console, CLI messages, scripted demo and code comments are in Chinese.** The model replies in the language you write in. The
+[English docs](https://flywhlway.github.io/flywhl-harness/en/) summarize every chapter and link to the Chinese full text.
+
+## What it implements
+
+| Area | What you get |
+|---|---|
+| Loop | Async-generator main loop with explicit phases; steering and queued follow-ups while a run is active |
+| Models | Unified messages and stream events; provider profiles for DeepSeek, Alibaba Bailian, Kimi, Zhipu, MiniMax, OpenRouter, Ollama and Anthropic; error classification, jittered retries, circuit breaking, cross-provider fallback |
+| Tools | Three side-effect levels (read / write / external); concurrent reads, serialized writes, results returned in call order; oversized results moved behind handles; MCP client |
+| Context | Context usage estimates, clearing of stale tool results, summary compaction that never splits a tool call from its result and always keeps the original task |
+| State | Session / Entry / Run / Step / Event model on SQLite WAL; branching session tree; append-only history |
+| Lifecycle | 14-state run machine with compare-and-swap transitions; cooperative cancellation; pause and resume; heartbeat leases and crash takeover, so a `kill -9` still gives exactly-once external side effects |
+| Policy | Four permission modes; deny > ask > allow rules; bash risk analysis; credential locations denied in every mode; taint tracking; hooks compatible with the Claude Code protocol; durable human approval with diff previews |
+| Isolation | Default-on OS sandbox with an egress allowlist; path confinement; shadow-git snapshots and rollback; secrets stripped from child processes |
+| Multi-agent | Subagents with isolated context and a structured return contract; DAG scheduling with concurrency quotas |
+| Measurement | Trajectory export with OTel GenAI-style spans; deterministic replay and counterfactual forks; evaluation with Wilson intervals and McNemar tests |
+
+## Quick start
+
+Requires Python 3.11+ on macOS or Linux. Windows is not supported. On Linux, install
+[bubblewrap](https://github.com/containers/bubblewrap) first (`sudo apt install bubblewrap`): bash runs in an OS sandbox by default and
+refuses to run if there isn't one.
+
+```bash
+pipx install flywhl-harness      # or: uv tool install flywhl-harness
+
+mkdir agent-demo
+flywhl serve -w agent-demo       # open the tokenized link it prints
+```
+
+With no API key set, the console uses the built-in `flywhl-demo` model, a scripted model that needs no network. The demo cards on the start
+page walk through approvals, cancellation, compaction, subagents and loop detection.
+
+To use a real model (the default is `deepseek:deepseek-flash`):
+
+```bash
+cd agent-demo
+export DEEPSEEK_API_KEY=sk-...
+flywhl doctor                        # streaming and tool round trip for each configured provider
+flywhl serve -w .
+flywhl chat --model kimi:kimi-k2.6   # also dashscope:qwen3.8-flash, minimax:MiniMax-M2.7, ollama:qwen3.5:9b-mlx
+```
+
+For Anthropic's official SDK, install the extra with `pipx install 'flywhl-harness[anthropic]'`, then use
+`--model anthropic:claude-opus-5-5`.
+
+The access token is on by default, even on loopback. It is stored in `~/.flywhl/server_token` and survives restarts.
+
+## Default security posture
+
+The goal is that opening an untrusted repository is safe with no configuration. bash, command hooks, stdio MCP servers and
+`verify_command` all run in an OS sandbox: `sandbox-exec` on macOS, bubblewrap on Linux.
+
+**What it stops**
+
+- Reading credential locations such as `~/.ssh` and cloud config, enforced by the kernel on real paths.
+- Writing outside the workspace and temp directories.
+- Reaching the network, unless the host is on the allowlist. The list starts empty, so this is effectively offline until you add a host, and a
+  blocked call names the host and how to allow it.
+- Local IPC that would bypass the sandbox: keychain, clipboard, `open`, launchd, Unix sockets.
+- A repository's own config turning any of this off. Only your user config, a file passed with `-c`, or `--sandbox off` can do that.
+
+If no sandbox is available, the harness refuses to run commands. It does not quietly fall back.
+
+**What it does not stop**
+
+- Things written into the workspace that you later run outside the sandbox: a `Makefile`, `.envrc` or `package.json` script.
+- Data leaving through a host you allowed. The workspace is readable, so allowing a host anyone can upload to allows exfiltration.
+- Kernel exploits. The sandbox shares the host kernel. It contains mistakes and injection-driven overreach, and it is not a boundary for
+  multi-tenant use.
+
+**Everyday consequences**
+
+```bash
+flywhl chat --net-allow pypi.org --net-allow files.pythonhosted.org   # let the model install packages
+```
+
+Commands that need your credentials (`git push` over SSH, `gh`, `kubectl`) fail in the sandbox. Run them in your own terminal, or let the
+model request `outside_sandbox: true`, a separate human gate that always needs a person: `auto_approve`, rules and session grants cannot
+pass it, and unattended runs are refused. `.git/hooks` and `.git/config` are read-only in the sandbox, so `git add` and `git commit` work
+while `git config`, `git remote add` and `git push -u` do not.
+
+Details: [workspace and sandbox](https://flywhlway.github.io/flywhl-harness/en/governance/workspace-sandbox) ·
+[behavior changes in 0.2.0](https://github.com/flywhlway/flywhl-harness/blob/main/CHANGELOG.md)
+
+## Use as a library
+
+```python
+import asyncio
+from typing import Annotated
+from flywhl_harness import Harness, HarnessConfig, HookEvent, HookOutput, Effect, tool
+
+@tool(effect=Effect.READ)
+async def weather(city: Annotated[str, "City name"]) -> str:
+    """Look up the weather for a city."""
+    return f"{city}: sunny, 23°C"
+
+async def main():
+    async with Harness(HarnessConfig.load(workspace=".")) as h:
+        h.tools.register(weather)
+
+        @h.hooks.on(HookEvent.PRE_TOOL_USE, matcher="bash")
+        async def no_rm(inp):
+            if "rm " in inp.tool_input["command"]:
+                return HookOutput(decision="deny", reason="Deleting files is not allowed")
+
+        result = await h.run("What's the weather in Shanghai?", on_event=print)
+        print(result.status, result.text)
+
+asyncio.run(main())
+```
+
+## Project status
+
+Beta. The supported use is a local, single-user developer tool. It is not built for multi-user or multi-tenant service, and the console
+should not be exposed beyond loopback.
+
+- CI runs the offline suite on Linux (Python 3.11–3.13) and macOS, runs the sandbox tests for real on both, and installs the wheel into a
+  clean environment to verify the sandbox boundaries end to end.
+- 33 live scenarios against real models live in `tests/live`. They cost money and need keys, so they run outside CI, in a disposable container.
+- Open security gaps are listed rather than hidden. Workspace files are not yet a taint source, and project instruction files still reach
+  the system prompt. See the [security chapter](https://flywhlway.github.io/flywhl-harness/en/governance/security) and the
+  [readiness review](https://github.com/flywhlway/flywhl-harness/blob/main/docs/quality-audit/release-readiness.md).
+- The [first benchmark](https://flywhlway.github.io/flywhl-harness/en/benchmark/) covers 5 models and 30 small tasks at one commit. It is evidence for the harness mechanisms, not a claim about task success rates in real work.
+
+## Documentation
+
+- [English docs](https://flywhlway.github.io/flywhl-harness/en/): quick start, architecture, and a summary of all 30 chapters
+- [Chinese tutorial](https://flywhlway.github.io/flywhl-harness/): the full text
+- [Changelog](https://github.com/flywhlway/flywhl-harness/blob/main/CHANGELOG.md)
+
+To read the code or run the examples and tests, clone the repository. The examples are not in the wheel.
+
+```bash
+git clone https://github.com/flywhlway/flywhl-harness && cd flywhl-harness
+uv sync --all-extras
+.venv/bin/python examples/11_kill9_cli_recover.py    # kill -9 a run, take over from another process, verify 7 invariants
+.venv/bin/python -m pytest -q                        # runs inside an OS sandbox, in two stages
+```
+
+MIT License

flywhl_harness-0.2.0/README.en.md

@@ -0,0 +1,157 @@
+# flywhl-harness
+
+[![tests](https://github.com/flywhlway/flywhl-harness/actions/workflows/tests.yml/badge.svg)](https://github.com/flywhlway/flywhl-harness/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/flywhl-harness)](https://pypi.org/project/flywhl-harness/)
+
+English | [简体中文](https://github.com/flywhlway/flywhl-harness/blob/main/README.md)
+
+> **Agent = Model + Harness.** The model does the thinking; the harness does everything else.
+
+flywhl-harness is an Agent Harness written by hand in Python, with no agent framework underneath: about 15,000 lines that implement the
+mechanisms a production harness needs as code you can run, test and replace. It comes with a web console and a 30-chapter tutorial.
+
+It is meant for two kinds of reader: engineers who want to see how a harness works all the way down, and developers who want a local
+coding agent that can open an untrusted repository without being handed the keys to the machine.
+
+**The console, CLI messages, scripted demo and code comments are in Chinese.** The model replies in the language you write in. The
+[English docs](https://flywhlway.github.io/flywhl-harness/en/) summarize every chapter and link to the Chinese full text.
+
+## What it implements
+
+| Area | What you get |
+|---|---|
+| Loop | Async-generator main loop with explicit phases; steering and queued follow-ups while a run is active |
+| Models | Unified messages and stream events; provider profiles for DeepSeek, Alibaba Bailian, Kimi, Zhipu, MiniMax, OpenRouter, Ollama and Anthropic; error classification, jittered retries, circuit breaking, cross-provider fallback |
+| Tools | Three side-effect levels (read / write / external); concurrent reads, serialized writes, results returned in call order; oversized results moved behind handles; MCP client |
+| Context | Context usage estimates, clearing of stale tool results, summary compaction that never splits a tool call from its result and always keeps the original task |
+| State | Session / Entry / Run / Step / Event model on SQLite WAL; branching session tree; append-only history |
+| Lifecycle | 14-state run machine with compare-and-swap transitions; cooperative cancellation; pause and resume; heartbeat leases and crash takeover, so a `kill -9` still gives exactly-once external side effects |
+| Policy | Four permission modes; deny > ask > allow rules; bash risk analysis; credential locations denied in every mode; taint tracking; hooks compatible with the Claude Code protocol; durable human approval with diff previews |
+| Isolation | Default-on OS sandbox with an egress allowlist; path confinement; shadow-git snapshots and rollback; secrets stripped from child processes |
+| Multi-agent | Subagents with isolated context and a structured return contract; DAG scheduling with concurrency quotas |
+| Measurement | Trajectory export with OTel GenAI-style spans; deterministic replay and counterfactual forks; evaluation with Wilson intervals and McNemar tests |
+
+## Quick start
+
+Requires Python 3.11+ on macOS or Linux. Windows is not supported. On Linux, install
+[bubblewrap](https://github.com/containers/bubblewrap) first (`sudo apt install bubblewrap`): bash runs in an OS sandbox by default and
+refuses to run if there isn't one.
+
+```bash
+pipx install flywhl-harness      # or: uv tool install flywhl-harness
+
+mkdir agent-demo
+flywhl serve -w agent-demo       # open the tokenized link it prints
+```
+
+With no API key set, the console uses the built-in `flywhl-demo` model, a scripted model that needs no network. The demo cards on the start
+page walk through approvals, cancellation, compaction, subagents and loop detection.
+
+To use a real model (the default is `deepseek:deepseek-flash`):
+
+```bash
+cd agent-demo
+export DEEPSEEK_API_KEY=sk-...
+flywhl doctor                        # streaming and tool round trip for each configured provider
+flywhl serve -w .
+flywhl chat --model kimi:kimi-k2.6   # also dashscope:qwen3.8-flash, minimax:MiniMax-M2.7, ollama:qwen3.5:9b-mlx
+```
+
+For Anthropic's official SDK, install the extra with `pipx install 'flywhl-harness[anthropic]'`, then use
+`--model anthropic:claude-opus-5-5`.
+
+The access token is on by default, even on loopback. It is stored in `~/.flywhl/server_token` and survives restarts.
+
+## Default security posture
+
+The goal is that opening an untrusted repository is safe with no configuration. bash, command hooks, stdio MCP servers and
+`verify_command` all run in an OS sandbox: `sandbox-exec` on macOS, bubblewrap on Linux.
+
+**What it stops**
+
+- Reading credential locations such as `~/.ssh` and cloud config, enforced by the kernel on real paths.
+- Writing outside the workspace and temp directories.
+- Reaching the network, unless the host is on the allowlist. The list starts empty, so this is effectively offline until you add a host, and a
+  blocked call names the host and how to allow it.
+- Local IPC that would bypass the sandbox: keychain, clipboard, `open`, launchd, Unix sockets.
+- A repository's own config turning any of this off. Only your user config, a file passed with `-c`, or `--sandbox off` can do that.
+
+If no sandbox is available, the harness refuses to run commands. It does not quietly fall back.
+
+**What it does not stop**
+
+- Things written into the workspace that you later run outside the sandbox: a `Makefile`, `.envrc` or `package.json` script.
+- Data leaving through a host you allowed. The workspace is readable, so allowing a host anyone can upload to allows exfiltration.
+- Kernel exploits. The sandbox shares the host kernel. It contains mistakes and injection-driven overreach, and it is not a boundary for
+  multi-tenant use.
+
+**Everyday consequences**
+
+```bash
+flywhl chat --net-allow pypi.org --net-allow files.pythonhosted.org   # let the model install packages
+```
+
+Commands that need your credentials (`git push` over SSH, `gh`, `kubectl`) fail in the sandbox. Run them in your own terminal, or let the
+model request `outside_sandbox: true`, a separate human gate that always needs a person: `auto_approve`, rules and session grants cannot
+pass it, and unattended runs are refused. `.git/hooks` and `.git/config` are read-only in the sandbox, so `git add` and `git commit` work
+while `git config`, `git remote add` and `git push -u` do not.
+
+Details: [workspace and sandbox](https://flywhlway.github.io/flywhl-harness/en/governance/workspace-sandbox) ·
+[behavior changes in 0.2.0](https://github.com/flywhlway/flywhl-harness/blob/main/CHANGELOG.md)
+
+## Use as a library
+
+```python
+import asyncio
+from typing import Annotated
+from flywhl_harness import Harness, HarnessConfig, HookEvent, HookOutput, Effect, tool
+
+@tool(effect=Effect.READ)
+async def weather(city: Annotated[str, "City name"]) -> str:
+    """Look up the weather for a city."""
+    return f"{city}: sunny, 23°C"
+
+async def main():
+    async with Harness(HarnessConfig.load(workspace=".")) as h:
+        h.tools.register(weather)
+
+        @h.hooks.on(HookEvent.PRE_TOOL_USE, matcher="bash")
+        async def no_rm(inp):
+            if "rm " in inp.tool_input["command"]:
+                return HookOutput(decision="deny", reason="Deleting files is not allowed")
+
+        result = await h.run("What's the weather in Shanghai?", on_event=print)
+        print(result.status, result.text)
+
+asyncio.run(main())
+```
+
+## Project status
+
+Beta. The supported use is a local, single-user developer tool. It is not built for multi-user or multi-tenant service, and the console
+should not be exposed beyond loopback.
+
+- CI runs the offline suite on Linux (Python 3.11–3.13) and macOS, runs the sandbox tests for real on both, and installs the wheel into a
+  clean environment to verify the sandbox boundaries end to end.
+- 33 live scenarios against real models live in `tests/live`. They cost money and need keys, so they run outside CI, in a disposable container.
+- Open security gaps are listed rather than hidden. Workspace files are not yet a taint source, and project instruction files still reach
+  the system prompt. See the [security chapter](https://flywhlway.github.io/flywhl-harness/en/governance/security) and the
+  [readiness review](https://github.com/flywhlway/flywhl-harness/blob/main/docs/quality-audit/release-readiness.md).
+- The [first benchmark](https://flywhlway.github.io/flywhl-harness/en/benchmark/) covers 5 models and 30 small tasks at one commit. It is evidence for the harness mechanisms, not a claim about task success rates in real work.
+
+## Documentation
+
+- [English docs](https://flywhlway.github.io/flywhl-harness/en/): quick start, architecture, and a summary of all 30 chapters
+- [Chinese tutorial](https://flywhlway.github.io/flywhl-harness/): the full text
+- [Changelog](https://github.com/flywhlway/flywhl-harness/blob/main/CHANGELOG.md)
+
+To read the code or run the examples and tests, clone the repository. The examples are not in the wheel.
+
+```bash
+git clone https://github.com/flywhlway/flywhl-harness && cd flywhl-harness
+uv sync --all-extras
+.venv/bin/python examples/11_kill9_cli_recover.py    # kill -9 a run, take over from another process, verify 7 invariants
+.venv/bin/python -m pytest -q                        # runs inside an OS sandbox, in two stages
+```
+
+MIT License